View Source ECSx.Component behaviour (ECSx v0.3.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 - When true, each entity may have, at most, one component of this type; attempting to add another will overwrite the first. When false, an entity may have many components of this type.
  • :read_concurrency - when true, enables read concurrency for this component table. Only set this if you know what you're doing. Defaults to false

Link to this section Summary

Callbacks

Creates a new component.

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.

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.

Link to this section Types

@type id() :: any()
@type value() :: any()

Link to this section Callbacks

@callback add(entity :: id(), value :: value()) :: :ok

Creates a new component.

example

Example

# Add an ArmorRating component to entity `123` with value `10`
ArmorRating.add(123, 10)
@callback exists?(entity :: id()) :: boolean()

Checks if an entity has one or more components of this type.

@callback get_all() :: [{id(), value()}]

Look up all components of this type.

example

Example

# Get all velocity components
Velocity.get_all()
@callback get_all(entity :: id()) :: [value()]

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)
@callback get_one(entity :: id()) :: value() | nil

Look up a single component.

Raises if more than one component is returned.

example

Example

# Get the Velocity for entity `123`
Velocity.get_one(123)
@callback remove(entity :: id()) :: :ok

Removes any existing components of this type from an entity.

Link to this callback

remove_one(entity, value)

View Source
@callback remove_one(entity :: id(), value :: value()) :: :ok

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)
@callback search(value :: value()) :: [id()]

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)