02 — Use and author an object component

This case is for scene authors who need reusable rigid objects such as boxes, tools, tableware, or props, and for component authors packaging their assets once.

Audience

Verification level

Configuration only. FastSim resolves the real URDF resource and compiles the object instance. PyBullet is not started, so this is not a physics/rendering pass.

Files

run.yaml places and scales one component instance.
main.py asserts the component kind and the effective entity values.
Object manifest is the reusable catalog entry.
../catalog/index.yaml publishes its stable release.

Component manifest, line by line

yaml

schema: fastsim-component/1              # Required component schema.
id: object://fastsim/component-demo-cube # Namespace plus stable component name.
version: 1.0.0                           # Release selected by the Registry.
kind: object                             # Restricts use to the objects scene group.
semantics:
  category: primitive                    # Optional portable metadata.
variants:
  pybullet:                              # Backend representation used here.
    resources:
      model:                             # Unique name within this variant.
        uri: assets/cube.urdf
        format: model/vnd.urdf+xml       # Explicit format; no filename guessing.
        role: simulation                 # Resource used to create the entity.

To write your own object component, copy this envelope, choose a globally unique object:// identity, increment version for incompatible releases, and point each backend variant to an appropriate asset. Then add the release and manifest SHA-256 to a Registry index. Do not put placement in the manifest: placement belongs to each Run instance.

`run.yaml`, line by line

yaml

schema: fastsim/2                        # Run authoring contract.
name: object-component                   # Name printed in diagnostics and locks.
backend: pybullet                        # Choose the URDF variant.

runtime:
  physics_hz: 60                         # Physics clock declaration.
  control_hz: 30                         # Control clock declaration.
  seed: 102                              # Reproducible seed.

scenario:
  scene:
    objects:
      workpiece:                         # Instance alias, not component identity.
        use: object://fastsim/component-demo-cube
        pose:
          xyz_m: [0.35, -0.10, 0.20]    # Per-instance world position, metres.
          quat_xyzw: [0.0, 0.0, 0.0, 1.0] # Per-instance orientation.
        scale: [0.25, 0.25, 0.25]       # Positive XYZ scale multiplier.
        enabled: true                    # Include this entity in the scene.

The same component can appear many times under different aliases, poses, scales, and instance parameters. use chooses what it is; the surrounding mapping chooses how this occurrence is placed.

What `main.py` proves

The script finds run.yaml relative to __file__, loads the nearest project, and compiles it through the public load_project API. It then reads plan.entities["objects.workpiece"] and checks:

the manifest declared kind: object;
the PyBullet variant was selected;
pose, scale, and enabled reached the immutable plan unchanged;
the instance points to the exact resolved component.

Run it

bash

cd demo/components/02_object_component
fastsim config validate run.yaml --json
fastsim config expand run.yaml
fastsim config explain run.yaml scenario.scene.objects.workpiece.scale
fastsim config lock run.yaml --output run.lock.yaml
fastsim config verify-lock run.lock.yaml --json
python main.py

Expected output

text

Entity: objects.workpiece
Component: object://fastsim/component-demo-cube@1.0.0
Pose xyz_m: (0.35, -0.1, 0.2)
Scale: (0.25, 0.25, 0.25)
Resource: model/vnd.urdf+xml

Common errors

Putting the component below robots: or articulations: causes a kind mismatch.
A zero or negative scale is invalid; all three scale values must be positive.
quat_xyzw must contain four finite values and use XYZW order.
An asset path is resolved relative to its manifest, not relative to run.yaml.
Editing a released manifest requires updating the Registry digest and normally a new semantic version.

Previous: loading pipeline · Next: articulation component