Telemetry

What a Gym.step(), Gym.reset() or Gym.restore() answers.

Choosing groups

When you connect, you name the groups every sample carries, or TelemetryGroup.ALL for every one of them. Each group is an attribute of Telemetry, and a group you did not choose is None. The lidar group is the scan of the gym’s Lidar, so it is there exactly when you give one.

Group	Attribute	View	Holds
TelemetryGroup.RACE	t.race	Race	race time, flags, lap, checkpoints taken
TelemetryGroup.VEHICLE	t.vehicle	Vehicle	position, orientation, velocities
TelemetryGroup.DRIVETRAIN	t.drivetrain	Drivetrain	gear, shift state, inputs in force, drive command
TelemetryGroup.WHEELS	t.wheels	Wheels	contact, surface, suspension, icing per wheel
TelemetryGroup.EFFECTS	t.effects	Effects	the gameplay effects in force
TelemetryGroup.SHAPE	t.shape	tuple of Ellipsoid	the car’s collision shape, in world space
TelemetryGroup.RUNTIME	t.runtime	Runtime	every scalar of the game’s vehicle state
TelemetryGroup.LIDAR	t.lidar	LidarScan	what the gym’s Lidar rays saw

A TelemetryGroup value is a set of groups: combine them with | when opening a gym, and test one with in.

groups = TelemetryGroup.RACE | TelemetryGroup.VEHICLE | TelemetryGroup.WHEELS
TelemetryGroup.WHEELS in groups

class TelemetryGroup(value)

NONE = 0

RACE = 1

VEHICLE = 2

DRIVETRAIN = 4

WHEELS = 8

EFFECTS = 16

SHAPE = 32

RUNTIME = 64

LIDAR = 128

ALL = 255

Types and units

Units follow the game: metres, metres per second, radians per second, milliseconds, ticks of 10 ms. Coordinates are world space unless a property says otherwise. A scalar property is a plain int, float or bool; a vector is a NumPy array. The wheel and lidar views give their properties an axis (4 wheels, R rays) before a vector’s components.

type Vec3

A numpy.ndarray of float32 whose last axis is (x, y, z): shape (3,).

type Quat

A numpy.ndarray of float32 whose last axis is a unit quaternion (x, y, z, w): shape (4,).

type FloatArray

A numpy.ndarray of float32: a scalar, or the axis the property documents.

type IntArray

A numpy.ndarray of integers: a scalar, or the axis the property documents.

type BoolArray

A numpy.ndarray of bool: a scalar, or the axis the property documents.

The telemetry object

class Telemetry

What a step, a reset or a restore answered: the state at one race tick.

The group attributes (t.race, t.vehicle, …) are the groups the gym was opened with and None for the others. A scalar property is a plain int, float or bool; a vector one is a (3,) array.

race_tick: int

The race tick of the state.

finished: bool

Whether the race is finished, whatever groups were chosen.

property race: Race | None

The race group, or None if it was not chosen.

property vehicle: Vehicle | None

The vehicle group, or None if it was not chosen.

property drivetrain: Drivetrain | None

The drivetrain group, or None if it was not chosen.

property wheels: Wheels | None

The wheels group, or None if it was not chosen.

property effects: Effects | None

The effects group, or None if it was not chosen.

property shape: tuple[Ellipsoid, ...] | None

The car’s collision ellipsoids, however many the car has. None if the shape group was not chosen.

property runtime: Runtime | None

The runtime group, or None if it was not chosen.

property lidar: LidarScan | None

The lidar scan, or None if the gym has no lidar.

Race

class Race

Race time, flags, lap and the checkpoints taken. t.race when TelemetryGroup.RACE was chosen.

property finished: bool

The race is finished at the sample.

property entered_off_zone: bool

The car has left the playable area at least once since the reset.

Race.race_tick: int

The race tick of the sample. A scalar.

Race.race_time_ms: int

Race time, in ms. A scalar.

Race.lap_time_ms: int

Time in the current lap, in ms. A scalar.

Race.flags: int

Bits of RaceFlag; finished and entered_off_zone read them. A scalar.

Race.lap: int

Laps completed. A scalar.

Race.checkpoints_taken: int

Checkpoints passed so far, over every lap; Gym.checkpoints() says which and when. A scalar.

class RaceFlag(value)

NONE = 0

FINISHED = 1

ENTERED_OFF_ZONE = 2

Vehicle

class Vehicle

