# 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 ```json { "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.body` maps a visual node to a runtime body name. - Physics role: `object.physics` may be `dynamic`, `fixed`, `stateOnly`, or `visualOnly`. The browser uses this to decide whether an object can be dragged and how to label physics tiers; `fixed` bodies can still have backend collision while being protected from pose edits. - Editable grouping: `object.editableGroup` groups multiple real runtime bodies into a product-level entity. `editableGroupRole = "anchor"` and `"member"` describe group structure; actual editability is governed by `object.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 `` files, resolves mesh names from either `name` or file stem, resolves `assetdir` / `meshdir` / `texturedir`, applies nested `` geom inheritance, skips collision-only geoms, handles `fromto`, `xyaxes`, `zaxis`, mesh `scale`, 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: ```json { "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.