game reference
The game package: game.ecs, game.world.
game.ecs
class Store
offer class Store<T>The components of one type, packed.
Rows are dense: the component in row i belongs to entity owners[i],
and a pass over the rows reads them in order with no holes to skip.
slots[e] is the row entity e occupies plus one, or zero when it has
none of this component -- plus one so that an unused slot is the zero a
fresh array already holds.
Removing a component moves the last row into the hole rather than shifting the rest. That is what keeps the pass sequential, and it is why nothing may hold a row index across a removal.
field rows
var rows: soa []mut Tfield owners
var owners: []mut intfield slots
var slots: []mut intfield count
var count: int = 0method Row
fun Row(e: int) -> intThe row entity e occupies, or -1 when it has no component here.
method Has
fun Has(e: int) -> boolmethod Add
fun Add(e: int) -> intThe row for e, adding one if it has none. -1 when the store is
full or the entity is outside the range it was built for.
method Remove
fun Remove(e: int)Drops e's component by moving the last row into its place.
function StoreNew
offer fun StoreNew<T>(capacity: int, entities: int) -> Store<T> uses unsafeA store for capacity components of up to entities entities.
Fixed size: there is no growth yet, so Add reports -1 rather than
reallocating. A game that knows its budget is the case this serves,
and growth is a copy loop away.
class Entities
offer class EntitiesHands out entity numbers.
Numbers are not reused yet. Reuse needs a generation counter beside the index -- otherwise a handle to a dead entity reads the one that took its place -- and that is a change to what an entity is, so it waits until there is something to free.
field next
var next: int = 0field limit
var limit: int = 0method Spawn
fun Spawn() -> intA fresh entity, or -1 when there are no more.
method Len
fun Len() -> intfunction EntitiesNew
offer fun EntitiesNew(limit: int) -> Entitiesclass PackedStore
offer class PackedStore<T>The components of one type, one record after another.
The same interface as Store and the other layout underneath: a pass
that touches most of a record wants this one, and a pass that touches
one field of a wide record wants the other. Which is the whole point of
the layout being a property of the storage (D73) -- the rows are the
only difference between the two, and a system reads them the same way.
field rows
var rows: []mut Tfield owners
var owners: []mut intfield slots
var slots: []mut intfield count
var count: int = 0method Row
fun Row(e: int) -> intmethod Has
fun Has(e: int) -> boolmethod Add
fun Add(e: int) -> intmethod Remove
fun Remove(e: int)function PackedStoreNew
offer fun PackedStoreNew<T>(capacity: int, entities: int) -> PackedStore<T> uses unsafegame.world
struct Token
offer struct Token<T>The number that says which component type this is.
A struct rather than a bare u64 because the type it names is what
makes it the right number: TokenOf<Position>() has type
Token<Position>, and that is how the compiler knows which token to
answer with.
field value
var value: u64function TokenOf
offer fun TokenOf<T>() -> Token<T>The token of T. Answered by the compiler, so it has no body.
class World
offer class WorldA world: entities, and a component array per type.
field handle
var handle: u64 = 0method Spawn
fun Spawn() -> u64 uses unsafeA new entity with no components. Never zero.
method Despawn
fun Despawn(entity: u64) uses unsafeRemoves it and everything it had.
method Alive
fun Alive(entity: u64) -> bool uses unsafemethod Len
fun Len() -> int uses unsafeHow many entities are living.
method Destroy
fun Destroy() uses unsafeGives the storage back. Not a deinit: a world is handed to the
functions that work on it, and a type with a destructor would be
moved by that rather than borrowed (D87).
function WorldNew
offer fun WorldNew() -> World uses unsafefunction Add
offer fun Add<T>(world: World, entity: u64, value: T) uses unsafeGives entity a component, or replaces the one it has.
function Get
offer fun Get<T>(world: World, entity: u64) -> T? uses unsafeWhat entity's component of T is, or nothing when it has none.
function Has
offer fun Has<T>(world: World, entity: u64, of: Token<T>) -> bool uses unsafeWhether entity has the component of names.
The token is an argument rather than a type parameter of its own
because the answer is a bool: a type parameter has to appear in the
signature for a call to be able to say what it is (E0133), and here
the token is where it appears.
function Remove
offer fun Remove<T>(world: World, entity: u64) -> T? uses unsafeTakes T away from entity and gives back what it was.
function CountOf
offer fun CountOf<T>(world: World, of: Token<T>) -> int uses unsafeHow many entities have the component of names.
function RunSystems
offer unsafe fun RunSystems(world: World, delta: f32)Runs every system of the calling file, stage by stage.
What a stage is, is the compiler's answer: the systems in one may run
at the same time because none of them writes what another reads, and
the runtime starts a thread per system in it (D101). It has no body
for the same reason TokenOf has none -- the schedule is a property of
the declarations, and only the compiler can see them all.
The systems that run are the ones in the file that calls this: the address of a function is something only the module holding it can give. A program whose systems live in several files calls it once per file.