Module pyboy.plugins.base_plugin

Classes

class PyBoyGameWrapper (*args, game_area_section=(0, 0, 32, 32), game_area_follow_scxy=False, **kwargs)

This is the base-class for the game-wrappers. It provides some generic game-wrapping functionality, like game_area , which shows both sprites and tiles on the screen as a simple matrix.

Expand source code

class PyBoyGameWrapper(PyBoyPlugin):
    """
    This is the base-class for the game-wrappers. It provides some generic game-wrapping functionality, like `game_area`
    , which shows both sprites and tiles on the screen as a simple matrix.
    """

    cartridge_title = None

    mapping_one_to_one = np.arange(TILES_CGB, dtype=np.uint8)
    """
    Example mapping of 1:1
    """

    def __init__(self, *args, game_area_section=(0, 0, 32, 32), game_area_follow_scxy=False, **kwargs):
        super().__init__(*args, **kwargs)
        if not utils.cython_compiled:
            self.tilemap_background = self.pyboy.tilemap_background
            self.tilemap_window = self.pyboy.tilemap_window
        self.tilemap_use_background = True
        self.mapping = np.arange(TILES_CGB, dtype=np.uint32)
        self.sprite_offset = 0
        self.game_has_started = False
        self._tile_cache_invalid = True
        self._sprite_cache_invalid = True

        self.shape = None
        """
        The shape of the game area. This can be modified with `pyboy.PyBoy.game_area_dimensions`.

        Example:
        ```python
        >>> pyboy.game_wrapper.shape
        (32, 32)
        ```
        """
        self._set_dimensions(*game_area_section, game_area_follow_scxy)
        width, height = self.shape
        self._cached_game_area_tiles_raw = array("B", [0xFF] * (width * height * 4))
        self._cached_game_area_tiles = memoryview(self._cached_game_area_tiles_raw).cast("I", shape=(width, height))

        self.saved_state = io.BytesIO()

        self.tilemap_background = self.pyboy.tilemap_background
        self.tilemap_window = self.pyboy.tilemap_window

    def enabled(self):
        return self.cartridge_title is None or self.pyboy.cartridge_title == self.cartridge_title

    def post_tick(self):
        self._tile_cache_invalid = True
        self._sprite_cache_invalid = True

    def _set_timer_div(self, timer_div):
        if timer_div is None:
            self.mb.timer.DIV = random.getrandbits(8)
        else:
            self.mb.timer.DIV = timer_div & 0xFF

    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)

    def reset_game(self, timer_div=None):
        """
        After calling `start_game`, you can call this method at any time to reset the game.

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

        if self.game_has_started:
            self.saved_state.seek(0)
            self.pyboy.load_state(self.saved_state)
            self._set_timer_div(timer_div)
            self.post_tick()
        else:
            raise utils.PyBoyException("Tried to reset game, but it hasn't been started yet!")

    def game_over(self):
        """
        After calling `start_game`, you can call this method at any time to know if the game is over.
        """
        raise NotImplementedError("game_over not implemented in game wrapper")

    def _sprites_on_screen(self):
        if self._sprite_cache_invalid:
            self._cached_sprites_on_screen = []
            for s in range(SPRITES):
                sprite = self.pyboy.get_sprite(s)
                if sprite.on_screen:
                    self._cached_sprites_on_screen.append(sprite)
            self._sprite_cache_invalid = False
        return self._cached_sprites_on_screen

    def _game_area_tiles(self):
        if self._tile_cache_invalid:
            xx, yy, width, height = self.game_area_section
            scanline_parameters = self.pyboy.screen.tilemap_position_list

            if self.game_area_follow_scxy:
                self._cached_game_area_tiles = np.ndarray(shape=(height, width), dtype=np.uint32)
                for y in range(height):
                    SCX = scanline_parameters[(yy + y) * 8][0] // 8
                    SCY = scanline_parameters[(yy + y) * 8][1] // 8
                    for x in range(width):
                        _x = (xx + x + SCX) % 32
                        _y = (yy + y + SCY) % 32
                        if self.tilemap_use_background:
                            self._cached_game_area_tiles[y, x] = self.tilemap_background.tile_identifier(_x, _y)
                        else:
                            self._cached_game_area_tiles[y, x] = self.tilemap_window.tile_identifier(_x, _y)
            else:
                if self.tilemap_use_background:
                    self._cached_game_area_tiles = np.asarray(
                        self.tilemap_background[xx : xx + width, yy : yy + height], dtype=np.uint32
                    )
                else:
                    self._cached_game_area_tiles = np.asarray(
                        self.tilemap_window[xx : xx + width, yy : yy + height], dtype=np.uint32
                    )
            self._tile_cache_invalid = False
        return self._cached_game_area_tiles

    def use_background(self, value):
        self.tilemap_use_background = value

    def game_area(self):
        """
        This method returns a cut-out of the screen as a simplified matrix for use in machine learning applications.

        Returns
        -------
        memoryview:
            Simplified 2-dimensional memoryview of the screen
        """
        tiles_matrix = self.mapping[self._game_area_tiles()]
        sprites = self._sprites_on_screen()
        xx, yy, width, height = self.game_area_section
        for s in sprites:
            _x = (s.x // 8) - xx
            _y = (s.y // 8) - yy
            if 0 <= _x < width:
                # Adding offset to try to seperate sprites from tiles
                if 0 <= _y < height:
                    tiles_matrix[_y][_x] = self.mapping[s.tile_identifier] + self.sprite_offset
                if len(s.tiles) == 2 and 0 <= _y + 1 < height:  # Sprite has two tiles
                    tiles_matrix[_y + 1][_x] = self.mapping[s.tile_identifier + 1] + self.sprite_offset

        return tiles_matrix

    def game_area_mapping(self, mapping, sprite_offest):
        self.mapping = np.asarray(mapping, dtype=np.uint32)
        self.sprite_offset = sprite_offest

    def _set_dimensions(self, x, y, width, height, follow_scrolling=True):
        self.shape = (width, height)
        self.game_area_section = (x, y, width, height)
        self.game_area_follow_scxy = follow_scrolling

    def _sum_number_on_screen(self, x, y, length, blank_tile_identifier, tile_identifier_offset):
        number = 0
        for i, x in enumerate(self.tilemap_background[x : x + length, y]):
            if x != blank_tile_identifier:
                number += (x + tile_identifier_offset) * (10 ** (length - 1 - i))
        return number

    def __repr__(self):
        adjust = 4

        sprites = "\n".join([str(s) for s in self._sprites_on_screen()])

        tiles_header = (
            " " * 4 + "".join([f"{i: >4}" for i in range(self.shape[0])]) + "\n" + "_" * (adjust * self.shape[0] + 4)
        )

        tiles = "\n".join(
            [
                (f"{i: <3}|" + "".join([str(tile).rjust(adjust) for tile in line])).strip()
                for i, line in enumerate(self.game_area())
            ]
        )

        return "Sprites on screen:\n" + sprites + "\n" + "Tiles on screen:\n" + tiles_header + "\n" + tiles

Ancestors

• pyboy.plugins.base_plugin.PyBoyPlugin

Subclasses

• GameWrapperKirbyDreamLand
• GameWrapperPokemonGen1
• GameWrapperPokemonPinball
• GameWrapperSuperMarioLand
• GameWrapperTetris

Class variables

var cartridge_title

var mapping_one_to_one

Example mapping of 1:1

Instance variables

var shape

The shape of the game area. This can be modified with PyBoy.game_area_dimensions().

Example:

>>> pyboy.game_wrapper.shape
(32, 32)

Methods

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.

Expand source code

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)

def reset_game(self, timer_div=None)

After calling start_game, you can call this method at any time to reset the game.

Args

timer_div : int

Replace timer's DIV register with this value. Use None to randomize.

Expand source code

def reset_game(self, timer_div=None):
    """
    After calling `start_game`, you can call this method at any time to reset the game.

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

    if self.game_has_started:
        self.saved_state.seek(0)
        self.pyboy.load_state(self.saved_state)
        self._set_timer_div(timer_div)
        self.post_tick()
    else:
        raise utils.PyBoyException("Tried to reset game, but it hasn't been started yet!")

