Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/raoulkdev/MiniECS/llms.txt

Use this file to discover all available pages before exploring further.

This page collects common usage patterns drawn from the MiniECS source and the bundled main.cpp example. Each snippet is self-contained and maps directly to the public API exposed by World, Unit, and the built-in modules. Read through them in order for a progressive introduction, or jump to the pattern most relevant to your use case.
World::play() runs an infinite game loop and never returns. It iterates through the units vector and, for the first unit that has modules, enters an unbounded while(true) loop calling callModuleStart() — it never advances to subsequent units. Configure all units and modules before calling it. Any setup code placed after scene.play() will never execute.

​
Example 1

​
Basic scene with Transform and Renderer

The simplest possible MiniECS program creates a World, adds one Unit, attaches a couple of modules, sets an initial value, and starts the loop. This is the exact code from src/main.cpp. 
// Imports
#include <memory>
#include "modules/transform/TransformModule.h"
#include "unit/Unit.h"
#include "world/World.h"

// Example use
int main()
{
    // Create World
    MiniECS::World scene("Scene");

    // Create new unit inside the world
    scene.createUnit("u1");

    // Add a renderer module to the new unit
    scene.getUnitByName("u1")->addModule(MiniECS::ModuleType::Renderer);

    // Add a transform module to the new unit
    scene.getUnitByName("u1")->addModule(MiniECS::ModuleType::Transform);

    // Set transform position
    scene.getUnitByName("u1")->getModule<MiniECS::TransformModule>()->position = {22.5f, 33.4f};

    // Play the scene
    scene.play();
}

​
Example 2

​
Multiple units in a scene

World holds an arbitrary number of units. Create each one with createUnit(), attach whichever modules it needs, then configure their initial state through getModule<T>(). Units that don’t share the same module set coexist without issue — only the modules actually attached to a unit are called during play(). 
MiniECS::World scene("GameScene");

scene.createUnit("player");
scene.getUnitByName("player")->addModule(MiniECS::ModuleType::Transform);
scene.getUnitByName("player")->addModule(MiniECS::ModuleType::Renderer);

scene.createUnit("enemy");
scene.getUnitByName("enemy")->addModule(MiniECS::ModuleType::Transform);

// Set player position
auto* playerTransform = scene.getUnitByName("player")->getModule<MiniECS::TransformModule>();
if (playerTransform) {
    playerTransform->position = {0.0f, 0.0f};
}

// Set enemy position
auto* enemyTransform = scene.getUnitByName("enemy")->getModule<MiniECS::TransformModule>();
if (enemyTransform) {
    enemyTransform->position = {10.0f, 5.0f};
}

​
Example 3

​
Always check getModule<T>() for nullptr

Unit::getModule<T>() performs a dynamic_cast over the unit’s module list and returns the first match, or nullptr if no module of type T is attached. It also prints a message to std::cerr when the module is not found. Always guard the returned pointer before dereferencing it — omitting the check will produce undefined behaviour if the module was never added. 
auto* transform = unit->getModule<MiniECS::TransformModule>();
if (transform) {
    transform->position = {1.0f, 2.0f};
} else {
    // Module not found — handle gracefully
}
Calling addModule() with a ModuleType that already exists on the unit is safe — the framework detects the duplicate and prints a warning without adding a second copy. getModule<T>() will still return the original instance.

​
Example 4

​
Iterating over all units in a World

World::getUnitsVector() returns a const reference to the internal std::vector<std::unique_ptr<Unit>>. Use a range-based for loop to inspect or operate on every unit without modifying the container. 
const auto& units = scene.getUnitsVector();
for (const auto& unit : units) {
    std::cout << "Unit: " << unit->getName() << "\n";
}

​
Example 5

​
Removing units by name or index

Units can be removed from a World either by their string name or by their zero-based position in the units vector. Both operations destroy the unique_ptr and invoke the destructors of all modules still attached to that unit. 
scene.removeUnitByName("enemy");   // remove by name
scene.removeUnitByIndex(0);        // remove first unit
After calling removeUnitByIndex(i), all subsequent indices shift down by one. Removing multiple units by index in a loop requires careful index management — prefer removeUnitByName() when the target unit’s name is known.

Build docs developers (and LLMs) love

Get started for freeTalk to us