Skip to content

Give plugins the owning task; move hooks to holosoma.hooks - #274

Draft
Mark2000 wants to merge 4 commits into
mainfrom
dev/markstph/task-owned-plugins
Draft

Mark2000 wants to merge 4 commits into
mainfrom
dev/markstph/task-owned-plugins

Conversation

@Mark2000

@Mark2000 Mark2000 commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

Plugins now belong to the task rather than the simulator. The hook registry moves to a common module, and each phase is emitted by the layer that owns it: the simulator emits the physics phases, the task emits the task-level ones.

Summary

  • Plugins are built by the task as cls(cfg, task). BaseTask constructs each configured plugin at the end of task setup (after its managers and reset manager), each inside its slot's hooks.installing(key) scope, then validates the registry. A plugin can use any part of the task: task.hooks, task.simulator, task.num_envs and, for policy tasks, its managers. It used to be cls(cfg, simulator) from BaseSimulator.install_plugins().
  • One registry, owned by the task. BaseTask creates the HookRegistry and passes it to the simulator, which takes a new required hooks argument and registers its own callbacks on it (sensor render, bridge, virtual gantry, video, contact recording, MuJoCo backend close). Plugins register on task.hooks, the same object, and keep following task.simulator.sensor_render_hook, the bridge's transport_hook and the ROS2 runtime's close_hook.
  • The registry lives in holosoma.hooks (holosoma/hooks.py), below both the simulator and the task, instead of holosoma.simulator.base_simulator.hooks. frame_base_rates(sim_config) derives the per-phase base rates that every="30Hz" resolves against.
  • Emitters split by layer. BaseSimulator.simulate_at_each_physics_step() emits PRE_STEP before each physics substep and POST_STEP after it. BaseTask emits FRAME_BEGIN, FRAME_END, EPISODE_START/END and CLOSE; motion playback also emits EPISODE_* at clip boundaries, as before.
  • Task-owned teardown. BaseTask emits CLOSE on close() and when setup fails; BaseSimulator.close() is removed.
  • The simulator no longer knows about plugins: install_plugins(), installed_plugins and plugin_config are removed, and so is FullSimConfig.plugin. Plugins are read from the task config; task.installed_plugins holds the instances. Consumers validate env ids against task.num_envs, and the shared ROS2 runtime is keyed on the task.
  • Unchanged: shutdown stays on the simulator (task.simulator.request_shutdown(), polled by SimulationTask).

Ordering

The resolved order on every phase is unchanged:

  • Simulator callbacks still register before any plugin, and consumers declare after= the handles they follow.
  • CLOSE still tears plugins down before the simulator's own resources.
  • The task's pacing hooks (viewer redraw, time_scale rate limiter) are registered after the plugins, so they still run last in each substep.

Breaking changes for out-of-tree code

  • A plugin written as __init__(self, cfg, simulator) takes task instead: register on task.hooks, reach the backend through task.simulator.
  • Phase, HookRegistry and the rest of the hooks API import from holosoma.hooks. The old path is removed, with no re-export.
  • Code that constructs a simulator directly passes a HookRegistry and closes it by emitting CLOSE on that registry.

Commits

  1. Move the hook registry to holosoma.hooks. A pure move plus frame_base_rates.
  2. Give plugins the owning task and a task-owned hook registry.
  3. Emit the physics phases from the simulator and CLOSE from the task.
  4. Check playback's shutdown request on the simulator in the playback harness and test.

Testing

  • pre-commit hooks pass; full mypy . is clean (564 files).
  • pytest -m no_sim from the repo root, as CI runs it: 1,771 passed, 62 skipped.
  • Importing each simulator, plugin and task module first, in a fresh interpreter, succeeds, so the module move adds no import cycle.
  • -m "mujoco and not multi_gpu" (MUJOCO_GL=egl): 318 passed, 34 skipped, plus test_kinematic_playback_classic.py (5 passed) re-run after commit 4.
  • -m "isaacsim and not multi_gpu": 85 passed, 45 skipped.
  • playback_assert.py passes on MuJoCo classic (1 env), MuJoCo Warp (2 envs) and IsaacSim (2 envs).
  • Not run locally: multi-GPU tests.

Test changes:

  • Plugin unit tests construct plugins against a small stand-in task, simulator/plugins/tests/_task.py::plugin_task().
  • simulator/base_simulator/tests/test_plugins.py moves to envs/base_task/tests/test_plugin_install.py and drives the real BaseTask._install_plugins(): plugins get the task, in config-key order, and slot scoping lets a HookRef between two plugins resolve. It previously drove a copy of the install loop.
  • simulator/base_simulator/tests/test_base_simulator_init.py keeps the real-BaseSimulator tests: sensors render before task plugins consume them, the empty sensor registry, and PRE_STEP → step → POST_STEP in dynamics and kinematic mode.
  • test_constructor_cleanup.py: plugins are built after the managers and reset manager, pacing hooks resolve after plugin hooks, and setup failure emits CLOSE.
  • test_frame_egress.py: the fake simulator emits the physics phases itself, as the real one does.
  • Raw-simulator harnesses get a registry from launch_simulator and drop their install_plugins() calls. contact_substep_assert and state_freshness_assert stop emitting the physics phases by hand. The classic MuJoCo playback test and playback_assert.py run through a SimulationTask.

🤖 Generated with Claude Code

@Mark2000 Mark2000 changed the title Give plugins the owning task and use task-owned hooks Give plugins the owning task; take the simulator off the hook registry Oct 27, 2026
@Mark2000 Mark2000 changed the title Give plugins the owning task; take the simulator off the hook registry Give plugins the owning task; move hooks to holosoma.hooks Oct 27, 2026
@Mark2000
Mark2000 force-pushed the dev/markstph/simulation-task branch from 32633de to 3467d0b Compare October 28, 2026 23:53
@Mark2000
Mark2000 force-pushed the dev/markstph/simulation-task branch 3 times, most recently from 5ebad2f to f939004 Compare November 6, 2026 18:20
Mark2000 and others added 4 commits November 13, 2026 09:54
The registry is shared by the simulator and the task, so it moves from
holosoma.simulator.base_simulator.hooks to a module below both,
holosoma/hooks.py, with its tests. frame_base_rates(sim_config) derives
the per-phase base rates that every="30Hz" resolves against, replacing
BaseSimulator._hook_base_rates. No behaviour change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Plugins are constructed as cls(cfg, task) by BaseTask at the end of task
setup, instead of cls(cfg, simulator) by BaseSimulator.install_plugins.
BaseTask creates the HookRegistry and passes it to the simulator, which
registers its own callbacks (sensor render, bridge, gantry, video,
contact recording, backend close) on it; plugins register on task.hooks,
the same object, and reach the backend through task.simulator.

- BaseSimulator takes a required hooks argument and no longer keeps
  plugin configs or installs plugins. FullSimConfig drops its plugin
  field.
- BaseTask builds plugins after its managers and reset manager, each in
  its slot's hooks.installing(key) scope, registers its pacing hooks
  after them so pacing still runs last each substep, then validates the
  registry.
- Consumers validate env ids against task.num_envs. The shared ROS2
  runtime is keyed on the task. Shutdown stays on the simulator.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each layer emits the phases it owns on the shared registry:

- BaseSimulator.simulate_at_each_physics_step() emits PRE_STEP before the
  substep and POST_STEP after it, so any caller of the physics step gets
  them. BaseTask's substep loop no longer emits them.
- BaseTask emits CLOSE itself, on close() and when setup fails;
  BaseSimulator.close() is removed. A standalone simulator is closed by
  emitting CLOSE on the registry it was given. The unreachable simulator
  fallback in _close_environment goes with it.
- The task still emits FRAME_BEGIN, FRAME_END and EPISODE_START/END;
  motion playback also emits EPISODE_* at clip boundaries, as before.

Harnesses that emitted the physics phases by hand around the step stop
doing so, since the step now emits them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Shutdown stays on the simulator, so the playback harness and the classic
MuJoCo playback test read simulator.shutdown_requested.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Mark2000
Mark2000 force-pushed the dev/markstph/task-owned-plugins branch from ac1b862 to c736484 Compare November 13, 2026 18:58
@Mark2000
Mark2000 changed the base branch from dev/markstph/simulation-task to main November 13, 2026 18:58

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant