Lesson 23: Racing Physics

Work in the car's own frame: after the heading changes, recompute fwd and right, split the velocity with two dot products, change v_fwd and v_side separately, and only then rebuild vel = fwd * v_fwd + right * v_side. For the lap logic, remember which checkpoint the car spawns on. If laps never count, print car.next_cp every second and see where it gets stuck.

If your instructor hands you the lab file, you will see a few extra lines marked lab runtime near the top and and frame_budget() in the loop. They let the instructor's checker run the program automatically; when you run it yourself they do nothing.

"""Lap Racer: Advanced Lesson 23 practice exercise (solution).

A top-down racer built on a kinematic bicycle model with separate front and
rear grip (so you can feel understeer and oversteer), circle-vs-track wall
collisions, an AI rival, and lap timing that counts a lap only at the
start/finish line after every other checkpoint.

Keys: arrows or WASD drive (hold brake when stopped to reverse), SPACE is the
handbrake, 1 and 2 switch tracks, R restarts. Close the window to quit.
"""
import math
from dataclasses import dataclass

import pygame


WIDTH, HEIGHT = 960, 600
PX_PER_M = 8                     # game scale: 8 px = 1 m (only used for the km/h readout)
CAR_RADIUS = 11                  # collision circle, px
CAR_LENGTH, CAR_WIDTH = 30, 16   # drawn size, px
WHEELBASE = 22                   # px between the front and rear axles
MAX_STEER = math.radians(32)     # front-wheel angle at full lock
ENGINE_ACCEL = 260               # px/s^2 at full throttle
BRAKE_DECEL = 520                # px/s^2 at full brake
REVERSE_ACCEL = 140              # px/s^2 while holding brake when (almost) stopped
MAX_REVERSE = 90                 # px/s
ROLLING = 0.4                    # 1/s   rolling resistance (proportional to speed)
DRAG = 0.0012                    # 1/px  air drag (proportional to speed squared)
WALL_BOUNCE = 0.3                # restitution against the track edge
CAR_BOUNCE = 0.5                 # restitution between cars

GRASS = (46, 104, 58)
ASPHALT = (58, 60, 66)
KERB = (200, 200, 205)
TEXT = (235, 235, 235)
WARN = (255, 200, 80)


@dataclass
class Controls:
    throttle: float = 0.0    # 0..1
    brake: float = 0.0       # 0..1
    steer: float = 0.0       # -1 (left) .. 1 (right)
    handbrake: bool = False


def move_toward(value, target, max_delta):
    """Move value toward target by at most max_delta, never past it."""
    if abs(target - value) <= max_delta:
        return target
    return value + math.copysign(max_delta, target - value)


def wrap_angle(a):
    """Wrap an angle in radians into [-pi, pi)."""
    return (a + math.pi) % math.tau - math.pi


class Car:
    def __init__(self, pos, heading, color, front_grip=700.0, rear_grip=900.0):
        self.pos = pygame.Vector2(pos)
        self.vel = pygame.Vector2()
        self.heading = heading           # radians, 0 = facing right, clockwise on screen
        self.color = color
        self.front_grip = front_grip     # most sideways accel the front tires can give, px/s^2
        self.rear_grip = rear_grip       # how fast the rear tires cancel sliding, px/s^2
        self.slip_angle = 0.0            # radians between the nose and the direction of travel
        self.understeer = False
        self.sliding = False
        # Race progress. next_cp starts at 1: the car spawns on the start line (checkpoint 0).
        self.next_cp = 1
        self.laps = 0
        self.lap_time = 0.0
        self.best_lap = None

    def axes(self):
        fwd = pygame.Vector2(1, 0).rotate_rad(self.heading)
        right = pygame.Vector2(-fwd.y, fwd.x)        # 90 degrees clockwise on screen
        return fwd, right

    def speed_kmh(self):
        return self.vel.length() / PX_PER_M * 3.6

    def update(self, c, dt):
        # 1. Steering: kinematic bicycle model, capped by what the front tires can grip.
        fwd, _ = self.axes()
        v_fwd = self.vel.dot(fwd)
        yaw_rate = v_fwd / WHEELBASE * math.tan(c.steer * MAX_STEER)
        lateral_accel = abs(v_fwd * yaw_rate)
        self.understeer = lateral_accel > self.front_grip
        if self.understeer:
            yaw_rate *= self.front_grip / lateral_accel
        self.heading = wrap_angle(self.heading + yaw_rate * dt)

        # 2. Split the velocity along the NEW nose direction.
        fwd, right = self.axes()
        v_fwd = self.vel.dot(fwd)
        v_side = self.vel.dot(right)

        # 3. Engine, brakes and resistance act along the nose.
        v_fwd += ENGINE_ACCEL * c.throttle * dt
        if c.brake > 0:
            if v_fwd > 5:            # rolling forward: slow down and stop at exactly 0
                v_fwd = move_toward(v_fwd, 0.0, BRAKE_DECEL * c.brake * dt)
            else:                    # stopped: keep holding brake to reverse slowly
                v_fwd = max(-MAX_REVERSE, v_fwd - REVERSE_ACCEL * c.brake * dt)
        v_fwd -= (ROLLING * v_fwd + DRAG * v_fwd * abs(v_fwd)) * dt

        # 4. The rear tires cancel sideways sliding, but only so fast.
        grip = self.rear_grip * (0.2 if c.handbrake else 1.0)
        v_side = move_toward(v_side, 0.0, grip * dt)
        self.sliding = abs(v_side) > 25
        self.slip_angle = math.atan2(v_side, abs(v_fwd)) if self.vel.length_squared() > 1 else 0.0

        self.vel = fwd * v_fwd + right * v_side
        self.pos += self.vel * dt

    def corners(self):
        fwd, right = self.axes()
        hl, hw = fwd * (CAR_LENGTH / 2), right * (CAR_WIDTH / 2)
        return [self.pos + hl + hw, self.pos + hl - hw, self.pos - hl - hw, self.pos - hl + hw]


