322. Позиция sprite zero hit в PPU

Извлечь позицию перекрытия спрайта 0 из текущего состояния PPU.

Урок 322 из 356 · tests/chapter_11_sprite_zero_hit/test_322_ppu_sprite_zero_hit_position.py

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

emulator/rendering/sprite_zero_hit.py

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

Существующая чистая вспомогательная функция требует явных данных рендеринга

find_sprite_zero_hit_position(
    sprite_zero,
    pattern_table,
    background_opaque_mask,
)

Такой API полезен для точечных тестов, но будущий шаг Console начинается с PPU. Этот шаг добавляет небольшой адаптер, который извлекает нужные данные из текущего состояния PPU и делегирует их существующей чистой вспомогательной функции.

Хранить обе функции в sprite_zero_hit.py при текущем размере проекта разумно:

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

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

Вторая функция — это адаптер, а не ещё один алгоритм проверки перекрытия.

Необходимое извлечение

декодировать только запись OAM 0
построить маску непрозрачности фона через ppu_background_to_opaque_mask(ppu)
выбрать таблицу шаблонов спрайта, используя бит 3 PPUCTRL
прочитать PATTERN_TABLE_SIZE байт через PpuBus
делегировать выполнение find_sprite_zero_hit_position(...)

Пример предлагаемой реализации

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

Важное различие

Непрозрачность фона использует путь выбора таблицы шаблонов фона, основанный на бите 4 PPUCTRL. Данные CHR спрайта 0 используют бит 3 PPUCTRL. Эти два выбора могут указывать на разные таблицы шаблонов.

Важная граница

Эта функция только возвращает позицию. Она не устанавливает PPUSTATUS и не вызывает PPU.set_sprite_zero_hit_position(). Подключение в Console остаётся более поздним шагом.

Вне рамок

подключение в Console
автоматическое планирование
правила включения рендеринга PPUMASK
правила отсечения левого края
аппаратное исключение x=255
коррекция OAM Y+1
проверка на Super Mario Bros.

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

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

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

Пример предлагаемой реализации

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

Показать код тестаtest_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

Тестовые функции (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