Frequently Asked Questions¶

Common questions about PixelRoot32, organized by category.

General¶

What is PixelRoot32?¶

PixelRoot32 is a lightweight, modular 2D game engine designed for ESP32 microcontrollers. It provides a complete game development framework with rendering, audio, physics, input, and UI systems, optimized for limited hardware resources.

What platforms does it support?¶

ESP32: Primary platform (TFT displays, GPIO buttons, DAC/I2S audio)
Native/Desktop: Development platform (SDL2, keyboard, SDL2 audio)

What kind of games can I make?¶

PixelRoot32 is ideal for: - Retro/arcade-style games - 2D platformers - Shooters - Puzzle games - Simple RPGs - Educational games

See Limitations and Considerations for what's not suitable.

Is it free to use?¶

Yes, PixelRoot32 is open source and licensed under the MIT License. You can use it freely for personal and commercial projects.

Where can I find the source code?¶

Engine: https://github.com/Gperez88/PixelRoot32-Game-Engine
Samples: https://github.com/Gperez88/PixelRoot32-Game-Samples
Documentation: https://github.com/PixelRoot32-Game-Engine/PixelRoot32-Docs

Installation and Configuration¶

How do I install PixelRoot32?¶

See Your First Project for detailed installation instructions.

Quick answer: 1. Install PlatformIO in VS Code 2. Create new ESP32 project 3. Add library dependency: gperez88/PixelRoot32-Game-Engine@0.2.0-dev 4. Configure hardware in platformio.ini

What version should I use?¶

Use the exact version 0.2.0-dev. Do NOT use ^ or fuzzy versioning, as the API may change.

How do I configure my display?¶

Configure TFT_eSPI via build flags in platformio.ini. See Your First Project for examples.

How do I set up audio?¶

Choose an audio backend: - ESP32_DAC: Simple, one pin (GPIO 25 or 26) - ESP32_I2S: Higher quality, requires external DAC - SDL2_AudioBackend: For Native/PC development

See Audio for details.

Development¶

How do I create a scene?¶

Inherit from pixelroot32::core::Scene and implement init(), update(), and draw(). See Scenes and Entities.

How do I add entities to a scene?¶

Create entities and call addEntity() in init(). The scene manages them automatically.

What's the difference between Entity, Actor, and PhysicsActor?¶

Entity: Base class, can be drawn and updated
Actor: Entity with collision detection
PhysicsActor: Actor with automatic physics (velocity, gravity, friction)

See Scenes and Entities for details.

How do I handle input?¶

Access InputManager through the engine:

auto& input = engine.getInputManager();
if (input.isButtonPressed(Buttons::A)) {
    // Handle input
}

See Input and Control.

How do I play sounds?¶

Create an AudioEvent and play it:

pixelroot32::audio::AudioEvent sound{};
sound.type = pixelroot32::audio::WaveType::PULSE;
sound.frequency = 800.0f;
sound.duration = 0.1f;
engine.getAudioEngine().playEvent(sound);

See Audio.

How do I create sprites?¶

Define sprite data manually or use the Sprite Compiler tool. See Sprites and Animation.

Can I use images instead of manual sprite data?¶

Yes, use the Sprite Compiler tool to convert PNG images to sprite data. See Available Tools.

Performance¶

Why is my game running slowly?¶

Common causes: - Too many entities (MAX_ENTITIES = 32) - Too many draw calls - Expensive calculations in update() - Memory issues

See Performance Tuning for solutions.

What FPS should I target?¶

30-60 FPS is typical. Lower complexity games can achieve 60 FPS, more complex games may need to target 30 FPS.

How do I optimize my game?¶

Use object pooling
Implement viewport culling
Reduce entity count
Cache calculations
Use tilemaps for backgrounds

See Performance Tuning.

Memory¶

Why do I get "out of memory" errors?¶

ESP32 has limited RAM (~320KB). Solutions: - Use object pooling - Store data in flash (const/constexpr) - Reduce entity count - Avoid dynamic allocation

See Memory Management.

What is MAX_ENTITIES?¶

MAX_ENTITIES = 32 is a hard limit per scene. This includes all entities: actors, UI elements, particles, etc.

Solutions: - Use object pooling to reuse entities - Disable entities instead of removing - Combine multiple entities into one

How do I check available memory?¶

#ifdef PLATFORM_ESP32
Serial.print("Free heap: ");
Serial.println(ESP.getFreeHeap());
#endif

Hardware¶

Which ESP32 board should I use?¶

Any ESP32 board works. Common choices: - ESP32-WROOM-32 - ESP32-WROVER (more RAM) - ESP32-DevKit

Which display should I use?¶

Popular choices: - ST7789: 240x240, good quality - ST7735: 128x128, smaller/cheaper - ILI9341: 240x320, larger

See Platforms and Drivers.

How many buttons do I need?¶

Minimum: 4 (UP, DOWN, LEFT, RIGHT) Recommended: 6 (add A and B buttons) More buttons can be added if needed.

Can I use analog joysticks?¶

Not directly supported. You can read analog pins manually and convert to digital input, but the engine expects digital buttons.

Troubleshooting¶

My display is blank. What's wrong?¶

Check wiring connections
Verify pin numbers in platformio.ini
Lower SPI frequency
Check display type matches hardware
Verify power supply

See Troubleshooting.

Buttons don't work. Why?¶

Check button wiring
Verify pin numbers in InputConfig
Check pull-up/pull-down resistors
Ensure InputManager is being updated
Test with isButtonDown() vs isButtonPressed()

Audio is distorted. How do I fix it?¶

Lower volume levels
Reduce sample rate (try 11025 Hz)
Check for too many simultaneous sounds
Verify hardware connections
Check power supply

Game crashes randomly. What's happening?¶

Common causes: - Out of memory - Too many entities - Infinite loops - Stack overflow - Watchdog timeout

See Troubleshooting for debugging techniques.

Advanced¶

Can I extend the engine?¶

Yes, PixelRoot32 is designed to be extensible. You can: - Create custom display drivers - Create custom audio backends - Extend existing systems

See Extensibility.

Can I use 3D graphics?¶

No, PixelRoot32 is 2D-only. It's designed for sprite-based 2D games.

Can I add networking?¶

Not currently supported. The engine focuses on single-player games.

Can I save game data?¶

Not currently supported. A save system is planned for future versions.

Can I use multiple scenes at once?¶

Yes, use SceneManager to push/pop scenes. This is useful for menus and pause screens.

Getting Help¶

Where can I get help?¶

Documentation: This documentation site
Examples: Study example games in the samples project
Discord: Community Discord server
GitHub: Open an issue for bugs

How do I report a bug?¶

Create a detailed bug report with: - Platform (ESP32 or Native) - Hardware details - Minimal reproduction code - Error messages - Expected vs actual behavior

Can I contribute?¶

Yes! PixelRoot32 is open source. Check the main repository for contribution guidelines.