Export model for scripted animation

When preparing a model for use in 3dverse, a clean and logical scene hierarchy (aka scene graph) makes all the difference.

A well-structured hierarchy doesn't just keep your project tidy. It defines how easily your model can be animated, scripted, or controlled once inside 3dverse. This is especially important for robotic systems or any model that relies on serial kinematics. (i.e., parent-child chains of motion).

By "Scripted Animation", we mean animation that is driven by controlled inputs, but not by the 3dverse physics engine, nor by the skeleton animation controller. It can be scripted in different ways, for example:

• From Livelink.js.
• From an animation sequence.
• From a Script event graph (not documented yet).

Think in Terms of Relationships

For example, most CAD exports are just collections of static parts. However in 3dverse, each part becomes an entity in a real-time 3D scene. To make animation and control easier later, organize your parts based on mechanical relationships - how each part depends on or moves with the others - not just how they look.

For exampe, A robotic arm should be organized like this:

RobotBase
 └── Shoulder
      └── Elbow
           └── Wrist
                └── Grippers

Each node inherits its transform from its parent, so when the Shoulder rotates, the entire chain follows naturally.

Local vs Global Transform

In 3dverse, each entity has a local_transform component defining its position, rotation, and scale relative to its parent.

Its global transform is automatically computed by combining its local_transform with the local_transform components of all its ancestors in the hierarchy.

In other words, the entity's final world transform is its local transform applied on top of the parent chain.

Respect the Serial Kinematic Chain

Again, a common CAD export issue is that every part ends up at the same level - hundreds of objects all parented directly to te root node. It makes it hard to animate or apply local transformations logically. Instead:

• Group related parts under a single parent, especially parts that move together.
• Parent each group to the part that drives its motion.
• Keep the hierarchy shallow but meaningful, i.e. avoid over-nesting but make sure parent–child links reflect real mechanical relationships.

In short, respect the serial kinematic chain by organizing parts according to how motion flows through the mechanism.

Define Clear Pivot Points

Each entity must have a pivot (origin) that matches its real-world rotation axis, so before exporting:

• Re-align local origins to their actual hinge or rotation centers.
• Avoid arbitrary global pivots (e.g. everything rotating around the world origin) unless the whole system rotates as one.

Correct pivots ensure predictable motion and simplify animation setup later. This is especially critical for robots, vehicles, and articulated machines.

Use Consistent Naming

Meaningful names make scripting and debugging easier. Use a clear naming scheme such as:

Base
Shoulder_Joint
Elbow_Joint
Wrist_Rotator
Gripper_Left
Gripper_Right

Avoid generated names like Part_00034 or Body_12, which are meaningless outside your design tool.

Validate Before Export

Before exporting from your design tool:

• Confirm pivots and parent–child links behave correctly
• Ensure the object names are meaningful.
• Remove unnecessary helper geometry or objects(construction planes, sketches, constraints, etc.).

If everything moves as intended before export, it will behave predictably into 3dverse.

Keep the Scene Lightweight

Simplify wherever possible:

• Merge identical static parts (like screws, bolts, or nuts) under a same kinematic branch (e.g., screws on the Wrist go under Wrist) into a single mesh.
• Share identical materials between meshes instead of duplicating them.

A compact scene reduces file size, speeds up loading, and keeps animation smooth in 3dverse.

Benefits Inside 3dverse

A clean and well-organized hierarchy means:

• Easier animation setup and scripting.
• Minimal extra setup to recosntruct the kinematic chains.
• Predictable motion.
• Simpler editing and material management.

The scene is lighter, easier to navigate, and more efficient at runtime.

In Short

A well-structured hierarchy is the backbone of a smooth and realistic 3D experience.