Built-in Functions

All built-ins are imported from the core module:

from core import pressed, just_pressed, set_sprite, set_bg_tile, set_scroll, Button

Input

pressed(button) -> bool

Returns true if the button is currently held down.

if pressed(Button.Right):
    x := x + 1

just_pressed(button) -> bool

Returns true only on the first frame the button is pressed. Useful for actions that should trigger once (like jumping).

if just_pressed(Button.A):
    vy := -8

Button enum

Sprites

set_sprite(index, x, y, tile)

Places a sprite on screen.

set_sprite(0, 80, 72, player)

The Game Boy can display up to 40 sprites, with a limit of 10 per scanline. Sprite coordinates place the top-left corner of the 8×8 tile at (x, y). A sprite at (0, 0) is at the top-left of the screen.

Background

set_bg_tile(tx, ty, tile)

Places a tile on the background layer.

# Fill row 16 with ground tiles
let i = 0
while i < 20:
    set_bg_tile(i, 16, ground)
    i := i + 1

The background is a 32×32 grid of 8×8 tiles. The visible screen shows a 20×18 window into this grid (160×144 pixels). Use set_scroll to pan the view.

Scrolling

set_scroll(sx, sy)

Sets the background scroll position.

let scroll_x = 0

on vblank:
    scroll_x := scroll_x + 1
    set_scroll(scroll_x, 0)

Scrolling wraps around at 256 pixels in both directions. The background layer scrolls independently of sprites.

Text

print(tx, ty, "text")

Renders a string to the background layer using a built-in 8×8 ASCII font (96 characters, printable ASCII 32–127).

print(2, 4, "HELLO WORLD!")
print(3, 8, "Score: 0")

The built-in font is loaded automatically when print() is used. No tile definitions or imports are needed. The font occupies tiles after your user-defined tiles.

Large Sprites

set_sprite_16(index, x, y, top_tile, bottom_tile)

Places a 16-pixel-tall sprite using two consecutive OAM slots.

set_sprite_16(0, px, py, player_top, player_bottom)

Uses two standard sprite slots. The bottom half is drawn 8 pixels below the top.

Tile Expressions

Tile arguments in set_sprite(), set_bg_tile(), etc. accept any expression, not just tile names:

# Tile name (resolves to its index)
set_bg_tile(x, y, grass)

# Arithmetic on tile indices
set_bg_tile(x, y, grass + 1)

# Numeric tile index directly
set_bg_tile(x, y, 5)

This lets you compute tile indices at runtime for animation frames, tile variations, or font rendering.

Sound

beep()

Plays a short blip sound (A5, ~880 Hz) with fast volume decay. Good for UI feedback.

beep()  # plays a quick blip

play_tone(freq_lo, freq_hi)

Plays a tone on the Game Boy's Channel 1 square wave. Takes the raw 11-bit frequency register value split into low and high bytes.

play_tone(0x6B, 0x07)   # ~880 Hz (A5)
play_tone(0x0C, 0x06)   # ~262 Hz (C4)

The frequency formula is: freq_register = 2048 - (131072 / Hz). Common note values: