API

World{CS<:Tuple,CT<:Tuple,N}

The World is the central ECS storage.

World(
    comp_types::Type...;
    initial_capacity::Int=128,
    allow_mutable::Bool=false,
)

Creates a new, empty World for the given component types.

Arguments

• comp_types: The component types used by the world.
• initial_capacity: Initial capacity for entities in each archetype and in the entity index.
• allow_mutable: Allows mutable components. Use with care, as all mutable objects are heap-allocated in Julia.

Example

world = World(Position, Velocity)
;

reset!(world::World)

Removes all entities and resources from the world, and un-registers all observers. Does NOT free reserved memory or remove archetypes.

Can be used to run systematic simulations without the need to re-allocate memory for each run. Accelerates re-populating the world by a factor of 2-3.

is_locked(world::World)::Bool

Returns whether the world is currently locked for modifications.

StructArrayStorage

Marks component types for using StructArray-like storage in world constructor.

In StructArray storages, mutable components are not allowed.

See also VectorStorage.

Example

world = World(
    Position => StructArrayStorage,
    Velocity => StructArrayStorage,
)

VectorStorage

Marks component types for using Vector storage in world constructor. As this is the default storage mode if the storage type is not specified.

See also StructArrayStorage.

Example

world = World(
    Position => VectorStorage,
    Velocity => VectorStorage,
)

Entity

Entity identifier.

const zero_entity::Entity

The reserved zero Entity value.

new_entity!(world::World, values::Tuple)::Entity

Creates a new Entity with the given component values. Types are inferred from the values.

new_entities!(world::World, n::Int, defaults::Tuple; iterate::Bool=false)::Union{Batch,Nothing}

Creates the given number of Entity, initialized with default values. Component types are inferred from the provided default values.

If iterate is true, a Batch iterator over the newly created entities is returned that can be used for initialization.

Arguments

• world::World: The World instance to use.
• n::Int: The number of entities to create.
• defaults::Tuple: A tuple of default values for initialization, like (Position(0, 0), Velocity(1, 1)).
• iterate::Bool: Whether to return a batch for individual entity initialization.

new_entities!(world::World, n::Int, comp_types::Tuple{Vararg{Val}})::Batch

Creates the given number of Entity.

Returns a Batch iterator over the newly created entities that should be used to initialize components. Note that components are not initialized/undef unless set in the iterator!

For a more convenient tuple syntax, the macro @new_entities! is provided.

Arguments

• world::World: The World instance to use.
• n::Int: The number of entities to create.
• comp_types::Tuple: Component types for the new entities, like Val.((Position, Velocity)).

@new_entities!(world::World, n::Int, comp_types::Tuple{Vararg{Val}})::Batch

Creates the given number of Entity.

Returns a Batch iterator over the newly created entities that should be used to initialize components. Note that components are not initialized/undef unless set in the iterator.

Macro version of new_entities! for ergonomic construction of component mappers.

Arguments

• world::World: The World instance to use.
• n::Int: The number of entities to create.
• comp_types::Tuple: Component types for the new entities, like (Position, Velocity).

remove_entity!(world::World, entity::Entity)

Removes an Entity from the World.

copy_entity!(
    world::World,
    entity::Entity;
    add::Tuple=(),
    remove::Tuple=(),
    mode=Val(:copy),
)

Copies an Entity, optionally adding and/or removing components.

Mutable and non-isbits components are shallow copied by default. This can be changed with the mode argument.

For a more convenient tuple syntax, the macro @copy_entity! is provided.

Arguments

• world: The World instance to query.
• entity::Entity: The entity to copy.
• add::Tuple: Components to add, like with=(Health(0),).
• remove::Tuple: Component types to remove, like Val.((Position,Velocity)).
• mode::Tuple: Copy mode for mutable and non-isbits components, like Val(:copy). Modes are :ref, :copy, :deepcopy.

Example

entity1 = copy_entity!(world, entity)

entity2 = copy_entity!(world, entity;
    add=(Health(100),),
    remove=Val.((Position, Velocity)),
)

@copy_entity!(
    world::World,
    entity::Entity;
    add::Tuple=(),
    remove::Tuple=(),
    mode=:copy,
)

Copies an Entity, optionally adding and/or removing components.

Mutable and non-isbits components are shallow copied by default. This can be changed with the mode argument.

Macro version of copy_entity! for more ergonomic component type tuples.

Arguments

• world: The World instance to query.
• entity::Entity: The entity to copy.
• add::Tuple: Components to add, like with=(Health(0),).
• remove::Tuple: Component types to remove, like (Position,Velocity).
• mode::Tuple: Copy mode for mutable and non-isbits components, like :copy. Modes are :ref, :copy, :deepcopy.

Example

entity1 = @copy_entity!(world, entity)

entity2 = @copy_entity!(world, entity;
    add=(Health(100),),
    remove=(Position, Velocity),
)

is_alive(world::World, entity::Entity)::Bool

Returns whether an Entity is alive.

is_zero(entity::Entity)::Bool

Returns whether an Entity is the zero entity.

