Contents8 sections
Fully articulated models without building the motion from scratch
Lighter models cost less to run in your engine, and every moving part still moves the way it was built.
meshfx reads a GLB built as a tree of named parts, with one authored empty pivot node above each moving part. Each pivot's extras.s3d_joint holds the joint name, type, axis and limits, and meshfx keeps those parts, pivots and joint limits intact across every level.
Submit an articulated GLB with a .meshfx.toml spec to compile reduced levels of detail for each rigid part while keeping every pivot frame and joint extra.
Prepare the input GLB
Author a tree hierarchy in the GLB where each empty pivot node above a moving part carries one s3d_joint object in its node extras.
{
"name": "door_pivot",
"extras": {
"s3d_joint": {
"name": "door_hinge", "type": "revolute",
"axis": [0, -1, 0], "value": 0,
"lower": 0, "upper": 2.4958
}
}
}| Key | Meaning |
|---|---|
name | Required unique joint name in the file. |
type | Required joint type, one of revolute, continuous, prismatic or floating. |
value | Saved joint value already baked into the pivot transform. |
axis | Pivot-local axis vector [x, y, z] in glTF Y-up coordinates. Required for every type except floating. |
lower | Optional lower limit in the joint's unit. |
upper | Optional upper limit in the joint's unit. |
mimic | Optional {"joint": "...", "multiplier": 1} object that scales another joint's value by multiplier. |
| Type | Motion | Unit |
|---|---|---|
revolute | Rotates around the axis between lower and upper limits | radians |
continuous | Rotates freely around the axis with no limits | radians |
prismatic | Translates along the axis between lower and upper limits | metres |
floating | Preserves the saved transform, sign and scale. | none |
A missing axis, unknown type, duplicate name, inverted limits or missing mimic leader in GLB node extras stops the run with MODEL_INVALID and names the node.
Compile the articulated appliance
Place the washer GLB beside the washer spec. Set source.hierarchy = "tree" to preserve its parts. Each mesh-bearing node receives its own repair and triangle allocation, even where two parts touch at rest.
The bake writes GLB levels and a layout.json joint table sorted by name. Inspect metrics.joints in the report for triangle counts by part and level. Both a full bake and a preview write preview_joints.png.
How the preview articulates each joint
For the articulated preview, a one-way joint moves to its upper limit (143 degrees for the washer door, 0.2 m for its drawer). A two-way joint moves to half its positive limit. A continuous joint turns 45 degrees, an unbounded slide moves 0.1 m, a mimic joint follows its leader and a floating joint stays at its saved transform.
Drive the joints in Godot
Instance the generated scene. Its articulated.gd controller exposes the joint table with get_joints(). Call set_joint("door_hinge", 1.0) to set the hinge angle in radians. Slides take metres. Each limited joint clamps its target before passing the value to a mimic follower.
Pose a part in three.js
Load the compiled GLB with GLTFLoader. Each pivot already includes its saved value, so apply only the difference along its local axis. The joint extras land on pivot.userData.s3d_joint. The spec has no key for pose values; your engine sets the targets.
// Capture once per scalar pivot, before posing any parts.
pivot.updateWorldMatrix(true, false);
const joint = pivot.userData.s3d_joint;
const rest = pivot.matrix.clone();
const axis = new THREE.Vector3().fromArray(joint.axis).normalize();
const basis = new THREE.Matrix3().setFromMatrix4(pivot.matrixWorld);
const metresPerUnit = axis.clone().applyMatrix3(basis).length();
pivot.matrixAutoUpdate = false;
function pose(target) {
const delta = target - joint.value;
const motion = new THREE.Matrix4();
if (joint.type === 'prismatic') {
motion.makeTranslation(axis.clone().multiplyScalar(delta / metresPerUnit));
} else {
motion.makeRotationAxis(axis, delta);
}
pivot.matrix.multiplyMatrices(rest, motion);
pivot.matrixWorldNeedsUpdate = true;
}Use a target within the joint's limits. For a mimic follower, resolve the leader's target first. A parent's motion carries down the part tree. Try the washer and lamp.
Keep rigid parts intact
Use tree hierarchy and leave remeshing, thickening and retopology off. A triangle target below the rigid-part floor produces JOINT_PART_FLOOR. The warning names the setting to adjust.
The washing machine and floor lamp models and the s3d_joint layout come from sand3d by Sandflow, under the Apache License 2.0. See the notice.
Questions
What happens if a joint in extras.s3d_joint has a missing axis or duplicate name?
meshfx stops the run with MODEL_INVALID and names the node so you can fix the invalid joint configuration.
How do you drive articulated joints in Godot after compiling?
Instance the generated scene and call set_joint on the articulated.gd controller using radians for hinges and metres for slides.