07 — Deformable and fluid components

This example is for beginners adding cloth-like or liquid entities without writing simulator-specific setup code. It shows both component kinds, their procedural source parameters, how a Run places them, and how to read their state through the same public Application API.

Audience

Verification level

This case has two explicit levels:

CONFIGURATION PASS: main.py validates both Manifests and checks the enabled cloth plus separately selectable water record without starting a simulator.
VISIBLE ISAAC DEFORMABLE RUN: python verify_runtime.py opens Isaac, reads all 144 cloth nodes, advances physics, and verifies that the cloth moved under gravity.
VISIBLE ISAAC FLUID RUN: fastsim run fluid.yaml --duration 5 runs the separately enabled particle fluid.

FastSim lowers procedural surface deformables and particle fluids to UniRoboSim and exposes both as on-demand state queries. Isaac Lab 3.0 cannot combine this adapter's USD-readback particle path with its tensor-backed deformable path in one native World, so the two checked configurations select one enabled matter type at a time.

Files

run.yaml enables the cloth and disables water for the visible deformable check.
fluid.yaml disables the cloth and enables water for the visible fluid check.
main.py compiles the Run through the public configuration API and checks the resolved kinds, enabled states, capabilities, and procedural source types.
verify_runtime.py reads immutable deformable snapshots through FastSimApplication.deformable() before and after physics advances.
../catalog/deformable_cloth.yaml defines the reusable deformable component.
../catalog/fluid_water.yaml defines the reusable fluid component.
../catalog/index.yaml publishes both releases as stable.

Read the manifests

The cloth manifest uses the deformable:// identity scheme and kind: deformable. Its defaults.params.source describes a surface grid; material density is component data shared by every instance unless a Run overrides it.

The water Manifest uses fluid:// and kind: fluid. Its box-grid source fixes the particle region and spacing, while material holds density, viscosity, and surface tension.

It deliberately does not declare capabilities: [fluid]. Component capabilities are mapped FastSim contracts, not free-form labels and not raw UniRoboSim Provider capabilities. For this procedural entity, kind: fluid, semantics.model: particle_fluid, and the typed parameters select Fluid Lowering. FastSim then adds the versioned UniRoboSim requirement state.fluid.particles@1 to the World automatically.

Read the Run

yaml

scenario:
  scene:
    deformables:
      cloth:
        use: deformable://fastsim/component-demo-cloth
        enabled: true
        pose:
          xyz_m: [0.0, 0.0, 1.2]
          quat_xyzw: [0.0, 0.0, 0.0, 1.0]
    fluids:
      water:
        use: fluid://fastsim/component-demo-water
        enabled: false
        pose:
          xyz_m: [0.0, 0.0, 0.8]
          quat_xyzw: [0.0, 0.0, 0.0, 1.0]

cloth and water are Scenario-local aliases. use asks the Project Registry for the stable release; pose remains instance-specific physical placement. An entity with enabled: false stays in the Scenario, ExecutionPlan, and Lock for authoring inspection but is excluded from Runtime projection. fluid.yaml reverses the two flags because of the documented Isaac mixed-matter limitation.

Run it

From this directory:

bash

fastsim config validate run.yaml --json
fastsim config expand run.yaml
python main.py
python verify_runtime.py
fastsim run fluid.yaml --duration 5 --json

Expected output names backend isaaclab, source types surface_grid and box_grid, their enabled/disabled states, and one 64-character Plan digest. The runtime verifier prints node count, generation, tick, and cloth centroid before/after gravity. The final command opens visible Isaac for the particle-fluid variant and closes cleanly after five wall-clock seconds.

The CLI lifecycle run proves native construction, stepping, and clean shutdown. For a semantic Fluid test that reads 125 particles, advances exactly 60 physics ticks, and verifies centroid motion, continue to fundamentals/17_liquid.

Common errors

Adding capabilities: [fluid] as a descriptive tag causes FastSim capabilities are not mapped by the procedural projection. Remove it; kind and semantics drive this Fluid projection.
Enabling Cloth and Water together is rejected by the Isaac adapter because its two native state paths cannot share one World. Use the two supplied Run files.
Putting water under objects: the entity group must match the manifest kind.
Omitting a physical pose because behavior text describes a relation: component semantics do not replace concrete scene placement.

Previous: 06 — Sensors and lights · Next: 08 — Scenario component