Lesson 13: Capstone Part 2: Polish & Playtest

If the flame shows the whole strip of four frames, slice_sheet() still returns [sheet]. If puffs never disappear, check that self.kill() runs once self.index reaches len(self.frames), and return right after it so you don't index past the end. If restarting keeps the old score, you changed state but forgot game = new_game(assets, rng). If you hear nothing, print sounds after loading: an empty dictionary means the mixer failed to start or the files weren't found.

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 for a fixed number of frames; when you run it yourself they do nothing. You never need to write them.

"""Space Salvage, Part 2: Intro Lesson 13 capstone (solution).

The finished arcade game: a title screen, thruster and puff animations,
sound effects and music, a game-over screen with restart, and every
tuning number grouped at the top for playtest changes.

Controls: arrow keys or WASD to fly, Enter or Space to start, M to mute,
Esc to quit. Art and sound: Kenney (www.kenney.nl), CC0. See CREDITS.md.
"""
import random
from pathlib import Path

import pygame


# --- Tuning: change ONE number at a time between playtests -------------------
WIDTH, HEIGHT = 960, 540
FPS = 60
PLAYER_SPEED = 320            # pixels per second
PLAYER_RADIUS = 20            # collision circle, a little smaller than the art
START_LIVES = 3
INVULNERABLE_TIME = 1.5       # seconds of blinking safety after a hit
SALVAGE_ON_SCREEN = 3
SALVAGE_POINTS = 10
ASTEROID_MIN_SPEED = 110      # pixels per second
ASTEROID_MAX_SPEED = 210
FIRST_SPAWN_GAP = 1.2         # seconds between asteroids at the start
MIN_SPAWN_GAP = 0.35          # the gap never gets shorter than this
GAP_SHRINK = 0.015            # the gap shrinks this much per second survived
FLAME_FPS = 12                # thruster animation speed (frames per second)
PUFF_FPS = 24                 # puff animation speed
STAR_COUNT = 90

ASSETS = Path(__file__).parent / "assets"
BG_COLOR = (10, 12, 26)
TEXT_COLOR = (235, 235, 245)
ACCENT_COLOR = (255, 200, 80)
KILL_MARGIN = 150             # asteroids this far off screen are removed


def clamp_color(value):
    """Keep a computed color channel inside 0-255."""
    return max(0, min(255, int(value)))


def load_image(name):
    """Load an image from the assets folder, or a pink placeholder if it is missing."""
    try:
        return pygame.image.load(ASSETS / name).convert_alpha()
    except (FileNotFoundError, pygame.error):
        print(f"Missing assets/{name}: using a placeholder circle.")
        surface = pygame.Surface((40, 40), pygame.SRCALPHA)
        pygame.draw.circle(surface, (255, 0, 200), (20, 20), 20)
        return surface


def slice_sheet(sheet, frame_width):
    """Cut a one-row sprite sheet into a list of frames."""
    frames = []
    for x in range(0, sheet.get_width() - frame_width + 1, frame_width):
        frames.append(sheet.subsurface((x, 0, frame_width, sheet.get_height())))
    return frames


def load_assets():
    """Load every image once, after the window exists (convert_alpha needs it)."""
    ship = load_image("ship.png")
    return {
        "ship": ship,
        "life_icon": pygame.transform.smoothscale_by(ship, 0.45),
        "meteors": [load_image(f"meteor_{n}.png") for n in range(1, 5)],
        "salvage": [load_image(f"salvage_{n}.png") for n in range(1, 4)],
        "flame": slice_sheet(load_image("flame_sheet.png"), 16),
        "puff": slice_sheet(load_image("puff_sheet.png"), 52),
    }


def load_sounds():
    """Start the mixer and load the sound effects. Returns {} if audio is unavailable."""
    try:
        pygame.mixer.init()
    except pygame.error:
        return {}
    sounds = {}
    for name, volume in (("collect", 0.4), ("hit", 0.7), ("game_over", 0.8)):
        try:
            sounds[name] = pygame.mixer.Sound(ASSETS / f"{name}.ogg")
            sounds[name].set_volume(volume)
        except (FileNotFoundError, pygame.error):
            print(f"Missing assets/{name}.ogg: that sound is skipped.")
    try:
        pygame.mixer.music.load(ASSETS / "engine_hum.ogg")
        pygame.mixer.music.set_volume(0.25)
        pygame.mixer.music.play(-1)             # -1 = loop forever
    except (FileNotFoundError, pygame.error):
        pass
    return sounds


