Provides low-level entity storage backed by ETS.
A context contains the following ETS tables that are always kept in sync.
mtable- table that stores metadata associated with entitiesctable- table that stores components associated with entitiesnindex- table that stores metadata indexed by nametindex- table that stores components indexed by type
Note that most read operations are intentionally dirty reads for performance reasons.
Summary
Functions
Assigns components to an existing entity.
Components of the same type will be replaced.
Returns :ok on success, or {:error, reason} on failure.
Returns a specification to start a context under a supervisor.
Deletes all data from the context tables.
Creates a new entity in the context with the given options.
Destroys an entity and removes all associated data.
Returns :ok on success, or {:error, reason} on failure.
Associates a component to an entity, fails if the component type is already present.
Returns :ok on success, or {:error, reason} on failure.
Removes components from an entity.
When the component_type is provided, only that component is removed.
Returns :ok on success, or {:error, reason} on failure.
Replaces the metadata of an entity.
Returns :ok on success, or {:error, reason} on failure.
Replaces an existing component on an entity.
Returns :ok on success, or {:error, reason} on failure.
Introspection API
Returns a stream of all component entries in the context. Note that this function will cause the entire table to be iterated.
Returns a stream of entities with their components grouped together. Note that this function will cause the entire table to be iterated.
Returns a stream of all metadata entries in the context. Note that this function will cause the entire table to be iterated.
Process API
Starts a new Genesis.Context.
Same as GenServer.start_link/3.
Query API
Returns all entities with components of the given type. Returns a list of tuples containing the entity and the component struct.
Returns a list of entities that have all the components specified in the list.
Returns a list of entities that have at least one of the components specified in the list.
Returns all entities that have the given property with a value greater than or equal to the given minimum.
Returns all entities that have the given property with a value less than or equal to the given maximum.
Returns all entities that have the given property with a value between the given minimum and maximum (inclusive).
Returns a list of entities that are direct children of the given entity.
Checks if an entity or name exists in the context.
Returns true if found, or false otherwise.
Fetches all components of an entity.
Returns {entity, components} if found, or nil.
Retrieves the component attached to an entity. Returns the component struct if present or default.
Retrieves information about an entity.
Returns {entity, types, metadata} if found, or nil.
Looks up an entity by a registered name.
Returns {entity, types, metadata} if found, or nil.
Returns all entities that match the given properties for the component type.
Returns a list of entities that do not have any of the components specified in the list.
Returns a list of entities that match the specified criteria.
Functions
Assigns components to an existing entity.
Components of the same type will be replaced.
Returns :ok on success, or {:error, reason} on failure.
Examples
{:ok, entity} = Genesis.Context.create(context)
components = [%Health{current: 100, maximum: 100}]
Genesis.Context.assign(context, entity, components)Returns a specification to start a context under a supervisor.
See Supervisor.
Deletes all data from the context tables.
Creates a new entity in the context with the given options.
Options:
:name- registers the entity under the given name (optional):metadata- associates metadata to the entity (optional)
See Genesis.Entity.new/1 for additional options.
Note that the created entity has its context set automatically.
Examples
# Create an entity
Genesis.Context.create(context)
#=> {:ok, entity}
# Create a named entity with metadata
Genesis.Context.create(context,
name: "Shopkeeper",
metadata: %{faction: :alliance}
)Destroys an entity and removes all associated data.
Returns :ok on success, or {:error, reason} on failure.
Associates a component to an entity, fails if the component type is already present.
Returns :ok on success, or {:error, reason} on failure.
Examples
{:ok, entity} = Genesis.Context.create(context)
Genesis.Context.emplace(context, entity, %Position{x: 10, y: 20})Removes components from an entity.
When the component_type is provided, only that component is removed.
Returns :ok on success, or {:error, reason} on failure.
Examples
# Removes a specific component from the entity
Genesis.Context.erase(context, entity, Health)
# Removes all components from the entity
Genesis.Context.erase(context, entity)Replaces the metadata of an entity.
Returns :ok on success, or {:error, reason} on failure.
Examples
metadata = %{created_at: System.system_time()}
Genesis.Context.patch(context, entity, metadata)Replaces an existing component on an entity.
Returns :ok on success, or {:error, reason} on failure.
Examples
{:ok, entity} = Genesis.Context.create(context)
Genesis.Context.emplace(context, entity, %Position{x: 0, y: 0})
# Replaces the position component entirely
Genesis.Context.replace(context, entity, %Position{x: 10, y: 20})Introspection API
Returns a stream of all component entries in the context. Note that this function will cause the entire table to be iterated.
Returns a stream of entities with their components grouped together. Note that this function will cause the entire table to be iterated.
Returns a stream of all metadata entries in the context. Note that this function will cause the entire table to be iterated.
Process API
Starts a new Genesis.Context.
Same as GenServer.start_link/3.
Query API
Returns all entities with components of the given type. Returns a list of tuples containing the entity and the component struct.
Examples
iex> Genesis.Context.all(context, Health)
#=> [{entity_1, %Health{current: 100}}, {entity_2, %Health{current: 50}}]Returns a list of entities that have all the components specified in the list.
Examples
iex> Genesis.Context.all_of(context, [Health, Velocity])
#=> [entity_1, entity_2]Returns a list of entities that have at least one of the components specified in the list.
Examples
iex> Genesis.Context.any_of(context, [Health, Velocity])
#=> [entity_1, entity_2, entity_3]Returns all entities that have the given property with a value greater than or equal to the given minimum.
Examples
iex> Genesis.Context.at_least(context, Health, :current, 50)
#=> [{entity_1, %Health{current: 75}}]Returns all entities that have the given property with a value less than or equal to the given maximum.
Examples
iex> Genesis.Context.at_most(context, Health, :current, 50)
#=> [{entity_1, %Health{current: 25}}]Returns all entities that have the given property with a value between the given minimum and maximum (inclusive).
Examples
iex> Genesis.Context.between(context, Health, :current, 50, 100)
#=> [{entity_1, %Health{current: 75}}]Returns a list of entities that are direct children of the given entity.
Examples
iex> Genesis.Context.children_of(context, entity_1)
#=> [entity_2, entity_3, entity_4, ...]Checks if an entity or name exists in the context.
Returns true if found, or false otherwise.
Examples
# Using an entity
Genesis.Context.exists?(context, entity)
# Using a name
Genesis.Context.exists?(context, "Player")Fetches all components of an entity.
Returns {entity, components} if found, or nil.
Examples
# Fetch by entity
Genesis.Context.fetch(context, entity)
#=> {entity, [%Health{current: 100}, %Position{x: 10, y: 20}]}
# Fetch by name
Genesis.Context.fetch(context, "Enemy")
#=> {#Entity<9876543>, [%Health{current: 50}, %Position{x: 5, y: 15}]}Retrieves the component attached to an entity. Returns the component struct if present or default.
Examples
iex> Genesis.Context.get(context, entity_1, Health)
#=> %Health{current: 100}Retrieves information about an entity.
Returns {entity, types, metadata} if found, or nil.
Examples
Genesis.Context.info(context, entity)
#=> {entity, [], %{}}Looks up an entity by a registered name.
Returns {entity, types, metadata} if found, or nil.
Examples
{:ok, npc} = Genesis.Context.create(context, name: "Shopkeeper")
Genesis.Context.emplace(context, npc, %Health{current: 100})
Genesis.Context.lookup(context, "Shopkeeper")
#=> {entity, [Health], %{created_at: 1234567890}}Returns all entities that match the given properties for the component type.
Examples
iex> Genesis.Context.match(context, Moniker, name: "Tripida")
#=> [{entity_1, %Moniker{name: "Tripida"}}]Returns a list of entities that do not have any of the components specified in the list.
Examples
iex> Genesis.Context.none_of(context, [Health, Velocity])
#=> [entity_1, entity_2]Returns a list of entities that match the specified criteria.
Options
:all- Matches entities that have all the specified components.:any- Matches entities that have at least one of the specified components.:none- Matches entities that do not have any of the specified components.