ECSx is an Entity-Component-System (ECS) framework for Elixir. ECS is an architecture for building real-time games and simulations, wherein data about Entities is stored in small fragments called Components, which are then read and updated by Systems.
:ecsx
to the list of dependencies in mix.exs
:def deps do
[
{:ecsx, "~> 0.5"}
]
end
mix deps.get
mix ecsx.setup
While ECSx is pre-v1.0, minor version updates will contain breaking changes. If you are upgrading an application from ECSx 0.4.x or earlier, please refer to our upgrade guide.
Building a ship combat engine with ECSx in a Phoenix app
Note: This tutorial project is a work-in-progress
Everything in your application is an Entity, but in ECS you won't work with these Entities directly - instead you will work with the individual attributes that an Entity might have. These attributes are given to an Entity by creating a Component, which holds, at minimum, the Entity's unique ID, but also can store a value. For example:
entity_id
e.g. 123
123
is blue, we give it a Color
Component with value "blue"
Direction
Component with value "west"
and a Speed
Component with value 60
XCoordinate
and YCoordinate
to locate it on the mapOnce your Entities are modeled using Components, you'll create Systems to operate on them. For example:
Speed
Components should have their locations regularly updated according to the speed and directionMove
System which reads the Speed
and Direction
Components, calculates how far the car has moved since the last server tick, and updates the Entity's XCoordinate
and/or YCoordinate
Component accordingly.Speed
ComponentECSx comes with generators to quickly create new Components or Systems:
mix ecsx.gen.component
mix ecsx.gen.system
Every ECSx application requires a Manager module, where valid Component types and Systems are declared, as well as the setup to spawn world objects before any players join. This module is created for you during mix ecsx.setup
and will be automatically updated by the other generators.
It is especially important to consider the order of your Systems list. The manager will run each System one at a time, in order.
Components are not persisted by default. To persist an entity, use the persist: true
option when adding the component. The default adapter for persistence is the ECSx.Persistence.FileAdapter, which stores the components in a binary file. The adapter can be changed using the persistence_adapter
application variable:
config :ecsx,
...
persistence_adapter: ...
Currently available Persistence Adapters (see links for installation/configuration instructions):
Copyright (C) 2022 Andrew P Berrien
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.