def set_muted(muted):
    """Silence or restore all sound: the music loop and any effect still playing."""
    if pygame.mixer.get_init():
        pygame.mixer.music.set_volume(0 if muted else 0.25)
        if muted:
            pygame.mixer.stop()                 # cut effects already playing, like Lesson 10's SoundManager


class Player(pygame.sprite.Sprite):
    def __init__(self, image, flame_frames, pos):
        super().__init__()
        self.base_image = image                 # the unrotated ship, nose up
        self.image = image
        self.pos = pygame.Vector2(pos)          # float position
        self.rect = self.image.get_frect(center=self.pos)
        self.radius = PLAYER_RADIUS             # used by collide_circle
        self.angle = 0.0                        # degrees clockwise from "up"
        self.invulnerable = 0.0                 # seconds of safety left
        self.flame_frames = flame_frames
        self.flame_index = 0
        self.flame_timer = 0.0
        self.thrusting = False

    def update(self, dt, direction):
        self.thrusting = direction.length_squared() > 0
        if self.thrusting:
            direction = direction.normalize()   # diagonals are not faster
            self.pos += direction * PLAYER_SPEED * dt
            self.angle = pygame.Vector2(0, -1).angle_to(direction)
            # Thruster animation: subtract the frame time, keep the remainder.
            self.flame_timer += dt
            while self.flame_timer >= 1 / FLAME_FPS:
                self.flame_timer -= 1 / FLAME_FPS
                self.flame_index = (self.flame_index + 1) % len(self.flame_frames)
        self.pos.x = max(PLAYER_RADIUS, min(WIDTH - PLAYER_RADIUS, self.pos.x))
        self.pos.y = max(PLAYER_RADIUS, min(HEIGHT - PLAYER_RADIUS, self.pos.y))
        self.image = pygame.transform.rotate(self.base_image, -self.angle)
        self.rect = self.image.get_frect(center=self.pos)
        self.invulnerable = max(0.0, self.invulnerable - dt)

    def draw(self, screen):
        # Blink while invulnerable: skip drawing on every other tenth of a second.
        if self.invulnerable > 0 and int(self.invulnerable * 10) % 2 == 0:
            return
        if self.thrusting:
            flame = pygame.transform.rotate(self.flame_frames[self.flame_index], -self.angle)
            behind = self.pos + pygame.Vector2(0, 26).rotate(self.angle)
            screen.blit(flame, flame.get_frect(center=behind))
        screen.blit(self.image, self.rect)


class Asteroid(pygame.sprite.Sprite):
    def __init__(self, image, pos, velocity, spin):
        super().__init__()
        self.base_image = image
        self.image = image
        self.pos = pygame.Vector2(pos)
        self.velocity = pygame.Vector2(velocity)   # pixels per second
        self.spin = spin                           # degrees per second
        self.angle = 0.0
        self.radius = image.get_width() * 0.42
        self.rect = self.image.get_frect(center=self.pos)

    def update(self, dt):
        self.pos += self.velocity * dt
        self.angle = (self.angle + self.spin * dt) % 360
        self.image = pygame.transform.rotate(self.base_image, self.angle)
        self.rect = self.image.get_frect(center=self.pos)
        if not (-KILL_MARGIN < self.pos.x < WIDTH + KILL_MARGIN
                and -KILL_MARGIN < self.pos.y < HEIGHT + KILL_MARGIN):
            self.kill()                            # far off screen: forget it


class Salvage(pygame.sprite.Sprite):
    def __init__(self, image, pos):
        super().__init__()
        self.image = image
        self.pos = pygame.Vector2(pos)
        self.rect = self.image.get_frect(center=self.pos)
        self.radius = 18


class Puff(pygame.sprite.Sprite):
    """A one-shot animation that removes itself after its last frame."""

    def __init__(self, frames, pos):
        super().__init__()
        self.frames = frames
        self.index = 0
        self.timer = 0.0
        self.image = frames[0]
        self.rect = self.image.get_frect(center=pos)

    def update(self, dt):
        self.timer += dt
        while self.timer >= 1 / PUFF_FPS:
            self.timer -= 1 / PUFF_FPS
            self.index += 1
            if self.index >= len(self.frames):
                self.kill()
                return
        center = self.rect.center
        self.image = self.frames[self.index]
        self.rect = self.image.get_frect(center=center)


