Audience

Verification level

COMPILE-ONLY PASS. The example resolves the Scenario, recursively resolves its cube leaf component, and checks preserved behavior and evaluation data. It starts no simulator and makes no native-backend claim.

Files

  • run.yaml selects one Scenario component instead of expanding the scene inline.
  • main.py checks the Scenario source, nested cube, behavior, and evaluation.
  • ../catalog/scenario_tabletop.yaml owns the reusable composition.
  • ../catalog/object_cube.yaml is the leaf component referenced by that composition.

Why Scenario is special

Ordinary component defaults configure one leaf instance. They must not form hidden graphs of other components. kind: scenario is the single explicit exception: its defaults.scene may contain leaf use references, because scene composition is its defined responsibility. A Scenario cannot recursively contain another Scenario.

behavior and evaluation are opaque to FastSim Core. Core validates that they are mappings, preserves them, and gives authorized plugins access; it does not interpret “move”, success criteria, grasp semantics, or task policy.

Read the manifest and Run

The Manifest contains the reusable content:

yaml
defaults:
  scene:
    objects:
      cube:
        use: object://fastsim/component-demo-cube
        pose: {xyz_m: [0.45, 0.0, 0.5], quat_xyzw: [0.0, 0.0, 0.0, 1.0]}
  behavior:
    description: Move the cube to a requested target.
  evaluation:
    target_xyz_m: [0.65, 0.0, 0.5]

The Run only selects it:

yaml
scenario:
  use: scenario://fastsim/component-demo-tabletop

Omitting @1.0.0 selects the Registry's declared stable release. Compilation locks the exact Scenario and nested cube releases.

Run it

bash
fastsim config validate run.yaml --json
mkdir -p output
fastsim config materialize run.yaml --output output/tabletop-expanded.yaml
python main.py

Expected output identifies scenario://fastsim/component-demo-tabletop@1.0.0, objects.cube, the behavior description, and a Scenario digest. materialize writes portable inline authoring so a beginner can inspect the resolved composition.

Common errors

  • Adding inline scene beside scenario.use: choose either a reference or an inline Scenario, not both.
  • Referencing scenario://... inside a Scenario's defaults.scene: recursive Scenario composition is rejected.
  • Assuming Core executes behavior: a plugin owns that interpretation.
  • Hiding physical placement in semantic text: entities still require concrete poses.

Previous: 07 — Deformables and fluids · Next: 09 — Defaults and parameters