class Track:
    def __init__(self, name, points, half_width=55):
        self.name = name
        self.points = [pygame.Vector2(p) for p in points]    # centerline; also the checkpoints
        self.half_width = half_width
        self.checkpoint_radius = half_width * 1.6
        self.surface = None                                  # drawn once, on first use

    def segments(self):
        return zip(self.points, self.points[1:] + self.points[:1])

    def nearest(self, p):
        """Distance from p to the centerline, and the closest centerline point."""
        best_d2, best_q = None, None
        for a, b in self.segments():
            ab = b - a
            t = max(0.0, min(1.0, (p - a).dot(ab) / ab.length_squared()))
            q = a + ab * t
            d2 = p.distance_squared_to(q)
            if best_d2 is None or d2 < best_d2:
                best_d2, best_q = d2, q
        return math.sqrt(best_d2), best_q

    def keep_inside(self, car):
        """Circle-vs-track collision: push the car back and bounce it off the edge."""
        d, q = self.nearest(car.pos)
        limit = self.half_width - CAR_RADIUS
        if d <= limit or d == 0:
            return False
        n = (car.pos - q) / d                      # points from the centerline out to the wall
        car.pos = q + n * limit
        v_out = car.vel.dot(n)
        if v_out > 0:
            car.vel -= n * v_out * (1 + WALL_BOUNCE)
        return True

    def start_heading(self):
        d = self.points[1] - self.points[0]
        return math.atan2(d.y, d.x)

    def grid(self, count):
        """Starting spots behind the start line, two abreast, never overlapping."""
        back = (self.points[-1] - self.points[0]).normalize()
        side = pygame.Vector2(-back.y, back.x)
        spots = []
        for i in range(count):
            row, col = divmod(i, 2)
            offset = side * (self.half_width * 0.45) * (1 if col == 0 else -1)
            spots.append(self.points[0] + back * (20 + row * 3 * CAR_RADIUS) + offset)
        return spots

    def render(self):
        surf = pygame.Surface((WIDTH, HEIGHT)).convert()
        surf.fill(GRASS)
        for a, b in self.segments():
            pygame.draw.line(surf, KERB, a, b, self.half_width * 2 + 6)
        for p in self.points:
            pygame.draw.circle(surf, KERB, p, self.half_width + 3)
        for a, b in self.segments():
            pygame.draw.line(surf, ASPHALT, a, b, self.half_width * 2)
        for p in self.points:
            pygame.draw.circle(surf, ASPHALT, p, self.half_width)
        # Checkered start/finish line across checkpoint 0.
        d = (self.points[1] - self.points[0]).normalize()
        n = pygame.Vector2(-d.y, d.x)
        for k in range(-5, 5):
            color = (240, 240, 240) if k % 2 else (20, 20, 20)
            c = self.points[0] + n * (k + 0.5) * (self.half_width / 5)
            pygame.draw.circle(surf, color, c, self.half_width / 10 + 1)
        return surf


def make_oval():
    return Track("Oval", [(480, 510), (700, 510), (820, 440), (860, 300), (820, 160), (700, 90),
                          (480, 90), (260, 90), (140, 160), (100, 300), (140, 440), (260, 510)])


def make_chicane():
    return Track("Chicane", [(480, 520), (760, 520), (880, 460), (900, 330), (880, 170), (780, 80),
                             (620, 80), (540, 190), (420, 190), (340, 80), (180, 80), (80, 170),
                             (60, 330), (80, 460), (200, 520)])


def update_progress(car, track, dt):
    """Count checkpoints in order; a lap ends only at checkpoint 0. Returns True on a new lap."""
    car.lap_time += dt
    if car.pos.distance_to(track.points[car.next_cp]) > track.checkpoint_radius:
        return False
    finished = car.next_cp == 0
    car.next_cp = (car.next_cp + 1) % len(track.points)
    if finished:
        car.laps += 1
        if car.best_lap is None or car.lap_time < car.best_lap:
            car.best_lap = car.lap_time
        car.lap_time = 0.0
    return finished


