5.0 KiB
MotrixSim Universal Three.js Manifest
This project uses a small scene manifest as the boundary between MotrixSim/MJCF assets and the browser renderer.
The manifest does not try to duplicate every engine feature. It carries enough data for a browser to load visible assets, create stable Three.js nodes, and bind runtime state by body name.
Minimal Shape
{
"version": "0.1",
"name": "demo",
"coordinateSystem": { "up": "Z", "handedness": "right" },
"materials": [
{ "id": "ball", "color": "#4f8cff" },
{ "id": "checker_floor", "textureKind": "checker", "textureColors": ["#334155", "#e2e8f0"], "textureRepeat": [4, 4] },
{ "id": "label", "color": "#ffffff", "textureUrl": "/assets/label.png", "textureRepeat": [1, 1] }
],
"objects": [
{
"id": "ball_visual",
"body": "_unnamed_link_0",
"physics": "dynamic",
"editableGroup": "shelf-1",
"editableGroupRole": "member",
"geometry": { "kind": "primitive", "primitive": "sphere", "radius": 0.5 },
"material": "ball"
},
{
"id": "inline_convex",
"geometry": { "kind": "convexMesh", "vertices": [0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1] },
"material": "checker_floor"
}
],
"state": { "mode": "poll", "url": "/state", "controlUrl": "/control", "pollIntervalMs": 50 },
"controls": {
"joints": [
{ "name": "joint1", "index": 0, "range": [-2.8973, 2.8973] }
],
"actuators": []
}
}
Supported Visuals
- Primitives:
box,sphere,capsule,cylinder,plane,axes. - Meshes:
gltf,glb,obj,stl, plus small inline convex meshes. - Materials: solid color, transparent color, file texture, and generated checker texture with repeat.
- State binding:
object.bodymaps a visual node to a runtime body name. - Physics role:
object.physicsmay bedynamic,fixed,stateOnly, orvisualOnly. The browser uses this to decide whether an object can be dragged and how to label physics tiers;fixedbodies can still have backend collision while being protected from pose edits. - Editable grouping:
object.editableGroupgroups multiple real runtime bodies into a product-level entity.editableGroupRole = "anchor"and"member"describe group structure; actual editability is governed byobject.physics. - Runtime body names may be MotrixSim body names or link names. The headless bridge publishes link poses first, then fills non-duplicate body poses.
- MJCF export: the current exporter expands
<include>files, resolves mesh names from eithernameor file stem, resolvesassetdir/meshdir/texturedir, applies nested<default>geom inheritance, skips collision-only geoms, handlesfromto,xyaxes,zaxis, meshscale, file textures, builtin checker textures, and emits an internal asset map for the headless bridge to serve/assets/....
Repeated mesh URLs are cached by the browser renderer and cloned into the scene, so large scenes with hundreds of repeated OBJ assets do not refetch or reparse the same asset for every instance.
Runtime State
For state.mode = "poll", the browser repeatedly fetches state.url and
applies the returned pose data to body-bound objects. A typical response is:
{
"step": 12,
"time": 0.012,
"paused": true,
"running": false,
"link_names": ["link0", "link1", "hand"],
"joint_names": ["joint1", "joint2"],
"bodies": {
"hand": {
"pos": [0.4, 0.0, 0.77],
"quat": [-0.88, -0.36, 0.27, 0.11]
}
},
"joints": {
"joint2": { "pos": 0.6, "vel": 0.0, "range": [-1.7628, 1.7628], "index": 1 }
},
"actuators": {}
}
Control Endpoint
When state.controlUrl is present, the UI can POST JSON commands to the
bridge. The current bridge supports:
{"action": "pause"}/{"action": "resume"}/{"action": "toggle"}{"action": "step"}for one paused physics step{"action": "reset"}for engine reset{"action": "home"}for zeroing exposed joints{"action": "set_joint", "joint": "joint2", "value": 0.6}{"action": "set_joints", "values": {"joint1": 0, "joint2": 0.6}}{"action": "gripper", "value": 0.04}for known finger joints{"action": "set_body_pose", "body": "box_0", "pos": [0.6, 0, 0.2], "quat": [0, 0, 0, 1]}for paused edits of dynamic bodies{"action": "set_body_poses", "poses": [...]}for paused batched dynamic body edits. Fixed bodies return an explicit error instead of being silently moved.
The bridge returns the same frame shape as /state, so the frontend can update
the renderer and the control panel from one response.
Coordinate Policy
MotrixSim/MJCF scenes are assumed to be Z-up. Three.js is Y-up. The renderer
converts positions, rotations, primitive dimensions, and loaded mesh local
coordinate bases when coordinateSystem.up is Z.
Security Boundary
If the browser renders the real mesh, that mesh is downloaded to the browser. Private assets that must not leave the server should use a server-side video or image stream instead of Three.js mesh delivery.