def spawn_asteroid(assets, rng):
    """Make an asteroid just outside a random edge, aimed across the screen."""
    size = rng.randint(40, 90)
    image = pygame.transform.smoothscale(rng.choice(assets["meteors"]), (size, size))
    edge = rng.choice(("top", "bottom", "left", "right"))
    if edge == "top":
        pos = pygame.Vector2(rng.uniform(0, WIDTH), -size)
    elif edge == "bottom":
        pos = pygame.Vector2(rng.uniform(0, WIDTH), HEIGHT + size)
    elif edge == "left":
        pos = pygame.Vector2(-size, rng.uniform(0, HEIGHT))
    else:
        pos = pygame.Vector2(WIDTH + size, rng.uniform(0, HEIGHT))
    target = pygame.Vector2(rng.uniform(WIDTH * 0.2, WIDTH * 0.8),
                            rng.uniform(HEIGHT * 0.2, HEIGHT * 0.8))
    speed = rng.uniform(ASTEROID_MIN_SPEED, ASTEROID_MAX_SPEED)
    velocity = (target - pos).normalize() * speed
    return Asteroid(image, pos, velocity, rng.uniform(-90, 90))


def fill_salvage(game, assets, rng):
    """Top the salvage back up to SALVAGE_ON_SCREEN, away from the player."""
    while len(game["salvage"]) < SALVAGE_ON_SCREEN:
        for _ in range(20):
            pos = pygame.Vector2(rng.uniform(60, WIDTH - 60), rng.uniform(60, HEIGHT - 60))
            if pos.distance_to(game["player"].pos) > 150:
                break
        game["salvage"].add(Salvage(rng.choice(assets["salvage"]), pos))


def spawn_gap(elapsed):
    """Seconds between asteroids: shrinks as the run goes on, down to a floor."""
    return max(MIN_SPAWN_GAP, FIRST_SPAWN_GAP - GAP_SHRINK * elapsed)


def new_game(assets, rng):
    """Everything that changes during one run, in one dictionary."""
    game = {
        "player": Player(assets["ship"], assets["flame"], (WIDTH / 2, HEIGHT / 2)),
        "asteroids": pygame.sprite.Group(),
        "salvage": pygame.sprite.Group(),
        "effects": pygame.sprite.Group(),
        "score": 0,
        "lives": START_LIVES,
        "time": 0.0,
        "spawn_timer": FIRST_SPAWN_GAP,
    }
    fill_salvage(game, assets, rng)
    return game


def read_direction(keys):
    """Turn the arrow keys and WASD into a direction vector (not yet normalized)."""
    x = (keys[pygame.K_RIGHT] or keys[pygame.K_d]) - (keys[pygame.K_LEFT] or keys[pygame.K_a])
    y = (keys[pygame.K_DOWN] or keys[pygame.K_s]) - (keys[pygame.K_UP] or keys[pygame.K_w])
    return pygame.Vector2(x, y)


def update_game(game, dt, direction, assets, rng):
    """Advance one frame of play. Returns a list of what happened, for sound."""
    events = []
    game["time"] += dt
    player = game["player"]
    player.update(dt, direction)
    game["asteroids"].update(dt)
    game["effects"].update(dt)

    # Spawn asteroids on a timer: subtract, keep the remainder.
    game["spawn_timer"] -= dt
    while game["spawn_timer"] <= 0:
        game["asteroids"].add(spawn_asteroid(assets, rng))
        game["spawn_timer"] += spawn_gap(game["time"])

    # Collect: touching salvage removes it (dokill=True) and scores.
    for crate in pygame.sprite.spritecollide(player, game["salvage"], True,
                                             pygame.sprite.collide_circle):
        game["score"] += SALVAGE_POINTS
        game["effects"].add(Puff(assets["puff"], crate.pos))
        events.append("collect")
    fill_salvage(game, assets, rng)

    # Dodge: an asteroid costs a life, then a short blinking safety window.
    if player.invulnerable <= 0 and pygame.sprite.spritecollideany(
            player, game["asteroids"], pygame.sprite.collide_circle):
        game["lives"] -= 1
        player.invulnerable = INVULNERABLE_TIME
        game["effects"].add(Puff(assets["puff"], player.pos))
        events.append("hit")
        if game["lives"] <= 0:
            events.append("game_over")
    return events


