README.org

* 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`:


#+BEGIN_SRC elixir
def deps do
  [{:ecstatic, "~> 0.1.0"}]
end
#+END_SRC

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

#+BEGIN_SRC elixir
  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
#+END_SRC

* TODO
1. 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.
2. Implement an API for changing component values, so that we maintain the abstraction of the "state" key holding the values
3. Can an Aspect represent a change in a component as well? This would finish simplifying the watchers...
4. 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?
5. 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?)
6. Spend some time with the Commander library and seeing if it's a good fit for what I'm doing
7. Streamline API; if all changes come through Changesets, then =Entity.add_component/2= doesn't make sense unless it returns a Changeset.