def collide_cars(a, b):
    """Equal-mass circle collision: separate the cars, then exchange a bounce impulse."""
    delta = b.pos - a.pos
    dist = delta.length()
    if dist >= 2 * CAR_RADIUS or dist == 0:
        return False
    n = delta / dist
    overlap = 2 * CAR_RADIUS - dist
    a.pos -= n * overlap / 2
    b.pos += n * overlap / 2
    closing = (b.vel - a.vel).dot(n)
    if closing < 0:
        j = -(1 + CAR_BOUNCE) * closing / 2
        a.vel -= n * j
        b.vel += n * j
    return True


def ai_controls(car, track):
    """Steer toward the next checkpoint; lift and brake when the turn is sharp."""
    to_target = track.points[car.next_cp] - car.pos
    error = wrap_angle(math.atan2(to_target.y, to_target.x) - car.heading)
    sharp = abs(error) > 0.6
    brake = 1.0 if sharp and car.vel.length() > 200 else 0.0
    return Controls(throttle=0.0 if brake else (0.5 if sharp else 1.0), brake=brake,
                    steer=max(-1.0, min(1.0, error * 2.0)))


def player_controls(held):
    def down(*keys):
        return any(k in held for k in keys)
    return Controls(throttle=1.0 if down(pygame.K_UP, pygame.K_w) else 0.0,
                    brake=1.0 if down(pygame.K_DOWN, pygame.K_s) else 0.0,
                    steer=(1.0 if down(pygame.K_RIGHT, pygame.K_d) else 0.0)
                    - (1.0 if down(pygame.K_LEFT, pygame.K_a) else 0.0),
                    handbrake=down(pygame.K_SPACE))


def fmt_time(t):
    return "--:--.--" if t is None else f"{int(t // 60):02d}:{t % 60:05.2f}"


class Race:
    def __init__(self, track):
        self.set_track(track)

    def set_track(self, track):
        """Switching tracks rebuilds the cars, so no car keeps a checkpoint index from the old track."""
        self.track = track
        spots = track.grid(2)
        heading = track.start_heading()
        self.player = Car(spots[0], heading, (80, 170, 255))
        self.rival = Car(spots[1], heading, (255, 90, 90), front_grip=650.0)
        self.cars = [self.player, self.rival]

    def update(self, controls, dt):
        self.player.update(controls, dt)
        self.rival.update(ai_controls(self.rival, self.track), dt)
        collide_cars(self.player, self.rival)
        for car in self.cars:
            self.track.keep_inside(car)
            update_progress(car, self.track, dt)

    def draw(self, screen, font):
        if self.track.surface is None:
            self.track.surface = self.track.render()
        screen.blit(self.track.surface, (0, 0))
        target = self.track.points[self.player.next_cp]
        pygame.draw.circle(screen, WARN, target, 8, 2)
        for car in self.cars:
            pygame.draw.polygon(screen, car.color, car.corners())
            fwd, _ = car.axes()
            pygame.draw.circle(screen, (250, 250, 250), car.pos + fwd * (CAR_LENGTH / 2 - 4), 3)
        p = self.player
        lines = [f"{self.track.name}   Lap {p.laps + 1}   Rival laps {self.rival.laps}",
                 f"Speed {p.speed_kmh():5.0f} km/h   Slip {math.degrees(p.slip_angle):+5.1f} deg",
                 f"Lap time {fmt_time(p.lap_time)}   Best {fmt_time(p.best_lap)}"]
        tags = ("UNDERSTEER " if p.understeer else "") + ("SLIDING" if p.sliding else "")
        for i, text in enumerate(lines):
            screen.blit(font.render(text, True, TEXT), (12, 10 + i * 22))
        if tags:
            screen.blit(font.render(tags, True, WARN), (12, 76))
        help_text = font.render("Arrows/WASD drive  SPACE handbrake  1/2 track  R restart", True, TEXT)
        screen.blit(help_text, (12, HEIGHT - 28))


def main():
    pygame.init()
    screen = pygame.display.set_mode((WIDTH, HEIGHT))
    pygame.display.set_caption("Lap Racer")
    clock = pygame.time.Clock()
    font = pygame.font.Font(None, 24)            # created once, before the loop
    tracks = [make_oval(), make_chicane()]
    race = Race(tracks[0])
    held = set()                                  # keys currently held down

    running = True
    while running:
        dt = min(clock.tick(60) / 1000, 0.05)     # seconds; capped so a stall can't tunnel a wall
        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                running = False
            elif event.type == pygame.KEYDOWN:
                held.add(event.key)
                if event.key == pygame.K_1:
                    race.set_track(tracks[0])
                elif event.key == pygame.K_2:
                    race.set_track(tracks[1])
                elif event.key == pygame.K_r:
                    race.set_track(race.track)
            elif event.type == pygame.KEYUP:
                held.discard(event.key)

        race.update(player_controls(held), dt)
        race.draw(screen, font)
        pygame.display.flip()

    pygame.quit()
    print(f"Track: {race.track.name}  laps: {race.player.laps}  best: {fmt_time(race.player.best_lap)}")
    print("Race closed cleanly.")


if __name__ == "__main__":
    main()