Driving Mechanisms

Not every mechanism is driven the same way. Some machines can be animated by simply updating joint transforms. Others require solving a kinematic system, or handing the problem to the physics engine. And some are not rigid-body mechanisms at all, and are better represented with rendering techniques. This page gives the recommended approach for the most common industrial mechanisms.

Choosing the Right Approach

Mechanism	Recommended approach
Industrial robots, articulated arms, gantries	Update the transform of each joint
Delta robots, four-bar linkages, scissor lifts	Compute the kinematics, or let the physics engine solve them
Conveyors and belts	Move the carried bodies with physics, scroll the belt surface's texture
Gear trains and transmissions	Rotate each gear from the driving gear ratio
Tanks, silos and hoppers	Scale the visible level from the measured value
Pipes and process flow	Animate the material, not the geometry
Discrete items on a line	Spawn one entity per item

Serial Kinematic Chains

The easy case, and the one most industrial machines fall into. Each part is carried by the previous one, exactly like the real mechanism:

In the scene graph that is simply a nesting:

Base
└── Arm 1
    └── Arm 2
        └── End-Effector

Each entity's transform is relative to its parent, so motion propagates for free:

• Move or rotate the Base and everything below it follows.
• Rotate Arm 1 and Arm 2 and the End-Effector follow.
• Rotate Arm 2 and only the End-Effector follows.

Nothing computes this — it falls out of the hierarchy. Which means driving a six-axis robot from live data is six component writes and no mathematics at all.

Updating the mechanism is simply a matter of updating the transform of each joint. A controller publishing all its joint angles in one message is the norm, and it maps directly onto the array form of updates:

const robotMapping: EventMapping = {
    channel: "plant/robot-01/state",

    // Entities named after the axes the controller reports.
    entities: { byName: "axis-{id}" },

    // One event, six entities.
    updates: event => {
        const { joints } = event.payload as { joints: Array<number> };
        return joints.map((angle, index) => ({
            id: String(index + 1),
            update: { local_transform: { eulerOrientation: [0, radiansToDegrees(angle), 0] } },
        }));
    },
};

That is the whole integration. See mapping events to entities for the general shape.

Rotation axes

Each joint rotates about one axis of its own local frame. If the pivots were aligned to the real rotation axes at export time — as preparing a scene recommends — that axis is the same for every joint and the mapping stays this simple. If they were not, every joint needs its own correction, which is the usual reason this code gets ugly.

Parallel and Closed-Loop Mechanisms

Some mechanisms cannot be represented by a parent-child hierarchy, because several links influence the same component at once. Typical examples include delta robots, four-bar linkages, scissor lifts and Stewart platforms.

The hierarchy cannot express this: the end-effector has four parents, and each forearm depends on the position of all the upper arms at once, so there is no propagation order to follow. And your data source will typically give you only the actuated values — the three upper-arm angles — leaving everything else to be derived.

There are two recommended approaches, and they are mutually exclusive per part.

Compute the Kinematics

If the forward kinematics are known, compute the dependent transforms from the actuated joints and update every moving part directly. The agent's updates function is the natural home for it: it receives the event, and it can return as many entity updates as the mechanism has moving parts.

const deltaMapping: EventMapping = {
    channel: "plant/delta-01/state",
    entities: { byName: "{id}" },

    updates: event => {
        const { theta1, theta2, theta3 } = event.payload as Record<string, number>;

        // Your forward-kinematics solver: actuated angles in, every dependent
        // transform out.
        const pose = solveDeltaForwardKinematics(theta1, theta2, theta3);

        return [
            { id: "upper-arm-1", update: { local_transform: { eulerOrientation: [0, 0, theta1] } } },
            { id: "upper-arm-2", update: { local_transform: { eulerOrientation: [0, 0, theta2] } } },
            { id: "upper-arm-3", update: { local_transform: { eulerOrientation: [0, 0, theta3] } } },
            { id: "forearm-1", update: { local_transform: pose.forearms[0] } },
            { id: "forearm-2", update: { local_transform: pose.forearms[1] } },
            { id: "forearm-3", update: { local_transform: pose.forearms[2] } },
            { id: "platform", update: { local_transform: pose.platform } },
        ];
    },
};

When to choose it: the solver is known — most parallel machines have a closed-form solution published — and you want the scene to be a faithful mirror of the real machine rather than a plausible one. This produces the most accurate representation.

Watch the write amplification

One incoming event now produces seven or more component writes instead of one. The flush rate has to keep up: the client sends dirty entities on a fixed timer, 30 times a second by default and capped at 125. Size it against the rate of the fastest-moving part, and remember that redundant writes are already deduplicated for you.

Use the Physics Engine

When analytical kinematics are difficult or unnecessary, build the mechanism out of physics constraints and drive only the actuated joints. The physics solver computes the remaining motion.

Each link is connected by a

Joint

Entity Component

Joint joint

Base joint connecting two bodies. By default locks relative position and orientation between constrainer and constrainee.

Schema

breakForce

Float(N)

Default:10000000000000000

Break force threshold (Newtons).

Break force threshold (Newtons).

