321. PPU 根据调度设置精灵零命中

让 PPU 时序在先前检测到的屏幕位置设置精灵 0 命中。

第 321 / 356 · tests/chapter_11_sprite_zero_hit/test_321_ppu_sets_scheduled_sprite_zero_hit.py

需要更新的文件

emulator/ppu/ppu.py

该步骤存在的原因

第 320 步可以找到第一个重叠的精灵 0/背景像素,并返回其屏幕位置:

(screen_x, screen_y)

PPU 不应在发现该位置时立即设置 PPUSTATUS 的第 6 位。它应当存储该位置,并且只有当模拟的 PPU 时序到达对应的可见像素时才设置该标志。

简化坐标映射

screen y -> PPU scanline y
screen x -> PPU cycle x + 1

可见帧缓冲坐标从 x=0 开始,而本项目简化的 PPU 时序将可见输出视为从周期 1 开始:

screen x=0 -> PPU cycle 1
screen x=1 -> PPU cycle 2
screen x=40 -> PPU cycle 41

建议的实现改动

# --- NEW LINE ---
SpriteZeroHitPosition = tuple[int, int]
# --- END NEW LINE ---


@dataclass
class PPU:
    ...
    scanline: int = 0
    frame: int = 0
    nmi_requested: bool = False
    # --- NEW BLOCK ---
    sprite_zero_hit_position: SpriteZeroHitPosition | None = None

    def set_sprite_zero_hit_position(
        self,
        position: SpriteZeroHitPosition | None,
    ) -> None:
        self.sprite_zero_hit_position = position
    # --- END NEW BLOCK ---

    def step(self, cycles: int = 1) -> None:
        ...
        for _ in range(cycles):
            self.cycle += 1

            # --- NEW BLOCK ---
            if self.sprite_zero_hit_position is not None:
                hit_x, hit_y = self.sprite_zero_hit_position

                if self.scanline == hit_y and self.cycle == hit_x + 1:
                    self.status |= SPRITE_ZERO_HIT
                    self.sprite_zero_hit_position = None
            # --- END NEW BLOCK ---

            ...

为什么要消费该位置?该位置描述的是一个未来的时序事件。事件触发后,将其设为 None 可以防止同一个已调度事件在之后的帧中再次触发。PPUSTATUS 标志本身则保持置位状态,直到第 319 步的预渲染清除阶段。

重要区别

set_sprite_zero_hit_position((x, y))
    stores a future position

PPU.step()
    sets SPRITE_ZERO_HIT when timing reaches that position

重要边界

PPU 只接收一个中性的 tuple[int, int] | None。它不得导入渲染模块,也不应知道 CHR/背景重叠是如何被检测出来的。

不在本步骤范围内

Console 接线
调用 find_sprite_zero_hit_position()
选择精灵/背景图案表
PPUMASK 渲染使能规则
x=255 硬件例外
OAM Y+1 修正
《超级马里奥兄弟》验证

运行本课

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

示例实现

建议的实现改动

# --- NEW LINE ---
SpriteZeroHitPosition = tuple[int, int]
# --- END NEW LINE ---


@dataclass
class PPU:
    ...
    scanline: int = 0
    frame: int = 0
    nmi_requested: bool = False
    # --- NEW BLOCK ---
    sprite_zero_hit_position: SpriteZeroHitPosition | None = None

    def set_sprite_zero_hit_position(
        self,
        position: SpriteZeroHitPosition | None,
    ) -> None:
        self.sprite_zero_hit_position = position
    # --- END NEW BLOCK ---

    def step(self, cycles: int = 1) -> None:
        ...
        for _ in range(cycles):
            self.cycle += 1

            # --- NEW BLOCK ---
            if self.sprite_zero_hit_position is not None:
                hit_x, hit_y = self.sprite_zero_hit_position

                if self.scanline == hit_y and self.cycle == hit_x + 1:
                    self.status |= SPRITE_ZERO_HIT
                    self.sprite_zero_hit_position = None
            # --- END NEW BLOCK ---

            ...

查看测试代码test_321_ppu_sets_scheduled_sprite_zero_hit.py

from pathlib import Path

from emulator.ppu.ppu import PPU, SPRITE_ZERO_HIT, SpriteZeroHitPosition


def test_sprite_zero_hit_position_type_alias_has_screen_coordinate_shape():
    """
    Objective:
    PPU timing receives a simple screen-coordinate tuple without depending on the
    rendering package's implementation types.
    """
    position: SpriteZeroHitPosition = (40, 30)

    assert position == (40, 30)


def test_ppu_starts_without_a_scheduled_sprite_zero_hit_position():
    """
    Objective:
    A new PPU should not invent a future sprite 0 hit event.
    """
    ppu = PPU()

    assert ppu.sprite_zero_hit_position is None


def test_set_sprite_zero_hit_position_stores_future_event_without_setting_status():
    """
    Objective:
    Supplying an overlap position schedules a future event; it must not immediately
    set PPUSTATUS bit 6.
    """
    ppu = PPU()

    ppu.set_sprite_zero_hit_position((40, 30))

    assert ppu.sprite_zero_hit_position == (40, 30)
    assert (ppu.status & SPRITE_ZERO_HIT) == 0


