📚 Example Programs#

Tip

For models and code, see the MotrixSim Docs repository.

Before running the examples, please refer to 🛠️ Environment Setup to complete the environment setup.

We provide a series of example programs to help you master the use of MotrixSim from scratch.

On all platforms (Linux, Windows, MacOS), you can run any example of interest with:

uv run examples/{category}/{example_name}.py

Note

Special note for MacOS (aarch64-apple-darwin) platform:

If the example uses 🎨 Renderer, use:

uv run mxpython examples/{category}/{example_name}.py

If the example does not use RenderApp (physics simulation only), use uv run which is consistent with other platforms

Most examples requiring visual rendering (such as robotic arm control, robot locomotion, etc.) use RenderApp and need uv run mxpython.

Getting Started#

Preview	File	Description
	`empty.py`	Create an empty scene, equivalent to a Hello World example.
	`falling_ball.py`	A ball falls under gravity, demonstrating how to create a `model` and `data`.
	`load_from_str.py`	Load an MJCF model from a string, demonstrating how to create a scene directly from an XML string.
	`slope.py`	Simulation of a block rolling down a slope.

Physics#

Preview	File	Description
	`actuator.py`	Retrieve and configure `actuator` parameters.
	`body.py`	Usage of `body`-related APIs; here, `body` specifically refers to the root world body.
	`joint.py`	Usage of `joint`-related APIs, including reading and writing `dof_position` and `dof_velocity`.
	`link.py`	Usage of `link`-related APIs.
	`model.py`	Usage of `model`-related APIs, including multi-instance scenarios for a single model.
	`options.py`	Configure simulator parameters using `options`.
	`site_and_sensor.py`	Usage of `site` and `sensor`-related APIs.
	`friction.py`	Scene demonstrating friction configuration.
	`geom.py`	Usage of geometry-related APIs, showing how to access and query geometry position, velocity, and other information.
	`hfield.py`	Usage of height field APIs, demonstrating how to access terrain height data and perform statistical analysis.
	`combine_msd.py`	Combine multiple MSD models, demonstrating how to use the `Scene.attach()` method to attach multiple models together, supporting transforms and namespace prefixes.
	`adhesion.py`	A robotic arm with adhesion actuator.
	`external_force.py`	External force and torque application example, demonstrating how to use `add_external_force` and `add_external_torque` APIs to apply forces and torques to links in local coordinate frames. Includes three phases: center-of-mass thrust, Z-axis torque, and offset-point force.

Control#

Preview	File	Description
	`keyboard_car.py`	Control a cart using the keyboard; demonstrates keyboard event handling. Use W to move forward, S to move backward. Turning: A to turn left, D to turn right.
	`mouse_click.py`	Move a ball by clicking on the ground with the mouse; demonstrates mouse event handling.
	`ik.py`	Demonstrates how to use the built-in IK module in MotrixSim for inverse kinematics solving.
	`local_arm.py`	A robotic arm composed of simple geometries and `joints`.
	`robotic_arm.py`	The Stanford robotic arm uses a sequence of movement commands to pick and place a ball.
	`go1.py`	Random motion of the Go1 quadruped robot, demonstrating how to integrate a neural network and use `.onnx` files.
	`robot_locomotion.py`	Go2 quadruped keyboard control example: arrow keys and WASD control walking and turning. Use `uv run examples/control/robot_locomotion.py --robot go2` to run.
	`robot_locomotion.py`	G1 humanoid keyboard control example: arrow keys and WASD control walking and turning. Use `uv run examples/control/robot_locomotion.py --robot g1` to run.
	`g1_motion_tracking.py`	G1 humanoid motion-tracking playback example. It loads the bundled reference motion and ONNX actor for single-environment playback. Use `uv run examples/control/g1_motion_tracking.py` to run.
	`robot_locomotion.py`	G1 humanoid keyboard control example in an indoor parlour scene: arrow keys and WASD control walking and turning. Use `uv run examples/control/robot_locomotion.py --robot g1 --scene parlour` to run.
	`rm65_open_cabinet.py`	RM65 cabinet-opening policy example using an ONNX policy. Demo video. Press `R` to reset and `ESC` to exit.
	`shadow_hand_repose.py`	Shadow Hand cube reorientation policy example using an ONNX policy. Demo video. Press `R` to reset and `ESC` to exit.
	`osc.py`	Operational Space Control (OSC) interactive example, demonstrating how to use `OscSolver` with `IkChain` to control end-effector position and orientation via computed torques. Arrow keys and WASD to move target, Q/E to rotate, R to reset.
	`go1_multi_task.py`	Go1 quadruped multi-task policy example, supporting walking, handstand, footstand, and getup recovery mode switching. WASD to move, U for handstand, I for footstand, O for recovery, P to reset.

