Entities & scene tutorial

Not an examples/ project — This page is a didactic walkthrough (bouncing entities, Entity subclass, scene wiring). There is no matching folder under examples/ with this code. For a real, minimal PlatformIO project, start with hello_world and its README.

The snippets below illustrate fundamentals: scene lifecycle, custom Entity subclasses, input, and drawing — useful once you have already opened hello_world in the repo.

Complete Source

cpp

#include <Arduino.h>
#include <Engine.h>
#include <Scene.h>
#include <Renderer.h>
#include <Entity.h>
#include <InputManager.h>

using namespace pixelroot32;

// ============================================================================
// Custom Entity: A bouncing ball
// ============================================================================
class Ball : public core::Entity {
    math::Scalar velocityX;
    math::Scalar velocityY;
    graphics::Color color;
    int screenWidth;
    int screenHeight;
    
public:
    Ball(int x, int y, int screenW, int screenH) 
        : Entity(math::toScalar(x), math::toScalar(y), 8, 8, core::EntityType::GENERIC),
          screenWidth(screenW),
          screenHeight(screenH),
          color(graphics::Color::RED) {
        
        // Random velocity using math::Scalar
        velocityX = math::toScalar(random(50, 150));
        velocityY = math::toScalar(random(50, 150));
        
        if (random(2) == 0) velocityX = -velocityX;
        if (random(2) == 0) velocityY = -velocityY;
    }
    
    void update(unsigned long deltaTime) override {
        using namespace math;
        
        // Convert deltaTime to seconds as Scalar
        Scalar dt = toScalar(deltaTime) / toScalar(1000);
        
        // Update position
        position.x += velocityX * dt;
        position.y += velocityY * dt;
        
        // Bounce off walls
        if (position.x <= toScalar(0) || 
            position.x >= toScalar(screenWidth - width)) {
            velocityX = -velocityX;
            color = static_cast<graphics::Color>(random(1, 16));
        }
        
        if (position.y <= toScalar(0) || 
            position.y >= toScalar(screenHeight - height)) {
            velocityY = -velocityY;
            color = static_cast<graphics::Color>(random(1, 16));
        }
        
        // Clamp to screen
        if (position.x < toScalar(0)) position.x = toScalar(0);
        if (position.y < toScalar(0)) position.y = toScalar(0);
        if (position.x > toScalar(screenWidth - width)) 
            position.x = toScalar(screenWidth - width);
        if (position.y > toScalar(screenHeight - height)) 
            position.y = toScalar(screenHeight - height);
    }
    
    void draw(graphics::Renderer& r) override {
        r.drawFilledRectangle(
            static_cast<int>(position.x),
            static_cast<int>(position.y),
            width,
            height,
            color
        );
    }
};

// ============================================================================
// Game Scene
// ============================================================================
class BouncingBallsScene : public core::Scene {
    static constexpr int NUM_BALLS = 10;
    std::unique_ptr<Ball> balls[NUM_BALLS];
    unsigned long spawnTimer = 0;
    int ballsActive = 0;
    int screenWidth;
    int screenHeight;
    
public:
    void init() override {
        // Nothing to do - balls spawned in first update
        screenWidth = engine->getRenderer().getLogicalWidth();
        screenHeight = engine->getRenderer().getLogicalHeight();
    }
    
    void update(unsigned long deltaTime) override {
        auto& input = engine->getInputManager();
        
        // Spawn balls gradually
        spawnTimer += deltaTime;
        if (spawnTimer > 500 && ballsActive < NUM_BALLS) {  // Every 500ms
            spawnTimer = 0;
            
            balls[ballsActive] = std::make_unique<Ball>(
                screenWidth / 2,
                screenHeight / 2,
                screenWidth,
                screenHeight
            );
            addEntity(balls[ballsActive].get());
            ballsActive++;
        }
        
        // Reset with button A
        if (input.isButtonJustPressed(input::ButtonName::A)) {
            resetBalls();
        }
        
        // Update all entities (calls Ball::update)
        Scene::update(deltaTime);
    }
    
    void draw(graphics::Renderer& r) override {
        // Clear handled by beginFrame, draw background
        r.drawFilledRectangle(0, 0, screenWidth, screenHeight, graphics::Color::BLACK);
        
        // Draw all entities (balls)
        Scene::draw(r);
        
        // Draw UI
        r.drawText("Balls: " + std::to_string(ballsActive), 5, 5, graphics::Color::WHITE, 1);
        r.drawText("Press A to reset", 5, 15, graphics::Color::GRAY, 1);
    }
    
private:
    void resetBalls() {
        // Remove existing balls
        for (int i = 0; i < ballsActive; ++i) {
            removeEntity(balls[i].get());
            balls[i].reset();
        }
        ballsActive = 0;
        spawnTimer = 0;
    }
};

