picogame

picogame is a small 2D game engine for the PicoPad - a pocket handheld (320×240 screen, D-pad + a few buttons, RP2040 with little RAM) running CircuitPython. The heavy lifting - sprites, tilemaps, a retained scene with automatic dirty-rectangle redraw, blit effects - is a native C module built into the firmware; on top of it sits a set of small Python helper libraries and a desktop simulator, so you write games in plain Python and run them on your PC before ever touching hardware.

This repository is the public collection: finished games, short demos, feature examples, step-by-step tutorials, the simulator, and the asset tools - everything you need to learn the engine and build for it. The engine itself and the helper library live in their own repos (see The wider picogame project below).

👉 Docs, guides and an in-browser playground: https://picogame.makerclass.cz/

🤖 Building with an AI coding agent? There's a ready-made picogame-game-design skill (design fundamentals, the full API, genre playbooks) and the whole docs site is published as llms.txt. See https://picogame.makerclass.cz/ai-agents/.

---

Try it without installing anything

Everything below runs in the browser - the engine itself is compiled to WebAssembly, so it is the real thing, not a mock-up:

Playground	write picogame code and run it, right on the page
Examples gallery	every game and demo in this repo, playable in one click (try corona and picatro)
Level editor	paint tilemaps, place sprites, set a follow-camera; Try in playground turns the level into a running game, Export gives you a ready <name>_scene.py
Asset converter	drop a PNG, get an engine-ready .py module (the browser twin of tools/png2picogame.py)

Both browser tools are static apps you can also self-host - their source is right here in tools/editor/ and tools/assets/.

---

What's in this repo

Folder	What it holds
games/	finished games - a demo that grew up: real assets, tuned mechanics, meant to be fun
demos/	one game genre each, playable but with placeholder art - the skeleton to start from
examples/	one engine feature each, the smallest code that shows it (FX, HUD, tilemaps, ...)
tutorials/	three guided, build-it-yourself tutorials
sim/	the desktop simulator (try/develop games on your PC)
lib/	the picogame_* helper modules — a mirror of picogame-libs
tools/	asset converters and build helpers
docs/	the documentation itself — every page of the site, as plain markdown you can read in the clone (API reference, hardware, memory, scene format) and send a PR to
skills/	the picogame-game-design skill for AI coding agents (design fundamentals, full API, genre playbooks)

The picogame_* helper modules this code imports are bundled in lib/ — a generated mirror of picogame-libs (the single source of truth, with its own changelog and circup install). A clone is self-contained — you don't fetch them separately. See lib/README.md. On a device, circup install from picogame-libs gives you versioning; the bundled lib/ is for the simulator and a zero-setup copy.

---

Quick start

Run any game or demo on the desktop simulator (needs Python 3; a live window needs pygame):

python sim/run.py games/picoracer/code.py --backend pygame   # live, playable window
python sim/run.py demos/picogame_snake.py                    # headless, runs ~150 frames
python sim/run.py demos/picogame_snake.py --shot shot.png    # + save a screenshot

Simulator controls (live pygame window):

Keyboard	Button
Arrow keys	D-pad
Z or Ctrl	A
X or Space	B
A / S	X / Y

On the PicoPad: the fastest route is a ready-made quick-start pack

• a CIRCUITPY drive image with the firmware's helper libs, a launcher and a selection of games and demos, for PicoPad and Fruit Jam. To install a single game instead, copy its folder plus the lib/ helpers it imports onto the board; each file's header comment lists what it needs.

---

Games

Complete features rich games - each in its own folder (code.py + assets):

Game	Genre
picoracer	top-down racer - 5 laps, with ghost cars replaying your earlier laps
picotris	falling-block puzzle in a reserved play-area well
picowing	vertical shoot-'em-up - hold the sky against raiders
squest	Seaquest-style underwater shooter (rescue divers, watch your air)
corona	horde survivor - your lantern auto-fires, you only move; XP, level-ups, dashes
train	Miroslav Nemecek's Czech classic Vlak (1993): a snake-on-rails puzzle, all 50 levels
picatro	poker deck-builder - play hands against rising score targets, bank your discards
bangbang	turn-based artillery duel on destructible terrain (1P vs AI or 2P hot-seat)

