mujoco-wasm-forge documentation

mujoco-wasm-forge is a reproducible MuJoCo→WebAssembly toolchain that keeps the exported ABI as an explicit, auditable contract. It builds a specific upstream MuJoCo ref into dist/<ver>/mujoco.js + dist/<ver>/mujoco.wasm, plus ABI artifacts under dist/<ver>/abi/.

Jump to

• Quickstart: quickstart

• How-to: howto_build_version

• ABI contract: reference_abi_contract

• Bench: bench

• Simulate-style demo: mujoco-wasm-play (GitHub)

30-second summary

• If you just want artifacts: use a committed dist/<ver>/ or run python forge_cli.py build --version <mjver>.

• Exports are explicitly defined by dist/<ver>/abi/exports.lst and enforced at link time.

• --with-checks runs smoke + quality gates (check/tests/*.mjs) against the produced dist.

• Maintainers can use the ABI artifacts to audit diffs when upgrading MuJoCo.

• Bench: a reproducible suite that validates forge’s flexibility/variant model against performance and Simulate TTFS (bench).

Mini glossary

Term	Plain meaning
dist/<ver>	A build output directory for one MuJoCo version/ref.
exports.lst	The single source of truth for exported C symbols (fed to Emscripten -sEXPORTED_FUNCTIONS=@...).
wrapper	mjwf_* functions that form the supported C API surface for JS/Node/WebWorker.
introspect	Header/AST-based extraction of functions/structs/enums from mujoco.h.
gate	A check that fails (or warns) when ABI/exports/quality constraints are violated.

Where to start

• New users: read quickstart, then howto_build_version.

• Integrators: howto_web_worker and howto_node.

• Maintainers: user_guide_pipeline, reference_abi_contract, and reference_checks_gates.

Quickstart

• Quickstart
  • Prerequisites
  • Build (single command)
  • Find the outputs
  • Next

User Guide

• Overview
  • What is mujoco-wasm-forge?
  • What it guarantees (and what it doesn’t)
  • Key terms
• Bench: validating forge’s flexibility without performance regression
  • What we measure (organized by user needs)
  • Comparison matrix (what we compare)
  • Summary findings (reference run)
  • Limitations (what this bench may still miss)
  • Reproducing the bench
• Build pipeline (end-to-end)
  • Fast paths for iteration (avoid full rebuilds)
• Artifacts and guarantees
  • Primary artifacts (what most users need)
  • ABI & audit artifacts (what maintainers and reviewers use)
  • Version selection (important for checks)
• Compatibility model
  • What “compatibility” means here
  • How upgrades are validated

How-to

• How-to: build a specific MuJoCo version/ref
  • Build
  • Outputs
  • Build directory placement (recommended on synced filesystems)
  • Clean rebuild
• How-to: build with checks
  • Run build + checks in one command
  • Run checks manually
• How-to: integrate in a Web Worker
  • Minimal module worker example
  • Common pitfalls
• How-to: integrate in Node.js
  • Minimal example (Node ESM)
• How-to: pin and reproduce builds
  • Pin upstream MuJoCo
  • Verify a committed dist against a reproducible build
  • CI helpers
• How-to: audit ABI and investigate diffs
  • Key files
  • Typical questions
  • Common causes

Reference

• CLI reference (forge_cli.py)
  • build
  • collect-versions
  • verify-dist
  • Exit status
• Environment variables & build knobs
  • Version selection
  • Toolchain
  • Upstream checkout hygiene
  • Build tree placement
  • Export list override
  • Dist variant selection
  • CMake profile
  • pthreads (WebAssembly threads)
  • Quality gates (check/tests/gates.mjs)
• Dist layout reference
  • Directory layout (typical)
  • Key ABI files
• ABI contract (exports & wrappers)
  • The contract
  • A ∩ B = C (flat exports)
  • JS/Runtime surface
• Checks & gates
  • Post-build validation
  • Runtime checks (--with-checks)
  • Tuning
• Supported MuJoCo versions (committed dist/)
  • Versions currently present in dist/
  • Release tags (convention)
• Glossary

Developer

• Contributing
  • Scope and expectations
  • Local workflow (typical)
  • What not to commit
• Repo tour
  • High-level layout
  • External sources
• Add a new MuJoCo version
  • Steps
  • Tips
• Modify introspection / wrapper generation
  • Touch points
  • Recommended workflow
• CI & release
  • CI overview
  • Tag convention
  • Release assets
  • Local reproduction of the CI verify step