323. Console планирует sprite zero hit на каждый кадр

Автоматически планировать sprite 0 hit при продвижении Console на кадр вперёд.

Урок 323 из 356 · tests/chapter_11_sprite_zero_hit/test_323_console_schedules_sprite_zero_hit_per_frame.py

Файл для обновления

emulator/console.py

Зачем нужен этот шаг

Предыдущие шаги предоставляют все необходимые механизмы

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

Этот шаг соединяет их с циклом кадра.

Архитектурное решение

Мы намеренно помещаем подготовку sprite zero hit внутрь Console.step_until_next_frame(). Вызывающий код, такой как main.py, должен просить Console продвинуться на один полный эмулируемый кадр, не зная, какие внутренние события тайминга PPU нужно подготовить заранее.

Это позволяет main.py оставаться сосредоточенным на обязанностях фронтенда:

input
display
FPS reporting
frame pacing

Console владеет координацией эмулятора на уровне кадра.

Предлагаемое изменение реализации

# --- 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:
        ...

Почему до цикла пошагового выполнения? CPU может опрашивать PPUSTATUS во время эмуляции кадра. Будущее срабатывание должно быть запланировано до того, как выполнение CPU/PPU достигнет перекрывающегося пикселя.

Контрольная точка ручной проверки совместимости

После этого шага студенты могут временно изменить локальный путь к ручному ROM в main.py на собственную легальную копию:

Предлагаемое изменение реализации в main.py:

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

Затем запустить с помощью PyPy

Linux/macOS

sh launcher.sh

Командная строка Windows

launcher.cmd

Ожидаемое улучшение при ручной проверке

Super Mario Bros. использует sprite 0 hit как сигнал тайминга PPU. Теперь, когда срабатывание обнаруживается, планируется и предоставляется через PPUSTATUS, титульный экран/меню должны продвигаться дальше, Марио должен появиться, а ввод с контроллера должен стать рабочим.

Известное оставшееся ограничение

Когда Марио движется по горизонтали, сцена может по-прежнему выглядеть некорректно, поскольку текущий рендерер фона ещё не применяет состояние прокрутки PPU для выбора и смещения видимой области nametable. Sprite 0 hit включает путь тайминга игры; он не реализует горизонтальную прокрутку фона.

Правило легальности/тестирования

Super Mario Bros.nes — это только ручной эксперимент совместимости, предоставляемый пользователем. Не коммитьте ROM и не требуйте его в автоматических тестах. Эти тесты используют поддельные объекты CPU/PPU и проверяют только поведение координации.

Вне рамок

горизонтальная/вертикальная прокрутка
тонкая прокрутка по X
композиция соседних nametable
точное поведение OAM Y+1
правила левого края PPUMASK
исключение sprite 0 hit при x=255
фикстуры коммерческих ROM

Запустить этот урок

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

Пример реализации

Предлагаемое изменение реализации

# --- 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:
        ...

Показать код тестаtest_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()

Тестовые функции (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