Space Invaders 2D

the arcade classic rebuilt on nodes, signals and synthesized sound.

▶ Run in browser

Tags: game collision waves shooting

Five rows of aliens march across the screen, drop closer every time the formation touches an edge, and shoot back from the bottom of each column. Four barriers erode block by block as fire lands on them, and a mystery ship crosses the top on the arcade’s 15-shot scoring cycle. Clear the fleet and the next wave arrives faster and fires more often, so the run ends when your three lives do, or when the aliens reach the ground.

Every pixel and every sound is generated in code: the demo ships no asset files.

• 8x8 bit-pattern sprites drawn as filled rects, two frames per alien type driving the marching animation

• Shot, explosion, march-step and UFO-siren clips synthesized with NumPy at import time and wrapped as AudioClip.from_pcm buffers

• One-shot AudioPlayer nodes that reap themselves via queue_free_on_end, mixed through the SFX bus the options popup drives live

• Scene-tree groups (aliens, bullets, barriers, the player, the mystery ship) backing the circle-overlap collision queries, with no physics world involved

• Per-instance signals (died, wave_cleared, reached_bottom, hit, fired) keeping the rules out of the actors

• Timer nodes for the fire rate, the alien volley, respawn invulnerability and the wave banner

• tree.change_scene between menu, game and game-over, with declarative input_actions re-registered on every swap

• Anchored Label HUD plus a modal show_overlay popup with Slider volume controls

• Camera2D.shake on a player death, over a parallax starfield

Controls: arrows or A/D move, SPACE fires, ENTER starts. With a mouse or a touchscreen, hold anywhere to slide the cannon toward the pointer and fire while held; the AUDIO OPTIONS button (or O) opens the mixer.

Source

#!/usr/bin/env python3
"""Space Invaders 2D: the arcade classic rebuilt on nodes, signals and synthesized sound.

# /// simvx
# tags = ["game", "collision", "waves", "shooting"]
# web = { root = "MainMenu" }
# ///

Five rows of aliens march across the screen, drop closer every time the
formation touches an edge, and shoot back from the bottom of each column. Four
barriers erode block by block as fire lands on them, and a mystery ship crosses
the top on the arcade's 15-shot scoring cycle. Clear the fleet and the next wave
arrives faster and fires more often, so the run ends when your three lives do,
or when the aliens reach the ground.

Every pixel and every sound is generated in code: the demo ships no asset files.

- 8x8 bit-pattern sprites drawn as filled rects, two frames per alien type
  driving the marching animation
- Shot, explosion, march-step and UFO-siren clips synthesized with NumPy at
  import time and wrapped as ``AudioClip.from_pcm`` buffers
- One-shot ``AudioPlayer`` nodes that reap themselves via ``queue_free_on_end``,
  mixed through the ``SFX`` bus the options popup drives live
- Scene-tree groups (aliens, bullets, barriers, the player, the mystery ship)
  backing the circle-overlap collision queries, with no physics world involved
- Per-instance signals (``died``, ``wave_cleared``, ``reached_bottom``, ``hit``,
  ``fired``) keeping the rules out of the actors
- ``Timer`` nodes for the fire rate, the alien volley, respawn invulnerability
  and the wave banner
- ``tree.change_scene`` between menu, game and game-over, with declarative
  ``input_actions`` re-registered on every swap
- Anchored ``Label`` HUD plus a modal ``show_overlay`` popup with ``Slider``
  volume controls
- ``Camera2D.shake`` on a player death, over a parallax starfield

Controls: arrows or A/D move, SPACE fires, ENTER starts. With a mouse or a
touchscreen, hold anywhere to slide the cannon toward the pointer and fire while
held; the AUDIO OPTIONS button (or O) opens the mixer.
"""

import random

import numpy as np

from simvx.core import (
    AudioClip,
    AudioPlayer,
    Camera2D,
    Input,
    Key,
    MouseButton,
    Node,
    Node2D,
    Property,
    Signal,
    Timer,
    Vec2,
)
from simvx.core.audio_bus import AudioBusLayout
from simvx.core.ui import AnchorPreset, Button, Control, Label, Panel, Slider
from simvx.graphics import App

WIDTH, HEIGHT = 800, 600

# Declared on every root scene below: the tree bulk-registers a root's
# ``input_actions`` on mount and again after each ``change_scene``, so no scene
# depends on another having run first.
INPUT_ACTIONS = {
    "move_left": [Key.A, Key.LEFT],
    "move_right": [Key.D, Key.RIGHT],
    "fire": [Key.SPACE],
    "start": [Key.ENTER, MouseButton.LEFT],
    "options": [Key.O],
}


class Body2D(Node2D):
    """A manually integrated 2D actor with a collision radius + group overlap query.

    Space Invaders is an arcade game with NO physics simulation: aliens, bullets
    and the player move by directly setting ``position`` and collisions are plain
    circle-vs-circle radius tests. So this is deliberately not a physics body
    (these entities need no collider at all): it is a light ``Node2D`` carrying a
    radius and a group-scoped overlap poll.
    """

    def __init__(self, radius: float = 8.0, **kwargs):
        super().__init__(**kwargs)
        self.radius = float(radius)

    def get_overlapping(self, group: str) -> list[Body2D]:
        """Other ``Body2D`` nodes in ``group`` whose radius overlaps ours."""
        if not self.tree:
            return []
        hits: list[Body2D] = []
        for b in self.tree.group(group):
            if b is self or not isinstance(b, Body2D):
                continue
            d = b.world_position - self.world_position
            rr = self.radius + b.radius
            if float(d.x) ** 2 + float(d.y) ** 2 <= rr * rr:
                hits.append(b)
        return hits


