jecs/README.md

Just a stupidly fast Entity Component System

• Entity Relationships as first class citizens
• Iterate 800,000 entities at 60 frames per second
• Type-safe Luau API
• Zero-dependency package
• Optimized for column-major operations
• Cache friendly archetype/SoA storage
• Rigorously unit tested for stability

Example

local world = jecs.World.new()
local pair = jecs.pair

-- These components and functions are actually already builtin
-- but have been illustrated for demonstration purposes
local ChildOf = world:component()
local Name = world:component()

local function parent(entity)
    return world:target(entity, ChildOf)
end
local function getName(entity)
    return world:get(entity, Name)
end

local alice = world:entity()
world:set(alice, Name, "alice")

local bob = world:entity()
world:add(bob, pair(ChildOf, alice))
world:set(bob, Name, "bob")

local sara = world:entity()
world:add(sara, pair(ChildOf, alice))
world:set(sara, Name, "sara")

print(getName(parent(sara)))

for e in world:query(pair(ChildOf, alice)) do
    print(getName(e), "is the child of alice")
end

-- Output
-- "alice"
-- bob is the child of alice
-- sara is the child of alice

21,000 entities 125 archetypes 4 random components queried. Can be found under /benches/visual/query.luau

Inserting 8 components to an entity and updating them over 50 times. Can be found under /benches/visual/insertions.luau

Installation

Using Wally

Add jecs to your wally.toml file:

[dependencies]
jecs = "ukendio/jecs@0.1.0"

Then run wally install in your project directory.

Manual Installation

Download the latest release from the releases page.

Documentation

For complete documentation, visit our documentation site.

Contributing

Contributions are welcome. Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.