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.

MiniECS::World is the top-level scene container. It owns all Units and drives the simulation loop. Every scene begins with a World instance — you create and configure Units through it, then hand control over to the game loop by calling play().

​
Namespace & Header

namespace MiniECS { class World; }
#include "world/World.h"

​
Constructor

explicit World(std::string initName);
Creates a new World and stores the given name internally as worldName. No Units are created at construction time; use createUnit() to populate the scene.
​
initName
string
required
The display name for this World instance. Stored internally and used for identification purposes.
Example 
MiniECS::World myWorld("MainScene");

​
createUnit

void createUnit(std::string newUnitName);
Creates a new Unit with the given name, wraps it in a std::unique_ptr, and appends it to the internal worldUnits vector. If newUnitName is an empty string, the method prints "New unit name invalid!" to stdout and returns without creating anything.
​
newUnitName
string
required
The name to assign to the new Unit. Must be non-empty — passing an empty string is a no-op and produces a console warning.
Example 
myWorld.createUnit("Player");
myWorld.createUnit("Enemy");
Unit names are used as identifiers by removeUnitByName() and getUnitByName(). Choose unique names to avoid ambiguous lookups.

​
removeUnitByName

void removeUnitByName(std::string unitName);
Searches the worldUnits vector for a Unit whose name matches unitName. If a match is found, that Unit is erased from the vector and its destructor is called (the unique_ptr is released). If no match is found, the method prints "Could not find: <unitName>" to stdout and leaves the vector unchanged.
​
unitName
string
required
The name of the Unit to locate and remove. The comparison is an exact string match.
Example 
myWorld.removeUnitByName("Enemy");

​
removeUnitByIndex

void removeUnitByIndex(int index);
Removes the Unit at the given zero-based position in the internal worldUnits vector. Internally uses vector::at() to access the element, which means an out-of-range index will throw a standard library exception rather than silently invoking undefined behaviour.
​
index
int
required
Zero-based index into the units vector. Valid range is [0, getUnitsVector().size() - 1].
Passing an index outside the valid range causes std::vector::at() to throw std::out_of_range. Always validate the index against getUnitsVector().size() before calling this method.
Example 
// Remove the first unit in the scene
myWorld.removeUnitByIndex(0);

​
getUnitByName

std::unique_ptr<Unit>& getUnitByName(std::string name);
Iterates worldUnits and returns a mutable reference to the unique_ptr<Unit> whose getName() matches name. This allows you to call Unit methods or pass the smart pointer around without transferring ownership.
​
name
string
required
The exact name of the Unit to retrieve.
Returns: std::unique_ptr<Unit>& — a reference to the smart pointer that owns the matched Unit.
If no Unit with the given name exists, the function reaches the end of the loop without executing a return statement, resulting in undefined behaviour. Always ensure the Unit exists before calling this method, or use getUnitsVector() to iterate safely.
Example 
auto& playerPtr = myWorld.getUnitByName("Player");
playerPtr->addModule(MiniECS::ModuleType::Transform);

​
getUnitByIndex

std::unique_ptr<Unit>& getUnitByIndex(int index);
Returns a mutable reference to the unique_ptr<Unit> at the given zero-based index. Internally delegates to vector::at(), so out-of-range access throws rather than silently corrupting memory.
​
index
int
required
Zero-based index into the units vector. Valid range is [0, getUnitsVector().size() - 1].
Returns: std::unique_ptr<Unit>& — a reference to the smart pointer at the specified position. Throws: std::out_of_range if index is outside the bounds of the vector. Example 
auto& firstUnit = myWorld.getUnitByIndex(0);
firstUnit->addModule(MiniECS::ModuleType::Renderer);

​
getUnitsVector

const std::vector<std::unique_ptr<Unit>>& getUnitsVector() const;
Returns a const reference to the internal worldUnits vector. Use this for read-only iteration over all Units in the scene — for example, to inspect names or module counts without modifying the collection. Returns: const std::vector<std::unique_ptr<Unit>>& — a read-only reference to the units container. Example 
const auto& units = myWorld.getUnitsVector();
for (const auto& unit : units)
{
    std::cout << unit->getName() << "\n";
}
Because the return type is const, you cannot call non-const methods such as addModule() through this reference. Use getUnitByName() or getUnitByIndex() when you need a mutable handle.

​
play

void play() const;
Starts the simulation loop. The method first checks that worldUnits is non-empty; if it is empty, it prints "No units in the scene" and returns. It then iterates the units vector in order:
  • If a Unit has no Modules attached, it prints "No units in the scene have modules" and moves on to the next Unit.
  • If a Unit has at least one Module attached, it enters an infinite while(true) loop for that Unit, calling unit->callModuleStart() each iteration and sleeping the calling thread for 16 milliseconds (approximately 60 frames per second) via std::this_thread::sleep_for.
Because the while(true) loop never exits, play() will run forever on the first Unit that has Modules attached and never advance to any subsequent Units. Set up your World, Units, and Modules completely before calling play(). Any code placed after this call will never execute.
Example 
MiniECS::World world("Game");

world.createUnit("Player");
world.getUnitByName("Player")->addModule(MiniECS::ModuleType::Transform);
world.getUnitByName("Player")->addModule(MiniECS::ModuleType::Renderer);

world.play(); // Execution does not return from here

Build docs developers (and LLMs) love

Get started for freeTalk to us