Prefabs

Module: superdex.physics.prefab

Declarative physics scene descriptions.

Scene Description

The root document and records that organize scene settings, actors, constraints, and nested prefabs.

class ActorLists(*args, **kwargs)

Bases: object

Lists of actors grouped by type.

property articulated

Articulated actors.

property comment

Optional serialized comment.

property rigid

Rigid actors.

property soft

Soft actors.

property soft_skinned

Soft-skinned actors.

class ConstraintLists(*args, **kwargs)

Bases: object

Lists of constraints grouped by type.

property articulated3d_rotation_range

3D rotation range constraints on articulated actors.

property articulated3d_rotation_target

3D rotation target constraints on articulated actors.

property articulated_single_dof_range

Single-DoF range constraints on articulated actors.

property articulated_single_dof_target

Single-DoF target constraints on articulated actors.

property comment

Optional serialized comment.

property deformable_node_position

Position constraints on a deformable actor node.

property deformable_node_to_deformable_node

Constraints connecting two deformable actor nodes.

property deformable_node_to_rigid

Constraints connecting a deformable node to a rigid actor.

property joint_rotation_range

Joint rotation range constraints.

property joint_rotation_tracking

Joint rotation tracking constraints.

property rigid_pivot_position

Position constraints on a rigid actor’s pivot point.

property rigid_pivot_rotation

Rotation constraints on a rigid actor’s pivot frame.

property rigid_pivot_to_rigid_target

Position constraints attaching a rigid actor’s pivot point to a rigid target.

property rigid_prismatic_joint

Prismatic joint constraints between two rigid actors.

property rigid_spherical_joint

Spherical joint constraints between two rigid actors.

class PrefabReference(*args, **kwargs)

Bases: object

Reference to another prefab (scene or actor) for prefab nesting.

property comment

Optional serialized comment.

property name

Name of the nested prefab instance. Used to format the names of nested actors in the form “prefabName/actorName”.

Note

Name-reference ambiguity is evaluated per nested subtree. A nested prefab’s own name-based references resolve within its own instance first, so a name reused across independent sibling instances is not ambiguous for each instance’s internal references. It becomes ambiguous only for a reference written at the enclosing (parent) scope or above.

property path

Path to the nested prefab file.

If non-empty, load_nested_prefabs() reloads the prefab from this path on every call. ensure_fully_loaded() loads it from this path only if the reference does not already contain a loaded prefab. If empty, both functions require the reference to already contain a loaded prefab; they keep that prefab and load all prefabs nested within it.

Note

A reference created with the Python constructor needs a non-empty path before loading because the constructor cannot accept a loaded prefab. C++ callers may instead assign a loaded prefab directly and leave this path empty.

Warning

The loaded prefab is not serialized. After deserialization, an empty-path reference has no loaded prefab and is rejected by load_nested_prefabs() and ensure_fully_loaded(). Set a non-empty path before saving if the reference must remain loadable after deserialization.

property rotation

Rotation quaternion [x, y, z, w] of the nested prefab in the parent’s local space.

Note

Must be finite and non-zero.

property scale

Uniform scale of the nested prefab, relative to the parent prefab.

The scale applied to this nested prefab is this value multiplied by scale and each enclosing scale. See scale for what scaling affects.

Note

Set this value before loading shapes. If changed later, call load_shapes() on the top-level ScenePrefab before adding it to a Scene.

Note

Must be strictly positive and finite. Negative or zero scale is invalid and rejected at add_to_scene().

See also

scale

property translation

Translation [x, y, z] of the nested prefab in the parent’s local space.

Note

Must be finite.

class SceneParams(*args, **kwargs)

Bases: object

Parameters that are global to the Scene in which this prefab will be instantiated.

Note

If prefabs are nested, then only the top-level prefab will use these parameters.

property comment

Optional serialized comment.

property description

Human-readable description of the scene.

property gravity

Optional gravity vector [m/s^2] in world frame.

add_to_scene() replaces the scene’s gravity only when this value is provided by the top-level prefab and apply_scene_settings is true. Otherwise, the existing scene gravity is preserved.

property solver

Optional solver parameters.

add_to_scene() replaces the scene’s complete solver parameters only when this value is provided by the top-level prefab and apply_scene_settings is true. In all other cases, the existing scene solver parameters are preserved. When replacement occurs, fields omitted from the solver object use their default values, e.g. “solver”: {} resets all solver parameters to their defaults.

class ScenePrefab(*args, **kwargs)

Bases: object

Top-level prefab describing a complete or partial physics scene (possibly just one actor).

property actors

Lists of actors by type.

property comment

Optional serialized comment.

property constraints

Lists of constraints by type.

property contact_filter

Contact filter settings for selective contact filtering.

property contact_pair_params_overrides

Optional actor-pair contact parameter overrides.

Entries are applied in array order after all actors in their prefab have been created. A later entry for the same unordered actor pair replaces the earlier override rather than merging with it. Nested child prefab entries are applied before parent entries.

property controllers

List of pose controllers.

property prefabs

List of nested prefab references.

property scene

Global scene parameters (top-level prefab only).

Actors

Actor descriptions.

class ArticulatedActorPrefab(*args, **kwargs)

Bases: object

Prefab parameters for an articulated actor.

property comment

Optional serialized comment.

property cycles

Cycle joints creating closed kinematic loops. Empty if no cycles exist.

property joint_velocities

Optional initial velocity per DoF.

Note

Units depend on joint type: [rad/s] for revolute and spherical, [m/s] for prismatic.

property joints

Joint parameters (one per joint).

property links

Link parameters (one per link).

property name

Optional actor name. Uniqueness is not enforced.

Note

Nested actor runtime paths use the effective actor name as the parent path, where the effective actor name is this actor name combined with any enclosing name or name path. If the effective actor name is empty, runtime nested actor paths use “unnamed_articulation” as the parent path. Prefab actor-reference fields such as contact filters and constraints are authored relative to their containing prefab, and enclosing prefab-reference names are prepended during instantiation. They do not resolve through the “unnamed_articulation” fallback. Use a non-empty actor name or enclosing prefab name when prefab references need to target nested actors.

Note

A name shared by more than one actor cannot be used by name-based prefab references.

property rotation

Actor rotation quaternion [x, y, z, w] relative to the prefab’s local frame (i.e., the prefab-from-root rotation). Composes with rotation to produce the final world-from-root rotation.

Note

Must be finite and non-zero.

property scale

Uniform scale baked into all link and skin shapes when the prefab is instantiated.

Note

Must be strictly positive and finite. Negative or zero scale is invalid and rejected at add_to_scene().

Note

This scale is not applied to rotation and translation. It scales each link’s baked shape by multiplying both shape_scale and shape_translation. It also uniformly scales the skin shape.

property skin

Optional skinned mesh parameters.