breakTorque

Float(N·m)

Default:10000000000000000

Break torque threshold (N·m).

Break torque threshold (N·m).

constrainee

Entity Reference

Entity with a Rigid Body to be constrained.

Entity with a Rigid Body to be constrained.

constrainer

Entity Reference

Entity acting as constrainer (rigid/static) or null to constrain to world origin.

Entity acting as constrainer (rigid/static) or null to constrain to world origin.

enableCollision

Boolean

Default:false

Enable collision between constrainer and constrainee bodies.

Enable collision between constrainer and constrainee bodies.

View in component reference

, with a

Constraint

Entity Component

Constraint constraint

6-DoF constraint built on a Joint. Defaults to fixed; selectively unlock translation and rotation on X/Y/Z and configure limits and springs.

Schema

motionLimitSpringDamping

Vector3(N·s/m)

Default:[0,0,0]

Linear limit spring damping per axis (N·s/m).

Linear limit spring damping per axis (N·s/m).

motionLimitSpringStiffness

Vector3(N/m)

Default:[0,0,0]

Linear limit spring stiffness per axis (N/m). >0 makes the limit soft (spring-like).

Linear limit spring stiffness per axis (N/m). >0 makes the limit soft (spring-like).

motionLowerLimit

Vector3(m)

Default:[0,0,0]

Lower linear limit per axis (meters).

Lower linear limit per axis (meters).

motionUpperLimit

Vector3(m)

Default:[0,0,0]

Upper linear limit per axis (meters).

Upper linear limit per axis (meters).

swingLimitAngle

Vector2(deg)

Default:[0,0]

Swing cone half-angles about Y and Z of the constraint frame (degrees). 0 does not restrict rotation; max 180. Used if either swing axis is limited.

Swing cone half-angles about Y and Z of the constraint frame (degrees). 0 does not restrict rotation; max 180. Used if either swing axis is limited.

swingSpringDamping

Float(N·m·s/rad)

Default:0

Swing limit spring damping (N·m·s/rad).

Swing limit spring damping (N·m·s/rad).

swingSpringStiffness

Float(N·m/rad)

Default:0

Swing limit spring stiffness (N·m/rad). >0 makes the limit soft.

Swing limit spring stiffness (N·m/rad). >0 makes the limit soft.

twistLimitAngle

Vector2(deg)

Default:[0,0]

Twist angle limits (min,max) around the twist axis (degrees). Range (−360, 360).

Twist angle limits (min,max) around the twist axis (degrees). Range (−360, 360).

twistSpringDamping

Float(N·m·s/rad)

Default:0

Twist limit spring damping (N·m·s/rad).

Twist limit spring damping (N·m·s/rad).

twistSpringStiffness

Float(N·m/rad)

Default:0

Twist limit spring stiffness (N·m/rad). >0 makes the limit soft.

Twist limit spring stiffness (N·m/rad). >0 makes the limit soft.

unlockedMotion

Unsigned Integer

Default:0

Min:0

Unlock motion along/around the specified axes.

76543210

1

Unlock motion along the X axis.

76543210

2

Unlock motion along the Y axis.

76543210

4

Unlock motion along the Z axis.

76543210

8

Unlock motion around the X axis.

76543210

16

Unlock motion around the Y axis.

76543210

32

Unlock motion around the Z axis.

Unlock motion along/around the specified axes.

View in component reference

on top of it to free the degrees of freedom that should move — 3dverse has no named joint types, so a hinge or a slider is a constraint unlocking one axis. A

Constraint Actuator

Entity Component

Constraint Actuator constraint_actuator

Drives a Constraint toward target position/orientation and velocities using configurable stiffness, damping, and force limits.

Schema

angularDamping

Vector3(N·m·s/rad)

Default:[0,0,0]

Angular drive damping per axis (N·m·s/rad).

Angular drive damping per axis (N·m·s/rad).

angularForceLimit

Vector3(N·m)

Default:[-1,-1,-1]

Max angular drive torque/impulse per axis (N·m). −1 = unlimited.

Max angular drive torque/impulse per axis (N·m). −1 = unlimited.

angularStiffness

Vector3(N·m/rad)

Default:[0,0,0]

Angular drive stiffness per axis (N·m/rad). >0 applies spring torque toward the goal.

Angular drive stiffness per axis (N·m/rad). >0 applies spring torque toward the goal.

angularVelocity

Vector3(rad/s)

Default:[0,0,0]

Target angular velocity (rad/s).

Target angular velocity (rad/s).

goalOrientation

Quaternion

Default:[0,0,0,1]

Target angular orientation.

Target angular orientation.

goalPosition

Vector3(m)

Default:[0,0,0]

Target linear position offset (meters).

Target linear position offset (meters).

linearDamping

Vector3(N·s/m)

Default:[0,0,0]

Linear drive damping per axis (N·s/m).

Linear drive damping per axis (N·s/m).

linearForceLimit

Vector3(N)

Default:[-1,-1,-1]

Max linear drive force/impulse per axis (N). −1 = unlimited.

Max linear drive force/impulse per axis (N). −1 = unlimited.