The car’s pose and velocities in world space. t.vehicle when TelemetryGroup.VEHICLE was chosen.

property speed: float

The length of the linear velocity, in m/s.

Vehicle.position: Vec3

World position, in m. Shape (3,).

Vehicle.rotation: Quat

World orientation. Shape (4,).

Vehicle.linear_velocity: Vec3

World velocity, in m/s. Shape (3,).

Vehicle.angular_velocity: Vec3

World angular velocity, in rad/s. Shape (3,).

Drivetrain

class Drivetrain

Gear, shift state, the inputs in force and the drive command. t.drivetrain when TelemetryGroup.DRIVETRAIN was chosen.

Drivetrain.gear: int

The gear; 0 is reverse. A scalar.

Drivetrain.shift_state: int

A GearShiftState value. A scalar.

Drivetrain.steer: int

Steering in force, -127 to 127. A scalar.

Drivetrain.held: int

Bits of HeldInput: the inputs in force. A scalar.

Drivetrain.longitudinal_command: float

The gearbox’s drive command. A scalar.

Drivetrain.longitudinal_target: float

The drive command’s target. A scalar.

class GearShiftState(value)

TAKE_OFF = 0

TAKE_OFF_SETTLING = 1

SHIFTING = 2

TRACKING = 3

REVERSE_TAKE_OFF = 4

BURNOUT_OVERRIDE = 5

class HeldInput(value)

NONE = 0

ACCELERATE = 1

BRAKE = 2

Wheels

class Wheels

The four wheels, with a trailing axis of four in the order front-left, front-right, rear-left, rear-right. t.wheels when TelemetryGroup.WHEELS was chosen.

property contact: BoolArray

Each wheel touches the ground. Shape (4,).

Wheels.flags: IntArray

Bits of WheelFlag; contact reads them. Shape (4,).

Wheels.material_id: IntArray

The surface material under the wheel. Shape (4,).

Wheels.compression: FloatArray

Suspension compression. Shape (4,).

Wheels.icing_percent: FloatArray

Icing of the wheel, in percent. Shape (4,).

Wheels.angular_velocity: FloatArray

Wheel spin, in rad/s. Shape (4,).

class WheelFlag(value)

NONE = 0

CONTACT = 1

Effects

class Effects

The gameplay effects in force, one bit per Effect. t.effects when TelemetryGroup.EFFECTS was chosen.

has(effect: Effect) → bool

Whether effect is in force at the sample.

Effects.active: int

One bit per Effect; has() reads them. A scalar.

class Effect(value)

REACTOR_BOOST_UP = 0

REACTOR_BOOST_DOWN = 1

TURBO = 2

SUPER_TURBO = 3

ENGINE_OFF = 4

FRAGILE = 5

NO_STEERING = 6

NO_BRAKES = 7

NO_GRIP = 8

SLOW_MOTION = 9

CRUISE_CONTROL = 10

Collision shape

t.shape is a tuple of Ellipsoid, one per sphere or ellipsoid of the car’s collision shape, however many the car has, in world space at the scale the physics uses. The wheel spheres ride the suspension, so the list changes from one state to the next.

class Ellipsoid

One ellipsoid of the car’s collision shape, in world space and at the scale the physics uses. A sphere has three equal radii.

center: Vec3

The centre, in metres. Shape (3,).

rotation: Quat

The orientation. Shape (4,).

radii: Vec3

The three semi-axes, in metres. Shape (3,).

Lidar readings

What the gym’s Lidar saw at the sample, and what Gym.raycast() returns. Configure the rays on the Lidar page.

class LidarScan

What the rays saw, with a trailing axis over the rays in the order they were given. t.lidar when the gym has a Lidar; also what Gym.raycast returns.

property hit: BoolArray

The ray met geometry within range. Where it did not, distance is the range and normal is zero. Shape (R,).

LidarScan.distance: FloatArray

Along the ray, in m; the range when nothing was hit. Shape (R,).

LidarScan.flags: IntArray

Bits of LidarHitFlag; hit reads them. Shape (R,).

LidarScan.material_id: IntArray

The surface material hit, 0 for none. Shape (R,).

LidarScan.point: Vec3

The hit point, in world m. Shape (R, 3).

LidarScan.normal: Vec3

The surface normal at the hit; zero for a miss. Shape (R, 3).

class LidarHitFlag(value)

NONE = 0

HIT = 1

Runtime

class Runtime

Every scalar of the game’s vehicle runtime state, one property per field. t.runtime when TelemetryGroup.RUNTIME was chosen.