property translation

Actor translation [x, y, z] relative to the prefab’s local frame (i.e., the prefab-from-root translation). Composes with scale, rotation, and translation to produce the final world-from-root translation.

Note

Must be finite.

class RigidActorPrefab(*args, **kwargs)

Bases: RigidActorParams

Prefab parameters for a rigid actor.

Extends RigidActorParams. The inherited world_from_local is replaced by the prefab-relative rotation and translation fields, and the inherited shape (a runtime ShapeHandle) is replaced by shape_file (a path serialized to JSON. The shape is loaded at instantiation time).

Note

The inherited name field need not be unique, but a name shared by more than one actor cannot be used by name-based prefab references.

property comment

Optional serialized comment.

property render_model_file

Optional path to a render model file (e.g. .glb) for visualization.

Note

SuperDex Physics does not use this field for simulation. It provides additional metadata for visualization in supported tools. Ignored if empty.

property render_model_rotation

Rotation quaternion [x, y, z, w] to apply to the render model.

Note

Ignored if render_model_file is empty.

property render_model_scale

Scale [x, y, z] to apply to the render model.

Note

Ignored if render_model_file is empty.

property render_model_translation

Translation [x, y, z] to apply to the render model.

Note

Ignored if render_model_file is empty.

property rotation

Actor rotation quaternion [x, y, z, w] relative to the prefab’s local frame (i.e., the prefab-from-local rotation). Composes with rotation to produce the final world-from-local rotation.

Note

Must be finite and non-zero.

property scale

Scale [x, y, z] to bake into the shape file.

Note

All components must be non-zero and finite. Negative scale mirrors the shape.

Note

Some shape data cannot bake arbitrary non-uniform scale. Unsupported scale values are rejected when the shape is loaded.

Note

Precomputed grid SDF data is preserved only when scale is uniform by absolute value. Non-uniform scale by absolute value discards the precomputed SDF. If an SDF collider is used, SuperDex Physics regenerates the SDF from the transformed mesh at runtime, which may be expensive.

property shape_file

Path to a model file that will be loaded and referenced via ShapeHandle.

property shape_rotation

Rotation quaternion [x, y, z, w] to bake into the shape file.

property shape_translation

Translation [x, y, z] to bake into the shape file.

property translation

Actor translation [x, y, z] relative to the prefab’s local frame (i.e., the prefab-from-local translation). Composes with scale, rotation, and translation to produce the final world-from-local translation.

Note

Must be finite.

class SoftActorPrefab(*args, **kwargs)

Bases: SoftActorParams

Prefab parameters for a soft actor.

Extends SoftActorParams. The inherited world_from_local is replaced by the prefab-relative rotation and translation fields, and the inherited shape (a runtime ShapeHandle) is replaced by shape_file (a path serialized to JSON. The shape is loaded at instantiation time).

Note

When used as a standalone soft actor prefab, the inherited name field need not be unique, but a name shared by more than one actor cannot be used by name-based prefab references.

property collider_type

[Experimental] Collision detection geometry.

Note

Determines how OTHER actors detect contact with this actor. It does not affect how this actor detects contact with other actors.

Warning

This is an experimental feature. It may be changed or removed in the future. Use at your own risk.

property comment

Optional serialized comment.

property flow

[Experimental] Optional deep flow shape handle loaded from flow_file.

Warning

This is an experimental feature. It may be changed or removed in the future. Use at your own risk.

property flow_file

[Experimental] Optional path to a deep flow shape handle for collision detection.

Warning

This is an experimental feature. It may be changed or removed in the future. Use at your own risk.

property render_model_file

Optional path to a render model file (e.g. .glb) for visualization.

Note

SuperDex Physics does not use this field for simulation. It provides additional metadata for visualization in supported tools. Ignored if empty.

property render_model_rotation

Rotation quaternion [x, y, z, w] to apply to the render model.

Note

Ignored if render_model_file is empty.

property render_model_scale

Scale [x, y, z] to apply to the render model.

Note

Ignored if render_model_file is empty.

property render_model_translation

Translation [x, y, z] to apply to the render model.

Note

Ignored if render_model_file is empty.

property rotation

Actor rotation quaternion [x, y, z, w] relative to the prefab’s local frame (i.e., the prefab-from-local rotation). Composes with rotation to produce the final world-from-local rotation.

Note

Must be finite and non-zero when used in soft.

Note

Ignored when used in soft_params.

property scale

Scale [x, y, z] to bake into the shape file.

Note

All components must be strictly positive and finite. Negative scale (mirroring) is not supported and rejected at add_to_scene().

Note

If flow_file is set, scale must be (1, 1, 1).

Note

Non-uniform scale is supported only for shape data that supports arbitrary per-axis bake scale. Unsupported scale values are rejected when the shape is loaded.

property sdf

[Experimental] Parameters used to construct a grid-based Signed Distance Field (SDF) if the shape doesn’t already have one.

Note

Ignored if collider_type is not SDF.

Note

Ignored if the shape already has a grid-based SDF.

Warning

This is an experimental feature. It may be changed or removed in the future. Use at your own risk.

property shape_file

Path to a model file that will be loaded and referenced via ShapeHandle.

property shape_rotation

Rotation quaternion [x, y, z, w] to bake into the shape file.

property shape_translation

Translation [x, y, z] to bake into the shape file.

property translation

Actor translation [x, y, z] relative to the prefab’s local frame (i.e., the prefab-from-local translation). Composes with scale, rotation, and translation to produce the final world-from-local translation.

Note

Must be finite when used in soft.

Note

Ignored when used in soft_params.

property use_recentering

[Experimental] Enable automatic recentering of the local coordinate system.

Note

Recentering updates the root transform as the actor moves, keeping local-space displacements small. This improves numerical stability for actors that move far from their initial position.

Note

Ignored for nested soft actors in soft-skinned actors, which do not support recentering.

Warning

This is an experimental feature. It may be changed or removed in the future. Use at your own risk.

class SoftSkinnedActorPrefab(*args, **kwargs)

Bases: object

Prefab parameters for a soft-skinned actor.

A soft-skinned actor consists of an articulated skeleton with one or more attached soft bodies.

property comment

Optional serialized comment.

property enable_colliding_links

Whether links can collide with each other.

property has_gravity

Whether gravity is applied.

property has_inertia

Whether inertia is applied.

property has_stress

Whether soft material stress is applied.

property skeleton_params

Articulated actor parameters for the skeleton.

property soft_attach_links

Local link names to attach each nested soft actor to. Empty or one entry per soft_params element.

Note

If provided, each entry must be non-empty and must match a skeleton link local name.

property soft_params

Parameters for each nested soft actor.

Note

The rotation and translation fields for each nested soft actor are ignored. Nested soft actor transforms are determined by the skeleton’s link attachments (see soft_attach_links).

