Skip to content

Entity

Abstract base class for all game objects.

Description

Entity is the fundamental building block of the scene. Entities have a position, size, and lifecycle methods (update, draw). All game objects inherit from Entity, including actors, UI elements, and custom game objects.

Entities are managed by Scene and are automatically updated and drawn each frame when enabled and visible.

Namespace

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

Inheritance

  • Base class: None (abstract base class)
  • Inherited by: Actor, UI elements, and your custom entity classes

Constructors

Entity(float x, float y, int w, int h, EntityType t)

Creates a new entity with specified position, size, and type.

Parameters: - x (float): Initial X position in world space - y (float): Initial Y position in world space - w (int): Width in pixels - h (int): Height in pixels - t (EntityType): The type of entity (GENERIC, ACTOR, UI_ELEMENT)

Example: 

class MyEntity : public pixelroot32::core::Entity {
public:
    MyEntity(float x, float y) 
        : Entity(x, y, 16, 16, EntityType::GENERIC) {}

    void update(unsigned long deltaTime) override {
        // Update logic
    }

    void draw(pixelroot32::graphics::Renderer& renderer) override {
        // Draw logic
    }
};

Public Properties

float x, y

Position of the entity in world space.

Type: float

Access: Read-write

Notes: - Position is in world coordinates, not screen coordinates - Can be modified directly or through helper methods - Use for entity positioning and movement

Example: 

entity->x = 100.0f;
entity->y = 50.0f;

int width, height

Dimensions of the entity in pixels.

Type: int

Access: Read-write

Notes: - Used for collision detection, rendering bounds, and layout - Should match the visual size of the entity - Can be modified at runtime if needed

Example: 

entity->width = 32;
entity->height = 32;

EntityType type

The specific type of this entity.

Type: EntityType enum

Access: Read-only (set in constructor)

Values: - EntityType::GENERIC: Generic entity - EntityType::ACTOR: Actor entity (with collision) - EntityType::UI_ELEMENT: UI element

Notes: - Used for type-safe casting and logic differentiation - Set once in constructor, typically not changed

bool isVisible

If false, the entity's draw() method will not be called.

Type: bool

Access: Read-write

Default: true

Notes: - Use to hide entities without removing them from the scene - More efficient than removing and re-adding entities - Useful for object pooling

Example: 

entity->isVisible = false;  // Hide entity
entity->setVisible(true);   // Show entity

bool isEnabled

If false, the entity's update() method will not be called.

Type: bool

Access: Read-write

Default: true

Notes: - Use to disable entity logic without removing it - Entity still exists but doesn't update - Useful for paused entities or object pooling

Example: 

entity->isEnabled = false;  // Disable updates
entity->setEnabled(true);   // Enable updates

unsigned char renderLayer

The render layer this entity is drawn on.

Type: unsigned char

Access: Read-write

Default: 1

Notes: - Layers are drawn in ascending order (0 = background, 1 = gameplay, 2 = UI) - Entities on the same layer are drawn in add order - Use to control draw order without changing entity order

Example: 

entity->renderLayer = 0;  // Background layer
entity->setRenderLayer(2); // UI layer

Public Methods

virtual void setVisible(bool v)

Sets the visibility of the entity.

Parameters: - v (bool): true to show, false to hide

Returns: - void

Notes: - Equivalent to setting isVisible directly - Can be overridden for custom visibility logic

Example: 

entity->setVisible(false);  // Hide
entity->setVisible(true);   // Show

virtual void setEnabled(bool e)

Sets the enabled state of the entity.

Parameters: - e (bool): true to enable, false to disable

Returns: - void

Notes: - Equivalent to setting isEnabled directly - Can be overridden for custom enable logic

Example: 

entity->setEnabled(false);  // Disable updates
entity->setEnabled(true);   // Enable updates

unsigned char getRenderLayer() const

Gets the current render layer.

Returns: - unsigned char: The render layer (0-255)

Example: 

unsigned char layer = entity->getRenderLayer();

virtual void setRenderLayer(unsigned char layer)

Sets the render layer for this entity.

Parameters: - layer (unsigned char): The render layer (0 = background, 1 = gameplay, 2 = UI)

Returns: - void

Example: 

entity->setRenderLayer(0);  // Background

virtual void update(unsigned long deltaTime) = 0

Updates the entity's logic. Must be implemented by derived classes.

Parameters: - deltaTime (unsigned long): Time elapsed since the last frame in milliseconds

Returns: - void

Notes: - Called automatically by Scene every frame if isEnabled is true - Use deltaTime for frame-rate independent movement - Override to implement entity-specific update logic

Example: 

void update(unsigned long deltaTime) override {
    // Move entity
    float speed = 50.0f;  // pixels per second
    x += (speed * deltaTime) / 1000.0f;

    // Wrap around screen
    if (x > 128) {
        x = 0;
    }
}

virtual void draw(Renderer& renderer) = 0

Renders the entity. Must be implemented by derived classes.

Parameters: - renderer (pixelroot32::graphics::Renderer&): Reference to the renderer to use for drawing

Returns: - void

Notes: - Called automatically by Scene every frame if isVisible is true - Entities are drawn in render layer order, then in add order - Override to implement entity-specific drawing logic

Example: 

void draw(pixelroot32::graphics::Renderer& renderer) override {
    // Draw sprite at entity position
    renderer.drawSprite(mySprite, static_cast<int>(x), static_cast<int>(y), Color::White);
}

EntityType Enum

Categorizes entities for type-safe casting and logic differentiation.

Values: - EntityType::GENERIC: Generic entity (default) - EntityType::ACTOR: Actor entity (with collision support) - EntityType::UI_ELEMENT: UI element

Example: 

if (entity->type == EntityType::ACTOR) {
    Actor* actor = static_cast<Actor*>(entity);
    // Use actor-specific methods
}

Rect Structure

Represents a 2D rectangle, typically used for hitboxes or bounds.

Members: - float x, y: Top-left corner coordinates - int width, height: Dimensions of the rectangle

Methods: - bool intersects(const Rect& other): Checks if this rectangle intersects with another

Example: 

pixelroot32::core::Rect rect1{10.0f, 20.0f, 50, 50};
pixelroot32::core::Rect rect2{30.0f, 40.0f, 50, 50};

if (rect1.intersects(rect2)) {
    // Rectangles overlap
}

Usage Example

#include "core/Entity.h"

class Collectible : public pixelroot32::core::Entity {
private:
    const pixelroot32::graphics::Sprite* sprite;

public:
    Collectible(float x, float y) 
        : Entity(x, y, 8, 8, EntityType::GENERIC),
          sprite(&collectibleSprite) {}

    void update(unsigned long deltaTime) override {
        // Rotate or animate
        rotation += deltaTime * 0.001f;
    }

    void draw(pixelroot32::graphics::Renderer& renderer) override {
        if (isVisible) {
            renderer.drawSprite(*sprite, 
                               static_cast<int>(x), 
                               static_cast<int>(y), 
                               Color::Yellow);
        }
    }

private:
    float rotation = 0.0f;
};

Performance Considerations

  • Visibility: Use isVisible = false instead of removing entities when hiding
  • Enable state: Use isEnabled = false to pause entity logic
  • Render layers: Organize entities by layer to minimize layer switches
  • Direct access: Direct property access is fast (no function call overhead)

ESP32 Considerations

  • Memory: Each entity consumes memory; stay within MAX_ENTITIES limit
  • Object pooling: Reuse entities instead of creating/destroying frequently
  • Update frequency: Disable entities that don't need to update every frame

See Also