[wlgys8]

Summary

This is PR 1 of the robot/deployment configuration refactor, extracted onto main without the robot package extraction or deployment runtime changes.

• Introduce format-neutral actuator declarations on BodyCfg, shared by MJCF and URDF instances.
• Dictionary keys name actuators; None preserves imported actuators, {} removes them, and an explicit mapping replaces the complete actuator set.
• Support position servos and unit-gain joint effort motors in both MuJoCo and MotrixSim scene compilers, before model attachment/name decoration.
• Reset obsolete keyframe control/activation data during replacement while preserving joint position/velocity data (MotrixSim MSD does not expose activation state).
• Migrate the existing Dex-EVT robot and URDF compiler tests to body-owned actuator mappings, retaining asset locations, joint order, drive parameters and model configuration.
• Update the existing English/Chinese robot guides to describe the current actuator configuration; leave scene tutorials unchanged.

Scope / migration

Actuation belongs to the body instance, not the URDF file augmentation. Move UrdfFileCfg(actuators=[...]) declarations to BodyCfg(actuators={name: cfg, ...}); use motrix_env_core.config.scene.actuator for the definition-module imports. Joint references use source-model names before prefix/suffix decoration. Replacement is not append/merge: declare the complete desired set. Actuator name / actuator_name fields are replaced by dictionary keys. Inherited hinge control limits honor the MJCF compiler angle unit (including the default degree setting); slide limits retain their length units.

No robot assets/package extraction, dependency/lock changes, deployment runtime/task/artifact changes, or hardware backend changes are included. The original large branch is preserved.

Review

Independent subagent review was requested before submission. It identified a degree-based MJCF hinge range conversion issue; the fix and regression coverage are included and re-reviewed before submission.

Validation

• Broad isolated-worktree suite: 394 passed, 3 skipped (core, both compiler backends, robot/scene consumers, CLI configuration and view script).
• Independent reviewer final focused suite: 153 passed, 3 skipped, with runtime module paths verified to originate in this worktree.
• Exact baseline Dex-EVT drive comparison and compilation through both backends passed.
• prek run --all-files and git diff --check passed.
• Bilingual documentation snippets parse, construct and validate against the baseline configuration API.
• Strict full English and Chinese Sphinx builds passed for the initial documentation (-E -W --keep-going, Python 3.10/Sphinx 8.1.3). Subsequent requested simplification removes the added tutorial section and migration prose/dead links; both tutorial files now match main.
• After documentation simplification, MotrixSim actuator tests: 21 passed, 3 skipped; pinned Ruff 0.15.16 full-repository format check and all hooks passed.
• MotrixSim 0.10.1 supports MJCF inheritrange during parsing, but its MSD Python actuator API does not expose an inheritance field. Programmatic position actuator creation therefore keeps the resolved joint-limit assignment.

[Copilot]

Copilot review overview

🔵 Needs a closer look

It changes public config API and actuator-preservation semantics across core plus two simulator backends with subtle unit-conversion and keyframe logic that requires simulator execution and human sign-off to fully validate.

Review effort: Balanced
Findings: None

What changed in this PR

This PR unifies joint-actuator configuration so it is owned by the model instance (BodyCfg/RobotCfg) rather than being a URDF-only augmentation on UrdfFileCfg. It introduces a new format-neutral actuator config module shared by MJCF and URDF instances across both the MuJoCo and MotrixSim scene compilers, with None preserving imported actuators, {} removing them, and an explicit mapping replacing the entire set. Replacement also resets obsolete keyframe control/activation data while preserving joint pose/velocity.

Changes:

• New config/scene/actuator.py (ActuatorCfg, MotorActuatorCfg, PositionActuatorCfg); BodyCfg.actuators: dict[str, ActuatorCfg] | None; actuator declarations removed from UrdfFileCfg.
• New apply_actuator_cfgs in both backends (MuJoCo handles hinge degree→radian ctrl-range conversion; MotrixSim resets keyframe ctrl only, since MSD has no activation state), wired into each compiler before attach; old URDF-only actuator paths removed.
• Dex-EVT robot migrated to body-owned actuator mapping; new backend/core test suites; bilingual docs updated.

File	Description
motrix_env_core/​.../​config/​scene/​actuator.py	New format-neutral actuator config classes with finite-gain validation
motrix_env_core/​.../​config/​scene/​base.py	Adds BodyCfg.actuators field + validation and updated docstring
motrix_env_core/​.../​config/​scene/​urdf.py	Removes ActuatorCfg/PositionActuatorCfg and UrdfFileCfg.actuators
motrix_env_core/​.../​config/​scene/​__init__.py	Re-exports actuator classes from the new module
motrix_env_mujoco/​.../​actuators.py	New MuJoCo actuator replacement (position/motor, keyframe reset)
motrix_env_mujoco/​.../​urdf.py, compiler.py	Removes URDF actuator building; wires apply_actuator_cfgs
motrix_env_motrixsim/​.../​actuators.py	New MotrixSim actuator replacement with keyframe ctrl reset
motrix_env_motrixsim/​.../​urdf.py, compiler.py	Removes URDF actuator building and unconditional clear; wires new path
motrix_envs/​.../​robot/​dex_evt.py	Migrates drive params to BodyCfg.actuators dict
*/​tests/​test_*actuator*.py, test_mujoco_scene_compiler.py	New/updated coverage incl. degree-unit regression; PYTHONPATH fix
docs/​.../​robots.md, docs/​.../​scene.md (en/​zh)	Documents new actuator declaration and migration

I verified the migration is complete: no remaining references to the removed UrdfFileCfg.actuators, the actuator_name property, or ActuatorCfg imported from scene.urdf; @configclass deep-copies the mutable actuators default per instance; __init__/__all__ are consistent; and backend validation ordering guarantees invalid inputs don't mutate the spec/world. I did not find concrete objective defects to comment on. The degree/radian conversion and cross-backend keyframe behavior rest on simulator-specific semantics that have regression tests but cannot be executed in this review environment.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.