Project F: ECS Game Engine Core (1/4)
Learn Zig Series):We just wrapped up a four-episode HTTP server project, and now it's time for something completely different. We're building a game engine. Well -- the core of one, anyway. Over the next four episodes we'll implement an Entity-Component-System (ECS) framework in Zig, complete with component storage, queries, systems, and a terminal renderer to actually see things move on screen. This first episode is about the architecture: what ECS is, why it exists, and building the foundation -- entities, the World struct, and sparse set storage.
If you've ever tried to build a game in an object-oriented language, you've probably hit the inheritance wall. Your Player extends Character extends Entity, and then you need a FlyingEnemy that shares movement code with Player but also needs Enemy behavior and suddenly you're stuck in a diamond inheritance problem that makes you question your career choices. ECS solves this entirely, and Zig's data-oriented design philosophy makes it a particularly good fit. Here we go!
The Entity-Component-System pattern splits game objects into three separate concepts:
The key insight is composition over inheritance. Instead of defining what an object IS (a Player, an Enemy, a Bullet), you define what an object HAS. A player entity has Position + Velocity + Health + PlayerInput components. An enemy entity has Position + Velocity + Health + AIBehavior components. A bullet entity has Position + Velocity + Damage components. The movement system doesn't care whether something is a player, enemy, or bullet -- it just moves anything that has Position and Velocity.
const std = @import("std");
// Components are just data structs. Nothing more.
const Position = struct {
x: f32,
y: f32,
};
const Velocity = struct {
dx: f32,
dy: f32,
};
const Health = struct {
current: i32,
max: i32,
};
const Sprite = struct {
char: u8,
color: u8,
};
const Gravity = struct {
force: f32,
};
That's all a component is. A struct with fields. No methods, no inheritance, no vtables. The simplicity is the point. Data lives in components. Logic lives in systems. Identity lives in entities. This three-way separation is what makes ECS so powerful and flexible.
To understand why ECS exists, you need to understand what it replaced. Traditional game engines use deep class hierarchies. Here's the kind of thing you'd see in a typical C++ or Java game engine:
// THE OLD WAY (illustrative pseudo-code -- don't do this)
//
// GameObject
// +-- Character
// | +-- Player
// | +-- Enemy
// | +-- FlyingEnemy
// | +-- GroundEnemy
// +-- Projectile
// | +-- Bullet
// | +-- Missile (has health... wait, that's a Character thing)
// +-- Pickup
// +-- HealthPack
// +-- AmmoBox (needs physics... like a Projectile?)
// The problems multiply fast:
// 1. FlyingEnemy needs movement code from Character AND flying physics
// 2. Missile needs both Projectile trajectory AND can be destroyed (Health)
// 3. HealthPack needs collision detection -- same as Projectile?
// 4. Adding a new feature (e.g. "burnable") means touching the ENTIRE tree
// 5. Changing the base class breaks everything downstream
Every time a game designer says "what if this enemy could also fly?" or "what if the player could pick up the missile and throw it?", the inheritance tree needs surgery. You end up with diamond inheritance, god objects, or massive if/else chains checking type at runtime. The class hierarchy becomes a prison where adding one feature requires modifying six files.
With ECS, the same scenarios are trivial:
// THE ECS WAY
// Want a flying enemy? Give it: Position, Velocity, Health, AIBehavior, Flying
// Want a destructible missile? Give it: Position, Velocity, Damage, Health
// Want a pickup with physics? Give it: Position, Velocity, Pickup, Collider
// Want something burnable? Just add a Burnable component. Done.
//
// No class changes. No hierarchy. Just data.
const Flying = struct {
altitude: f32,
max_altitude: f32,
};
const Burnable = struct {
ignite_threshold: f32,
burn_rate: f32,
is_burning: bool,
};
const Collider = struct {
width: f32,
height: f32,
};
The second major advantage is cache performance. In an inheritance-based system, a Player object contains ALL its data in one allocation: position, velocity, health, inventory, input state, animation state, audio state -- hundreds of bytes. When the physics system iterates over all game objects to update positions, it loads the entire object into cache just to read 8 bytes of position data. Most of the cache line is wasted on data the physics system doesn't need.
In an ECS, all Position components live in a contiguous array. When the movement system iterates positions, it gets pure sequential memory access -- every byte in the cache line is useful data. This is the same data-oriented design philosophy we saw in Zig's standard library (remember how std.ArrayList stores all elements contiguously in episode 5?). On modern CPUs, cache-friendly access patterns can mean 10-50x performance differences for hot loops.
An entity is an ID. But not just any integer -- we need to handle the case where entities get destroyed and their IDs get recycled. If entity 42 dies and later entity 42 is reused for a completely different object, we don't want stale references to the old entity 42 accidentally accessing the new one. This is the ABA problem, and the solution is a generation counter.
pub const Entity = struct {
index: u32,
generation: u32,
pub const INVALID = Entity{ .index = std.math.maxInt(u32), .generation = 0 };
pub fn eql(self: Entity, other: Entity) bool {
return self.index == other.index and self.generation == other.generation;
}
pub fn isValid(self: Entity) bool {
return self.index != std.math.maxInt(u32);
}
pub fn format(
self: Entity,
comptime _: []const u8,
_: std.fmt.FormatOptions,
writer: anytype,
) !void {
try writer.print("Entity({d}v{d})", .{ self.index, self.generation });
}
};
The entity has two fields: an index (which slot in the entity array this is) and a generation (how many times this slot has been recycled). When you create entity slot 42 for the first time, it's Entity{.index = 42, .generation = 0}. When that entity is destroyed and the slot gets reused, the new entity is Entity{.index = 42, .generation = 1}. Any code still holding the old Entity{.index = 42, .generation = 0} can check the generation and see that it's stale.
This is the exact same concept as a generational index that Rust game engines use (the generational-arena crate, for example). The two 32-bit fields pack into a single 64-bit value, which is cheap to copy and compare. We could use packed structs (episode 17) to squeeze both into a single u64, but keeping them as separate fields is clearer for a learning project.
The INVALID sentinel uses maxInt(u32) as the index -- that's 4 billion, and no sane game will have that many entities. The format function lets us print entities nicely with std.debug.print("{}", .{entity}) which outputs something like Entity(42v1) -- index 42, generation (version) 1. We implemented custom formatters before in episode 24, same pattern here.
Now we need something to manage entities -- create new ones, destroy old ones, and recycle IDs. This is the entity registry:
const EntityEntry = struct {
generation: u32,
alive: bool,
};
pub const EntityRegistry = struct {
entries: std.ArrayList(EntityEntry),
free_indices: std.ArrayList(u32),
alive_count: u32,
allocator: std.mem.Allocator,
pub fn init(allocator: std.mem.Allocator) EntityRegistry {
return .{
.entries = std.ArrayList(EntityEntry).init(allocator),
.free_indices = std.ArrayList(u32).init(allocator),
.alive_count = 0,
.allocator = allocator,
};
}
pub fn deinit(self: *EntityRegistry) void {
self.entries.deinit();
self.free_indices.deinit();
}
pub fn create(self: *EntityRegistry) !Entity {
if (self.free_indices.items.len > 0) {
// Recycle a previously destroyed slot
const index = self.free_indices.pop();
var entry = &self.entries.items[index];
entry.alive = true;
self.alive_count += 1;
return Entity{
.index = index,
.generation = entry.generation,
};
}
// No free slots -- allocate a new one
const index: u32 = @intCast(self.entries.items.len);
try self.entries.append(.{
.generation = 0,
.alive = true,
});
self.alive_count += 1;
return Entity{
.index = index,
.generation = 0,
};
}
pub fn destroy(self: *EntityRegistry, entity: Entity) !void {
if (entity.index >= self.entries.items.len) return;
var entry = &self.entries.items[entity.index];
// Check generation matches -- don't destroy an already-recycled slot
if (entry.generation != entity.generation) return;
if (!entry.alive) return;
entry.alive = false;
entry.generation += 1; // Bump generation so old references become stale
self.alive_count -= 1;
try self.free_indices.append(entity.index);
}
pub fn isAlive(self: *const EntityRegistry, entity: Entity) bool {
if (entity.index >= self.entries.items.len) return false;
const entry = self.entries.items[entity.index];
return entry.alive and entry.generation == entity.generation;
}
};
The create function checks the free list first. If there's a recycled slot available, it reuses it (with the bumped generation from when it was destroyed). If not, it appends a new entry. The destroy function marks the slot as dead, bumps the generation, and pushes the index onto the free list for future reuse.
Having said that, the generation check in destroy is important. If someone holds a stale reference to an entity that was already destroyed and recycled, calling destroy with the old generation won't do anything -- the generation won't match, so the currently alive entity in that slot is safe. This is defensive programming at its finest.
The free list approach means entity creation is O(1) in both cases -- either pop from the free list or append to the entries array. Destruction is also O(1) -- mark dead and push to free list. This is fast enough for creating and destroying thousands of entities per frame, which is exactly what a particle system or bullet hell game needs.
Now the interesting part. We know entities are just IDs. We know components are just data. The question is: how do we associate components with entities efficiently? We need to answer three questions fast:
There are two main approaches in the ECS world: archetypes and sparse sets. We're going with sparse sets because they're simpler to implement and better for dynamic component addition/removal.
pub fn SparseSet(comptime T: type) type {
return struct {
const Self = @This();
// Sparse array: indexed by entity index, contains index into dense array
// null_sentinel means "this entity doesn't have this component"
sparse: std.ArrayList(u32),
// Dense array: packed component data
dense_entities: std.ArrayList(u32),
dense_data: std.ArrayList(T),
allocator: std.mem.Allocator,
const null_sentinel: u32 = std.math.maxInt(u32);
pub fn init(allocator: std.mem.Allocator) Self {
return .{
.sparse = std.ArrayList(u32).init(allocator),
.dense_entities = std.ArrayList(u32).init(allocator),
.dense_data = std.ArrayList(T).init(allocator),
.allocator = allocator,
};
}
pub fn deinit(self: *Self) void {
self.sparse.deinit();
self.dense_entities.deinit();
self.dense_data.deinit();
}
pub fn set(self: *Self, entity_index: u32, component: T) !void {
// Grow sparse array if needed
while (self.sparse.items.len <= entity_index) {
try self.sparse.append(null_sentinel);
}
if (self.sparse.items[entity_index] != null_sentinel) {
// Entity already has this component -- update in place
const dense_idx = self.sparse.items[entity_index];
self.dense_data.items[dense_idx] = component;
return;
}
// New component: add to dense arrays
const dense_idx: u32 = @intCast(self.dense_data.items.len);
try self.dense_entities.append(entity_index);
try self.dense_data.append(component);
self.sparse.items[entity_index] = dense_idx;
}
pub fn get(self: *const Self, entity_index: u32) ?*const T {
if (entity_index >= self.sparse.items.len) return null;
const dense_idx = self.sparse.items[entity_index];
if (dense_idx == null_sentinel) return null;
return &self.dense_data.items[dense_idx];
}
pub fn getMut(self: *Self, entity_index: u32) ?*T {
if (entity_index >= self.sparse.items.len) return null;
const dense_idx = self.sparse.items[entity_index];
if (dense_idx == null_sentinel) return null;
return &self.dense_data.items[dense_idx];
}
pub fn has(self: *const Self, entity_index: u32) bool {
if (entity_index >= self.sparse.items.len) return false;
return self.sparse.items[entity_index] != null_sentinel;
}
pub fn remove(self: *Self, entity_index: u32) void {
if (entity_index >= self.sparse.items.len) return;
const dense_idx = self.sparse.items[entity_index];
if (dense_idx == null_sentinel) return;
// Swap-remove: move last element into the removed slot
const last_idx: u32 = @intCast(self.dense_data.items.len - 1);
if (dense_idx != last_idx) {
const last_entity = self.dense_entities.items[last_idx];
self.dense_data.items[dense_idx] = self.dense_data.items[last_idx];
self.dense_entities.items[dense_idx] = last_entity;
// Update the sparse entry for the moved entity
self.sparse.items[last_entity] = dense_idx;
}
_ = self.dense_data.pop();
_ = self.dense_entities.pop();
self.sparse.items[entity_index] = null_sentinel;
}
pub fn count(self: *const Self) usize {
return self.dense_data.items.len;
}
// Iteration: return the dense data array directly
pub fn data(self: *Self) []T {
return self.dense_data.items;
}
pub fn entities(self: *const Self) []const u32 {
return self.dense_entities.items;
}
};
}
Here's how it works. The sparse array is indexed by entity index. If sparse[42] is 7, that means entity 42's component data lives at index 7 in the dense arrays. If sparse[42] is null_sentinel, entity 42 doesn't have this component.
The dense arrays store the actual component data and the corresponding entity indices, packed contiguously with no gaps. When we iterate all Position components, we iterate the dense data array -- pure sequential memory access, every element is a Position that belongs to a living entity. No gaps, no null checks during iteration.
The remove operation uses swap-remove: instead of shifting all elements after the removed one (which would be O(n) and invalidate all sparse indices), we copy the last element into the gap and update the sparse entry for the moved element. This is O(1) and keeps the dense array packed. We've seen this pattern before with std.ArrayList.swapRemove in episode 22.
The generic SparseSet(comptime T: type) uses Zig's comptime generics (episode 14) so we get a separate, fully typed sparse set for each component type. SparseSet(Position) stores positions. SparseSet(Velocity) stores velocities. Each is independent, each has its own dense array for iteration. The compiler generates specialized code for each -- no runtime type dispatch, no boxing, no heap allocation for individual components.
Before we move on, let me explain why I picked sparse sets over archetypes, since it's a legitimate design decision.
Archetypes group entities by their exact set of components. All entities with (Position, Velocity) live together in one table. All entities with (Position, Velocity, Health) live in a different table. Iteration is blazing fast because you iterate entire tables with perfect cache locality. But adding or removing a component means moving the entity from one archetype table to another -- which involves copying all its component data.
Sparse sets store each component type independently. Adding or removing a component is just an insert/delete in one sparse set -- O(1), no data copying. But iterating entities that have BOTH Position and Velocity requires checking two sparse sets, which is slower than archetype iteration.
For our learning project, sparse sets win because:
Production ECS frameworks like Bevy (Rust) use archetypes. Entt (C++) uses sparse sets. Both work. For learning the concepts, sparse sets are the better starting point because you understand exactly what's happening with no hidden complexity.
The World is the top-level container that owns the entity registry and all component storage. It's the central hub that everything else talks to:
pub const World = struct {
registry: EntityRegistry,
positions: SparseSet(Position),
velocities: SparseSet(Velocity),
healths: SparseSet(Health),
sprites: SparseSet(Sprite),
gravities: SparseSet(Gravity),
allocator: std.mem.Allocator,
pub fn init(allocator: std.mem.Allocator) World {
return .{
.registry = EntityRegistry.init(allocator),
.positions = SparseSet(Position).init(allocator),
.velocities = SparseSet(Velocity).init(allocator),
.healths = SparseSet(Health).init(allocator),
.sprites = SparseSet(Sprite).init(allocator),
.gravities = SparseSet(Gravity).init(allocator),
.allocator = allocator,
};
}
pub fn deinit(self: *World) void {
self.gravities.deinit();
self.sprites.deinit();
self.healths.deinit();
self.velocities.deinit();
self.positions.deinit();
self.registry.deinit();
}
pub fn spawn(self: *World) !Entity {
return self.registry.create();
}
pub fn despawn(self: *World, entity: Entity) !void {
if (!self.registry.isAlive(entity)) return;
// Remove all components for this entity
self.positions.remove(entity.index);
self.velocities.remove(entity.index);
self.healths.remove(entity.index);
self.sprites.remove(entity.index);
self.gravities.remove(entity.index);
try self.registry.destroy(entity);
}
pub fn isAlive(self: *const World, entity: Entity) bool {
return self.registry.isAlive(entity);
}
// Convenience: spawn with initial components
pub fn spawnWith(
self: *World,
pos: ?Position,
vel: ?Velocity,
hp: ?Health,
sprite: ?Sprite,
grav: ?Gravity,
) !Entity {
const entity = try self.spawn();
if (pos) |p| try self.positions.set(entity.index, p);
if (vel) |v| try self.velocities.set(entity.index, v);
if (hp) |h| try self.healths.set(entity.index, h);
if (sprite) |s| try self.sprites.set(entity.index, s);
if (grav) |g| try self.gravities.set(entity.index, g);
return entity;
}
};
Yes, the component storage is hardcoded -- we have explicit fields for Position, Velocity, Health, Sprite, and Gravity. A production ECS would use type-erased storage (we covered type erasure in episode 13) combined with comptime reflection (episode 32) to register arbitrary component types at compile time. That's beautiful but adds quite some complexity. For our game engine, we know exactly which components we need, and listing them explicitly is clearer.
The despawn function removes all components before destroying the entity. This is critical -- if we only destroyed the entity ID without cleaning up components, the sparse sets would still contain orphaned data for a dead entity. When the slot gets recycled, the new entity would inherit the old one's components. Nasty bug to track down.
The spawnWith convenience function lets you create an entity with its initial components in one call. Using optionals (?Position) means you pass null for components you don't need. So spawning a particle might look like world.spawnWith(.{.x = 10, .y = 20}, .{.dx = 1, .dy = -2}, null, .{.char = '*', .color = 3}, .{.force = 0.5}) -- position, velocity, no health, a sprite, and gravity. Compact and readable.
Let's make sure all of this actually works. Testing an ECS means verifying entity lifecycle, component storage, and the interaction between the two:
test "entity creation returns unique IDs" {
const allocator = std.testing.allocator;
var registry = EntityRegistry.init(allocator);
defer registry.deinit();
const e1 = try registry.create();
const e2 = try registry.create();
const e3 = try registry.create();
try std.testing.expect(e1.index == 0);
try std.testing.expect(e2.index == 1);
try std.testing.expect(e3.index == 2);
// All should be generation 0 (first use)
try std.testing.expect(e1.generation == 0);
try std.testing.expect(e2.generation == 0);
try std.testing.expect(e3.generation == 0);
try std.testing.expect(registry.alive_count == 3);
}
test "entity destruction and recycling" {
const allocator = std.testing.allocator;
var registry = EntityRegistry.init(allocator);
defer registry.deinit();
const e1 = try registry.create(); // index 0, gen 0
const e2 = try registry.create(); // index 1, gen 0
_ = try registry.create(); // index 2, gen 0
try std.testing.expect(registry.alive_count == 3);
// Destroy entity 1
try registry.destroy(e2);
try std.testing.expect(registry.alive_count == 2);
try std.testing.expect(!registry.isAlive(e2));
// Creating a new entity should recycle index 1 with bumped generation
const e4 = try registry.create();
try std.testing.expect(e4.index == 1); // recycled slot
try std.testing.expect(e4.generation == 1); // bumped generation
// Old reference to e2 should be stale
try std.testing.expect(!registry.isAlive(e2));
try std.testing.expect(registry.isAlive(e4));
// They have the same index but different generations
try std.testing.expect(e2.index == e4.index);
try std.testing.expect(!e2.eql(e4));
// e1 should still be alive and unaffected
try std.testing.expect(registry.isAlive(e1));
}
test "sparse set basic operations" {
const allocator = std.testing.allocator;
var positions = SparseSet(Position).init(allocator);
defer positions.deinit();
// Set components for some entities
try positions.set(0, .{ .x = 10.0, .y = 20.0 });
try positions.set(5, .{ .x = 50.0, .y = 60.0 });
try positions.set(2, .{ .x = 30.0, .y = 40.0 });
try std.testing.expect(positions.count() == 3);
// Check existence
try std.testing.expect(positions.has(0));
try std.testing.expect(positions.has(5));
try std.testing.expect(positions.has(2));
try std.testing.expect(!positions.has(1));
try std.testing.expect(!positions.has(99));
// Read data
const p0 = positions.get(0).?;
try std.testing.expectApproxEqAbs(p0.x, 10.0, 0.001);
try std.testing.expectApproxEqAbs(p0.y, 20.0, 0.001);
// Update existing component
try positions.set(0, .{ .x = 100.0, .y = 200.0 });
const p0_updated = positions.get(0).?;
try std.testing.expectApproxEqAbs(p0_updated.x, 100.0, 0.001);
try std.testing.expect(positions.count() == 3); // count unchanged
}
test "sparse set removal with swap" {
const allocator = std.testing.allocator;
var positions = SparseSet(Position).init(allocator);
defer positions.deinit();
try positions.set(0, .{ .x = 1.0, .y = 1.0 });
try positions.set(1, .{ .x = 2.0, .y = 2.0 });
try positions.set(2, .{ .x = 3.0, .y = 3.0 });
// Remove entity 0 -- last element (entity 2) should fill the gap
positions.remove(0);
try std.testing.expect(positions.count() == 2);
try std.testing.expect(!positions.has(0));
try std.testing.expect(positions.has(1));
try std.testing.expect(positions.has(2));
// Entity 2's data should still be correct after the swap
const p2 = positions.get(2).?;
try std.testing.expectApproxEqAbs(p2.x, 3.0, 0.001);
}
test "sparse set iteration" {
const allocator = std.testing.allocator;
var positions = SparseSet(Position).init(allocator);
defer positions.deinit();
try positions.set(10, .{ .x = 1.0, .y = 0.0 });
try positions.set(20, .{ .x = 2.0, .y = 0.0 });
try positions.set(30, .{ .x = 3.0, .y = 0.0 });
// Iterate and sum all x values
var sum: f32 = 0;
for (positions.data()) |pos| {
sum += pos.x;
}
try std.testing.expectApproxEqAbs(sum, 6.0, 0.001);
// Verify entity indices match
const ents = positions.entities();
try std.testing.expect(ents.len == 3);
}
test "world spawn and despawn" {
const allocator = std.testing.allocator;
var world = World.init(allocator);
defer world.deinit();
// Spawn an entity with position and velocity
const player = try world.spawnWith(
.{ .x = 0.0, .y = 0.0 },
.{ .dx = 1.0, .dy = 0.0 },
.{ .current = 100, .max = 100 },
.{ .char = '@', .color = 2 },
null,
);
try std.testing.expect(world.isAlive(player));
try std.testing.expect(world.positions.has(player.index));
try std.testing.expect(world.velocities.has(player.index));
try std.testing.expect(world.healths.has(player.index));
try std.testing.expect(world.sprites.has(player.index));
try std.testing.expect(!world.gravities.has(player.index)); // we passed null
// Despawn should clean up everything
try world.despawn(player);
try std.testing.expect(!world.isAlive(player));
try std.testing.expect(!world.positions.has(player.index));
try std.testing.expect(!world.velocities.has(player.index));
try std.testing.expect(!world.healths.has(player.index));
try std.testing.expect(!world.sprites.has(player.index));
}
test "world entity recycling with components" {
const allocator = std.testing.allocator;
var world = World.init(allocator);
defer world.deinit();
// Spawn and give a position
const e1 = try world.spawn();
try world.positions.set(e1.index, .{ .x = 42.0, .y = 99.0 });
// Destroy it
try world.despawn(e1);
// Spawn a new entity -- should recycle the slot
const e2 = try world.spawn();
try std.testing.expect(e2.index == e1.index);
try std.testing.expect(e2.generation == 1);
// The recycled entity should NOT have the old position
try std.testing.expect(!world.positions.has(e2.index));
}
The last test is particularly important -- it verifies that despawning properly cleans up components before recycling the entity slot. Without that cleanup, e2 would inherit e1's position, which would be a silent, hard-to-debug correctness bug. The kind of thing that makes your game characters teleport randmoly across the screen and you spend three hours wondering why ;-)
Let's spawn some game entities to see the whole system working end-to-end:
pub fn main() !void {
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
defer {
const check = gpa.deinit();
if (check == .leak) std.debug.print("WARNING: memory leak detected\n", .{});
}
const allocator = gpa.allocator();
var world = World.init(allocator);
defer world.deinit();
// Spawn a player
const player = try world.spawnWith(
.{ .x = 40.0, .y = 12.0 },
.{ .dx = 0.0, .dy = 0.0 },
.{ .current = 100, .max = 100 },
.{ .char = '@', .color = 2 },
null,
);
// Spawn some enemies
const enemy1 = try world.spawnWith(
.{ .x = 10.0, .y = 5.0 },
.{ .dx = 0.5, .dy = 0.0 },
.{ .current = 50, .max = 50 },
.{ .char = 'E', .color = 1 },
null,
);
const enemy2 = try world.spawnWith(
.{ .x = 70.0, .y = 8.0 },
.{ .dx = -0.3, .dy = 0.1 },
.{ .current = 30, .max = 30 },
.{ .char = 'e', .color = 1 },
null,
);
// Spawn a projectile (no health, has gravity)
const bullet = try world.spawnWith(
.{ .x = 40.0, .y = 11.0 },
.{ .dx = 0.0, .dy = -2.0 },
null,
.{ .char = '|', .color = 3 },
.{ .force = 0.1 },
);
// Print what we've got
const stdout = std.io.getStdOut().writer();
try stdout.print("Spawned entities:\n", .{});
try stdout.print(" Player: {}\n", .{player});
try stdout.print(" Enemy1: {}\n", .{enemy1});
try stdout.print(" Enemy2: {}\n", .{enemy2});
try stdout.print(" Bullet: {}\n", .{bullet});
try stdout.print("\nPositions ({d} entities):\n", .{world.positions.count()});
const pos_ents = world.positions.entities();
const pos_data = world.positions.data();
for (pos_ents, pos_data) |ent_idx, pos| {
try stdout.print(" entity {d}: ({d:.1}, {d:.1})\n", .{ ent_idx, pos.x, pos.y });
}
try stdout.print("\nEntities with gravity: {d}\n", .{world.gravities.count()});
try stdout.print("Entities with health: {d}\n", .{world.healths.count()});
// Kill enemy2
try stdout.print("\nDestroying enemy2...\n", .{});
try world.despawn(enemy2);
try stdout.print("Positions after despawn: {d}\n", .{world.positions.count()});
try stdout.print("Is enemy2 alive? {}\n", .{world.isAlive(enemy2)});
// Spawn a new entity -- should recycle enemy2's slot
const pickup = try world.spawnWith(
.{ .x = 70.0, .y = 8.0 },
null,
null,
.{ .char = '+', .color = 4 },
null,
);
try stdout.print("New pickup: {} (recycled slot)\n", .{pickup});
}
Running this prints:
$ zig build-exe ecs.zig && ./ecs
Spawned entities:
Player: Entity(0v0)
Enemy1: Entity(1v0)
Enemy2: Entity(2v0)
Bullet: Entity(3v0)
Positions (4 entities):
entity 0: (40.0, 12.0)
entity 1: (10.0, 5.0)
entity 2: (70.0, 8.0)
entity 3: (40.0, 11.0)
Entities with gravity: 1
Entities with health: 3
Destroying enemy2...
Positions after despawn: 3
Is enemy2 alive? false
New pickup: Entity(2v1) (recycled slot)
Entity 2 got recycled with generation bumped to 1. The old enemy2 reference (Entity(2v0)) is stale. The new pickup has Position and Sprite but no Velocity, Health, or Gravity -- it's a completely different entity that happens to reuse the same index. This is ECS working exactly as designed.
despawn cleaning up all components before recycling the entity slotSparseSet(comptime T: type)) generate specialized storage for each component type with zero runtime overheadDe groeten!
@scipio