Every scalar of the game’s vehicle runtime state and of its four wheel contact states, each a FloatArray, one property per field. The groups above are the curated view; this is the full one, and a field that appears in both holds the same value. Conventions:

• Wheel fields carry a position prefix: fl_, fr_, rl_, rr_.

• A field named *_tick_age is the age of a timestamp in ticks: how long ago the thing happened.

• A flag word is published one column per named bit, 0 or 1 (surface_effect_flags_no_grip).

• Fields prefixed m6_ to m15_ belong to other handling models (TM2 cars, boats) and sit at their reset value for every TM2020 car.

The fields worth sampling for a TM2020 car:

• Water: is_in_water (a point cast hit this step), wetness (0 to 1, rises in water and dries on ground contact; scales brake and lateral limits).

• Grip: surface_grip_scale (the mean over wheels of the icing grip scale: 1 normally, 0.8 on ice or snow above 5 km/h, near 0 under NoGrip), is_any_wheel_on_ice_or_snow, per wheel icing_state (0 none, 1 icing up, 2 thawing), icing_blend, icing_thaw_floor.

• Gates and effects: gate_gameplay_id (the gameplay id of the gate the chassis is in), surface_effect_flags_* (this step’s surface effects: engine off, engine forced on, no brakes, no steering, no grip) and held_surface_effect_flags_* (the same bits held until a reset gate or checkpoint), slow_motion_time_scale, cruise_control_target_meters_per_second, reactor_boost_*, fragile_gate_active, fragile_damage.

• Script coefficients, named as ManiaScript names them: accel_coef, control_coef, gravity_coef, adherence_coef.

• Steering (Stadium car): steering_smoothed, steering_direction (0 neutral, 1 left, 2 right), steering_direction_change_tick_age, steering_direction_change_drive_scale, forward_motion_alignment_scale (1 moving along the heading, 0.2 sliding sideways under throttle).

• Surfaces (Stadium car): all_wheels_on_dirt_target, dirt_axle_force_ramp_*, soft_surface_wheel_count, soft_surface_drive_scale_hold_deadline_tick_age.

• Collisions: has_contact_this_step, wall_hit_damping_start_tick_age, roof_contact_this_step, side_or_roof_contact_this_step, floor_contact_this_step, direction_change_boost_* (a throttle reversal away from a wall below 40 km/h), contact_solver_residual, collision_yaw_rate_*.

• Respawn: respawn_hold_deadline_tick_age, first_step_tick_after_respawn, pose_discontinuity_count (teleports and respawns).

• Per wheel: damper_length (suspension length in metres, smaller is compressed), damper_velocity, wheel_angular_velocity (rad/s), wheel_spin_blend (0 rolls at ground speed, 1 spins with the drive demand), wheel_rotation_radians, wheel_steer_angle_radians, has_ground_contact, had_contact_last_step, is_slipping, surface_material_id, surface_gameplay_id.

All fields

• scene_runtime_id

• collision_item_count

• m6_upright_cos_contact_scale_full

• m6_upright_cos_contact_scale_zero

• m6_upright_cos_wheel_point_full

• m6_upright_cos_wheel_point_zero

• m6_upright_cos_speed_response_full

• wheel_contact_normal_y_ground_threshold

• pending_replay_event_flag

• accel_coef

• action_key_steer_limit

• control_coef

• gravity_coef

• impact_notice_body_normal_sum_x

• impact_notice_body_normal_sum_y

• impact_notice_body_normal_sum_z

• impact_notice_body_peak_normal_speed_mps

• impact_notice_body_material_id

• wheel_count

• linked_parent_entity_id

• race_timer_base_tick_age

• respawn_hold_deadline_tick_age

• surface_effect_flags_engine_off

• surface_effect_flags_engine_forced_on

• surface_effect_flags_no_brakes

• surface_effect_flags_no_steering

• surface_effect_flags_no_grip

• pose_discontinuity_count

• has_contact_this_step

• is_in_water_this_step

• any_wheel_slipping

• m6_direct_steer_ratio

• wheel_slip_last_tick_age

• steering_smoothed

• m6_drift_latch_active

• m6_surface_speed_scale

• m6_surface_acceleration_scale

• m6_surface_brake_scale

• m6_surface_grip

• m6_surface_force_ramp_start_kmh

• m6_surface_force_ramp_end_kmh

• m6_surface_force_ramp_magnitude

• m6_surface_drift_tangent_force_scale

• m6_surface_steer_approach_rate

• m6_magnetic_surface_class

• m6_overhead_contact_reflect_pending

• m6_overhead_contact_normal_x

• m6_overhead_contact_normal_y

• m6_overhead_contact_normal_z

• m6_has_recent_contact

• m6_has_three_recent_contacts

• m6_wheel_steering_angle_radians

• m6_throttle_demand_smoothed

• m6_brake_demand_smoothed

• brake_input_toggle_count

• m6_drift_wheel_force_blend

• m6_drift_direction_sign

• m13_throttle_pulse_start_tick_age

• m6_chassis_upright_factor

• m13_collision_penalty_accumulator

• m9_rotation_coast_mode

• m9_throttle_input_smoothed

• m9_pitch_input_smoothed

• m9_roll_input_smoothed

• m9_yaw_assist_scale

• m9_rotation_phase_radians

• m9_rotation_rate_radians_per_second

• collision_penalty_accumulator

• m14_steer_integrated

• m14_throttle_integrated

• m14_propeller_phase_radians

• m14_lift_speed_budget_kph

• m14_last_destabilized_tick_age

• m14_reverse_brake_start_tick_age

• m14_reverse_brake_scale

• m15_throttle_integrated

• m15_impact_window_start_tick_age

• m15_impact_window_first_contact_tick_age

• m15_impact_window_stopped_tick_age

• m15_impact_window_collision_event_count

• m15_impact_window_max_tilt_radians

• m15_impact_metric

• m12_speed_hold_gain

• m12_target_world_z_speed

• m12_yaw_torque_scale

• surface_grip_scale

• gravity_scale

• direction_change_boost_start_tick_age

• direction_change_boost_end_tick_age

• direction_change_boost_contact_flags_front_hit

• direction_change_boost_contact_flags_rear_hit

• fragile_gate_active

• fragile_damage

• fragile_impact_pending_weight

• fragile_impact_pending_sample_count

• held_surface_effect_flags_engine_off

• held_surface_effect_flags_engine_forced_on

• held_surface_effect_flags_no_brakes

• held_surface_effect_flags_no_steering

• held_surface_effect_flags_no_grip

• cruise_control_target_meters_per_second

• effects_reset_start_tick_age

• slow_motion_time_scale

• slow_motion_reset_deadline_tick_age

• is_in_water

• checkpoint_passed_effects_reset_pending

• water_hold_deadline_tick_age

• water_exit_correction_deadline_tick_age

• wetness

• wall_hit_this_step

• wall_hit_damping_start_tick_age

• linked_collision_support_velocity_sample_count

• gate_gameplay_id

• gate_merge_group_id

• slow_motion_last_gate_merge_group_id

• reactor_boost_type

• reactor_boost_level

• reactor_boost_start_tick_age

• reactor_boost_first_start_tick_age

• reactor_boost_up_ground_cast_start_tick_age

• reactor_boost_duration_ticks

• reactor_boost_up_over_water_steering_start_tick_age

• forward_motion_alignment_scale

• dirt_axle_force_ramp_start_tick_age

• all_wheels_on_dirt_target

• dirt_axle_force_ramp_base_scale

• soft_surface_drive_scale_hold_deadline_tick_age

• soft_surface_wheel_count

• steering_direction_change_tick_age

• steering_direction_change_drive_scale

• steering_neutral_start_tick_age

• steering_yaw_torque_direction

• steering_direction

• collision_yaw_rate_change_accumulated

• collision_yaw_rate_window_start_tick_age

• directional_response_gravity_coef

• adherence_coef

• vehicle_transform_copy_tick_age

• runtime_flags_transform_copy_source

• runtime_flags_ghost_response_applied

• runtime_flags_crush_impulse_recorded

• runtime_flags_crush_impulse_from_kinematic

• runtime_flags_opposing_crush_impulse

• runtime_flags_one_body_solve_ran

• contact_solver_residual

• previous_slow_motion_time_scale

• previous_steering_direction

• previous_step_forward_speed_mps

• rear_wheels_icing_grip_scale

• front_wheels_icing_grip_scale

• is_any_wheel_on_ice_or_snow

• first_step_tick_after_respawn

• wheel_contact_count

• car_to_car_contact_count

• previous_step_had_contact

• roof_contact_this_step

• side_or_roof_contact_this_step

• floor_contact_this_step

• physicalized_flags_physicalized

• auto_pilot_update_active

• m13_pair_link_eligible

• m9_ground_clearance_meters

• m9_last_step_position_y

• arena_player_state_id

• is_update_active

• arena_player_update_blocked

• registry_index

• fl_damper_length

• fl_damper_velocity

• fl_suspension_contact_compression_max

• fl_wheel_force_scale

• fl_wheel_angular_velocity

• fl_m6_contact_patch_speed

• fl_had_contact_last_step

• fl_has_ground_contact

• fl_surface_material_id

• fl_surface_gameplay_id

• fl_is_slipping

• fl_wheel_spin_blend

• fl_wheel_rotation_radians

• fl_wheel_steer_angle_radians

• fl_wheel_steer_angle_target_radians

• fl_m6_contact_position_hash

• fl_m6_suspension_force

• fl_fragile_impact_window_start_tick_age

• fl_fragile_impact_count

• fl_fragile_impact_weight_sum

• fl_icing_state

• fl_icing_transition_tick_age

• fl_icing_blend

• fl_icing_thaw_floor

• fl_reactor_boost_up_ground_distance_max

• fl_reactor_boost_up_peak_ground_distance_tick_age

• fl_super_reactor_boost_up_ground_distance

• fl_super_reactor_boost_up_has_ground_hit

• fr_damper_length

• fr_damper_velocity

• fr_suspension_contact_compression_max

• fr_wheel_force_scale

• fr_wheel_angular_velocity

• fr_m6_contact_patch_speed

• fr_had_contact_last_step

• fr_has_ground_contact

• fr_surface_material_id

• fr_surface_gameplay_id

• fr_is_slipping

• fr_wheel_spin_blend

• fr_wheel_rotation_radians

• fr_wheel_steer_angle_radians

• fr_wheel_steer_angle_target_radians

• fr_m6_contact_position_hash

• fr_m6_suspension_force

• fr_fragile_impact_window_start_tick_age

• fr_fragile_impact_count

• fr_fragile_impact_weight_sum

• fr_icing_state

• fr_icing_transition_tick_age

• fr_icing_blend

• fr_icing_thaw_floor

• fr_reactor_boost_up_ground_distance_max

• fr_reactor_boost_up_peak_ground_distance_tick_age

• fr_super_reactor_boost_up_ground_distance

• fr_super_reactor_boost_up_has_ground_hit

• rl_damper_length

• rl_damper_velocity

• rl_suspension_contact_compression_max

• rl_wheel_force_scale

• rl_wheel_angular_velocity

• rl_m6_contact_patch_speed

• rl_had_contact_last_step

• rl_has_ground_contact

• rl_surface_material_id

• rl_surface_gameplay_id

• rl_is_slipping

• rl_wheel_spin_blend

• rl_wheel_rotation_radians

• rl_wheel_steer_angle_radians

• rl_wheel_steer_angle_target_radians

• rl_m6_contact_position_hash

• rl_m6_suspension_force

• rl_fragile_impact_window_start_tick_age

• rl_fragile_impact_count

• rl_fragile_impact_weight_sum

• rl_icing_state

• rl_icing_transition_tick_age

• rl_icing_blend

• rl_icing_thaw_floor

• rl_reactor_boost_up_ground_distance_max

• rl_reactor_boost_up_peak_ground_distance_tick_age

• rl_super_reactor_boost_up_ground_distance

• rl_super_reactor_boost_up_has_ground_hit

• rr_damper_length

• rr_damper_velocity

• rr_suspension_contact_compression_max

• rr_wheel_force_scale

• rr_wheel_angular_velocity

• rr_m6_contact_patch_speed

• rr_had_contact_last_step

• rr_has_ground_contact

• rr_surface_material_id

• rr_surface_gameplay_id

• rr_is_slipping

• rr_wheel_spin_blend

• rr_wheel_rotation_radians

• rr_wheel_steer_angle_radians

• rr_wheel_steer_angle_target_radians

• rr_m6_contact_position_hash

• rr_m6_suspension_force

• rr_fragile_impact_window_start_tick_age

• rr_fragile_impact_count

• rr_fragile_impact_weight_sum

• rr_icing_state

• rr_icing_transition_tick_age

• rr_icing_blend

• rr_icing_thaw_floor

• rr_reactor_boost_up_ground_distance_max

• rr_reactor_boost_up_peak_ground_distance_tick_age

• rr_super_reactor_boost_up_ground_distance

• rr_super_reactor_boost_up_has_ground_hit