Fundamental Concepts¶

Before you start programming, it's important to understand the basic concepts that form PixelRoot32's architecture. This section explains how the engine works at a conceptual level, without going into code details.

Engine Architecture¶

Engine: The Heart of the Engine¶

The Engine is the main class that orchestrates the entire system. Think of it as the conductor that coordinates all subsystems:

Renderer: Handles drawing everything on screen
InputManager: Reads and processes user input (buttons, keyboard)
AudioEngine: Generates and plays sounds and music
SceneManager: Manages game scenes (menus, levels, etc.)

The Engine runs the main game loop: an infinite cycle that updates game logic and draws each frame on screen. It also calculates delta time (time elapsed between frames) so the game runs at the same speed regardless of framerate.

Scene: Organizing Your Game¶

A Scene represents a screen or level in your game. For example: - A scene for the main menu - A scene for each game level - A scene for the game over screen - A scene for the pause menu

Each scene contains and manages a set of entities (characters, enemies, objects, etc.). The scene is responsible for: - Initializing its entities when loaded - Updating the logic of all its entities each frame - Drawing all its visible entities each frame - Managing collisions between entities that can collide

The Engine can only have one active scene at a time, but you can easily switch between scenes (for example, go from menu to game, or from game to pause menu).

Entity: The Fundamental Building Blocks¶

An Entity is any object in your game that has: - Position (x, y) in the world - Size (width and height) - Visibility (can be visible or not) - Active state (can be enabled or disabled) - Render layer (in what order it's drawn)

Entities are the foundation of everything in your game: the player, enemies, projectiles, objects, UI elements—everything is an entity or inherits from Entity.

Each entity has two main methods: - update(): Called each frame to update the entity's logic (movement, animation, etc.) - draw(): Called each frame to draw the entity on screen

Actor: Entities That Can Collide¶

An Actor is a special entity that can participate in the collision system. In addition to everything an Entity has, an Actor has: - Collision layer: Which group it belongs to (e.g., "player", "enemy", "projectile") - Collision mask: Which other groups it can collide with - Hitbox: The shape used to detect collisions (usually a rectangle)

For example, a player might be on the "player" layer and have a mask that allows it to collide with "enemies" and "obstacles", but not with "other players".

When two actors collide, the system calls their onCollision() method so they can react (e.g., player loses health, enemy is destroyed, etc.).

PhysicsActor: Entities with Physics¶

A PhysicsActor is an Actor that also has physical properties: - Velocity (vx, vy): Moves automatically according to its velocity - Gravity: Can fall automatically - Friction: Gradually loses velocity - Restitution: Bounces when it collides (like a ball)

The PhysicsActor updates automatically each frame, applying physics and moving the entity. It can also detect collisions with world boundaries (the walls of the play area).

Entity Hierarchy¶

The relationship between these classes is hierarchical:

Entity (base)
  └── Actor (can collide)
       └── PhysicsActor (has physics)

This means: - Every Actor is also an Entity - Every PhysicsActor is also an Actor and an Entity - You can use Entity for simple objects that don't need collisions - You can use Actor for objects that need to detect collisions - You can use PhysicsActor for objects that need automatic physics

Rendering System¶

Render Layers¶

To control the order in which things are drawn, PixelRoot32 uses render layers:

Layer 0 (Background): Backgrounds, tilemaps, background elements
Layer 1 (Gameplay): Characters, enemies, projectiles, game objects
Layer 2 (UI): Menus, HUD, text, interface elements

Layers are drawn in order: first 0, then 1, and finally 2. This ensures the background is always behind, gameplay in the middle, and UI always visible in front.

Each entity has a renderLayer property that indicates which layer it should be drawn on. You can change this property to move entities between layers.

Rendering Pipeline¶

The rendering process works like this:

beginFrame(): The screen is cleared (painted black or background color)
Draw entities: All visible entities are traversed, organized by layer
endFrame(): The complete frame is sent to the display

The Renderer abstracts hardware details, so the same code works on both ESP32 (TFT_eSPI) and PC (SDL2).

Coordinates and Space¶

PixelRoot32 uses a standard coordinate system: - Origin (0, 0): Top-left corner - X-axis: Increases to the right - Y-axis: Increases downward

Coordinates are in pixels. If your display is 240x240, coordinates range from (0, 0) to (239, 239).

Lifecycle¶

Initialization¶

When your game starts:

Configuration: Configuration objects are created (DisplayConfig, InputConfig, AudioConfig)
Engine: The Engine is created with these configurations
init(): engine.init() is called to initialize all subsystems
Scene: The initial scene is created and configured
setScene(): The scene is assigned to the Engine

Game Loop¶

Once initialized, the Engine enters the game loop:

While the game is running:
  1. Calculate deltaTime (time since last frame)
  2. Update InputManager (read buttons/keyboard)
  3. Update AudioEngine (advance sounds and music)
  4. Update current scene (update all entities)
  5. Detect collisions in the scene
  6. Draw the scene (draw all visible entities)
  7. Repeat

This cycle runs continuously, typically at 30-60 FPS on ESP32, or faster on PC.

Update¶

Each frame, all enabled entities receive a call to their update(deltaTime) method. This is where: - Entities move - Animations update - Game logic is processed - User input is read - Sound effects are played

The deltaTime is passed in milliseconds and represents how much time has passed since the last frame. This allows movement to be framerate-independent.

Rendering (Draw)¶

After updating, all visible entities receive a call to their draw(renderer) method. This is where: - Sprites are drawn - Text is drawn - Primitives are drawn (rectangles, circles, etc.)

The renderer is passed as a parameter so entities can draw themselves.

Cleanup¶

When you change scenes or end the game: - Entities from the previous scene can be cleaned up - Resources are freed - The new scene is initialized

Conceptual Summary¶

To summarize, PixelRoot32 works like this:

Engine coordinates everything and runs the game loop
Scene organizes your game into screens/levels
Entity is any object in your game
Actor is an entity that can collide
PhysicsActor is an actor with automatic physics
Renderer draws everything on screen using layers
Each frame updates logic and then draws

All of this works automatically once you configure the Engine and create your scenes and entities. You don't need to worry about game loop details; you just need to implement update() and draw() in your entities.

Next Step¶

Now that you understand the fundamental concepts, you're ready to create your first project and see these concepts in action with real code.