get_components(world::World, entity::Entity, comp_types::Tuple)

Get the given components for an Entity. Components are returned in a tuple.

For a more convenient tuple syntax, the macro @get_components is provided.

Example

pos, vel = get_components(world, entity, Val.((Position, Velocity)))

@get_components(world::World, entity::Entity, comp_types::Tuple)

Get the given components for an Entity. Components are returned in a tuple.

Macro version of get_components for more ergonomic component type tuples.

Example

pos, vel = @get_components(world, entity, (Position, Velocity))

has_components(world::World, entity::Entity, comp_types::Tuple)::Bool

Returns whether an Entity has all given components.

For a more convenient tuple syntax, the macro @has_components is provided.

Example

has = has_components(world, entity, Val.((Position, Velocity)))

@has_components(world::World, entity::Entity, comp_types::Tuple)::Bool

Returns whether an Entity has all given components.

Macro version of has_components for more ergonomic component type tuples.

Example

has = @has_components(world, entity, (Position, Velocity))

set_components!(world::World, entity::Entity, values::Tuple)

Sets the given component values for an Entity. Types are inferred from the values. The entity must already have all these components.

add_components!(world::World, entity::Entity, values::Tuple)

Adds the given component values to an Entity. Types are inferred from the values.

remove_components!(world::World, entity::Entity, comp_types::Tuple)

Removes the given components from an Entity.

For a more convenient tuple syntax, the macro @remove_components! is provided.

Example

remove_components!(world, entity, Val.((Position, Velocity)))

@remove_components!(world::World, entity::Entity, comp_types::Tuple)

Removes the given components from an Entity.

Macro version of remove_components! for ergonomic construction of component mappers.

Example

@remove_components!(world, entity, (Position, Velocity))

exchange_components!(world::World{CS,CT,N}, entity::Entity; add::Tuple, remove::Tuple)

Adds and removes components on an Entity. Types are inferred from the add values.

For a more convenient tuple syntax, the macro @exchange_components! is provided.

Example

exchange_components!(world, entity;
    add=(Health(100),),
    remove=Val.((Position, Velocity)),
)

@exchange_components!(world::World, entity::Entity; add::Tuple, remove::Tuple)

Removes the given components from an Entity.

Macro version of exchange_components! for more ergonomic component type tuples.

Example

@exchange_components!(world, entity;
    add=(Health(100),),
    remove=(Position, Velocity),
)

Query

A query for components.

Query(
    world::World,
    comp_types::Tuple;
    with::Tuple=(),
    without::Tuple=(),
    optional::Tuple=(),
    exclusive::Val=Val(false)
)

Creates a query.

For a more convenient tuple syntax, the macro @Query is provided.

Arguments

• world: The World instance to query.
• comp_types::Tuple: Components the query filters for and provides access to. Must be a Val tuple like Val.((Position, Velocity)).
• with::Tuple: Additional components the entities must have. Passed as with=Val.((Health,)).
• without::Tuple: Components the entities must not have. Passed as without=Val.((Altitude,)).
• optional::Tuple: Additional components that are optional in the query. Passed as optional=Val.((Velocity,)).
• exclusive::Val{Bool}: Makes the query exclusive in base and with components, can't be combined with without.

Example

for (entities, positions, velocities) in Query(world, Val.((Position, Velocity)))
    for i in eachindex(entities)
        pos = positions[i]
        vel = velocities[i]
        positions[i] = Position(pos.x + vel.dx, pos.y + vel.dy)
    end
end

@Query(
    world::World,
    comp_types::Tuple;
    with::Tuple=(),
    without::Tuple=(),
    optional::Tuple=(),
    exclusive::Bool=false
)

Creates a query.

Macro version of Query that allows ergonomic construction of queries using simulated keyword arguments.

Arguments

• world: The World instance to query.
• comp_types::Tuple: Components the query filters for and provides access to. Must be a literal tuple like (Position, Velocity).
• with::Tuple: Additional components the entities must have. Passed as with=(Health,).
• without::Tuple: Components the entities must not have. Passed as without=(Altitude,).
• optional::Tuple: Additional components that are optional in the query. Passed as optional=(Velocity,).
• exclusive::Bool: Makes the query exclusive in base and with components, can't be combined with without.

Example

for (entities, positions, velocities) in @Query(world, (Position, Velocity))
    for i in eachindex(entities)
        pos = positions[i]
        vel = velocities[i]
        positions[i] = Position(pos.x + vel.dx, pos.y + vel.dy)
    end
end

close!(q::Query)

Closes the query and unlocks the world.

Must be called if a query is not fully iterated.

Entities

Archetype column for entities. Can be iterated and indexed like a Vector.

Used in query iteration.

@unpack ...

Unpacks the tuple returned from a Query during iteration into field vectors. Field vectors are particularly useful for StructArrayStorages, but can also be used with VectorStorages, although those are currently not equally efficient in broadcasted operations.

Example

for columns in Query(world, Val.((Position, Velocity)))
    @unpack entities, (x, y), (dx, dy) = columns
    @inbounds x .+= dx
    @inbounds y .+= dy
