docs/learn/concepts/addons.md

@@ -1,23 +1,16 @@
-# Addons
+# Assets
-
+A collection of third-party jecs assets made by the community. If you would like to share what you're working on, [submit a pull request](https://github.com/Ukendio/jecs)!
-A collection of third-party jecs addons made by the community. If you would like to share what you're working on, [submit a pull request](https://github.com/Ukendio/jecs)!
+
-
+# Debuggers
-# Debuggers
+## [jabby](https://github.com/alicesaidhi/jabby)
-
+A jecs debugger with a string-based query language and entity editing capabilities.
-## [jabby](https://github.com/alicesaidhi/jabby)
+
-
+# Schedulers
-A jecs debugger with a string-based query language and entity editing capabilities.
+## [lockstep scheduler](https://gist.github.com/1Axen/6d4f78b3454cf455e93794505588354b)
-
+A simple fixed step system scheduler.
-# Schedulers
+
-
+## [sapphire-jecs](https://github.com/Mark-Marks/sapphire/tree/main/crates/sapphire-jecs)
-## [lockstep scheduler](https://gist.github.com/1Axen/6d4f78b3454cf455e93794505588354b)
+A batteries-included [sapphire](https://github.com/mark-marks/sapphire) scheduler for jecs
-
+
-A simple fixed step system scheduler.
+## [jam](https://github.com/revvy02/Jam)
-
+Provides hooks and a scheduler that implements jabby and a topographical runtime
-## [rubine](https://github.com/Mark-Marks/rubine)
-
-An ergonomic, runtime agnostic scheduler for Jecs
-
-## [jam](https://github.com/revvy02/Jam)
-
-Provides hooks and a scheduler that implements jabby and a topographical runtime

docs/learn/concepts/component-traits.md

@@ -1,185 +1,150 @@
-# Component Traits
+# Component Traits
-
+Component traits are IDs and pairs that can be added to components to modify their behavior. Although it is possible to create custom traits, this manual only contains an overview of all builtin component traits supported by Jecs.
-Component traits are IDs and pairs that can be added to components to modify their behavior. Although it is possible to create custom traits, this manual only contains an overview of all builtin component traits supported by Jecs.
+
-
+# Component
-# Component
+Every (component) ID comes with a `Component` which helps with the distinction between normal entities and component IDs.
-
+
-Every (component) ID comes with a `Component` which helps with the distinction between normal entities and component IDs.
+# Tag
-
+A (component) ID can be marked with `Tag´ in which the component will never contain any data. This allows for zero-cost components which improves performance for structural changes.
-# Tag
+
-
+# Hooks
-A (component) ID can be marked with `Tag´ in which the component will never contain any data. This allows for zero-cost components which improves performance for structural changes.
+Hooks are part of the "interface" of a component. You could consider hooks as the counterpart to OOP methods in ECS. They define the behavior of a component, but can only be invoked through mutations on the component data. You can only configure a single `OnAdd`, `OnRemove` and `OnSet` hook per component, just like you can only have a single constructor and destructor.
-
+
-# Hooks
+## Examples
-
+::: code-group
-Hooks are part of the "interface" of a component. You could consider hooks as the counterpart to OOP methods in ECS. They define the behavior of a component, but can only be invoked through mutations on the component data. You can only configure a single `OnAdd`, `OnRemove` and `OnSet` hook per component, just like you can only have a single constructor and destructor.
+
-
+```luau [luau]
-## Examples
+local Transform= world:component()
-
+world:set(Transform, OnAdd, function(entity)
-::: code-group
+    -- A transform component has been added to an entity
-
+end)
-```luau [luau]
+world:set(Transform, OnRemove, function(entity)
-local Transform= world:component()
+    -- A transform component has been removed from the entity
-world:set(Transform, OnAdd, function(entity)
+end)
-    -- A transform component has been added to an entity
+world:set(Transform, OnSet, function(entity, value)
-end)
+    -- A transform component has been assigned/changed to value on the entity
-world:set(Transform, OnRemove, function(entity)
+end)
-    -- A transform component has been removed from the entity
+```
-end)
+
-world:set(Transform, OnSet, function(entity, value)
+```typescript [typescript]
-    -- A transform component has been assigned/changed to value on the entity
+
-end)
+const Transform = world.component()
-```
+world.set(Transform, OnAdd, (entity) => {
-
+    // A transform component has been added to an entity
-```typescript [typescript]
+})
-const Transform = world.component();
+world.set(Transform, OnRemove, (entity) => {
-world.set(Transform, OnAdd, (entity) => {
+    // A transform component has been removed from the entity
-	// A transform component has been added to an entity
+})
-});
+world.set(Transform, OnSet, (entity, value) => {
-world.set(Transform, OnRemove, (entity) => {
+    // A transform component has been assigned/changed to value on the entity
-	// A transform component has been removed from the entity
+})
-});
+
-world.set(Transform, OnSet, (entity, value) => {
+```
-	// A transform component has been assigned/changed to value on the entity
+
-});
+:::
-```
+
-
+# Cleanup Traits
-:::
+When entities that are used as tags, components, relationships or relationship targets are deleted, cleanup traits ensure that the store does not contain any dangling references. Any cleanup policy provides this guarantee, so while they are configurable, games cannot configure traits that allows for dangling references.
-
+
-# Cleanup Traits
+We also want to specify this per relationship. If an entity has `(Likes, parent)` we may not want to delete that entity, meaning the cleanup we want to perform for `Likes` and `ChildOf` may not be the same.
-
+
-When entities that are used as tags, components, relationships or relationship targets are deleted, cleanup traits ensure that the store does not contain any dangling references. Any cleanup policy provides this guarantee, so while they are configurable, games cannot configure traits that allows for dangling references.
+This is what cleanup traits are for: to specify which action needs to be executed under which condition. They are applied to entities that have a reference to the entity being deleted: if I delete the `Archer` tag I remove the tag from all entities that have it.
-
+
-We also want to specify this per relationship. If an entity has `(Likes, parent)` we may not want to delete that entity, meaning the cleanup we want to perform for `Likes` and `ChildOf` may not be the same.
+To configure a cleanup policy for an entity, a `(Condition, Action)` pair can be added to it. If no policy is specified, the default cleanup action (`Remove`) is performed.
-
+
-This is what cleanup traits are for: to specify which action needs to be executed under which condition. They are applied to entities that have a reference to the entity being deleted: if I delete the `Archer` tag I remove the tag from all entities that have it.
+There are two cleanup actions:
-
+
-To configure a cleanup policy for an entity, a `(Condition, Action)` pair can be added to it. If no policy is specified, the default cleanup action (`Remove`) is performed.
+- `Remove`: removes instances of the specified (component) id from all entities (default)
-
+- `Delete`: deletes all entities with specified id
-There are two cleanup actions:
+
-
+There are two cleanup conditions:
--   `Remove`: removes instances of the specified (component) id from all entities (default)
+
--   `Delete`: deletes all entities with specified id
+- `OnDelete`: the component, tag or relationship is deleted
-
+- `OnDeleteTarget`: a target used with the relationship is deleted
-There are two cleanup conditions:
+
-
+## Examples
--   `OnDelete`: the component, tag or relationship is deleted
+The following examples show how to use cleanup traits
--   `OnDeleteTarget`: a target used with the relationship is deleted
+
-
+### (OnDelete, Remove)
-## Examples
+::: code-group
-
+
-The following examples show how to use cleanup traits
+```luau [luau]
-
+local Archer = world:component()
-### (OnDelete, Remove)
+world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
-
+
-::: code-group
+local e = world:entity()
-
+world:add(e, Archer)
-```luau [luau]
+
-local Archer = world:component()
+-- This will remove Archer from e
-world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
+world:delete(Archer)
-
+```
-local e = world:entity()
+
-world:add(e, Archer)
+```typescript [typescript]
-
+const Archer = world.component()
--- This will remove Archer from e
+world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
-world:delete(Archer)
+
-```
+const e = world:entity()
-
+world.add(e, Archer)
-```typescript [typescript]
+
-const Archer = world.component();
+// This will remove Archer from e
-world.add(Archer, pair(jecs.OnDelete, jecs.Remove));
+world.delete(Archer)
-
+```
-const e = world.entity();
+
-world.add(e, Archer);
+:::
-
+
-// This will remove Archer from e
+### (OnDelete, Delete)
-world.delete(Archer);
+::: code-group
-```
+
-
+```luau [luau]
-:::
+local Archer = world:component()
-
+world:add(Archer, pair(jecs.OnDelete, jecs.Delete))
-### (OnDelete, Delete)
+
-
+local e = world:entity()
-::: code-group
+world:add(e, Archer)
-
+
-```luau [luau]
+-- This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
-local Archer = world:component()
+world:delete(Archer)
-world:add(Archer, pair(jecs.OnDelete, jecs.Delete))
+```
-
+
-local e = world:entity()
+```typescript [typescript]
-world:add(e, Archer)
+const Archer = world.component()
-
+world.add(Archer, pair(jecs.OnDelete, jecs.Delete))
--- This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
+
-world:delete(Archer)
+const e = world:entity()
-```
+world.add(e, Archer)
-
+
-```typescript [typescript]
+// This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
-const Archer = world.component();
+world.delete(Archer)
-world.add(Archer, pair(jecs.OnDelete, jecs.Delete));
+```
-
+
-const e = world.entity();
+:::
-world.add(e, Archer);
+
-
+### (OnDeleteTarget, Delete)
-// This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
+::: code-group
-world.delete(Archer);
+
-```
+```luau [luau]
-
+local ChildOf = world:component()
-:::
+world:add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete))
-
+
-### (OnDeleteTarget, Remove)
+local parent = world:entity()
-
+local child = world:entity()
-::: code-group
+world:add(child, pair(ChildOf, parent))
-
+
-```luau [luau]
+-- This will delete both parent and child
-local OwnedBy = world:component()
+world:delete(parent)
-world:add(OwnedBy, pair(jecs.OnDeleteTarget, jecs.Remove))
+```
-local loot = world:entity()
+
-local player = world:entity()
+```typescript [typescript]
-world:add(loot, pair(OwnedBy, player))
+const Archer = world.component()
-
+world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
--- This will remove (OwnedBy, player) from loot
+
-world:delete(player)
+const e = world:entity()
-```
+world.add(e, Archer)
-
+
-```typescript [typescript]
+// This will delete e
-const OwnedBy = world.component();
+world.delete(Archer)
-world.add(OwnedBy, pair(jecs.OnDeleteTarget, jecs.Remove));
+```
-const loot = world.entity();
+
-const player = world.entity();
+:::
-world.add(loot, pair(OwnedBy, player));
+
-
+This page takes wording and terminology directly from Flecs [documentation](https://www.flecs.dev/flecs/md_docs_2ComponentTraits.html)
-// This will remove (OwnedBy, player) from loot
-world.delete(player);
-```
-
-### (OnDeleteTarget, Delete)
-
-::: code-group
-
-```luau [luau]
-local ChildOf = world:component()
-world:add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete))
-
-local parent = world:entity()
-local child = world:entity()
-world:add(child, pair(ChildOf, parent))
-
--- This will delete both parent and child
-world:delete(parent)
-```
-
-```typescript [typescript]
-const ChildOf = world.component();
-world.add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete));
-
-const parent = world.entity();
-const child = world.entity();
-world.add(child, pair(ChildOf, parent));
-
-// This will delete both parent and child
-world.delete(parent);
-```
-
-:::
-
-This page takes wording and terminology directly from Flecs [documentation](https://www.flecs.dev/flecs/md_docs_2ComponentTraits.html)

docs/learn/concepts/entities-and-components.md

@@ -1,140 +1,113 @@
-# Entities and Components
+# Entities and Components
-
+
-## Entities
+## Entities
-
+Entities represent things in a game. In a game there may be entities of characters, buildings, projectiles, particle effects etc.
-Entities represent things in a game. In a game there may be entities of characters, buildings, projectiles, particle effects etc.
+
-
+By itself, an entity is just an unique identifier without any data
-By itself, an entity is just an unique identifier without any data
+
-
+## Components
-## Components
+A component is something that is added to an entity. Components can simply tag an entity ("this entity is an `Npc`"), attach data to an entity ("this entity is at `Position` `Vector3.new(10, 20, 30)`") and create relationships between entities ("bob `Likes` alice") that may also contain data ("bob `Eats` `10` apples").
-
+
-A component is something that is added to an entity. Components can simply tag an entity ("this entity is an `Npc`"), attach data to an entity ("this entity is at `Position` `Vector3.new(10, 20, 30)`") and create relationships between entities ("bob `Likes` alice") that may also contain data ("bob `Eats` `10` apples").
+### Operations
-
+Operation | Description
-## Operations
+----------|------------
-
+`get`     | Get a specific component or set of components from an entity.
-| Operation | Description                                                                                    |
+`add`     | Adds component to an entity. If entity already has the component, `add` does nothing.
-| --------- | ---------------------------------------------------------------------------------------------- |
+`set`     | Sets the value of a component for an entity. `set` behaves as a combination of `add` and `get`
-| `get`     | Get a specific component or set of components from an entity.                                  |
+`remove`  | Removes component from entity. If entity doesn't have the component, `remove` does nothing.
-| `add`     | Adds component to an entity. If entity already has the component, `add` does nothing.          |
+`clear`   | Remove all components from an entity. Clearing is more efficient than removing one by one.
-| `set`     | Sets the value of a component for an entity. `set` behaves as a combination of `add` and `get` |
+
-| `remove`  | Removes component from entity. If entity doesn't have the component, `remove` does nothing.    |
+### Components are entities
-| `clear`   | Remove all components from an entity. Clearing is more efficient than removing one by one.     |
+
-
+In an ECS, components need to be uniquely identified. In Jecs this is done by making each component its own unique entity. If a game has a component Position and Velocity, there will be two entities, one for each component. Component entities can be distinguished from "regular" entities as they have a `Component` component. An example:
-## Components are entities
+
-
+::: code-group
-In an ECS, components need to be uniquely identified. In Jecs this is done by making each component its own unique entity. If a game has a component Position and Velocity, there will be two entities, one for each component. Component entities can be distinguished from "regular" entities as they have a `Component` component. An example:
+
-
+```luau [luau]
-::: code-group
+local Position = world:component() :: jecs.Entity<Vector3>
-
+print(world:has(Position, Jecs.Component))
-```luau [luau]
+```
-local Position = world:component() :: jecs.Entity<Vector3>
+
-print(world:has(Position, jecs.Component))
+```typescript [typescript]
-```
+const Position = world.component<Vector3>();
-
+print(world.has(Position, Jecs.Component))
-```typescript [typescript]
+```
-const Position = world.component<Vector3>();
+
-print(world.has(Position, jecs.Component));
+:::
-```
+
-
+All of the APIs that apply to regular entities also apply to component entities. This means it is possible to contexualize components with logic by adding traits to components
-:::
+
-
+::: code-group
-All of the APIs that apply to regular entities also apply to component entities. This means it is possible to contexualize components with logic by adding traits to components
+
-
+```luau [luau]
-::: code-group
+local Networked = world:component()
-
+local Type = world:component()
-```luau [luau]
+local Name = world:component()
-local Networked = world:component()
+local Position = world:component() :: jecs.Entity<Vector3>
-local Type = world:component()
+world:add(Position, Networked)
-local Name = world:component()
+world:set(Position, Name, "Position")
-local Position = world:component() :: jecs.Entity<Vector3>
+world:set(Position, Type, { size = 12, type = "Vector3" } ) -- 12 bytes to represent a Vector3
-world:add(Position, Networked)
+
-world:set(Position, Name, "Position")
+for id, ty, name in world:query(Type, Name):with(Networked) do
-world:set(Position, Type, { size = 12, type = "Vector3" } ) -- 12 bytes to represent a Vector3
+    local batch = {}
-
+    for entity, data in world:query(id) do
-for id, ty, name in world:query(Type, Name, Networked) do
+        table.insert(batch, { entity = entity, data = data })
-    local batch = {}
+    end
-    for entity, data in world:query(id) do
+    -- entities are sized f64
-        table.insert(batch, { entity = entity, data = data })
+    local packet = buffer.create(#batch * (8 + ty.size))
-    end
+    local offset = 0
-    -- entities are sized f64
+    for _, entityData in batch do
-    local packet = buffer.create(#batch * (8 + ty.size))
+        offset+=8
-    local offset = 0
+        buffer.writef64(packet, offset, entityData.entity)
-    for _, entityData in batch do
+        if ty.type == "Vector3" then
-        offset+=8
+            local vec3 = entity.data :: Vector3
-        buffer.writef64(packet, offset, entityData.entity)
+            offset += 4
-        if ty.type == "Vector3" then
+            buffer.writei32(packet, offset, vec3.X)
-            local vec3 = entity.data :: Vector3
+            offset += 4
-            offset += 4
+            buffer.writei32(packet, offset, vec3.Y)
-            buffer.writei32(packet, offset, vec3.X)
+            offset += 4
-            offset += 4
+            buffer.writei32(packet, offset, vec3.Z)
-            buffer.writei32(packet, offset, vec3.Y)
+        end
-            offset += 4
+    end
-            buffer.writei32(packet, offset, vec3.Z)
+
-        end
+    updatePositions:FireServer(packet)
-    end
+end
-
+```
-    updatePositions:FireServer(packet)
+
-end
+```typescript [typescript]
-```
+const Networked = world.component()
-
+const Type = world.component()
-```typescript [typescript]
+const Name = world.component()
-const Networked = world.component();
+const Position = world.component<Vector3>();
-const Type = world.component();
+world.add(Position, Networked)
-const Name = world.component();
+world.set(Position, Name, "Position")
-const Position = world.component<Vector3>();
+world.set(Position, Type, { size: 12, type: "Vector3" } ) // 12 bytes to represent a Vector3
-world.add(Position, Networked);
+
-world.set(Position, Name, "Position");
+for (const [id, ty, name] of world.query(Type, Name).with(Networked)) {
-world.set(Position, Type, { size: 12, type: "Vector3" }); // 12 bytes to represent a Vector3
+    const batch = new Array<{ entity: Entity, data: unknown}>()
-
+
-for (const [id, ty, name] of world.query(Type, Name, Networked)) {
+    for (const [entity, data] of world.query(id)) {
-	const batch = new Array<{ entity: Entity; data: unknown }>();
+        batch.push({ entity, data })
-
+    }
-	for (const [entity, data] of world.query(id)) {
+    // entities are sized f64
-		batch.push({ entity, data });
+    const packet = buffer.create(batch.size() * (8 + ty.size))
-	}
+    const offset = 0
-	// entities are sized f64
+    for (const [_, entityData] of batch) {
-	const packet = buffer.create(batch.size() * (8 + ty.size));
+        offset+=8
-	const offset = 0;
+        buffer.writef64(packet, offset, entityData.entity)
-	for (const [_, entityData] of batch) {
+        if (ty.type == "Vector3") {
-		offset += 8;
+            const vec3 = entity.data as Vector3
-		buffer.writef64(packet, offset, entityData.entity);
+            offset += 4
-		if (ty.type == "Vector3") {
+            buffer.writei32(packet, offsetm, vec3.X)
-			const vec3 = entity.data as Vector3;
+            offset += 4
-			offset += 4;
+            buffer.writei32(packet, offset, vec3.Y)
-			buffer.writei32(packet, offsetm, vec3.X);
+            offset += 4
-			offset += 4;
+            buffer.writei32(packet, offset, vec3.Z)
-			buffer.writei32(packet, offset, vec3.Y);
+        }
-			offset += 4;
+    }
-			buffer.writei32(packet, offset, vec3.Z);
+
-		}
+    updatePositions.FireServer(packet)
-	}
+}
-
+```
-	updatePositions.FireServer(packet);
+
-}
+:::
-```
-
-:::
-
-## Singletons
-
-Singletons are components for which only a single instance
-exists on the world. They can be accessed on the
-world directly and do not require providing an entity.
-Singletons are useful for global game resources, such as
-game state, a handle to a physics engine or a network socket. An example:
-
-::: code-group
-
-```luau [luau]
-local TimeOfDay = world:component() :: jecs.Entity<number>
-world:set(TimeOfDay, TimeOfDay, 0.5)
-local t = world:get(TimeOfDay, TimeOfDay)
-```
-
-```typescript [typescript]
-const TimeOfDay = world.component<number>();
-world.set(TimeOfDay, TimeOfDay, 0.5);
-const t = world.get(TimeOfDay, TimeOfDay);
-```
-
-:::

docs/learn/concepts/queries.md

@@ -17,14 +17,14 @@ This manual contains a full overview of the query features available in Jecs. So
 ## Performance and Caching
 
 Understanding the basic architecture of queries helps to make the right tradeoffs when using queries in games.
+
 The biggest impact on query performance is whether a query is cached or not.
+
 This section goes over what caching is, how it can be used and when it makes sense to use it.
 
 ### Caching: what is it?
 
-Jecs is an archetype ECS, which means that entities with exactly the same components are
+Jecs is an archetype ECS, which means that entities with exactly the same components are grouped together in an "archetype". Archetypes are created on the fly whenever a new component combination is created in the ECS. For example:
-grouped together in an "archetype". Archetypes are created on the fly
-whenever a new component combination is created in the ECS. For example:
 
 :::code-group