Note

Each nested soft actor’s scale must be uniform (three equal, strictly positive, finite values). Non-uniform soft shape scale is not supported for soft-skinned prefabs.

Note

If a nested soft actor’s flow_file is set, that entry’s scale must be (1, 1, 1).

Note

Each entry’s inherited name field is a nested soft local name. Explicit non-empty names must be unique across skeleton link local names and other nested soft local names, and must not contain forward slash, backslash, or embedded NUL characters.

Note

Empty names are assigned deterministically after reserving all skeleton link names and all explicit nested soft names: an empty entry at index i uses soft_i if available; otherwise it uses the first available soft_N found by scanning upward from N = 0.

Articulation Components & Controllers

Articulated actor components and pose controllers.

class ArticulatedJointPrefab(*args, **kwargs)

Bases: ArticulatedJointParams

Joint parameters for an articulated actor prefab.

class ArticulatedLinkPrefab(*args, **kwargs)

Bases: ArticulatedLinkParams

Link parameters for an articulated actor prefab.

Extends ArticulatedLinkParams. The inherited shape (a runtime ShapeHandle) is replaced by shape_file (a path serialized to JSON. The shape is loaded at instantiation time). Inherited link local-name requirements apply: names must not contain forward slash, backslash, or embedded NUL characters, and must be unique within the parent articulated actor’s nested actor namespace after default-name assignment.

property render_model_file

Optional path to a render model file (e.g. .glb) for visualization.

Note

SuperDex Physics does not use this field for simulation. It provides additional metadata for visualization in supported tools. Ignored if empty.

property render_model_rotation

Rotation quaternion [x, y, z, w] to apply to the render model.

Note

Ignored if render_model_file is empty.

property render_model_scale

Scale [x, y, z] to apply to the render model.

Note

Ignored if render_model_file is empty.

property render_model_translation

Translation [x, y, z] to apply to the render model.

Note

Ignored if render_model_file is empty.

property shape_file

Path to a simulation model file defining the geometry of the rigid link actor.

Note

Leave empty for dummy links.

property shape_rotation

Rotation quaternion [x, y, z, w] to bake into the shape file.

Note

Ignored if shape_file is empty.

property shape_scale

Scale [x, y, z] to bake into the shape file.

Note

Ignored if shape_file is empty.

Note

All components must be non-zero and finite. Negative scale mirrors the link shape.

Note

Non-uniform scale is supported only for shape data that supports arbitrary per-axis bake scale. Unsupported scale values are rejected when the shape is loaded.

Note

If mass, center_of_mass, or moment_of_inertia are set explicitly, they are transformed consistently with the final per-axis scale applied to the link at add_to_scene(). If they are left unset, they are computed from the scaled shape.

property shape_translation

Translation [x, y, z] to bake into the shape file.

Note

Ignored if shape_file is empty.

class ArticulatedSkinPrefab(*args, **kwargs)

Bases: ArticulatedSkinParams

Skin parameters for an articulated actor prefab.

Extends ArticulatedSkinParams. The inherited shape (a runtime ShapeHandle) is replaced by shape_file (a path serialized to JSON. The shape is loaded at instantiation time).

property render_model_file

Optional path to a render model file (e.g. .glb) for visualization.

Note

SuperDex Physics does not use this field for simulation. It provides additional metadata for visualization in supported tools. Ignored if empty.

property render_model_rotation

Rotation quaternion [x, y, z, w] to apply to the render model.

Note

Ignored if render_model_file is empty.

property render_model_scale

Scale [x, y, z] to apply to the render model.

Note

Ignored if render_model_file is empty.

property render_model_translation

Translation [x, y, z] to apply to the render model.

Note

Ignored if render_model_file is empty.

property shape_file

Path to the model file containing a skinned mesh.

class PoseControllerPrefab(*args, **kwargs)

Bases: object

Prefab parameters for an articulated pose controller.

property articulated_actor

Name or hierarchy path of the articulated actor to control.

Note

A name like “myArticulation” refers to an articulated actor in the same prefab. A name like “myPrefab/myArticulation” refers to an articulated actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property comment

Optional serialized comment.

property joint_tracking

Per-joint pose tracking parameters.

property link_pos_tracking

Per-link position tracking parameters.

property link_rot_tracking

Per-link rotation tracking parameters.

Constraints

Authoring records for constraints that bind actors by name.

class Articulated3dRotationRangeConstraintPrefab(*args, **kwargs)

Bases: Articulated3dRotationRangeConstraintParams

Prefab parameters for a Articulated3dRotationRangeConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name

Name or hierarchy path identifying the articulated actor.

class Articulated3dRotationTargetConstraintPrefab(*args, **kwargs)

Bases: Articulated3dRotationTargetConstraintParams

Prefab parameters for a Articulated3dRotationTargetConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name

Name or hierarchy path identifying the articulated actor.

class ArticulatedSingleDofRangeConstraintPrefab(*args, **kwargs)

Bases: ArticulatedSingleDofRangeConstraintParams

Prefab parameters for a ArticulatedSingleDofRangeConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name

Name or hierarchy path identifying the articulated actor.

class ArticulatedSingleDofTargetConstraintPrefab(*args, **kwargs)

Bases: ArticulatedSingleDofTargetConstraintParams

Prefab parameters for a ArticulatedSingleDofTargetConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name

Name or hierarchy path identifying the articulated actor.

class DeformableNodePositionConstraintPrefab(*args, **kwargs)

Bases: DeformableNodePositionConstraintParams

Prefab parameters for a DeformableNodePositionConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name

Name or hierarchy path identifying the deformable actor.

class DeformableNodeToDeformableNodeConstraintPrefab(*args, **kwargs)

Bases: DeformableNodeToDeformableNodeConstraintParams

Prefab parameters for a DeformableNodeToDeformableNodeConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name_a

Name or hierarchy path identifying deformable actor A.

property actor_name_b

Name or hierarchy path identifying deformable actor B.

class DeformableNodeToRigidConstraintPrefab(*args, **kwargs)

Bases: DeformableNodeToRigidConstraintParams

Prefab parameters for a DeformableNodeToRigidConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property deformable_actor_name

Name or hierarchy path identifying the deformable actor.

property rigid_actor_name

Name or hierarchy path identifying the rigid actor.

class JointRotationRangeConstraintPrefab(*args, **kwargs)

Bases: JointRotationRangeConstraintParams

Prefab parameters for a JointRotationRangeConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name_a

Name or hierarchy path identifying rigid actor A.

property actor_name_b

Name or hierarchy path identifying rigid actor B.

class JointRotationTrackingConstraintPrefab(*args, **kwargs)

Bases: JointRotationTrackingConstraintParams

Prefab parameters for a JointRotationTrackingConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name_a

