Manages the registration and lifecycle of components and prefabs.
Components
Components can be registered with the register_components/1 function which accepts a list of modules that implement
the Genesis.Component behaviour. When components are registered, their order and some additional information is stored
in a persistent_term for efficient lookup during event dispatching.
This means that this function is expensive and should not be called frequently - ideally once during application startup.
Genesis.Manager.register_components([
MyApp.Components.Health,
MyApp.Components.Position,
MyApp.Components.Velocity
])The order of registration matters
The order of registration also defines the order in which event are handled by components.
This means that if both Health and Position components handle the :damage event,
Health will always handle that event before Position and so on.
Prefabs
Prefabs are reusable entity templates that define a set of components with default properties.
They allow you to quickly spawn entities with predefined characteristics. Like components, prefabs are also
represented internally as entities and they also have a dedicated global named context called Genesis.Prefabs.
Prefab registration can be done with the register_prefab/1 function. This function accepts a map with the prefab
definition including its name and components with their default properties.
Genesis.Manager.register_prefab(%{
name: "Spaceship",
components: %{
"health" => %{current: 100, maximum: 100},
"velocity" => %{acceleration: 10, max_speed: 50}
}
})See the dedicated documentation for Genesis.Prefab for more details on prefab definitions.
Notifications
Notifications are a useful way to react to entity changes without needing to poll for updates constantly. It's specially useful in scenarios where you need to have some piece of UI that needs to be updated on demand.
When an entity is modified, the manager dispatches notifications to the registered processes right before calling the Genesis.Component.on_hook/3 callback.
Processes watching for changes can specify which hooks and component types they are interested in by passing additional options to the watch/2 function.
Summary
Functions
Clones an entity or prefab into the target context.
Returns a map of components registered in the manager.
Returns all event handlers registered in the manager.
Returns a stream of prefabs registered in the manager.
Registers component modules.
Components must implement the Genesis.Component behaviour.
Registers a new prefab definition. Prefabs are templates for creating entities with predefined components and properties.
Stops receiving notifications for the entities in the given world.
Starts receiving notifications for the entities in the given world.
Functions
Clones an entity or prefab into the target context.
Options
:target- the target context (defaults toentity.context):overrides- a map of component / properties to override in the cloned entity
See Genesis.Context.create/2 for additional options.
Examples
# Clone an entity within the same context
Genesis.Manager.clone(entity)
#=> {:ok, cloned}
# Clone with property overrides
overrides = %{"health" => %{current: 50}}
Genesis.Manager.clone(entity, overrides: overrides)
#=> {:ok, cloned}
# Clone to a different context
Genesis.Manager.clone(entity, target: context2)
#=> {:ok, cloned}Returns a map of components registered in the manager.
Examples
Genesis.Manager.register_components([Health, Position])
#=> :ok
Genesis.Manager.components()
#=> %{"health" => Health, "position" => Position}Returns all event handlers registered in the manager.
Examples
Genesis.Manager.register_components([Health, Position])
#=> :ok
Genesis.Manager.handlers()
#=> [damage: [Health], move: [Position], heal: [Health]]Returns a stream of prefabs registered in the manager.
Examples
Genesis.Manager.register_prefab(%{name: "X-Wing", components: ...})
#=> {:ok, entity, [...]}
Genesis.Manager.prefabs() |> Enum.to_list()
#=> [{"X-Wing", %Genesis.Prefab{name: "X-Wing", components: [...]}}]Registers component modules.
Components must implement the Genesis.Component behaviour.
Examples
Genesis.Manager.register_components([Health, Position, Velocity])
#=> :okRegisters a new prefab definition. Prefabs are templates for creating entities with predefined components and properties.
Examples
Genesis.Manager.register_prefab(%{name: "Spaceship", components: ...})
#=> {:ok, entity, [%Health{current: 50, maximum: 100}]}
Genesis.Manager.register_prefab(%{name: "Spaceship", components: ...})
#=> {:error, :already_registered}Stops receiving notifications for the entities in the given world.
Starts receiving notifications for the entities in the given world.
Options
:hooks- A list of hooks to watch for. Defaults to all hooks (:attached, :removed, :updated).:components- A list of component modules to watch for. Defaults to all registered components.