mjswan web engine

Browser-side runtime for mjswan. Interactive MuJoCo simulations with real-time policy control, running entirely in the browser via WebAssembly.

The package runs MuJoCo physics (mujoco-wasm), renders with three.js, and executes policies with ONNX Runtime Web.

Most users want the Python package. mjswan is primarily authored in Python (pip install mjswan), which bundles your models, policies, and UI into a static site. This npm package is the browser side, and is useful directly in two cases: embedding a published simulation in your own page, and authoring custom MDP terms in TypeScript with full type support. See the documentation for the full Python workflow.

Installation

npm install mjswan

Requires Node.js 20+ and a bundler that handles TypeScript sources (Vite recommended. See Custom MDP terms below for why).

Embedding a simulation (mount)

The package ships a self-contained library build (dist/mjswan.js) that renders a published mjswan simulation into any element. It bundles every dependency and co-locates its WASM, runs single-threaded by default (no COOP/COEP headers needed), and works cross-origin — so it can be loaded straight from a CDN:

const { mount } = await import(
  'https://cdn.jsdelivr.net/npm/[email protected]/dist/mjswan.js'
);

// `source` points at a published simulation's config.json; every other asset
// (scene.mjz, policy.onnx/json, motion.npz, splats) resolves relative to it.
const sim = await mount(container, 'https://cdn.mjswan.com/scenes/<id>/config.json');

Or as a normal bundled import:

import { mount } from 'mjswan';

const sim = await mount(document.getElementById('viewer')!, configUrl);

mount(element, source) resolves, once the first scene is running, to an instance:

interface MjswanInstance {
  // Capture the current frame as a JPEG Blob.
  captureThumbnail(options?: { maxDim?: number; quality?: number }): Promise<Blob>;
  // Tear down the simulation and free resources.
  dispose(): void;
}

source is either a config.json URL (assets resolve against its directory) or an in-memory file resolver { resolve(path): Promise<ArrayBuffer | null> } for rendering locally-selected files without an upload round-trip. Call unmount(element) to dispose a mounted instance by its host element.

Custom MDP terms

When authoring custom observations, commands, events, or terminations for a mjswan simulation, import the base classes and helpers from subpath exports instead of fragile relative paths. Install mjswan as a dev dependency and import directly:

import { ObservationBase } from 'mjswan/observation';
import { mjcToThreeCoordinate } from 'mjswan/coordinate';
import type { PolicyState } from 'mjswan/types';

export class MyObservation extends ObservationBase {
  get size(): number {
    return 3;
  }

  compute(state: PolicyState): Float32Array {
    // ... read MuJoCo state, return the observation vector
  }
}

The build step bundles your source into the engine. See the examples for complete custom terms.

Subpath exports point at TypeScript source (not compiled .d.ts), so consumers need a bundler that handles TypeScript. Vite does; plain tsc does not. This keeps full IDE IntelliSense without a separate types package — see ADR 0001.

Available subpaths

| Import | Provides | |---|---| | mjswan | mount, unmount (the runtime library build) | | mjswan/observation | ObservationBase, ObservationConfig | | mjswan/command | CommandManager, command types and helpers | | mjswan/event | EventBase, event config and context types | | mjswan/termination | TerminationBase, termination config types | | mjswan/scene | Scene helpers (getPosition, getQuaternion, …) | | mjswan/npz | .npz loading (loadNpz, NpzEntry) | | mjswan/coordinate | MuJoCo ↔ three.js coordinate conversions | | mjswan/math | Quaternion / vector math utilities | | mjswan/types | Shared types (PolicyState, PolicyRunner, …) |

Links

• Documentation: mjswan.readthedocs.io
• Repository: github.com/ttktjmt/mjswan
• Python package: pypi.org/project/mjswan
• Live demo: ttktjmt.github.io/mjswan

License

Apache-2.0