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

Returns a single tuple wiht 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.

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

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.

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 restults 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}}
  ]

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

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

See the select/2 function for more info.