323. Console programa el sprite zero hit por frame

Programar el sprite 0 hit automáticamente cuando Console avanza un frame.

Lección 323 de 356 · tests/chapter_11_sprite_zero_hit/test_323_console_schedules_sprite_zero_hit_per_frame.py

Archivo a actualizar

emulator/console.py

Por qué existe este paso

Los pasos anteriores proporcionan todos los mecanismos necesarios

ppu_sprite_zero_hit_position(ppu)
    -> extracts current PPU state and finds the overlap position

ppu.set_sprite_zero_hit_position(position)
    -> stores the future timing event

ppu.step(...)
    -> sets PPUSTATUS bit 6 when timing reaches that position

Este paso los conecta al bucle de frames.

Decisión de arquitectura

Ponemos la preparación del sprite zero hit dentro de Console.step_until_next_frame() de forma intencionada. Un código llamante como main.py debe pedir a Console que avance un frame emulado completo sin saber qué eventos de timing internos del PPU deben prepararse primero.

Esto mantiene main.py centrado en las responsabilidades del frontend:

input
display
FPS reporting
frame pacing

Console es el propietario de la coordinación del emulador a nivel de frame.

Cambio de implementación sugerido

# --- NEW LINE ---
from emulator.rendering.sprite_zero_hit import ppu_sprite_zero_hit_position
# --- END NEW LINE ---


def step_until_next_frame(
    self,
    max_cpu_instructions: int | None = None,
) -> int:
    # --- NEW BLOCK ---
    position = ppu_sprite_zero_hit_position(self.ppu)
    self.ppu.set_sprite_zero_hit_position(position)
    # --- END NEW BLOCK ---

    start_frame = self.ppu.frame
    executed = 0

    while self.ppu.frame == start_frame:
        ...

¿Por qué antes del bucle de pasos? La CPU puede consultar PPUSTATUS mientras se emula el frame. El hit futuro debe programarse antes de que la ejecución CPU/PPU alcance el píxel solapado.

Punto de comprobación manual de compatibilidad

Después de este paso, los estudiantes pueden cambiar temporalmente la ruta local de la ROM manual en main.py por su propia copia legal:

Cambio de implementación sugerido en main.py:

ROM_PATH = Path("Super Mario Bros.nes")

Después, ejecuta con PyPy

Linux/macOS

sh launcher.sh

Símbolo del sistema de Windows

launcher.cmd

Mejora manual esperada

Super Mario Bros. usa el sprite 0 hit como señal de timing del PPU. Con el hit ahora detectado, programado y expuesto a través de PPUSTATUS, la pantalla de título/menú debería avanzar más, Mario debería aparecer y la entrada del mando debería volverse utilizable.

Limitación conocida restante

Cuando Mario avanza horizontalmente, la escena aún puede verse incorrecta porque el renderizador de fondo actual todavía no aplica el estado de scrolling del PPU para seleccionar y desplazar la región visible del nametable. El sprite 0 hit habilita la ruta de timing del juego; no implementa el scrolling horizontal del fondo.

Regla legal y de testeo

Super Mario Bros.nes es solo un experimento manual de compatibilidad proporcionado por el usuario. No hagas commit de la ROM y no la exijas en los tests automatizados. Estos tests usan objetos CPU/PPU falsos y solo comprueban el comportamiento de coordinación.

Fuera del alcance

scrolling horizontal/vertical
scrolling X fino
composición de nametables adyacentes
comportamiento exacto de Y+1 de OAM
reglas del borde izquierdo de PPUMASK
excepción del sprite 0 hit en x=255
fixtures de ROM comerciales

Ejecutar esta lección

uv run pytest tests/chapter_11_sprite_zero_hit/test_323_console_schedules_sprite_zero_hit_per_frame.py -v

Implementación de ejemplo

Cambio de implementación sugerido

# --- NEW LINE ---
from emulator.rendering.sprite_zero_hit import ppu_sprite_zero_hit_position
# --- END NEW LINE ---


def step_until_next_frame(
    self,
    max_cpu_instructions: int | None = None,
) -> int:
    # --- NEW BLOCK ---
    position = ppu_sprite_zero_hit_position(self.ppu)
    self.ppu.set_sprite_zero_hit_position(position)
    # --- END NEW BLOCK ---

    start_frame = self.ppu.frame
    executed = 0

    while self.ppu.frame == start_frame:
        ...

Ver código del testtest_323_console_schedules_sprite_zero_hit_per_frame.py

import inspect
from pathlib import Path

import emulator.console as console_module
from emulator.console import Console


class FakeCPU:
    def __init__(self, events: list[str]):
        self.events = events

    def step(self) -> int:
        self.events.append("cpu_step")
        return 2

    def interrupt_nmi(self) -> None:
        self.events.append("nmi")