PIXEL = 3  # scale for 8x8 sprites
SAMPLE_RATE = 48000  # matches the engine mixer, so the clips need no resampling

# 8x8 bit-pattern sprites (each int = one row, bit 7 = leftmost pixel).
# Two frames per type drives the iconic "step" animation.
ALIEN_SQUID_A = [0x18, 0x3C, 0x7E, 0xDB, 0xFF, 0x24, 0x5A, 0xA5]
ALIEN_SQUID_B = [0x18, 0x3C, 0x7E, 0xDB, 0xFF, 0x24, 0xA5, 0x5A]
ALIEN_CRAB_A = [0x24, 0x18, 0x3C, 0x5A, 0x7E, 0x24, 0x24, 0x42]
ALIEN_CRAB_B = [0x24, 0xA5, 0x3C, 0x5A, 0x7E, 0x24, 0x42, 0x24]
ALIEN_OCTOPUS_A = [0x18, 0x3C, 0x7E, 0xDB, 0xFF, 0x5A, 0x81, 0x42]
ALIEN_OCTOPUS_B = [0x18, 0x3C, 0x7E, 0xDB, 0xFF, 0x5A, 0x42, 0x81]
ALIEN_UFO = [0x3C, 0x7E, 0xFF, 0xDB, 0xFF, 0x7E, 0x24, 0x00]

ALIEN_TYPES = [
    ((ALIEN_SQUID_A, ALIEN_SQUID_B), (1.0, 0.2, 0.2), 30),  # squid, red, 30 pts
    ((ALIEN_CRAB_A, ALIEN_CRAB_B), (0.2, 1.0, 0.2), 20),  # crab, green, 20 pts
    ((ALIEN_OCTOPUS_A, ALIEN_OCTOPUS_B), (0.2, 0.59, 1.0), 10),  # octopus, blue, 10 pts
]

# Formation geometry: one squid row, two crab rows, two octopus rows.
ALIEN_ROW_TYPES = [0, 1, 1, 2, 2]
ALIEN_ROWS = len(ALIEN_ROW_TYPES)
ALIEN_COLS = 11
ALIEN_SPACING_X = 40
ALIEN_SPACING_Y = 36

# Canonical Invaders mystery-ship 15-cycle (player shot count → points).
MYSTERY_POINTS_CYCLE = [100, 50, 50, 100, 150, 100, 100, 50, 300, 100, 100, 100, 50, 150, 100]

BARRIER_PATTERN = [
    "  #######  ",
    " ######### ",
    "###########",
    "###########",
    "###########",
    "###########",
    "###  #  ###",
    "##   #   ##",
]
BARRIER_PIXEL = 3


# ---------------------------------------------------------------------------
# Procedural audio: generated once at import time. The same numpy buffers feed
# the desktop (miniaudio) and web (Web Audio) backends unchanged.
# ---------------------------------------------------------------------------


