Limitations and Considerations¶

This document honestly documents what PixelRoot32 can and cannot do, helping you make informed decisions about using the engine.

Hardware Limitations (ESP32)¶

Memory Constraints¶

RAM: - Available: ~320KB total (varies by ESP32 model) - Heap: Limited and fragmented over time - Stack: ~8KB, avoid large stack allocations - Impact: Limits entity count, sprite data, and dynamic allocation

Flash: - Available: 4MB+ (varies by model) - Usage: Program code, sprite data, assets - Impact: Large games may approach limits

Recommendations: - Use object pooling - Store data in flash (const/constexpr) - Avoid dynamic allocation in game loop - Keep entity count low

CPU Limitations¶

Performance: - Clock Speed: 240MHz (typically) - Single-threaded: One core handles everything - Target FPS: 30-60 FPS (depends on complexity) - Frame Budget: ~16-33ms per frame at 60 FPS

Impact: - Complex games may struggle - Many entities reduce performance - Expensive calculations hurt FPS

Recommendations: - Optimize rendering - Reduce entity count - Cache calculations - Profile on hardware

Display Limitations¶

Supported Displays: - TFT displays via SPI (ST7735, ST7789, ILI9341, etc.) - Limited to SPI displays - Resolution typically 128x128 to 320x240

Constraints: - SPI communication speed limits - Display initialization complexity - Power consumption

Audio Limitations¶

Hardware: - Internal DAC: Lower quality, simple setup - I2S: Higher quality, requires external DAC - Sample rates: 11025 Hz (DAC) or 22050 Hz (I2S)

Constraints: - 4 channels total (2 Pulse, 1 Triangle, 1 Noise) - Music uses one channel - Limited simultaneous sounds - Quality limited by hardware

Software Limitations¶

Entity System¶

MAX_ENTITIES = 32 per scene - Hard limit, cannot be changed easily - Applies to all entities (actors, UI, particles, etc.) - Must manage entity count carefully

Workarounds: - Use object pooling - Reuse entities - Disable entities instead of removing - Combine multiple entities into one

No RTTI (Runtime Type Information)¶

Impact: - Cannot use dynamic_cast in most code - Type checking must be done manually - Limits polymorphism patterns

Alternatives: - Use virtual functions - Manual type checking - Tag-based systems

No Exceptions in Critical Code¶

Impact: - Cannot use try/catch in game loop - Error handling must be explicit - Crashes instead of exceptions

Best Practices: - Validate inputs - Check return values - Use assertions for debugging - Handle errors explicitly

No Dynamic Allocation in Game Loop¶

Impact: - Cannot use new/delete during gameplay - Must pre-allocate resources - Limits flexibility

Solutions: - Object pooling - Pre-allocation in init() - Static buffers - Fixed-size arrays

No Advanced Features¶

Not Supported: - 3D graphics - Shaders - Advanced physics (joints, constraints) - Networking - File system (ESP32) - Advanced audio effects

Focus: - 2D sprite-based games - Simple physics - Retro-style games - Embedded-friendly features

Experimental Features¶

2bpp Sprites¶

Status: Experimental - Requires PIXELROOT32_ENABLE_2BPP_SPRITES flag - May have bugs or limitations - Not fully tested

Use with caution: - Test thoroughly - May change in future versions - Report issues if found

4bpp Sprites¶

Status: Experimental - Requires PIXELROOT32_ENABLE_4BPP_SPRITES flag - More experimental than 2bpp - Higher memory usage

Use with caution: - Test extensively - Monitor memory usage - May be unstable

Scene Arena¶

Status: Experimental - Requires PIXELROOT32_ENABLE_SCENE_ARENA flag - Alternative memory management - May have bugs

Recommendations: - Use object pooling instead (more stable) - Test thoroughly if using - May be removed or changed

Unsupported Features (Current)¶

Planned but Not Available¶

u8g2 Driver: Alternative display driver (planned)
Music Compiler: Tool to convert music files (planned)
Tilemap Compiler: Tool to create tilemaps (planned)
Save System: Persistent storage system (planned)
Spatial Partitioning: Advanced collision optimization (planned)

Not Planned¶

3D Graphics: 2D-only engine
Networking: No network support
File System: No file I/O on ESP32
Advanced Audio: NES-like audio only
Scripting: No Lua/JavaScript support

Best Practices for ESP32¶

Memory Management¶

Pre-allocate: All resources in init()
Object pooling: Reuse entities
Flash storage: Use const/constexpr for data
Avoid strings: Use static buffers
Monitor usage: Check heap regularly

Performance¶

Limit entities: Stay well below MAX_ENTITIES
Optimize rendering: Use culling, batching
Cache calculations: Avoid repeated work
Profile on hardware: PC performance ≠ ESP32

Development¶

Test on hardware: Don't rely only on Native
Start simple: Add complexity gradually
Monitor memory: Watch for leaks
Optimize incrementally: Profile and optimize

What PixelRoot32 IS Good For¶

✅ Retro-style 2D games ✅ Arcade games ✅ Puzzle games ✅ Platformers ✅ Shooters ✅ Educational projects ✅ Prototyping ✅ Embedded game development

What PixelRoot32 is NOT Good For¶

❌ 3D games ❌ Complex physics simulations ❌ Large open worlds ❌ Games requiring many entities ❌ Games with complex graphics ❌ Network multiplayer ❌ Games requiring file I/O

Making Informed Decisions¶

Before Starting a Project¶

Assess requirements: Does PixelRoot32 fit?
Check limitations: Can you work within constraints?
Plan architecture: Design around limitations
Test early: Verify on hardware early

If Limitations Are a Problem¶

Consider alternatives: - Full game engines (Unity, Godot) for complex games - Custom solutions for specific needs - Different hardware for more resources

Or work within limits: - Simplify game design - Optimize aggressively - Use creative solutions

Version Compatibility¶

Current Version¶

Engine Version: 0.2.0-dev
API Stability: May change
Breaking Changes: Possible in future versions

Recommendations: - Pin exact version in platformio.ini - Don't use ^ or fuzzy versioning - Test after engine updates - Review changelog

Honest Assessment¶

PixelRoot32 is designed for: - Simple to medium complexity games - Retro/arcade style - ESP32 hardware constraints - Rapid development

It is not designed for: - AAA game complexity - Modern graphics - Large-scale games - Unlimited resources