### Install PyBoy using pip

Source: https://github.com/baekalfen/pyboy/blob/master/README.md

Install PyBoy using pip. This is the first step to getting started with the library.

```sh
pip install pyboy
```

--------------------------------

### Start Game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_super_mario_land.html

Initializes and starts the game. Control is returned on the first possible frame.

```APIDOC
## POST /game_wrapper/start_game

### Description
Call this function right after initializing PyBoy. This will start a game in world 1-1 and give back control on the first frame it's possible. The state of the emulator is saved, and using `reset_game`, you can get back to this point of the game instantly. The game has 4 major worlds with each 3 level. to start at a specific world and level, provide it as a tuple for the optional keyword-argument `world_level`.

### Method
POST

### Endpoint
/game_wrapper/start_game

### Parameters
#### Request Body
- **timer_div** (int) - Optional - Timer divisor value.
- **world_level** (tuple) - Optional - A tuple specifying the starting world and level (e.g., (3, 2)).
- **unlock_level_select** (boolean) - Optional - Whether to unlock level select (defaults to false).

### Request Example
```json
{
  "world_level": [3, 2],
  "unlock_level_select": true
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Start Game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_pinball.html

Starts the game with optional timer division and stage parameters.

```APIDOC
## POST /game/start

### Description
Starts the game with optional timer division and stage parameters. This function sets up the game state, sends the necessary inputs to start the game, and saves the initial game state.

### Method
POST

### Endpoint
/game/start

### Parameters
#### Query Parameters
- **timer_div** (int, optional) - The division value for the game timer. Defaults to None.
- **stage** (int, optional) - The stage to start the game at. Defaults to None.

### Request Example
```json
{
  "timer_div": 10,
  "stage": 1
}
```

### Response
#### Success Response (200)
- **None** - This function does not return any value.

#### Response Example
```json
null
```
```

--------------------------------

### Start Game with Optional Parameters (Python)

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_pinball.html

Starts the game with optional timer division and stage. Sends necessary inputs and saves the initial game state. Raises an exception if the game has already started.

```python
def start_game(self, timer_div=None, stage=None):
    """
    Starts the game with optional timer division and stage parameters.

    This function sets up the game state, sends the necessary inputs to start the game, and saves the initial game state.

    Parameters:
    timer_div (int, optional): The division value for the game timer. Defaults to None.
    stage (int, optional): The stage to start the game at. Defaults to None.

    Returns:
    None
    """
    if self.game_has_started:
        raise PyBoyException("Gamewrapper already started! Use 'reset' instead.")

    self._set_stage(stage)

    # Random tilemap I observed doesn't change until shortly before input is read
    while self.tilemap_background[10, 10] != 269:
        self.pyboy.tick(1, False, False)

    # tick needed count to get to the point where input is read
    self.pyboy.tick(18, False, False)

    # start game
    self.pyboy.send_input(WindowEvent.PRESS_BUTTON_A)
    self.pyboy.tick(2, False, False)
    self.pyboy.send_input(WindowEvent.RELEASE_BUTTON_A)
    # tick count needed to get to the next point where input is read
    self.pyboy.tick(95, False, False)

    self.pyboy.send_input(WindowEvent.PRESS_BUTTON_A)
    self.pyboy.tick(1, False, False)
    self.pyboy.send_input(WindowEvent.RELEASE_BUTTON_A)
    self.pyboy.tick(1, False, False)

    ticks_until_visible = 74
    self.pyboy.tick(ticks_until_visible, False, False)

    ticks_until_input_ready = 4
    self.pyboy.tick(ticks_until_input_ready, False, False)

    # needs to be called after normal initializations, otherwise it will be overwritten
    self._init_bonus_stage(stage)

    PyBoyGameWrapper.start_game(self, timer_div=timer_div)
```

--------------------------------

### Start Game with Options

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_pinball.html

Initiates the game, setting the stage and sending initial inputs. Raises an exception if the game has already started.

```python
def start_game(self, timer_div=None, stage=None):
    """
    Starts the game with optional timer division and stage parameters.

    This function sets up the game state, sends the necessary inputs to start the game, and saves the initial game state.

    Parameters:
    timer_div (int, optional): The division value for the game timer. Defaults to None.
    stage (int, optional): The stage to start the game at. Defaults to None.

    Returns:
    None
    """
    if self.game_has_started:
        raise PyBoyException("Gamewrapper already started! Use 'reset' instead.")

    self._set_stage(stage)

    # Random tilemap I observed doesn't change until shortly before input is read
    while self.tilemap_background[10, 10] != 269:
        self.pyboy.tick(1, False, False)

    # tick needed count to get to the point where input is read
    self.pyboy.tick(18, False, False)

    # start game
    self.pyboy.send_input(WindowEvent.PRESS_BUTTON_A)
    self.pyboy.tick(2, False, False)
    self.pyboy.send_input(WindowEvent.RELEASE_BUTTON_A)
    # tick count needed to get to the next point where input is read
```

--------------------------------

### Start Game Initialization

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/base_plugin.html

Starts the game by navigating menus to the first playable state and saving the initial emulator state. Optionally sets the timer's DIV register.

```python
def start_game(self, timer_div=None):
    """
    Call this function right after initializing PyBoy. This will navigate through menus to start the game at the
    first playable state.

    A value can be passed to set the timer's DIV register. Some games depend on it for randomization.

    The state of the emulator is saved, and using `reset_game`, you can get back to this point of the game
    instantly.

    Args:
        timer_div (int): Replace timer's DIV register with this value. Use `None` to randomize.
    """

    self.game_has_started = True
    self.saved_state.seek(0)
    self.pyboy.save_state(self.saved_state)
    self._set_timer_div(timer_div)
```

--------------------------------

### Initialize Bonus Stage and Start Game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_pinball.html

Initializes the bonus stage and starts the game. Ensure normal initializations are complete before calling.

```python
# needs to be called after normal initializations, otherwise it will be overwritten
            self._init_bonus_stage(stage)

            PyBoyGameWrapper.start_game(self, timer_div=timer_div)
```

--------------------------------

### PyBoy Game Wrapper: Start Game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_super_mario_land.html

Starts a game, with options to set the initial world and level, and unlock the level selector.

```APIDOC
## POST /game_wrapper/start_game

### Description
Starts a game. This function can be called right after initializing PyBoy. It returns control on the first frame it's possible. The state of the emulator is saved, and using `reset_game`, you can get back to this point of the game instantly.

### Method
POST

### Endpoint
/game_wrapper/start_game

### Parameters
#### Query Parameters
- **timer_div** (int) - Optional - Replace timer's DIV register with this value. Use `None` to randomize.
- **world_level** (tuple) - Optional - (world, level) to start the game from.
- **unlock_level_select** (bool) - Optional - Unlock level selector menu. Enabling the selector will make this function return before entering the game.

### Request Example
```json
{
  "timer_div": null,
  "world_level": [4, 1],
  "unlock_level_select": true
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "Game started successfully"
}
```
```

--------------------------------

### Install PyBoy from Requirements

Source: https://github.com/baekalfen/pyboy/wiki/Installation

Install PyBoy and its dependencies by running this command in your terminal after cloning the repository.

```bash
python3 -m pip install -r requirements.txt
```

--------------------------------

### Install PyBoy on WSL

Source: https://github.com/baekalfen/pyboy/wiki/Installation

Steps to install PyBoy within a Windows Subsystem for Linux environment. Includes updating WSL, installing Python 3, and necessary libraries.

```bash
wsl --update
```

```bash
wsl --install Ubuntu-22.04
```

```bash
sudo apt update && sudo apt upgrade
```

```bash
sudo apt install libgl1 libpulse0
```

```bash
python3 -m venv pyboy-venv
source pyboy-venv/bin/activate
```

```bash
pip install pyboy
```

--------------------------------

### Start Game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_super_mario_land.html

Starts the game, optionally from a specific world and level, or unlocks the level selector.

```APIDOC
## POST /game_wrapper/start_game

### Description
Starts the game. This function can be used to begin a new game, resume from a specific world and level, or unlock the level selector menu.

### Method
POST

### Endpoint
/game_wrapper/start_game

### Parameters
#### Request Body
- **timer_div** (int) - Optional - Value to replace the timer's DIV register. If `None`, it will be randomized.
- **world_level** (tuple) - Optional - A tuple `(world, level)` to specify the starting world and level.
- **unlock_level_select** (bool) - Optional - If `True`, unlocks the level selector menu. Defaults to `False`.

### Request Example
{
  "world_level": [4, 1],
  "unlock_level_select": false
}

### Response
#### Success Response (200)
- **message** (string) - Indicates the game has started or level selector is unlocked.

#### Response Example
{
  "message": "Game started successfully."
}
```

--------------------------------

### Initialize and Start Game with PyBoy

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_kirby_dream_land.html

Initializes the PyBoy emulator and navigates through menus to start the game. It saves the emulator state for later resets. Use `None` to randomize the timer's DIV register.

```python
self.pyboy.tick(1, False)
                if self.tilemap_background[0:3, 16] == [231, 224, 235]:  # 'HAL' on the first screen
                    break

            # Wait for transition to finish (start screen)
            self.pyboy.tick(25, False)
            self.pyboy.button("start")
            self.pyboy.tick()

            # Wait for transition to finish (exit start screen, enter level intro screen)
            self.pyboy.tick(60, False)

            # Skip level intro
            self.pyboy.button("start")
            self.pyboy.tick()

            # Wait for transition to finish (exit level intro screen, enter game)
            self.pyboy.tick(60, False)

            PyBoyGameWrapper.start_game(self, timer_div=timer_div)
```

--------------------------------

### Convert Raw Buffer to PIL Image

Source: https://github.com/baekalfen/pyboy/blob/master/docs/api/screen.html

Example of converting the raw screen buffer to a PIL Image. Ensure Pillow is installed. The screen buffer is row-major.

```python
>>> from PIL import Image
>>> image = Image.frombuffer(
...    pyboy.screen.raw_buffer_format,
...    pyboy.screen.raw_buffer_dims[::-1],
...    pyboy.screen.raw_buffer,
... ) # Just an example, use pyboy.screen.image instead
>>> image.save('frame.png')
```

--------------------------------

### Install PyBoy on Windows

Source: https://github.com/baekalfen/pyboy/wiki/Installation

Installs PyBoy on Windows using PowerShell. Requires Python 3 to be installed from python.org. Installs wheel and setuptools for build compatibility.

```powershell
py -m pip install --upgrade pip
py -m pip install wheel setuptools
py -m pip install pyboy
```

--------------------------------

### Install PyBoy on macOS

Source: https://github.com/baekalfen/pyboy/wiki/Installation

Installs Python 3 and PyBoy using Homebrew and pip. Ensure Homebrew is installed first. JPEG library may be needed if Pillow fails to build from source.

```bash
brew update
brew install python3
```

```bash
python3 -m pip install --upgrade pip
python3 -m pip install pyboy
```

--------------------------------

### Install PyBoy as a Package

Source: https://github.com/baekalfen/pyboy/wiki/Installation

Install PyBoy as a package on your system, allowing it to be used in other Python projects.

```bash
python3 -m pip install .
```

--------------------------------

### Install Test Dependencies

Source: https://github.com/baekalfen/pyboy/wiki/Run-Pytests

Install the necessary Python packages for running tests using pip.

```sh
python3 -m pip install -r requirements_tests.txt
```

--------------------------------

### Start Game with PyBoy

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_pinball.html

Initiates the game by sending button inputs and ticking the emulator. This method is used for starting a new game or resuming from a specific point.

```python
self.pyboy.tick(1, False, False)

            # tick needed count to get to the point where input is read
            self.pyboy.tick(18, False, False)

            # start game
            self.pyboy.send_input(WindowEvent.PRESS_BUTTON_A)
            self.pyboy.tick(2, False, False)
            self.pyboy.send_input(WindowEvent.RELEASE_BUTTON_A)
            # tick count needed to get to the next point where input is read
            self.pyboy.tick(95, False, False)

            self.pyboy.send_input(WindowEvent.PRESS_BUTTON_A)
            self.pyboy.tick(1, False, False)
            self.pyboy.send_input(WindowEvent.RELEASE_BUTTON_A)
            self.pyboy.tick(1, False, False)

            ticks_until_visible = 74
            self.pyboy.tick(ticks_until_visible, False, False)

            ticks_until_input_ready = 4
            self.pyboy.tick(ticks_until_input_ready, False, False)

            # needs to be called after normal initializations, otherwise it will be overwritten
            self._init_bonus_stage(stage)

            PyBoyGameWrapper.start_game(self, timer_div=timer_div)
```

--------------------------------

### Initialize and Start Game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_tetris.html

Call this method right after initializing PyBoy to navigate menus and start the game. The emulator state is saved, allowing for instant resets. Optionally, a timer DIV register value can be provided.

```python
def start_game(self, timer_div=None):
            """
            Call this function right after initializing PyBoy. This will navigate through menus to start the game at the
            first playable state.

            The state of the emulator is saved, and using `reset_game`, you can get back to this point of the game
            instantly.

            Kwargs:
                * timer_div (int): Replace timer's DIV register with this value. Use `None` to randomize.
            """

            # Boot screen
            while True:
                self.pyboy.tick(1, False)
                if self.tilemap_background[2:9, 14] == [89, 25, 21, 10, 34, 14, 27]:  # '1PLAYER' on the first screen
                    break
            self.pyboy.tick(5, False)

            # Start game. Just press Start when the game allows us.
            for i in range(2):
                self.pyboy.button("start")
                self.pyboy.tick(7, False)

            # We don't supply the timer_div arg here, as it won't have the desired effect
            PyBoyGameWrapper.start_game(self)
            self.reset_game(timer_div=timer_div)
```

--------------------------------

### Start Game in PyBoy

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_super_mario_land.html

Starts a game, optionally at a specific world and level, or unlocks the level selector. Control is returned on the first possible frame. The game state is saved.

```python
def start_game(self, timer_div=None, world_level=None, unlock_level_select=False):
            """
            Call this function right after initializing PyBoy. This will start a game in world 1-1 and give back control on
            the first frame it's possible.

            The state of the emulator is saved, and using `reset_game`, you can get back to this point of the game
            instantly.

            The game has 4 major worlds with each 3 level. to start at a specific world and level, provide it as a tuple for
            the optional keyword-argument `world_level`.

            If you're not using the game wrapper for unattended use, you can unlock the level selector for the main menu.
            Enabling the selector, will make this function return before entering the game.

            Example:
            ```python
            >>> pyboy = PyBoy(supermarioland_rom)
            >>> pyboy.game_wrapper.start_game(world_level=(4,1))
            >>> pyboy.game_wrapper.world
            (4, 1)
            ```

            Kwargs:
                * timer_div (int): Replace timer's DIV register with this value. Use `None` to randomize.
                * world_level (tuple): (world, level) to start the game from
                * unlock_level_select (bool): Unlock level selector menu
            """

            if self.game_has_started:
                raise PyBoyException("Gamewrapper already started! Use 'reset' instead.")

            if world_level is not None:
                self.set_world_level(*world_level)

            # Boot screen
            while True:
                self.pyboy.tick(1, False)
                if self.tilemap_background[6:11, 13] == [284, 285, 266, 283, 285]:  # "START" on the main menu
                    break

            self.pyboy.tick(3, False)
            self.pyboy.button("start")
            self.pyboy.tick(1, False)

            while True:
                if (
                    unlock_level_select and self.pyboy.frame_count == 71
                ):  # An arbitrary frame count, where the write will work
                    self.pyboy.memory[ADDR_WIN_COUNT] = 2 if unlock_level_select else 0
                    break
                self.pyboy.tick(1, False)

                # "MARIO" in the title bar and 0 is placed at score
                if self.tilemap_background[0:5, 0] == [278, 266, 283, 274, 280] and self.tilemap_background[5, 1] == 256:
                    # Game has started
                    break

            PyBoyGameWrapper.start_game(self, timer_div=timer_div)
```

--------------------------------

### Start Game in PyBoy

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_super_mario_land.html

Call this function right after initializing PyBoy to start a game in world 1-1 and gain control on the first possible frame. The emulator state is saved for later reset.

```python
def start_game(self, timer_div=None, world_level=None, unlock_level_select=False):
    """
    Call this function right after initializing PyBoy. This will start a game in world 1-1 and give back control on the first frame it's possible.

    The state of the emulator is saved, and using `reset_game`, you can get back to this point of the game instantly.

    The game has 4 major worlds with each 3 level. to start at a specific world and level, provide it as a tuple for the optional keyword-argument `world_level`.
    """
    pass
```

--------------------------------

### PyBoy RegisterFile Example Usage

Source: https://github.com/baekalfen/pyboy/blob/master/docs/index.html

Demonstrates how to use the `PyBoyRegisterFile` within a callback function to read and modify CPU registers, and control program flow by setting the Program Counter (PC). This example also shows how to interact with memory, such as disabling the boot ROM.

```python
def my_callback(pyboy):
        print("Register A:", pyboy.register_file.A)
        pyboy.memory[0xFF50] = 1 # Example: Disable boot ROM
        pyboy.register_file.A = 0x11 # Modify to the needed value
        pyboy.register_file.PC = 0x100 # Jump past existing code
```

```python
pyboy.hook_register(-1, 0xFC, my_callback, pyboy)
```

```python
pyboy.tick(120)
```

--------------------------------

### Install Pillow for Screen Recording

Source: https://github.com/baekalfen/pyboy/wiki/Experimental-and-optional-features

Install the Pillow library using pip to enable screen recording capabilities within PyBoy. This may require additional system dependencies.

```sh
python3 -m pip install pillow
```

--------------------------------

### Start Kirby Dream Land Game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_kirby_dream_land.html

Navigates through menus to start the game at the first playable state. Saves the emulator state for later reset. Optionally replaces the timer's DIV register.

```python
def start_game(self, timer_div=None):
    """
    Call this function right after initializing PyBoy. This will navigate through menus to start the game at the
    first playable state.

    The state of the emulator is saved, and using `reset_game`, you can get back to this point of the game
    instantly.

    Kwargs:
        * timer_div (int): Replace timer's DIV register with this value. Use `None` to randomize.
    """
    if self.game_has_started:
        raise PyBoyException("Gamewrapper already started! Use 'reset' instead.")

    # Boot screen
    while True:
        self.pyboy.tick(1, False)
        if self.tilemap_background[0:3, 16] == [231, 224, 235]:  # 'HAL' on the first screen
            break

    # Wait for transition to finish (start screen)
    self.pyboy.tick(25, False)
    self.pyboy.button("start")
    self.pyboy.tick()

    # Wait for transition to finish (exit start screen, enter level intro screen)
    self.pyboy.tick(60, False)

    # Skip level intro
    self.pyboy.button("start")
    self.pyboy.tick()

    # Wait for transition to finish (exit level intro screen, enter game)
    self.pyboy.tick(60, False)

    PyBoyGameWrapper.start_game(self, timer_div=timer_div)
```

--------------------------------

### Build PyBoy from Source

Source: https://github.com/baekalfen/pyboy/wiki/Installation

After installing dependencies, use this command to build PyBoy from the source code.

```bash
make build
```

--------------------------------

### Catch Mode Initialization

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_pinball.html

Function to start the catch mode in the game.

```APIDOC
## Catch Mode

### Description
Starts the catch mode in the game.

### Method
`start_catch_mode(pokemon, unlimited_time)`

### Description
Starts the catch mode in the game. NOTE: This method does not change stage specific values and may need a top/bottom stage change to work properly.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **pokemon** (Pokemon, optional) - The Pokemon to initiate catch mode for. Defaults to Pokemon.BULBASAUR.
- **unlimited_time** (bool, optional) - If True, the catch mode will have unlimited time. Defaults to False.

### Request Example
None

### Response
#### Success Response (200)
None

### Response Example
None
```

--------------------------------

### Start Game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_kirby_dream_land.html

Initializes the game by navigating through menus to the first playable state. Saves the current emulator state for later reset.

```APIDOC
## start_game

### Description
Call this function right after initializing PyBoy. This will navigate through menus to start the game at the first playable state. The state of the emulator is saved, and using `reset_game`, you can get back to this point of the game instantly.

### Method
`start_game(self, timer_div=None)`

### Parameters
#### Kwargs
- **timer_div** (int) - Optional - Replace timer's DIV register with this value. Use `None` to randomize.
```

--------------------------------

### start_game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_pinball.html

Starts the game with optional timer division and stage parameters. Sets up the game state and sends initial inputs.

```APIDOC
## POST start_game

### Description
Starts the game with optional timer division and stage parameters. This function sets up the game state, sends the necessary inputs to start the game, and saves the initial game state.

### Method
POST

### Endpoint
/start_game

### Parameters
#### Query Parameters
- **timer_div** (int) - Optional - The division value for the game timer. Defaults to None.
- **stage** (int) - Optional - The stage to start the game at. Defaults to None.

### Request Example
```json
{
  "timer_div": 10,
  "stage": 1
}
```

### Response
#### Success Response (200)
None

#### Response Example
```json
{
  "message": "Game started successfully"
}
```
```

--------------------------------

### Get Game Score

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_super_mario_land.html

Retrieves the current score in the game. This value starts at 0.

```python
pyboy.game_wrapper.score
```

--------------------------------

### Get Collected Coins

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_super_mario_land.html

Returns the number of coins collected. This value starts at 0.

```python
pyboy.game_wrapper.coins
```

--------------------------------

### Start Game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_pinball.html

Initiates the game with optional timer division and stage parameters. Sets up the game state, sends inputs, and saves the initial state.

```python
if self.game_has_started:
    return
```

--------------------------------

### Get Screen Dimensions

Source: https://github.com/baekalfen/pyboy/blob/master/docs/api/screen.html

Retrieve the dimensions of the raw screen buffer. The screen buffer is row-major. Example output is (144, 160).

```python
>>> pyboy.screen.raw_buffer_dims
(144, 160)
```

--------------------------------

### Get Super Mario Land Coins

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_super_mario_land.html

Retrieve the number of coins collected in Super Mario Land. Ensure the game has started before accessing.

```python
>>> pyboy = PyBoy(supermarioland_rom)
>>> pyboy.game_wrapper.start_game()
>>> pyboy.game_wrapper.coins
0
```

--------------------------------

### Get Raw Screen Buffer Color Format

Source: https://github.com/baekalfen/pyboy/blob/master/docs/api/screen.html

Retrieves the color format of the raw screen buffer. This format is subject to change. Example: 'RGBA'.

```python
>>> from PIL import Image
>>> pyboy.screen.raw_buffer_format
'RGBA'
```

```python
>>> image = Image.frombuffer(
...    pyboy.screen.raw_buffer_format,
...    pyboy.screen.raw_buffer_dims[::-1],
...    pyboy.screen.raw_buffer,
... ) # Just an example, use pyboy.screen.image instead
>>> image.save('frame.png')
```

--------------------------------

### Get Raw Screen Buffer Format

Source: https://github.com/baekalfen/pyboy/blob/master/docs/api/screen.html

Retrieve the color format of the raw screen buffer. This format is subject to change. Example output is 'RGBA'.

```python
>>> pyboy.screen.raw_buffer_format
'RGBA'
```

--------------------------------

### Initialize Pokemon Gen 1 Game Wrapper

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_gen1.html

Initializes the GameWrapperPokemonGen1 class, which wraps Pokemon Red/Blue for AI interaction. No specific setup is required beyond having PyBoy installed.

```python
__pdoc__ = {
        "GameWrapperPokemonGen1.cartridge_title": False,
        "GameWrapperPokemonGen1.post_tick": False,
    }
    
    import numpy as np
    
    import pyboy
    
    from .base_plugin import PyBoyGameWrapper
    
    logger = pyboy.logging.get_logger(__name__)
    
    
    class GameWrapperPokemonGen1(PyBoyGameWrapper):
        """
        This class wraps Pokemon Red/Blue, and provides basic access for AIs.
    
        If you call `print` on an instance of this object, it will show an overview of everything this object provides.
        """
    
        cartridge_title = None
    
        def __init__(self, *args, **kwargs):

```

--------------------------------

### PyBoy Initialization with Plugin Options

Source: https://github.com/baekalfen/pyboy/blob/master/docs/index.html

Enable and configure PyBoy plugins during initialization. Examples include AutoPause, DebugPrompt, RecordReplay, and Rewind.

```python
pyboy.PyBoy(gamerom, autopause=True, breakpoints='0x100', record_input=True, rewind=True)
```

--------------------------------

### Extract Pixel Data from PyBoy Screen

Source: https://github.com/baekalfen/pyboy/blob/master/docs/api/index.html

Extract a specific region of pixel data from the PyBoy screen buffer. This example shows how to get data for displaying 'P' from the bootrom. The screen buffer is row-major.

```python
>>> # Display "P" on screen from the PyBoy bootrom
>>> pyboy.screen.ndarray[66:80,64:72,0]
array([[255, 255, 255, 255, 255, 255, 255, 255],
       [255,   0,   0,   0,   0,   0, 255, 255],
       [255,   0,   0,   0,   0,   0,   0, 255],
       [255,   0,   0, 255, 255,   0,   0, 255],
       [255,   0,   0, 255, 255,   0,   0, 255],
       [255,   0,   0, 255, 255,   0,   0, 255],
       [255,   0,   0,   0,   0,   0,   0, 255],
       [255,   0,   0,   0,   0,   0, 255, 255],
       [255,   0,   0, 255, 255, 255, 255, 255],
       [255,   0,   0, 255, 255, 255, 255, 255],
       [255,   0,   0, 255, 255, 255, 255, 255],
       [255,   0,   0, 255, 255, 255, 255, 255],
       [255,   0,   0, 255, 255, 255, 255, 255],
       [255, 255, 255, 255, 255, 255, 255, 255]], dtype=uint8)
```

--------------------------------

### Get Screen Image

Source: https://github.com/baekalfen/pyboy/blob/master/docs/api/screen.html

Access the screen content as a PIL Image object. Remember to copy, resize, or convert this object if you intend to store it, as the backing buffer will update. Example output shows the type of the returned object.

```python
>>> image = pyboy.screen.image
>>> type(image)
<class 'PIL.Image.Image'>
>>> image.save('frame.png')
```

--------------------------------

### PyBoyWindowPlugin Initialization

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/base_plugin.html

Initializes the PyBoyWindowPlugin, setting up scaling, sound support, and renderer based on arguments.

```python
def __init__(self, pyboy, mb, pyboy_argv, *args, **kwargs):
            super().__init__(pyboy, mb, pyboy_argv, *args, **kwargs)

            self._ftime = time.perf_counter_ns()
            self.sound_support = False
            self.fullscreen = False
            self.sound_paused = True

            if not self.enabled():
                return

            scale = pyboy_argv.get("scale")
            self.scale = scale
            logger.debug("%s initialization" % self.__class__.__name__)

            self._scaledresolution = (scale * COLS, scale * ROWS)
            logger.debug("Scale: x%d (%d, %d)", self.scale, self._scaledresolution[0], self._scaledresolution[1])

            self.enable_title = True
            if not utils.cython_compiled:
                self.renderer = mb.lcd.renderer
            self.sound = self.mb.sound
```

--------------------------------

### PyBoyGameWrapper Start Game Method

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/base_plugin.html

Initiates the game by navigating menus to the first playable state. Optionally sets the timer DIV register.

```python
def start_game(self, timer_div=None):
            """
            Call this function right after initializing PyBoy. This will navigate through menus to start the game at the
            first playable state.

            """
```

--------------------------------

### PyBoyGameWrapper.start_game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/base_plugin.html

Initializes the game by navigating menus to the first playable state. It can optionally set the timer's DIV register for game randomization and saves the initial emulator state.

```APIDOC
## start_game

### Description
Call this function right after initializing PyBoy. This will navigate through menus to start the game at the first playable state. A value can be passed to set the timer's DIV register. Some games depend on it for randomization. The state of the emulator is saved, and using `reset_game`, you can get back to this point of the game instantly.

### Method
`start_game(self, timer_div=None)`

### Parameters
#### Arguments
- **timer_div** (int) - Optional - Replace timer's DIV register with this value. Use `None` to randomize.

### Request Example
```python
# Assuming 'wrapper' is an instance of PyBoyGameWrapper
wrapper.start_game(timer_div=100)
```

### Response
This method does not return a value directly but modifies the emulator state.
```

--------------------------------

### Catch Mode Setup

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_pinball.html

Sets up the game state for catch mode, including the Pokemon to catch and the game timer.

```APIDOC
## POST /game/catch/setup

### Description
Sets up the game state for catch mode, including the Pokemon to catch and the game timer.

### Method
POST

### Endpoint
/game/catch/setup

### Parameters
#### Query Parameters
- **pokemon** (Pokemon, optional) - The Pokemon to catch in this mode. Defaults to Pokemon.BULBASAUR.
- **unlimited_time** (bool, optional) - If True, the game timer is not activated, giving unlimited time in catch mode. Defaults to False.

### Request Example
```json
{
  "pokemon": "charmander",
  "unlimited_time": true
}
```

### Response
#### Success Response (200)
- **None** - This function does not return any value.

#### Response Example
```json
null
```
```

--------------------------------

### Game Initialization and Reset

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_pinball.html

Methods for starting and resetting the game, including options for timer manipulation.

```APIDOC
## POST /start_game

### Description
Starts the game with the specified stage and optional timer divisor.

### Method
POST

### Endpoint
/start_game

### Parameters
#### Query Parameters
- **stage** (string) - Required - The stage to start the game in.
- **timer_div** (int) - Optional - Replaces the timer's DIV register with this value. If None, it will be randomized.

### Request Example
```json
{
  "stage": "some_stage",
  "timer_div": 100
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful game start.

#### Response Example
```json
{
  "message": "Game started successfully."
}
```

## POST /reset_game

### Description
Resets the game to its initial state after `start_game` has been called.

### Method
POST

### Endpoint
/reset_game

### Parameters
#### Query Parameters
- **timer_div** (int) - Optional - Replaces the timer's DIV register with this value. Use `None` to randomize.

### Request Example
```json
{
  "timer_div": null
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful game reset.

#### Response Example
```json
{
  "message": "Game reset successfully."
}
```
```

--------------------------------

### PyBoyGameWrapper.start_game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_super_mario_land.html

Starts the game, optionally unlocking the level selector and setting a specific world and level.

```APIDOC
## POST /game_wrapper/start_game

### Description
Starts the game, optionally unlocking the level selector and setting a specific world and level. If the game wrapper has already been started, this method will raise a `PyBoyException`.

### Method
POST

### Endpoint
/game_wrapper/start_game

### Parameters
#### Query Parameters
- **timer_div** (int) - Optional - Replace timer's DIV register with this value. Use `None` to randomize.
- **world_level** (tuple) - Optional - A tuple representing (world, level) to start the game from.
- **unlock_level_select** (bool) - Optional - If true, unlocks the level selector menu.

### Request Example
```json
{
  "timer_div": null,
  "world_level": [4, 1],
  "unlock_level_select": true
}
```

### Response
#### Success Response (200)
This method does not return specific data on success, but initiates the game state.

#### Response Example
(No specific JSON response body for success)
```

--------------------------------

### POST /start_game

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_kirby_dream_land.html

Initializes and starts the Kirby Dream Land game, navigating through menus to the first playable state. The current emulator state is saved.

```APIDOC
## POST /start_game

### Description
Call this function right after initializing PyBoy. This will navigate through menus to start the game at the first playable state. The state of the emulator is saved, and using `reset_game`, you can get back to this point of the game instantly.

### Method
POST

### Endpoint
/start_game

### Parameters
#### Query Parameters
- **timer_div** (int) - Optional - Replace timer's DIV register with this value. Use `None` to randomize.

### Request Example
```json
{
  "timer_div": null
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful game start.
```

--------------------------------

### Pokemon Pinball - Start Catch Mode

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_pokemon_pinball.html

Starts the catch mode in the game, allowing the player to catch a specified Pokemon.

```APIDOC
## POST /game/catch/start

### Description
Starts the catch mode in the game. This method does not change stage specific values and may need a top/bottom stage change to work properly. It sets up the game state for catch mode, including the Pokemon to catch and the game timer.

### Method
POST

### Endpoint
/game/catch/start

### Parameters
#### Request Body
- **pokemon** (Pokemon) - Optional - The Pokemon to catch in this mode. Defaults to Pokemon.BULBASAUR.
- **unlimited_time** (boolean) - Optional - If True, the game timer is not activated, giving unlimited time in catch mode. Defaults to False.

### Request Example
```json
{
  "pokemon": "Charmander",
  "unlimited_time": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Catch mode started successfully."
}
```
```

--------------------------------

### PyBoy Initialization

Source: https://github.com/baekalfen/pyboy/blob/master/docs/index.html

Initialize the PyBoy emulator with a game ROM and various configuration options.

```APIDOC
## PyBoy Initialization

### Description
Initializes the PyBoy emulator. Requires a game ROM and accepts numerous keyword arguments for configuration.

### Method
`PyBoy()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **gamerom** (str or file-like object) - Required - Filepath to a game-ROM for Game Boy or Game Boy Color.
- **ram_file** (file-like object) - Optional - File-like object for RAM save data.
- **rtc_file** (file-like object) - Optional - File-like object for RTC save data.
- **window** (str) - Optional - Window display type: "SDL2", "OpenGL", "GLFW", or "null". Defaults to "SDL2".
- **scale** (int) - Optional - Window scale factor. Does not apply to API.
- **symbols** (str) - Optional - Filepath to a .sym file for symbol mapping. Specify `None` if unsure.
- **bootrom** (str) - Optional - Filepath to a boot-ROM to use. Specify `None` if unsure.
- **sound_volume** (int) - Optional - Sound volume in percent (0-100). Defaults to 100.
- **sound_emulated** (bool) - Optional - Disables sound emulation. Defaults to True.
- **sound_sample_rate** (int) - Optional - Sound sample rate. Must be divisible by 60. Defaults to 44100.
- **cgb** (bool) - Optional - Forces Game Boy Color mode. Defaults to False.
- **gameshark** (str) - Optional - GameShark codes to apply.
- **no_input** (bool) - Optional - Disables all user input. Defaults to False.
- **log_level** (str) - Optional - Logging level: "CRITICAL", "ERROR", "WARNING", "INFO", or "DEBUG". Defaults to "WARNING".
- **color_palette** (tuple) - Optional - Specifies the color palette for rendering.
- **cgb_color_palette** (list of tuple) - Optional - Specifies the CGB color palette for non-color games.
- **title_status** (bool) - Optional - Enables performance status in window title. Defaults to False.

### Plugin kwargs:
- **autopause** (bool) - [plugin: AutoPause] Enable auto-pausing when window loses focus.
- **breakpoints** (str) - [plugin: DebugPrompt] Add breakpoints on start-up (internal use).
- **record_input** (bool) - [plugin: RecordReplay] Record user input and save to a file (internal use).
- **rewind** (bool) - [plugin: Rewind] Enable rewind function.

Other keyword arguments may exist for plugins not listed here. View with `pyboy --help`.

### Request Example
```json
{
  "gamerom": "path/to/your/game.gb",
  "window": "SDL2",
  "scale": 2,
  "sound_volume": 50,
  "cgb": true,
  "log_level": "DEBUG"
}
```

### Response
#### Success Response (200)
Initializes the PyBoy instance.

#### Response Example
```json
{
  "message": "PyBoy instance initialized successfully."
}
```
```

--------------------------------

### Start Game in PyBoy

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_tetris.html

Initiates the game by navigating menus to the first playable state. The emulator state is saved for later resets. Optionally replaces the timer's DIV register.

```python
def start_game(self, timer_div=None):
    """
    Call this function right after initializing PyBoy. This will navigate through menus to start the game at the
    first playable state.

    The state of the emulator is saved, and using `reset_game`, you can get back to this point of the game
    instantly.

    Kwargs:
        * timer_div (int): Replace timer's DIV register with this value. Use `None` to randomize.
    """

    # Boot screen
    while True:
        self.pyboy.tick(1, False)
        if self.tilemap_background[2:9, 14] == [89, 25, 21, 10, 34, 14, 27]:  # '1PLAYER' on the first screen
            break
    self.pyboy.tick(5, False)

    # Start game. Just press Start when the game allows us.
    for i in range(2):
        self.pyboy.button("start")
        self.pyboy.tick(7, False)

    # We don't supply the timer_div arg here, as it won't have the desired effect
    PyBoyGameWrapper.start_game(self)
    self.reset_game(timer_div=timer_div)
```

--------------------------------

### Display PyBoy Help Information

Source: https://github.com/baekalfen/pyboy/wiki/Experimental-and-optional-features

Run this command to see an overview of all available features and command-line options for PyBoy.

```sh
$ python -m pyboy --help
```

--------------------------------

### Access PyBoy Sound Object

Source: https://github.com/baekalfen/pyboy/blob/master/docs/index.html

Use this method to get a `pyboy.api.sound.Sound` object. This can be used to get the sound buffer of the latest screen frame.

```python
>>> pyboy.sound.ndarray.shape # 801 samples, 2 channels (stereo)
(801, 2)
>>> pyboy.sound.ndarray
array([[0, 0],
       [0, 0],
       ...
       [0, 0],
       [0, 0]], dtype=int8)
```

--------------------------------

### Set World Level in PyBoy

Source: https://github.com/baekalfen/pyboy/blob/master/docs/plugins/game_wrapper_super_mario_land.html

Patches the handler for pressing start in the menu. It hardcodes a world and level to always 'continue' from. Use this before starting the game.

```python
>>> pyboy = PyBoy(supermarioland_rom)
>>> pyboy.game_wrapper.set_world_level(3, 2)
>>> pyboy.game_wrapper.start_game()
>>> pyboy.game_wrapper.world
(3, 2)
```