class FakePPU:
    def __init__(self, events: list[str]):
        self.events = events
        self.frame = 0
        self.nmi_requested = False
        self.received_position = "not-set"

    def set_sprite_zero_hit_position(self, position) -> None:
        self.events.append("set_position")
        self.received_position = position

    def step(self, cycles: int) -> None:
        self.events.append("ppu_step")
        self.frame += 1


def make_fake_console() -> tuple[Console, FakePPU, list[str]]:
    events: list[str] = []
    cpu = FakeCPU(events)
    ppu = FakePPU(events)
    console = Console(cpu=cpu, ppu=ppu)
    return console, ppu, events


def test_console_computes_sprite_zero_hit_position_before_advancing_frame(monkeypatch):
    """
    Objective:
    Frame-level overlap extraction must happen before the first CPU instruction of
    the frame.
    """
    console, _ppu, events = make_fake_console()

    def fake_ppu_sprite_zero_hit_position(ppu):
        events.append("find_position")
        return (40, 30)

    monkeypatch.setattr(
        console_module,
        "ppu_sprite_zero_hit_position",
        fake_ppu_sprite_zero_hit_position,
    )

    console.step_until_next_frame()

    assert events == [
        "find_position",
        "set_position",
        "cpu_step",
        "ppu_step",
    ]


def test_console_forwards_exact_overlap_position_to_ppu(monkeypatch):
    """
    Objective:
    Console coordinates the helpers but must not alter the detected screen
    coordinate.
    """
    console, ppu, _events = make_fake_console()
    expected_position = (123, 45)

    monkeypatch.setattr(
        console_module,
        "ppu_sprite_zero_hit_position",
        lambda received_ppu: expected_position,
    )

    console.step_until_next_frame()

    assert ppu.received_position is expected_position


def test_console_forwards_none_when_frame_has_no_overlap(monkeypatch):
    """
    Objective:
    A frame without sprite 0/background overlap should explicitly clear any future
    scheduled position by forwarding None.
    """
    console, ppu, _events = make_fake_console()

    monkeypatch.setattr(
        console_module,
        "ppu_sprite_zero_hit_position",
        lambda received_ppu: None,
    )

    console.step_until_next_frame()

    assert ppu.received_position is None


def test_sprite_zero_hit_preparation_preserves_instruction_count_result(monkeypatch):
    """
    Objective:
    Adding frame preparation must not change the existing return contract of
    step_until_next_frame().
    """
    console, _ppu, _events = make_fake_console()

    monkeypatch.setattr(
        console_module,
        "ppu_sprite_zero_hit_position",
        lambda received_ppu: None,
    )

    executed = console.step_until_next_frame()

    assert executed == 1


def test_main_does_not_need_to_know_sprite_zero_hit_internals():
    """
    Objective:
    The frontend should continue calling only Console.step_until_next_frame() rather
    than manually finding or scheduling sprite 0 hit.
    """
    source = Path("main.py").read_text()

    assert "console.step_until_next_frame()" in source
    assert "ppu_sprite_zero_hit_position" not in source
    assert "set_sprite_zero_hit_position" not in source


def test_console_schedules_position_before_existing_frame_loop():
    """
    Objective:
    Preserve the source-level timing invariant even if implementation details around
    the loop evolve later.
    """
    source = inspect.getsource(Console.step_until_next_frame)

    find_index = source.index("ppu_sprite_zero_hit_position(self.ppu)")
    set_index = source.index("self.ppu.set_sprite_zero_hit_position(position)")
    loop_index = source.index("while self.ppu.frame == start_frame")

    assert find_index < set_index < loop_index


def test_sprite_zero_hit_frame_coordination_keeps_pygame_outside_core():
    """
    Objective:
    Sprite-zero-hit scheduling is emulator behavior and must not introduce pygame
    into Console, PPU, or rendering helpers.
    """
    core_files = [
        Path("emulator/console.py"),
        Path("emulator/ppu/ppu.py"),
        Path("emulator/rendering/sprite_zero_hit.py"),
    ]

    for file_path in core_files:
        assert "import pygame" not in file_path.read_text()

Funciones de test (7)

test_console_computes_sprite_zero_hit_position_before_advancing_frame
test_console_forwards_exact_overlap_position_to_ppu
test_console_forwards_none_when_frame_has_no_overlap
test_sprite_zero_hit_preparation_preserves_instruction_count_result
test_main_does_not_need_to_know_sprite_zero_hit_internals
test_console_schedules_position_before_existing_frame_loop
test_sprite_zero_hit_frame_coordination_keeps_pygame_outside_core