323. Console 按帧调度精灵零命中

在 Console 推进一帧时自动调度精灵 0 命中。

第 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

本步骤将它们连接到帧循环中。

架构决策

我们有意将精灵零命中的准备工作放在 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 执行到达重叠像素之前调度好这次未来的命中。

手动兼容性检查点

完成本步骤后,学生可以临时将 main.py 中本地手动 ROM 路径改为自己合法拥有的副本:

main.py 中建议的实现改动:

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

然后用 PyPy 运行

Linux/macOS

sh launcher.sh

Windows 命令提示符

launcher.cmd

预期的手动改进效果

《超级马里奥兄弟》使用精灵 0 命中作为 PPU 时序信号。现在该命中已被检测、调度并通过 PPUSTATUS 暴露出来,标题/菜单界面应能进一步推进,马里奥应会出现,手柄输入也应变得可用。

已知的遗留限制

当马里奥水平前进时,场景可能仍然显示不正确,因为当前的背景渲染器尚未应用 PPU 卷动状态来选择和偏移可见的名称表区域。精灵 0 命中启用了游戏的时序路径,但并未实现水平背景卷动。

合法性/测试规则

Super Mario Bros.nes 仅用于用户自行提供的手动兼容性实验。不要提交该 ROM,也不要在自动化测试中要求使用它。这些测试使用伪造的 CPU/PPU 对象,仅检查协调行为。

不在本步骤范围内

水平/垂直卷动
精细 X 卷动
相邻名称表的合成
精确的 OAM Y+1 行为
PPUMASK 左边缘规则
x=255 精灵 0 命中例外
商业 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