Demos

demos/ has a short, focused demo for each classic arcade genre - Breakout, Asteroids, Flappy, a maze chase, Snake, a platformer and more. Great for seeing how a whole genre maps onto the engine in one small file.

Examples

examples/ isolates a single engine feature per file - Canvas, StripDraw, Tilemap, Particles, the HUD, sprite anchors, scrolling/camera, save data, scene loading, juice effects, and so on. Reach for these when you want to learn one specific building block.

Tutorials

tutorials/ teaches the engine one mechanic at a time - every step is a runnable program, and the lesson is the diff to the next step. Three complete games:

• 01 - Bounce · Breakout / Arkanoid → https://picogame.makerclass.cz/tutorials/01-bounce/
• 02 - Starship · top-down space shooter → https://picogame.makerclass.cz/tutorials/02-starship/
• 03 - Quest · top-down RPG → https://picogame.makerclass.cz/tutorials/03-quest/

---

The simulator (sim/)

sim/run.py runs a game on the PC by emulating the device - it provides the picogame module and the CircuitPython stubs, so the same code runs unchanged on your machine and on the PicoPad. Useful flags:

Flag	Effect
--backend pygame	a live, playable window (default pil is headless)
--frames N	how many frames to run (headless; default 150)
--shot FILE / --shot-at N	save a screenshot (at the end, or at frame N)
--hold RIGHT,B	hold buttons for the whole run (test input headlessly)
--profile	a cProfile + per-frame allocation report

Tools (tools/)

Helpers for turning art and sound into engine-ready assets:

Script	Run it	Purpose
png2picogame.py	python tools/png2picogame.py art.png -o art.py	convert a PNG/BMP into an asset module - a single image, a --frames animation atlas, a --tile WxH tile sheet, or a --map tilemap (or use the browser version)
tiled2scene.py	python tools/tiled2scene.py map.tmx	import a map made in Tiled (.tmx/.tmj) as a picogame scene - tile layers with their flips/rotations, objects to sprites/zones/points, tile properties to flags. The level editor reads Tiled maps too (Load)
p8music.py	python tools/p8music.py song.p8 -o song.py	import music written in a PICO-8 tracker: bakes the __sfx__/__music__ sections into a bank picogame_music plays
pack_sheet.py	python tools/pack_sheet.py IN.py NAME --outdir DIR	pack a big sprite sheet into a raw .bin streamed from flash, so the pixels don't sit in RAM
scene_build.py	python tools/scene_build.py level.scene.json	bake an editor scene file into a compact runtime SCENE module the loader reads
synth_preview.py	python3 tools/synth_preview.py	render picogame_synth sound effects to .wav so you can tune them by ear (the simulator is silent)
build_mpy.sh	tools/build_mpy.sh	precompile the Python helpers to .mpy bytecode (faster load, less RAM on device)

---

The wider picogame project

This repo is the games-and-learning side of picogame. The rest:

Repository	What it is
picogame-libs	the source of truth for the picogame_* Python helpers - input, HUD/UI, clock, juice effects, sprite pools, audio, save. Releases carry .mpy builds per CircuitPython version and it installs with circup; the lib/ folder here is a mirror of it (the desktop simulator needs the .py sources, which .mpy can't provide). Type stubs for the native module ship there too - see editor setup.
circuitpython	the CircuitPython firmware fork carrying the native C engine. Branch picogame is the working branch; picogame-fruitjam is just a proposed board patch (exposing board.DISPLAY like other boards); the branch behind the upstream PR deliberately leaves out what isn't settled yet (ROMFS, core1) and is kept as stable as possible. Prebuilt firmware: downloads.
picogame-stage	a compatibility layer to run existing ugame/stage games on the picogame engine.

And the home base - docs, feature guides, the glossary, and a playground that runs picogame in your browser: https://picogame.makerclass.cz/