Docs addons (#112)

* Fix indentations

* Add addons page

* Fix indent

docs/.vitepress/config.mts

@@ -38,7 +38,8 @@ export default defineConfig({
                         { text: 'Entities and Components', link: '/learn/concepts/entities-and-components' },
                         { text: 'Queries', link: '/learn/concepts/queries' },
                         { text: 'Relationships', link: '/learn/concepts/relationships' },
-                        { text: 'Builtin Component Traits', link: 'learn/concepts/builtin-component-traits' }
+                        { text: 'Component Traits', link: 'learn/concepts/component-traits' },
+                        { text: 'Addons', link: '/learn/addons' }
                     ]
                 },
                 {

docs/learn/concepts/addons.md

@@ -0,0 +1,16 @@
+# Addons
+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]()!
+
+# Debuggers
+
+## [jabby](https://github.com/alicesaidhi/jabby)
+
+A jecs debugger with a string-based query language and entity editing capabilities.
+
+# Schedulers
+
+## [sapphire-jecs](https://github.com/Mark-Marks/sapphire/tree/main/crates/sapphire-jecs)
+
+A batteries-included [sapphire](https://github.com/mark-marks/sapphire) scheduler for jecs
+
+This page takes wording and terminology directly from Bevy's [assets page](https://bevyengine.org/assets/)

docs/learn/concepts/component-traits.md

@@ -1,10 +1,49 @@
-# Builtin 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. This manual contains an overview of all component traits supported by Jecs.
+# Component
+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.
+
+# Hooks
+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.
+
+## Examples
+::: code-group
+
+```luau [luau]
+local Transform= world:component()
+world:set(Transform, OnAdd, function(entity)
+    -- A transform component has been added to an entity
+end)
+world:set(Transform, OnRemove, function(entity)
+    -- A transform component has been removed from the entity
+end)
+world:set(Transform, OnSet, function(entity, value)
+    -- A transform component has been assigned/changed to value on the entity
+end)
+```
+
+```typescript [typescript]
+
+const Transform = world.component()
+world.set(Transform, OnAdd, (entity) => {
+    // A transform component has been added to an entity
+})
+world.set(Transform, OnRemove, (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.
 
 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.
@@ -24,11 +63,9 @@ There are two cleanup conditions:
 - `OnDeleteTarget`: a target used with the relationship is deleted
 
 ## Examples
-
 The following examples show how to use cleanup traits
 
 ### (OnDelete, Remove)
-
 ::: code-group
 
 ```luau [luau]
@@ -83,7 +120,6 @@ world.delete(Archer)
 :::
 
 ### (OnDeleteTarget, Delete)
-
 ::: code-group
 
 ```luau [luau]

src/init.luau

@@ -272,7 +272,8 @@ local function hash(arr: { number }): string
 	return table.concat(arr, "_")
 end
 
-local world_get: (world: World, entityId: i53, a: i53, b: i53?, c: i53?, d: i53?, e: i53?) -> (...any)
+local world_get: (world: World, entityId: i53,
+    a: i53, b: i53?, c: i53?, d: i53?, e: i53?) -> ...any
 do
 	-- Keeping the function as small as possible to enable inlining
 	local records
@@ -289,7 +290,9 @@ do
 		return columns[tr.column][row]
 	end
 
-    function world_get(world: World, entity: i53, a: i53, b: i53?, c: i53?, d: i53?, e: i53?): ...any
+	function world_get(world: World, entity: i53,
+	    a: i53, b: i53?, c: i53?, d: i53?, e: i53?): ...any
+
 		local record = world.entityIndex.sparse[entity]
 		if not record then
 			return nil
@@ -401,7 +404,9 @@ end
 -- TODO:
 -- should have an additional `nth` parameter which selects the nth target
 -- this is important when an entity can have multiple relationships with the same target
-local function world_target(world: World, entity: i53, relation: i24--[[, nth: number]]): i24?
+local function world_target(world: World, entity: i53,
+    relation: i24--[[, nth: number]]): i24?
+
 	local record = world.entityIndex.sparse[entity]
 	local archetype = record.archetype
 	if not archetype then
@@ -421,10 +426,7 @@ local function world_target(world: World, entity: i53, relation: i24--[[, nth: n
 	return ecs_pair_second(world, archetype.types[tr.column])
 end
 
-local function id_record_ensure(
+local function id_record_ensure(world: World, id: number): ArchetypeMap
-    world: World,
-	id: number
-): ArchetypeMap
 	local componentIndex = world.componentIndex
 	local idr = componentIndex[id]
 
@@ -433,8 +435,7 @@ local function id_record_ensure(
 		local relation = ECS_ENTITY_T_HI(id)
 
 		local cleanup_policy = world_target(world, relation, EcsOnDelete)
-		local cleanup_policy_target = world_target(world, relation,
+		local cleanup_policy_target = world_target(world, relation, EcsOnDeleteTarget)
-		    EcsOnDeleteTarget)
 
 		if cleanup_policy == EcsDelete or cleanup_policy_target == EcsDelete then
 			flags = bit32.bor(flags, ECS_ID_DELETE)
@@ -457,7 +458,7 @@ local function id_record_ensure(
 		idr = {
 			size = 0,
 			cache = {},
-			flags = flags
+			flags = flags,
 		} :: ArchetypeMap
 		componentIndex[id] = idr
 	end
@@ -754,16 +755,16 @@ local function world_clear(world: World, entity: i53)
 	entity_move(world.entityIndex, entity, record, ROOT_ARCHETYPE)
 end
 
-local function archetype_fast_delete_last(columns, column_count,
+local function archetype_fast_delete_last(columns: { Column },
-    types, entity)
+    column_count: number, types: { i53 }, entity: i53)
 
 	for i, column in columns do
 		column[column_count] = nil
 	end
 end
 
-local function archetype_fast_delete(columns, column_count,
+local function archetype_fast_delete(columns: { Column },
-    row, types, entity)
+    column_count: number, row, types, entity)
 
 	for i, column in columns do
 		column[row] = column[column_count]
@@ -771,8 +772,6 @@ local function archetype_fast_delete(columns, column_count,
 	end
 end
 
-local ERROR_DELETE_PANIC = "Tried to delete entity that has (OnDelete, Panic)"
-
 local function archetype_delete(world: World,
     archetype: Archetype, row: number)
 
@@ -802,14 +801,11 @@ local function archetype_delete(world: World,
 	end
 
 	if row == last then
-        archetype_fast_delete_last(columns,
+		archetype_fast_delete_last(columns, column_count, types, delete)
-            column_count, types, delete)
 	else
-        archetype_fast_delete(columns, column_count,
+		archetype_fast_delete(columns, column_count, row, types, delete)
-            row, types, delete)
 	end
 
-
 	local component_index = world.componentIndex
 	local archetypes = world.archetypes
 
@@ -933,8 +929,7 @@ end
 
 type CompatibleArchetype = { archetype: Archetype, indices: { number } }
 
-local function noop()
+local function noop() end
-end
 
 local function Arm(query, ...)
 	return query
@@ -1322,7 +1317,7 @@ do
 			return query
 		end
 
-        local function world_query_replace(query, fn: (...any) -> (...any))
+		local function world_query_replace(query, fn: (...any) -> ...any)
 			query_init(query)
 
 			for i, archetype in compatible_archetypes do
@@ -1351,15 +1346,13 @@ do
 						local vc = columns[records[C].column]
 						local vd = columns[records[D].column]
 
-             			va[row], vb[row], vc[row], vd[row] = fn(
+						va[row], vb[row], vc[row], vd[row] = fn(va[row], vb[row], vc[row], vd[row])
-             			    va[row], vb[row], vc[row], vd[row])
 					else
 						for j, id in ids do
 							local tr = records[id]
 							queryOutput[j] = columns[tr.column][row]
 						end
-             			world_query_replace_values(row, columns,
+						world_query_replace_values(row, columns, fn(unpack(queryOutput)))
-                            fn(unpack(queryOutput)))
 					end
 				end
 			end
@@ -1430,7 +1423,7 @@ do
 			with = world_query_with,
 			without = world_query_without,
 			replace = world_query_replace,
-            archetypes = world_query_archetypes
+			archetypes = world_query_archetypes,
 		} :: any
 
 		setmetatable(it, it)
@@ -1478,8 +1471,7 @@ function World.new()
 		entity_index_new_id(self.entityIndex, i)
 	end
 
-	world_add(self, EcsChildOf,
+	world_add(self, EcsChildOf, ECS_PAIR(EcsOnDeleteTarget, EcsDelete))
-	   ECS_PAIR(EcsOnDeleteTarget, EcsDelete))
 
 	return self
 end
@@ -1495,14 +1487,14 @@ export type Entity<T = nil> = number & {__T: T }
 type Iter<T...> = (query: Query<T...>) -> () -> (Entity, T...)
 
 type Query<T...> = typeof(setmetatable({}, {
-    __iter = (nil :: any) :: Iter<T...>
+	__iter = (nil :: any) :: Iter<T...>,
 })) & {
 	iter: Iter<T...>,
 	next: Item<T...>,
 	drain: (self: Query<T...>) -> Query<T...>,
 	with: (self: Query<T...>, ...i53) -> Query<T...>,
 	without: (self: Query<T...>, ...i53) -> Query<T...>,
-    replace: (self: Query<T...>, <U...>(T...) -> (U...)) -> (),
+	replace: (self: Query<T...>, <U...>(T...) -> U...) -> (),
 	archetypes: () -> { Archetype },
 }