Troubleshooting¶

This guide helps you diagnose and fix common issues when developing with PixelRoot32.

Compilation Problems¶

Common Compilation Errors¶

Error: Library not found

Solution: Ensure PixelRoot32-Game-Engine is properly installed
- Check platformio.ini has correct lib_deps
- Verify library version matches (use exact version, not ^)
- Try: pio lib install

Error: Include file not found

Solution: Check include paths
- Verify lib_extra_dirs in platformio.ini
- Check that library is in lib/ directory
- Ensure correct namespace (pixelroot32::)

Error: Undefined reference

Solution: Link missing libraries
- Check all required libraries are listed
- Verify TFT_eSPI is installed for ESP32
- Check SDL2 is installed for Native builds

Error: Build flags not recognized

Solution: Verify build flag syntax
- Use -D FLAG_NAME (not --define)
- Check flag names are correct
- Ensure flags are in correct environment section

Configuration Issues¶

Wrong display type: - Verify DisplayType matches your hardware - Check TFT_eSPI build flags match display - Test with different display types

Incorrect pin configuration: - Verify GPIO pins match your wiring - Check pin numbers in platformio.ini - Ensure pins aren't used by other peripherals

Hardware Problems (ESP32)¶

Display Not Working¶

Symptoms: - Blank screen - Garbled display - No output

Solutions: 1. Check wiring: - Verify SPI connections (MOSI, SCLK, DC, RST) - Check power supply (3.3V or 5V as required) - Ensure ground connections

Verify configuration:
Check display type matches hardware
Verify pin numbers in platformio.ini
Test with known working configuration
SPI frequency:
Lower SPI frequency (try 20MHz instead of 40MHz)
Some displays need slower speeds
Check display datasheet for max frequency
Display initialization:
Try different rotation values
Check display width/height settings
Verify TFT_eSPI driver is correct

Resolution Scaling Issues¶

Symptoms: - Image is not scaled to full screen - Visual artifacts (jittery pixels) - Frame rate drops when scaling is enabled

Solutions: 1. Verify DisplayConfig: - Ensure physicalWidth and physicalHeight match your hardware resolution (e.g., 240x240). - Check that logicalWidth and logicalHeight are set correctly (e.g., 128x128). - Use displayConfig.needsScaling() to check if the engine thinks scaling is required.

Check Scaling Performance:
Enabling scaling is generally faster than native high resolution, but still has some overhead.
Use the Debug Statistics Overlay to check CPU load.
Ensure you are using integer-only coordinates for drawing.
Visual Quality:
The engine uses nearest-neighbor scaling. Some aspect ratios might look "blocky" or have uneven pixel sizes.
For best results, use logical resolutions that are simple fractions of the physical resolution (e.g., 120x120 for a 240x240 screen).

Buttons Not Responding¶

Symptoms: - No input detected - Buttons don't trigger actions - Input feels laggy

Solutions: 1. Check wiring: - Verify button connections to GPIO pins - Check pull-up/pull-down resistors - Test buttons with multimeter

Verify pin configuration:
Check InputConfig pin numbers
Ensure pins match hardware
Verify pins aren't used elsewhere
Input debouncing:
Add hardware debouncing (capacitor)
Check InputManager is being updated
Verify input is read in update(), not draw()
Button logic:
Test with isButtonDown() vs isButtonPressed()
Check button indices match configuration
Verify input is accessed correctly

Audio Not Working¶

Symptoms: - No sound output - Distorted audio - Audio glitches

Solutions: 1. DAC Configuration: - Verify DAC pin (25 or 26 for ESP32) - Check sample rate (11025 Hz recommended) - Ensure audio backend is initialized

I2S Configuration:
Verify I2S pin connections (BCLK, LRCK, DOUT)
Check external DAC is powered
Verify I2S DAC is compatible
Audio quality:
Lower sample rate if distorted
Reduce volume levels
Check for too many simultaneous sounds
Verify audio buffer size
Hardware:
Check speaker connections
Verify amplifier is powered
Test with different audio hardware
Check audio cable connections

Power Issues¶

Symptoms: - ESP32 resets randomly - Display flickers - Unstable operation

Solutions: 1. Power supply: - Use adequate power supply (500mA+ recommended) - Check voltage is stable (3.3V) - Add decoupling capacitors

Current draw:
Display draws significant current
Audio amplifier adds load
Reduce brightness if possible
Wiring:
Use thick wires for power
Keep power wires short
Add capacitors near ESP32

Performance Problems¶

Low FPS¶

Symptoms: - Game runs slowly - Laggy movement - Stuttering

Solutions: 1. Reduce entity count: - Limit active entities (MAX_ENTITIES = 32) - Disable off-screen entities - Use object pooling

Optimize rendering:
Use viewport culling
Reduce draw calls
Use tilemaps instead of individual sprites
Limit sprite count
Simplify logic:
Cache expensive calculations
Reduce collision checks
Lower update frequency for non-critical entities
Check hardware:
Verify ESP32 is running at full speed (240MHz)
Check for thermal throttling
Ensure adequate power supply

Frame Drops¶

Symptoms: - Occasional stuttering - Inconsistent frame times - Periodic freezes

