Your first game

Goal: a red ball you can drive around the screen with the arrow keys — running on your computer, no PicoPad needed. About five minutes. If you can run a Python script, you can do this.

Tip

You don’t need any hardware, any art, or any C toolchain to start. Everything here runs in the desktop simulator that ships with picogame.

1. Get the project

1. You need Python 3 and the picogame project (the picogame repo) with its lib/ helpers and sim/ simulator. Pillow is used for screenshots:

   pip install pillow

2. (Optional) for a live, playable window instead of screenshots, also install pygame:

   pip install pygame

2. Write the game

Save this as first_game.py. It’s the whole game — about a dozen lines:

import picogame as pg
import picogame_game        # one-call setup
import picogame_input       # buttons
import picogame_clock       # frame timing
import picogame_shapes as shapes   # make simple bitmaps in code

# Take over the screen and get a scene to draw into.
scene, bufA, bufB = picogame_game.setup(background=pg.rgb565(20, 24, 40))
buttons = picogame_input.Buttons()
clock = picogame_clock.Clock(30)        # aim for 30 frames per second

# A red ball — a 24px circle drawn in code, so we need no art yet.
ball = pg.Sprite(shapes.circle(24, pg.rgb565(230, 80, 80)), 150, 110)
scene.add(ball)

# The game loop: read input, move, redraw — forever.
while True:
    buttons.poll()
    ball.x += (buttons.is_pressed(buttons.RIGHT) - buttons.is_pressed(buttons.LEFT)) * 3
    ball.y += (buttons.is_pressed(buttons.DOWN) - buttons.is_pressed(buttons.UP)) * 3
    scene.refresh()
    clock.tick()

▶ Try it in the browser

You can run it right here in the browser with Try it, or save it as first_game.py and run it in the simulator (below).

3. Run it

From the project folder:

# headless: runs ~30 frames holding RIGHT+DOWN, saves a screenshot
python3 sim/run.py first_game.py --frames 30 --hold RIGHT,DOWN --shot out.png

# or a live, playable window (needs pygame):
python3 sim/run.py first_game.py --backend pygame

You’ll see the ball sitting in the dark-blue screen — and in the live window, the arrow keys drive it around:

What just happened

Only four ideas carry the whole game — the rest is detail you’ll meet later:

Line	Idea
picogame_game.setup(...)	Hands you a scene — the thing you draw into — and clears the screen. One call hides all the display setup.
pg.Sprite(shapes.circle(...), x, y)	A sprite is a movable picture. Here the picture is a circle we generated in code; later it’ll be your own art.
scene.add(ball)	Put the sprite in the scene so it gets drawn.
the while loop	The game loop: every frame, read input → change things → scene.refresh(). The engine redraws only what moved.

Why colors look like `rgb565(r, g, b)`

The screen stores colors in a packed format. You never deal with that directly — just build every color with pg.rgb565(red, green, blue) (each 0–255) and it works everywhere.

Next steps

• How picogame works — the five-minute mental model, so the next things you build make sense.
• The tutorials — build a real Breakout, then a shooter, then an RPG, one new idea per step.
• Want to use real art instead of code-drawn shapes? See the art in the tutorials.