View Source Ecspanse.Query (ECSpanse v0.10.0)

The Ecspanse.Query module provides a set of functions for querying entities, components and resources.

The queries are read-only operations they do not modify the state of the components or resources.

Queries can be run both from within the Ecspanse systems and from outside of the framework.

Summary

Generic

one(query)

Returns a single tuple with components for a t/0 query. Returns nil if no result was found. Raises if more than one entry.

select(component_modules_tuple, filters \\ [])

select/2 is the most versatile function for querying entities and components. On its own, it will return an Ecspanse.Query struct that holds the query details. The struct needs to be passed to Ecspanse.Query.stream/1 or Ecspanse.Query.one/1 to get the results.

stream(query)

Returns a stream of components tuples for a t/0 query.

Entities

entity_exists?(entity_id)

Checks if an entity exists by its ID, or by the entity struct.

fetch_entity(entity_id)

Fetches an Ecspanse.Entity.t/0 by its ID.

get_component_entity(component)

Returns a component's entity.

Relationships

has_children_with_component?(entity, component_module)

Returns true if the entity has at least a child with the given component module.

has_children_with_components?(entity, component_module_list)

Returns true if the entity has at least a child with all the given component modules.

has_parents_with_component?(entity, component_module)

Returns true if the entity has at least a parent with the given component module.

has_parents_with_components?(entity, component_module_list)

Returns true if the entity has at least a parent with all the given component modules.

is_child_of?(list)

Returns true if a given entity is a child of another entity.

is_parent_of?(list)

Returns true if a given entity is a parent of another entity.

list_ancestors(entity)

Returns the list of ancestor entities for the given entity. That means the parents of the entity and their parents and so on.

list_children(entity)

Returns the list of child entities for the given entity.

list_descendants(entity)

Returns the list of descendant entities for the given entity. That means the children of the entity and their children and so on.

list_parents(entity)

Returns the list of parent entities for the given entity.

Components

fetch_component(entity, component_module)

Fetches the component by its module for a given entity.

fetch_components(entity, component_modules_tuple)

Fetches a tuple of components by their modules for a given entity. The entity must have all the components for the query to succeed.

has_component?(entity, component_module)

Returns true if the entity has a component with the given module.

has_components?(entity, component_module_list)

Returns true if the entity has all the components with the given modules.

list_components(entity)

Lists all the components for a given entity.

Resources

fetch_resource(resource_module)

Fetches a resource by its module.

Types

t()

The query preparation struct.

Generic

one(query)

@spec one(t()) :: components_state :: tuple() | nil

Returns a single tuple with components for a t/0 query. Returns nil if no result was found. Raises if more than one entry.

See the select/2 function for more info.

select(component_modules_tuple, filters \\ [])

@spec select(
  component_modules :: tuple(),
  keyword()
) :: t()

Arguments

1. component_modules

The first argument is a tuple of components to be selected. The query will return the components only for the entities that have all the components in the tuple.

The entity can be queried as well by adding Ecspanse.Entity as the first element in the tuple. Also, optional components can be queries, by adding the :opt key. The optional components should be placed at the end of the tuple.

The results will be returned in the same order as the components in the tuple. This makes it easy to use pattern matching on the result.

2. filters

The filters are optional. They can be used to further narrow down the results.

:with - a list of components that the entity must have in addition to the ones specified in the component_modules tuple. But those components will not be returned in the result. :with filter has one option: :without - a list of components that the entity must not have.
:or_with - similar to :with. It allows to specify multiple filters for the same query. Multiple or_with filters can be used in the same query. The results will be returned if the entity components match any of the filters.
:for - a list of Ecspanse.Entity.t/0 that the query should be run for. The components will be returned only for those entities.
:not_for - a list of Ecspanse.Entity.t/0 that the query should not be run for. The components will be returned for all entities except those.
:for_children_of - a list of Ecspanse.Entity.t/0. The components will be returned only for the children of those entities.
:for_descendants_of - a list of Ecspanse.Entity.t/0. The components will be returned only for all descendants of those entities.
:for_parents_of - a list of Ecspanse.Entity.t/0. The components will be returned only for the parents of those entities.
:for_ancestors_of - a list of Ecspanse.Entity.t/0. The components will be returned only for all ancestors of those entities.