def test_setting_none_represents_no_sprite_zero_hit_this_frame():
    """
    Objective:
    The caller can explicitly represent a frame where pure overlap detection found
    no hit.
    """
    ppu = PPU()
    ppu.set_sprite_zero_hit_position((10, 20))

    ppu.set_sprite_zero_hit_position(None)

    assert ppu.sprite_zero_hit_position is None
    assert (ppu.status & SPRITE_ZERO_HIT) == 0


def test_sprite_zero_hit_is_not_set_one_cycle_before_scheduled_pixel():
    """
    Objective:
    An overlap at screen x=3 maps to PPU cycle 4, not cycle 3.
    """
    ppu = PPU()
    ppu.scanline = 20
    ppu.cycle = 2
    ppu.set_sprite_zero_hit_position((3, 20))

    ppu.step(1)

    assert ppu.cycle == 3
    assert (ppu.status & SPRITE_ZERO_HIT) == 0
    assert ppu.sprite_zero_hit_position == (3, 20)


def test_sprite_zero_hit_is_set_at_screen_x_plus_one_cycle():
    """
    Objective:
    When timing reaches the scheduled scanline and x+1 cycle, set PPUSTATUS bit 6.
    """
    ppu = PPU()
    ppu.scanline = 20
    ppu.cycle = 3
    ppu.set_sprite_zero_hit_position((3, 20))

    ppu.step(1)

    assert ppu.scanline == 20
    assert ppu.cycle == 4
    assert (ppu.status & SPRITE_ZERO_HIT) != 0


def test_screen_x_zero_maps_to_ppu_cycle_one():
    """
    Objective:
    Verify the origin conversion explicitly: the first framebuffer pixel maps to
    visible PPU cycle 1.
    """
    ppu = PPU()
    ppu.scanline = 8
    ppu.cycle = 0
    ppu.set_sprite_zero_hit_position((0, 8))

    ppu.step(1)

    assert ppu.cycle == 1
    assert (ppu.status & SPRITE_ZERO_HIT) != 0


def test_matching_cycle_on_wrong_scanline_does_not_set_hit():
    """
    Objective:
    Both timing coordinates must match. Reaching x+1 on a different scanline is not
    the scheduled event.
    """
    ppu = PPU()
    ppu.scanline = 19
    ppu.cycle = 3
    ppu.set_sprite_zero_hit_position((3, 20))

    ppu.step(1)

    assert (ppu.status & SPRITE_ZERO_HIT) == 0
    assert ppu.sprite_zero_hit_position == (3, 20)


def test_sprite_zero_hit_position_is_consumed_after_it_fires():
    """
    Objective:
    One scheduled position represents one timing event and should be removed after
    setting the status flag.
    """
    ppu = PPU()
    ppu.scanline = 20
    ppu.cycle = 3
    ppu.set_sprite_zero_hit_position((3, 20))

    ppu.step(1)

    assert (ppu.status & SPRITE_ZERO_HIT) != 0
    assert ppu.sprite_zero_hit_position is None


def test_consumed_position_does_not_fire_again():
    """
    Objective:
    Consuming the position prevents a stale event from setting the flag in a later
    frame unless the caller schedules a new overlap.
    """
    ppu = PPU()
    ppu.scanline = 20
    ppu.cycle = 3
    ppu.set_sprite_zero_hit_position((3, 20))
    ppu.step(1)
    assert ppu.sprite_zero_hit_position is None

    ppu.status &= ~SPRITE_ZERO_HIT
    ppu.scanline = 20
    ppu.cycle = 3
    ppu.step(1)

    assert (ppu.status & SPRITE_ZERO_HIT) == 0


def test_ppu_does_not_import_rendering_to_schedule_hit_position():
    """
    Objective:
    PPU owns timing and status flags, but overlap detection remains in the pure
    rendering helper. Keep this dependency direction explicit.
    """
    source = Path("emulator/ppu/ppu.py").read_text()

    assert "from emulator.rendering" not in source
    assert "import emulator.rendering" not in source

测试函数 (11)

test_sprite_zero_hit_position_type_alias_has_screen_coordinate_shape
test_ppu_starts_without_a_scheduled_sprite_zero_hit_position
test_set_sprite_zero_hit_position_stores_future_event_without_setting_status
test_setting_none_represents_no_sprite_zero_hit_this_frame
test_sprite_zero_hit_is_not_set_one_cycle_before_scheduled_pixel
test_sprite_zero_hit_is_set_at_screen_x_plus_one_cycle
test_screen_x_zero_maps_to_ppu_cycle_one
test_matching_cycle_on_wrong_scanline_does_not_set_hit
test_sprite_zero_hit_position_is_consumed_after_it_fires
test_consumed_position_does_not_fire_again
test_ppu_does_not_import_rendering_to_schedule_hit_position