0xDocs 0x.limo

Docs / P2P and the swarm

What you control

The P2P settings a developer has (swarm policy, boot script, x1.json fields, reports), how to opt out, and how versions and caching work.

0x runs the swarm, the tracker, the seeder and the relay. You decide which files are shared, whether your page starts the runtime at all, and a few runtime settings.

#Summary

you wantdo this
The default (share every file of 16 KiB or more)Load ./x1/boot.js from index.html. Ship no swarm-assets.json.
Share only some filesShip a swarm-assets.json policy.
Share nothing, but keep the runtime (transfer reports, ./p2p/ice)swarm-assets.json with {"include": []}.
No runtime at allDon't load ./x1/boot.js. Every file comes from the origin.
Debug without the swarmOpen the page with ?x1=off.
Test as a Private or Off playerOpen the page with ?p2p=relay or ?p2p=0.

#Starting the runtime

The runtime starts only if your page loads it:

html
<script type="module" src="./x1/boot.js" data-entry="./main.js"></script>
  • data-entry is your game's entry module. boot.js imports it after the swarm is up (at most 5 s), so your first asset request already goes through the swarm. Without data-entry, load your code yourself. Files requested before the service worker controls the page come from the origin.
  • data-tracker, data-manifest and data-timeout on the script tag override the x1.json values. You rarely need them on 0x hosting.

The 0x init templates and the starters already contain this line. If you publish a version whose index.html doesn't load ./x1/boot.js, the publish output and the finalize response say so (boot: false).

#x1.json

0x writes x1.json into every version. You can't upload it, because it is a server-owned path. The fields it can contain:

fieldmeaning
trackerThe tracker WebSocket (wss://play.0x.limo/p2p/tracker on 0x.limo).
manifestThe swarm manifest, relative to the version root (swarm/manifest.json).
timeoutMsHow long the worker waits for the swarm before it asks the origin (20000).
apiThe platform API URL, for @0xlimo/platform's siteApi().
swarmfalse on a paid game's site: the runtime starts no swarm.
reportsfalse turns transfer reports off. A URL sends them there instead (the local dev server uses this in tests).
mirrorRuntime 0.2.3+, self-hosted sites: an https:// copy of the swarm's files that the worker asks before the origin. See mirror.
readaheadRuntime 0.2.0+, self-hosted sites: true warms the next 6 MiB after each ranged read of a mounted file. See readahead.

With 0x publish --to <dir> (your own hosting) you control x1.json through the CLI flags (--tracker, --policy), and you can edit the published result. The CLI doesn't write mirror or readahead, so add them after each publish. A self-hosted site can also put a large data tree on the swarm with mounts.

#Transfer reports

Transfer reports are byte counts per file hash: from the swarm, from the origin, and uploaded to others. They feed the traffic numbers you and 0x see. They carry no addresses and no peer identities. They stay off when the player turned sharing off. See the overview.

A site that a priced app's listing points at (universe.web.hosted) is a paid site:

  • Its new versions are built origin-only: no swarm manifest, and x1.json says "swarm": false. Nothing of the game is seeded by 0x or shared between players.
  • Versions published before the game got a price were built with a swarm manifest. Those older versions stay published and seeded. Publish a new version after the price is approved, and point the listing at it.
  • The site front lets only owners load the pages (see the note below for its status on 0x.limo).

You don't need to change anything in your game for this. The same boot.js line simply starts no swarm.

Paid games on 0x.limo

The origin-only build for paid sites is live in the hosting service. The owners-only gate in front of paid sites (@0xlimo/paygate) is coded, but it is not deployed on 0x.limo, and no hosted site is paid today. Until the gate is on, don't rely on hosting to keep a paid game's files private.

#Versions are immutable

A version (/sites/<site>/<n>/) never changes after finalize. To change anything, publish a new version. The service uploads only the files it doesn't already have, by SHA-256, so an unchanged 200 MB asset costs nothing to republish. Because versions are immutable:

  • Files other than pages are served with Cache-Control: public, max-age=31536000, immutable (one year, in browsers and in Cloudflare).
  • Pages (/ and *.html) are served Cache-Control: no-cache. Browsers revalidate them (a 304 with the current headers), so a change to your site's security policy reaches returning players.
  • The swarm can trust a file's hash forever. A new version's unchanged files keep their infohash, so players who have the old version already seed them.

Point your store listing at the new version (resubmit with 0x submit, or on /dev/submit) to move players over. Old versions stay published.

Don't cache-bust with query strings on swarm files

The worker matches requests by path. models/ship.glb?v=2 still maps to the manifest entry /models/ship.glb. Within one version the bytes never change, so the query string isn't needed: publish a new version instead.

#What you can't change

  • The tracker, the ICE servers and the seeder on 0x hosting.
  • The isolation and policy headers your site is served with. You influence the policy through your declaration (see Content-Security-Policy).
  • The paths 0x writes: x1.json, x1-sw.js, x1/ and swarm/.