Name or hierarchy path identifying rigid actor A.

property actor_name_b

Name or hierarchy path identifying rigid actor B.

class RigidPivotPositionConstraintPrefab(*args, **kwargs)

Bases: RigidPivotPositionConstraintParams

Prefab parameters for a RigidPivotPositionConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name

Name or hierarchy path identifying the rigid actor.

class RigidPivotRotationConstraintPrefab(*args, **kwargs)

Bases: RigidPivotRotationConstraintParams

Prefab parameters for a RigidPivotRotationConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name

Name or hierarchy path identifying the rigid actor.

class RigidPivotToRigidTargetConstraintPrefab(*args, **kwargs)

Bases: RigidPivotToRigidTargetConstraintParams

Prefab parameters for a RigidPivotToRigidTargetConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name

Name or hierarchy path identifying the rigid actor.

class RigidPrismaticJointConstraintPrefab(*args, **kwargs)

Bases: RigidPrismaticJointConstraintParams

Prefab parameters for a RigidPrismaticJointConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name_a

Name or hierarchy path identifying rigid actor A.

property actor_name_b

Name or hierarchy path identifying rigid actor B.

class RigidSphericalJointConstraintPrefab(*args, **kwargs)

Bases: RigidSphericalJointConstraintParams

Prefab parameters for a RigidSphericalJointConstraintParams.

Note

Actor name fields use the same naming convention as PoseControllerPrefab. “myActor” refers to an actor in this prefab. “myPrefab/myActor” refers to an actor in a nested prefab.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

property actor_name_a

Name or hierarchy path identifying rigid actor A.

property actor_name_b

Name or hierarchy path identifying rigid actor B.

Contact Filters

Declarative contact rules over actor and layer names.

class ActorContactEntry(*args, **kwargs)

Bases: object

Used by ContactFilter to enable or disable contact for a pair of actors.

See also

enable_actor_contact_asymmetric(), enable_actor_contact_symmetric()

property actors

Identifies two actors by name or hierarchy path.

If the actor is in this prefab, then reference it by name, e.g., “myActor”. If the actor is in a nested prefab, then reference it by hierarchy path, e.g., “myPrefab/myActor”.

Note

A referenced actor name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

Note

Parent actor expansion is controlled by include_nested_actors.

Note

Order matters when contact settings are applied asymmetrically. In that case, the first actor is the “colliding” actor and the second actor is the “collider”. When contact is enabled, the first actor’s contact sample points will be tested against the second actor’s collider geometry.

Note

If both actors are the same, then the setting affects self-contact within the actor.

Warning

Must contain exactly 2 elements.

property enable

Enable (true) or disable (false) contact for the specified pair of actors.

Note

Contact is enabled for all actor pairs by default, except that automatic contact filtering disables adjacent links in articulated and soft-skinned actors. Therefore, you should usually only list additional pairs of actors for which contact should be explicitly disabled.

See also

ContactFilter

property include_nested_actors

Whether expandable parent actor names should include nested actors.

When true, a parent actor name resolves to the parent actor plus nested actors. The contact setting is applied to every ordered pair in the cross-product of the two resolved actor sets; no pairs outside that cross-product are affected. If the resolved sets overlap, pairs in the overlap, including self-pairs, are affected. When false, the contact setting applies only to the exact named actors.

Note

Actors without nested actors are affected as exact actors irrespective of this setting.

Note

Default contact filtering disables contact between adjacent links in articulated and soft-skinned actors. Actor-contact entries override those defaults for pairs included in the resolved actor sets. If include_nested_actors is true and both actor names resolve to the same parent actor, the entry also covers pairs between that parent’s nested actors, including adjacent links.

class ContactFilter(*args, **kwargs)

Bases: object

Contact filtering parameters for a prefab.

Note

By default, all actor pairs can potentially collide with each other, except that automatic contact filtering disables adjacent links in articulated and soft-skinned actors. To prevent additional contact, use this contact filter in one of two ways (or both): 1) Use actor_contact_asymmetric or actor_contact_symmetric to disable contact for a specific pair of actors, or 2) use layer_contact_asymmetric or layer_contact_symmetric to disable contact for a specific pair of contact layer names. This applies to all actors in those layers.

Note

Contact only occurs if it is allowed by both the actor-vs-actor contact filter and the layer-vs-layer contact filter. Either can prevent contact.

Note

You can also explicitly enable contact for a pair of actors or layers to override a setting applied earlier. Actor entries can also override automatic adjacent-link exclusions.

Note

Contact filters are applied after all actors in the prefab have been created. Nested child prefab contact filters are applied before parent prefab contact filters, so parent settings can override child settings in the same actor-vs-actor or layer-vs-layer filter table.

Note

Settings are applied in this fixed order: layer_contact_asymmetric, layer_contact_symmetric, actor_contact_asymmetric, then actor_contact_symmetric. Within each list, entries are applied in array order, so later entries can override earlier entries in the same actor-vs-actor or layer-vs-layer filter table.

Note

Contact filter settings are not necessarily symmetric.

Note

Exporting a scene stores disabled pairs from the effective contact-filter state, not the exact JSON representation originally used to author it. Exporting may emit a canonical representation whose contact-filter category differs from the original JSON. For example, self-contact may be emitted as actor_contact_symmetric because the forward and reverse resolved actor pair are the same. Entry order and duplicate, redundant, or overridden entries from the source prefab are not preserved.

Warning

Scene export does not record explicit settings that enable contact between actor pairs. If such a setting enables contact between adjacent links of an articulated or soft-skinned actor, adding the exported prefab to a scene applies automatic adjacent-link filtering and disables contact for that pair again. To preserve this behavior, add an equivalent enabling entry to the exported prefab or re-enable the pair after adding the prefab to a scene.

See also

ActorContactEntry, enable_actor_contact_asymmetric(), enable_actor_contact_symmetric(), LayerContactEntry, enable_layer_contact_asymmetric(), enable_layer_contact_symmetric()

property actor_contact_asymmetric

Enables or disables contact asymmetrically for each ordered pair of actors.

See also

ContactFilter, ActorContactEntry, enable_actor_contact_asymmetric()

property actor_contact_symmetric

Enables or disables contact symmetrically for each pair of actors.

See also

ContactFilter, ActorContactEntry, enable_actor_contact_symmetric()

property comment

Optional serialized comment.

property layer_contact_asymmetric

Enables or disables contact asymmetrically for each ordered pair of layers.

See also

ContactFilter, LayerContactEntry, enable_layer_contact_asymmetric()

property layer_contact_symmetric

Enables or disables contact symmetrically for each pair of layers.

See also

ContactFilter, LayerContactEntry, enable_layer_contact_symmetric()

class ContactPairParamsOverrideEntry(*args, **kwargs)

