Skip to content
Embabel Worlds

Build on load

A realm that ships wasm/handlers.js is compiled to dist/handlers.wasm by the host when the realm loads:

  • A content fingerprint over the handler source, manifest, and host build-toolchain identity decides whether to rebuild — a change to any member rebuilds, timestamp games don’t.
  • The build writes a candidate and atomically replaces the published bundle only on success. A failed build — bad JavaScript, a hung compiler, a missing toolchain — leaves the previous good bundle (or no bundle) in place and the realm’s declarative content loaded, with a warning.
  • The host publishes the bundle and manifest atomically as one artifact set. A failed rebuild keeps the previous complete set; a new manifest can never pair with a stale bundle.
  • Bundles are build output. Don’t commit them from a wasm/handlers.js realm — the host rebuilds on load. A src/ project is different: the host does not build src/ on load, so the project ships its built dist/handlers.wasm (and generated manifest), and that bundle is the truth if it disagrees with the source.

A realm may instead ship a prebuilt dist/handlers.wasm and no source — a self-contained realm. The host loads the bundle as-is. This is the right shape when the module is compiled from a language the host has no toolchain for.