Implementation:Google deepmind Mujoco MJWarp Collision Primitive

Knowledge Sources	Google_deepmind_Mujoco MJWarp Documentation
Domains	Physics_Simulation, GPU_Computing, NVIDIA_Warp
Last Updated	2026-02-15 04:00 GMT

Overview

MJWarp Collision Primitive implements narrowphase collision detection for primitive geometry pairs using analytical contact formulas on the GPU.

Description

This module provides GPU-accelerated narrowphase collision detection for simple geometry pairs that have closed-form analytical solutions (e.g., plane-sphere, sphere-sphere, capsule-capsule, box-box). It defines the Geom Warp struct used across collision modules and provides wrapper functions for each primitive collision pair that handle contact parameter computation and result writing. The module imports core collision functions from collision_primitive_core and wraps them with contact output logic.

Usage

Invoked by the collision driver when geometry pairs are classified as PRIMITIVE collision type. Handles pairs such as plane-sphere, sphere-capsule, capsule-capsule, plane-box, sphere-box, capsule-box, and box-box.

Code Reference

Source Location

• Repository: Google_deepmind_Mujoco
• File: mjx/mujoco/mjx/third_party/mujoco_warp/_src/collision_primitive.py
• Lines: 1-1809

Key Functions

# Warp struct for geometry data
@wp.struct
class Geom:
    pos: wp.vec3; rot: wp.mat33; normal: wp.vec3; size: wp.vec3
    margin: float; vertadr: int; vertnum: int; ...

# Primary entry point
def primitive_narrowphase(m: Model, d: Data, ctx: CollisionContext,
                          collision_table: list[tuple[GeomType, GeomType]])

# Shared utility functions
def geom_collision_pair(...)   # Load geom pair data from arrays
def write_contact(...)         # Write contact result to output arrays
def contact_params(...)        # Compute contact parameters (friction, etc.)

# Primitive collision wrappers
def plane_sphere_wrapper(...)
def sphere_sphere_wrapper(...)
def sphere_capsule_wrapper(...)
def capsule_capsule_wrapper(...)
def plane_capsule_wrapper(...)
def plane_box_wrapper(...)
def sphere_box_wrapper(...)
def capsule_box_wrapper(...)
def box_box_wrapper(...)

Import

from mujoco.mjx.third_party.mujoco_warp._src.collision_primitive import primitive_narrowphase
from mujoco.mjx.third_party.mujoco_warp._src.collision_primitive import Geom
from mujoco.mjx.third_party.mujoco_warp._src.collision_primitive import write_contact

I/O Contract

Inputs

Name	Type	Required	Description
m	Model	Yes	Warp model with geometry types, sizes, and material properties
d	Data	Yes	Warp simulation data with geom transforms
ctx	CollisionContext	Yes	Collision context with broadphase candidate pairs
collision_table	list[tuple[GeomType, GeomType]]	Yes	Geometry type pairs to process as primitive collisions

Outputs

Name	Type	Description
d.contact	Contact	Contact points with positions, frames, depths, and friction parameters
d.nacon	wp.array	Updated count of active contacts

Related Pages

• Environment:Google_deepmind_Mujoco_MJX_Warp_CUDA_Environment