Bases: object

Overrides selected contact parameters for an unordered actor pair.

See also

set_contact_pair_params_override(), ContactPairParamsOverride

property actors

Identifies two actors by name or hierarchy path.

If the actor is in this prefab, reference it by name, e.g., “myActor”. If the actor is in a nested prefab, reference it by hierarchy path, e.g., “myPrefab/myActor”.

Note

Each referenced name must identify exactly one existing actor. Actor names need not be unique, but referencing a name shared by more than one actor, or a name that matches no actor, is invalid and rejected at add_to_scene().

Note

Both referenced actors must have contact parameters.

Note

Parent actor names identify only the parent. Name nested actors explicitly to override their contact pairs.

Note

If both names identify the same actor, the entry applies to that actor’s self-pair.

Warning

Must contain exactly 2 elements.

property params_override

Partial contact parameter override for the actor pair.

Note

At least one field must be present.

class LayerContactEntry(*args, **kwargs)

Bases: object

Used by ContactFilter to enable or disable contact for a pair of layers.

See also

enable_layer_contact_asymmetric(), enable_layer_contact_symmetric()

property enable

Enable (true) or disable (false) contact for the specified pair of contact layer names.

Note

Contact is enabled for any pair of layers by default. Therefore, you should usually only list pairs of layers for which contact should be explicitly disabled.

See also

ContactFilter

property layers

Identifies two contact layer names.

Note

Order matters when contact settings are applied asymmetrically. In that case, the first layer is the “colliding” layer and the second layer is the “collider”. When contact is enabled, the contact sample points on an actor in the first layer will be tested against the collider geometry of an actor in the second layer.

Note

Both layer names can be the same. In that case, the setting applies between actors within the same layer.

Warning

Must contain exactly 2 elements.

Loading & Dependencies

Load prefab documents and resolve nested prefabs and shape assets.

ensure_fully_loaded

superdex.physics.prefab.ScenePrefab, root_path: str) -> None

Ensure that all nested prefabs and shape files are loaded, skipping any that are already loaded.

Parameters:

• prefab (ScenePrefab) – The ScenePrefab whose nested prefabs and shapes will be loaded.

• root_path (str) – Root directory for resolving relative paths, except those resolved against a prefab file.

Raises:

Error – If an error occurs.

Note

Use this if the file was loaded via shallow_load_from_file() or shallow_load_from_json_string() or if the ScenePrefab was created procedurally.

Note

You do not need to call this after load_from_file() or load_from_json_string() because they load all nested content for you.

Note

A prefab must not reference itself, directly or indirectly.

Note

If a reference already contains a loaded prefab, this function does not reload its file, even when its path is non-empty; it still loads any missing nested prefabs. A reference with neither a path nor a loaded prefab is invalid. See path for when a path is required.

Warning

If this function returns an error, the input prefab may remain partially loaded. A reference that was unloaded when the call began remains unloaded if its file or any prefab nested within it fails to load.

See also

load_nested_prefabs(), load_shapes(), add_to_scene()

Type:

ensure_fully_loaded(prefab

get_prefab_full_path

str, root_for_relative_path: str, prefab_file_path: str) -> str

Resolve a path referenced inside a prefab to a full path.

Parameters:

• input_path (str) – The path to resolve, as stored in the prefab (may be prefixed with “./” to indicate it is relative to the prefab file).

• root_for_relative_path (str) – Root directory used to resolve paths that are not prefixed with “./”.

• prefab_file_path (str) – Path to the prefab file that references inputPath, used to resolve “./”-prefixed paths relative to its location.

Returns:

The resolved full path.

Note

Absolute paths are returned unchanged. Paths starting with “./” are resolved relative to the directory containing prefab_file_path when provided. Other relative paths are resolved against root_for_relative_path.

Type:

get_prefab_full_path(input_path

load_from_file

str, root_path: str) -> superdex.physics.prefab.ScenePrefab

Fully load a ScenePrefab from a file, including all nested prefabs and shapes.

Parameters:

• prefab_path (str) – File path to the prefab file.

• root_path (str) – Root directory for resolving relative paths, except those resolved against a prefab file.

Returns:

The fully loaded ScenePrefab, or a default-constructed ScenePrefab on error.

Raises:

Error – If an error occurs.

Note

Prefab files are in JSON format.

Note

A prefab must not reference itself, directly or indirectly.

See also

load_from_json_string(), shallow_load_from_file(), shallow_load_from_json_string()

Type:

load_from_file(prefab_path

load_from_json_string

str, root_path: str) -> superdex.physics.prefab.ScenePrefab

Fully load a ScenePrefab from a JSON string, including all nested prefabs and shapes.

Parameters:

• json (str) – JSON string containing the serialized prefab.

• root_path (str) – Root directory for resolving relative paths, except those resolved against a prefab file.

Returns:

The fully loaded ScenePrefab, or a default-constructed ScenePrefab on error.

Raises:

Error – If an error occurs.

Note

The top-level prefab has no source file, so prefab-relative (“./”-prefixed) nested prefab and shape paths written in json resolve against root_path, not against a prefab directory. Nested prefabs that are loaded from files resolve their own “./”-prefixed paths relative to the directory containing the nested prefab file. Use load_from_file() if you need prefab-relative resolution at the top level.

Note

A prefab must not reference itself, directly or indirectly.

See also

load_from_file(), shallow_load_from_file(), shallow_load_from_json_string()

Type:

load_from_json_string(json

load_nested_prefabs

superdex.physics.prefab.ScenePrefab, root_path: str) -> None

Load nested prefab files recursively.

Parameters:

• prefab (ScenePrefab) – The ScenePrefab whose nested prefab references will be loaded.

• root_path (str) – Root directory for resolving relative paths, except those resolved against a prefab file.

Raises:

Error – If an error occurs.

Note

Use this if the file was loaded via shallow_load_from_file() or shallow_load_from_json_string() or if the ScenePrefab was created procedurally.

Note

You do not need to call this after load_from_file() or load_from_json_string() because they load all nested content for you.

Note

A reference with a non-empty path is reloaded from its file on every call. A reference with an empty path must already contain a loaded prefab; this function keeps that prefab and loads all prefabs nested within it. See path for when a path is required. Use ensure_fully_loaded() to avoid reloading prefabs that are already loaded.

Note

A prefab must not reference itself, directly or indirectly.

Warning

If this function returns an error, the input prefab may remain partially loaded. A reference with a non-empty path keeps its previously loaded prefab if its file or any prefab nested within it fails to load; if it had no loaded prefab, it remains unloaded.

See also

ensure_fully_loaded(), load_shapes()

Type:

load_nested_prefabs(prefab

load_shapes

superdex.physics.prefab.ScenePrefab, root_path: str) -> None

Load shape files referenced by prefab and its loaded nested prefabs.

