ecs
stableAn Entity-Component System (ECS) for game and simulation logic. Create a World, spawn entities, and attach named components to compose behavior.
use plugin ecs::{World.new, spawn, add_component, …} Functions (8)
- World.new Creates a new empty ECS world.
- spawn Spawns a new entity and returns a unique integer id.
- add_component Attaches any value to an entity under the given component name.
- get_component Returns the component value, or nil if the entity does not have that component.
- query Returns a table of entity ids that possess every component in the list.
- query_with Like query, but returns a table of {entity_id, comp1, comp2, ...} rows so component values are available alongside the id.
- each Returns all {entity_id, value} pairs for entities that have the named component.
- serialize serialize snapshots the whole world into a plain table.
Creates a new empty ECS world.
Creates a new empty ECS world. All entities and components live inside this world handle.
use plugin ecs::{World}
let world = World.new()
let player = world.spawn()
print("player id: {player}")
Spawns a new entity and returns a unique integer id.
Spawns a new entity and returns a unique integer id. Ids are monotonically increasing and never reused within the same world.
use plugin ecs::{World}
let world = World.new()
let e1 = world.spawn()
let e2 = world.spawn()
print("spawned {e1} and {e2}")
Attaches any value to an entity under the given component name.
Attaches any value to an entity under the given component name. Calling it again with the same name replaces the previous value.
use plugin ecs::{World}
let world = World.new()
let e = world.spawn()
world.add_component(e, "position", #{"x": 10.0, "y": 20.0})
world.add_component(e, "health", 100)
world.add_component(e, "name", "hero")
Returns the component value, or nil if the entity does not have that component.
Returns the component value, or nil if the entity does not have that component.
use plugin ecs::{World}
let world = World.new()
let e = world.spawn()
world.add_component(e, "hp", 80)
let hp = world.get_component(e, "hp")
print("hp = {hp}")
Returns a table of entity ids that possess every component in the list.
Returns a table of entity ids that possess every component in the list. Useful for iterating over a category of entities in a game loop.
use plugin ecs::{World}
let world = World.new()
let a = world.spawn()
world.add_component(a, "position", #{"x": 0.0, "y": 0.0})
world.add_component(a, "velocity", #{"x": 1.0, "y": 0.0})
let b = world.spawn()
world.add_component(b, "position", #{"x": 5.0, "y": 5.0})
let moving = world.query(["position", "velocity"])
print("entities with both: {moving}")
Like query, but returns a table of {entity_id, comp1, comp2, ...} rows so component values are available alongside the id.
Like query, but returns a table of {entity_id, comp1, comp2, ...} rows so component values are available alongside the id.
use plugin ecs::{World}
let world = World.new()
let e = world.spawn()
world.add_component(e, "hp", 50)
world.add_component(e, "name", "goblin")
let rows = world.query_with(["hp", "name"])
print(rows)
Returns all {entity_id, value} pairs for entities that have the named component.
Returns all {entity_id, value} pairs for entities that have the named component. Convenient for iterating a single component across all entities.
use plugin ecs::{World}
let world = World.new()
let e1 = world.spawn()
let e2 = world.spawn()
world.add_component(e1, "score", 42)
world.add_component(e2, "score", 99)
let scores = world.each("score")
print(scores)
serialize snapshots the whole world into a plain table.
serialize snapshots the whole world into a plain table. deserialize restores it, replacing current content. Useful for save/load systems.
use plugin ecs::{World}
let world = World.new()
let e = world.spawn()
world.add_component(e, "level", 5)
let snapshot = world.serialize()
world.clear()
world.deserialize(snapshot)
print(world.entity_count())