ukendio / jecs

Just an ECS

jecs is a stupidly fast Entity Component System (ECS).

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

Example

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

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

125 archetypes, 4 random components queried. Can be found under /benches/query.lua

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

jecs's Issues

WildCards

Queries should be able to have wildcard terms that can match multiple instances of a relationship

World.target should have index parameter

jecs/lib/init.lua

Line 376 in 6c2f47b

-- TODO:

Move this into world constructor

		--TODO: Move this into world constructor

jecs/lib/init.lua

Line 277 in 517dbb9

local ROOT_ARCHETYPE = world.ROOT_ARCHETYPE

should traverse linked component records to pairs including entityId

	-- TODO: should traverse linked component records to pairs including entityId

jecs/lib/init.lua

Line 438 in 6c2f47b

archetypeDelete(world, entityId)

Better documentation needed

We need to add comprehensive documentation to our GitHub repository to help new contributors understand the project, its structure, and how to contribute. Proper documentation will also assist users in understanding how to use the project effectively.

Documentation should include:

1. Overview

   • Brief description of the project.
   • Key features and functionalities.

2. Installation

   • Prerequisites.
   • Step-by-step installation guide.
   • Configuration instructions.

3. Usage

   • How to run the project.
   • Basic usage examples.
   • Explanation of main components.

4. Contributing

   • Contribution guidelines.
   • How to report issues.
   • How to submit pull requests.
   • Code of conduct.

5. FAQs

   • Common issues and troubleshooting.
   • Frequently asked questions.

6. License

   • Licensing information.

Additional Notes:

• Use Markdown for documentation.
• Include images/screenshots where applicable.
• Ensure the documentation is easy to navigate and well-organized.

Tasks:

• Create an overview section.
• Write installation instructions.
• Provide usage examples.
• Draft contributing guidelines.
• Compile FAQs.
• Add license information.

[v0.1.0] Iterating `world` after calling `world:delete(entityId)` throws an error

When an entity is deleted, World.__iter tries getting the archetype of a non-existent sparse array record.

local world = jecs.World.new()

local entity = world:entity()

world:delete(entity)

for e in world do -- jecs:839: attempt to index nil with 'archetype' 
	
end

Type Declarations Files for Typescript

https://roblox-ts.com/docs/guides/using-existing-luau

Cached Iterator

A lot of the computations in the queries are very expensive, e.g. populating the compatible archetypes in the world, caching indices to the the columns and unpacking the entity ID's for flags + low and high IDs for indexing and relations.

All of this overhead can be paid once up front for each system. This similar to how Matter's runtime queries work right now.

World.target should have index parameter

jecs/lib/init.lua

Line 376 in 6c2f47b

-- TODO:

More unit tests needed!

The coverage over the codebase is pretty poor and a lot of potential edge cases have not been found yet. This is something we can add incrementally!

Sparse Components (non-movable components)

Non-movable components, that when inserted goes into the sparse set storage. The sparse component itself does not need to be moved to the destination archetype during insertion.

Benefits

• Doesn't need to move the sparse component itself so slightly faster removals and insertions
• Fast iteration of single sparse components since it should just iterate over the densely packed pool/column

Drawbacks

• Explicit storage specification
• Queries of sparse components are always slower than archetype queries except for two scenarios:

1. if the query is just interested in a single sparse component (just iterate the dense array of the sparse set)
2. if fragmentation is very high (like 1-2 entities per archetype, and lots of archetypes)