Engine sample projects
PixelRoot32 — Examples
Self-contained PlatformIO projects that show how to use the engine on PC (SDL2) and ESP32-class boards. Each folder has its own platformio.ini, src/ entry point, and README.md with build flags, supported environments, and documentation links.
Typical workflow: open a project folder in PlatformIO (or run CLI from that folder), pick an environment (native, esp32dev, etc.), then:
cd <example-folder>
pio run -e <environment>On Windows, native examples may need local SDL2 include/lib paths in platformio.ini (see comments in animated_tilemap).
The engine revision for each example is defined in lib_deps inside that example’s platformio.ini (registry tag vs Git branch).
Catalogue
| Example | What it demonstrates | PlatformIO environments |
|---|---|---|
| hello_world | Minimal Scene, UILabel, button input, background color cycle | native, esp32dev , esp32s3 |
| camera | Camera2D, parallax, tile platforms, KinematicActor | native, esp32dev |
| dual_palette | Dual palette mode (background vs sprite color tables) | native, esp32dev |
| sprites | 2bpp / 4bpp sprites and animation | native, esp32dev |
| snake | Grid game, segment pool, AudioEngine + platform audio backends | native, esp32dev |
| brick_breaker | Classic Breakout: paddle, ball physics, bricks, particles, AudioEngine + MusicPlayer | native, esp32dev |
| music_demo | MusicPlayer multi-track (main + sub-tracks), tick / BPM timing, InstrumentPreset melodies + percussion presets; UI-based sound testing | native, esp32dev |
| space_invaders | Classic Space Invaders: alien formation, shooting, bunkers, score system, AudioEngine | native, esp32dev |
| physics | RigidActor / KinematicActor / StaticActor, touch, optional touch UI (CYD) | native, esp32dev, esp32cyd |
| metroidvania | 4bpp tilemaps, StaticTilemapLayerCache, platformer player | native, esp32dev |
| animated_tilemap | Tile animation, palettes, static tilemap framebuffer cache (reference depth) | native, esp32dev, esp32cyd |
| tic_tac_toe | UI, GPIO vs touch, minimax AI, vector-drawn board, MusicPlayer / melody data | native, esp32dev, esp32cyd |
| flappy_bird | Physics flappy clone, U8g2 OLED, ESP32-C3 (no audio in this sample) | native, esp32c3 |
Suggested learning order
- hello_world — engine init, one scene, text and input.
- sprites or dual_palette — graphics and color models.
- camera or metroidvania / animated_tilemap — scrolling, tilemaps, caching (read animated_tilemap for the fullest tilemap write-up).
- physics — bodies, sensors, touch.
- snake / tic_tac_toe / brick_breaker / music_demo / space_invaders — audio (events, single-track music, or multi-track reference). flappy_bird — physics + OLED, no audio subsystem.
Engine documentation
- API reference index
- Architecture
- Module docs under
docs/api/(Graphics, Physics, UI, Input, Audio, Core, …)
Format reference for per-example READMEs
The animated_tilemap example is the template for depth: opening summary, Requirements (build flags), optional technical subsection, Documentation links, Features, and Build commands. Scene intent is also described in each src/*Scene.h file.