Parameters:

• prefab (ScenePrefab) – The ScenePrefab whose shape references will be loaded.

• root_path (str) – Root directory for resolving relative paths, except those resolved against a prefab file.

Raises:

Error – If an error occurs.

Note

Returns an error if the input prefab or any loaded nested prefab references itself, directly or indirectly.

Note

Use this if the file was loaded via shallow_load_from_file() or shallow_load_from_json_string() or if the ScenePrefab was created procedurally.

Note

You do not need to call this after load_from_file() or load_from_json_string() because they load all nested content for you.

Note

Calling this function again reloads previously loaded shapes to reflect changes to shape file paths or transforms. Use ensure_fully_loaded() to avoid reloading them.

Warning

Shapes are loaded from nested prefabs only if those prefabs are already loaded. Use ensure_fully_loaded() if any nested prefabs may be unloaded.

See also

ensure_fully_loaded(), load_nested_prefabs(), add_to_scene()

Type:

load_shapes(prefab

shallow_load_from_file

str) -> superdex.physics.prefab.ScenePrefab

Deserialize a single ScenePrefab from a file, without loading any nested files.

Parameters:

path (str) – File path to the prefab file.

Returns:

The deserialized ScenePrefab, or a default-constructed ScenePrefab on error.

Raises:

Error – If an error occurs.

Note

Use this if you want to modify the ScenePrefab data before nested content is loaded, or if you simply want to edit and re-save the prefab file.

Note

If you intend to add the ScenePrefab to a Scene, then you will need to load any nested prefabs and shapes first.

See also

ensure_fully_loaded(), load_nested_prefabs(), load_shapes(), shallow_load_from_json_string()

Type:

shallow_load_from_file(path

shallow_load_from_json_string

str) -> superdex.physics.prefab.ScenePrefab

Deserialize a single ScenePrefab from a JSON string, without loading any nested files.

Parameters:

json (str) – JSON string containing the serialized prefab.

Returns:

The deserialized ScenePrefab, or a default-constructed ScenePrefab on error.

Raises:

Error – If an error occurs.

Note

Same as shallow_load_from_file() except that the JSON string is provided in memory.

Note

Unlike shallow_load_from_file(), this function is not given a source file for the top-level prefab. Its “./”-prefixed nested prefab and shape paths therefore resolve against the root path passed to load_nested_prefabs(), load_shapes(), or ensure_fully_loaded(). Pass the prefab directory as the root path to preserve prefab-relative resolution.

See also

shallow_load_from_file(), load_from_json_string()

Type:

shallow_load_from_json_string(json

Instantiation

Instantiate a loaded prefab in a scene and inspect the created objects.

class AddToSceneResult(*args, **kwargs)

Bases: object

Struct used to return all created actors and constraints from add_to_scene().

Note

The returned pointers are non-owning. They remain valid as long as the Scene is alive and the actors/constraints have not been destroyed.

property actors

All newly created actors.

Note

Order is not guaranteed except that actors from nested prefabs will be listed before actors from the top-level prefab.

Note

Contains only top-level actors. Articulated actors’ nested link actors and soft-skinned actors’ nested link actors and nested soft actors are created but not listed here. Reach them via get_nested_link_actors() and get_nested_soft_actors().

See also

filter()

property constraints

All newly created constraints.

Note

Order is not guaranteed except that constraints from nested prefabs will be listed before constraints from the top-level prefab.

See also

filter()

filter

Overloaded function.

1. filter(self, type: superdex.physics.ActorType) -> superdex.physics.DynamicArrayActor

Return all the newly created actors of a particular type, in order.

Parameters:

type (ActorType | int) – Type of actor to return.

Returns:

List of actors of the specified type.

Note

If there were nested prefabs, then actors will be listed in depth-first order.

Note

For a single prefab (no nested prefabs) whose actors have no nested link actors or nested soft actors, the result is 1-to-1 with the prefab’s actors of that type (same size, same order). Nested link actors and nested soft actors are not listed, and soft-skinned actors are reported under ARTICULATED.

2. filter(self, type: superdex.physics.ConstraintType) -> superdex.physics.DynamicArrayConstraint

Return all the newly created constraints of a particular type, in order.

Parameters:

type (ConstraintType | int) – Type of constraint to return.

Returns:

List of constraints of the specified type.

Note

If there were nested prefabs, then constraints will be listed in depth-first order.

Note

For a single prefab (no nested prefabs), the result will be 1-to-1 with the constraint list in the prefab (same size, same order).

class PrefabParams(*args, **kwargs)

Bases: object

Parameters for instantiating a ScenePrefab into a Scene.

property apply_scene_settings

Whether to apply top-level scene settings.

When true, add_to_scene() applies gravity and solver overrides from the SceneParams of the top-level prefab. Omitted overrides preserve existing scene values. When false, neither override is applied. Scene settings from nested prefabs are always ignored.

property name

Optional name prefix for created actors.

Actor names are formatted based on their hierarchy paths. If this string is not empty, it will be used as the first token in the path (“prefabName/actorName”, “prefabName/nestedPrefabName/actorName”, etc.)

property rotation

Rotation quaternion [x, y, z, w] of the new prefab in world-space.

Note

Must be finite and non-zero.

property scale

Uniform scale of the new prefab in world-space.

Composes multiplicatively with any nested scale and any per-actor scale (e.g. scale) to give the cumulative “effective scale” baked into each actor when the prefab is instantiated.

The effective scale is applied to:

• Mesh geometry (link / actor shapes are loaded at the cumulative scale)

• Joint and link translations, cycle joint anchors

• Prismatic joint position limits (Real3, in meters)

• Constraint geometric target and limit distances [m], including rigid prismatic joint limits, world-space position targets, rigid actor-local pivot/joint positions in RigidPivotPositionConstraintPrefab, RigidPivotToRigidTargetConstraintPrefab, and RigidSphericalJointConstraintPrefab; the rigid-local attachment/search point in DeformableNodeToRigidConstraintPrefab; and translational single-DoF target/range values in ArticulatedSingleDofTargetConstraintPrefab and ArticulatedSingleDofRangeConstraintPrefab. Actor-local constraint distances use the referenced actor’s prefab metric scale, so standalone rigid/soft shape-bake scale fields are not applied again.

• User-supplied inertia overrides on rigid and articulated link actors: center of mass scales componentwise by the signed effective scale, mass scales by the absolute effective volume scale, moment of inertia uses the corresponding diagonal inertia transform. For a purely uniform effective scale s, this reduces to:

  centerOfMass *= s
  mass *= s^3
  momentOfInertia *= s^5
  

The mass and moment of inertia formulas preserve the user’s authored density.

The effective scale is NOT applied to:

• density (intrinsic material property; mass/density are mutually exclusive in the prefab API, so no double-application)

• linearVelocity / angularVelocity / jointVelocities

• Contact-pair parameter overrides, whose authored values are preserved

• Constraint stiffness/damping coefficients and saturation thresholds inherited from ConstraintParams. These parameters define the constraint’s response, not just geometry: different goals (preserving material behavior, damping ratio, actuator limits, or closed-loop response) imply different scale laws, so prefab scaling preserves authored values.

• Joint inertia, friction, limit stiffness/damping, cycle joint stiffness (characterized actuator / tuned-penalty parameters; bring your own actuator model when scaling a robot)

• Revolute and spherical joint angular limits, rotation-valued targets and ranges in Articulated3dRotationTargetConstraintPrefab and Articulated3dRotationRangeConstraintPrefab, and rotational single-DoF target/range values in ArticulatedSingleDofTargetConstraintPrefab and ArticulatedSingleDofRangeConstraintPrefab (scale invariant)

Note

Must be strictly positive and finite. Negative or zero scale is invalid and rejected at add_to_scene(). The ScenePrefab overload additionally requires scale == 1; use the file-path add_to_scene() overload, nested scale, or per-actor scale for non-identity scaling.

Note

Authoring with mass = M is equivalent to authoring with the implied density M / V_unit; under prefab scale the density is preserved and mass scales with the absolute volume scale, so the result is “the same material at a bigger size.” For a purely uniform effective scale s, this mass factor is s^3. If you need a fixed mass that does NOT scale with the prefab, set the mass at runtime via set_density() after the actor is instantiated.

property translation

Translation (position) of the new prefab in world-space.

Note

Must be finite.

add_to_scene

superdex.physics.prefab.ScenePrefab, scene: superdex.physics.Scene | None, params: superdex.physics.prefab.PrefabParams) -> superdex.physics.prefab.AddToSceneResult add_to_scene(prefab: superdex.physics.prefab.ScenePrefab, scene: superdex.physics.Scene | None) -> superdex.physics.prefab.AddToSceneResult add_to_scene(prefab_path: str, root_path: str, scene: superdex.physics.Scene | None, params: superdex.physics.prefab.PrefabParams) -> superdex.physics.prefab.AddToSceneResult add_to_scene(prefab_path: str, root_path: str, scene: superdex.physics.Scene | None) -> superdex.physics.prefab.AddToSceneResult

