319. Сброс sprite 0 hit перед предрендером

Сбрасываем sprite 0 hit на упрощённой границе предрендера.

Урок 319 из 356 · tests/chapter_11_sprite_zero_hit/test_319_clear_sprite_zero_hit_pre_render.py

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

emulator/ppu/ppu.py

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

Sprite 0 hit — это бит 6 PPUSTATUS. Игры могут использовать его как сигнал тайминга, ожидая перехода флага через следующий жизненный цикл:

visible frame overlap -> sprite 0 hit becomes set
pre-render boundary   -> sprite 0 hit becomes clear
next visible frame    -> sprite 0 hit may become set again

Прежде чем реализовывать обнаружение пересечения или установку флага, этот шаг устанавливает инвариант сброса/очистки. Без этого сброса будущий sprite 0 hit может остаться установленным навсегда и сломать игры, которые ждут очистки флага перед ожиданием следующего попадания.

Текущая модель тайминга

Проект в настоящее время продвигает тайминг на переходах между сканлиниями. Поэтому этот шаг очищает флаг при начале сканлинии 261. Точный тайминг по точкам на реальном оборудовании — это будущее уточнение точности.

Пример фрагмента реализации

if self.scanline == PPU_PRE_RENDER_SCANLINE:
    self.status &= ~VBLANK_STARTED

    # --- NEW BLOCK: CLEAR SPRITE 0 HIT FOR THE NEXT FRAME ---
    self.status &= ~SPRITE_ZERO_HIT
    # --- END NEW BLOCK ---

Важный инвариант

Чтение PPUSTATUS очищает бит 7 VBlank, но не должно очищать бит 6 sprite 0 hit. В текущей модели sprite 0 hit очищается только событием жизненного цикла предрендера.

Текущая политика ручного ROM

Продолжайте использовать MarioBros.nes для текущих ручных проверок. Проверка на Super Mario Bros. откладывается до реализации обнаружения пересечения и установки попадания по времени.

Вне рамок

обнаружение пересечения sprite 0/фона
установка sprite 0 hit
фиксированные/поддельные попадания по сканлинии
переполнение спрайтов
изменения в Console
изменения рендеринга
проверка на Super Mario Bros.

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

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

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

Пример фрагмента реализации

if self.scanline == PPU_PRE_RENDER_SCANLINE:
    self.status &= ~VBLANK_STARTED

    # --- NEW BLOCK: CLEAR SPRITE 0 HIT FOR THE NEXT FRAME ---
    self.status &= ~SPRITE_ZERO_HIT
    # --- END NEW BLOCK ---

Показать код тестаtest_319_clear_sprite_zero_hit_pre_render.py

from emulator.ppu.ppu import (
    PPU,
    PPU_CYCLES_PER_SCANLINE,
    PPU_PRE_RENDER_SCANLINE,
    SPRITE_ZERO_HIT,
    VBLANK_STARTED,
)


def advance_to_start_of_pre_render_scanline(ppu: PPU) -> None:
    """Place the PPU one cycle before scanline 261 and cross the boundary."""
    ppu.scanline = PPU_PRE_RENDER_SCANLINE - 1
    ppu.cycle = PPU_CYCLES_PER_SCANLINE - 1
    ppu.step(1)


def test_sprite_zero_hit_remains_set_before_pre_render_boundary():
    """
    Objective:
    Sprite 0 hit should not be cleared early during the previous scanline.
    """
    ppu = PPU()
    ppu.status |= SPRITE_ZERO_HIT
    ppu.scanline = PPU_PRE_RENDER_SCANLINE - 1
    ppu.cycle = PPU_CYCLES_PER_SCANLINE - 2

    ppu.step(1)

    assert ppu.scanline == PPU_PRE_RENDER_SCANLINE - 1
    assert (ppu.status & SPRITE_ZERO_HIT) != 0


def test_sprite_zero_hit_clears_when_pre_render_scanline_begins():
    """
    Objective:
    Crossing into the simplified pre-render boundary should clear PPUSTATUS bit 6.
    """
    ppu = PPU()
    ppu.status |= SPRITE_ZERO_HIT

    advance_to_start_of_pre_render_scanline(ppu)

    assert ppu.scanline == PPU_PRE_RENDER_SCANLINE
    assert ppu.cycle == 0
    assert (ppu.status & SPRITE_ZERO_HIT) == 0


def test_pre_render_boundary_clears_vblank_and_sprite_zero_hit_together():
    """
    Objective:
    Adding sprite 0 hit clearing should preserve the existing VBlank-clear behavior.
    """
    ppu = PPU()
    ppu.status |= VBLANK_STARTED | SPRITE_ZERO_HIT

    advance_to_start_of_pre_render_scanline(ppu)

    assert (ppu.status & VBLANK_STARTED) == 0
    assert (ppu.status & SPRITE_ZERO_HIT) == 0


def test_pre_render_clear_preserves_unrelated_status_bits():
    """
    Objective:
    Clear only the lifecycle flags owned by this boundary. Other status bits should
    not be erased by assigning status to zero.
    """
    unrelated_status_bit = 1 << 5
    ppu = PPU()
    ppu.status = VBLANK_STARTED | SPRITE_ZERO_HIT | unrelated_status_bit

    advance_to_start_of_pre_render_scanline(ppu)

    assert (ppu.status & VBLANK_STARTED) == 0
    assert (ppu.status & SPRITE_ZERO_HIT) == 0
    assert (ppu.status & unrelated_status_bit) != 0


def test_reading_ppustatus_does_not_clear_sprite_zero_hit():
    """
    Objective:
    PPUSTATUS reads clear VBlank, not sprite 0 hit. This distinction is required by
    games that poll bit 6 repeatedly.
    """
    ppu = PPU()
    ppu.status = VBLANK_STARTED | SPRITE_ZERO_HIT

    returned_status = ppu.read_register(0x2002)

    assert (returned_status & VBLANK_STARTED) != 0
    assert (returned_status & SPRITE_ZERO_HIT) != 0
    assert (ppu.status & VBLANK_STARTED) == 0
    assert (ppu.status & SPRITE_ZERO_HIT) != 0


def test_step_319_does_not_set_sprite_zero_hit():
    """
    Objective:
    This step only defines clearing behavior. Starting with a clear flag and crossing
    pre-render must not invent a hit.
    """
    ppu = PPU()
    assert (ppu.status & SPRITE_ZERO_HIT) == 0

    advance_to_start_of_pre_render_scanline(ppu)

    assert (ppu.status & SPRITE_ZERO_HIT) == 0

Тестовые функции (6)

test_sprite_zero_hit_remains_set_before_pre_render_boundary
test_sprite_zero_hit_clears_when_pre_render_scanline_begins
test_pre_render_boundary_clears_vblank_and_sprite_zero_hit_together
test_pre_render_clear_preserves_unrelated_status_bits
test_reading_ppustatus_does_not_clear_sprite_zero_hit
test_step_319_does_not_set_sprite_zero_hit