Actions

Every robot has a fixed library of named base actions. These are the building blocks for ActionCall, Sim.run, CLI group actions, and policy outputs.

How an action becomes motion

An ActionSpec is either gait-based (a continuous locomotion command run by the gait engine) or phase-based (a timed sequence of joint targets with per-joint PD gains and motor schedules). The simulator dispatches on spec.is_gait / spec.is_phase.

Look up actions

import cadenza_lab as cadenza

cadenza.list_actions("go1")          # -> list[str] of action names
spec = cadenza.get_action("go1", "walk_forward")   # -> ActionSpec
lib  = cadenza.get_library("go1")    # -> ActionLibrary

list_actions(robot) -> list[str]
get_action(robot, name) -> ActionSpec
get_library(robot) -> ActionLibrary

`ActionLibrary`

lib = cadenza.get_library("g1")
lib.robot              # "g1"
lib.list_actions()     # action names
lib.get("walk_forward")    # -> ActionSpec
lib.describe()         # human-readable summary of the library

`ActionSpec`

The full description of one action. Key fields:

Field	Description
`name`, `description`, `robot`	Identity.
`phases`	Tuple of `ActionPhase` for phase-based actions.
`gait`	A `GaitAction` for gait-based actions (else `None`).
`distance_m`, `rotation_rad`, `duration_s`, `speed_ms`	Action defaults.
`max_pitch_rad`, `max_roll_rad`	Abort thresholds. Exceed them and the action fails.
`hip_range`, `thigh_range`, `knee_range`	Joint limits used by `clamp_joints`.

spec = cadenza.get_action("go1", "walk_forward")
spec.is_gait          # True
spec.is_phase         # False
spec.total_duration() # seconds

jump = cadenza.get_action("go1", "jump")
jump.is_phase         # True
[p.name for p in jump.phases]   # ['crouch', 'hold_crouch', 'launch', ...]

Supporting dataclasses: GaitAction (gait command), ActionPhase (one timed phase), JointTarget (12/16-DOF targets + kp/kd), and MotorSchedule (per-joint velocity/torque caps and delays).

Action catalog

go1 (quadruped, 21)
g1 (humanoid, 20)
arm (6-axis, 6)

stand            stand_up         sit              lie_down
jump             walk_forward     walk_backward    trot_forward
crawl_forward    turn_left        turn_right       precision_turn_left
precision_turn_right             climb_step        side_step_left
side_step_right  pace_forward     bound_forward    rear_up
shake_hand       rear_kick

stand            stand_up         sit              lie_down
crouch           deep_crouch      lift_left_hand   lift_right_hand
walk_forward     walk_backward    trot_forward     crawl_forward
turn_left        turn_right       side_step_left   side_step_right
jump             shake_hand       rear_kick        rear_up

home             move_to          open_gripper
close_gripper    pick             place

The arm’s library is Cartesian, not gait/phase: move_to, pick, and place take an (x, y, z) target instead of a GaitAction or ActionPhase schedule, and cadenza.get_library("arm") returns an ArmActionLibrary (it duck-types list_actions / get / describe). See the Arm controller.

Action availability is per-robot, so always confirm with cadenza.list_actions(robot) rather than assuming a name exists on both robots.

Parameterize with `ActionCall`

Wrap an action name with parameters to execute it (see Gym adapter):

from cadenza_lab import ActionCall

ActionCall("walk_forward", distance_m=1.0)
ActionCall("turn_left", rotation_rad=1.57)
ActionCall("trot_forward", distance_m=2.0, speed=1.2)

Natural-language parsing

CommandParser turns a natural-language command into a list[ActionCall], the same parser the one-liner cadenza.run(...) and the CLI’s scripted driver use.

The parser lives at cadenza.parser (the real module), not cadenza_lab.parser. Import it as shown below.

from cadenza.parser import CommandParser

calls = CommandParser("go1").parse("walk forward 2 meters then turn left")
# [ActionCall(walk_forward, 2.0m), ActionCall(turn_left)]

Demo: explore the library

"""demo_actions.py: inspect the action library (headless, no viewer)."""
import cadenza_lab as cadenza
from cadenza.parser import CommandParser

for robot in ("go1", "g1"):
    names = cadenza.list_actions(robot)
    print(f"\n{robot}: {len(names)} actions")
    for name in names:
        spec = cadenza.get_action(robot, name)
        kind = "gait " if spec.is_gait else "phase"
        print(f"  {kind}  {name:<22} {spec.description}")

# Natural language → actions
calls = CommandParser("go1").parse("trot forward 3 meters then turn right then sit")
print("\nparsed:", [c.action_name for c in calls])

python demo_actions.py

Get started

Features

Tutorial

How an action becomes motion

Look up actions

`ActionLibrary`

`ActionSpec`

Action catalog

Parameterize with `ActionCall`

Natural-language parsing

Demo: explore the library

​How an action becomes motion

​Look up actions

​ActionLibrary

​ActionSpec

​Action catalog

​Parameterize with ActionCall

​Natural-language parsing

​Demo: explore the library

How an action becomes motion

Look up actions

`ActionLibrary`

`ActionSpec`

Action catalog

Parameterize with `ActionCall`

Natural-language parsing

Demo: explore the library