Swarm assets
Which of your files go on the player swarm, the swarm-assets.json policy, and the swarm manifest format.
When a version is published, 0x decides which files go on the swarm. It writes them into
swarm/manifest.json together with a .torrent file per file and a content-addressed copy of
each one. Your swarm policy controls that choice.
#The default policy
Without a swarm-assets.json in your upload, this policy applies:
{
"include": ["**"],
"exclude": ["**/*.html", "**/*.htm", "x1/**", "x1-sw.js", "x1.json", "swarm-assets.json",
"node_modules/**", ".x1/**", "server.mjs", "package.json", "package-lock.json", "0x.config.json"]
}It also applies two size bounds:
- files under 16 KiB stay on the origin, because tracker traffic would cost more than it saves;
- files over 256 MiB stay on the origin. On 0x hosting the 64 MiB per-file limit applies first.
In practice the default puts every file of 16 KiB or more on the swarm, whatever its format:
models, textures, audio, WebAssembly, game data, archives and .0xpak packs. Your pages stay
on the origin, and so does the 0x runtime, which has to load before the swarm exists.
#Your own policy: swarm-assets.json
Put a swarm-assets.json at the top of your site (next to index.html). It replaces the
default policy completely, so add any excludes you still want.
{
"include": ["packs/*.0xpak", "media/**", "*.wasm"],
"exclude": ["media/previews/**"],
"minBytes": 1048576,
"maxBytes": 67108864
}| field | type | meaning |
|---|---|---|
include | list of globs (required) | Files that may go on the swarm. |
exclude | list of globs | Files that never go on the swarm, even if include matches. |
minBytes | number | Smaller files stay on the origin (default 16384). |
maxBytes | number | Larger files stay on the origin (default 268435456). |
Globs are matched against paths relative to the site root, with / separators. ** matches
any depth, so **/ also matches zero directories (**/*.png matches a.png and x/y/a.png).
* matches within one name and ? matches one character. A file goes on the swarm when it
matches an include glob, matches no exclude glob, and is within the size bounds.
To keep everything on the origin, use an include list that matches nothing:
{ "include": [] }The policy file is public
swarm-assets.json is published with your site like any other file. Don't put anything in it that you
wouldn't publish.
0x publish --to <dir> (a local or rsync build) reads the policy from your build directory, or
from the file named by --policy. The hosting service keeps the swarm-assets.json you uploaded and
uses the default only when there is none.
#The manifest: swarm/manifest.json
The manifest is canonical JSON (meshtorrent manifest version 1). Its keys are site paths, so the worker can look up a request by its URL:
{
"version": 1,
"entries": {
"/models/ship.glb": {
"tileId": "9f2c…64 hex…",
"infoHash": "3b1d…40 hex…",
"size": 1843200
}
}
}| field | meaning |
|---|---|
| key | The file's path under the site root, with a leading /. |
tileId | SHA-256 of the file's bytes (hex). The swarm worker checks every delivered file against it. |
infoHash | BitTorrent v1 infohash of the deterministic single-file torrent of those bytes, named <tileId><ext>. The same bytes always give the same infohash, so identical files are one swarm across versions and sites. |
size | File size in bytes. |
sg | Optional: the 0x content info native clients use (piece_len and the SHA-256 of each 256 KiB piece). |
Next to it, the builder writes:
swarm/t/<infoHash>.torrent: torrent metadata, so a peer can start a swarm that has no peers yet;swarm/content/<id>andswarm/content/<id>.info: the content-addressed copy used as a web seed by native clients.
Pieces are 256 KiB, the same as 0x's native content delivery, so the same bytes line up in both.
The builder verifies the manifest after writing it: every entry must exist, have its size and hash
to its tileId. A version whose manifest fails this check is not published.
#Large files
- Hosted sites: at most 64 MiB per file, 5000 files and 2048 MiB in total per developer
(
GET /v1/hosting/configreturns the current values). Split bigger content: several 0xpak packs, or chunks your loader fetches by name. - Each swarm file is one torrent. The worker fetches a listed file whole, verifies it, then serves any
Rangeof it from memory (the last 64 MiB of whole files are kept), so a media element's many range requests cost one swarm fetch. - Native builds (
sg-content publish) have their own large-file support: big files are published and installed in parts. That is part of the native runtime, not of hosted sites.
#Checking what went on the swarm
0x publish prints the count, for example 0x publish: 41 files (183.2 MiB) in the swarm. It also
prints a note when index.html does not load ./x1/boot.js, because then players get every file from
the origin. The finalize response of the hosting API carries the same numbers in
swarm: {files, bytes} and boot: true|false.
Read the live manifest of any version:
curl -s https://<site>-play.0x.limo/sites/<site>/<n>/swarm/manifest.json | head -c 600In the page, await window.x1swarm.stats() returns the worker's counters (swarm, cache, origin,
peerBytes, originBytes, rejected, manifestEntries, ...) and the swarm host's.
