Jecs

Just a Stupidly Fast Entity Component System

✨ Features

• 🚀 Blazing Fast: Iterate over 800,000 entities at 60 FPS
• 🔗 Entity Relationships: First-class support for entity relationships
• 📝 Type Safety: Fully typed Luau API
• 🎯 Zero Dependencies: Simple integration with no external dependencies
• ⚡ Optimized Storage: Cache-friendly archetype/SoA storage
• ✅ Battle-tested: Rigorously tested for stability

🚀 Example Usage

local world = jecs.World.new()
local pair = jecs.pair
local Position = world:component() :: jecs.Id<Vector3>
local Velocity = world:component() :: jecs.Id<Vector3>

-- These components and functions are actually already builtin
-- but have been illustrated for demonstration purposes
local ChildOf = world:component()
local Name = world:component()
local entity = world:entity()
world:set(entity, Position, Vector3.new(0, 0, 0))
world:set(entity, Velocity, Vector3.new(1, 0, 0))

local function parent(entity)
    return world:target(entity, ChildOf)
-- Update system (example)
for id, position, velocity in world:query(Position, Velocity) do
    world:set(id, Position, position + velocity)
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

⚡ Performance

Query Performance

21,000 entities, 125 archetypes, 4 random components queried: Benchmark source: /benches/visual/query.luau

Insertion Performance

Inserting 8 components to an entity and updating them over 50 times: Benchmark source: /benches/visual/insertions.luau

📖 Documentation

• Getting Started
• API Reference
• Examples
• Common Issues

🤝 Contributing

Please read our Contributing Guidelines before submitting pull requests.

💬 Community

• Join our Discord
• Report issues on GitHub

📄 License

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