Skip to content

Engine

The main engine class that manages the game loop and core subsystems.

Description

Engine acts as the central hub of the PixelRoot32 game engine. It initializes and manages the Renderer, InputManager, AudioEngine, and SceneManager. It runs the main game loop, handling timing (delta time), updating the current scene, and rendering frames.

The engine provides a unified interface for both ESP32 and Native (SDL2) platforms, abstracting platform-specific details while maintaining consistent behavior.

Namespace

namespace pixelroot32::core {
    class Engine {
        // ...
    };
}

Inheritance

  • Base class: None (standalone class)
  • Used by: Application entry point (main.cpp)

Constructors

Engine(const DisplayConfig& displayConfig, const InputConfig& inputConfig, const AudioConfig& audioConfig)

Creates a new engine instance with custom display, input, and audio configurations.

Parameters: - displayConfig (const pixelroot32::graphics::DisplayConfig&): Configuration settings for the display (width, height, rotation, etc.) - inputConfig (const pixelroot32::input::InputConfig&): Configuration settings for the input system (pins, buttons) - audioConfig (const pixelroot32::audio::AudioConfig&): Configuration settings for the audio system (backend, sample rate, buffer size)

Example: 

#include "core/Engine.h"
#include "graphics/DisplayConfig.h"
#include "input/InputConfig.h"
#include "audio/AudioConfig.h"

pixelroot32::graphics::DisplayConfig displayConfig;
displayConfig.width = 128;
displayConfig.height = 128;

pixelroot32::input::InputConfig inputConfig;
// Configure input pins...

pixelroot32::audio::AudioConfig audioConfig;
audioConfig.backend = pixelroot32::audio::AudioConfig::Backend::ESP32_DAC;
audioConfig.sampleRate = 11025;

pixelroot32::core::Engine engine(displayConfig, inputConfig, audioConfig);
engine.init();
engine.run();

Engine(const DisplayConfig& displayConfig, const InputConfig& inputConfig)

Creates a new engine instance with custom display and input configurations, using default audio settings.

Parameters: - displayConfig (const pixelroot32::graphics::DisplayConfig&): Configuration settings for the display - inputConfig (const pixelroot32::input::InputConfig&): Configuration settings for the input system

Example: 

pixelroot32::core::Engine engine(displayConfig, inputConfig);
engine.init();
engine.run();

Engine(const DisplayConfig& displayConfig)

Creates a new engine instance with custom display configuration and default input/audio settings.

Parameters: - displayConfig (const pixelroot32::graphics::DisplayConfig&): Configuration settings for the display

Example: 

pixelroot32::core::Engine engine(displayConfig);
engine.init();
engine.run();

Public Methods

void init()

Initializes the engine subsystems. This method must be called before run().

Returns: - void

Notes: - Initializes the Renderer, InputManager, and sets up the initial state - Must be called after construction and before run() - Safe to call multiple times (idempotent)

Example: 

Engine engine(displayConfig);
engine.init();  // Initialize subsystems
engine.setScene(myScene);
engine.run();   // Start game loop

void run()

Starts the main game loop. This method contains the infinite loop that calls update() and draw() repeatedly until the application exits.

Returns: - void

Notes: - This method blocks until the application exits - Handles frame timing and delta time calculation automatically - Calls update() and draw() once per frame - Do not call this method multiple times

Example: 

Engine engine(displayConfig);
engine.init();
engine.setScene(myScene);
engine.run();  // Blocks here, runs game loop

unsigned long getDeltaTime() const

Gets the time elapsed since the last frame.

Returns: - unsigned long: The delta time in milliseconds

Performance Notes: - Very fast (inline accessor) - Safe to call every frame - Use this value to make movement frame-rate independent

Example: 

void update(unsigned long deltaTime) override {
    auto& engine = getEngine();
    unsigned long dt = engine.getDeltaTime();

    // Move at constant speed regardless of FPS
    float speed = 100.0f;  // pixels per second
    x += (speed * dt) / 1000.0f;
}

void setScene(Scene* newScene)

Sets the current active scene to be updated and rendered.

Parameters: - newScene (Scene*): Pointer to the new Scene to become active. Can be nullptr to clear the current scene.

Notes: - The previous scene is replaced (not pushed onto a stack) - Use SceneManager for push/pop operations if needed - The scene's init() method will be called automatically - Safe to call during the game loop

Example: 

class MainMenuScene : public pixelroot32::core::Scene {
    // ...
};

class GameScene : public pixelroot32::core::Scene {
    // ...
};

MainMenuScene menuScene;
GameScene gameScene;

Engine engine(displayConfig);
engine.init();
engine.setScene(&menuScene);  // Start with menu
engine.run();

Scene* getCurrentScene() const

Retrieves the currently active scene.

Returns: - Scene*: Pointer to the current Scene, or nullptr if none is set

Example: 

auto* currentScene = engine.getCurrentScene();
if (currentScene) {
    // Scene is active
}

void setRenderer(Renderer& newRenderer)

Replaces the current renderer instance.

Parameters: - newRenderer (pixelroot32::graphics::Renderer&): Reference to the new Renderer to use

Notes: - Advanced usage: typically not needed unless implementing custom renderer - The renderer must be properly initialized before use - Use with caution: may break existing rendering code

Renderer& getRenderer()

Provides access to the Renderer subsystem.

Returns: - pixelroot32::graphics::Renderer&: Reference to the current Renderer

Example: 

void draw(pixelroot32::graphics::Renderer& renderer) override {
    auto& engineRenderer = engine.getRenderer();
    engineRenderer.drawSprite(mySprite, 100, 100, Color::White);
}

InputManager& getInputManager()

Provides access to the InputManager subsystem.

Returns: - pixelroot32::input::InputManager&: Reference to the InputManager

Example: 

void update(unsigned long deltaTime) override {
    auto& input = engine.getInputManager();
    if (input.isButtonPressed(Buttons::A)) {
        // Handle button press
    }
}

AudioEngine& getAudioEngine()

Provides access to the AudioEngine subsystem.

Returns: - pixelroot32::audio::AudioEngine&: Reference to the AudioEngine

Example: 

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

MusicPlayer& getMusicPlayer()

Provides access to the MusicPlayer subsystem.

Returns: - pixelroot32::audio::MusicPlayer&: Reference to the MusicPlayer

Example: 

void playMusic() {
    auto& music = engine.getMusicPlayer();
    music.playTrack(myMusicTrack);
}

Usage Example

#include "core/Engine.h"
#include "graphics/DisplayConfig.h"
#include "MyScene.h"

void setup() {
    // Configure display
    pixelroot32::graphics::DisplayConfig displayConfig;
    displayConfig.width = 128;
    displayConfig.height = 128;
    displayConfig.rotation = 0;

    // Create engine
    pixelroot32::core::Engine engine(displayConfig);

    // Initialize
    engine.init();

    // Create and set scene
    MyScene myScene;
    engine.setScene(&myScene);

    // Run game loop
    engine.run();
}

Performance Considerations

  • Initialization: init() should be called once at startup, not in the game loop
  • Scene switching: Switching scenes is fast but avoid doing it every frame
  • Subsystem access: Getters are inline and very fast; safe to call every frame
  • Delta time: Use getDeltaTime() for frame-rate independent movement

ESP32 Considerations

  • Ensure init() completes before run() to avoid initialization issues
  • Monitor memory usage when switching scenes frequently
  • Use getDeltaTime() for consistent gameplay across different frame rates

See Also