What is PixelRoot32?¶

PixelRoot32 is a lightweight, modular 2D game engine written in C++ designed specifically for ESP32 microcontrollers, with a native simulation layer for PC (SDL2) that allows you to develop and debug quickly on your desktop before deploying to hardware.

Simple Definition¶

PixelRoot32 is a game engine that lets you create retro-style 8-bit/16-bit video games directly on an ESP32 board, with the ability to develop and test on your PC before transferring code to hardware.

Key Features¶

🎮 Scene-Based Architecture¶

• Scene system inspired by Godot Engine
• Intuitive management of levels, menus, and screens
• Simple transitions between scenes

🎨 Optimized Rendering¶

• 1bpp (monochrome) sprites as the standard format
• Support for multi-layer sprites (MultiSprite)
• Experimental 2bpp and 4bpp formats for higher fidelity
• Retro color palette system (NES, GameBoy, PICO-8, etc.)
• Compact tilemaps for backgrounds and levels
• 2D camera with dead-zone for smooth scrolling
• Render layer system (background, gameplay, UI)

🔊 NES-like Audio¶

• 4 audio channels (2 Pulse, 1 Triangle, 1 Noise)
• Integrated sound effects system
• Music player for background melodies
• Backends for ESP32 (internal DAC or external I2S) and SDL2

🎯 Physics and Collisions¶

• AABB (Axis-Aligned Bounding Box) collision system
• PhysicsActor with gravity, friction, and restitution
• Collision layers and masks for fine control
• World boundary collision detection

🖥️ User Interface¶

• Basic elements: Labels, Buttons, Panels
• Automatic layouts: Vertical, Horizontal, Grid, Anchor
• Integrated D-pad navigation
• Scroll and viewport culling for long lists

⚡ Optimized for ESP32¶

• Efficient memory management
• Integrated object pooling
• No dynamic allocations in the game loop
• Performance optimized for limited hardware

Typical Use Cases¶

PixelRoot32 is ideal for creating:

• Arcade Games: Space Invaders, Pong, Breakout
• Platformers: Horizontal scrolling games with simple physics
• Puzzles: Tetris, Snake, logic games
• Simple RPGs: Basic role-playing games with tilemaps
• Shooters: Vertical or horizontal shooting games
• Rapid Prototypes: Quick development of game ideas

Supported Platforms¶

ESP32¶

• Display: TFT_eSPI (ST7735, ILI9341, ST7789, etc.)
• Audio: Internal DAC (GPIO 25/26) or external I2S (MAX98357A, PCM5102)
• Input: Digital buttons, D-pad
• Hardware: Any ESP32 board (ESP32-WROOM, ESP32-WROVER, etc.)

Desktop/Native (PC)¶

• Display: SDL2 (Windows, Linux, macOS)
• Audio: SDL2 Audio
• Input: Keyboard, mouse
• Usage: Development, debugging, testing

Note: Support for u8g2 (OLEDs) is planned for the future.

Project Status¶

Current Version: v0.2.0-dev

PixelRoot32 is under active development. APIs may change and some subsystems are still experimental. Occasional changes or breaking changes are expected, especially on less-tested configurations.

Stable Features¶

• Scene and entity system
• Basic rendering (1bpp sprites)
• NES-like audio system
• Basic physics and collisions
• Basic UI system
• ESP32 and Native support

Experimental Features¶

• 2bpp and 4bpp sprites (require compilation flags)
• Scene Arena (advanced memory management)

Planned Features¶

• Support for u8g2 (OLEDs)
• Music compiler
• Tilemap compiler
• Save/load system
• Spatial partitioning for collisions

Quick Comparison¶

When to use PixelRoot32?¶

✅ Use PixelRoot32 if: - You want to create retro games on ESP32 - You need a lightweight and efficient engine - You prefer a simple and clear architecture - You want to develop on PC and deploy to ESP32 - You like 8-bit/16-bit style games

❌ Don't use PixelRoot32 if: - You need 3D graphics - You require advanced shaders - You need complex physics (advanced physics engines) - You want to create modern AAA games - You need support for multiple mobile platforms

Next Step¶

Now that you understand what PixelRoot32 is, discover why you should use it or go directly to your first project.

See also: - Fundamental Concepts - Installation - API Reference