Info
Combining the following filters is not supported: :for, :not_for, :for_children_of, :for_descendants_of, :for_parents_of, :for_ancestors_of. Only one of them can be used in a query. Otherwise it will rise an error.

Examples

  Ecspanse.Query.select({Ecspanse.Entity, Demo.Components.Health, opt: Demo.Components.Mana},
    with: [Demo.Components.Orc],
    or_with: [[Demo.Components.Wizard], without: [Demo.Components.WhiteMagic]],
    for_descendants_of: [enemy_clan_entity]
  )
  |> Ecspanse.Query.stream()
  |> Enum.to_list()

a potential result may be:

  [
    {orc_entity, %Demo.Components.Health{value: 100}, nil},
    {wizard_entity, %Demo.Components.Health{value: 60}, %Demo.Components.Mana{value: 200}}
  ]

stream(query)

@spec stream(t()) :: Enumerable.t()

Returns a stream of components tuples for a t/0 query.

See the select/2 function for more info.

Entities

entity_exists?(entity_id)

@spec entity_exists?(Ecspanse.Entity.id() | Ecspanse.Entity.t()) :: boolean()

Checks if an entity exists by its ID, or by the entity struct.

fetch_entity(entity_id)

@spec fetch_entity(Ecspanse.Entity.id()) ::
  {:ok, Ecspanse.Entity.t()} | {:error, :not_found}

Fetches an Ecspanse.Entity.t/0 by its ID.

An entity exists only if it has at least one component.

Examples

  {:ok, %Ecspanse.Entity{}} = Ecspanse.Query.fetch_entity(hero_entity_id)

get_component_entity(component)

@spec get_component_entity(component_state :: struct()) :: Ecspanse.Entity.t()

Returns a component's entity.

Examples

  {:ok, %Ecspanse.Entity{}} = Ecspanse.Query.get_component_entity(hero_component)

Relationships

has_children_with_component?(entity, component_module)

@spec has_children_with_component?(Ecspanse.Entity.t(), module()) :: boolean()

Returns true if the entity has at least a child with the given component module.

Examples

  true = Ecspanse.Query.has_children_with_component?(hero_entity, Demo.Components.Boots)

has_children_with_components?(entity, component_module_list)

@spec has_children_with_components?(Ecspanse.Entity.t(), [module()]) :: boolean()

Returns true if the entity has at least a child with all the given component modules.

Examples

  true = Ecspanse.Query.has_children_with_components?(hero_entity, [Demo.Components.Boots, Demo.Components.Sword])

has_parents_with_component?(entity, component_module)

@spec has_parents_with_component?(Ecspanse.Entity.t(), module()) :: boolean()

Returns true if the entity has at least a parent with the given component module.

Examples

  true = Ecspanse.Query.has_parents_with_component?(boots_entity, Demo.Components.Hero)

has_parents_with_components?(entity, component_module_list)

@spec has_parents_with_components?(Ecspanse.Entity.t(), [module()]) :: boolean()

Returns true if the entity has at least a parent with all the given component modules.

Examples

  true = Ecspanse.Query.has_parents_with_components?(boots_entity, [Demo.Components.Hero, Demo.Components.Gold])

is_child_of?(list)

@spec is_child_of?(parent: Ecspanse.Entity.t(), child: Ecspanse.Entity.t()) ::
  boolean()

Returns true if a given entity is a child of another entity.

Examples

  true = Ecspanse.Query.is_child_of?(parent: hero_entity, child: boots_entity)

is_parent_of?(list)

@spec is_parent_of?(parent: Ecspanse.Entity.t(), child: Ecspanse.Entity.t()) ::
  boolean()

Returns true if a given entity is a parent of another entity.

Examples

  true = Ecspanse.Query.is_parent_of?(parent: hero_entity, child: boots_entity)

list_ancestors(entity)

