295. Visualización manual de fondo en pygame desde main

Añadir la visualización manual de fondo en pygame a main_only_background.py.

Lección 295 de 356 · tests/chapter_08_manual_main/test_295_manual_main_pygame_background_display.py

Archivo a crear/actualizar en la carpeta raíz

main_only_background.py

Por qué existe este paso

core_validator.py demuestra que el emulador puede arrancar una ROM local y avanzar fotogramas sin pygame. main_only_background.py es el ejecutor visual manual histórico solo de fondo: debe usar pygame para mostrar el Framebuffer de fondo producido por el emulador tras cada fotograma.

Flujo de trabajo recomendado

Empieza copiando la estructura funcional de core_validator.py y añade solo las piezas de pygame/visualización que falten:

importar pygame
importar draw_framebuffer desde tools.show_framebuffer
definir SCALE
crear un framebuffer inicial para las dimensiones de la ventana
abrir una ventana de pygame
procesar eventos pygame.QUIT
tras cada paso de fotograma, renderizar el framebuffer de fondo
dibujar el framebuffer y volcar la pantalla
llamar a pygame.quit() en finally

Límite importante

pygame está permitido en main_only_background.py porque es un punto de entrada manual/frontend. pygame no debe importarse en los módulos del núcleo del emulador.

Regla legal/de pruebas importante

El repositorio del tutorial no debe incluir archivos de ROM comerciales. Las pruebas automatizadas no deben requerir MarioBros.nes ni abrir una ventana real de pygame.

Hash de referencia usado durante el desarrollo del tutorial [Mario Bros. (World).nes]:

MD5 5d7bcc400a2fb5fa27346da345d3bb62  MarioBros.nes
SHA1 314b6e46e814f955b52ac954f67dab849582fe77

Este hash es solo una referencia manual. Las pruebas no deben requerir este archivo ni este hash exacto, porque los usuarios pueden tener volcados/revisiones legales distintos.

Ejemplo de implementación sugerido

from pathlib import Path

import pygame

from emulator.bus.cpu_bus import CpuBus
from emulator.cartridge.cartridge import Cartridge
from emulator.console import Console
from emulator.cpu.cpu import CPU
from tools.show_framebuffer import draw_framebuffer


ROM_PATH = Path("MarioBros.nes")
debug_mode = False
SCALE = 3