def _envelope(n_frames: int, attack: float = 0.005, release: float = 0.05) -> np.ndarray:
    env = np.ones(n_frames, dtype=np.float32)
    a = min(int(SAMPLE_RATE * attack), n_frames // 4)
    r = min(int(SAMPLE_RATE * release), n_frames // 2)
    if a:
        env[:a] = np.linspace(0, 1, a, dtype=np.float32)
    if r:
        env[-r:] = np.linspace(1, 0, r, dtype=np.float32)
    return env


def _clip(name: str, mono: np.ndarray) -> AudioClip:
    """Wrap a mono float32 buffer as a centred stereo ``AudioClip``.

    ``AudioClip.from_pcm`` is the sanctioned way to hand the engine a
    pre-rendered buffer: it records the rate and channel count alongside the
    samples, so nothing downstream has to guess how to play them.
    """
    mono = np.clip(mono, -1.0, 1.0).astype(np.float32)
    interleaved = np.empty(mono.size * 2, dtype=np.float32)
    interleaved[0::2] = mono
    interleaved[1::2] = mono
    return AudioClip.from_pcm(interleaved, sample_rate=SAMPLE_RATE, channels=2, name=name)


def _make_shoot() -> AudioClip:
    duration = 0.10
    n = int(SAMPLE_RATE * duration)
    sweep = np.linspace(880.0, 220.0, n, dtype=np.float32)
    phase = 2 * np.pi * np.cumsum(sweep) / SAMPLE_RATE
    sig = 0.35 * np.sign(np.sin(phase)) * _envelope(n, 0.002, 0.05)
    return _clip("sfx:shoot", sig)


def _make_explosion() -> AudioClip:
    duration = 0.35
    n = int(SAMPLE_RATE * duration)
    noise = np.random.uniform(-1, 1, n).astype(np.float32)
    sweep = np.linspace(1.0, 0.2, n, dtype=np.float32)
    sig = 0.45 * noise * sweep * _envelope(n, 0.001, 0.15)
    return _clip("sfx:explosion", sig)


def _make_step(freq: float) -> AudioClip:
    duration = 0.08
    n = int(SAMPLE_RATE * duration)
    t = np.linspace(0, duration, n, dtype=np.float32)
    sig = 0.4 * np.sign(np.sin(2 * np.pi * freq * t)) * _envelope(n, 0.002, 0.02)
    return _clip(f"sfx:step:{freq:.0f}", sig)


def _make_ufo_loop() -> AudioClip:
    duration = 0.40
    n = int(SAMPLE_RATE * duration)
    t = np.linspace(0, duration, n, dtype=np.float32)
    # Wobble between 600 and 1100 Hz: classic UFO siren.
    freq = 850.0 + 250.0 * np.sin(2 * np.pi * 6.0 * t)
    phase = 2 * np.pi * np.cumsum(freq) / SAMPLE_RATE
    sig = 0.25 * np.sin(phase).astype(np.float32)
    return _clip("sfx:ufo_loop", sig)


def _make_ufo_hit() -> AudioClip:
    duration = 0.45
    n = int(SAMPLE_RATE * duration)
    t = np.linspace(0, duration, n, dtype=np.float32)
    # Three descending tones blended with noise for a "chord crash".
    tone = sum(np.sin(2 * np.pi * f * t) for f in (660.0, 440.0, 220.0)) / 3.0
    noise = np.random.uniform(-0.4, 0.4, n).astype(np.float32)
    sig = 0.4 * (tone + 0.5 * noise) * _envelope(n, 0.001, 0.2)
    return _clip("sfx:ufo_hit", sig)


SFX_SHOOT = _make_shoot()
SFX_EXPLOSION = _make_explosion()
SFX_STEPS = [_make_step(f) for f in (110.0, 92.5, 82.4, 73.4)]
SFX_UFO_LOOP = _make_ufo_loop()
SFX_UFO_HIT = _make_ufo_hit()


def play_sfx(parent: Node, stream: AudioClip, *, bus: str = "SFX", volume_db: float = 0.0) -> AudioPlayer:
    """Spawn a one-shot SFX player that removes itself when the clip ends."""
    return parent.add_child(
        AudioPlayer(stream=stream, bus=bus, volume_db=volume_db, autoplay=True, queue_free_on_end=True, name="SFX")
    )


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------


def draw_sprite(renderer, sprite, x, y, scale, colour):
    """Draw an 8x8 bit-pattern sprite using filled rects."""
    for row_i, row_bits in enumerate(sprite):
        for col in range(8):
            if row_bits & (1 << (7 - col)):
                renderer.draw_rect((x + col * scale, y + row_i * scale), (scale, scale), colour=colour, filled=True)


# ---------------------------------------------------------------------------
# Starfield: parallax background drawn beneath everything
# ---------------------------------------------------------------------------


class Starfield(Node2D):
    """Slow-scrolling parallax stars rendered in screen space."""

    # Stars drift down every frame (on_update mutates _stars), so on_draw must
    # re-run each frame under retained 2D.
    dynamic = True

    def __init__(self, count: int = 70, **kwargs):
        super().__init__(**kwargs)
        rng = random.Random(0xC0DE)  # deterministic so the field looks the same each run
        self._stars = [
            (rng.uniform(0, WIDTH), rng.uniform(0, HEIGHT), rng.uniform(0.25, 1.0), rng.uniform(0.2, 1.0))
            for _ in range(count)
        ]

    def on_update(self, dt: float):
        new_stars = []
        for x, y, brightness, parallax in self._stars:
            y += parallax * 18.0 * dt
            if y > HEIGHT:
                y -= HEIGHT
                x = random.uniform(0, WIDTH)
            new_stars.append((x, y, brightness, parallax))
        self._stars = new_stars

    def on_draw(self, renderer):
        for x, y, b, _p in self._stars:
            renderer.draw_rect((x, y), (1.5, 1.5), colour=(b, b, b, 1.0), filled=True)


# ---------------------------------------------------------------------------
# Alien
# ---------------------------------------------------------------------------


class Alien(Body2D):
    died = Signal()  # emits self when destroyed by a player bullet

    def __init__(self, alien_type: int = 0, **kwargs):
        super().__init__(radius=PIXEL * 4, **kwargs)
        self.add_to_group("aliens")
        frames, colour, points = ALIEN_TYPES[min(alien_type, 2)]
        self.frames = frames
        self.colour = colour
        self.points = points
        self.frame = 0  # animation frame, pushed by the formation via set_frame()

    def set_frame(self, frame: int):
        """Swap the animation frame and mark the sprite for redraw."""
        if frame != self.frame:
            self.frame = frame
            self.queue_redraw()

    def on_draw(self, renderer):
        wp = self.world_position
        draw_sprite(renderer, self.frames[self.frame], wp.x - PIXEL * 4, wp.y - PIXEL * 4, PIXEL, self.colour)


# ---------------------------------------------------------------------------
# AlienFormation
# ---------------------------------------------------------------------------


class AlienFormation(Node2D):
    speed = Property(28.0)
    wave_cleared = Signal()
    reached_bottom = Signal()

    def __init__(self, wave: int = 1, **kwargs):
        super().__init__(**kwargs)
        self._direction = 1
        self._wave = wave
        self._frame = 0
        self._step_index = 0
        self._move_accum = 0.0  # pixels travelled since last animation step
        self._step_cooldown = 0.0  # seconds remaining before next step is allowed

    def on_ready(self):
        for row in range(ALIEN_ROWS):
            for col in range(ALIEN_COLS):
                x = (col - ALIEN_COLS // 2) * ALIEN_SPACING_X
                y = (row - ALIEN_ROWS // 2) * ALIEN_SPACING_Y
                self.add_child(Alien(alien_type=ALIEN_ROW_TYPES[row], name=f"Alien_{row}_{col}", position=Vec2(x, y)))

    def on_update(self, dt: float):
        aliens = self.tree.group("aliens") if self.tree else []
        if not aliens:
            self.wave_cleared()
            return

        # Speed scales with fewer aliens + gentle wave progression.
        full_fleet = ALIEN_ROWS * ALIEN_COLS
        spd = (self.speed + (full_fleet - len(aliens)) * 4.0) * (1.0 + (self._wave - 1) * 0.10)
        dx = self._direction * spd * dt

        min_x = min(a.world_position.x for a in aliens)
        max_x = max(a.world_position.x for a in aliens)

        if (max_x + dx > WIDTH - 30 and self._direction > 0) or (min_x + dx < 30 and self._direction < 0):
            self._direction *= -1
            # Descend 22 px per edge bounce: enough to feel the fleet closing in,
            # small enough that a wave is still survivable.
            self.position.y += 22
            for a in aliens:
                if a.world_position.y > HEIGHT - 80:
                    self.reached_bottom()
                    return
        else:
            self.position.x += dx
            self._move_accum += abs(dx)

        # Pixel cadence drives the visual frame swap; a separate time cooldown
        # keeps the step audio from devolving into a buzz at end-of-wave speeds
        # (cap at ~8 Hz). Visual animation stays untied to the cooldown.
        self._step_cooldown = max(0.0, self._step_cooldown - dt)
        if self._move_accum >= 14.0:
            self._move_accum -= 14.0
            self._frame ^= 1
            for alien in aliens:
                alien.set_frame(self._frame)
            if self._step_cooldown <= 0.0:
                play_sfx(self, SFX_STEPS[self._step_index % 4], bus="SFX")
                self._step_index += 1
                self._step_cooldown = 0.12


# ---------------------------------------------------------------------------
# Player
# ---------------------------------------------------------------------------


class Player(Body2D):
    speed = Property(300.0)
    # Set while the cannon is respawning: the game skips hit tests and the
    # cannon blinks. The on_change hook restarts the blink from full brightness.
    invulnerable = Property(False, on_change="_on_invulnerable_changed")
    hit = Signal()
    fired = Signal()

    def __init__(self, **kwargs):
        super().__init__(radius=12, **kwargs)
        self.add_to_group("player")
        self.fire_timer = self.add_child(Timer(0.4, name="FireTimer"))
        self._invuln_timer = self.add_child(Timer(1.5, one_shot=True, name="InvulnTimer"))
        self._invuln_timer.timeout.connect(self._end_invulnerability)
        self._blink_phase = 0.0

    def on_ready(self):
        self.position = Vec2(WIDTH / 2, HEIGHT - 50)

    def begin_invulnerability(self, seconds: float):
        """Blink and ignore alien fire for ``seconds`` after a respawn."""
        self.invulnerable = True
        self._invuln_timer.start(seconds)

    def _end_invulnerability(self):
        self.invulnerable = False

    def _on_invulnerable_changed(self):
        self._blink_phase = 0.0
        self.queue_redraw()

    def on_fixed_update(self, dt: float):
        if self.invulnerable:
            self._blink_phase += dt
            self.queue_redraw()  # the blink is time-driven, so dirty the sprite by hand

        # Pointer controls: hold/drag to slide the cannon toward the pointer and
        # fire while held (web touch arrives as MouseButton.LEFT).
        pointer_held = Input.is_mouse_button_pressed(MouseButton.LEFT)
        if Input.is_action_pressed("move_left"):
            self.position.x -= self.speed * dt
        if Input.is_action_pressed("move_right"):
            self.position.x += self.speed * dt
        if pointer_held:
            step = self.speed * dt
            self.position.x += max(-step, min(step, float(Input.mouse_position.x) - self.position.x))
        self.position.x = max(20, min(WIDTH - 20, self.position.x))

        if (Input.is_action_pressed("fire") or pointer_held) and self.fire_timer.stopped:
            self.fire_timer.start()
            self.parent.add_child(
                Bullet(direction=-1, name="PBullet", position=Vec2(self.position.x, self.position.y - 15))
            )
            play_sfx(self, SFX_SHOOT, bus="SFX")
            self.fired()

    def on_draw(self, renderer):
        if self.invulnerable and int(self._blink_phase * 8) % 2 == 0:
            return  # blink while respawning
        x, y = self.position.x, self.position.y
        green = (0.0, 1.0, 0.0, 1.0)
        renderer.draw_rect((x - 13, y - 4), (26, 8), colour=green, filled=True)
        renderer.draw_rect((x - 3, y - 12), (6, 8), colour=green, filled=True)
        renderer.draw_rect((x - 1, y - 15), (2, 3), colour=green, filled=True)


# ---------------------------------------------------------------------------
# Bullet
# ---------------------------------------------------------------------------


class Bullet(Body2D):
    def __init__(self, direction: int = 1, **kwargs):
        super().__init__(radius=3, **kwargs)
        self.direction = direction
        self.speed = 400.0
        self.add_to_group("player_bullets" if direction < 0 else "alien_bullets")

    def on_fixed_update(self, dt: float):
        self.position.y += self.direction * self.speed * dt
        if self.position.y < 0 or self.position.y > HEIGHT:
            self.destroy()

    def on_draw(self, renderer):
        colour = (1.0, 1.0, 1.0, 1.0) if self.direction < 0 else (1.0, 1.0, 0.2, 1.0)
        renderer.draw_rect((self.position.x - 1, self.position.y - 4), (2, 8), colour=colour, filled=True)


# ---------------------------------------------------------------------------
# Barrier
# ---------------------------------------------------------------------------


class Barrier(Node2D):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.add_to_group("barriers")
        self.pixels = [[ch == "#" for ch in row] for row in BARRIER_PATTERN]

    def hit(self, pos) -> bool:
        bx, by = self.position.x, self.position.y
        pw, ph = len(self.pixels[0]), len(self.pixels)
        col = int((pos.x - bx) / BARRIER_PIXEL)
        row = int((pos.y - by) / BARRIER_PIXEL)
        if 0 <= row < ph and 0 <= col < pw and self.pixels[row][col]:
            for dr in range(-1, 2):
                for dc in range(-1, 2):
                    r, c = row + dr, col + dc
                    if 0 <= r < ph and 0 <= c < pw:
                        self.pixels[r][c] = False
            return True
        return False

    def on_draw(self, renderer):
        barrier_colour = (0.0, 1.0, 0.39, 1.0)
        bx, by = self.position.x, self.position.y
        for row_i, row in enumerate(self.pixels):
            for col_i, alive in enumerate(row):
                if alive:
                    renderer.draw_rect(
                        (bx + col_i * BARRIER_PIXEL, by + row_i * BARRIER_PIXEL),
                        (BARRIER_PIXEL, BARRIER_PIXEL),
                        colour=barrier_colour,
                        filled=True,
                    )


# ---------------------------------------------------------------------------
# Floating effects
# ---------------------------------------------------------------------------


class ScorePopup(Node2D):
    def __init__(self, points: int = 0, colour=(1.0, 1.0, 1.0), **kwargs):
        super().__init__(**kwargs)
        self._text = f"+{points}"
        self._colour = colour
        self._elapsed = 0.0
        self._duration = 0.8
        t = self.add_child(Timer(self._duration, name="Life"))
        t.timeout.connect(self.destroy)
        t.start()

    def on_update(self, dt: float):
        self._elapsed += dt
        self.position.y -= 40 * dt

    def on_draw(self, renderer):
        alpha = max(0.0, 1.0 - self._elapsed / self._duration)
        r, g, b = self._colour
        renderer.draw_text(self._text, (self.position.x, self.position.y), scale=2, colour=(r, g, b, alpha))


class Explosion(Node2D):
    # The particles expand and fade from a plain elapsed-time attribute while the
    # node stays put, so nothing dirties the draw: opt into per-frame redraws.
    dynamic = True

    def __init__(self, colour=(1.0, 1.0, 1.0), **kwargs):
        super().__init__(**kwargs)
        self._colour = colour
        self._elapsed = 0.0
        self._duration = 0.4
        self._particles = [(random.uniform(-1, 1), random.uniform(-1, 1), random.uniform(40, 100)) for _ in range(8)]
        t = self.add_child(Timer(self._duration, name="Life"))
        t.timeout.connect(self.destroy)
        t.start()

    def on_update(self, dt: float):
        self._elapsed += dt

    def on_draw(self, renderer):
        alpha = max(0.0, 1.0 - self._elapsed / self._duration)
        r, g, b = self._colour
        colour = (r, g, b, alpha)
        px, py = self.position.x, self.position.y
        for dx, dy, spd in self._particles:
            dist = spd * self._elapsed
            renderer.draw_rect((px + dx * dist - 1.5, py + dy * dist - 1.5), (3, 3), colour=colour, filled=True)


# ---------------------------------------------------------------------------
# MysteryShip
# ---------------------------------------------------------------------------


class MysteryShip(Body2D):
    def __init__(self, points: int = 100, **kwargs):
        super().__init__(radius=PIXEL * 4, **kwargs)
        self.add_to_group("mystery")
        self.points = points
        self.colour = (1.0, 0.2, 1.0)
        self._dir = 1 if random.random() < 0.5 else -1
        self.position = Vec2(-30 if self._dir > 0 else WIDTH + 30, 40)
        # Looping siren: quieter than other SFX (closer to background music) so it
        # doesn't dominate the mix while the ship transits the screen. As a child
        # of the ship it stops itself when the ship leaves the tree, whether that
        # is a bullet hit or the exit below.
        self.add_child(
            AudioPlayer(stream=SFX_UFO_LOOP, bus="SFX", loop=True, autoplay=True, volume_db=-6.0, name="Siren")
        )

    def on_update(self, dt: float):
        self.position.x += self._dir * 120 * dt
        if (self._dir > 0 and self.position.x > WIDTH + 40) or (self._dir < 0 and self.position.x < -40):
            self.destroy()

    def on_draw(self, renderer):
        draw_sprite(renderer, ALIEN_UFO, self.position.x - PIXEL * 4, self.position.y - PIXEL * 4, PIXEL, self.colour)


# ---------------------------------------------------------------------------
# Wave banner: shown briefly between waves
# ---------------------------------------------------------------------------


class WaveBanner(Control):
    """Full-width "WAVE n" banner shown for a moment between waves.

    ``AnchorPreset.CENTER`` collapses both anchor pairs onto the centre point, so
    the box comes from the margins: set all four, not ``size``.
    """

    def __init__(self, wave: int, on_done, **kwargs):
        super().__init__(**kwargs)
        self.set_anchor_preset(AnchorPreset.CENTER)
        self.margin_left = -WIDTH / 2
        self.margin_right = WIDTH / 2
        self.margin_top = -40
        self.margin_bottom = 40
        label = self.add_child(Label(f"WAVE {wave}", name="WaveLabel"))
        label.font_size = 56
        label.alignment = "center"
        label.set_anchor_preset(AnchorPreset.FULL_RECT)
        label.text_colour = (1.0, 1.0, 1.0, 1.0)
        self._timer = self.add_child(Timer(1.5, one_shot=True, autostart=True, name="Life"))

        def _finish():
            on_done()
            self.destroy()

        self._timer.timeout.connect(_finish)


# ---------------------------------------------------------------------------
# Audio settings popup
# ---------------------------------------------------------------------------


def _slider_to_db(v: float) -> float:
    """Map slider 0..100 to bus volume in dB. 0 → -40 (near-silent), 100 → 0."""
    return -40.0 + (v / 100.0) * 40.0


def _db_to_slider(db: float) -> float:
    return max(0.0, min(100.0, (db + 40.0) * 100.0 / 40.0))


class AudioSettingsPopup(Control):
    """Modal popup with Music/SFX volume sliders.

    Shown through the overlay layer: ``show_overlay("blocking", inert=True)``
    supplies the dim scrim, freezes the scene underneath and keeps input from
    reaching it, so the popup only has to lay out its own widgets.
    """

    closed = Signal()

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_anchor_preset(AnchorPreset.FULL_RECT)

        # Centred dialog body. A collapsed anchor pair (CENTER here, and the
        # TOP_WIDE / BOTTOM_WIDE children below on their vertical axis) takes its
        # box from the two margins on that axis, so both are set.
        body = self.add_child(Panel(name="Body"))
        body.set_anchor_preset(AnchorPreset.CENTER)
        body.margin_left = -180
        body.margin_right = 180
        body.margin_top = -120
        body.margin_bottom = 120
        body.bg_colour = (0.08, 0.08, 0.12, 0.95)

        title = body.add_child(Label("AUDIO", name="Title"))
        title.font_size = 32
        title.alignment = "center"
        title.set_anchor_preset(AnchorPreset.TOP_WIDE)
        title.margin_top = 12
        title.margin_bottom = 52

        layout = AudioBusLayout.get_default()
        music_db = layout.get_bus("Music").volume_db
        sfx_db = layout.get_bus("SFX").volume_db

        self._music_slider = self._row(body, "MUSIC", _db_to_slider(music_db), 70, lambda v: self._set_bus("Music", v))
        self._sfx_slider = self._row(body, "SFX", _db_to_slider(sfx_db), 130, lambda v: self._set_bus("SFX", v))

        back = body.add_child(Button("BACK", name="Back"))
        back.set_anchor_preset(AnchorPreset.BOTTOM_WIDE)
        back.margin_left = 120
        back.margin_right = 120
        back.margin_top = -52
        back.margin_bottom = -16
        back.pressed.connect(self._close)

    def _row(self, parent: Control, label: str, value: float, top_y: float, on_change) -> Slider:
        lab = parent.add_child(Label(label))
        lab.font_size = 18
        lab.set_anchor_preset(AnchorPreset.TOP_LEFT)
        lab.margin_left = 24
        lab.margin_top = top_y
        lab.size = Vec2(80, 28)

        slider = parent.add_child(Slider(0, 100, value=value, name=f"Slider{label}"))
        slider.set_anchor_preset(AnchorPreset.TOP_LEFT)
        slider.margin_left = 120
        slider.margin_top = top_y + 4
        slider.size = Vec2(220, 20)
        slider.value_changed.connect(on_change)
        return slider

    @staticmethod
    def _set_bus(name: str, slider_value: float):
        bus = AudioBusLayout.get_default().get_bus(name)
        bus.volume_db = _slider_to_db(slider_value)

    def _close(self):
        self.closed()
        if self.is_overlay_open:
            self.close_overlay()
        self.destroy()


# ---------------------------------------------------------------------------
# MainMenu
# ---------------------------------------------------------------------------


class MainMenu(Node):
    input_actions = INPUT_ACTIONS

    def __init__(self, **kwargs):
        super().__init__(name="MainMenu", **kwargs)
        self._popup_open = False
        self._blink_on = True
        self._blink_timer = self.add_child(Timer(0.5, one_shot=False, autostart=True, name="Blink"))
        self._blink_timer.timeout.connect(self._toggle_blink)

        # Real button so the mixer is reachable with a mouse or a finger, not
        # only with the O key.
        self._options_button = self.add_child(Button("AUDIO OPTIONS (O)", on_press=self._open_popup, name="Options"))
        self._options_button.set_anchor_preset(AnchorPreset.CENTER_BOTTOM)
        self._options_button.font_size = 18
        self._options_button.margin_left = -120
        self._options_button.margin_right = 120
        self._options_button.margin_top = -72
        self._options_button.margin_bottom = -30

    def _toggle_blink(self):
        self._blink_on = not self._blink_on
        self.queue_redraw()  # blink flips on a timer event, not per-frame -> dirty here

    def on_ready(self):
        self.add_child(Starfield(name="Starfield"))

    def _pointer_over_options(self) -> bool:
        """True while the pointer sits on the options button.

        ``start`` is bound to the left button so a tap anywhere begins a game;
        this keeps a tap on the button from doing both at once.
        """
        x, y, w, h = self._options_button.get_global_rect()
        p = Input.mouse_position
        return x <= p.x <= x + w and y <= p.y <= y + h

    def on_update(self, dt: float):
        if self._popup_open:
            return
        if Input.is_action_just_pressed("start") and not self._pointer_over_options():
            self.tree.change_scene(Game())
        elif Input.is_action_just_pressed("options"):
            self._open_popup()

    def _open_popup(self):
        if self._popup_open:
            return
        popup = self.add_child(AudioSettingsPopup(name="AudioSettings"))
        popup.show_overlay("blocking", inert=True, dismiss=False)
        popup.closed.connect(self._on_popup_closed)
        self._popup_open = True
        self._options_button.visible = False
        self.queue_redraw()  # menu copy must clear so it can't bleed through the scrim

    def _on_popup_closed(self):
        self._popup_open = False
        self._options_button.visible = True
        self.queue_redraw()  # repaint the menu now the popup is gone

    def on_draw(self, renderer):
        if self._popup_open:
            return  # popup owns the screen; menu copy would bleed through the backdrop

        title = "SPACE INVADERS"
        tw = renderer.text_width(title, 5)
        renderer.draw_text(title, (WIDTH // 2 - tw // 2, 80), scale=5, colour=(1.0, 1.0, 1.0))

        y = 200
        for frames, colour, points in ALIEN_TYPES:
            draw_sprite(renderer, frames[0], WIDTH // 2 - 80, y, 3, colour)
            renderer.draw_text(f"= {points} PTS", (WIDTH // 2 - 45, y + 4), scale=2, colour=(1.0, 1.0, 1.0))
            y += 46
        draw_sprite(renderer, ALIEN_UFO, WIDTH // 2 - 80, y, 3, (1.0, 0.2, 1.0))
        renderer.draw_text("= ??? PTS", (WIDTH // 2 - 45, y + 4), scale=2, colour=(1.0, 1.0, 1.0))

        if self._blink_on:
            prompt = "ENTER OR CLICK TO START"
            pw = renderer.text_width(prompt, 3)
            renderer.draw_text(prompt, (WIDTH // 2 - pw // 2, 396), scale=3, colour=(0.78, 0.78, 0.78))
        for i, line in enumerate(("ARROWS / A-D  MOVE      SPACE  FIRE", "OR HOLD THE POINTER TO MOVE AND FIRE")):
            lw = renderer.text_width(line, 2)
            renderer.draw_text(line, (WIDTH // 2 - lw // 2, 456 + i * 34), scale=2, colour=(0.6, 0.6, 0.6))


# ---------------------------------------------------------------------------
# Game
# ---------------------------------------------------------------------------


class Game(Node):
    input_actions = INPUT_ACTIONS

    def __init__(self, **kwargs):
        super().__init__(name="Game", **kwargs)
        self.score = 0
        self.lives = 3
        self._wave = 0
        self._shots_fired = 0
        self._between_waves = False

        self.add_child(Starfield(name="Starfield"))

        self.camera = self.add_child(Camera2D(name="Camera", position=Vec2(WIDTH / 2, HEIGHT / 2)))
        self.player = self.add_child(Player(name="Player"))
        self.player.fired.connect(self._on_player_fired)
        self.player.hit.connect(self._on_player_hit)
        self.formation: AlienFormation | None = None
        self._shoot_timer: Timer | None = None

        # HUD: Label controls with anchors so layout follows the window.
        self._score_label = self._make_hud_label("SCORE 00000", AnchorPreset.TOP_LEFT, left=10, width=170)
        self._wave_label = self._make_hud_label(
            "WAVE 1", AnchorPreset.CENTER_TOP, left=-70, width=140, align="center", colour=(0.78, 0.78, 0.78, 1.0)
        )
        self._lives_label = self._make_hud_label("LIVES 3", AnchorPreset.TOP_RIGHT, left=-150, width=140, align="right")

        self._mystery_timer = self.add_child(
            Timer(random.uniform(15, 30), one_shot=True, autostart=True, name="MysteryTimer")
        )
        self._mystery_timer.timeout.connect(self._spawn_mystery)

    def _make_hud_label(
        self,
        text: str,
        preset: AnchorPreset,
        *,
        left: float,
        width: float,
        align: str = "left",
        colour=(1.0, 1.0, 1.0, 1.0),
    ) -> Label:
        """One anchored HUD label, ``left`` pixels from its anchor.

        A preset whose anchors collapse to a point (CENTER_TOP, TOP_RIGHT) takes
        its box from the margin pair while TOP_LEFT takes it from ``size``, so
        both are set and kept in agreement.
        """
        height = 28.0
        lbl = self.add_child(Label(text, name=f"HUD_{text.split()[0]}"))
        lbl.set_anchor_preset(preset)
        lbl.font_size = 22
        lbl.alignment = align
        lbl.text_colour = colour
        lbl.size = Vec2(width, height)
        lbl.margin_left = left
        lbl.margin_right = left + width
        lbl.margin_top = 10
        lbl.margin_bottom = 10 + height
        return lbl

    def on_ready(self):
        self._spawn_barriers()
        self._next_wave()

    def _next_wave(self):
        self._wave += 1
        self._between_waves = False
        self.formation = self.add_child(
            AlienFormation(
                wave=self._wave, name="Formation", position=Vec2(WIDTH // 2, 80 + (ALIEN_ROWS // 2) * ALIEN_SPACING_Y)
            )
        )
        self.formation.wave_cleared.connect(self._on_wave_cleared)
        self.formation.reached_bottom.connect(self._on_game_over)
        # Signals are per-instance and disconnect themselves when either end is
        # destroyed, so the wave can be wired up and then forgotten.
        for alien in self.formation.children:
            if isinstance(alien, Alien):
                alien.died.connect(self._on_alien_killed)

        # Shoot interval slows the floor a bit so wave 5+ stays beatable.
        interval = max(0.45, 1.10 - (self._wave - 1) * 0.10)
        self._shoot_timer = self.add_child(Timer(interval, one_shot=False, autostart=True, name="ShootTimer"))
        self._shoot_timer.timeout.connect(self._alien_shoot)

    def _on_wave_cleared(self):
        if self._between_waves:
            return
        self._between_waves = True
        if self._shoot_timer:
            self._shoot_timer.destroy()
            self._shoot_timer = None
        if self.formation:
            self.formation.destroy()
            self.formation = None
        self.add_child(WaveBanner(self._wave + 1, self._next_wave, name="WaveBanner"))

    def _on_game_over(self):
        self.tree.change_scene(GameOver(self.score))

    def _alien_shoot(self):
        aliens = self.tree.group("aliens") if self.tree else []
        if not aliens:
            return
        # Pick the bottom-most alien per column so back rows can't friendly-fire.
        columns: dict[int, Alien] = {}
        for a in aliens:
            col = round(a.world_position.x / ALIEN_SPACING_X)
            existing = columns.get(col)
            if existing is None or a.world_position.y > existing.world_position.y:
                columns[col] = a
        shooter = random.choice(list(columns.values()))
        wp = shooter.world_position
        self.add_child(Bullet(direction=1, name="ABullet", position=Vec2(wp.x, wp.y + 10)))

    def _spawn_barriers(self):
        barrier_w = len(BARRIER_PATTERN[0]) * BARRIER_PIXEL
        total_w = 4 * barrier_w
        gap = (WIDTH - total_w) / 5
        for i in range(4):
            bx = gap + i * (barrier_w + gap)
            self.add_child(Barrier(name=f"Barrier_{i}", position=Vec2(bx, HEIGHT - 130)))

    def _spawn_mystery(self):
        points = MYSTERY_POINTS_CYCLE[self._shots_fired % len(MYSTERY_POINTS_CYCLE)]
        self.add_child(MysteryShip(points=points, name="Mystery"))
        self._mystery_timer.start(random.uniform(15, 30))

    def _on_player_fired(self):
        self._shots_fired += 1

    def _on_alien_killed(self, alien: Alien):
        wp = Vec2(alien.world_position)
        self.score += alien.points
        self.add_child(ScorePopup(points=alien.points, colour=alien.colour, position=wp))
        self.add_child(Explosion(colour=alien.colour, position=wp))
        play_sfx(self, SFX_EXPLOSION, bus="SFX", volume_db=-3.0)

    def _on_player_hit(self):
        self.camera.shake(intensity=4.0, duration=0.3)
        wp = Vec2(self.player.position)
        self.add_child(Explosion(colour=(0.0, 1.0, 0.4), position=wp))
        play_sfx(self, SFX_EXPLOSION, bus="SFX", volume_db=-3.0)
        self.lives -= 1
        if self.lives <= 0:
            self.tree.change_scene(GameOver(self.score))
            return
        self.player.position = Vec2(WIDTH / 2, HEIGHT - 50)
        self.player.begin_invulnerability(1.5)

    def on_update(self, dt: float):
        self._score_label.text = f"SCORE {self.score:05d}"
        self._wave_label.text = f"WAVE {self._wave}"
        self._lives_label.text = f"LIVES {self.lives}"

    def on_fixed_update(self, dt: float):
        tree = self.tree
        if not tree:
            return

        for bullet in tree.group("player_bullets"):
            # Aliens
            hits = bullet.get_overlapping(group="aliens")
            if hits:
                alien = hits[0]
                alien.died(alien)
                alien.destroy()
                bullet.destroy()
                continue
            # Mystery ship
            hits = bullet.get_overlapping(group="mystery")
            if hits:
                mystery = hits[0]
                wp = Vec2(mystery.position)
                self.score += mystery.points
                self.add_child(ScorePopup(points=mystery.points, colour=mystery.colour, position=wp))
                self.add_child(Explosion(colour=mystery.colour, position=wp))
                play_sfx(self, SFX_UFO_HIT, bus="SFX", volume_db=-3.0)
                mystery.destroy()
                bullet.destroy()
                continue
            # Mid-air interception with alien bullets: both vanish in a spark.
            hits = bullet.get_overlapping(group="alien_bullets")
            if hits:
                other = hits[0]
                self.add_child(Explosion(colour=(1.0, 1.0, 1.0), position=Vec2(bullet.position)))
                bullet.destroy()
                other.destroy()
                continue
            # Barriers
            for barrier in tree.group("barriers"):
                if barrier.hit(bullet.position):
                    bullet.destroy()
                    break

        for bullet in tree.group("alien_bullets"):
            if not self.player.invulnerable:
                hits = bullet.get_overlapping(group="player")
                if hits:
                    bullet.destroy()
                    self.player.hit()  # connected to _on_player_hit in __init__
                    continue
            for barrier in tree.group("barriers"):
                if barrier.hit(bullet.position):
                    bullet.destroy()
                    break


# ---------------------------------------------------------------------------
# GameOver
# ---------------------------------------------------------------------------


class GameOver(Node):
    input_actions = INPUT_ACTIONS

    def __init__(self, score: int = 0, **kwargs):
        super().__init__(name="GameOver", **kwargs)
        self.score = score
        self._blink_on = True
        self._blink_timer = self.add_child(Timer(0.5, one_shot=False, autostart=True, name="Blink"))
        self._blink_timer.timeout.connect(self._toggle_blink)

    def _toggle_blink(self):
        self._blink_on = not self._blink_on
        self.queue_redraw()  # blink flips on a timer event, not per-frame -> dirty here

    def on_ready(self):
        self.add_child(Starfield(name="Starfield"))

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("start"):
            self.tree.change_scene(MainMenu())

    def on_draw(self, renderer):
        title = "GAME OVER"
        tw = renderer.text_width(title, 5)
        renderer.draw_text(title, (WIDTH // 2 - tw // 2, 180), scale=5, colour=(1.0, 0.2, 0.2))

        score_text = f"SCORE  {self.score:05d}"
        sw = renderer.text_width(score_text, 3)
        renderer.draw_text(score_text, (WIDTH // 2 - sw // 2, 300), scale=3, colour=(1.0, 1.0, 1.0))

        if self._blink_on:
            prompt = "ENTER OR CLICK TO CONTINUE"
            pw = renderer.text_width(prompt, 2)
            renderer.draw_text(prompt, (WIDTH // 2 - pw // 2, 420), scale=2, colour=(0.78, 0.78, 0.78))


# ---------------------------------------------------------------------------
# Main
# ---------------------------------------------------------------------------


if __name__ == "__main__":
    App("Space Invaders", WIDTH, HEIGHT, target_fps=30).run(MainMenu())