// ============================================================================
// Main Setup
// ============================================================================
void setup() {
    // Seed random
    randomSeed(analogRead(0));
    
    // Display configuration
    graphics::DisplayConfig displayConfig(240, 240);
    
    // Input configuration
    input::InputConfig inputConfig;
    inputConfig.addButton(input::ButtonName::A, 0);  // BOOT button
    
    // Create engine
    core::Engine engine(std::move(displayConfig), inputConfig);
    
    // Create and set scene
    BouncingBallsScene scene;
    engine.setScene(&scene);
    
    // Initialize and run
    engine.init();
    engine.run();
}

void loop() {
    // Empty - engine.run() contains the game loop
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175

Key Concepts Demonstrated

1. Entity Creation

cpp

class Ball : public core::Entity {
public:
    Ball(int x, int y, int w, int h) 
        : Entity(x, y, w, h, EntityType::GENERIC) {
        // Initialize
    }
    
    void update(unsigned long deltaTime) override;
    void draw(graphics::Renderer& r) override;
};

Extend Entity for game objects
Implement update() for logic
Implement draw() for rendering

2. Frame-Rate Independent Movement

cpp

void update(unsigned long deltaTime) override {
    // Convert to seconds
    math::Scalar dt = math::toScalar(deltaTime) / math::toScalar(1000);
    
    // Move at constant speed regardless of FPS
    position.x += velocityX * dt;
}

Always use deltaTime for time-based calculations.

3. Entity Management

cpp

// Create
balls[i] = std::make_unique<Ball>(...);
addEntity(balls[i].get());  // Scene manages the pointer

// Remove
removeEntity(balls[i].get());  // Remove from scene
balls[i].reset();               // Free memory

Use smart pointers for automatic memory management.

4. Input Handling

cpp

auto& input = engine->getInputManager();

// Button pressed this frame (edge trigger)
if (input.isButtonJustPressed(ButtonName::A)) {
    // Trigger action once
}

// Button held (continuous)
if (input.isButtonPressed(ButtonName::LEFT)) {
    // Continuous action
}

5. Scene Structure

cpp

class MyScene : public core::Scene {
public:
    void init() override;                          // Setup
    void update(unsigned long deltaTime) override; // Logic
    void draw(graphics::Renderer& r) override;      // Rendering
};

Build Configuration

ini

; platformio.ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino

; C++17 required
build_unflags = -std=gnu++11
build_flags =
    -std=gnu++17
    -fno-exceptions

; Library dependencies
lib_deps = 
    https://github.com/PixelRoot32-Game-Engine/PixelRoot32-Game-Engine.git

Running the Example

Create project:
bash
```
mkdir bouncing_balls
cd bouncing_balls
```
1
2
Copy code to src/main.cpp
Create platformio.ini with configuration above
Build and upload:
- Open in VS Code with PlatformIO
- Select environment (ESP32 or Native)
- Build and upload

Expected Behavior

Balls spawn one at a time every 500ms
Balls bounce off screen edges
Ball color changes on each bounce
Press button A to reset
Counter shows active ball count

Variations

Add Physics

cpp

// Change to physics-enabled actor
class Ball : public physics::KinematicActor {
public:
    Ball(...) : KinematicActor(x, y, w, h) {
        setCollisionLayer(DefaultLayers::kEnvironment);
    }
    
    void onCollision(Actor* other) override {
        // Bounce with physics response
        velocityX = -velocityX;
    }
};

Add Audio

cpp

#if PIXELROOT32_ENABLE_AUDIO
void onCollision(Actor* other) override {
    engine->getAudioEngine().playSFX(sound_bounce);
}
#endif

Touch Control

cpp

#if PIXELROOT32_ENABLE_TOUCH
void onUnconsumedTouchEvent(const input::TouchEvent& event) override {
    if (event.type == input::TouchEventType::CLICK) {
        spawnBallAt(event.x, event.y);
    }
}
#endif

Next Steps

Samples index — Real folders under examples/
Physics (physics) — Collision and actors
Sprites (sprites) — Sprite graphics
Audio — See snake, tic_tac_toe, music_demo

Entities & scene tutorial ​

Complete Source ​

Key Concepts Demonstrated ​

1. Entity Creation ​

2. Frame-Rate Independent Movement ​

3. Entity Management ​

4. Input Handling ​

5. Scene Structure ​

Build Configuration ​

Running the Example ​

Expected Behavior ​

Variations ​

Add Physics ​

Add Audio ​

Touch Control ​

Next Steps ​