DOCS // meshfx

Articulation Available

meshfx delivers lighter assets from a spec, and the parts still move the way they were built.

Contents8 sections
  1. Fully articulated models without building the motion from scratch
  2. Prepare the input GLB
  3. Compile the articulated appliance
  4. How the preview articulates each joint
  5. Drive the joints in Godot
  6. Pose a part in three.js
  7. Keep rigid parts intact
  8. Questions

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.

Compare Compiled washer with door and drawer closed and Washer with door open and detergent drawer extended
Compiled washer with door and drawer closedWasher with door open and detergent drawer extended

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.

glTF
{
  "name": "door_pivot",
  "extras": {
    "s3d_joint": {
      "name": "door_hinge", "type": "revolute",
      "axis": [0, -1, 0], "value": 0,
      "lower": 0, "upper": 2.4958
    }
  }
}
KeyMeaning
nameRequired unique joint name in the file.
typeRequired joint type, one of revolute, continuous, prismatic or floating.
valueSaved joint value already baked into the pivot transform.
axisPivot-local axis vector [x, y, z] in glTF Y-up coordinates. Required for every type except floating.
lowerOptional lower limit in the joint's unit.
upperOptional upper limit in the joint's unit.
mimicOptional {"joint": "...", "multiplier": 1} object that scales another joint's value by multiplier.
TypeMotionUnit
revoluteRotates around the axis between lower and upper limitsradians
continuousRotates freely around the axis with no limitsradians
prismaticTranslates along the axis between lower and upper limitsmetres
floatingPreserves 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.

three.js
// 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

How do you author moving parts in an input GLB for meshfx?

Build a tree hierarchy where each empty pivot node above a moving part carries an extras.s3d_joint object with name, type, axis and limits.

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.