API

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

The World is the central ECS storage.

World(comp_types::Type...; allow_mutable::Bool=false)

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

Arguments

• comp_types: The component types used by the world.
• allow_mutable: Allows mutable components. Use with care, as all mutable objects are heap-allocated in Julia.

Example

world = World(Position, Velocity)
;

is_locked(world::World)::Bool

Returns whether the world is currently locked for modifications.

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.

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 = Val.((Position, Velocity)),
)

Query

A query for components.

@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.

Queries can be stored and re-used. However, query creation is fast (<20ns), so this is not mandatory.

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: 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.

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.