Engine Overview

Detailed documentation about the engine architecture.

This page provides an in-depth look at the engine architecture powering the R-Type project. It is divided into several key parts:

1. Entity Component System (ECS): A modern design pattern for performance-critical applications.
2. Event Queue System: A custom event queue implementation for handling game events efficiently.
3. Dynamic Libraries and Configuration Files: Extending functionality with .so files and configuration files.
4. In-Game Console: A powerful tool for debugging and monitoring the game.

---

Entity Component System (ECS) Documentation

1. Introduction

What is an ECS?

An Entity Component System (ECS) is a design pattern widely used in game development and other performance-critical applications. ECS promotes a composition-over-inheritance approach by decoupling data (components) and behavior (systems).

The three core concepts of ECS are:

• Entity: A unique identifier that represents an object.
• Component: A piece of data that describes the properties or state of an entity.
• System: Logic or operations that act on entities with specific components.

ECS stands out from traditional object-oriented inheritance due to its flexibility, cache-friendly design, and improved performance.

2. ECS Architecture

Entities

Entities are unique IDs (often integers) that have no behavior or data on their own. They simply act as identifiers.

EntityID player = ecs.spawn_entity();

Components

Components are plain data structures (e.g., structs in C++). Each component represents a specific attribute of an entity.

struct Position {
    float x, y;
};

struct Velocity {
    float dx, dy;
};

Systems

Systems are responsible for processing entities that have specific components. Systems are where the behavior/logic resides.

void move(Engine &engine, ecs::sparse_arraycomp::position &positions,
          ecs::sparse_arraycomp::vector &vectors) {
    for (auto &&[pos, vec] : ecs::zipper(positions, vectors)) {
        pos.x += vec.x;
        pos.y += vec.y;
    }
}

3. ECS vs Traditional Inheritance

Feature	ECS	Traditional Inheritance
Design Principle	Composition over inheritance	Inheritance-based hierarchy
Performance	Cache-friendly, better memory use	Slower due to pointer indirection
Flexibility	Easily add/remove components	Requires class hierarchy updates
Scalability	Highly scalable	Becomes complex with deep hierarchies
Data Storage	Separate components (SoA)	Mixed data and logic

Explanation:

• ECS avoids the rigid structure of deep inheritance trees by allowing entities to “compose” their behavior through components.
• Systems process only the components they care about, improving cache efficiency and performance.

4. Benchmark: ECS vs Inheritance

Setup

• ECS Approach: Entities with Position and Velocity components.
• Inheritance Approach: Classes with virtual methods and inheritance.
• Operations: Update 1,000,000 entities’ positions over 1,000 iterations.

Results

Approach	Time Taken (ms)	Memory Usage (MB)
ECS	120 ms	50 MB
Inheritance	230 ms	75 MB

Analysis

• ECS outperformed inheritance in both speed and memory usage.
• ECS leverages contiguous memory storage and avoids the overhead of virtual function calls.

5. Advantages of ECS

Performance:

• Cache-friendly design improves CPU performance.
• Separation of components allows parallel processing.

Flexibility:

• Add or remove components without modifying existing code.
• Entities can be dynamically updated at runtime.

Scalability:

• ECS scales well with large numbers of entities and systems.
• Simple to extend with new components or systems.

Maintainability:

• Decouples data and logic, making the code easier to understand and maintain.

---

Event Queue System

Key Features

1. Event Queue: A FIFO (First-In, First-Out) structure to process events sequentially.
2. Event Dispatching: Events are pushed into the queue and consumed by systems that subscribe to them.
3. Decoupling: Allows for clean separation between systems and event handling logic.

Sending an Event

To send an event, the engine uses the sendEvent method. Here is an example of sending a collision event:

engine.sendEvent<evt::collision>(i, j);

• evt::collision: Type of the event being sent.
• i, j: Parameters for the event (e.g., entity IDs involved in the collision).

Handling an Event

Events are processed using the resolveEvent function. Systems that listen for events handle them accordingly.

void resolveEvent(Engine& engine, ecs::sparse_array<comp::event_listener>& evtls) {
    while (!engine._events.empty()) {
        Event evt = engine._events.front();
        if (engine.reg.get_components<comp::event_listener>().size() > evt.entity &&
            engine.reg.get_entity_component<comp::event_listener>(evt.entity)) {
            // Check if the entity can handle the event
            if (engine.reg.get_entity_component<comp::event_listener>(evt.entity)
                ->_functions.find(evt.tid) != engine.reg.get_entity_component<comp::event_listener>(evt.entity)->_functions.end()) {

                engine.reg.get_entity_component<comp::event_listener>(evt.entity)
                    ->_functions[evt.tid](engine, evt.entity, evt);
            }
        }
        engine._events.pop();
    }
}

Benefits

• Decoupling: Clean separation between event producers and consumers.
• Scalability: Efficiently handles a large number of events.
• Maintainability: Simplifies debugging and testing of individual systems.

---

Dynamic Libraries and Configuration Files

Dynamic Libraries (.so Files)

The engine supports dynamic libraries (.so files) to enable modularity and extend the engine’s functionality. Developers can:

• Load custom systems or components at runtime.
• Extend engine features without modifying the core code.

Example

void loadLibrary(const std::string& path) {
    void* lib = dlopen(path.c_str(), RTLD_LAZY);
    if (!lib) {
        std::cerr << "Error loading library: " << dlerror() << std::endl;
        return;
    }
    // Use the library...
    dlclose(lib);
}

Configuration Files

The engine reads configuration files for:

• Game settings: Resolution, controls, audio preferences.
• Entity definitions: Starting positions, attributes, etc.
• Network settings: Ports, IP addresses, etc.

Example Configuration File

{
    "resolution": "1920x1080",
    "fullscreen": true,
    "audio": {
        "volume": 75,
        "mute": false
    },
    "network": {
        "tcp_port": 12345,
        "udp_port": 54321
    }
}

---

In-Game Console

Overview

The in-game console provides developers and testers with a powerful interface to:

• Debug the game.
• Monitor performance metrics.
• Manipulate in-game entities and settings in real time.

Console Features

Commands

• help: Displays a list of available commands.
• debug [on | off]: Enables or disables debug logs.
• playSound [name]: Plays a sound by its name.
• metrics [on | off]: Toggles the display of performance metrics.
• hitbox [on | off]: Toggles the display of entity hitboxes.
• entities: Lists all active entities.
• kill [entity]: Removes an entity by its ID.

Example

> help
help               -> Display all commands.
debug [on | off]   -> Turn on or off debug log.
playSound [name]   -> Play a sound by name.
metrics [on | off] -> Toggle metrics displaying.
hitbox  [on | off] -> Toggle hitboxes displaying.
entities           -> Display all entities.
kill [entity]      -> Kill an entity.

Implementation

The console is implemented as a thread-safe class that interacts with the engine:

void Console::run(std::mutex &mutex, Engine &engine) {
    std::string input("");
    while (1) {
        {
            std::unique_lock<std::mutex> lock(mutex);
            std::cout << "> ";
            std::getline(std::cin, input);
            if (input == "help")
                help();
            else if (engine.GraphLib && input.rfind("playSound ", 0) == 0)
                playSound(engine, input.substr(10));
            // Additional commands here...
        }
    }
}

Benefits

• Real-time debugging and monitoring.
• Simplifies testing during development.
• Provides a robust interface for manipulating the game state.

---