0xDocs 0x.limo

Docs / JavaScript SDK

Starter packs and .x1patch updates

Partly live

Let players keep a game's boot data in one file on their disk (a starter pack), read by the swarm runtime with every piece hash-checked, and update it with a .x1patch that carries only the changed pieces.

A starter pack is one file that holds the byte spans a game reads while it boots and plays, as whole pieces of the site's files. The player picks the pack once, or the page downloads it. From then on, the swarm runtime answers every read the pack covers from the player's disk, before it asks the swarm or the origin. Anything the pack doesn't cover loads as before.

A .x1patch updates a stored pack to a newer generation. It carries only the pieces that changed, so an update costs only what changed.

Starter packs are built for mounts: a big data tree whose reads are ranges of 1 MiB pieces. They also answer whole files of the swarm manifest.

Runtime 0.2.x, self-hosted sites, no SDK builder yet

  • This needs the site runtime from @0xlimo/swarm-sw 0.1.8 (runtime 0.2.6). 0x hosting installs runtime 0.1.4, so it isn't available on hosted sites.
  • 0x publish doesn't copy x1/starter.js into the site, and the package doesn't export it. Copy node_modules/@0xlimo/swarm-sw/src/starter.js to <site>/x1/starter.js yourself. Without that file, boot.js runs without a pack.
  • The SDK has no tool that builds starter packs or .x1patch files yet. The formats are described below.
  • The runtime looks pack entries up by the path the page asks for, with a leading /data/ removed. It is built for a site at the root of its origin, with its mount at /data/.

#How a page uses a pack

x1/boot.js opens the pack before it starts the swarm host, and passes it to startSwarmHost({localPack}):

  1. ?starter=<url> in the page URL opens a pack at that URL by range requests (a local share, or a launcher's localhost endpoint). It is never stored. The server must send Content-Length on HEAD and answer Range requests with 206.
  2. Otherwise, the pack the player stored earlier is opened from IndexedDB (database x1-starter).
  3. A pack stored as a file handle by an older runtime may need a read grant. Then boot sets window.x1swarm.starterPending = {name, grant} instead. Call grant() from a click handler (it needs a user gesture), and reload. The grant also stores the file itself, so it is asked only once.

When a pack is open, window.x1swarm.starter is {name, bytes, files}, and x1swarm.stats() includes it.

The swarm host then answers:

  • mount pieces the pack covers, from disk, before the tracker is consulted. With a pack open, the worker asks the page for every piece of a mounted file and never streams a read past it.
  • whole manifest files the pack holds completely, before the swarm.
  • mounted files the shards don't list (excluded or too small, such as an engine's own index files), whole, before the origin.

A piece that fails its hash, or a span the pack doesn't cover, falls through to the swarm and the origin.

#What is checked

ReadCheck
Every piece read from the packSHA-1 against the pack's own index (ph), on every read
Mount pieces and whole manifest filesthen SHA-256 against the site's shards or manifest, in the worker, before the game gets them
Mounted files the shards don't listonly the pack's own SHA-1s: the site has no hash for them

Verified pieces are kept in memory for re-reads, up to 1 GiB by default. Engines read the same piece often.

#A Play button: data-manual

html
<script type="module" src="./x1/boot.js" data-entry="./main.js" data-manual></script>

With data-manual, boot doesn't import the entry module on its own. It waits until the page calls window.x1start(). Your page can show its own pack card and Play control first, and the click is also the gesture that browsers want for audio. If the page sets window.__wantStart = true before boot gets there, the entry starts at once.

#Storing a pack: x1/starter.js

Import the module from the site (./x1/starter.js) in your page's own code.

js
import { storeStarterHandle, storeStarterRanges, starterDownloadState, clearStarter } from "./x1/starter.js";

// the player picks the file (any browser)
input.onchange = async () => {
  await storeStarterHandle(input.files[0]);
  location.reload(); // boot opens it on the next load
};

