Simulation Assets

Simulation Assets#

Simulation assets in EmbodiChain are configured using Python dataclasses. This approach provides a structured and type-safe way to define properties for physics, materials and objects in the simulation environment.

Visual Materials#

Configuration#

The VisualMaterialCfg class defines the visual appearance of objects using Physically Based Rendering (PBR) properties.

Parameter	Type	Default	Description
`uid`	`str`	`"default_mat"`	Unique identifier for the material.
`base_color`	`list`	`[0.5, 0.5, 0.5, 1.0]`	Base color/diffuse color (RGBA).
`metallic`	`float`	`0.0`	Metallic factor (0.0 = dielectric, 1.0 = metallic).
`roughness`	`float`	`0.7`	Surface roughness (0.0 = smooth, 1.0 = rough).
`emissive`	`list`	`[0.0, 0.0, 0.0]`	Emissive color (RGB).
`emissive_intensity`	`float`	`1.0`	Emissive intensity multiplier.
`base_color_texture`	`str`	`None`	Path to base color texture map.
`metallic_texture`	`str`	`None`	Path to metallic map.
`roughness_texture`	`str`	`None`	Path to roughness map.
`normal_texture`	`str`	`None`	Path to normal map.
`ao_texture`	`str`	`None`	Path to ambient occlusion map.
`ior`	`float`	`1.5`	Index of refraction for ray tracing materials.

Visual Material and Visual Material Instance#

A visual material is defined using the VisualMaterialCfg class. It is a material template that can create multiple instances with independent parameters.

A VisualMaterialInst can come from either of two sources:

create_instance() creates a new dexsim material instance from an EmbodiChain material template.
from_existing() wraps a dexsim material instance parsed from an asset without copying or replacing it.

When a rigid object, articulation, soft object, or cloth object is constructed, EmbodiChain inspects its render body and automatically wraps an existing material. If no material exists, list-based assets return None, while an articulation omits that link from its material dictionary. For render bodies with multiple mesh segments, this compatibility API exposes the first valid material as the representative instance. Rigid objects and articulations additionally provide get_existing_visual_material() for per-segment access.

get_existing_visual_material() retains every original dexsim MaterialInst and creates a separate working MaterialInst from the first segment’s existing material template. Randomizers can therefore modify and attach the working instance while keeping the original instance available for restoration. This creates an instance, not a new VisualMaterial template.

For batched simulation, set_visual_material() creates an instance per environment by default. Pass shared=True to reuse one instance across environments.

Rigid objects, articulations, soft objects, and cloth objects retain their construction-time per-segment material assignments. Call restore_visual_material() explicitly to restore them; each asset’s reset() method performs the same restoration for the selected environments.

Code#

# Create a visual material with base color white and low roughness.
mat: VisualMaterial = sim.create_visual_material(
    cfg=VisualMaterialCfg(
        base_color=[1.0, 1.0, 1.0, 1.0],
        roughness=0.05,
    )
)

# Set the material to a rigid object.
object: RigidObject
object.set_visual_material(mat)

# Get the material registered for each environment.
mat_inst: list[VisualMaterialInst | None] = object.get_visual_material_inst()

# Modify one instance without changing the other environments.
if mat_inst[0] is not None:
    mat_inst[0].set_base_color([1.0, 0.0, 0.0, 1.0])

To modify a material already contained in a loaded asset, no replacement call is needed:

object: RigidObject = sim.add_rigid_object(cfg=object_cfg)
asset_inst = object.get_visual_material_inst()[0]
if asset_inst is not None:
    asset_inst.set_roughness(0.4)

VisualMaterialInst.set_base_color_texture() accepts a file path, a tensor, or a pre-created dexsim Texture. Reusing a pre-created texture avoids uploading the same image on every material update.

Objects#

All objects inherit from ObjectBaseCfg, which provides common properties.

Base Properties

