4.2 插件系统与自定义力学
4.2 插件系统与自定义力学
本节摘要：当内置元素表达不了你要的力学或传感器时，MuJoCo 的插件机制允许把自定义代码接进引擎的官方接口：以执行器、传感器、弹簧阻尼件的身份参与求解循环，而不是在外面「 hack 」状态。本节讲清插件的注册与生命周期、四类官方接口各自的适用场景，以及一套「什么时候该写插件、什么时候千万别写」的判断准则——扩展能力越强的系统，越需要克制。
4.1 的内置近似覆盖了常见非刚体，但总有需求越界：一种新型人工肌肉的力学曲线、一个多自由度柔性关节的耦合弹性、一块需要读取「局部压力分布」的触觉阵列。这些需求的共同点是「要往求解循环里塞私货」。本节讲合法塞私货的方法。
学习目标
阅读完本节，你应当能够：
- 说清插件在 mj_step 流水线里的接入点，解释为什么「插件走官方接口」与「外部改状态」有本质区别；
- 按需求类型选择正确的插件身份：执行器、力反馈件、传感器还是场景元素；
- 遵守插件开发的三条纪律，知道哪些「聪明做法」会在并行化与可微分化时炸雷。
一、插件的正确姿势：走接口，不走后门
先立一个原则性判断。往仿真里加自定义行为有两条路：后门路线是每步 mj_step 之后直接改 data 里的力与状态——写起来最快，破坏力也最强；接口路线是把自定义行为注册成引擎认识的元素（一个执行器、一个传感器、一个弹性件），让引擎在流水线的正确时点调用你。
后门的问题在三步之外才暴露：其一，时序错乱——外挂修改发生在积分之后，引擎对这次修改「毫不知情」，约束求解与能量账本全部失真；其二，并行不通——第七章的 GPU 路线会把仿真体编译成加速器上的批计算，后门代码根本进不去编译；其三，可微分断裂——梯度沿引擎的正式计算图传播，后门的赋值操作让梯度链断在半路。接口路线慢一步注册，三条全通。
插件的生命周期不长但规矩明确：加载时注册（引擎按名字认识它）、编译时读配置（从 MJCF 里拿参数）、每步回调（在约定时点被调用）、释放时清理。对写插件的人，真正要记住的是「你被调用的时点」与「你被允许改什么」——接口契约里写得很清楚，越界就是未定义行为。
二、四类插件身份：按「想干什么」对号入座
身份一：自定义执行器。 需求形态是「输入控制量、输出广义力」。人工肌肉、气动腔体、带迟滞的电机模型都归这类。写好「激活动态」与「力生成」两个函数，引擎把它当作与 motor、muscle 平起平坐的原生执行器——ctrl 范围、力范围、动作空间语义全部通用。第五章 RL 环境里的自定义驱动，走这条路能无痛接入训练管线。
身份二：自定义力件。 需求形态是「两个 site 或 body 之间始终有一对按照自定义规律的相互作用力」。非线性弹簧、磁性吸附、电缆的连续张力都归这类。它与 equality 约束的区别在于「软硬」：等式约束由求解器强制满足，力件只是方程右端的一项力——磁铁吸不上时不会像焊死约束那样产生约束抖动，而是表现出「吸力不够就拉不住」的自然失败。
身份三：自定义传感器。 需求形态是「从当前状态算一个读数」。触觉阵列按接触分布积分出压力图、惯性测量单元按加速度与角速度合成读数、自定义的能耗表计——传感器插件是只读的，不干扰动力学，写起来最安全，也最适合作为插件开发的第一课。
身份四：场景与求解扩展。 官方插件库里的代表性例子（如某些接触变体与深度传感器模拟）属于这类，机制上仍是「注册元素加回调」，但涉及与求解器的更深交互。这类插件的开发门槛最高，原则是：先确认官方插件库没有现成的，再确认需求真的越过了内置元素的表达边界，最后才动手。
三、三条纪律：插件开发的防炸清单
纪律一：无状态优先，状态要登记。 插件内部尽量不存「跨步记忆」；确实需要（如肌肉激活度的动态过程），状态要作为插件实例的正式字段存在，而不是藏在全局变量里。原因在第七章会兑现：GPU 化与并行的前提是「每份仿真实例完全独立」，藏在全局的内存会把两份独立仿真偷偷耦合，症状是「单环境跑对、多环境跑错」——这是插件类 bug 里最阴的一种。
纪律二：只用契约内的输入。 回调里能读什么、能写什么，接口文档划了界。读「上一步的接触力」做力反馈件是合法的，读「引擎内部求解器的中间缓冲」是越界的——那些布局随版本变化，跨版本必炸。把「契约外数据」的诱惑挡住，插件才能跨版本活下来。
纪律三：数值行为要自检。 自定义力的量级、可导性、连续性要自己验证：给插件一个单元测试场景（单独挂它、给扫频输入、看输出与能量账），量级离谱、输出跳变这类问题在独立场景里暴露，比混进整机模型好查十倍。插件是引擎的一部分，就该按引擎的数值标准验收。
一个最小传感器插件的使用视角值得看一眼——不写 C 代码，先看它在 MJCF 里怎么被声明、在 Python 里怎么被消费：
<extension> <plugin plugin_name="touch_grid"/> <!-- 注册：引擎按名识别 --> </extension> ... <sensor> <plugin name="fingertip_grid" plugin="touch_grid" site="fingertip" grid_n="8" grid_m="8"/> <!-- 声明：参数随插件约定 --> </sensor>
# 使用视角：与原生传感器完全同构 adr = model.sensor_adr[model.sensor("fingertip_grid").id] dim = model.sensor_dim[model.sensor("fingertip_grid").id] pressure_map = data.sensordata[adr:adr+dim].reshape(8, 8)
声明、寻址、切片读数——与 2.3 的原生传感器一模一样。这就是接口路线的价值：扩展物与原生元素在用户视角下不可区分，下游所有代码（训练管线、日志、可视化）不需要知道它是不是插件。
四、什么该写插件，什么该收手
把判断准则压成三问。一问：内置元素组合能不能表达？ 非线性弹簧加阻尼器能拼出的大部分行为，不需要插件。二问：能不能在引擎外面做？ 观测的后期处理（图像裁剪、读数滤波）在环境层做更干净，不必进引擎。三问：改的是「力」还是「规则」？ 想改求解器规则、接触模型本身的，插件接口不管这些——那是改引擎源码的工程，维护成本自担，且与官方主线升级永久分叉。
收手信号还包括：插件需要「预知未来」（下一步接触还没生成就要用）、需要跨实例共享状态、需要修改 model 的结构。三者任一出现，说明需求与插件机制的假设错位，重新设计需求比硬写插件便宜。
本节要点回顾
- 接口优先于后门：注册成引擎元素才能保住时序正确、并行可行、可微分三条命；
- 四类身份：执行器出力、力件成对相互作用、传感器只读、场景扩展门槛最高；
- 三条纪律：无状态优先、只用契约内输入、数值行为单元自检；
- 无缝是检验标准：扩展物在用户视角与原生元素不可区分，下游代码零改动；
- 三问再动手：能组合、能外置、只改力的才值得插件，改规则是分叉源码级工程。
引擎能算的、能扩的都讲完了。最后一节解决「看见」的问题：渲染系统怎么把 mjData 的状态变成画面，又怎么变成算法的观测。