🏄‍♀️ REPORT → A Ride Through Entity Component System

In which all computer code is essentially a series of data transformations.

🎶 "Fantasy is escapist, and that is its glory." — Ursula K. Le Guin on The Language of the Night

🎧 "In every real man a child is hidden that wants to play." — Friedrich Nietzsche on Thus Spoke Zarathustra

🎼 "I have a binary rule for publishing writings: either you take your time to make sure it's perfect, or you put it out fast and iterate publicly, like in open-source development. The first is perfectionism; the second is pragmatism." — Marina von Steinkirch



Hello there, my dear anon friend. Continuing our informal discussion from earlier this week about NULLSTAR's PleiadesOS:STEROPE, today we're going to dive a little into a topic we only briefly mentioned: Entity Component Systems (ECS).

As we read through today's material, please remember our rules:

🤖 If these notes look cool to you, it's your ✦moral duty✦ to read the original resources.
🤖 Just another blog, but not your usual blog: they're living notes that I change as I fancy.







🦴 A General Mental Model


From ecs-faq, ECS describes a design approach which promotes code reusability by separating data from behavior. Data is often stored in cache-friendly ways which benefit performance, so that ECS can typically support larger numbers of simulation objects.

More specifically, ECS separates three things that object-oriented programming often bundles together:

1️⃣ Entity: identity (a unique identifier for something in the world; the behavior of an entity can be changed at runtime; it can contain zero or more components)
2️⃣ Component: data without logic (a small piece of state attached to an entity; such as position, velocity, inventory, etc.; implementations typically use structs, classes, or associative arrays)
3️⃣ System: logic for behavior (code that processes entities with the relevant components)


This means that:

  • The behavior comes from composition (over inheritance), and it can be changed at runtime by adding or removing components. This avoids deep class hierarchies and the diamond problem.
  • For example, instead of a class Troll extends Monster extends Entity, a troll is an ID with Position + Velocity + AI...
  • Components of the same type are stored contiguously, so systems iterate over tightly packed arrays (maximizes CPU cache locality and decouples data from behavior). This is data-oriented design, making it ideal for multiplayer and high-performance simulations.


💡 ECS is commonly associated with data-oriented design (DOD), a software design philosophy that emphasizes data layout and memory access patterns as primary design concerns. DOD focuses on how data is laid out in RAM: when components of the same type are stored contiguously in memory arrays, the CPU loads them into its cache efficiently, drastically reducing cache misses during iteration.



🦴 A Rusty Example


Let's model a very simple simulation from one of the main robots, with a player and an NPC using bevy_ecs API. Both entities have positions and velocities, but only the player has a mutable quantity called entropy.

First, components are normal Rust structs. Specific instances of components correlate to entities:


use bevy_ecs::prelude::*;

#[derive(Component, Debug)]
struct Position {
    x: f32,
    y: f32,
}

#[derive(Component)]
struct Velocity {
    x: f32,
    y: f32,
}

#[derive(Component)]
struct Entropy(u32);

#[derive(Component)]
struct Player;

#[derive(Component)]
struct Npc;


Systems are normal Rust functions that run in parallel with each other:


// Processes every entity that has Position + Velocity.
fn movement_system(mut query: Query<(&mut Position, &Velocity)>) {
    for (mut position, velocity) in &mut query {
        position.x += velocity.x;
        position.y += velocity.y;
    }
}

// Processes only entities that have Entropy.
fn entropy_system(query: Query<(Entity, &Entropy)>) {
    for (entity, entropy) in &query {
        println!("Entity {:?}: Entropy = {}", entity, entropy.0);
    }
}


Entities, components, and resources are stored in a World, which are like std::collections’s HashSet and Vec, and they expose operations to insert, read, write, and remove the data they store:


fn main() {
    let mut world = World::new();

    (all the code below)
}


Entities are unique identifiers that correlate to zero or more components:


// An entity is an ID with a collection of components.
let player = world
        .spawn((
            Player,
            Position { x: 0.0, y: 0.0 },
            Velocity { x: 1.0, y: 0.5 },
            Entropy(100),
        ))
        .id();

let npc = world
        .spawn((
            Npc,
            Position { x: 10.0, y: 10.0 },
            Velocity { x: -1.0, y: 0.0 },
        ))
        .id();


Schedules run a set of systems according to some execution strategy (built in "parallel executor", running as many of them in parallel as possible):


// A Schedule executes systems against the World.
let mut schedule = Schedule::default();
schedule.add_systems((movement_system, entropy_system));

// Run one simulation tick.
schedule.run(&mut world);

// Inspect the updated state.
let position = world.get::<&Position>(player).unwrap();
println!("Player position: ({}, {})", position.x, position.y);

let position = world.get::<&Position>(npc).unwrap();
println!("NPC position: ({}, {})", position.x, position.y);


Things to note:

  • There is no inheritance: the NPC and the player share movement capabilities without a common base class.
  • Queries define membership: adding or removing a component changes which systems match an entity.
  • The schedule defines execution: systems can run independently and if one system depends on another’s output, the ordering requirement must be expressed.


How do I design for ECS?

  • How many instances of the data will exist?
  • How often is data accessed?
  • How often is the data mutated?
  • When does data need to be accessed/mutated?
  • Which data is accessed/mutated together?
  • What is the cardinality of the data (the number of entities, components, component instances, or possible combinations of component types in the world)?
  • Do the components and systems have single responsibilities?




🦴 Further References


Let's end today's discussion with an ever-growing list of good resources on building ECS:



Until next time, my friend!

⬛