car race

The prompt

Build a car race on an oval. Paint a racing line that cuts the apex of each bend. I accelerate and steer. The car should keep some speed when I ease off. Staying on the line should pay, and leaving the asphalt should slow me down and cost more. Finishing one lap should end the round.

Show the oval, the line, the car, and the score. Driving keys and a way to coast. A real-time switch keeps the car moving when I let go, so I can see the speed. N does nothing on purpose and the car still coasts. Different starts can place me off the line. The same start should repeat.

"""A car race on an oval. Paint a racing line that cuts the apex of each bend.

The person accelerates and steers. The car keeps some speed when they ease off
(coast). Staying on the line pays; leaving the asphalt slows the car and costs.
Finishing one lap ends the round.
"""
from __future__ import annotations

import math
from typing import Any, Dict, List, Tuple

from contract_ui_to_env import Action
from helpers import base_observation, clamp01, key_input, pick_task, task_ids

GAME_CLASS = "Race"

# Track geometry in display (SVG) pixels. World y grows up, but we already
# convert to screen pixels here so the view stays dumb.
VCX = 230.0
VCY = 180.0
RX = 168.0            # centreline semi-axis, horizontal
RY = 88.0             # centreline semi-axis, vertical
HW = 26.0             # asphalt half width (radial)
CUT = 0.62 * HW       # how far the racing line cuts inside each bend
MAX_OFF = HW * 1.4    # the car cannot drift farther than this from the line

VB_W = 460.0
VB_H = 360.0
N_LINE = 240          # samples for the painted racing line

TWO_PI = 2.0 * math.pi

# ---- physics, per step (every_ms ~ 60) ----
ACCEL = 0.0034        # throttle adds speed per step
MAX_SPEED = 0.058     # radians of lap progress per step
DRAG_FLAT = 0.0006    # always-on rolling resistance
FRICTION_MULT = 0.998 # coast keeps a little speed, then bleeds off
BRAKE = 0.011         # brake subtracts speed per step
STEER_RATE = 4.5      # lateral units of movement per step at full steer
OFFROAD_FLAT = 0.020  # heavy drag when the car is on the grass
OFFROAD_MULT = 0.90

LAP_BONUS = 1.0
ON_LINE_STEP = 0.011
OFFROAD_STEP = -0.03

START_OFFSETS: Dict[str, float] = {
    "s1": -CUT,        # right on the racing line (default)
    "s2": 0.0,         # a little outside the apex
    "s3": -0.78 * HW,  # tucked toward the inside edge
    "s4": 0.55 * HW,   # wide of the line
    "s5": 0.88 * HW,   # near the outside edge, off line
}

DIRECTIONS = ("up", "down", "left", "right")


def _legal_moves() -> List[str]:
    moves = list(DIRECTIONS) + ["coast", "nothing"]
    for v in ("up", "down"):
        for h in ("left", "right"):
            moves.append(f"{v} {h}")
    return moves


def _inputs() -> List[Dict[str, Any]]:
    return [
        key_input(
            "W A S D / Arrows",
            "accelerate, brake and steer",
            {
                "w": "up", "ArrowUp": "up",
                "s": "down", "ArrowDown": "down",
                "a": "left", "ArrowLeft": "left",
                "d": "right", "ArrowRight": "right",
            },
            hold=True,
            every_ms=60,
            idle="coast",
        ),
        key_input(
            "Space / N",
            "coast, or N to do nothing (the car still coasts)",
            {" ": "coast", "n": "nothing"},
            hold=False,
        ),
    ]


