Baekalfen/PyBoy
PyBoy
PyBoy is a programmable Game Boy emulator and hardware simulation framework written in Python. It functions as an emulation engine that allows users to execute original handheld software while providing a programmatic interface to control, probe, and automate game execution.
The project is specifically designed as a reinforcement learning environment, exposing emulator states and controls to facilitate the training of machine learning agents. It distinguishes itself by providing tools for game area mapping and the extraction of simplified 2D screen representations and collision maps to support artificial intelligence.
The system covers a broad range of capabilities including cycle-accurate hardware emulation, direct memory read and write operations, and a callback system for execution hooks. It supports the extraction of real-time game data, such as sprite positions and memory symbols, and includes a headless execution mode to accelerate simulation speed by bypassing graphics and audio rendering.
The emulator also provides utilities for state persistence via snapshot serialization, input simulation for autonomous agents, and tools for memory analysis and ROM data modification.
Features
- Programmable Emulator APIs - Provides a programmable emulator with a Python API for automating inputs and managing emulation state.
- Reinforcement Learning Environments - Provides a simulated Game Boy environment specifically designed for training reinforcement learning agents.
- Emulator Headless Modes - Offers a headless execution mode to accelerate simulation speed by bypassing graphics and audio rendering for AI training.
- High-Speed Simulators - Runs simulations at high speed to shorten training cycles for reinforcement learning agents.
- Reinforcement Learning Environments - Exposes a standardized interface for state, action, and reward logic to train reinforcement learning agents.
- Hardware State Inspectors - Provides a public API for external scripts to read and modify internal registers and system memory.
- Instruction-To-Function Mappings - Decodes original binary machine code by mapping opcodes directly to corresponding Python functions for emulation.
- Game Boy Emulators - Functions as a programmable emulator specifically for Game Boy ROMs using Python.
- Emulation State Scripting - Provides a programmatic interface to manage the emulator as an object to automate gameplay and adjust execution speed.
- Real-time State Debugging - Allows for the live inspection of game object properties, health, and sprite positions during execution.
- Real-time Game Data Extraction - Enables real-time extraction of screen tile identifiers, sprite positions, and internal scores during emulation.
- Retro Game Emulation - Implements a full emulator to run classic Game Boy handheld software on modern operating systems.
- Emulator State APIs - Exposes internal registers and system memory through a public API for external scripting and automation.
- Real-time State Hooks - Provides programmatic interfaces to consume live game state data such as player positions and scores.
- Handheld Console Emulation - Replicates handheld gaming hardware to execute original Game Boy ROMs on modern architectures.
- Hardware Component Simulation - Simulates Game Boy hardware components, including the CPU and memory, for accurate software execution.
- Memory-Mapped I/O - Manages communication between the CPU and hardware components by assigning controls to specific memory addresses.
- Hardware Emulators - Provides the hardware emulation as a programmable Python object for scripted control and probing.
- Cycle-Accurate Emulators - Implements cycle-accurate hardware emulation to precisely mimic the timing and behavior of the original Game Boy.
- Autonomous Game Agents - Sends external control signals and reports on-screen objects to enable autonomous AI agents to play games.
- Game Automation Systems - Enables automated gameplay and behavior verification through scripted inputs and memory state monitoring.
- Visual Game State Analysis - Analyzes visual screen data and memory symbols to derive the current state of the game for AI agents.
- Execution Hooks - Triggers custom callback functions when the system executes specific memory addresses or symbols.
- Retro Game Debuggers - Provides execution hooks and graphics visualization to analyze the internal logic of legacy game software.
- Headless Execution Modes - Bypasses graphics and audio rendering to accelerate emulation speed for automated testing and AI training.
- Emulator Save State Managers - Provides capabilities to capture and restore the exact volatile memory state of the emulated system.
- Game Memory Modifiers - Allows inspecting and modifying CPU registers and system memory to inject cheat codes or alter game variables.
- Game Memory Extraction - Extracts real-time state values, such as player scores and sprite positions, from game memory.
- Game State Manipulators - Manipulates game execution and memory through scripts to automate inputs and probe internal variables.
- Memory-Based - Allows the retrieval of specific sprite and tile objects, including positions and identifiers, directly from memory.
- Screen Map Data Extraction - Extracts simplified 2D screen representations and collision maps from the emulation to support AI training.
- Direct Memory Access - Enables direct reading and writing of raw memory addresses and CPU registers to modify game state.
- Memory Address Identification - Includes tools for discovering and identifying the specific memory addresses where game variables are stored.
- Execution Speed Controls - Implements mechanisms to manage the temporal execution rate of the emulated system via multipliers.
- Machine State Serialization - Captures a binary dump of all registers and memory to save and restore the complete system state.
- Execution Event Hooks - Triggers custom user-defined functions when the emulator reaches specific memory addresses or system symbols.
- Game Input Simulation - Sends button presses and releases with specific frame delays to simulate human interaction with the game.
- Emulator Development - Hardware overview for emulator development purposes.