// or the page downloads it: 6 ranges at once, each 64 MiB chunk stored as it lands
const ctl = new AbortController();
await storeStarterRanges("game-starter.x1pack", packUrl, packSize, (got) => showProgress(got / packSize), {
  signal: ctl.signal,                 // ctl.abort() pauses; the landed chunks stay
  idle: async () => gameIsLoading(),  // true: the download waits (the game's reads win the link)
});
ExportWhat it does
openStarterPack(blob, {cacheBytes?})Opens a pack from a File, Blob or urlBlob(). Returns {name, bytes, files, built, indexHash, index, covers(rel, a, b), read(rel, a, b), whole(rel)}. read and whole check every piece and throw on a mismatch. cacheBytes defaults to 1 GiB.
openStoredStarter()The stored pack, opened. null without one, or {pending: true, name, grant()} for a handle that needs a grant.
urlBlob(url)A blob-like reader of a pack at a URL, by Range requests.
storeStarterHandle(fileOrHandle)Stores the picked file itself in IndexedDB, so no permission prompt is ever needed. A file over 512 MiB is stored as 64 MiB chunk records, each read into memory first. If a FileSystemFileHandle's file doesn't fit the quota, the handle is stored instead. It also asks for persistent storage.
storeStarterRanges(name, url, size, onProgress?, o?)Downloads a pack by ranges into IndexedDB chunks (see below). A pause keeps the landed chunks, and a resume fetches only the missing ones.
storeStarterStream(name, body, size, onProgress?, resume?, chunkBytes?)Stores a ReadableStream (one plain download) in 64 MiB chunks. On an interruption it keeps the whole chunks and throws … resumable. Pass starterDownloadState() as resume and fetch the rest with a Range from resume.got.
starterDownloadState()A waiting partial download: {name, size, chunks, chunkBytes?, doneChunks?, got}, or null.
clearStarterDownload()Discards a partial download.
clearStarter()Forgets the stored pack. The next load streams as before.
applyPatch(pack, patchBlob)Applies a .x1patch to an opened pack and returns the new pack as a Blob (see below).

storeStarterRanges options:

OptionDefaultMeaning
chunkBytes64 MiBBytes per range and per stored chunk. Use about 8 MiB with fetchRange, so progress and pause respond quickly.
concurrency6Ranges in flight
signalAn AbortSignal. Aborting pauses the download, and the error is an AbortError.
idleasync () => boolean. While it returns true, the download waits, checking once a second.
fetchRange(a, bInclusive)plain HTTP RangeYour own source of a chunk, such as the swarm's fetchRanges. It returns a Blob or bytes.

Each chunk is tried 3 times, 1 s and then 2 s apart, before the download fails. A failed download stays resumable. A partial download made with a different chunkBytes is discarded, except one made with the old fixed 64 MiB chunks: when the new chunk size divides 64 MiB, it is split into the new chunks and kept.

#Updates: .x1patch

Each pack has a generation: indexHash, the SHA-256 of its index JSON. A patch names the generation it builds on (from). applyPatch refuses any other generation with starter patch: this update builds on a different pack generation — download the full pack instead.

js
import { openStoredStarter, applyPatch, storeStarterHandle } from "./x1/starter.js";

const pack = await openStoredStarter();
const patch = await (await fetch("updates/2026-10-29.x1patch")).blob();
const next = await applyPatch(pack, patch); // nothing is copied yet: slices of the old pack and the patch
await storeStarterHandle(next);

The new pack's bytes are lazy slices of the old pack and the patch, so keep both readable until the new pack is stored. Every piece, patched or kept, is checked again when it is read. A piece that is neither in the patch nor in the old pack (same piece number and SHA-1) fails the apply.

#Formats

Both files end with a 16-byte trailer: an 8-byte magic, then the index length as a little-endian u64. The index JSON sits right before the trailer.

Starter pack (X1PACK01): [stored pieces of each file, ascending][index JSON][trailer]

json
{
  "v": 1,
  "kind": "x1pack-starter",
  "built": "2026-10-29T12:00:00Z",
  "files": {
    "maps/level1.pak": { "size": 734003200, "pieceLen": 1048576, "off": 0, "pieces": [0, 1, 2, 57, 58], "ph": ["<sha1 hex>", "…"] },
    "maps/level1.idx": { "whole": true, "size": 40960, "off": 5242880 }
  }
}
FieldMeaning
keyThe file's path as the page requests it, without a leading / or /data/. Mount pieces are looked up by the lower-case path.
sizeThe file's full size
pieceLenIts piece length: the mount's 1 MiB for mounted files
offWhere the file's stored pieces start in the pack
piecesThe piece numbers stored, ascending. They sit back to back from off, and only the file's last piece may be short.
phThe SHA-1 of each stored piece, in the same order
wholetrue: the whole file is stored at off, with no piece hashes

Patch (X1PATCH1): [piece bytes][index JSON][trailer]

json
{
  "v": 1,
  "kind": "x1pack-patch",
  "from": "<indexHash of the pack it updates>",
  "index": { "v": 1, "kind": "x1pack-starter", "files": { "…": "the new pack's index; off is recomputed" } },
  "patches": { "maps/level1.pak@3": 0, "maps/level1.idx@whole": 1048576 }
}

patches maps <path>@<k> (the k-th stored piece of the new index) or <path>@whole to that piece's byte offset in the patch.