319. Limpiar sprite 0 hit en el prerenderizado

Limpia sprite 0 hit en el límite simplificado de prerenderizado.

Lección 319 de 356 · tests/chapter_11_sprite_zero_hit/test_319_clear_sprite_zero_hit_pre_render.py

Archivo a actualizar

emulator/ppu/ppu.py

Por qué existe este paso

Sprite 0 hit es el bit 6 de PPUSTATUS. Los juegos pueden usarlo como señal de temporización esperando a que el flag transicione a través de este ciclo de vida:

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

Antes de implementar la detección de solapamiento o de establecer el flag, este paso establece el invariante de limpieza/reinicio. Sin este reinicio, un futuro sprite 0 hit podría quedar activado para siempre y romper los juegos que esperan a que el flag se limpie antes de esperar al siguiente hit.

Modelo de temporización actual

El proyecto actualmente avanza la temporización en las transiciones de scanline. Por tanto, este paso limpia el flag cuando comienza el scanline 261. La temporización exacta a nivel de dot del hardware es un refinamiento de precisión futuro.

Fragmento de implementación de ejemplo

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 ---

Invariante importante

Leer PPUSTATUS limpia el bit 7 de VBlank, pero no debe limpiar el bit 6 de sprite 0 hit. En el modelo actual, solo el evento del ciclo de vida de prerenderizado limpia sprite 0 hit.

Política actual de ROM manual

Continúa usando MarioBros.nes para las comprobaciones manuales actuales. La validación con Super Mario Bros. se pospone hasta que se implementen la detección de solapamiento y el establecimiento cronometrado del hit.

Fuera de alcance

detectar el solapamiento entre sprite 0 y el fondo
establecer sprite 0 hit
hits fijos/falsos de scanline
desbordamiento de sprites
cambios en Console
cambios en el renderizado
validación con Super Mario Bros.

Ejecutar esta lección

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

Implementación de ejemplo

Fragmento de implementación de ejemplo

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 ---

Ver código del testtest_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

Funciones de test (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