Migration From 0f90a49

从 0f90a49 迁移到当前 Mod 架构

本页总结 0f90a49c539e0efcec0d6fbc481f634890742c78 之后影响使用方的主要变化。

已删除的入口

以下旧入口不再存在：

bxi_example_py_elf3/robot_states.py
config/release_protection.yaml
data/isaaclab_model/
data/mjlab_model/

中央状态 YAML 中的 states、remote_events 和 speed_profiles 也不再作为配置源。

新的对应关系

旧方式	当前方式
在中央文件添加 State class	在 Mod 目录添加状态模块
构建器扫描所有 State 子类	plugin.py 返回显式 state_factories
中央 YAML 声明状态和边	mod.yaml 声明 states/events/routes
模型挂在 ctx 动态属性	ResourceKey + ResourceHandle
模型放 data/*_model	模型放所属 Mod 的 assets/
按单个类/模型做发布删除	visibility: protected 删除整个 Mod
热重载中央状态模块	不再支持运行时重载；修改后重启控制节点

状态名变化

基础动作已经合并到：

com.bxi.basic_actions

例如：

旧：com.bxi.normal/normal
新：com.bxi.basic_actions/normal

旧：com.bxi.zero_torque/zero_torque
新：com.bxi.basic_actions/zero_torque

基础事件也变为动作名：

com.bxi.basic_actions/normal
com.bxi.basic_actions/zero_torque
com.bxi.basic_actions/dance

后空翻、前空翻和芭蕾舞仍是独立 Mod，其入口事件是各自的 activate。

迁移一个旧状态

1. 创建 mods/com.example.action/。
2. 把状态类移到 state.py。
3. 把模型和动作数据移到 assets/。
4. 创建 plugin.py，注册资源并返回状态工厂。
5. 把中央 YAML 的状态、事件和边改写为 mod.yaml 的 states/events/routes。
6. 跨包引用改成完整名称并写入 requires。
7. 遥控器输出槽位可以保持不变。

完整模板见 手把手自定义状态 和 模型动作 Mod。

发布迁移

旧的类名、模型键和路径删除清单全部移除。现在只需在高危 Mod 中写：

visibility: protected

然后运行：

python3 tools/sanitize_release.py --out /tmp/public_release --self-check

工具会检查跨 Mod route 推导出的依赖和显式 requires，防止公开 Mod 依赖被删除 Mod。

运行时更新方式

/hot_reload 参数已经删除。系统 YAML、Mod 清单、状态代码、Transition 或模型资产发生变化后，需要重启控制节点。所有发现、依赖排序、资源注册和状态图校验都在启动阶段完成；运行期间不扫描文件，也不替换状态机对象。

index 冲突

当前加载器不会因两个 manifest.index 相同而直接退出。首次声明者保留原值，冲突状态会移到后续未占用 index，并输出 RuntimeWarning。非法值仍会报错。