end

unpack(a::StructArrayView)

Unpacks the components (i.e. field vectors) of a StructArrayStorage column returned from a Query. See also @unpack.

unpack(a::FieldsView)

Unpacks the components (i.e. field vectors) of a VectorStorage column returned from a Query. See also @unpack.

get_resource(world::World, res_type::Type{T})::T

Get the resource of type T from the world.

has_resource(world::World, res_type::Type{T})::Bool

Check if a resource of type T is in the world.

add_resource!(world::World, res::T)::T

Add the given resource to the world. Returns the newly added resource.

set_resource!(world::World, res::T)::T

Overwrites an existing resource in the world. Returns the newly overwritten resource.

remove_resource!(world::World, res_type::Type{T})::T

Remove the resource of type T from the world. Returns the removed resource.

Batch

A batch iterator. This is returned from batch operations and serves for initializing newly added components.

close!(b::Batch)

Closes the batch iterator and unlocks the world.

Must be called if a batch is not fully iterated.

EventType

Type for built-in and custom events. See EventRegistry for creating custom event types.

Built-in event types

• OnCreateEntity: Event emitted when a new entity is created.
• OnRemoveEntity: Event emitted when an entity is removed from the World.
• OnAddComponents: Event emitted when components are added to an entity.
• OnRemoveComponents: Event emitted when components are removed from an entity.

EventRegistry

Serves for creating custom event types.

EventRegistry()

Creates a new EventRegistry.

new_event_type!(reg::EventRegistry, symbol::Symbol)

Creates a new custom EventType. Custom event types are best stored in global constants.

The symbol is only used for printing.

Observer

Observer for reacting on built-in and custom events.

See @observe! for details. See EventType for built-in, and EventRegistry for custom event types.

@observe!(
    fn::Function,
    world::World,
    event::EventType,
    components::Tuple=();
    with::Tuple=(),
    without::Tuple=(),
    exclusive::Val=Val(false),
    register::Bool=true,
)

Creates an Observer and (optionally, default) registers it.

Macro version of observe! that allows ergonomic construction of observers using simulated keyword arguments.

See EventType for built-in, and EventRegistry for custom event types.

Arguments

• fn::Function: A callback function to execute when a matching event is received. Can be used via a do block.
• world::World: The World to observe.
• event::EventType: The EventType to observe.
• components::Tuple=(): The component types to observe. Must be empty for OnCreateEntity and OnRemoveEntity.
• with::Tuple=(): Components the entity must have.
• without::Tuple=(): Components the entity must not have.
• exclusive::Bool=false: Makes the observer exclusive for entities that have exactly the components given be with.
• register::Bool=true: Whether the observer is registered immediately. Alternatively, register later with observe!

Example

@observe!(world, OnAddComponents, (Position, Velocity); with=(Altitude,)) do entity
    println(entity)
end

observe!(
    fn::Function,
    world::World,
    event::EventType,
    components::Tuple=();
    with::Tuple=(),
    without::Tuple=(),
    exclusive::Bool=false,
    register::Bool=true,
)

Creates an Observer and (optionally, default) registers it.

For a more convenient tuple syntax, the macro @observe! is provided.

See EventType for built-in, and EventRegistry for custom event types.

Arguments

• fn::Function: A callback function to execute when a matching event is received. Can be used via a do block.
• world::World: The World to observe.
• event::EventType: The EventType to observe.
• components::Tuple=(): The component types to observe. Must be empty for OnCreateEntity and OnRemoveEntity.
• with::Tuple=(): Components the entity must have.
• without::Tuple=(): Components the entity must not have.
• exclusive::Bool=false: Makes the observer exclusive for entities that have exactly the components given be with.
• register::Bool=true: Whether the observer is registered immediately. Alternatively, register later with observe!

Example

observe!(world, OnAddComponents, Val.((Position, Velocity)); with=Val.((Altitude,))) do entity
    println(entity)
end

observe!(world::World, observer::Observer; unregister::Bool=false)

Registers or un-registers the given Observer. Note that observers created with @observe! are automatically registered by default.

@emit_event!(world::World, event::EventType, entity::Entity, components::Tuple=())

Emits a custom event for the given EventType, Entity and optional components. The entity must have the given components. The entity can be the reserved zero_entity.

Macro version of emit_event! that allows more ergonomic event construction.

• world::World: The World to emit the event.
• event::EventType: The EventType to emit.
• entity::Entity: The Entity to emit the event for.
• components::Tuple=(): The component types to emit the event for. Optional.

emit_event!(world::World, event::EventType, entity::Entity, components::Tuple=())

Emits a custom event for the given EventType, Entity and optional components. The entity must have the given components. The entity can be the reserved zero_entity.

For a more convenient tuple syntax, the macro @emit_event! is provided.

• world::World: The World to emit the event.
• event::EventType: The EventType to emit.
• entity::Entity: The Entity to emit the event for.
• components::Tuple=(): The component types to emit the event for. Optional.