322. Posición del sprite zero hit del PPU

Extraer la posición de solapamiento del sprite 0 del estado actual del PPU.

Lección 322 de 356 · tests/chapter_11_sprite_zero_hit/test_322_ppu_sprite_zero_hit_position.py

Archivo a actualizar

emulator/rendering/sprite_zero_hit.py

Por qué existe este paso

El helper puro existente requiere datos de renderizado explícitos

find_sprite_zero_hit_position(
    sprite_zero,
    pattern_table,
    background_opaque_mask,
)

Esa API es útil para tests centrados, pero un futuro paso de Console parte de un PPU. Este paso añade un pequeño adaptador que extrae los datos requeridos del estado actual del PPU y delega en el helper puro existente.

Mantener ambas funciones en sprite_zero_hit.py queda claro con el tamaño actual del proyecto:

find_sprite_zero_hit_position(...)
    explicit data -> overlap position

ppu_sprite_zero_hit_position(ppu)
    PPU state -> explicit data -> overlap position

La segunda función es un adaptador, no otro algoritmo de solapamiento.

Extracción requerida

decodificar solo la entrada 0 de OAM
construir la máscara de opacidad del fondo mediante ppu_background_to_opaque_mask(ppu)
seleccionar la tabla de patrones de sprite usando el bit 3 de PPUCTRL
leer PATTERN_TABLE_SIZE bytes a través de PpuBus
delegar en find_sprite_zero_hit_position(...)

Ejemplo de implementación sugerido

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE, decode_chr_tile
from emulator.ppu.ppu import CTRL_SPRITE_PATTERN_TABLE, PPU
from emulator.rendering.ppu_background_renderer import (
    PATTERN_TABLE_0_ADDR,
    PATTERN_TABLE_1_ADDR,
    ppu_background_to_opaque_mask,
)
from emulator.rendering.sprite_renderer import (
    SpriteEntry,
    decode_sprite_attributes,
    decode_sprite_entry,
)

...

def ppu_sprite_zero_hit_position(
    ppu: PPU,
) -> SpriteZeroHitPosition | None:
    sprite_zero = decode_sprite_entry(
        oam=ppu.oam,
        sprite_index=0,
    )

    background_opaque_mask = ppu_background_to_opaque_mask(ppu)

    sprite_pattern_table_base = (
        PATTERN_TABLE_1_ADDR
        if ppu.ctrl & CTRL_SPRITE_PATTERN_TABLE
        else PATTERN_TABLE_0_ADDR
    )

    sprite_pattern_table = bytes(
        ppu.ppu_bus.read(sprite_pattern_table_base + offset)
        for offset in range(PATTERN_TABLE_SIZE)
    )

    return find_sprite_zero_hit_position(
        sprite_zero=sprite_zero,
        pattern_table=sprite_pattern_table,
        background_opaque_mask=background_opaque_mask,
    )

Distinción importante

La opacidad del fondo usa la ruta de selección de la tabla de patrones del fondo, que se basa en el bit 4 de PPUCTRL. Los datos CHR del sprite 0 usan el bit 3 de PPUCTRL. Las dos selecciones pueden apuntar a tablas de patrones distintas.

Límite importante

Esta función solo devuelve una posición. No establece PPUSTATUS ni llama a PPU.set_sprite_zero_hit_position(). La conexión de Console queda para un paso posterior.

Fuera del alcance

Conexión de Console
programación automática
reglas de activación de renderizado de PPUMASK
reglas de recorte del borde izquierdo
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_322_ppu_sprite_zero_hit_position.py -v

Implementación de ejemplo

Ejemplo de implementación sugerido

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE, decode_chr_tile
from emulator.ppu.ppu import CTRL_SPRITE_PATTERN_TABLE, PPU
from emulator.rendering.ppu_background_renderer import (
    PATTERN_TABLE_0_ADDR,
    PATTERN_TABLE_1_ADDR,
    ppu_background_to_opaque_mask,
)
from emulator.rendering.sprite_renderer import (
    SpriteEntry,
    decode_sprite_attributes,
    decode_sprite_entry,
)

...

def ppu_sprite_zero_hit_position(
    ppu: PPU,
) -> SpriteZeroHitPosition | None:
    sprite_zero = decode_sprite_entry(
        oam=ppu.oam,
        sprite_index=0,
    )

    background_opaque_mask = ppu_background_to_opaque_mask(ppu)

    sprite_pattern_table_base = (
        PATTERN_TABLE_1_ADDR
        if ppu.ctrl & CTRL_SPRITE_PATTERN_TABLE
        else PATTERN_TABLE_0_ADDR
    )

    sprite_pattern_table = bytes(
        ppu.ppu_bus.read(sprite_pattern_table_base + offset)
        for offset in range(PATTERN_TABLE_SIZE)
    )

    return find_sprite_zero_hit_position(
        sprite_zero=sprite_zero,
        pattern_table=sprite_pattern_table,
        background_opaque_mask=background_opaque_mask,
    )

Ver código del testtest_322_ppu_sprite_zero_hit_position.py

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE
from emulator.ppu.ppu import CTRL_SPRITE_PATTERN_TABLE, PPU, SPRITE_ZERO_HIT
from emulator.rendering.ppu_background_renderer import (
    PATTERN_TABLE_0_ADDR,
    PATTERN_TABLE_1_ADDR,
)
from emulator.rendering.sprite_zero_hit import (
    find_sprite_zero_hit_position,
    ppu_sprite_zero_hit_position,
)
import emulator.rendering.sprite_zero_hit as sprite_zero_hit_module


def make_background_mask() -> list[bool]:
    return [False] * (256 * 240)


