220. Fábrica de mappers

Crea una fábrica de mappers.

Lección 220 de 356 · tests/chapter_02_rom_loading/test_220_mapper_factory.py

Archivo a crear

emulator/cartridge/mapper_factory.py

Función a implementar

create_mapper(cartridge: Cartridge)

Por qué existe este paso

El objeto Cartridge almacena hechos cargados desde la ROM

Cartridge(prg_rom, chr_rom, mapper_number)

Pero la CPU/PPU no hablan directamente con los bytes en bruto de PRG/CHR. Hablan a través de un mapper, porque el mapper es el hardware del cartucho que traduce las direcciones del emulador en desplazamientos de la ROM.

Flujo actual

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

Responsabilidades de la fábrica

inspeccionar cartridge.mapper_number
crear el objeto de mapper correcto
fallar de forma ruidosa ante mappers no soportados

Lo que la fábrica NO debe hacer

analizar los bytes de iNES
realizar la traducción de direcciones de la CPU
conocer el enrutamiento de CpuBus
mutar el Cartridge

Forma de implementación esperada

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}")

Por qué esto está separado de CpuBus

CpuBus debería encargarse de enrutar las lecturas y escrituras. No debería volverse responsable de cada regla de selección de mapper de cartucho. Mantener aquí la creación del mapper reduce el acoplamiento antes de integrar en el bus las lecturas de PRG ROM respaldadas por el cartucho.

Ejecutar esta lección

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

Implementación de ejemplo

Forma de implementación esperada

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}")

Ver código del testtest_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)

Funciones de test (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