generate-incident-config

用途

本技能用于生成和校验 IRI 事件配置 YAML——即定义场景中发生哪些事件、何时发生的文件。该文件由 Event Config File 面板加载，并由 IncidentManager.setup_incidents_from_config_file() 消费。它覆盖 isaacsim.replicator.incident.core 中的三种事件类型（topple、fire、spill）、各自的 item 组以及三种触发类型。

前置条件

已安装的 Isaac Sim，且包含 isaacsim.replicator.incident.core（$ISAAC_SIM_DIR）——仅用于读取扩展版本，不需要运行。
Python 3 及 PyYAML，用于生成脚本。无需 GPU，无需 Kit 会话。
来自 isaac-sim-orchestrator 的 shell 环境约定：$ISAAC_SIM_DIR、$WORKSPACE_DIR。

配置结构

顶层为 isaacsim.replicator.incident 头（注意不是 .core），其下包含 version、global（report_dir、seed）和 event.event_list。每个事件是一个单键映射，例如 ToppleEvent、FireEvent、SpillEvent。

事件与 item 组对应关系：

ToppleEvent → topple_item，item 键为 item、topple_nearby_radius
FireEvent → flammable_item，item 键为 item
SpillEvent → leakable_item，item 键为 item、target_size、leak_duration

item 可接受已打标签的图元路径，或以下随机哨兵之一：$random_loose_item$、$random_flammable_item$、$random_leakable_item$。

使用方式

脚本 scripts/starter_iri_config.py 可离线生成配置，或在扩展 schema 可用时校验现有配置。

生成示例：

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"

校验示例：

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

期望输出 IRI_CONFIG_OK: <path> mode=... errors=0 warnings=0。存在错误时退出码为 1，可直接用于 CI。

校验模式

mode=schema：使用扩展自带的 iri_config.schema.json，与扩展加载时校验的文档一致。需要构建包含该 schema、可通过 --from-ext 访问，且 jsonschema>=4.0 可导入。
mode=builtin：脚本内置的等效检查。适用于无 schema 的构建、未提供 --from-ext，或无 Draft 2020-12 jsonschema 的情况。

相关标志：--from-ext <path> 自动查找 schema 并推导版本；--schema <path> 显式指定 schema；--require-schema 在无法使用 schema 时报错而非回退；--strict 将未知键视为错误。

适用场景

编写、修复或校验事件配置 YAML。
需要为场景定义 topple、fire、spill 事件及触发时机时。

若需为图元打标签、将配置应用到实时阶段并记录报告，应使用 run-incident-events 技能。

限制

本仓库不构建该扩展。isaacsim.replicator.incident.core 在 metrosim 仓库中编写，此处从 extscache 消费。本技能仅描述并生成其配置格式；schema 变更属于上游。
配置本身不产生任何效果。必须先在 USD 阶段为图元打上事件标签，再将配置应用到实时阶段——两者均属于 run-incident-events。
此处的校验是结构性的、离线的，无法判断 /World/Box01 是否存在或已打标签；只有实时阶段可以。
基于 schema 的校验需要构建中包含 data/config_schema/iri_config.schema.json。对于不含该文件的构建，脚本回退到自身等效检查，需手动与扩展保持同步。
FireEvent 不接受 radius。PyroEventProperty 仅定义 flammable_item.item，generate_pyro_event_from_property 将 nearby 半径硬编码为 1.0，配置读取被注释掉。扩展自带的 default_config.yaml 仍带有无效的 flammable_nearby_radius 键。

故障排查

报错“does not contain header:isaacsim.replicator.incident”：顶层头缺失或拼写错误（注意不是 .core）。将所有内容嵌套在 isaacsim.replicator.incident: 下。
报错“version info is missing”：头块内缺少 version 键。添加 version:；使用 --from-ext 生成可确保正确。
报错“Invalid config file version”：主版本号与已安装扩展不同。仅比较主版本，任何 0.x 配置版本对 0.x 构建均通过。
设置的键无效果：EventPropertyBase.set_value 仅复制已知键，未知键被静默丢弃。运行 --validate 可报告所有被丢弃的键。
--validate 意外报告 mode=builtin：构建不含 schema 文件、未提供 --from-ext，或 jsonschema>=4.0 不可导入。note: 行会说明原因；传入 --from-ext "$ISAAC_SIM_DIR"，或用 --require-schema 使其致命。
报错“[seed] value must be a non-negative number”：global.seed 为负数。使用非负整数。
事件加载但从不触发：事件缺少 trigger 块。每个事件都需要 trigger；--validate 会将其标记为错误。
只有第一个事件发生：多个事件指向同一随机哨兵且已打标签的图元耗尽。打更多标签，或将 item: 固定到具体图元路径。

手工编辑现有配置

直接编辑可行，但风险在于错误是静默的。set_value() 只遍历已知键并忽略其余，因此拼写错误会保留默认值并继续以错误值运行。任何手工编辑后都应重新运行 --validate。

扩展自带两个起点：<ext>/config/default_config.yaml（每种事件类型各一个，注意其声明了过时版本，但仍通过，因为只比较主版本，且带有无效的 flammable_nearby_radius 键）；以及 Event Config File 面板的保存按钮，始终写入运行构建的版本。

技能介绍

用途