def main() -> None:
    if not ROM_PATH.exists():
        raise FileNotFoundError(
            "MarioBros.nes not found. Provide your own legal local copy. "
            "This file is intentionally not included in the tutorial repository."
        )

    cartridge = Cartridge.from_ines_bytes(ROM_PATH.read_bytes())

    cpu_bus = CpuBus(cartridge=cartridge)
    cpu = CPU(cpu_bus)
    console = Console(cpu=cpu, ppu=cpu_bus.ppu)

    cpu.reset()
    framebuffer = console.render_background_framebuffer()

    print(f"Loaded {ROM_PATH}")
    print(f"CPU reset PC = ${cpu.pc:04X}")
    print("Starting frame loop. Close the window or press Ctrl+C to stop.")

    pygame.init()
    try:
        window = pygame.display.set_mode(
            (framebuffer.width * SCALE, framebuffer.height * SCALE)
        )
        pygame.display.set_caption("NES Background")

        running = True
        while running:
            for event in pygame.event.get():
                if event.type == pygame.QUIT:
                    running = False

            executed = console.step_until_next_frame()

            framebuffer = console.render_background_framebuffer()
            draw_framebuffer(window, framebuffer, SCALE)
            pygame.display.flip()

            if debug_mode:
                print(
                    f"frame={console.ppu.frame} "
                    f"pc=${cpu.pc:04X} "
                    f"instructions={executed}"
                )
    except KeyboardInterrupt:
        print("

Detenido por el usuario.")

    finally:
        pygame.quit()


if __name__ == "__main__":
    main()

Comando manual

uv run python main_only_background.py

Comportamiento manual esperado

main_only_background.py abre una ventana de pygame y muestra el framebuffer de fondo actual. La ventana puede verse incompleta porque los sprites no están implementados en este ejecutor histórico. Cierra la ventana o pulsa Ctrl+C para detenerlo.

Ejemplo aproximado de la expectativa visual

+------------------------------+
|                              |
|          MARIO BROS.         |
|                              |
|        1 PLAYER GAME A       |
|        1 PLAYER GAME B       |
|        2 PLAYER GAME A       |
|        2 PLAYER GAME B       |
|                              |
|   background is shown        |
|   sprites are  missing       |
|                              |
+------------------------------+

Tras 30 segundos - 1 minuto, también deberías ver un fondo/composición similar al escenario clásico de Mario Bros. de 1983. Los sprites siguen faltando, pero la escena de fondo debería hacer que el emulador se sienta vivo:

+------------------------------+
|  I-0000   TOP-0000  II-0000  |
|                              |
|  ====                  ====  |
|==                          ==|
|                              |
|        ──────────────        |
|─────                    ─────|
|                              |
|                              |
| ─────────── POW  ─────────── |
|====                      ====|
|------------------------------|
+------------------------------+

Esto es solo un boceto ASCII aproximado. La señal manual importante es que los tiles de fondo/título/escenario aparezcan y cambien con el tiempo. Es esperable que falten los personajes/enemigos en movimiento hasta que se implemente el renderizado de sprites.

Nota de rendimiento

El ejecutor manual de pygame puede sentirse lento en este momento. Eso es esperable en esta etapa. El ayudante draw_framebuffer actual es deliberadamente simple y dibuja muchos rectángulos escalados desde Python. Una futura optimización podrá sustituirlo por una vía de subida de framebuffer más rápida, pero este paso se centra en la salida visual esperada y en los límites de arquitectura, no en la velocidad.

Por qué esta prueba no llama a main()

main_only_background.py abre una ventana real de pygame y ejecuta un bucle manual. Las pruebas automatizadas deben permanecer finitas y deben limitarse a inspeccionar la estructura.

Fuera de alcance

Optimización de subida rápida de framebuffer
Mapeo de teclado/mando de pygame
Renderizado de sprites
Verificar píxeles visuales exactos de una ROM comercial
Llamar a main() desde pytest

Ejecutar esta lección

uv run pytest tests/chapter_08_manual_main/test_295_manual_main_pygame_background_display.py -v

Implementación de ejemplo

Ejemplo de implementación sugerido

from pathlib import Path

import pygame

from emulator.bus.cpu_bus import CpuBus
from emulator.cartridge.cartridge import Cartridge
from emulator.console import Console
from emulator.cpu.cpu import CPU
from tools.show_framebuffer import draw_framebuffer


ROM_PATH = Path("MarioBros.nes")
debug_mode = False
SCALE = 3


def main() -> None:
    if not ROM_PATH.exists():
        raise FileNotFoundError(
            "MarioBros.nes not found. Provide your own legal local copy. "
            "This file is intentionally not included in the tutorial repository."
        )

    cartridge = Cartridge.from_ines_bytes(ROM_PATH.read_bytes())

    cpu_bus = CpuBus(cartridge=cartridge)
    cpu = CPU(cpu_bus)
    console = Console(cpu=cpu, ppu=cpu_bus.ppu)

    cpu.reset()
    framebuffer = console.render_background_framebuffer()

    print(f"Loaded {ROM_PATH}")
    print(f"CPU reset PC = ${cpu.pc:04X}")
    print("Starting frame loop. Close the window or press Ctrl+C to stop.")

    pygame.init()
    try:
        window = pygame.display.set_mode(
            (framebuffer.width * SCALE, framebuffer.height * SCALE)
        )
        pygame.display.set_caption("NES Background")

        running = True
        while running:
            for event in pygame.event.get():
                if event.type == pygame.QUIT:
                    running = False

            executed = console.step_until_next_frame()

            framebuffer = console.render_background_framebuffer()
            draw_framebuffer(window, framebuffer, SCALE)
            pygame.display.flip()

            if debug_mode:
                print(
                    f"frame={console.ppu.frame} "
                    f"pc=${cpu.pc:04X} "
                    f"instructions={executed}"
                )
    except KeyboardInterrupt:
        print("

Ejemplo de implementación sugerido

    finally:
        pygame.quit()


if __name__ == "__main__":
    main()

Ver código del testtest_295_manual_main_pygame_background_display.py

import inspect
import importlib
from pathlib import Path


background_main = importlib.import_module("main_only_background")


def test_main_only_background_py_exists_and_exposes_visual_runner_configuration():
    """
    Objective:
    main_only_background.py is the background-only visual manual runner and exposes
    the expected manual knobs.
    """
    assert Path("main_only_background.py").exists()
    assert hasattr(background_main, "ROM_PATH")
    assert hasattr(background_main, "debug_mode")
    assert hasattr(background_main, "SCALE")
    assert hasattr(background_main, "main")
    assert callable(background_main.main)


def test_main_only_background_rom_path_points_to_local_mariobros_file_name_without_requiring_it():
    """
    Objective:
    main_only_background.py documents the expected local ROM filename, but pytest
    must not require that file to exist.
    """
    assert isinstance(background_main.ROM_PATH, Path)
    assert background_main.ROM_PATH.name == "MarioBros.nes"


def test_main_only_background_debug_mode_exists_but_test_does_not_freeze_value():
    """
    Objective:
    debug_mode is a manual/developer knob. The test verifies existence only so
    future tutorial steps can change the default.
    """
    assert hasattr(background_main, "debug_mode")


def test_main_only_background_scale_exists_for_manual_window_size():
    """
    Objective:
    SCALE controls how large each NES framebuffer pixel appears in the pygame
    window.
    """
    assert isinstance(background_main.SCALE, int)
    assert background_main.SCALE >= 1


def test_main_only_background_uses_real_rom_boot_construction_path():
    """
    Objective:
    main_only_background.py should keep the same emulator ownership path as
    core_validator.py.
    """
    source = inspect.getsource(background_main.main)

    assert "Cartridge.from_ines_bytes" in source
    assert "CpuBus(cartridge=cartridge)" in source
    assert "CPU(cpu_bus)" in source
    assert "Console(cpu=cpu, ppu=cpu_bus.ppu)" in source
    assert "cpu.reset()" in source


def test_main_uses_pygame_window_loop_concepts():
    """
    Objective:
    main_only_background.py should contain the core pygame window-loop operations
    without tests opening the window.
    """
    source = inspect.getsource(background_main.main)

    assert "pygame.init()" in source
    assert "pygame.display.set_mode" in source
    assert "pygame.display.set_caption" in source
    assert "pygame.event.get()" in source
    assert "pygame.QUIT" in source
    assert "pygame.display.flip()" in source
    assert "pygame.quit()" in source


def test_main_renders_background_framebuffer_and_draws_it():
    """
    Objective:
    The visual runner should display the emulator-produced background framebuffer,
    not a synthetic checkerboard.
    """
    source = inspect.getsource(background_main.main)

    assert "console.render_background_framebuffer()" in source
    assert "draw_framebuffer" in Path("main_only_background.py").read_text()
    assert "draw_framebuffer(window, framebuffer, SCALE)" in source


def test_main_steps_emulation_by_frame_before_drawing():
    """
    Objective:
    main_only_background.py should advance emulation using the frame-level helper
    before rendering the next visible background.
    """
    source = inspect.getsource(background_main.main)

    assert "console.step_until_next_frame()" in source


def test_main_can_exit_by_window_close_or_ctrl_c():
    """
    Objective:
    The manual visual loop should support both pygame window close and Ctrl+C.
    """
    source = inspect.getsource(background_main.main)

    assert "running = True" in source
    assert "running = False" in source
    assert "KeyboardInterrupt" in source
    assert "Stopped by user" in source


def test_main_has_main_guard_so_importing_does_not_start_window_loop():
    """
    Objective:
    Importing main_only_background.py from pytest must not open a pygame window.
    """
    source = Path("main_only_background.py").read_text()

    assert 'if __name__ == "__main__"' in source
    assert "main()" in source


def test_pygame_stays_outside_emulator_core_modules():
    """
    Objective:
    pygame belongs in manual/frontend code. The emulator core should still be
    importable and testable without pygame.
    """
    core_files = [
        Path("emulator/bus/cpu_bus.py"),
        Path("emulator/console.py"),
        Path("emulator/input/controller.py"),
        Path("emulator/rendering/framebuffer.py"),
        Path("emulator/rendering/ppu_background_renderer.py"),
        Path("emulator/rendering/nametable_renderer.py"),
    ]

    for file_path in core_files:
        assert "import pygame" not in file_path.read_text()

Funciones de test (11)

test_main_only_background_py_exists_and_exposes_visual_runner_configuration
test_main_only_background_rom_path_points_to_local_mariobros_file_name_without_requiring_it
test_main_only_background_debug_mode_exists_but_test_does_not_freeze_value
test_main_only_background_scale_exists_for_manual_window_size
test_main_only_background_uses_real_rom_boot_construction_path
test_main_uses_pygame_window_loop_concepts
test_main_renders_background_framebuffer_and_draws_it
test_main_steps_emulation_by_frame_before_drawing
test_main_can_exit_by_window_close_or_ctrl_c
test_main_has_main_guard_so_importing_does_not_start_window_loop
test_pygame_stays_outside_emulator_core_modules