def test_ppu_adapter_and_pure_overlap_helper_live_in_same_focused_module():
    """
    Objective:
    Keep the two abstraction levels together while the sprite-zero-hit module remains
    small and cohesive.
    """
    assert callable(find_sprite_zero_hit_position)
    assert callable(ppu_sprite_zero_hit_position)
    assert find_sprite_zero_hit_position.__module__ == ppu_sprite_zero_hit_position.__module__


def test_ppu_sprite_zero_hit_position_decodes_only_oam_entry_zero(monkeypatch):
    """
    Objective:
    Sprite 0 hit uses the first four OAM bytes. Other sprites must not be substituted
    for OAM entry 0.
    """
    ppu = PPU()
    ppu.oam[0:4] = bytes([12, 7, 0x60, 34])
    ppu.oam[4:8] = bytes([99, 8, 0x00, 88])
    captured = {}

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        lambda received_ppu: make_background_mask(),
    )

    def fake_find_sprite_zero_hit_position(**kwargs):
        captured.update(kwargs)
        return None

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        fake_find_sprite_zero_hit_position,
    )

    ppu_sprite_zero_hit_position(ppu)

    sprite_zero = captured["sprite_zero"]
    assert sprite_zero.y == 12
    assert sprite_zero.tile_index == 7
    assert sprite_zero.attributes == 0x60
    assert sprite_zero.x == 34


def test_ppu_adapter_passes_background_mask_to_pure_helper_unchanged(monkeypatch):
    """
    Objective:
    Background extraction belongs to ppu_background_to_opaque_mask(). The adapter
    should pass its result directly to the pure overlap helper.
    """
    ppu = PPU()
    expected_mask = make_background_mask()
    expected_mask[123] = True
    captured = {}

    def fake_background_mask(received_ppu):
        assert received_ppu is ppu
        return expected_mask

    def fake_find_sprite_zero_hit_position(**kwargs):
        captured.update(kwargs)
        return None

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        fake_background_mask,
    )
    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        fake_find_sprite_zero_hit_position,
    )

    ppu_sprite_zero_hit_position(ppu)

    assert captured["background_opaque_mask"] is expected_mask


def test_ppu_adapter_uses_sprite_pattern_table_zero_when_ctrl_bit_is_clear(monkeypatch):
    """
    Objective:
    PPUCTRL bit 3 clear selects sprite pattern table $0000-$0FFF.
    """
    ppu = PPU()
    assert (ppu.ctrl & CTRL_SPRITE_PATTERN_TABLE) == 0
    ppu.ppu_bus.write(PATTERN_TABLE_0_ADDR, 0x11)
    ppu.ppu_bus.write(PATTERN_TABLE_1_ADDR, 0x22)
    captured = {}

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        lambda received_ppu: make_background_mask(),
    )

    def fake_find_sprite_zero_hit_position(**kwargs):
        captured.update(kwargs)
        return None

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        fake_find_sprite_zero_hit_position,
    )

    ppu_sprite_zero_hit_position(ppu)

    pattern_table = captured["pattern_table"]
    assert isinstance(pattern_table, bytes)
    assert len(pattern_table) == PATTERN_TABLE_SIZE
    assert pattern_table[0] == 0x11


def test_ppu_adapter_uses_sprite_pattern_table_one_when_ctrl_bit_is_set(monkeypatch):
    """
    Objective:
    PPUCTRL bit 3 set selects sprite pattern table $1000-$1FFF.
    """
    ppu = PPU()
    ppu.ctrl |= CTRL_SPRITE_PATTERN_TABLE
    ppu.ppu_bus.write(PATTERN_TABLE_0_ADDR, 0x11)
    ppu.ppu_bus.write(PATTERN_TABLE_1_ADDR, 0x22)
    captured = {}

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        lambda received_ppu: make_background_mask(),
    )

    def fake_find_sprite_zero_hit_position(**kwargs):
        captured.update(kwargs)
        return None

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        fake_find_sprite_zero_hit_position,
    )

    ppu_sprite_zero_hit_position(ppu)

    pattern_table = captured["pattern_table"]
    assert isinstance(pattern_table, bytes)
    assert len(pattern_table) == PATTERN_TABLE_SIZE
    assert pattern_table[0] == 0x22


def test_ppu_adapter_returns_pure_helper_result_unchanged(monkeypatch):
    """
    Objective:
    This adapter should not reinterpret or offset the position returned by the pure
    overlap helper.
    """
    ppu = PPU()
    expected_position = (45, 67)

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        lambda received_ppu: make_background_mask(),
    )
    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        lambda **kwargs: expected_position,
    )

    result = ppu_sprite_zero_hit_position(ppu)

    assert result is expected_position


def test_ppu_adapter_does_not_set_status_or_schedule_position(monkeypatch):
    """
    Objective:
    Step 322 only extracts and returns a position. PPU mutation belongs to the next
    Console orchestration step.
    """
    ppu = PPU()
    expected_position = (10, 20)

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        lambda received_ppu: make_background_mask(),
    )
    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        lambda **kwargs: expected_position,
    )

    result = ppu_sprite_zero_hit_position(ppu)

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

Funciones de test (7)

test_ppu_adapter_and_pure_overlap_helper_live_in_same_focused_module
test_ppu_sprite_zero_hit_position_decodes_only_oam_entry_zero
test_ppu_adapter_passes_background_mask_to_pure_helper_unchanged
test_ppu_adapter_uses_sprite_pattern_table_zero_when_ctrl_bit_is_clear
test_ppu_adapter_uses_sprite_pattern_table_one_when_ctrl_bit_is_set
test_ppu_adapter_returns_pure_helper_result_unchanged
test_ppu_adapter_does_not_set_status_or_schedule_position