Solutions: 1. Identify bottlenecks: - Profile frame time - Check for expensive operations - Look for blocking code

Optimize update loop:
Avoid dynamic allocation
Cache calculations
Reduce string operations
Memory issues:
Check for memory leaks
Reduce memory usage
Use object pooling

Freezes/Crashes¶

Symptoms: - Game stops responding - ESP32 resets - Watchdog resets

Solutions: 1. Memory issues: - Check available heap memory - Reduce entity count - Avoid dynamic allocation - Use object pooling

Infinite loops:
Check for infinite loops in update()
Verify collision detection doesn't loop
Check animation logic
Stack overflow:
Avoid large stack allocations
Reduce recursion depth
Move large data to heap (carefully)
Watchdog:
Ensure update() completes quickly
Add yield() calls if needed
Check for blocking operations

Memory Problems¶

Out of Memory¶

Symptoms: - Compilation fails - Runtime crashes - "Allocation failed" errors

Solutions: 1. Reduce memory usage: - Use 1bpp sprites instead of 2bpp/4bpp - Store data in flash (const/constexpr) - Reduce entity count - Use object pooling

Optimize data:
Reuse sprites
Compress tilemap data
Remove unused code/data
Memory management:
Avoid dynamic allocation in game loop
Pre-allocate all resources
Use static buffers

Memory Fragmentation¶

Symptoms: - Gradual performance degradation - Allocation failures over time - Crashes after running for a while

Solutions: 1. Use object pooling: - Pre-allocate entities - Reuse objects instead of creating/destroying - Avoid frequent new/delete

Pre-allocate resources:
Allocate everything in init()
Use fixed-size arrays
Avoid dynamic containers

Native Build Problems¶

SDL2 Not Found¶

Symptoms: - Compilation fails - Linker errors - Missing SDL2 symbols

Solutions: 1. Install SDL2: - Windows (MSYS2): pacman -S mingw-w64-x86_64-SDL2 - Linux: sudo apt-get install libsdl2-dev - macOS: brew install sdl2

Check paths:
Verify include paths in platformio.ini
Check library paths
Ensure SDL2 version is compatible
Linker flags:
Verify -lSDL2 is in build flags
Check library search paths
Ensure SDL2 DLL is accessible (Windows)

Window Not Opening¶

Symptoms: - Program runs but no window - Console shows errors - Immediate exit

Solutions: 1. Check SDL2 initialization: - Verify SDL2 is properly initialized - Check for SDL2 error messages - Ensure display config is correct

Graphics drivers:
Update graphics drivers
Check SDL2 video backend
Test with simple SDL2 program
Console output:
Run from terminal to see errors
Check for error messages
Verify SDL2 is working

Debugging Techniques¶

Serial Debugging (ESP32)¶

void setup() {
    Serial.begin(115200);
    // ... initialization

    Serial.println("Engine initialized");
}

void update(unsigned long deltaTime) override {
    // Debug output
    if (frameCount % 60 == 0) {
        Serial.print("FPS: ");
        Serial.println(1000.0f / deltaTime);
    }
    frameCount++;
}

Memory Monitoring¶

#ifdef PLATFORM_ESP32
#include <Arduino.h>

void checkMemory() {
    Serial.print("Free heap: ");
    Serial.println(ESP.getFreeHeap());
    Serial.print("Largest block: ");
    Serial.println(ESP.getMaxAllocHeap());
}
#endif

Performance Profiling¶

class Profiler {
private:
    unsigned long updateTime = 0;
    unsigned long drawTime = 0;

public:
    void startUpdate() {
        updateTime = micros();
    }

    void endUpdate() {
        updateTime = micros() - updateTime;
    }

    void log() {
        Serial.print("Update: ");
        Serial.print(updateTime);
        Serial.print("us, Draw: ");
        Serial.println(drawTime);
    }
};

Visual Debugging¶

Draw hitboxes: Visualize collision boxes
Show FPS: Display frame rate on screen
Entity count: Show active entity count
Memory usage: Display memory statistics

Common Patterns for Debugging¶

Isolate the Problem¶

Minimal reproduction: Create smallest code that shows issue
Disable features: Turn off systems one by one
Test incrementally: Add features back one at a time

Check the Basics¶

Verify initialization: Ensure engine.init() is called
Check scene setup: Verify scene is set and initialized
Test on both platforms: Compare ESP32 vs Native behavior
Review recent changes: What changed before the issue?

Use Logging¶

#define DEBUG_MODE

#ifdef DEBUG_MODE
    #define DEBUG_LOG(x) Serial.println(x)
#else
    #define DEBUG_LOG(x)
#endif

// Usage
DEBUG_LOG("Entity created");
DEBUG_LOG("Collision detected");

Getting Help¶

If you can't resolve an issue:

Check documentation: Review relevant guides
Search examples: Look at example games
Review code: Check engine source code
Community: Ask on Discord or GitHub
Report issue: Create detailed bug report

Bug Report Template¶

When reporting issues, include:

Platform: ESP32 or Native
Hardware: Display type, ESP32 model
Code: Minimal reproduction code
Error messages: Full error output
Expected behavior: What should happen
Actual behavior: What actually happens
Steps to reproduce: How to trigger the issue