Skip to content
picogame

How picogame works

This page is the mental model behind picogame. No setup, no API details — just the handful of ideas that make everything else click. If you’ve made games elsewhere, this is also the fastest way to map what you know onto picogame.

The big idea: describe the scene, then say what moved

Section titled “The big idea: describe the scene, then say what moved”

Most of a game’s screen doesn’t change from frame to frame — the background stays put, only a few things move. picogame is built around that.

You describe a scene once (these sprites, this tilemap, this background), and then each frame you just change what moved (ball.x += 3) and call scene.refresh(). The engine works out which little rectangles actually changed and redraws only those — it doesn’t repaint the whole screen. Nothing moved? Nothing is sent to the display.

That’s why real games run smoothly on a tiny, slow chip: the work each frame is proportional to how much changed, not to the size of the screen. You get this for free — you never manage it yourself.

The pieces you build a scene from

Section titled “The pieces you build a scene from”

You’ll meet these by name everywhere. Each one is just a kind of thing you can put in a scene:

  • Sprite — a movable picture: the player, an enemy, a bullet, a coin. It has a position, can be flipped, animated through frames, scaled and rotated.
  • Tilemap — a big grid built from a small set of tile pictures: a level, a tiled background, a brick wall. Cheap, because the grid stores one number per cell instead of every pixel.
  • Bitmap — the actual picture a sprite or tile draws. You can generate one in code (a circle, a rectangle) or convert it from a PNG.
  • Scene — the container that holds all of the above and draws them in order. You add things to it, then refresh it each frame.
  • A camera — the scene has a viewpoint you can move (set_view), so the world can be bigger than the screen and scroll as the player walks.

There are a few more specialised pieces (a drawing Canvas, full-frame StripDraw effects, Particles) — you’ll reach for those once you need them. See the feature guide for “which one when”.

The game loop

Section titled “The game loop”

Every picogame game is the same shape:

  1. Read input — which buttons are down.
  2. Update — move things, run game rules, spawn and remove objects.
  3. Refresh — scene.refresh() draws the changes.
  4. Wait — a clock caps the framerate so the game runs at a steady speed.
while True:
    buttons.poll()           # 1. input
    ball.x += speed            # 2. update
    scene.refresh()            # 3. draw what changed
    clock.tick()               # 4. hold the framerate

Everything else — collisions, sound, score — happens in step 2. That’s the entire structure of a picogame game.

You build on your computer first

Section titled “You build on your computer first”

picogame ships with a simulator: the exact same game code runs on your PC, either as headless screenshots (great for quick checks) or a live, playable window. You design, debug and iterate without touching hardware — and only copy the finished game to the device at the end. The device and the simulator run the same code, so what you see on screen is what you’ll get.

Where to go next

Section titled “Where to go next”