roqsim

roqsim is a lightweight, plugin-driven MuJoCo simulation framework for mobile robots, robot arms, and mobile manipulators. A MuJoCo step loop plus plugins that hook into well-defined lifecycle points, all loaded and configured from a single YAML file.

It runs standalone (a viewer by default, headless for CI and containers, real-time / scaled / as-fast-as-possible pacing) and as a scenario-execution SimulationInterface. The core is ROS-free and pip-installable; a ROS 2 bridge is provided as a separate package.

If you just want to see it run, start with Getting started.

User guide

• Getting started
  • Prerequisites
  • Five steps
  • No display? Run it headless
  • Where to next
• Installation
  • The Makefile (recommended)
  • Manual install
  • ROS 2 (optional)
  • External assets (fetched + converted, not committed)
  • Interpreter note
  • Container images
• Quickstart
  • Standalone
  • Checking a world before running it
  • Recording a run
  • Starting where the run starts moving
  • Moving the camera: chase, path, and a person flying it
  • Drawing on the frames
  • Rendering fewer frames than the recording holds
  • Replaying a run
  • Exporting a model as one mesh
  • Checking a run is healthy
  • Getting numbers out of a run
  • Rendering a picture
  • From scenario-execution
  • ROS 2 bridge
• Interfaces
  • The world YAML
  • Overriding the world
  • Selecting the world itself
  • Adding ROS transport
  • Choosing a GL backend
  • Listing what a world is made of
  • Listing what a world provides
  • Extending another world
  • Drawing on a render (roqsim.render_overlays)
  • The plugin lifecycle
  • SimContext
  • Switching an arm between controllers
  • Declaring a robot interface (endpoints)
  • simulation_interfaces services (ROS 2)
• Available plugins
  • ROS 2 bridge (roqsim_ros_bridge)
  • Transport plugins and the scene-only consumers
  • Model plugin manifests
  • Selecting a policy
  • Navigation: a mover the simulator drives itself
  • Navigation: detecting a collision
  • What a robot carries
  • A range sensor that is not a scanner
  • Injecting a physical fault
  • Perception ground truth
  • What a run cost
  • Ground that is not flat
  • Documenting a plugin’s config
  • Declaring a plugin’s config
  • Degrading a sensor mid-run
  • Bases: three geometries, one interface
  • Manipulation: an arm on a linear axis
  • Manipulation: the whole MoveIt configuration
  • Manipulation: the world the arm stands in
  • Manipulation: what a contact task needs
  • Manipulation: what a grasping world needs
  • Manipulation: where a workpiece lives
  • Writing your own
• Models & worlds
  • Asking from a shell (or a container)
  • Models
  • Worlds
• Textures
  • How a texture is referenced
  • Surface properties
  • Floor and wall appearance
  • Adding a texture
  • Catalog
• Sensor coverage
  • Concepts
  • The plugin (world-YAML toggle)
  • The CLI (placement search)
  • Adding a sensor the tool doesn’t know
  • Visualising a sensor’s FOV directly
  • A sensor never occludes itself
• Scene builder (human 2D floorplan + 3D review)
  • Install and register
  • Inputs — the same as roqsim
  • The review_scene_by_human tool
  • CLI (debugging)
  • The sketch_floorplan_by_human tool
  • The render_scene tool
  • Internals
  • Roadmap
  • The generic image tool (mcp-media-review)
• nav2 example
  • What it starts
  • Run it
  • The Depot world with AMCL (Gazebo-compatible)
  • The goal-reaching test
• The Create 3 / TurtleBot 4 stack
  • Run it
  • How it is layered
  • What is the same, and what is not
  • On the real robot
  • Varying it in a campaign
• ground truth
  • Ground-truth topic namespace (ros2_bridge gt:)
  • Ground-truth base pose (ground_truth_pose plugin)

Internals & development

• Developer guide
  • Architecture & porting playbook
  • Repository layout
  • Golden rules
  • Developer workflow
  • Adding a tool
  • Sensor coverage (analysis layer)
• Architecture & porting playbook
  • 1. Overview & goals
  • 2. Lifecycle reference
  • 3. API contracts
  • 4. Config & registry
  • 5. Plugin-type catalog
  • 6. Porting playbook
  • 7. Concurrency & threading model
  • 8. Rendering
  • 9. Sensor noise
  • 10. Synchronous / lockstep mode [planned — seams exist, behaviour inert]
  • 11. Performance & benchmarking
  • 12. Conventions
  • 13. Robot interface & transport bridges
  • 14. Glossary & FAQ
• Profiling & performance debugging
  • Built-in per-hook profiler
  • Load-phase profiling
  • Measuring end-to-end RTF (full ROS stack)
  • Thread/wall attribution with py-spy
  • The GIL, and a trap when testing threaded scaling
• Future work
  • Off-thread (asynchronous) camera rendering
  • Per-tick memoisation of lazy endpoint reads
  • Exporting a model as CAD geometry (STEP)