Beta

RacingGameState

Attribute Description
state.tick Number of ticks elapsed since the start of the race.
state.elapsed_seconds Simulated seconds elapsed. One tick is 1/30 of a second.
state.time_left Seconds until the engine takes this tick's controls and advances the race, as a float. It is just under 1/30 of a second when the state reaches you, and it counts down as your algo works: it is measured each time you read it, so read it again rather than keeping the number. Negative once the tick has moved on.
state.next_tick_time The moment time_left counts down to, as a UTC datetime.
state.rank Your current position, starting at 1. Karts that have finished rank ahead of karts still running, in the order they finished: your place is settled the moment you complete your last lap, whatever your kart does afterwards.
state.laps_left Laps remaining as a float, so 0.5 means half a lap to go. On the grid it is a little over the race's laps, since the grid is behind the line.
state.car A Car describing your own kart.
state.surroundings A list of SensedEntity, everything your kart can currently see.

Car

Your own kart. Positions and headings are in world coordinates; velocity and acceleration are in the kart’s own frame.

Attribute Description
car.pos (x, y) in metres.
car.heading Direction the kart points, in radians.
car.yaw_rate How fast the heading is changing, in radians per second.
car.yaw_acceleration How fast yaw_rate is changing, in radians per second squared, from the tyres' grip at the end of the last tick. A knock from a wall or another kart shows in yaw_rate instead. A yaw rate that keeps growing means the kart is spinning out.
car.velocity (forward, lateral) in metres per second. A large lateral component means the kart is sliding.
car.acceleration (forward, lateral) in metres per second squared.
car.engine_rpm How fast the rear wheel is turning the engine, in revolutions per minute: 0 at a standstill, and 8 engine turns to each wheel turn. The engine pulls hardest at about 4,000 rpm, and above 7,200 rpm its power stays the same, so its pull falls as it turns faster. A rear wheel rolling with the road gives about 546 rpm for each metre per second of speed, so an rpm well above that means it is spinning.
car.steering, car.throttle, car.brake The control inputs actually applied last tick, after clamping.

SensedEntity

One thing your kart can see, given as the line segment it presents to you. Both endpoints are in your kart’s frame: the origin is your kart, the positive x axis is straight ahead, and positive angles are to your left.

state.surroundings covers the full 360° around your kart, in counter-clockwise scan order. The first entry is always the thing directly ahead of you.

Each entry is one visible piece of one segment, after everything nearer has been clipped away. A wall behind another kart contributes only the parts you can actually see, so a single wall or kart may appear as several entries, or none at all. The ends of a piece that were cut by something in front of it have end1_is_true_endpoint or end2_is_true_endpoint set to False, which is how you tell “the wall stops here” from “I cannot see past here”. Other karts are sensed as the four sides of their box, so a kart near you is usually one or two entries rather than a point.

If an entity’s end_angle is less than its start_angle, that entity spans the ray straight ahead of you and its angular range wraps through 0.

The model is idealised: exact geometry, no noise, and no maximum range. What limits you is occlusion, not eyesight.

Attribute Description
entity.entity_id The index of the kart being sensed, or -1 for a wall.
entity.is_wall True when entity_id is -1.
entity.start_angle, entity.end_angle Angles in radians to each end of the segment.
entity.start_distance, entity.end_distance Distances in metres to each end of the segment.
entity.end1, entity.end2 The same two endpoints as (x, y) coordinates, which is usually what you want for geometry.
entity.end1_is_true_endpoint, entity.end2_is_true_endpoint False when that end is where the entity left your field of view or went behind something else, rather than where it actually ends.

Track

Handed to your algo once, as config[‘track’].

Attribute Description
track.name Name of the circuit.
track.half_width Half the width of the track surface, in metres.
track.lap_length Length of one lap along the centerline, in metres.
track.centerline A list of (x, y) points forming a closed loop.
track.start_pos, track.start_heading Where the start line crosses the centerline, and which way the race runs. The grid lines up just behind it.