301. 精灵属性定义

定义精灵属性数据模型。

第 301 / 356 · tests/chapter_09_sprite_rendering/test_301_sprite_attribute_definition.py

需要更新的文件

emulator/rendering/sprite_renderer.py

为什么需要这一步

每个 SpriteEntry 都包含一个原始属性字节。在渲染精灵之前,我们需要为其中重要的位起名字,并用一个小的数据类来表示解码后的含义。

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

建议的实现示例

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

常见误解

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

不是。背景属性表字节为图块区域选择背景调色板。精灵属性是逐精灵的,存放在 OAM 字节 2 中。

本步骤不涉及的内容

decode_sprite_attributes()
精灵调色板 RAM 辅助函数
渲染像素
sprite 0 hit
sprite overflow
pygame

运行本课

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

示例实现

建议的实现示例

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

查看测试代码test_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

测试函数 (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