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 want | do 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 files | Ship a swarm-assets.json policy. |
Share nothing, but keep the runtime (transfer reports, ./p2p/ice) | swarm-assets.json with {"include": []}. |
| No runtime at all | Don't load ./x1/boot.js. Every file comes from the origin. |
| Debug without the swarm | Open the page with ?x1=off. |
| Test as a Private or Off player | Open the page with ?p2p=relay or ?p2p=0. |
#Starting the runtime
The runtime starts only if your page loads it:
<script type="module" src="./x1/boot.js" data-entry="./main.js"></script>data-entryis your game's entry module.boot.jsimports it after the swarm is up (at most 5 s), so your first asset request already goes through the swarm. Withoutdata-entry, load your code yourself. Files requested before the service worker controls the page come from the origin.data-tracker,data-manifestanddata-timeouton the script tag override thex1.jsonvalues. 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:
| field | meaning |
|---|---|
tracker | The tracker WebSocket (wss://play.0x.limo/p2p/tracker on 0x.limo). |
manifest | The swarm manifest, relative to the version root (swarm/manifest.json). |
timeoutMs | How long the worker waits for the swarm before it asks the origin (20000). |
api | The platform API URL, for @0xlimo/platform's siteApi(). |
swarm | false on a paid game's site: the runtime starts no swarm. |
reports | false turns transfer reports off. A URL sends them there instead (the local dev server uses this in tests). |
mirror | Runtime 0.2.3+, self-hosted sites: an https:// copy of the swarm's files that the worker asks before the origin. See mirror. |
readahead | Runtime 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.
#Paid games
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.jsonsays"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 servedCache-Control: no-cache. Browsers revalidate them (a304with 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/andswarm/.
