Protocol Endpoints (generated)

Every request is a length-prefixed msgpack dict with a "cmd" key (see Protocol & Wire Format for framing and worked examples). This page lists every command the server understands.

Auto-generated by docs/generate_protocol_endpoints_md.py from src/robosim/protocol.json (core commands, parsed with microspec) and the live plugin .endpoints (plugin commands). Do not edit by hand — add the endpoint to the protocol / plugin and re-run the generator. Prose descriptions live in the schema itself (description on each protocol.json endpoint / plugin Endpoint).

Input / Output are the command's keys and their types (name: type). type notation: float32[6] = a length-6 float array, [N,6] = an N-by-6 array (variable first dim), ∈[lo,hi] = value range, (a|b|c) = allowed enum values, {k:type} = a nested dict. — = no keys.

Plugins are chosen at startup with --plugins (default: manual_move); several can run at once. Some commands behave differently while a trajectory mission is running — see the note on the Plugins page.

Interpolated variables

Some fields show a ${name} placeholder — a value the server resolves from its config at startup (so the docs stay config-independent):

  • ${components} — the registered component names — the str_enum of components an entity may carry.
  • ${max_robot_ix} — n_robots - 1 — the highest valid robot index (set by --n_robots, default 2).

    Core protocol

Command Input Output Description
help —
supported_commands: str[N]
 List available command names (core + enabled plugins)
connect —
status: str_enum (connected)
robot_ix: int32 ∈[0,${max_robot_ix}]
eid: int32
 Promote a socket to a robot-controlling channel; the reply carries the assigned robot index and entity id
map_load — — Not implemented — raises server-side (tasks 158/163)
sim_get_info —
control_loop_rate_hz: int32
physics_tick_s: dict {window:int32, p50:float32}
render_tick_s: dict {window:int32, p50:float32}
 Control-loop rate plus rolling physics/render tick timings (each {window, p50})
sim_get_state —
state: dict
 Full scene state (world + cameras + plugins) — identical shape to an on-disk save
sim_load_state
state: dict
status: str_enum (Loaded state)
 Replace the scene with a state dict (no disk roundtrip)
sim_save_state —
status: str
 Write the current scene to resources/state.json on the server host
sim_reset —
status: str_enum (Loaded state)
 Restore the initial scene captured at startup
sim_set_camera
type: str_enum (world | topdown | fpv)
id: int32 ∈[0,${max_robot_ix}]
status: str
 Switch the active camera; type is world/topdown/fpv and id picks the FPV robot
sim_set_wireframe_mode
value: bool
status: str
 Toggle wireframe rendering
sim_set_collision_render_mode
value: bool
status: str
 Render colliders (shapes) instead of meshes
sim_set_collision_cell_size
value: float32[3] ∈[0.1,100]
status: str
 Set the broadphase grid cell size (a 3-vector)
sim_display_uav_trace
value: bool
status: str
 Toggle drawing the robots' position traces (clears existing traces on toggle)
robot_get_state
robot_ix: int32 ∈[0,${max_robot_ix}]
robot: dict {components:str[N], data:dict, connected:bool}
 Robot entity dump: components + serializable data + connected
robot_get_state_with_camera
robot_ix: int32 ∈[0,${max_robot_ix}]
robot: dict {components:str[N], data:dict, connected:bool}
fpv_compressed: bytes
fpv_shape: int32[3]
fpv_frame_id: int32
 Robot dump plus a zlib-compressed FPV frame. Errors if the robot is not connected
entity_spawn
components: str_enum[N] (${components})
data: dict
status: str
entity_id: int32
 Create an entity from a serializable (components, data) recipe. See documentation for examples
entity_destroy
entity_id: int32
status: str
 Destroy an entity given its entity id
entity_add_component
entity_id: int32
component: str_enum (${components})
data: dict
status: str
 Add a component to a live entity with optional initial data; rejected if it already has it
entity_remove_component
entity_id: int32
component: str_enum (${components})
status: str
 Removes a component from a live entity. Rejected if the component does not exist
entity_set_data
entity_id: int32
component: str_enum (${components})
data: dict
status: str
 Sets the data of a field of an entity's component, given the entity id and the component

ManualMovePlugin (--plugins manual_move)

Command Input Output Description
move
control_input: float32[6] ∈[-1,1]
move_applied: dict
 Apply one control input to the connected robot.

TrajectoryMissionPlugin (--plugins trajectory_mission)

Command Input Output Description
mission_add_via_point
position: float32[3] ∈[-1000,1000]
status: str
 Record robot 0's current pose as a via-point.
mission_get_state —
status: dict
 Mission phase, progress, or final error.
mission_start
trajectory: float32[N,6] (min_len 2)
status: str
 Start the mission with the supplied trajectory (N×6).
mission_clear_via_points —
status: str
 Drop all recorded via-points.

RacePlugin (--plugins race)

Command Input Output Description
race_start —
status: str
 Start the race (one-shot, no restart).
race_status —
status: dict
 Race state: flag positions, per-robot next-flag index, start/end timestamps, winner.

For the response envelope (timestamps, the "error" key) and which commands answer straight from the TCP thread, see Protocol & Wire Format. See Plugins for how a plugin declares the commands it owns and how mission state affects them.