Parallel Simulation#

Preview	File	Description
	`parallelsim.py`	Multi-environment parallel simulation.

Randomization#

Preview	File	Description
	`mass.py`	Randomize rigid body mass from 0.1 kg to 500 kg across 16 parallel instances, demonstrating how mass affects falling dynamics.
	`friction.py`	Randomize per-geom friction coefficients from 0.01 to 2.0, demonstrating the transition from sliding to static grip on a 30° ramp.
	`armature.py`	Randomize joint armature (virtual rotor inertia), showing how armature affects the natural frequency of a torsion-spring-driven arm.
	`frictionloss.py`	Randomize joint frictionloss (Coulomb dry friction) from 0 to 200 N·m, demonstrating how friction can freeze a pendulum at different angles.
	`com.py`	Randomize center of mass position within the cylinder cross-section, showing how COM offset affects rolling behavior.
	`actuator_kp_kd.py`	Randomize position actuator PD gains in a 4×4 grid with kp (10–120 N·m/rad) varying by row and kd (1–20 N·m·s/rad) by column, visualizing PD servo dynamics.
	`geom_size.py`	Randomize collision and visual sizes of five geometry types (sphere, capsule, box, cylinder, ellipsoid), showing how size affects settling height and contact behavior.
	`gravity_direction.py`	Randomize gravity direction by assigning each of 16 parallel instances a different gravity vector inside a transparent box, demonstrating per-instance gravity override with `set_gravity_override`.

Viewer#

Preview	File	Description
	`camera_control.py`	Camera control API usage, showing how to enable/disable system and scene cameras, and get camera poses.
	`camera_viewport.py`	Camera viewport widgets displaying different camera feeds with interactive controls for switching cameras, resizing, and repositioning viewports.
	`custom_ui.py`	Usage of custom UI elements, demonstrating how to add buttons and switches for interaction.
	`gizmos.py`	Usage of the 3D gizmo drawing system, demonstrating how to draw spheres, cubes, capsules, arrows, grids, and other visualization helpers.
	`image_widget.py`	Image widget system usage, demonstrating how to display and interactively manipulate multiple image panels.
	`render_settings.py`	Rendering settings configuration example, demonstrating how to use `RenderSettings` to configure shadows, screen-space ambient occlusion (SSAO), and other rendering effects.
	`partial_rendering.py`	Selective rendering control in batch rendering, showing how to dynamically control visibility of specific scenes in multi-environment parallel simulation. Press A/D keys to toggle partial scene visibility, Q/E keys for all scenes.
	`share_lights_between_envs.py`	Light sharing optimization between environments, demonstrating how to share lights in parallel simulation to improve performance. Use `--share_lights=False` parameter to disable light sharing.
	`ssgi.py`	Screen Space Global Illumination (SSGI) rendering example, demonstrating how to use `RenderSettings` to enable high-quality SSGI rendering effects.
	`headless.py`	Headless rendering example, demonstrating how to use `RenderApp(headless=True)` to run simulation without a window and batch-capture images via the system camera. Use `--no-wait` to switch between sync and async capture modes.

Benchmark#

Preview	File	Description
	`gyroscope_mx.py`	Physical simulation of a gyroscope.
	`gyroscope_zero_gravity_mx.py`	Gyroscope in a zero-gravity environment, demonstrating conservation of angular momentum.
	`newton_cradle_mx.py`	Physical simulation of Newton’s cradle.
	`shake_test_mx.py`	Grasping and shaking test for the Franka Panda robotic arm, demonstrating how the arm grasps objects and maintains stability. Supports `--object` parameter to select object type (cube/ball/bottle), `--shake` parameter to control shaking, and `--record` parameter to record video.