Overloaded function.

1. add_to_scene(prefab: superdex.physics.prefab.ScenePrefab, scene: superdex.physics.Scene | None, params: superdex.physics.prefab.PrefabParams) -> superdex.physics.prefab.AddToSceneResult

Instantiate a ScenePrefab and add it to a Scene.

Creates the prefab’s actors, constraints, and controllers, applies any scene settings enabled by apply_scene_settings, contact filter entries, and contact-pair parameter overrides.

Parameters:

• prefab (ScenePrefab) – The fully loaded ScenePrefab to instantiate.

• scene (Scene) – The Scene to add things to.

• params (PrefabParams) – Parameters for how and where to instantiate the prefab. Can optionally be omitted in Python.

Returns:

An AddToSceneResult containing pointers to all created actors and constraints.

Raises:

Error – If an error occurs.

Note

The prefab must be fully loaded (nested prefabs and shapes) before calling this function. If you’re not sure, then call ensure_fully_loaded().

Warning

This function is not transactional. If it returns an error, the prefab may have been partially instantiated in the scene.

Warning

Only supported with scale = 1. To instantiate at a non-identity scale, use the file-path add_to_scene() overload or a nested scale.

See also

load_from_file(), ensure_fully_loaded(), PrefabParams

2. add_to_scene(prefab: superdex.physics.prefab.ScenePrefab, scene: superdex.physics.Scene | None) -> superdex.physics.prefab.AddToSceneResult

Overload of add_to_scene() that instantiates a ScenePrefab using default PrefabParams.

Parameters:

• prefab (ScenePrefab) – The fully loaded ScenePrefab to instantiate.

• scene (Scene) – The Scene to add things to.

Returns:

An AddToSceneResult containing pointers to all created actors and constraints.

Raises:

Error – If an error occurs.

Warning

This function is not transactional. If it returns an error, the prefab may have been partially instantiated in the scene.

See also

add_to_scene()

3. add_to_scene(prefab_path: str, root_path: str, scene: superdex.physics.Scene | None, params: superdex.physics.prefab.PrefabParams) -> superdex.physics.prefab.AddToSceneResult

Load a scene prefab from a file and create an instance of it in the Scene.

This is a convenience function that loads the prefab, including all nested prefabs and shapes, and immediately adds it to the scene. All loaded shape handles are released automatically afterward.

Parameters:

• prefab_path (str) – File path to the prefab file.

• root_path (str) – Root directory for resolving relative paths, except those resolved against a prefab file.

• scene (Scene) – The Scene to add things to.

• params (PrefabParams) – Parameters for how and where to instantiate the prefab.

Returns:

An AddToSceneResult containing pointers to all created actors and constraints.

Raises:

Error – If an error occurs.

Note

If you intend to add multiple copies of the prefab to a scene, or to multiple scenes, then consider using load_from_file() to load a ScenePrefab object. You can use that ScenePrefab multiple times.

Note

Unlike the ScenePrefab overload, this overload supports non-identity scale by baking it into actor geometry during load.

Warning

This function is not transactional. If it returns an error, the prefab may have been partially instantiated in the scene.

See also

load_from_file(), add_to_scene(), PrefabParams

4. add_to_scene(prefab_path: str, root_path: str, scene: superdex.physics.Scene | None) -> superdex.physics.prefab.AddToSceneResult

Overload of add_to_scene() that loads a prefab from a file and instantiates it using default PrefabParams.

Parameters:

• prefab_path (str) – File path to the prefab file.

• root_path (str) – Root directory for resolving relative paths, except those resolved against a prefab file.

• scene (Scene) – The Scene to add things to.

Returns:

An AddToSceneResult containing pointers to all created actors and constraints.

Raises:

Error – If an error occurs.

Warning

This function is not transactional. If it returns an error, the prefab may have been partially instantiated in the scene.

See also

add_to_scene()

Type:

add_to_scene(prefab

Serialization & Export

Serialize prefab documents and export live scenes or actors.

export_actor

superdex.physics.Actor | None, export_name: str, output_dir: str) -> None

Export a single actor to a prefab file under outputDir/exportName/<exportName>.mochi_scene.

Extracts creation parameters from the actor and writes the prefab plus any generated mesh assets to disk.

Parameters:

• actor (Actor) – The actor to export. Must not be None.

• export_name (str) – Label used for the actor’s name, the export subdirectory, and the prefab filename (<exportName>.mochi_scene).

• output_dir (str) – Parent directory for the export. The subdirectories <outputDir>/<exportName> and <outputDir>/<exportName>/generated_assets are created automatically.

