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
| piece | where it runs | what it does |
|---|---|---|
x1/boot.js | your page | Registers the service worker, starts the swarm host, then imports your entry module. |
x1-sw.js (service worker) | the browser | Intercepts GET requests for files listed in the swarm manifest and answers them with verified bytes. |
x1/host.js + x1/meshtorrent.mjs | your page | The WebTorrent client: talks to the tracker and opens WebRTC data channels to other players. |
swarm/manifest.json | your site | The files that go on the swarm, by path, each with its SHA-256 and torrent infohash. |
| tracker | wss://play.0x.limo/p2p/tracker | Introduces players who are loading the same site to each other. |
| 0x seeder | 0x servers | Seeds every published version, so a file has at least one peer. |
| your site's origin | <site>-play.0x.limo | The 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
- The page loads
x1/boot.js. It readsx1.json, registersx1-sw.jswith 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). x1/host.jschecks the tracker's/p2p/health, asks/p2p/icefor STUN and TURN servers, loadsswarm/manifest.json, and asks/p2p/seedshow many seeders each file has.boot.jsimports your entry module (data-entry). Your game starts loading files.- For each
GETthe 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
Rangehonoured, 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.
- 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:
| setting | URL parameter | effect |
|---|---|---|
| On (default) | none | Direct WebRTC connections to other players. |
| Private | ?p2p=relay | Every connection goes through 0x's TURN relay, so other players never see this player's address. |
| Off | ?p2p=0 | No 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/xferevery 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.jsonpolicy 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.