Parameter	Type	Default	Description
`uid`	`str`	`None`	Unique identifier.
`init_pos`	`tuple`	`(0.0, 0.0, 0.0)`	Position of the root in simulation world frame.
`init_rot`	`tuple`	`(0.0, 0.0, 0.0)`	Euler angles (in degrees) of the root.
`init_local_pose`	`np.ndarray`	`None`	4x4 transformation matrix (overrides `init_pos` and `init_rot`).

Rigid Object#

Configured via RigidObjectCfg.

Parameter	Type	Default	Description
`shape`	`ShapeCfg`	`ShapeCfg()`	Shape configuration (e.g., Mesh, Box).
`attrs`	`RigidBodyPhysicsCfg`	`RigidBodyPhysicsCfg()`	Grouped physical attributes.
`body_type`	`Literal`	`"dynamic"`	“dynamic”, “kinematic”, or “static”.
`shape.collision`	`MeshCollisionCfg \| None`	`None`	Explicit mesh collision geometry: convex hull, convex decomposition, triangle mesh, or SDF. `None` uses one convex hull.
`body_scale`	`tuple`	`(1.0, 1.0, 1.0)`	Scale of the rigid body.

Rigid Body Physics#

RigidBodyPhysicsCfg keeps physical settings in optional groups. An unset field leaves the source asset or backend default intact, which makes the same configuration usable as either a complete procedural definition or a sparse USD/URDF overlay.

Group	Type	Contents
`mass_props`	`MassPropertiesCfg`	Mass, density, inertia, and COM pose.
`rigid_props`	`DefaultRigidBodyPropertiesCfg`	Rigid-body behavior such as damping, CCD, and solver iterations.
`collision_props`	`CollisionPropertiesCfg`	Collision enablement, contact/rest offsets, and concrete-backend contact properties.
`material_props`	`RigidBodyMaterialCfg`	Restitution, friction, and concrete-backend material properties.

COM quaternions in configuration use xyzw. The Spawn adapter converts to the native backend order only when it writes an engine descriptor.

Mesh cooking is owned by MeshCfg.collision, not by rigid-body physics. Its approximation field selects the representation explicitly; strategy-specific fields such as max_hulls and sdf_resolution are validated against it.

For a runnable rigid-object example, see the Create Scene tutorial.

Rigid Object Groups#

RigidObjectGroupCfg allows initializing multiple rigid objects, potentially from a folder.

Lights#

Configured via LightCfg. Supports six light types matching the dexsim rendering backend.

Parameter	Type	Default	Description
`light_type`	`Literal`	`"point"`	Light type: `"point"`, `"sun"`, `"direction"`, `"spot"`, `"rect"`, or `"mesh"`.
`color`	`tuple`	`(1.0, 1.0, 1.0)`	RGB color of the light source.
`intensity`	`float`	`30.0`	Intensity of the light source in watts/m^2.
`enable_shadow`	`bool`	`True`	Whether the light casts shadows.
`radius`	`float`	`10.0`	Falloff radius (only for `"point"`).
`direction`	`tuple`	`(0.0, 0.0, -1.0)`	Direction vector for directional types (`"sun"`, `"direction"`, `"spot"`, `"rect"`, `"mesh"`).
`spot_angle_inner`	`float`	`30.0`	Inner cone angle in degrees (only for `"spot"`).
`spot_angle_outer`	`float`	`45.0`	Outer cone angle in degrees (only for `"spot"`).
`rect_width`	`float`	`1.0`	Width of rectangular area light (only for `"rect"`).
`rect_height`	`float`	`1.0`	Height of rectangular area light (only for `"rect"`).
`mesh_path`	`str`	`""`	Asset path for mesh-based emissive lights (only for `"mesh"`).

.. attention:: "sun" and "direction" are global scene lights (infinite-distance directional light sources). They are created as a single instance on the root environment, not batched per environment. Use :meth:Light.set_direction instead of :meth:Light.set_local_pose for these types.