220. 映射器工厂

创建一个映射器工厂。

第 220 / 356 · tests/chapter_02_rom_loading/test_220_mapper_factory.py

要创建的文件

emulator/cartridge/mapper_factory.py

要实现的函数

create_mapper(cartridge: Cartridge)

此步骤存在的原因

Cartridge 对象存储了从 ROM 中加载出的事实

Cartridge(prg_rom, chr_rom, mapper_number)

但 CPU/PPU 并不直接与原始的 PRG/CHR 字节打交道，而是通过映射器进行交互，因为映射器就是那块把模拟器地址转换为 ROM 偏移量的卡带硬件。

当前流程

raw .nes bytes
    -> Cartridge.from_ines_bytes(data)
    -> create_mapper(cartridge)
    -> Mapper000(prg_rom, chr_rom)

工厂的职责

检查 cartridge.mapper_number
创建正确的映射器对象
对不受支持的映射器明确报错

工厂不应该做的事情

解析 iNES 字节
执行 CPU 地址转换
了解 CpuBus 的路由方式
修改 Cartridge

预期的实现形态

from emulator.cartridge.cartridge import Cartridge
from emulator.cartridge.mapper000 import Mapper000


def create_mapper(cartridge: Cartridge):
    if cartridge.mapper_number == 0:
        return Mapper000(
            prg_rom=cartridge.prg_rom,
            chr_rom=cartridge.chr_rom,
        )

    raise ValueError(f"Unsupported mapper: {cartridge.mapper_number}")

为何要把它与 CpuBus 分开

CpuBus 应当负责读写的路由。它不应该承担每一条卡带映射器选择规则的职责。在我们把基于卡带的 PRG ROM 读取整合进总线之前，把映射器的创建放在这里可以降低耦合度。

运行本课

uv run pytest tests/chapter_02_rom_loading/test_220_mapper_factory.py -v

示例实现

预期的实现形态

from emulator.cartridge.cartridge import Cartridge
from emulator.cartridge.mapper000 import Mapper000


def create_mapper(cartridge: Cartridge):
    if cartridge.mapper_number == 0:
        return Mapper000(
            prg_rom=cartridge.prg_rom,
            chr_rom=cartridge.chr_rom,
        )

    raise ValueError(f"Unsupported mapper: {cartridge.mapper_number}")

查看测试代码test_220_mapper_factory.py

from pathlib import Path

import pytest

from emulator.cartridge.cartridge import Cartridge
from emulator.cartridge.mapper000 import CHR_ROM_SIZE, Mapper000, NROM_128_SIZE
from emulator.cartridge.mapper_factory import create_mapper


def test_mapper_factory_file_exists():
    """
    Objective:
    Create emulator/cartridge/mapper_factory.py.

    Why:
    Mapper construction is a small policy decision: mapper number 0 means
    Mapper000, mapper number 1 will later mean something else, and so on.
    """
    assert Path("emulator/cartridge/mapper_factory.py").exists()


def test_create_mapper_exists_and_is_callable():
    """
    Objective:
    Expose create_mapper(cartridge).

    The caller should not need to know which concrete mapper class corresponds
    to each mapper number.
    """
    assert callable(create_mapper)


def test_create_mapper_returns_mapper000_for_mapper_number_zero():
    """
    Objective:
    Mapper number 0 should create Mapper000 / NROM.

    This is the simplest NES cartridge mapping and the only mapper supported at
    this tutorial stage.
    """
    cartridge = Cartridge(
        prg_rom=bytes([0xEA]) * NROM_128_SIZE,
        chr_rom=bytes([0x00]) * CHR_ROM_SIZE,
        mapper_number=0,
    )

    mapper = create_mapper(cartridge)

    assert isinstance(mapper, Mapper000)


def test_create_mapper_preserves_prg_and_chr_rom_data():
    """
    Objective:
    The factory must pass both PRG ROM and CHR ROM into Mapper000 unchanged.

    Why this matters:
    PRG ROM will be used by CPU bus reads in $8000-$FFFF.
    CHR ROM will be used later by PPU pattern-table reads in $0000-$1FFF.
    """
    prg_rom = bytes([0xA9]) * NROM_128_SIZE
    chr_rom = bytes([0xBB]) * CHR_ROM_SIZE
    cartridge = Cartridge(
        prg_rom=prg_rom,
        chr_rom=chr_rom,
        mapper_number=0,
    )

    mapper = create_mapper(cartridge)

    assert mapper.prg_rom == prg_rom
    assert mapper.chr_rom == chr_rom


def test_create_mapper_rejects_unsupported_mapper_number():
    """
    Objective:
    Unsupported mappers should fail loudly.

    Why:
    If the emulator silently treats an unsupported mapper as Mapper000, games may
    run with incorrect memory mapping. That kind of bug is hard to debug because
    the CPU may execute plausible but wrong bytes.
    """
    cartridge = Cartridge(
        prg_rom=bytes([0x00]) * NROM_128_SIZE,
        chr_rom=bytes([0x00]) * CHR_ROM_SIZE,
        mapper_number=1,
    )

    with pytest.raises(ValueError, match="Unsupported mapper: 1"):
        create_mapper(cartridge)

测试函数 (5)

test_mapper_factory_file_exists
test_create_mapper_exists_and_is_callable
test_create_mapper_returns_mapper000_for_mapper_number_zero
test_create_mapper_preserves_prg_and_chr_rom_data
test_create_mapper_rejects_unsupported_mapper_number