@x1/meshtorrent
The 0x swarm toolkit (WebTorrent based) with the asset manifest builder, browser client, tile cache, tracker and seeder that hosted sites and the 0x CLI use.
meshtorrent is how 0x moves static files between players. It uses WebTorrent over WebRTC in
browsers, deterministic torrents (the same bytes always give the same infohash), SHA-256
content ids, and the origin as a last-resort web seed. Hosted sites and 0x dev use it
through @0xlimo/swarm-sw, so most games never import it directly. Use it
directly to:
- build or check a site's swarm manifest yourself (
asset-manifest.mjs); - fetch listed files from the swarm in your own loader (the browser client);
- keep a persistent, verified cache of fetched files (
openTileCache).
Registry version: 0.2.0 (Node.js 20+). It depends on webtorrent, bittorrent-tracker,
create-torrent, parse-torrent, node-datachannel and webrtc-polyfill.
npm install @x1/meshtorrent --@x1:registry=https://0x.limo/npm/Deep imports only
The package's package.json has no main, exports or bin field. Import modules by path
(@x1/meshtorrent/dist/src/asset-manifest.js), and run the tools with
node node_modules/@x1/meshtorrent/bin/<tool>.mjs. The browser bundle is
@x1/meshtorrent/dist-browser/meshtorrent.mjs (ES module) or …/meshtorrent.js
(an IIFE that sets window.MeshTorrent).
#Build and verify a swarm manifest
# what 0x publish does: the files your policy lists -> <site>/swarm/
node node_modules/@x1/meshtorrent/bin/asset-manifest.mjs --root dist --policy swarm-assets.json --verify
# check a published copy without writing anything
node node_modules/@x1/meshtorrent/bin/asset-manifest.mjs --root dist --verify-onlyThe output goes under <root>/swarm/:
| Path | What |
|---|---|
manifest.json | {version: 1, entries: {"/<site path>": {tileId, infoHash, size}}}, canonical JSON |
t/<infoHash>.torrent | metadata bootstrap, so a swarm with no peers can start from the web seed |
content/<id>, content/<id>.info | the content-addressed store that native 0x clients use as a web seed |
Files are rewritten only when their bytes change. Torrents and copies of files that left the
policy are removed. Without a policy nothing is taken (0x publish supplies its default; see
what goes into the swarm).
import { parsePolicy, writeAssetManifest, verifyAssetManifest } from "@x1/meshtorrent/dist/src/asset-manifest.js";
const policy = parsePolicy(JSON.stringify({ include: ["assets/**"], minBytes: 16384 }));
const r = await writeAssetManifest("dist", policy); // {files, bytes, skippedSmall, skippedLarge, ...}
const v = await verifyAssetManifest("dist"); // {entries, ok, mismatched, missing, bad}import { initClient } from "./x1/meshtorrent.mjs";
const client = initClient({ trackerUrls: [trackerUrl], originBase: location.origin + "/" });
const manifest = await fetch("./swarm/manifest.json").then((r) => r.json());
const entry = manifest.entries["/models/ship.glb"];
const { bytes, source } = await client.fetchEntry(entry, "./models/ship.glb", `./swarm/t/${entry.infoHash}.torrent`);
// source: "cache" | "swarm" | "webseed" | "origin"; bytes are verified against entry.tileId#Guarantees
- Integrity: everything fetched is hashed.
sha256(bytes)must equal the entry'stileId, or the bytes are discarded and never seeded. Cache reads are re-hashed too. - Peers first: the web seed joins late (
webseedDelayMs). A file that nobody seeds, per the tracker's/seeds, goes straight to a plain fetch. - Circuit breaker: after 3 swarm failures in a row, the client uses HTTP for 60 s
(
breakerFailures,breakerCooldownMs). - Fallback: without
RTCPeerConnection, the client is origin-only.
The full option and type list is in the reference.
