What is it?

ECS Lua is a fast and easy to use ECS (Entity Component System) engine for game development.

The basic idea of this pattern is to stop defining entities using a hierarchy of classes and start doing use of composition in a Data Oriented Programming paradigm. (More information on Wikipedia). Programming with an ECS can result in code that is more efficient and easier to extend over time.

How does it work?

Talk is cheap. Show me the code!

local World, System, Query, Component = ECS.World, ECS.System, ECS.Query, ECS.Component

local Health = Component(100)
local Position = Component({ x = 0, y = 0})

local isInAcid = Query.Filter(function()
   return true  -- it's wet season
end)

local InAcidSystem = System("process", Query.All( Health, Position, isInAcid() ))

function InAcidSystem:Update()
   for i, entity in self:Result():Iterator() do
      local health = entity[Health]
      health.value = health.value - 0.01
   end
end

local world = World({ InAcidSystem })

world:Entity(Position({ x = 5.0 }), Health())

Features

ECS Lua has no external dependencies and is compatible and tested with Lua 5.1, Lua 5.2, Lua 5.3, Lua 5.4, LuaJit and Roblox Luau

Game engine agnostic: It can be used in any engine that has the Lua scripting language.
Ergonomic: Focused on providing a simple yet efficient API
FSM: Finite State Machines in an easy and intuitive way
JobSystem: To running systems in parallel (through coroutines)
Reactive: Systems can be informed when an entity changes
Predictable:
- The systems will work in the order they were registered or based on the priority set when registering them.
- Reactive events do not generate a random callback when issued, they are executed at a predefined step.

Goal

To be a lightweight, simple, ergonomic and high-performance ECS library that can be easily extended. The ECS Lua does not strictly follow "pure ECS design".

Usage

Read our Full Documentation to learn how to use ECS Lua.

Get involved

All kinds of contributions are welcome!

🐛 Found a bug?
Let me know by creating an issue.

❓ Have a question?
Roblox DevForum is a good place to start.

⚙️ Interested in fixing a bug or adding a feature?
Check out the contributing guidelines.

📖 Can we improve our documentation?
Pull requests even for small changes can be helpful. Each page in the docs can be edited by clicking the "Edit on GitHub" link at the bottom right.

License

This code is distributed under the terms and conditions of the MIT license.

nidorx/ecs-lua