Import upstream snapshot c19f713c415a699a79d71cd96aa13c3104a05047

Upstream: https://github.com/michaelgillett/mjlab
Upstream-Commit: c19f713c415a699a79d71cd96aa13c3104a05047
Upstream-Branch: main

docs/source/commands.rst

@@ -0,0 +1,123 @@
+.. _commands:
+
+Commands
+========
+
+Commands specify what the policy should achieve at each moment: a target
+velocity, a reference trajectory, a goal position. The command manager
+generates these signals, resamples them at configurable intervals, and
+passes them to the policy through the observation system.
+
+
+Registration
+------------
+
+Commands are registered in ``ManagerBasedRlEnvCfg`` as a dictionary
+mapping string names to ``CommandTermCfg`` instances. Unlike the
+function-based terms used by other managers, every command term is a
+class that inherits from ``CommandTerm``.
+
+The ``resampling_time_range`` field controls how often the command
+changes. After each resample the term draws a new timer value uniformly
+from the given ``(min, max)`` range in seconds. Commands are also
+resampled unconditionally on every episode reset.
+
+.. code-block:: python
+
+    commands = {
+        "twist": UniformVelocityCommandCfg(
+            entity_name="robot",
+            resampling_time_range=(3.0, 8.0),
+            ranges=UniformVelocityCommandCfg.Ranges(
+                lin_vel_x=(-1.0, 1.0),
+                lin_vel_y=(-1.0, 1.0),
+                ang_vel_z=(-0.5, 0.5),
+            ),
+        ),
+    }
+
+The ``generated_commands`` observation function reads the current
+command tensor by name and passes it to the policy:
+
+.. code-block:: python
+
+    ObservationTermCfg(
+        func=mdp.generated_commands,
+        params={"command_name": "twist"},
+    )
+
+If the environment has no commands, the manager no-ops all operations
+and returns empty tensors. There is no special handling required.
+
+
+Included command terms
+----------------------
+
+Each task ships with its own command terms tailored to its objective.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 72
+
+   * - Term
+     - Description
+   * - ``UniformVelocityCommand``
+     - Generates planar velocity commands ``[v_x, v_y, omega_z]``
+       sampled uniformly from configurable ranges. Supports a standing
+       mode (fraction of environments receive zero velocity) and a
+       heading mode (yaw rate replaced by a proportional controller
+       tracking a sampled heading angle). Used by the velocity task.
+   * - ``LiftingCommand``
+     - Generates a 3D target position for a manipulated object.
+       Supports fixed and dynamic difficulty modes. Tracks metrics
+       including position error and episode success rate. Used by the
+       manipulation task.
+   * - ``MotionCommand``
+     - Streams reference joint positions, velocities, and body poses
+       from a pre-recorded ``.npz`` motion clip. Supports three
+       start-frame sampling modes: ``"start"`` (always frame 0),
+       ``"uniform"`` (random), and ``"adaptive"`` (biased toward
+       difficult regions). At reset the robot is initialized from the
+       sampled frame with optional perturbations. Used by the tracking
+       task.
+
+Each term can render debug visualizations in the interactive viewer
+when ``debug_vis=True`` is set in the configuration. The image below
+shows the ghost visualization from ``MotionCommand``, which renders a
+translucent copy of the robot at the reference pose alongside the
+actual robot.
+
+.. figure:: _static/ghost_visualization.png
+   :align: center
+   :width: 100%
+
+   Viser visualization of the commanded reference motion for the G1 tracking task.
+
+
+Writing custom command terms
+-----------------------------
+
+A custom command term is a class inheriting from ``CommandTerm`` paired
+with a configuration dataclass inheriting from ``CommandTermCfg``. The
+term must implement four methods: ``_resample_command(env_ids)`` to
+sample new goals, ``_update_command(env_ids)`` for per-step updates,
+``_update_metrics()`` for logging, and a ``command`` property returning
+the current goal tensor. The base class manages the resampling timer
+and reset logic automatically.
+
+``_update_command`` is called in two situations. On every environment
+step it receives ``env_ids=None``, meaning update all environments.
+After a reset it is called again with the ids of the environments that
+were just reset, so their command state is brought up to date before
+observations are computed.
+
+The distinction matters when your update advances state, such as
+incrementing a frame index into a reference motion. Apply such advances
+only to ``env_ids`` (all environments when ``None``); otherwise
+resetting a few environments would also advance every other one. Updates
+that simply recompute values from the current simulation state, like a
+heading error, give the same result no matter how often they run and can
+safely ignore ``env_ids``.
+
+The configuration must implement a ``build(env)`` method that
+constructs the paired term instance.