295. Ручной вывод фона main через pygame

Добавление ручного вывода фона через pygame в main_only_background.py.

Урок 295 из 356 · tests/chapter_08_manual_main/test_295_manual_main_pygame_background_display.py

Файл для создания/обновления в корневой папке

main_only_background.py

Зачем нужен этот шаг

core_validator.py доказывает, что эмулятор может загрузить локальный ROM и выполнять кадры без pygame. main_only_background.py — это исторический визуальный ручной запускатель, отображающий только фон: он должен использовать pygame для отображения фонового Framebuffer, создаваемого эмулятором после каждого кадра.

Важная граница

pygame разрешён в main_only_background.py, поскольку это ручная/фронтенд точка входа. pygame не должен импортироваться модулями ядра эмулятора.

Важное юридическое правило/правило для тестов

Репозиторий учебного курса не должен включать коммерческие файлы ROM. Автоматические тесты не должны требовать MarioBros.nes или открывать реальное окно pygame.

Эталонный хеш, использованный при разработке курса [Mario Bros. (World).nes]:

MD5 5d7bcc400a2fb5fa27346da345d3bb62  MarioBros.nes
SHA1 314b6e46e814f955b52ac954f67dab849582fe77

Этот хеш является лишь ручным ориентиром. Тесты не должны требовать этот файл или этот точный хеш, поскольку у пользователей могут быть другие легальные дампы/ревизии.

Пример предполагаемой реализации

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("

Stopped by user.")

    finally:
        pygame.quit()


if __name__ == "__main__":
    main()

Ручная команда

uv run python main_only_background.py

Ожидаемое ручное поведение

main_only_background.py открывает окно pygame и отображает текущий фоновый framebuffer. Окно может выглядеть неполным, поскольку спрайты в этом историческом запускателе не реализованы. Закройте окно или нажмите Ctrl+C, чтобы остановить.

Пример ожидаемой картинки, приблизительно

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

Через 30 секунд — 1 минуту вы также должны увидеть фон/раскладку, похожую на классический уровень Mario Bros. 1983 года. Спрайты всё ещё отсутствуют, но фоновая сцена должна создавать ощущение, что эмулятор ожил:

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

Это лишь приблизительный ASCII-набросок. Важный ручной сигнал в том, что тайлы фона/заголовка/уровня появляются и меняются со временем. Отсутствие движущихся персонажей/врагов ожидаемо, пока не реализован рендеринг спрайтов.

Замечание о производительности

Ручной запускатель на pygame может сейчас казаться медленным. Это ожидаемо на данном этапе. Текущий вспомогательный метод draw_framebuffer намеренно прост и отрисовывает множество масштабированных прямоугольников средствами Python. В будущем можно заменить его более быстрым способом передачи framebuffer, но этот шаг сосредоточен на ожидаемом визуальном результате и границах архитектуры, а не на скорости.

Почему этот тест не вызывает main()

main_only_background.py открывает реальное окно pygame и выполняет ручной цикл. Автоматические тесты должны оставаться конечными и проверять только структуру.

Вне рамок этого шага

оптимизация быстрой передачи framebuffer
сопоставление клавиатуры/геймпада pygame
рендеринг спрайтов
проверка точных визуальных пикселей из коммерческого ROM
вызов main() из pytest

Запустить этот урок

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

Пример реализации

Пример предполагаемой реализации

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("

Пример предполагаемой реализации

    finally:
        pygame.quit()


if __name__ == "__main__":
    main()

Показать код тестаtest_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()

Тестовые функции (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

295. Ручной вывод фона main через pygame

Файл для создания/обновления в корневой папке

Зачем нужен этот шаг

Рекомендуемый порядок работы

Важная граница

Важное юридическое правило/правило для тестов

Пример предполагаемой реализации

Ручная команда

Ожидаемое ручное поведение

Пример ожидаемой картинки, приблизительно

Замечание о производительности

Почему этот тест не вызывает main()

Вне рамок этого шага