@spec list_ancestors(Ecspanse.Entity.t()) :: [Ecspanse.Entity.t()]

Returns the list of ancestor entities for the given entity. That means the parents of the entity and their parents and so on.

Examples

  [hero_entity, level_entity] = Ecspanse.Query.list_ancestors(compass_entity)

list_children(entity)

@spec list_children(Ecspanse.Entity.t()) :: [Ecspanse.Entity.t()]

Returns the list of child entities for the given entity.

Examples

  [sword_item_entity, magic_potion_entity] = Ecspanse.Query.list_children(hero_entity)

list_descendants(entity)

@spec list_descendants(Ecspanse.Entity.t()) :: [Ecspanse.Entity.t()]

Returns the list of descendant entities for the given entity. That means the children of the entity and their children and so on.

Examples

  [inventory_entity, map_entity] = Ecspanse.Query.list_descendants(hero_entity)

list_parents(entity)

@spec list_parents(Ecspanse.Entity.t()) :: [Ecspanse.Entity.t()]

Returns the list of parent entities for the given entity.

Examples

  [hero_entity] = Ecspanse.Query.list_parents(inventory_entity)

Components

fetch_component(entity, component_module)

@spec fetch_component(Ecspanse.Entity.t(), module()) ::
  {:ok, component_state :: struct()} | {:error, :not_found}

Fetches the component by its module for a given entity.

Examples

  {:ok, gold_component} = Ecspanse.Query.fetch_component(hero_entity, Demo.Components.Gold)

fetch_components(entity, component_modules_tuple)

@spec fetch_components(Ecspanse.Entity.t(), component_modules :: tuple()) ::
  {:ok, components_state :: tuple()} | {:error, :not_found}

Fetches a tuple of components by their modules for a given entity. The entity must have all the components for the query to succeed.

Examples

  {:ok, {gold_component, gems_component}} = Ecspanse.Query.fetch_components(hero_entity, {Demo.Components.Gold, Demo.Components.Gems})

has_component?(entity, component_module)

@spec has_component?(Ecspanse.Entity.t(), module()) :: boolean()

Returns true if the entity has a component with the given module.

Examples

  true = Ecspanse.Query.has_component?(hero_entity, Demo.Components.Gold)

has_components?(entity, component_module_list)

@spec has_components?(Ecspanse.Entity.t(), [module()]) :: boolean()

Returns true if the entity has all the components with the given modules.

Examples

  true = Ecspanse.Query.has_components?(hero_entity, [Demo.Components.Gold, Demo.Components.Gems])

list_components(entity)

@spec list_components(Ecspanse.Entity.t()) :: [components_state :: struct()]

Lists all the components for a given entity.

The output is an unordered list of all the entity's components.

Note
The Ecspanse.Component.Children and Ecspanse.Component.Parents components are excluded from the output.
Use the provided list_children/1 and list_parents/1 functions to query the entity's relations.

Examples

  [gold_component, gems_component, position_component, energy_component] =
    Ecspanse.Query.list_components(hero_entity)

Resources

fetch_resource(resource_module)

@spec fetch_resource(resource_module :: module()) ::
  {:ok, resource_state :: struct()} | {:error, :not_found}

Fetches a resource by its module.

Examples

  {:ok, lobby_resource} = Ecspanse.Query.fetch_resource(Demo.Resources.Lobby)

fetch_tagged_component(entity, tags)

@spec fetch_tagged_component(Ecspanse.Entity.t(), [tag :: atom()]) ::
  {:ok, components_state :: struct()} | {:error, :not_found}

Fetches an entity's component by a list of tags. Raises if more than one entry is found.

Note
The project logic must ensure that only one component per entity is tagged with the given tags.

Examples

  {:ok, %Demo.Components.Paladin{} = hero_class_component} =
    Ecspanse.Query.fetch_tagged_component(hero_entity, [:class])

list_tagged_components(tags)

@spec list_tagged_components([tag :: atom()]) :: [components_state :: struct()]

Returns a list of components tagged with a list of tags for all entities.