def make_stars(rng):
    """Background stars as [x, y, speed] lists; faster stars are brighter."""
    return [[rng.uniform(0, WIDTH), rng.uniform(0, HEIGHT), rng.uniform(15, 70)]
            for _ in range(STAR_COUNT)]


def update_stars(stars, dt):
    for star in stars:
        star[1] += star[2] * dt
        if star[1] > HEIGHT:
            star[1] -= HEIGHT


def draw_stars(screen, stars):
    for x, y, speed in stars:
        shade = clamp_color(60 + speed * 2.6)
        screen.fill((shade, shade, clamp_color(shade + 20)), (x, y, 2, 2))


def draw_centered(screen, font, text, y, color=TEXT_COLOR):
    label = font.render(text, True, color)
    screen.blit(label, label.get_rect(center=(WIDTH / 2, y)))


def draw_hud(screen, game, font, assets):
    screen.blit(font.render(f"Score: {game['score']}", True, TEXT_COLOR), (14, 10))
    screen.blit(font.render(f"Time: {game['time']:.0f}s", True, TEXT_COLOR), (14, 40))
    icon = assets["life_icon"]
    for i in range(game["lives"]):
        screen.blit(icon, (WIDTH - 14 - (i + 1) * (icon.get_width() + 6), 14))


def draw_world(screen, game, stars, fonts, assets):
    screen.fill(BG_COLOR)
    draw_stars(screen, stars)
    game["salvage"].draw(screen)
    game["asteroids"].draw(screen)
    game["player"].draw(screen)
    game["effects"].draw(screen)
    draw_hud(screen, game, fonts["small"], assets)


def main():
    pygame.init()
    screen = pygame.display.set_mode((WIDTH, HEIGHT))
    pygame.display.set_caption("Space Salvage")
    clock = pygame.time.Clock()
    fonts = {"small": pygame.font.Font(None, 32), "big": pygame.font.Font(None, 84)}
    assets = load_assets()
    sounds = load_sounds()
    rng = random.Random()
    stars = make_stars(rng)
    game = new_game(assets, rng)
    state = "title"                             # "title", "playing" or "game_over"
    best = 0
    muted = False

    running = True
    while running:
        dt = min(clock.tick(FPS) / 1000, 0.05)  # seconds; capped after a stall

        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                running = False
            elif event.type == pygame.KEYDOWN:
                if event.key == pygame.K_ESCAPE:
                    running = False
                elif event.key == pygame.K_m:
                    muted = not muted
                    set_muted(muted)
                elif state != "playing" and event.key in (pygame.K_RETURN, pygame.K_SPACE):
                    game = new_game(assets, rng)
                    state = "playing"

        update_stars(stars, dt)
        if state == "playing":
            happened = update_game(game, dt, read_direction(pygame.key.get_pressed()), assets, rng)
            for name in happened:
                if name in sounds and not muted:
                    sounds[name].play()
            if "game_over" in happened:
                best = max(best, game["score"])
                state = "game_over"
        elif state == "game_over":
            game["effects"].update(dt)          # let the last puff finish

        if state == "title":
            screen.fill(BG_COLOR)
            draw_stars(screen, stars)
            draw_centered(screen, fonts["big"], "SPACE SALVAGE", HEIGHT / 2 - 70, ACCENT_COLOR)
            draw_centered(screen, fonts["small"], "Collect salvage. Dodge asteroids.", HEIGHT / 2)
            draw_centered(screen, fonts["small"], "Arrows or WASD to fly   M to mute", HEIGHT / 2 + 36)
            draw_centered(screen, fonts["small"], "Press Enter to launch", HEIGHT / 2 + 100, ACCENT_COLOR)
        else:
            draw_world(screen, game, stars, fonts, assets)
            if state == "game_over":
                draw_centered(screen, fonts["big"], "GAME OVER", HEIGHT / 2 - 50, ACCENT_COLOR)
                draw_centered(screen, fonts["small"],
                              f"Score {game['score']}    Best {best}", HEIGHT / 2 + 10)
                draw_centered(screen, fonts["small"], "Press Enter to fly again", HEIGHT / 2 + 50)
        pygame.display.flip()

    pygame.quit()
    print(f"Space Salvage closed in state '{state}'. Last score: {game['score']}, best: {best}.")


if __name__ == "__main__":
    main()