290. Definición del mando

Definir el objeto de estado puro del Controller del NES.

Lección 290 de 356 · tests/chapter_07_controller_input/test_290_controller_definition.py

Archivos a crear en este paso

emulator/input/controller.py

Por qué existe este paso

Antes de conectar la entrada del mando a la dirección $4016 de CpuBus, necesitamos un modelo de datos puro para el mando estándar del NES. Esto mantiene el mecanismo del mando fácil de probar sin involucrar a pygame, CpuBus, la ejecución de la ROM ni la temporización de fotogramas.

¿Qué es un mando estándar del NES?

El mando estándar tiene ocho botones

Referencias

https://www.nesdev.org/wiki/Standard_controller
https://www.nesdev.org/wiki/Controller_reading_code

A, B, Select, Start, Up, Down, Left, Right

El orden de lectura serial del hardware es

first read  -> A
second read -> B
third read  -> Select
fourth read -> Start
fifth read  -> Up
sixth read  -> Down
seventh read -> Left
eighth read -> Right

Distinción importante

Algunas rutinas en ensamblador del NES desplazan estas lecturas a la RAM de modo que A termina en el bit 7 de un byte propio del juego. Eso no significa que el hardware envíe Right primero. El emulador debería modelar el orden serial del hardware.

Ejemplo de implementación sugerida

from dataclasses import dataclass


BUTTON_A = 1 << 0
BUTTON_B = 1 << 1
BUTTON_SELECT = 1 << 2
BUTTON_START = 1 << 3
BUTTON_UP = 1 << 4
BUTTON_DOWN = 1 << 5
BUTTON_LEFT = 1 << 6
BUTTON_RIGHT = 1 << 7


@dataclass
class Controller:
    a: bool = False
    b: bool = False
    select: bool = False
    start: bool = False
    up: bool = False
    down: bool = False
    left: bool = False
    right: bool = False

    strobe: bool = False
    captured_buttons: int = 0
    read_index: int = 0

Fuera de alcance

enrutamiento de $4016 en CpuBus
asignación de teclado de pygame
puerto de mando 2
mandos de expansión de Famicom
comportamiento de fallo (glitch) de lectura de DMC/mando

Ejecutar esta lección

uv run pytest tests/chapter_07_controller_input/test_290_controller_definition.py -v

Implementación de ejemplo

Ejemplo de implementación sugerida

from dataclasses import dataclass


BUTTON_A = 1 << 0
BUTTON_B = 1 << 1
BUTTON_SELECT = 1 << 2
BUTTON_START = 1 << 3
BUTTON_UP = 1 << 4
BUTTON_DOWN = 1 << 5
BUTTON_LEFT = 1 << 6
BUTTON_RIGHT = 1 << 7


@dataclass
class Controller:
    a: bool = False
    b: bool = False
    select: bool = False
    start: bool = False
    up: bool = False
    down: bool = False
    left: bool = False
    right: bool = False

    strobe: bool = False
    captured_buttons: int = 0
    read_index: int = 0

Ver código del testtest_290_controller_definition.py

from dataclasses import is_dataclass
from pathlib import Path

from emulator.input.controller import (
    BUTTON_A,
    BUTTON_B,
    BUTTON_DOWN,
    BUTTON_LEFT,
    BUTTON_RIGHT,
    BUTTON_SELECT,
    BUTTON_START,
    BUTTON_UP,
    Controller,
)


def test_controller_input_files_exist():
    """
    Objective:
    Controller input starts as a pure emulator-core input module, not as pygame or
    CpuBus behavior.
    """
    assert Path("emulator/input/controller.py").exists()


def test_controller_is_a_dataclass():
    """
    Objective:
    The controller state is plain data with small behavior methods layered on top.
    """
    assert is_dataclass(Controller)


def test_controller_button_constants_match_hardware_serial_order():
    """
    Objective:
    Constants encode the order in which $4016 serial reads expose buttons.

    This is not the same thing as every game's final RAM byte layout.
    """
    assert BUTTON_A == 1 << 0
    assert BUTTON_B == 1 << 1
    assert BUTTON_SELECT == 1 << 2
    assert BUTTON_START == 1 << 3
    assert BUTTON_UP == 1 << 4
    assert BUTTON_DOWN == 1 << 5
    assert BUTTON_LEFT == 1 << 6
    assert BUTTON_RIGHT == 1 << 7


def test_controller_defaults_to_all_buttons_released_and_not_strobing():
    """
    Objective:
    A new controller starts with no pressed buttons and no captured serial state.
    """
    controller = Controller()

    assert controller.a is False
    assert controller.b is False
    assert controller.select is False
    assert controller.start is False
    assert controller.up is False
    assert controller.down is False
    assert controller.left is False
    assert controller.right is False

    assert controller.strobe is False
    assert controller.captured_buttons == 0
    assert controller.read_index == 0


def test_controller_module_does_not_import_pygame_or_cpubus():
    """
    Objective:
    This first controller step must remain pure. Pygame and CpuBus wiring come
    later.
    """
    source = Path("emulator/input/controller.py").read_text()

    assert "import pygame" not in source
    assert "CpuBus" not in source
    assert "4016" not in source

Funciones de test (5)

test_controller_input_files_exist
test_controller_is_a_dataclass
test_controller_button_constants_match_hardware_serial_order
test_controller_defaults_to_all_buttons_released_and_not_strobing
test_controller_module_does_not_import_pygame_or_cpubus