0xDocs 0x.limo

Docs / P2P and the swarm

P2P delivery overview

How 0x serves a hosted game's files from the player swarm, with your site's origin as the web seed and the fallback.

Players who load a game hosted on 0x also share its files with each other. The first visitor of the day gets the files from 0x's always-on seeder or from the site's origin. Every visitor after that can get them from other players' browsers over WebRTC. This happens without any code in your game: your loaders (fetch, GLTFLoader, TextureLoader, <audio>, WebAssembly streaming and so on) request the same URLs as before.

What is live

Swarm delivery is on for every hosted site on 0x.limo (https://<site>-play.0x.limo/sites/<site>/<n>/) whose index.html loads ./x1/boot.js. Paid games are the exception: their sites are built origin-only, so nothing of them is seeded or shared. See What you control.

#The pieces

piecewhere it runswhat it does
x1/boot.jsyour pageRegisters the service worker, starts the swarm host, then imports your entry module.
x1-sw.js (service worker)the browserIntercepts GET requests for files listed in the swarm manifest and answers them with verified bytes.
x1/host.js + x1/meshtorrent.mjsyour pageThe WebTorrent client: talks to the tracker and opens WebRTC data channels to other players.
swarm/manifest.jsonyour siteThe files that go on the swarm, by path, each with its SHA-256 and torrent infohash.
trackerwss://play.0x.limo/p2p/trackerIntroduces players who are loading the same site to each other.
0x seeder0x serversSeeds every published version, so a file has at least one peer.
your site's origin<site>-play.0x.limoThe web seed and the fallback: any file the swarm can't deliver comes from here.

0x writes all of these into each version when you publish (0x publish or the upload page at https://api.0x.limo/hosting/). You never upload x1/, x1-sw.js, x1.json or swarm/ yourself: the service refuses those paths.

#What happens on a page load

  1. The page loads x1/boot.js. It reads x1.json, registers x1-sw.js with your site's version directory as its scope, and waits for the worker to control the page (on a first visit the worker claims it when it activates).
  2. x1/host.js checks the tracker's /p2p/health, asks /p2p/ice for STUN and TURN servers, loads swarm/manifest.json, and asks /p2p/seeds how many seeders each file has.
  3. boot.js imports your entry module (data-entry). Your game starts loading files.
  4. For each GET the worker looks up the path in the manifest:
    • Not listed (pages, small files, the runtime itself): the request goes to the origin unchanged.
    • Listed: the worker asks the page's swarm client for the file. When the bytes arrive, the worker checks their length and SHA-256 against the manifest and answers the request (with Range honoured, so media elements work).
    • No peer, too slow, bad bytes, or any error: the worker fetches the request from the origin exactly as the browser would have. It then hands the whole file to the page, which keeps it and seeds it to the next player.
  5. Everything the page received stays in a persistent cache (up to 512 MiB, where the browser allows one) and is seeded while the tab is open.

The whole boot is bounded: if the service worker and swarm host are not ready within 5 seconds, or anything fails, boot.js logs 0x swarm: ... - files load from the origin and imports your entry anyway. A browser without service workers loads everything from the origin.

Your game never sees the difference

A response served from the swarm carries the same COOP, COEP and CORP headers as the origin's, and the header X-X1-Source: swarm. Files in the manifest are immutable per version, so a swarm answer is always byte-identical to what the origin would send.

#Integrity

Every file in the manifest is identified by the SHA-256 of its bytes (tileId). The worker checks every file it gets from the swarm against that hash before your game sees it, and drops it if the size or hash is wrong. Peers can delay a file, but they can't change it. The manifest itself always comes from your origin (it is never served by peers) and is revalidated at most once a minute.

#Privacy: what players share

The launcher passes the player's sharing setting to your page:

settingURL parametereffect
On (default)noneDirect WebRTC connections to other players.
Private?p2p=relayEvery connection goes through 0x's TURN relay, so other players never see this player's address.
Off?p2p=0No peer-to-peer connections at all: every file comes from the origin.

The setting is kept for the tab (sessionStorage), so it survives your game's own navigation. ?x1=off skips the whole runtime, which is handy for debugging.

#Transfer reports

The worker counts, per file hash, the bytes it got from the swarm and from the origin, and the page counts the bytes it uploaded to other players. Only those sums are reported: no addresses and no peers.

  • Inside the 0x launcher, the page sends them to the launcher every 30 seconds and when it is hidden. The launcher reports them unless the player turned sharing off.
  • Opened directly, the page sends them through its worker to its own origin's /x1/xfer every minute and when it is hidden, unless sharing is off.

Set "reports": false in x1.json to turn this off (see What you control).

#Next

  • Swarm assets: which files go on the swarm, the swarm-assets.json policy and the manifest format.
  • Tracker and web seed: the endpoints your page talks to, and CORS.
  • What you control: the settings you have, how to opt out, and how caching works.