301. Definición de atributos de sprite

Definir el modelo de datos de atributos de sprite.

Lección 301 de 356 · tests/chapter_09_sprite_rendering/test_301_sprite_attribute_definition.py

Archivo a actualizar

emulator/rendering/sprite_renderer.py

Por qué existe este paso

Cada SpriteEntry contiene un byte de atributos en crudo. Antes de renderizar sprites, necesitamos nombres para los bits relevantes y una pequeña dataclass para el significado decodificado.

Byte de atributos de sprite en la NES

bits 0-1: sprite palette ID
bits 2-4: unused / ignored for now
bit 5: priority behind background
bit 6: horizontal flip
bit 7: vertical flip

Ejemplo de implementación sugerido

SPRITE_PALETTE_ID_MASK = 0b0000_0011
SPRITE_IS_BEHIND_BACKGROUND = 1 << 5
SPRITE_FLIP_HORIZONTAL = 1 << 6
SPRITE_FLIP_VERTICAL = 1 << 7


@dataclass(frozen=True)
class SpriteAttributes:
    palette_id: int
    is_behind_background: bool
    flip_horizontal: bool
    flip_vertical: bool

Concepto erróneo frecuente

"Sprite attributes are the same as background attribute table bytes."

No. Los bytes de la tabla de atributos del fondo seleccionan paletas de fondo para regiones de tiles. Los atributos de sprite son por sprite y residen en el byte 2 de OAM.

Fuera del alcance

decode_sprite_attributes()
helper de paleta de sprite en RAM
renderizado de píxeles
sprite 0 hit
sprite overflow
pygame

Ejecutar esta lección

uv run pytest tests/chapter_09_sprite_rendering/test_301_sprite_attribute_definition.py -v

Implementación de ejemplo

Ejemplo de implementación sugerido

SPRITE_PALETTE_ID_MASK = 0b0000_0011
SPRITE_IS_BEHIND_BACKGROUND = 1 << 5
SPRITE_FLIP_HORIZONTAL = 1 << 6
SPRITE_FLIP_VERTICAL = 1 << 7


@dataclass(frozen=True)
class SpriteAttributes:
    palette_id: int
    is_behind_background: bool
    flip_horizontal: bool
    flip_vertical: bool

Ver código del testtest_301_sprite_attribute_definition.py

from dataclasses import is_dataclass
from pathlib import Path

from emulator.rendering.sprite_renderer import (
    SPRITE_FLIP_HORIZONTAL,
    SPRITE_FLIP_VERTICAL,
    SPRITE_IS_BEHIND_BACKGROUND,
    SPRITE_PALETTE_ID_MASK,
    SpriteAttributes,
)


def test_sprite_attribute_constants_define_relevant_oam_bits():
    """
    Objective:
    Constants document the meaning of the relevant bits in OAM attribute byte 2.
    """
    assert SPRITE_PALETTE_ID_MASK == 0b0000_0011
    assert SPRITE_IS_BEHIND_BACKGROUND == 1 << 5
    assert SPRITE_FLIP_HORIZONTAL == 1 << 6
    assert SPRITE_FLIP_VERTICAL == 1 << 7


def test_sprite_attributes_is_frozen_dataclass():
    """
    Objective:
    SpriteAttributes is a small immutable snapshot of decoded attribute meaning.
    """
    assert is_dataclass(SpriteAttributes)

    attributes = SpriteAttributes(
        palette_id=2,
        is_behind_background=True,
        flip_horizontal=True,
        flip_vertical=False,
    )

    assert attributes.palette_id == 2
    assert attributes.is_behind_background is True
    assert attributes.flip_horizontal is True
    assert attributes.flip_vertical is False


def test_sprite_attributes_field_order_is_teaching_friendly():
    """
    Objective:
    Field order follows the common reading order: palette, priority, flips.
    """
    assert list(SpriteAttributes.__dataclass_fields__) == [
        "palette_id",
        "is_behind_background",
        "flip_horizontal",
        "flip_vertical",
    ]


def test_sprite_attribute_definition_does_not_import_pygame():
    """
    Objective:
    Sprite attribute decoding must stay free of frontend dependencies.

    Historical note:
    Later sprite rendering steps intentionally import Framebuffer in this module to
    draw pure framebuffer data. That is acceptable. pygame is still not allowed.
    """
    source = Path("emulator/rendering/sprite_renderer.py").read_text()

    assert "import pygame" not in source

Funciones de test (4)

test_sprite_attribute_constants_define_relevant_oam_bits
test_sprite_attributes_is_frozen_dataclass
test_sprite_attributes_field_order_is_teaching_friendly
test_sprite_attribute_definition_does_not_import_pygame