class Race:
    def __init__(self) -> None:
        self.reset("")

    # ---- geometry ----
    def _px(self, theta: float, off: float) -> Tuple[float, float]:
        wx = (RX + off) * math.cos(theta)
        wy = (RY + off) * math.sin(theta)
        return (VCX + wx, VCY - wy)

    def _line_offset(self, theta: float) -> float:
        return -CUT * math.cos(2.0 * theta)

    def _line_points(self) -> List[List[float]]:
        pts: List[List[float]] = []
        for i in range(N_LINE):
            th = TWO_PI * i / N_LINE
            x, y = self._px(th, self._line_offset(th))
            pts.append([round(x, 2), round(y, 2)])
        return pts

    def _heading_deg(self, theta: float, off: float) -> float:
        tx = -(RX + off) * math.sin(theta)
        ty = -(RY + off) * math.cos(theta)
        return math.degrees(math.atan2(ty, tx))

    # ---- lifecycle ----
    def reset(self, task_id: str = "") -> Dict[str, Any]:
        self.task = pick_task(task_id, task_ids(5), "s1")
        self.offset = START_OFFSETS.get(self.task, -CUT)
        self.theta = 0.0
        self.speed = 0.0
        self.score = 0.0
        self.done = False
        self.last_move: Any = None
        self._line = self._line_points()
        self._outer = (RX + HW, RY + HW)
        self._inner = (RX - HW, RY - HW)
        self._start_line = [
            [VCX + RX - HW, VCY],
            [VCX + RX + HW, VCY],
        ]
        return self._obs(self.last_move)

    def step(self, action: Action) -> Tuple[Dict[str, Any], bool, Any]:
        move = (action.move or "").strip()
        legal = _legal_moves()
        if self.done:
            return self._obs(self.last_move), True, None
        if move not in legal:
            return self._obs(self.last_move), False, f"unknown move {move!r}"

        tokens = set(move.split())
        throttle = "up" in tokens
        brake = "down" in tokens
        steer = 0
        if "left" in tokens:
            steer -= 1
        if "right" in tokens:
            steer += 1

        off = self.offset
        offroad_before = abs(off) > HW

        speed = self.speed
        if throttle:
            speed += ACCEL
        if brake:
            speed -= BRAKE
        speed -= DRAG_FLAT
        speed *= FRICTION_MULT

        if abs(off) > HW:
            speed -= OFFROAD_FLAT
            speed *= OFFROAD_MULT
        else:
            factor = 0.3 + 0.7 * (speed / MAX_SPEED)
            self.offset += steer * STEER_RATE * factor

        self.offset = max(-MAX_OFF, min(MAX_OFF, self.offset))
        self.speed = max(0.0, min(MAX_SPEED, speed))
        self.theta += self.speed

        # scoring for this step
        line_off = self._line_offset(self.theta)
        diff = abs(self.offset - line_off)
        quality = clamp01(1.0 - diff / HW)
        on_road = abs(self.offset) <= HW
        if on_road:
            self.score += ON_LINE_STEP * (0.22 + 0.78 * quality)
        else:
            self.score += OFFROAD_STEP

        self.last_move = move

        if self.theta >= TWO_PI:
            self.done = True
            self.score += LAP_BONUS

        return self._obs(self.last_move), True, None

    # ---- observation ----
    def _obs(self, last_move: Any) -> Dict[str, Any]:
        x, y = self._px(self.theta, self.offset)
        speed_kmh = int(round(self.speed * 1800.0))
        progress = clamp01(self.theta / TWO_PI)
        lap_pct = int(round(progress * 100.0))

        line_off = self._line_offset(self.theta)
        diff = abs(self.offset - line_off)
        quality = clamp01(1.0 - diff / HW)
        on_road = abs(self.offset) <= HW

        if self.done:
            status = "Lap complete!"
        elif not on_road:
            status = "Off track - slow!"
        elif quality > 0.82:
            status = "On the racing line"
        else:
            status = "On track"

        legal = [] if self.done else _legal_moves()

        return base_observation(
            reward=self.score,
            done=self.done,
            legal_moves=legal,
            last_move=last_move,
            task=self.task,
            sig=f"race|{self.task}",
            vb_w=VB_W,
            vb_h=VB_H,
            cx=VCX,
            cy=VCY,
            rx=RX,
            ry=RY,
            hw=HW,
            outer=self._outer,
            inner=self._inner,
            start_line=self._start_line,
            line=self._line,
            car={"x": round(x, 2), "y": round(y, 2), "heading": round(self._heading_deg(self.theta, self.offset), 2)},
            score=round(self.score, 2),
            speed_kmh=speed_kmh,
            lap=round(progress, 4),
            lap_pct=lap_pct,
            status=status,
            on_line=quality > 0.82,
            offroad=not on_road,
            throttle="up" in str(last_move).split() if last_move else False,
            steer=("right" in str(last_move).split()) - ("left" in str(last_move).split()) if last_move else 0,
            inputs=_inputs(),
        )