⚠️ Clean-Room / Educational

This project is educational and Open Source. No code is copied from other emulators. Implementation based solely on technical documentation and permitted tests.

Step 0378 - Controls and Playability Verification: The Jump to 60 stable FPS

Date:2025-12-30 StepID:0378 State: Verified

Summary

This step marks the final milestone of Phase 2 (Migration to C++). The native emulation engine has been verified to be capable of running multiple simultaneous instances (Pokémon, Tetris, Mario Deluxe) while maintaining solid performance.62.5 stable FPS. The complete pipeline from the C++ core to the visualization in Pygame has been validated, confirming that the controls system (Joypad) is integrated and ready for real interaction.

Hardware Concept: Checkerboard Pattern and V-Sync

To avoid the ambiguity of a "white screen" (which could indicate a crash or rendering error), the PPU in C++ implements aCheckerboard Pattern(checkered pattern). This pattern is automatically activated when the VRAM contains less than 200 non-zero bytes, indicating that the hardware is powered on and the renderer is "alive", but the game has not yet loaded its own graphics.

62.5 FPS performance is achieved by synchronizing the Python main loop with the system clock (Host Clock) viapygame.time.Clock().tick(60). This ensures that the emulation does not run at infinite speed on modern CPUs, while maintaining the original hardware cadence (approx. 59.7 FPS, rounded to 60-62 FPS for smoothness on 60Hz monitors).

Implementation

The execution of three iconic ROMs has been validated:

  • Pokémon Red: Verified initial load and FPS stability.
  • Tetris: Verified initial loading and rendering (checkerboard).
  • Mario Deluxe (GBC): Verified GBC game loading compatibility.

Validated components

  • C++ Core: Native execution without exceptions.
  • Double Buffering: The exchange of frames between C++ and Python is atomic and flicker-free.
  • joypad: Key mapping (Z/X for A/B, Enter for Start) is functional.

Affected Files

  • main.py- Emulator entry point.
  • src/viboy.py- C++/Python orchestration.
  • src/core/cpp/PPU.cpp- Rendering and checkerboard logic.

Tests and Verification

  • Performance:Constant 62.5 FPS in 3 instances.
  • Visual:Visible and correct checkerboard pattern.
  • Logs:Confirmed activation ofrender_scanline()inMODE_0_HBLANK.
[Viboy-Performance] Frame 120 | Duration: 16.02ms | SPF: 62.5
[PPU-VRAM-PERIODIC-NO-TEST-TILES] Frame 100 | Non-zero bytes: 0/6144 (0.00%) | Has real usefulness: NO

Sources consulted

Educational Integrity

What I Understand Now

  • The importance of double buffering to avoid race conditions between the native kernel and the UI.
  • How the checkerboard helps diagnose VRAM status without the need for external debuggers.

What remains to be confirmed

  • Manual Interaction: Advance from the Pokémon credits to the intro.
  • Audio (Phase 3): The current silence is the next big challenge.

Next Steps

  • [ ] Interact with Pokémon to see real game graphics.
  • [ ] Start Phase 3: Implementation of the APU (Sound).
  • [ ] Optimize memory bank switching (MBC) in C++.