321. PPU устанавливает запланированное срабатывание sprite zero hit

Пусть тайминг PPU устанавливает sprite 0 hit в ранее обнаруженной позиции экрана.

Урок 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 не должен устанавливать бит 6 PPUSTATUS сразу же при обнаружении этой позиции. Он должен сохранить позицию и установить флаг только тогда, когда эмулируемый тайминг 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
проверка на Super Mario Bros.

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

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