# picogame

> A fast, retained-mode 2D game engine for CircuitPython on microcontrollers (RP2040 / RP2350 / ESP32-S3, e.g. the PicoPad): sprites, tilemaps, dirty-rect rendering, runtime transforms, pseudo-3D (Mode-7 & raycasting), a desktop simulator and a browser playground.


> Generated 2026-07-31 | docs commit fbd2d56 | picogame-libs 0.1.20 | API_LEVEL 1

## Build a game

- [Game-design skill](https://github.com/MakerClassCZ/picogame/tree/main/skills/picogame-game-design) — the best single resource: design fundamentals, genre playbooks, tuning numbers, RAM costs, the full API, and a desktop-simulator workflow. Load this to design and build a whole game. Overview and download: [picogame.makerclass.cz/ai-agents](https://picogame.makerclass.cz/ai-agents/).
- [Starter game](https://github.com/MakerClassCZ/picogame/blob/main/skills/picogame-game-design/templates/starter_game.py) — a minimal, correct game skeleton to copy.
- [Example games](https://github.com/MakerClassCZ/picogame/tree/main/games) — complete, runnable, tested reference games.
- [Feature demos](https://github.com/MakerClassCZ/picogame/tree/main/demos) — short demos across genres.
- [Focused examples](https://github.com/MakerClassCZ/picogame/tree/main/examples) — one engine feature per file (often the fastest way to see how a single API is used).
- [Desktop simulator](https://picogame.makerclass.cz/simulator/) — run, profile and screenshot without hardware.

## Choose a document

- Design or build a whole game -> the game-design skill above.
- Write or fix specific code -> [API reference](https://picogame.makerclass.cz/_llms-txt/api.txt) (exact engine + helper signatures).
- Understand how the engine works -> [Getting started](https://picogame.makerclass.cz/_llms-txt/getting-started.txt).
- Search across everything -> [Complete documentation](https://picogame.makerclass.cz/llms-full.txt).

## Critical implementation rules

- Build every colour with `pg.rgb565(r, g, b)`; never pass raw RGB565 integers.
- Test final builds on real hardware; the desktop simulator's timing and RAM differ.
- API_LEVEL is 1 (additive). Match the docs commit above with the picogame-libs release and firmware you flash.

## Documentation Sets

- [Abridged documentation](https://picogame.makerclass.cz/llms-small.txt): a compact version of the documentation for picogame, with non-essential content removed
- [Complete documentation](https://picogame.makerclass.cz/llms-full.txt): the full documentation for picogame
- [API](https://picogame.makerclass.cz/_llms-txt/api.txt): The picogame API only — the reference cheat sheet, the full engine API, and every helper library. This is what an agent needs to WRITE a game (signatures, no marketing).
- [Getting started](https://picogame.makerclass.cz/_llms-txt/getting-started.txt): How to start and how picogame works — the intro, the step-by-step tutorials, and the concept/explanation pages.

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [Main repository](https://github.com/MakerClassCZ/picogame): engine helpers, games, demos, simulator, tools — a clone is self-contained
- [Helper libraries (source + releases)](https://github.com/MakerClassCZ/picogame-libs): the picogame_* libs with their own changelog + circup install
- [Supported hardware](https://picogame.makerclass.cz/supported-hardware/): per-board status and limitations