Raises:

Error – If an error occurs.

Note

Any limitations documented in export_scene() also apply here.

Note

When exporting an articulated actor, pass the articulated actor itself (the one returned by create_articulated_actor() or by get_articulated_actor() on a nested link), not a nested actor.

Note

Generated mesh files (.mochi.h5) are written under generated_assets/ and referenced from the prefab using “./generated_assets/” paths.

Warning

Only supported for standalone rigid actors, standalone soft actors, and articulated actors. Soft-skinned actors are not supported.

Warning

Scene-level contact-filter settings and contact-pair parameter overrides are not exported. Adding an exported articulated actor to a scene applies automatic adjacent-link filtering, even if contact between adjacent links was explicitly enabled before export. To preserve this behavior, add an equivalent enabling entry to the exported prefab or re-enable the pair after adding the prefab to a scene.

See also

export_scene(), export_scene_excluding()

Type:

export_actor(actor

export_scene

superdex.physics.Scene | None, export_name: str, output_dir: str) -> None

Export a Scene to a folder containing a prefab file and all generated mesh files.

Parameters:

• scene (Scene) – The Scene to export.

• export_name (str) – Name for the exported prefab. Used both for the export subdirectory and for the prefab filename (<exportName>.mochi_scene).

• output_dir (str) – Directory where the export folder will be created. The subdirectories <outputDir>/<exportName> and <outputDir>/<exportName>/generated_assets are created automatically.

Raises:

Error – If an error occurs.

Note

Generated mesh files (.mochi.h5) are written under generated_assets/ and referenced from the prefab using “./generated_assets/” paths.

Note

Exported actor names are made unique: when two actors share a name, later ones receive a numeric suffix (e.g. “box”, “box1”), so an exported name may differ from the runtime name.

Note

Scene export reconstructs supported creation and configuration data from effective runtime state. It is not a lossless or structure-preserving round trip of any prefab used to create the scene.

Warning

Currently exports only rigid, soft, articulated, and soft-skinned actors. Constraints, pose controllers, shell, rod actors, and implicit (non-mesh) shapes are NOT exported.

Warning

For articulated actors, current joint pose and joint velocities are NOT exported.

Warning

Scene export does not record explicit settings that enable contact between actor pairs. If such a setting enables contact between adjacent links of an articulated or soft-skinned actor, adding the exported prefab to a scene applies automatic adjacent-link filtering and disables contact for that pair again. To preserve this behavior, add an equivalent enabling entry to the exported prefab or re-enable the pair after adding the prefab to a scene.

See also

export_scene_excluding(), export_actor()

Type:

export_scene(scene

export_scene_excluding

superdex.physics.Scene | None, export_name: str, output_dir: str, exclude_actors: Span[superdex.physics.ActorHandle]) -> None

Export a Scene to a folder containing a prefab file and all generated mesh files, omitting a caller-provided set of actors.

Parameters:

• scene (Scene) – The Scene to export.

• export_name (str) – Name for the exported prefab. Used both for the export subdirectory and for the prefab filename (<exportName>.mochi_scene).

• output_dir (str) – Directory where the export folder will be created. The subdirectories <outputDir>/<exportName> and <outputDir>/<exportName>/generated_assets are created automatically.

• exclude_actors (ArrayLikeActorHandle) – Handles of actors that should not be exported. Excluding an articulated actor also excludes all of its nested link actors. Excluding a soft-skinned actor also excludes all of its nested link actors and nested soft actors. Any contact filter or contact-pair parameter override entries that reference excluded actors are dropped.

Raises:

Error – If an error occurs.

Note

Generated mesh files (.mochi.h5) are written under generated_assets/ and referenced from the prefab using “./generated_assets/” paths.

Note

Exported actor names are made unique: when two actors share a name, later ones receive a numeric suffix (e.g. “box”, “box1”), so an exported name may differ from the runtime name.

Warning

Currently exports only rigid, soft, articulated, and soft-skinned actors. Constraints, pose controllers, shell, rod actors, and implicit (non-mesh) shapes are NOT exported.

Warning

For articulated actors, current joint pose and joint velocities are NOT exported.

Warning

Scene export does not record explicit settings that enable contact between actor pairs. If such a setting enables contact between adjacent links of an articulated or soft-skinned actor, adding the exported prefab to a scene applies automatic adjacent-link filtering and disables contact for that pair again. To preserve this behavior, add an equivalent enabling entry to the exported prefab or re-enable the pair after adding the prefab to a scene.

See also

export_scene(), export_actor()

Type:

export_scene_excluding(scene

save_to_json_file

superdex.physics.prefab.ScenePrefab, path: str) -> None

Serialize a ScenePrefab to a JSON file.

Parameters:

• prefab (ScenePrefab) – The ScenePrefab to serialize.

• path (str) – Output file path.

Raises:

Error – If an error occurs.

Note

Does NOT serialize nested prefabs. Only the top-level prefab data is written.

Note

Automatically creates the output directory path, as needed.

See also

save_to_json_string()

Type:

save_to_json_file(prefab

save_to_json_string

superdex.physics.prefab.ScenePrefab) -> str

Serialize a ScenePrefab to a JSON string.

Parameters:

prefab (ScenePrefab) – The ScenePrefab to serialize.

Returns:

The JSON string, or an empty string on error.

Raises:

Error – If an error occurs.

Note

Does NOT serialize nested prefabs. Only the top-level prefab data is written.

See also

save_to_json_file()

Type:

save_to_json_string(prefab

Containers

Owning array containers that carry prefab records across the native API.

class DynamicArrayActorContactEntry(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayArticulated3dRotationRangeConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayArticulated3dRotationTargetConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayArticulatedActorPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayArticulatedJointPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayArticulatedLinkPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayArticulatedSingleDofRangeConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayArticulatedSingleDofTargetConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayContactPairParamsOverrideEntry(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayDeformableNodePositionConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayDeformableNodeToDeformableNodeConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayDeformableNodeToRigidConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayJointRotationRangeConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayJointRotationTrackingConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayLayerContactEntry(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayPoseControllerPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayPrefabReference(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayRigidActorPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayRigidPivotPositionConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayRigidPivotRotationConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayRigidPivotToRigidTargetConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayRigidPrismaticJointConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArrayRigidSphericalJointConstraintPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArraySoftActorPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist

class DynamicArraySoftSkinnedActorPrefab(*args, **kwargs)

Bases: object

A resizable array with contiguous storage.

Warning

Instances are not thread-safe. Concurrent access to the same instance requires external synchronization if any access mutates the array or its exported storage.

append

capacity

clear

empty

extend

reserve

resize

size

tolist