Sprite¶

Technical overview. The Game Boy stores up to 40 sprite entries in OAM. Each entry describes a screen position, a tile, and display attributes such as flipping, palette, and priority. Sprites can be 8 by 8 or 8 by 16 pixels and can move independently of the background tile grid.

Using the API. Sprite decodes one OAM entry into coordinates, attributes, visibility, and its associated Tile objects. Obtain sprites through the PyBoy helpers, then inspect their fields after each tick because games rewrite OAM frequently.

This class presents an interface to the sprites held in the OAM data on the Game Boy.

class pyboy.api.sprite.Sprite(mb, sprite_index)[source]¶

Bases: object

y¶

The Y-coordinate on the screen to show the Sprite. The (x,y) coordinate points to the top-left corner of the sprite.

Returns:: Y-coordinate
Return type:: int

x¶

The X-coordinate on the screen to show the Sprite. The (x,y) coordinate points to the top-left corner of the sprite.

Returns:: X-coordinate
Return type:: int

tile_identifier¶

The identifier of the tile the sprite uses. To get a better representation, see the method pyboy.api.sprite.Sprite.tiles.

For double-height sprites, this will only give the identifier of the first tile. The second tile will always be the one immediately following the first (tile_identifier + 1).

Returns:: unified tile index, including the CGB VRAM bank
Return type:: int

attr_obj_bg_priority¶

OAM bit 7. On DMG, 1 places the sprite behind nonzero background/window pixels. On CGB, this flag combines with the tile-map priority attribute to determine whether the sprite is drawn above the background.

Returns:: The state of the bit in the attributes lookup.
Return type:: bool

attr_y_flip¶

OAM bit 6. A value of 1 flips the sprite vertically.

Returns:: The state of the bit in the attributes lookup.
Return type:: bool

attr_x_flip¶

OAM bit 5. A value of 1 flips the sprite horizontally.

Returns:: The state of the bit in the attributes lookup.
Return type:: bool

attr_cgb_bank_number¶

CGB VRAM bank selected by OAM attribute bit 3. This is always 0 on DMG.

Returns:: VRAM bank number, 0 or 1.
Return type:: int

attr_palette_number¶

DMG palette selector (0 or 1), or CGB object palette number (0 to 7).

Returns:: Palette number.
Return type:: int

shape¶

Sprites can be set to be 8x8 or 8x16 pixels (16 pixels tall). This is defined globally for the rendering hardware, so it’s either all sprites using 8x16 pixels, or all sprites using 8x8 pixels.

Returns:: The width and height of the sprite.
Return type:: (int, int)

tiles¶

The Game Boy support sprites of single-height (8x8 pixels) and double-height (8x16 pixels).

In the single-height format, one tile is used. For double-height sprites, the Game Boy will also use the tile immediately following the identifier given, and render it below the first.

More information can be found in the [Pan Docs: VRAM Sprite Attribute Table (OAM)](https://gbdev.io/pandocs/OAM.html)

Returns:: A list of pyboy.api.tile.Tile object(s) representing the graphics data for the sprite
Return type:: list

on_screen¶

To disable sprites from being rendered on screen, developers will place the sprite outside the area of the screen. This is often a good way to determine if the sprite is inactive.

This check doesn’t take transparency into account, and will only check the sprite’s bounding-box of 8x8 or 8x16 pixels.

Returns:: True if the sprite has at least one pixel on screen.
Return type:: bool