linearStiffness

Vector3(N/m)

Default:[0,0,0]

Linear drive stiffness per axis (N/m). >0 applies spring force toward the goal.

Linear drive stiffness per axis (N/m). >0 applies spring force toward the goal.

linearVelocity

Vector3(m/s)

Default:[0,0,0]

Target linear velocity (m/s).

Target linear velocity (m/s).

type

Integer

Default:1(ACCELERATION)

Drive type: apply as force or as acceleration.

0FORCE1ACCELERATION

Drive type: apply as force or as acceleration.

View in component reference

is the motor: it drives a constraint toward a target position, orientation or velocity. Writing its targets from live data is all the mapping has to do:

updates: event => {
    const { theta1, theta2, theta3 } = event.payload as Record<string, number>;
    return [
        { id: "upper-arm-1", update: { constraint_actuator: { goalOrientation: yawQuaternion(theta1) } } },
        { id: "upper-arm-2", update: { constraint_actuator: { goalOrientation: yawQuaternion(theta2) } } },
        { id: "upper-arm-3", update: { constraint_actuator: { goalOrientation: yawQuaternion(theta3) } } },
    ];
},

See joints for how to build the constraint itself: the unlockedMotion bitfield, limits and springs, breaking forces, and collision behaviour between the constrained bodies.

When to choose it: the mechanism is hard to solve analytically, or approximately right is good enough and you would rather not own a solver. The cost is that the result is a simulation — it converges, it can overshoot, and it will not match the real machine to the millimeter.

The two approaches do not mix on the same part

A body you move by writing its transform directly should be a kinematic rigid body (rigid_body.isKinematic), and a kinematic body is by definition unaffected by forces — so the solver cannot also drive it. Decide per part: either you write its transform, or the physics engine does. Note too that a joint has no anchor or axis attributes of its own — the constraint frame comes from the entities' own transforms, so pivot placement matters here just as much as it does for a serial chain.

Mechanisms That Are Not Rigid Chains

Rigid bodies connected by joints do not cover everything a plant contains. The rest is approximated — and knowing exactly what is being approximated is what keeps the twin honest.

Conveyors

Moving what sits on the belt is a first-class physics feature. Make the belt a static body, set modifyContact and contactVelocity on its physics_material component, and every rigid body touching it is given that relative velocity — see contact velocity, which has a video walkthrough.

Making the belt surface look like it is moving is a rendering problem, solved by scrolling its texture — below.

Belts, Chains and Gear Trains

Modelling every link of a roller chain and simulating it is not viable, and it is not what anyone does. The standard approach is a static mesh with a scrolling texture. The PBR shader exposes a UV offset as a material parameter:

finalUV = originalUV * scale + offset

offset is documented in UVs and reachable per entity through the dataJSON of the material component.

There is no built-in UV animation

offset is a static tiling and positioning parameter. Nothing scrolls it for you — you advance it, which is exactly the kind of work an ingestion mapping already does. Integrate the reported belt speed into an offset the same way the MQTT sample agent integrates a motor's rpm into a shaft angle: the source gives you a rate, and you accumulate it over the time between two samples.

Meshing gears are the same idea with a different target — write local_transform.orientation per gear, scaled by the gear ratio, from one reported input speed. Neither needs the physics engine, and neither should use it: a simulated gear train is no more accurate than multiplying by a ratio you already know.

Levels, Flow and Deformation

3dverse has no fluid simulation. Physics bodies are rigid and do not deform. Say what you are showing accordingly — these are indications, not simulations:

To show	Do this
Flow through a pipe or channel	A static mesh with a scrolling material, driven by the reported flow rate
A tank or silo level	Scale a mesh along one axis from the reported level, offsetting position by half its height
Discrete items on a line	Spawn one entity per item and move it — the stream defines the population
A surface that changes shape	Weights on a morph_targets component, authored in the DCC tool

The tank case is worth calling out because it is so common and so cheap: a level reading between 0 and 100 becomes a scale and a position, and reads correctly at a glance. Scaling happens about the entity's origin, so lift the entity by half its height to keep its base on the floor.

Which Technique Should I Use?

If your mechanism is...	Use...	What the data provides
Robot arm, gantry, articulated machine	Scene hierarchy, one write per joint	Joint angles or positions
Delta robot, linkage, scissor lift	Solve in the mapping, write every dependent transform	The actuated axes only
Same, when approximate is enough	joint + constraint + constraint_actuator	Targets for the actuated axes
Conveyor, belt, chain	Scrolling UV offset (+ contactVelocity for carried bodies)	A speed, integrated to an offset
Gear train, transmission	local_transform.orientation × gear ratio	One input speed
Tank, silo, hopper level	Scale a mesh on one axis	A level reading
Pipe or channel flow	Scrolling material on a static mesh	A flow rate
Discrete items on a line	Spawn an entity per item	Item identity and position

Next steps

• Quickstart — get the first values moving.
• Mapping events to entities — the full mapping contract.
• Real-Time Robot Digital Twin — a devlog walking through a robot arm driven over OPC-UA, including the update-rate tuning.