ecstatic-framework / ecstatic

An ECS (Entity-Component-System) framework in Elixir

Ecstatic

ECStatic is an Entity-Component-Systems framework in Elixir.

Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed by adding `ecstatic` to your list of dependencies in `mix.exs`:

def deps do
  [{:ecstatic, "~> 0.1.0"}]
end

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc) and published on [HexDocs](https://hexdocs.pm). Once published, the docs can be found at [https://hexdocs.pm/ecstatic](https://hexdocs.pm/ecstatic).

Vocabulary

Here’s a list of Ecstatic words; following will be an example sentence in English where we can connect each word to something meaningful for you.

• Component : a collection of properties
• Entity : a collection of components
• Aspect : a filter for entities, based on which components are and aren’t on that entity
• System : business logic; receives an entity and will do some work on it if the entity matches a given aspect.
• Watcher : A hook that connects to a lifecycle event and will call a system if a particular predicate is matched.

So if Zaphod is a 33-year-old alien who doesn’t have tendonitis and plays tennis, then his stamina will go down but he won’t hurt after the game.

This could be written as (for example): There’s an entity that has a “social component” with a name of “Zaphod”, a “race component” with a name of “alien”, and who does not have the “tendonitis component”. When taken through the TennisGame “system”, the entity’s “physical component” will see its stamina reduced. A “watcher” will check for “physical components” with a stamina going down and pass those to a HealthSystem; if the entity matches the “aspect” of “has tendonitis component”, it will add a “pain component” to the entity.

Code samples

defmodule Human do
  use Ecstatic.Entity
  @default_components [Age, Mortal]
end

defmodule Age do
  use Ecstatic.Component
  @default_value %{age: 1, life_expectancy: 80}
end

defmodule Mortal do
  use Ecstatic.Component
  @default_value %{mortal: true}
end

defmodule AgeSystem do
  use Ecstatic.System

  def aspect, do: %Ecstatic.Aspect{with: [Age]}

  def dispatch(entity) do
    age_comp = Entity.find_component(entity, Age)
    new_age_comp = %{age_comp | age: age_comp.age + 1}
    %Ecstatic.Changes{updated: [new_age_comp]}
  end
end

defmodule DeathOfOldAgeSystem do
  use Ecstatic.System

  def aspect, do: %Ecstatic.Aspect{with: [Age, Mortal]}

  def dispatch(entity) do
    if Enum.rand(10_000) > 7000 do
      %Ecstatic.Changes{attached: [Dead]}
    else
      %Ecstatic.Changes{}
    end
  end
end

defmodule Watchers do
  use Ecstatic.Watcher

  watch_component Age, run: AgeSystem, every: 6_000
  watch_component Age, run: DeathOfOldAgeSystem, when: fn(_pre, post) -> post.age > post.life_expectancy end
end

1. Stop using the Ets store, rely on the generic one. Let the users choose the one they want to use.
2. Some systems (all systems?) trigger on ASPECTS. This means that when a new component gets added, and when a component gets removed, the entity event consumer runs the check for new systems to tick or systems to stop ticking. Also means aspects need to be able to define some particular component values (such as %Aspect{with: [%Health{points: 0}]}). The good news is that this should simplify some watchers. Although that also means I kinda-sorta lose my “tick hack”, but that’s probably a good thing.
3. Implement an API for changing component values, so that we maintain the abstraction of the “state” key holding the values
4. Can an Aspect represent a change in a component as well? This would finish simplifying the watchers…
5. Do we replace the default components when initializing an entity? Do I provide an API for replacing and an API for merging the passed in components and the default components?
6. The tick should send an event to the unified log, it shouldn’t just trigger a system. (wait, is this true? It would be if I did command-sourcing, buuuuuut?)
7. Spend some time with the Commander library and seeing if it’s a good fit for what I’m doing
8. Streamline API; if all changes come through Changesets, then Entity.add_component/2 doesn’t make sense unless it returns a Changeset.

ecstatic's Issues

New release anytime soon?

Are you planning on issuing a new release with some of the improvements over the past 2 years anytime soon?

Create :ecstatic OTP application instead of manually starting the Ecstatic.Supervisor

It would be a bit more normal if :ecstatic existed as an OTP application instead of having to start Ecstatic.Supervisor from the end-user application.

Make use of Ecstatic.Store configurable and extensible

Currently Ecstatic.Store.Ets is used directly in the code in several places. Instead we should use a wrapper module such as Ecstatic.Store which internally defers to a configurable storage module.

In this way, the user can implement with their own storage backend by implementing the Ecstatic.Store @behaviour in a given module, and then configuring that storage backend using Mix.Config

Write detailed documentation and provide useful and updated code examples

The title says it all, right now there aren't really any useful explanations or code examples in the hexdocs and generally figuring out how to use Ecstatic is rather akin to reading Egyptian hieroglyphics.

Write tests for important ECS use-cases

Need to update the test suite for the library such that we run through some key work-flows which represent:

• "Reactive" (change-event-driven) systems which trigger watchers for other Reactive systems
• "Non-Reactive" systems which update entities in an interval-based way
• Interactions between Reactive and Non-Reactive Systems.
• All sorts of different Watcher logic
• Different aspect logic in our Systems

Probably need to deal with even more subjects.

Add license text

Copyright 2018 Aldric Giacomoni

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Reactive systems should not trigger :tick messages for non-reactive systems

So currently the Ecstatic.Ticker logic works by attaching a watcher to :attached, :removed and :updated component lifecycle hooks. This is so that the Ecstatic.EventConsumer is the process which sends each individual :tick message.

In that way, I can ensure that each change is completely propagated through the system before another tick message is fired. If the Ecstatic.Ticker process sends itself tick messages it can go too fast and essentially it re-executes the same System logic over and over again, overloading the gen_stage message queue and not allowing the entity to be updated.

What I need to do here is make it so that other reactive Ecstatic.System don't also trigger unwanted :tick messages for non-reactive Ecstatic.System, when are both are watching and updating the same Ecstatic.Component type.

Simplify Watcher application config syntax

So currently the watcher configuration line looks rather like this:

config :ecstatic, :watchers, fn() -> PhysicsSim.Watchers.watchers end

And I think it might be much simpler to represent it like this:

config :ecstatic, :watchers, [PhysicsSim.Watchers]

...and then internally have Ecstatic concatenate all of the watchers from each module together (by calling watchers/0 on each)