From 6a7a7230931e5cfd664af7cf6cc2e8d238f46858 Mon Sep 17 00:00:00 2001
From: Taylor Howell <taylorhowell@google.com>
Date: Thu, 30 Jul 2026 02:59:22 -0700
Subject: [PATCH] MuJoCo Warp documentation: Per-world assets

PiperOrigin-RevId: 956399999
Change-Id: I8d951e5e52e16442325c66cc33ac693bf68939e3
---
 doc/mjwarp/index.rst | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/doc/mjwarp/index.rst b/doc/mjwarp/index.rst
index 0e3d4877..e76fae6f 100644
--- a/doc/mjwarp/index.rst
+++ b/doc/mjwarp/index.rst
@@ -501,19 +501,22 @@ Certain fields are safe to modify directly without compilation, enabling on-devi
 `GitHub issue 893 <https://github.com/google-deepmind/mujoco_warp/issues/893>`__ tracks adding on-device updates for a
 subset of fields.
 
-Per-world meshes
+Per-world assets
 ----------------
 
-Per-world meshes enable heterogeneous worlds where different worlds simulate different meshes. The workflow
-is:
+Per-world assets enable heterogeneous worlds where different worlds simulate different
+`assets <https://mujoco.readthedocs.io/en/latest/XMLreference.html#asset>`__ including meshes, height fields, materials,
+and textures. The general workflow is:
 
-1. Create an :ref:`mjSpec` with **all** mesh assets and the **maximum** number of geom slots needed across variants.
+1. Create an :ref:`mjSpec` with **all** assets.
 2. Compile each variant by mutating the spec and calling ``spec.compile()``.
 3. Compile a **base** model and create :class:`mjw.Model <mujoco_warp.Model>` from it.
 4. Override the relevant :class:`mjw.Model <mujoco_warp.Model>` fields with per-world arrays built from the compiled
    variants.
 
-**Example 1 — Geom-level** randomization (1 body, 1 geom, 2 mesh assets):
+.. rubric:: Per-world meshes
+
+**Example 1 — Per-world meshes: Geom-level** randomization (1 body, 1 geom, 2 mesh assets):
 
 The base scene includes all mesh assets. The geom references one mesh (``mesh_a``); a second mesh
 (``mesh_b``) is available for per-world substitution.
@@ -612,7 +615,7 @@ The base scene includes all mesh assets. The geom references one mesh (``mesh_a`
   m.body_ipos = wp.array(body_ipos, dtype=wp.vec3)
   m.body_iquat = wp.array(body_iquat, dtype=wp.quat)
 
-**Example 2 — Body-level** randomization (1 body, 1 or 2 geoms, 3 mesh assets):
+**Example 2 — Per-world meshes: Body-level** randomization (1 body, 1 or 2 geoms, 3 mesh assets):
 
 .. admonition:: Maximum geom count
    :class: important
@@ -784,6 +787,14 @@ The base scene includes all mesh assets. The geom references one mesh (``mesh_a`
      - ``wp.quat``
      - ``(nworld, nbody)``
 
+Per-world height fields, materials, and textures can be similarly formulated.
+
+.. admonition:: Per-world asset dependent field construction
+  :class: note
+
+  MJWarp enables per-world asset functionality but does not provide utilities for construction of dependent per-world
+  field variants. Construction is left to the user or environment authoring frameworks.
+
 Batch Rendering
 ===============