321. El PPU establece el sprite zero hit programado

Permitir que el timing del PPU establezca el sprite 0 hit en una posición de pantalla detectada previamente.

Lección 321 de 356 · tests/chapter_11_sprite_zero_hit/test_321_ppu_sets_scheduled_sprite_zero_hit.py

Archivo a actualizar

emulator/ppu/ppu.py

Por qué existe este paso

El paso 320 puede encontrar el primer píxel solapado de sprite 0/fondo y devolver su posición en pantalla:

(screen_x, screen_y)

El PPU no debe establecer el bit 6 de PPUSTATUS inmediatamente cuando se descubre esa posición. Debe almacenar la posición y establecer el flag solo cuando el timing del PPU emulado alcance el píxel visible correspondiente.

Mapeo de coordenadas simplificado

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

Las coordenadas del framebuffer visible comienzan en x=0, mientras que el timing del PPU simplificado de este proyecto considera que la salida visible comienza en el ciclo 1:

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

Cambios de implementación sugeridos

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

            ...

¿Por qué consumir la posición? La posición describe un único evento de timing futuro. Una vez disparado el evento, establecerla en None evita que el mismo evento programado se dispare de nuevo en un frame posterior. El flag de PPUSTATUS en sí permanece establecido hasta el borrado de pre-render del paso 319.

Distinción importante

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

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

Límite importante

El PPU recibe solo un tuple[int, int] | None neutro. No debe importar módulos de renderizado ni saber cómo se detectó el solapamiento entre CHR y el fondo.

Fuera del alcance

Conexión de Console
llamar a find_sprite_zero_hit_position()
selección de las tablas de patrones de sprite/fondo
reglas de activación de renderizado de PPUMASK
excepción de hardware en x=255
corrección de Y+1 de OAM
validación con Super Mario Bros.

Ejecutar esta lección

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

Implementación de ejemplo

Cambios de implementación sugeridos

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

            ...

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

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