View Source ECSx.Component behaviour (ECSx v0.4.0)
A Component labels an entity as having a certain attribute, and holds any data needed to model that attribute.
For example, if Entities in your application should have a "color" value, you will create a Component type called Color
. This allows you to add a color component to an Entity with add/2
, look up the color value for a given Entity with get_one/1
, get all Entities' color values with get_all/1
, remove the color value from an Entity altogether with remove/1
, or test whether an entity has a color with exists?/1
.
Under the hood, we use ETS to store the Components in memory for quick retrieval via Entity ID.
usage
Usage
Each Component type should have its own module, where it can be optionally configured.
defmodule MyApp.Components.Color do
use ECSx.Component,
value: :binary,
unique: true
end
options
Options
:value
- The type of value which will be stored in this component type. Valid types are::atom, :binary, :datetime, :float, :integer
:unique
- Whentrue
, each entity may have, at most, one component of this type; attempting to add another will overwrite the first. Whenfalse
, an entity may have many components of this type.:log_edits
- Whentrue
, log messages will be emitted for each component added, updated, or removed. Defaults tofalse
:read_concurrency
- Whentrue
, enables read concurrency for this component table. Only set this if you know what you're doing. Defaults tofalse
Link to this section Summary
Callbacks
Creates a new component.
Look up all components where the value is greater than or equal to min
.
Look up all components where the value is less than or equal to max
.
Look up all components where the value is greater than or equal to min
and less
than or equal to max
.
Checks if an entity has one or more components of this type.
Look up all components of this type.
Look up all components of this type belonging to a given entity.
Look up a single component and return its value.
Removes any existing components of this type from an entity.
Removes one component with a specific entity ID and value.
Look up all IDs for entities which have a component of this type with a given value.
Updates an existing component's value.
Link to this section Types
Link to this section Callbacks
Creates a new component.
options
Options
:persist
- Whentrue
, this component will persist across app reboots. Defaults tofalse
example
Example
# Add an ArmorRating component to entity `123` with value `10`
# If the app shuts down, this component will be removed
ArmorRating.add(123, 10)
# This ArmorRating component will be persisted after app shutdown,
# and automatically re-added to entity `123` upon next startup
ArmorRating.add(123, 10, persist: true)
Look up all components where the value is greater than or equal to min
.
This function only works for numerical component types (:value
set to either
:integer
or :float
). Other value types will raise UndefinedFunctionError
.
example
Example
# Get all PlayerExperience components where value >= 2500
PlayerExperience.at_least(2500)
Look up all components where the value is less than or equal to max
.
This function only works for numerical component types (:value
set to either
:integer
or :float
). Other value types will raise UndefinedFunctionError
.
example
Example
# Get all PlayerHealth components where value <= 10
PlayerHealth.at_most(10)
Look up all components where the value is greater than or equal to min
and less
than or equal to max
.
This function only works for numerical component types (:value
set to either
:integer
or :float
). Other value types will raise UndefinedFunctionError
.
example
Example
# Get all RespawnCount components where 51 <= value <= 100
RespawnCount.between(51, 100)
Checks if an entity has one or more components of this type.
Look up all components of this type.
example
Example
# Get all velocity components
Velocity.get_all()
Look up all components of this type belonging to a given entity.
This function is only useful for component types configured with unique: false
.
For unique components, get_one/1
should be used instead.
example
Example
# Get all PowerUp components for entity `123`
PowerUp.get_all(123)
Look up a single component and return its value.
Raises an ECSx.MultipleResultsError
if more than one result is found.
If a default
value is provided, that value will be returned if no results are found.
If default
is not provided, this function will raise an ECSx.NoResultsError
if no results are found.
example
Example
# Get the Velocity for entity `123`, which is known to already exist
Velocity.get_one(123)
# Get the Velocity for entity `123` if it exists, otherwise return `nil`
Velocity.get_one(123, nil)
@callback remove(entity :: id()) :: :ok
Removes any existing components of this type from an entity.
Removes one component with a specific entity ID and value.
This function is only useful for component types configured with unique: false
.
For unique components, remove/1
should be used instead.
example
Example
# Remove a specific PowerUp value `9` from entity `123`
PowerUp.remove_one(123, 9)
Look up all IDs for entities which have a component of this type with a given value.
example
Example
# Get all entities with a velocity of `60`
Velocity.search(60)
Updates an existing component's value.
The component's :persist
option will remain unchanged. (see add/3
)
example
Example
ArmorRating.add(123, 10)
# Increase the ArmorRating value from `10` to `15`
ArmorRating.update(123, 15)