def game_over(self)

After calling start_game, you can call this method at any time to know if the game is over.

Expand source code

def game_over(self):
    """
    After calling `start_game`, you can call this method at any time to know if the game is over.
    """
    raise NotImplementedError("game_over not implemented in game wrapper")

def use_background(self, value)

Expand source code

def use_background(self, value):
    self.tilemap_use_background = value

def game_area(self)

This method returns a cut-out of the screen as a simplified matrix for use in machine learning applications.

Returns

memoryview:

Simplified 2-dimensional memoryview of the screen

Expand source code

def game_area(self):
    """
    This method returns a cut-out of the screen as a simplified matrix for use in machine learning applications.

    Returns
    -------
    memoryview:
        Simplified 2-dimensional memoryview of the screen
    """
    tiles_matrix = self.mapping[self._game_area_tiles()]
    sprites = self._sprites_on_screen()
    xx, yy, width, height = self.game_area_section
    for s in sprites:
        _x = (s.x // 8) - xx
        _y = (s.y // 8) - yy
        if 0 <= _x < width:
            # Adding offset to try to seperate sprites from tiles
            if 0 <= _y < height:
                tiles_matrix[_y][_x] = self.mapping[s.tile_identifier] + self.sprite_offset
            if len(s.tiles) == 2 and 0 <= _y + 1 < height:  # Sprite has two tiles
                tiles_matrix[_y + 1][_x] = self.mapping[s.tile_identifier + 1] + self.sprite_offset

    return tiles_matrix

def game_area_mapping(self, mapping, sprite_offest)

Expand source code

def game_area_mapping(self, mapping, sprite_offest):
    self.mapping = np.asarray(mapping, dtype=np.uint32)
    self.sprite_offset = sprite_offest