Generate an IRI Incident Config

Purpose

Produce the YAML that defines which incidents happen in a scene and when — the file the Event Config File panel loads and that IncidentManager.setup_incidents_from_config_file() consumes. Covers the three event types in isaacsim.replicator.incident.core (topple, fire, spill), their item groups, and the three trigger types.

Prerequisites

• An installed Isaac Sim carrying isaacsim.replicator.incident.core ($ISAAC_SIM_DIR) — needed only to read the extension version, not to run.
• Python 3 with PyYAML for the generator script. No GPU, no Kit session.
• Shell env contract from isaac-sim-orchestrator: $ISAAC_SIM_DIR, $WORKSPACE_DIR.

Limitations

• This repo does not build the extension. isaacsim.replicator.incident.core is authored in the metrosim repo and consumed here from extscache. This skill describes and generates its config format; schema changes belong upstream.
• The config alone does nothing. Items must carry incident tags in the USD stage first, and the config must then be applied to a live stage — both belong to run-incident-events.
• Validation here is structural and offline. It cannot tell you whether /World/Box01 exists or is tagged; only a live stage can.
• Schema-backed validation needs a build whose isaacsim.replicator.incident.core ships data/config_schema/iri_config.schema.json. Against builds without it the script falls back to its own equivalent checks, which must be kept in step with the extension by hand.
• FireEvent accepts no radius. PyroEventProperty defines flammable_item.item and nothing else, and generate_pyro_event_from_property hardcodes the nearby radius to 1.0 with the config read commented out. The extension's own shipped default_config.yaml still carries a flammable_nearby_radius key that has no effect.

Troubleshooting

When to use this skill

Config anatomy

isaacsim.replicator.incident:      # header — the extension family, not ".core"
  version: EXT_VERSION             # from the installed extension; only the MAJOR component is compared
  global:
    report_dir: /path/to/output    # where incidents_report.json lands
    seed: 123456                   # non-negative int; seeds random item selection
  event:
    event_list:
    - ToppleEvent:                 # one single-key mapping per event
        name: shelf collapse       # also the incident report's top-level key
        topple_item:
          item: $random_loose_item$
          topple_nearby_radius: 1.5
        trigger:
          type: time
          time: 3

item takes a tagged prim path or one of $random_loose_item$, $random_flammable_item$, $random_leakable_item$. Full key semantics, trigger schemas, and the loader's parsing rules are in references/config-schema.md; the failure modes that produce a silently wrong config are in references/authoring-notes.md. An index of both is in references/README.md.

Available Scripts

Running scripts

The script is offline. From agent runtimes that expose skill execution helpers:

run_script("scripts/starter_iri_config.py", args=["--help"])

Directly:

python3 skills/generate-incident-config/scripts/starter_iri_config.py \
    --from-ext "$ISAAC_SIM_DIR" \
    --event "topple:time=3,radius=1.5" \
    --event "fire:time=6,item=/World/Pallet" \
    --event "spill:time=9,target_size=1.5,leak_duration=5" \
    --report-dir "$WORKSPACE_DIR/EventsResult" \
    --output "$WORKSPACE_DIR/iri_config.yaml"

Workflow

1. Generate. Pass --from-ext "$ISAAC_SIM_DIR" so the version is read from the installed build rather than guessed. With no --event flags you get one of each type on a staggered time trigger.

2. Aim the events. Leave item at its random sentinel to let the extension pick among tagged prims, or set item=/World/Box01 to pin a specific one. A pinned path must be tagged on the stage — this skill cannot check that.

3. Validate. Run before every handoff. It reports version-major mismatches, missing triggers, bad seeds, and — most usefully — keys the loader would drop in silence.

   python3 scripts/starter_iri_config.py --validate "$WORKSPACE_DIR/iri_config.yaml" \
       --from-ext "$ISAAC_SIM_DIR"
   

   Expect IRI_CONFIG_OK: <path> mode=... errors=0 warnings=0. Exit code is 1 when errors are present, so it drops straight into CI.

   mode= reports which rule set was used — see Validation modes. Add --strict to treat unknown keys as errors rather than warnings.

4. Hand off. Give the path to run-incident-events action=setup, or load it from the Event Config File panel. The config is not stored in the USD stage — it saves and loads separately from the scene.

Validation modes

Newer isaacsim.replicator.incident.core builds ship a JSON Schema at data/config_schema/iri_config.schema.json. When it is present the script validates against it; otherwise it uses its own equivalent checks. Selection is automatic, and the result line reports which ran:

Prefer mode=schema when you can: it cannot drift from the extension. builtin exists so the script works everywhere, including against builds that predate the schema — the two agree on every fixture the extension ships.

Editing an existing config by hand

Editing directly is fine; the risk is that mistakes are silent. set_value() walks the keys it already knows and ignores the rest, so a typo leaves the default in place and the run proceeds with the wrong value. Re-run --validate after any hand edit.

Two starting points ship with the extension:

• <ext>/config/default_config.yaml — one of each event type. Note it declares a stale version (which still passes, since only the major is compared) and carries the inert flammable_nearby_radius key.
• The Event Config File panel's save button, which always writes the running build's version.

Related skills

• run-incident-events — tags prims, applies this config to a live stage, records the report.
• isaac-sim-remote — the transport run-incident-events rides on.
• data-collection-sim — Replicator writers that capture the incident semantic labels.
• isaac-sim-orchestrator — env-var contract and skill routing.