Add assertion against existing idr

* Add component registration and metadata API

* Fix test case erroring

* Fix type issues

* Add component to hook calls' arguments

* Add is_tag function

* Allow focus to capture a single Test

* Add test cases for preregistered tags

.gitattributes

@@ -0,0 +1,2 @@
+*.luau                 text eol=lf
+*.html           linguist-vendored

.github/ISSUE_TEMPLATE/BUG-REPORT.md

@@ -1,22 +1,25 @@
----
-name: Bug report
-about: File a bug report for any behavior that you believe is unintentional or problematic
-title: "[BUG]"
-labels: bug
-assignees: ''
-
----
-
-## Describe the bug
-Put a clear and concise description of what the bug is. This should be short and to the point, not to exceed more than a paragraph. Put the details inside your reproduction steps.
-
-## Reproduction
-Make an easy-to-follow guide on how to reproduce it. Does it happen all the time? Will specific features affect reproduction? All these questions should be answered for a good issue.
-
-This is a good place to put rbxl files or scripts that help explain your reproduction steps.
-
-## Expected Behavior
-What you expect to happen
-
-## Actual Behavior
-What actually happens
+---
+name: Bug report
+about: File a bug report for any behavior that you believe is unintentional or problematic
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Describe the bug
+
+Put a clear and concise description of what the bug is. This should be short and to the point, not to exceed more than a paragraph. Put the details inside your reproduction steps.
+
+## Reproduction
+
+Make an easy-to-follow guide on how to reproduce it. Does it happen all the time? Will specific features affect reproduction? All these questions should be answered for a good issue.
+
+This is a good place to put rbxl files or scripts that help explain your reproduction steps.
+
+## Expected Behavior
+
+What you expect to happen
+
+## Actual Behavior
+
+What actually happens

.github/ISSUE_TEMPLATE/DOCUMENTATION.md

@@ -1,14 +1,15 @@
 ---
 name: Documentation
 about: Open an issue to add, change, or otherwise modify any part of the documentation.
-title: "[DOCS]"
+title: ""
 labels: documentation
-assignees: ''
-
+assignees: ""
 ---
 
 ## Which Sections Does This Issue Cover?
+
 [Put sections (e.g. Query Concepts), page links, etc as necessary]
 
 ## What Needs To Change?
-What specifically needs to change and what suggestions do you have to change it?
+
+What specifically needs to change and what suggestions do you have to change it?

.github/ISSUE_TEMPLATE/FEATURE-REQUEST.md

@@ -1,27 +1,27 @@
----
-name: Feature Request
-about: File a feature request for something you believe should be added to Jecs
-title: "[FEATURE]"
-labels: enhancement
-assignees: ''
-
----
-
-## Describe your Feature
-
-You should explain your feature here, and the motivation for why you want it.
-
-## Implementation
-
-Explain how you would implement your feature here. Provide relevant API examples and such here (if applicable).
-
-## Alternatives
-
-What other alternative implementations or otherwise relevant information is important to why you decided to go with this specific implementation?
-
-## Considerations
-
-Some questions that need to be answered include the following:
-- Will old code break in response to this feature?
-- What are the performance impacts with this feature (if any)?
-- How is it useful to include?
+---
+name: Feature Request
+about: File a feature request for something you believe should be added to Jecs
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Describe your Feature
+
+You should explain your feature here, and the motivation for why you want it.
+
+## Implementation
+
+Explain how you would implement your feature here. Provide relevant API examples and such here (if applicable).
+
+## Alternatives
+
+What other alternative implementations or otherwise relevant information is important to why you decided to go with this specific implementation?
+
+## Considerations
+
+Some questions that need to be answered include the following:
+
+- Will old code break in response to this feature?
+- What are the performance impacts with this feature (if any)?
+- How is it useful to include?

.github/workflows/analysis.yaml

@@ -12,7 +12,7 @@ jobs:
               uses: actions/checkout@v4
 
             - name: Install Luau
-              uses: encodedvenom/install-luau@v2.1
+              uses: encodedvenom/install-luau@v4.3
 
             - name: Analyze
               run: |

.github/workflows/unit-testing.yaml

@@ -15,7 +15,7 @@ jobs:
             - name: Install Luau
               uses: encodedvenom/install-luau@v4.3
               with:
-                  version: "latest"
+                  version: "0.667"
                   verbose: "true"
 
             - name: Run Unit Tests

.gitignore

@@ -64,5 +64,10 @@ drafts/
 .vitepress/dist
 
 # Luau tools
-/tools
 profile.*
+
+# Patch files
+
+*.patch
+
+genhtml.perl

.luaurc

@@ -1,8 +1,10 @@
 {
     "aliases": {
         "jecs": "jecs",
-        "testkit": "test/testkit",
-        "mirror": "mirror"
+        "testkit": "tools/testkit",
+        "mirror": "mirror",
+        "tools": "tools",
+        "addons": "addons"
     },
     "languageMode": "strict"
 }

.stylua.toml

@@ -1,11 +1,9 @@
-column_width = 120
-line_endings = "Unix"
-indent_type = "Tabs"
-indent_width = 4
-quote_style = "ForceDouble"
-call_parentheses = "Always"
-collapse_simple_statement = "Never"
-syntax = "Luau"
-
-[sort_requires]
-enabled = true
+syntax = "All"
+column_width = 120
+line_endings = "Unix"
+indent_type = "Tabs"
+indent_width = 4
+quote_style = "AutoPreferDouble"
+call_parentheses = "Always"
+space_after_function_names = "Never"
+collapse_simple_statement = "Never"

CHANGELOG.md

@@ -11,28 +11,48 @@ The format is based on [Keep a Changelog][kac], and this project adheres to
 ## [Unreleased]
 
 -   `[world]`:
-    -   16% faster `world:get`
--   `[typescript]`
+    -   Changed `world:clear` to also look through the component record for the cleared `ID`
+        -   Removes the cleared ID from every entity that has it
+    -   Changed entity ID layouts by putting the index in the lower bits, which should make every world function 1-5 nanoseconds faster
+    -   Fixed `world:delete` not removing every pair with an unalive target
+        -   Specifically happened when you had at least two pairs of different relations with multiple targets each
+-   `[hooks]`:
+    -   Replaced `OnSet` with `OnChange`
+        -   The former was used to detect emplace/move actions. Now the behaviour for `OnChange` is that it will run only when the value has changed
+    -   Changed `OnAdd` to specifically run after the data has been set for non-zero-sized components. Also returns the value that the component was set to
+        -   This should allow a more lenient window for modifying data
+    -   Changed `OnRemove` to lazily lookup which archetype the entity will move to
+        -   Can now have interior structural changes within `OnRemove` hooks
+    -   Optimized `world:has` for both single component and multiple component presence.
+        -   This comes at the cost that it cannot check the component presence for more than 4 components at a time. If this is important, consider calling to this function multiple times.
 
-    -   Fixed Entity type to default to `undefined | unknown` instead of just `undefined`
+## [0.5.0] - 2024-12-26
 
+-   `[world]`:
+    -   Fixed `world:target` not giving adjacent pairs
+    -   Added `world:each` to find entities with a specific Tag
+    -   Added `world:children` to find children of entity
 -   `[query]`:
-    -   Fixed bug where `world:clear` did not invoke `jecs.OnRemove` hooks
-    -   Changed `query.__iter` to drain on iteration
-        -   It will initialize once wherever you left iteration off at last time
-    -   Changed `query:iter` to restart the iterator
-    -   Removed `query:drain` and `query:next`
-        -   If you want to get individual results outside of a for-loop, you need to call `query:iter` to initialize the iterator and then call the iterator function manually
-        ```lua
-        local it = world:query(A, B, C):iter()
-        local entity, a, b, c = it()
-        entity, a, b, c = it() -- get next results
-        ```
--   `[world`
-    -   Fixed a bug with `world:clear` not invoking `jecs.OnRemove` hooks
--   `[typescript]`:
-    -   Changed pair to accept generics
-    -   Improved handling of Tags
+    -   Added `query:cached`
+        -   Adds query cache that updates itself when an archetype matching the query gets created or deleted.
+-   `[luau]`:
+    -   Changed how entities' types are inferred with user-defined type functions
+    -   Changed `Pair<First, Second>` to return `Second` if `First` is a `Tag`; otherwise, returns `First`.
+
+## [0.4.0] - 2024-11-17
+
+-   `[world]`:
+    -   Added recycling to `world:entity`
+        -   If you see much larger entity ids, that is because its generation has been incremented
+-   `[query]`:
+    -   Removed `query:drain`
+        -   The default behaviour is simply to drain the iterator
+    -   Removed `query:next`
+        -   Just call the iterator function returned by `query:iter` directly if you want to get the next results
+    -   Removed `query:replace`
+-   `[luau]`:
+    -   Fixed `query:archetypes` not taking `self`
+    -   Changed so that the `jecs.Pair` type now returns the first element's type so you won't need to typecast anymore.
 
 ## [0.3.2] - 2024-10-01
 
@@ -165,7 +185,7 @@ The format is based on [Keep a Changelog][kac], and this project adheres to
 
 -   Separates ranges for components and entity IDs.
 
-    -   IDs created with `world:component()` will promote array lookups rather than map lookups in the `componentIndex` which is a significant boost
+    -   IDs created with `world:component()` will promote array lookups rather than map lookups in the `component_index` which is a significant boost
 
 -   No longer caches the column pointers directly and instead the column indices which stay persistent even when data is reallocated during swap-removals
     -   This was an issue with the iterator being invalidated when you move an entity to a different archetype.

addons/observers.luau

@@ -0,0 +1,161 @@
+local jecs = require("@jecs")
+
+type Observer<T...> = {
+	callback: (jecs.Entity) -> (),
+	query: jecs.Query<T...>,
+}
+
+export type PatchedWorld = jecs.World & {
+	added: (PatchedWorld, jecs.Id, (e: jecs.Entity, id: jecs.Id, value: any) -> ()) -> (),
+	removed: (PatchedWorld, jecs.Id, (e: jecs.Entity, id: jecs.Id) -> ()) -> (),
+	changed: (PatchedWorld, jecs.Id, (e: jecs.Entity, id: jecs.Id) -> ()) -> (),
+	observer: (PatchedWorld, Observer<any>) -> (),
+	monitor: (PatchedWorld, Observer<any>) -> (),
+}
+
+local function observers_new(world, description)
+	local query = description.query
+	local callback = description.callback
+	local terms = query.filter_with :: { jecs.Id }
+	if not terms then
+		local ids = query.ids
+		query.filter_with = ids
+		terms = ids
+	end
+
+	local entity_index = world.entity_index :: any
+	local function emplaced(entity: jecs.Entity)
+		local r = jecs.entity_index_try_get_fast(
+			entity_index, entity :: any)
+
+		if not r then
+			return
+		end
+
+		local archetype = r.archetype
+
+		if jecs.query_match(query, archetype) then
+			callback(entity)
+		end
+	end
+
+	for _, term in terms do
+		world:added(term, emplaced)
+		world:changed(term, emplaced)
+ 	end
+end
+
+local function monitors_new(world, description)
+	local query = description.query
+	local callback = description.callback
+	local terms = query.filter_with :: { jecs.Id }
+	if not terms then
+		local ids = query.ids
+		query.filter_with = ids
+		terms = ids
+	end
+
+	local entity_index = world.entity_index :: any
+	local function emplaced(entity: jecs.Entity)
+		local r = jecs.entity_index_try_get_fast(
+			entity_index, entity :: any)
+
+		if not r then
+			return
+		end
+
+		local archetype = r.archetype
+
+		if jecs.query_match(query, archetype) then
+			callback(entity, jecs.OnAdd)
+		end
+	end
+
+	local function removed(entity: jecs.Entity, component: jecs.Id)
+		local r = jecs.entity_index_try_get_fast(
+			entity_index, entity :: any)
+
+		if not r then
+			return
+		end
+
+		local archetype = r.archetype
+
+		if jecs.query_match(query, archetype) then
+			callback(entity, jecs.OnRemove)
+		end
+	end
+
+	for _, term in terms do
+		world:added(term, emplaced)
+		world:removed(term, removed)
+ 	end
+end
+
+local function observers_add(world: jecs.World & { [string]: any }): PatchedWorld
+	local signals = {
+		added = {},
+		emplaced = {},
+		removed = {}
+	}
+
+	world.added = function(_, component, fn)
+		local listeners = signals.added[component]
+		local component_index = world.component_index :: jecs.ComponentIndex
+		assert(component_index[component] == nil, "You cannot use hooks on components you intend to use this signal with")
+		if not listeners then
+			listeners = {}
+			signals.added[component] = listeners
+			local function on_add(entity: number, id: number, value: any)
+				for _, listener in listeners :: any do
+					listener(entity, id, value)
+				end
+			end
+			world:set(component, jecs.OnAdd, on_add)		end
+		table.insert(listeners, fn)
+	end
+
+	world.changed = function(_, component, fn)
+		local listeners = signals.emplaced[component]
+		local component_index = world.component_index :: jecs.ComponentIndex
+		assert(component_index[component] == nil, "You cannot use hooks on components you intend to use this signal with")
+		if not listeners then
+			listeners = {}
+			signals.emplaced[component] = listeners
+			local function on_change(entity: number, id: number, value: any)
+				for _, listener in listeners :: any do
+					listener(entity, id, value)
+				end
+			end
+			world:set(component, jecs.OnChange, on_change)
+		end
+		table.insert(listeners, fn)
+	end
+
+	world.removed = function(_, component, fn)
+		local listeners = signals.removed[component]
+		local component_index = world.component_index :: jecs.ComponentIndex
+		assert(component_index[component] == nil, "You cannot use hooks on components you intend to use this signal with")
+		if not listeners then
+			listeners = {}
+			signals.removed[component] = listeners
+			local function on_remove(entity: number, id: number, value: any)
+				for _, listener in listeners :: any do
+					listener(entity, id, value)
+				end
+			end
+			world:set(component, jecs.OnRemove, on_remove)
+		end
+		table.insert(listeners, fn)
+	end
+
+	world.signals = signals
+
+	world.observer = observers_new
+
+	world.monitor = monitors_new
+
+	return world :: PatchedWorld
+end
+
+return observers_add

benches/cached.luau

@@ -1,5 +1,5 @@
 local jecs = require("@jecs")
-local mirror = require("../mirror/init")
+local mirror = require("@mirror")
 
 type i53 = number
 

benches/general.luau

@@ -36,7 +36,7 @@ do
 	TITLE("set")
 
 	local world = jecs.World.new()
-	local A = world:entity()
+	local A = world:component()
 
 	local entities = table.create(N)
 
@@ -70,7 +70,7 @@ do
 	TITLE("set relationship")
 
 	local world = jecs.World.new()
-	local A = world:entity()
+	local A = world:component()
 
 	local entities = table.create(N)
 
@@ -194,12 +194,13 @@ do
 					world:set(id, B, true)
 					world:set(id, C, true)
 					world:set(id, D, true)
-					world:set(id, ct, true)
+					world:add(id, ct)
 				end
 			end
 
+			local q = world:query(A, B, C, D)
 			START()
-			for id in world:query(A, B, C, D) do
+			for id in q do
 			end
 		end)
 
@@ -218,17 +219,18 @@ do
 					world:set(id, B, true)
 					world:set(id, C, true)
 					world:set(id, D, true)
-					world:set(id, ct, true)
+					world:add(id, ct)
 				end
 			end
 
+			local archetypes = world:query(A, B, C, D):archetypes()
 			START()
-			for _, archetype in world:query(A, B, C, D):archetypes() do
+			for _, archetype in archetypes do
 				local columns, records = archetype.columns, archetype.records
-				local a = columns[records[A].column]
-				local b = columns[records[B].column]
-				local c = columns[records[C].column]
-				local d = columns[records[D].column]
+				local a = columns[records[A]]
+				local b = columns[records[B]]
+				local c = columns[records[C]]
+				local d = columns[records[D]]
 				for row in archetype.entities do
 					local _1, _2, _3, _4 = a[row], b[row], c[row], d[row]
 				end

benches/visual/despawn.bench.luau

@@ -5,41 +5,60 @@ local ReplicatedStorage = game:GetService("ReplicatedStorage")
 local Matter = require(ReplicatedStorage.DevPackages.Matter)
 local ecr = require(ReplicatedStorage.DevPackages.ecr)
 local jecs = require(ReplicatedStorage.Lib)
+local pair = jecs.pair
 local newWorld = Matter.World.new()
 local ecs = jecs.World.new()
+local mirror = require(ReplicatedStorage.mirror)
+local mcs = mirror.World.new()
 
-local A, B = Matter.component(), Matter.component()
-local C, D = ecs:component(), ecs:component()
+local C1 = ecs:component()
+local C2 = ecs:entity()
+ecs:add(C2, pair(jecs.OnDeleteTarget, jecs.Delete))
+local C3 = ecs:entity()
+ecs:add(C3, pair(jecs.OnDeleteTarget, jecs.Delete))
+local C4 = ecs:entity()
+ecs:add(C4, pair(jecs.OnDeleteTarget, jecs.Delete))
+local E1 = mcs:component()
+local E2 = mcs:entity()
+mcs:add(E2, pair(jecs.OnDeleteTarget, jecs.Delete))
+local E3 = mcs:entity()
+mcs:add(E3, pair(jecs.OnDeleteTarget, jecs.Delete))
+local E4 = mcs:entity()
+mcs:add(E4, pair(jecs.OnDeleteTarget, jecs.Delete))
+
+local registry2 = ecr.registry()
 
 return {
 	ParameterGenerator = function()
-		local matter_entities = {}
-		local jecs_entities = {}
-		local entities = {
-			matter = matter_entities,
-			jecs = jecs_entities,
-		}
+		local j = ecs:entity()
+		ecs:set(j, C1, true)
+		local m = mcs:entity()
+		mcs:set(m, E1, true)
 		for i = 1, 1000 do
-			table.insert(matter_entities, newWorld:spawn(A(), B()))
-			local e = ecs:entity()
-			ecs:set(e, C, {})
-			ecs:set(e, D, {})
-			table.insert(jecs_entities, e)
+			local friend1 = ecs:entity()
+			local friend2 = mcs:entity()
+
+			ecs:add(friend1, pair(C2, j))
+			ecs:add(friend1, pair(C3, j))
+			ecs:add(friend1, pair(C4, j))
+
+			mcs:add(friend2, pair(E2, m))
+			mcs:add(friend2, pair(E3, m))
+			mcs:add(friend2, pair(E4, m))
 		end
-		return entities
+		return {
+			m = m,
+			j = j,
+		}
 	end,
 
 	Functions = {
-		Matter = function(_, entities)
-			for _, entity in entities.matter do
-				newWorld:despawn(entity)
-			end
+		Mirror = function(_, a)
+			mcs:delete(a.m)
 		end,
 
-		Jecs = function(_, entities)
-			for _, entity in entities.jecs do
-				ecs:delete(entity)
-			end
+		Jecs = function(_, a)
+			ecs:delete(a.j)
 		end,
 	},
 }

benches/visual/insertion.bench.luau

@@ -28,22 +28,22 @@ local B6 = ecr.component()
 local B7 = ecr.component()
 local B8 = ecr.component()
 
-local C1 = ecs:entity()
-local C2 = ecs:entity()
-local C3 = ecs:entity()
-local C4 = ecs:entity()
-local C5 = ecs:entity()
-local C6 = ecs:entity()
-local C7 = ecs:entity()
-local C8 = ecs:entity()
-local E1 = mcs:entity()
-local E2 = mcs:entity()
-local E3 = mcs:entity()
-local E4 = mcs:entity()
-local E5 = mcs:entity()
-local E6 = mcs:entity()
-local E7 = mcs:entity()
-local E8 = mcs:entity()
+local C1 = ecs:component()
+local C2 = ecs:component()
+local C3 = ecs:component()
+local C4 = ecs:component()
+local C5 = ecs:component()
+local C6 = ecs:component()
+local C7 = ecs:component()
+local C8 = ecs:component()
+local E1 = mcs:component()
+local E2 = mcs:component()
+local E3 = mcs:component()
+local E4 = mcs:component()
+local E5 = mcs:component()
+local E6 = mcs:component()
+local E7 = mcs:component()
+local E8 = mcs:component()
 
 local registry2 = ecr.registry()
 return {
@@ -52,48 +52,30 @@ return {
 	end,
 
 	Functions = {
-		Matter = function()
-			local e = newWorld:spawn()
+		Mirror = function()
+			local e = mcs:entity()
 			for i = 1, 5000 do
-				newWorld:insert(
-					e,
-					A1({ value = true }),
-					A2({ value = true }),
-					A3({ value = true }),
-					A4({ value = true }),
-					A5({ value = true }),
-					A6({ value = true }),
-					A7({ value = true }),
-					A8({ value = true })
-				)
+				mcs:set(e, E1, false)
+				mcs:set(e, E2, false)
+				mcs:set(e, E3, false)
+				mcs:set(e, E4, false)
+				mcs:set(e, E5, false)
+				mcs:set(e, E6, false)
+				mcs:set(e, E7, false)
+				mcs:set(e, E8, false)
 			end
 		end,
-
-		ECR = function()
-			local e = registry2.create()
-			for i = 1, 5000 do
-				registry2:set(e, B1, { value = false })
-				registry2:set(e, B2, { value = false })
-				registry2:set(e, B3, { value = false })
-				registry2:set(e, B4, { value = false })
-				registry2:set(e, B5, { value = false })
-				registry2:set(e, B6, { value = false })
-				registry2:set(e, B7, { value = false })
-				registry2:set(e, B8, { value = false })
-			end
-		end,
-
 		Jecs = function()
 			local e = ecs:entity()
 			for i = 1, 5000 do
-				ecs:set(e, C1, { value = false })
-				ecs:set(e, C2, { value = false })
-				ecs:set(e, C3, { value = false })
-				ecs:set(e, C4, { value = false })
-				ecs:set(e, C5, { value = false })
-				ecs:set(e, C6, { value = false })
-				ecs:set(e, C7, { value = false })
-				ecs:set(e, C8, { value = false })
+				ecs:set(e, C1, false)
+				ecs:set(e, C2, false)
+				ecs:set(e, C3, false)
+				ecs:set(e, C4, false)
+				ecs:set(e, C5, false)
+				ecs:set(e, C6, false)
+				ecs:set(e, C7, false)
+				ecs:set(e, C8, false)
 			end
 		end,
 	},

benches/visual/remove.bench.luau

@@ -0,0 +1,49 @@
+--!optimize 2
+--!native
+
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local Matter = require(ReplicatedStorage.DevPackages.Matter)
+local ecr = require(ReplicatedStorage.DevPackages.ecr)
+local jecs = require(ReplicatedStorage.Lib)
+local pair = jecs.pair
+local ecs = jecs.World.new()
+local mirror = require(ReplicatedStorage.mirror)
+local mcs = mirror.World.new()
+
+local C1 = ecs:component()
+local C2 = ecs:entity()
+ecs:add(C2, pair(jecs.OnDeleteTarget, jecs.Delete))
+local C3 = ecs:entity()
+ecs:add(C3, pair(jecs.OnDeleteTarget, jecs.Delete))
+local C4 = ecs:entity()
+ecs:add(C4, pair(jecs.OnDeleteTarget, jecs.Delete))
+local E1 = mcs:component()
+local E2 = mcs:entity()
+mcs:add(E2, pair(jecs.OnDeleteTarget, jecs.Delete))
+local E3 = mcs:entity()
+mcs:add(E3, pair(jecs.OnDeleteTarget, jecs.Delete))
+local E4 = mcs:entity()
+mcs:add(E4, pair(jecs.OnDeleteTarget, jecs.Delete))
+
+return {
+	ParameterGenerator = function()
+	end,
+
+	Functions = {
+		Mirror = function()
+			local m = mcs:entity()
+			for i = 1, 100 do
+				mcs:add(m, E3)
+				mcs:remove(m, E3)
+			end
+		end,
+
+		Jecs = function()
+			local j = ecs:entity()
+			for i = 1, 100 do
+				ecs:add(j, C3)
+				ecs:remove(j, C3)
+			end
+		end,
+	},
+}

coverage/ansi.luau.html

@@ -0,0 +1,69 @@
+<html><head>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/js/bootstrap.bundle.min.js"></script>
+<style>
+body { font-family: monospace; text-align: center; }
+#funcTable table { margin: 0 auto; width: auto; max-width: 300px; font-size: 14px; border-collapse: collapse; }
+#funcTable th, #funcTable td { padding: 2px 6px; text-align: left; white-space: nowrap; }
+#funcTable th { background-color: #ddd; }
+#funcTable td:nth-child(2) { text-align: right; min-width: 50px; }
+.zero-hits { background-color: #fcc; font-weight: bold; color: red; }
+.nonzero-hits { color: green; font-weight: bold; }
+.low-hits { background-color: #ffe6b3; }
+.high-hits { background-color: #cfc; }
+.source-code-table { margin-left: 10px; }th, td { padding: 0px; font-size: 12px; }
+table.table { font-size: 14px; border-collapse: collapse; }
+table.table th, table.table td { padding: 1px; font-size: 12px; line-height: 1.2; }
+table.table tr { height: auto; }
+</style></head><body>
+<h1 class="text-center">ansi.luau Coverage</h1>
+<h2>Total Execution Hits: 1</h2>
+<h2>Function Coverage Overview: 11.11%</h2>
+<button class="btn btn-primary mb-2" type="button" data-bs-toggle="collapse" data-bs-target="#funcTable">Toggle Function Coverage</button>
+<div class="collapse show" id="funcTable">
+<h2>Function Coverage:</h2><table class="table table-bordered"><thead><tr><th>Function</th><th>Hits</th></tr></thead><tbody>
+<tr><td style="padding: 1px; min-width: 18ch;"><main></td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
+<tr><td style="padding: 1px; min-width: 18ch;">white_underline:2</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 18ch;">white:6</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 18ch;">green:10</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 18ch;">red:14</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 18ch;">yellow:18</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 18ch;">red_highlight:22</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 18ch;">green_highlight:26</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 18ch;">gray:30</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+</tbody></table></div>
+<h2>Source Code:</h2><table class="table table-bordered source-code-table "><thead><tr><th>Line</th><th>Hits</th><th>Code</th></tr></thead><tbody>
+<tr><td>1</td><td>1</td><td><span class=high-hits>return {</span></td></tr>
+<tr><td>2</td><td>1</td><td><span class=high-hits>white_underline = function(s: any)</span></td></tr>
+<tr><td>3</td><td>0</td><td><span class=zero-hits>return `\27[1;4m{s}\27[0m`</span></td></tr>
+<tr><td>4</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>5</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>6</td><td>1</td><td><span class=high-hits>white = function(s: any)</span></td></tr>
+<tr><td>7</td><td>0</td><td><span class=zero-hits>return `\27[37;1m{s}\27[0m`</span></td></tr>
+<tr><td>8</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>9</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>10</td><td>1</td><td><span class=high-hits>green = function(s: any)</span></td></tr>
+<tr><td>11</td><td>0</td><td><span class=zero-hits>return `\27[32;1m{s}\27[0m`</span></td></tr>
+<tr><td>12</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>13</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>14</td><td>1</td><td><span class=high-hits>red = function(s: any)</span></td></tr>
+<tr><td>15</td><td>0</td><td><span class=zero-hits>return `\27[31;1m{s}\27[0m`</span></td></tr>
+<tr><td>16</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>17</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>18</td><td>1</td><td><span class=high-hits>yellow = function(s: any)</span></td></tr>
+<tr><td>19</td><td>0</td><td><span class=zero-hits>return `\27[33;1m{s}\27[0m`</span></td></tr>
+<tr><td>20</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>21</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>22</td><td>1</td><td><span class=high-hits>red_highlight = function(s: any)</span></td></tr>
+<tr><td>23</td><td>0</td><td><span class=zero-hits>return `\27[41;1;30m{s}\27[0m`</span></td></tr>
+<tr><td>24</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>25</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>26</td><td>1</td><td><span class=high-hits>green_highlight = function(s: any)</span></td></tr>
+<tr><td>27</td><td>0</td><td><span class=zero-hits>return `\27[42;1;30m{s}\27[0m`</span></td></tr>
+<tr><td>28</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>29</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>30</td><td>1</td><td><span class=high-hits>gray = function(s: any)</span></td></tr>
+<tr><td>31</td><td>0</td><td><span class=zero-hits>return `\27[30;1m{s}\27[0m`</span></td></tr>
+<tr><td>32</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>33</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+</tbody></table></body></html>

coverage/entity_visualiser.luau.html

@@ -0,0 +1,74 @@
+<html><head>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/js/bootstrap.bundle.min.js"></script>
+<style>
+body { font-family: monospace; text-align: center; }
+#funcTable table { margin: 0 auto; width: auto; max-width: 300px; font-size: 14px; border-collapse: collapse; }
+#funcTable th, #funcTable td { padding: 2px 6px; text-align: left; white-space: nowrap; }
+#funcTable th { background-color: #ddd; }
+#funcTable td:nth-child(2) { text-align: right; min-width: 50px; }
+.zero-hits { background-color: #fcc; font-weight: bold; color: red; }
+.nonzero-hits { color: green; font-weight: bold; }
+.low-hits { background-color: #ffe6b3; }
+.high-hits { background-color: #cfc; }
+.source-code-table { margin-left: 10px; }th, td { padding: 0px; font-size: 12px; }
+table.table { font-size: 14px; border-collapse: collapse; }
+table.table th, table.table td { padding: 1px; font-size: 12px; line-height: 1.2; }
+table.table tr { height: auto; }
+</style></head><body>
+<h1 class="text-center">entity_visualiser.luau Coverage</h1>
+<h2>Total Execution Hits: 1</h2>
+<h2>Function Coverage Overview: 25.00%</h2>
+<button class="btn btn-primary mb-2" type="button" data-bs-toggle="collapse" data-bs-target="#funcTable">Toggle Function Coverage</button>
+<div class="collapse show" id="funcTable">
+<h2>Function Coverage:</h2><table class="table table-bordered"><thead><tr><th>Function</th><th>Hits</th></tr></thead><tbody>
+<tr><td style="padding: 1px; min-width: 13ch;"><main></td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
+<tr><td style="padding: 1px; min-width: 13ch;">pe:6</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 13ch;">name:11</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 13ch;">components:15</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+</tbody></table></div>
+<h2>Source Code:</h2><table class="table table-bordered source-code-table "><thead><tr><th>Line</th><th>Hits</th><th>Code</th></tr></thead><tbody>
+<tr><td>1</td><td>1</td><td><span class=high-hits>local jecs = require("@jecs")</span></td></tr>
+<tr><td>2</td><td>1</td><td><span class=high-hits>local ECS_GENERATION = jecs.ECS_GENERATION</span></td></tr>
+<tr><td>3</td><td>1</td><td><span class=high-hits>local ECS_ID = jecs.ECS_ID</span></td></tr>
+<tr><td>4</td><td>1</td><td><span class=high-hits>local ansi = require("@tools/ansi")</span></td></tr>
+<tr><td>5</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>6</td><td>1</td><td><span class=high-hits>local function pe(e: any)</span></td></tr>
+<tr><td>7</td><td>0</td><td><span class=zero-hits>local gen = ECS_GENERATION(e)</span></td></tr>
+<tr><td>8</td><td>0</td><td><span class=zero-hits>return ansi.green(`e{ECS_ID(e)}`) .. ansi.yellow(`v{gen}`)</span></td></tr>
+<tr><td>9</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>10</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>11</td><td>1</td><td><span class=high-hits>local function name(world: jecs.World, id: any)</span></td></tr>
+<tr><td>12</td><td>0</td><td><span class=zero-hits>return world:get(id, jecs.Name) or `${id}`</span></td></tr>
+<tr><td>13</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>14</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>15</td><td>1</td><td><span class=high-hits>local function components(world: jecs.World, entity: any)</span></td></tr>
+<tr><td>16</td><td>0</td><td><span class=zero-hits>local r = jecs.entity_index_try_get(world.entity_index, entity)</span></td></tr>
+<tr><td>17</td><td>0</td><td><span class=zero-hits>if not r then</span></td></tr>
+<tr><td>18</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
+<tr><td>19</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>20</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>21</td><td>0</td><td><span class=zero-hits>local archetype = r.archetype</span></td></tr>
+<tr><td>22</td><td>0</td><td><span class=zero-hits>local row = r.row</span></td></tr>
+<tr><td>23</td><td>0</td><td><span class=zero-hits>print(`Entity {pe(entity)}`)</span></td></tr>
+<tr><td>24</td><td>0</td><td><span class=zero-hits>print("-----------------------------------------------------")</span></td></tr>
+<tr><td>25</td><td>0</td><td><span class=zero-hits>for i, column in archetype.columns do</span></td></tr>
+<tr><td>26</td><td>0</td><td><span class=zero-hits>local component = archetype.types[i]</span></td></tr>
+<tr><td>27</td><td>0</td><td><span class=zero-hits>local n</span></td></tr>
+<tr><td>28</td><td>0</td><td><span class=zero-hits>if jecs.IS_PAIR(component) then</span></td></tr>
+<tr><td>29</td><td>0</td><td><span class=zero-hits>n = `({name(world, jecs.pair_first(world, component))}, {name(world, jecs.pair_second(world, component))})`</span></td></tr>
+<tr><td>30</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
+<tr><td>31</td><td>0</td><td><span class=zero-hits>n = name(world, component)</span></td></tr>
+<tr><td>32</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>33</td><td>0</td><td><span class=zero-hits>local data = column[row] or "TAG"</span></td></tr>
+<tr><td>34</td><td>0</td><td><span class=zero-hits>print(`| {n} | {data} |`)</span></td></tr>
+<tr><td>35</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>36</td><td>0</td><td><span class=zero-hits>print("-----------------------------------------------------")</span></td></tr>
+<tr><td>37</td><td>0</td><td><span class=zero-hits>return true</span></td></tr>
+<tr><td>38</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>39</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>40</td><td>1</td><td><span class=high-hits>return {</span></td></tr>
+<tr><td>41</td><td>1</td><td><span class=high-hits>components = components,</span></td></tr>
+<tr><td>42</td><td>1</td><td><span class=high-hits>prettify = pe,</span></td></tr>
+<tr><td>43</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+</tbody></table></body></html>

coverage/index.html

@@ -0,0 +1,12 @@
+<html><head>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">
+</head><body>
+<h1 class="text-center">Coverage Report</h1>
+<table class="table table-striped table-bordered"><thead><tr><th>File</th><th>Total Hits</th><th>Functions</th></tr></thead><tbody>
+<tr><td><a href="tests.luau.html">tests.luau</a></td><td>100</td><td>67</td></tr>
+<tr><td><a href="jecs.luau.html">jecs.luau</a></td><td>1006447</td><td>97</td></tr>
+<tr><td><a href="testkit.luau.html">testkit.luau</a></td><td>1826</td><td>31</td></tr>
+<tr><td><a href="lifetime_tracker.luau.html">lifetime_tracker.luau</a></td><td>1</td><td>11</td></tr>
+<tr><td><a href="entity_visualiser.luau.html">entity_visualiser.luau</a></td><td>1</td><td>4</td></tr>
+<tr><td><a href="ansi.luau.html">ansi.luau</a></td><td>1</td><td>9</td></tr>
+</tbody></table></body></html>

coverage/lifetime_tracker.luau.html

@@ -0,0 +1,254 @@
+<html><head>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/js/bootstrap.bundle.min.js"></script>
+<style>
+body { font-family: monospace; text-align: center; }
+#funcTable table { margin: 0 auto; width: auto; max-width: 300px; font-size: 14px; border-collapse: collapse; }
+#funcTable th, #funcTable td { padding: 2px 6px; text-align: left; white-space: nowrap; }
+#funcTable th { background-color: #ddd; }
+#funcTable td:nth-child(2) { text-align: right; min-width: 50px; }
+.zero-hits { background-color: #fcc; font-weight: bold; color: red; }
+.nonzero-hits { color: green; font-weight: bold; }
+.low-hits { background-color: #ffe6b3; }
+.high-hits { background-color: #cfc; }
+.source-code-table { margin-left: 10px; }th, td { padding: 0px; font-size: 12px; }
+table.table { font-size: 14px; border-collapse: collapse; }
+table.table th, table.table td { padding: 1px; font-size: 12px; line-height: 1.2; }
+table.table tr { height: auto; }
+</style></head><body>
+<h1 class="text-center">lifetime_tracker.luau Coverage</h1>
+<h2>Total Execution Hits: 1</h2>
+<h2>Function Coverage Overview: 9.09%</h2>
+<button class="btn btn-primary mb-2" type="button" data-bs-toggle="collapse" data-bs-target="#funcTable">Toggle Function Coverage</button>
+<div class="collapse show" id="funcTable">
+<h2>Function Coverage:</h2><table class="table table-bordered"><thead><tr><th>Function</th><th>Hits</th></tr></thead><tbody>
+<tr><td style="padding: 1px; min-width: 24ch;"><main></td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
+<tr><td style="padding: 1px; min-width: 24ch;">print_centered_entity:12</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 24ch;">name:26</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 24ch;">pad:30</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 24ch;">lifetime_tracker_add:36</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:48</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:62</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:89</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:135</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:164</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:175</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+</tbody></table></div>
+<h2>Source Code:</h2><table class="table table-bordered source-code-table "><thead><tr><th>Line</th><th>Hits</th><th>Code</th></tr></thead><tbody>
+<tr><td>1</td><td>1</td><td><span class=high-hits>local jecs = require("@jecs")</span></td></tr>
+<tr><td>2</td><td>1</td><td><span class=high-hits>local ECS_GENERATION = jecs.ECS_GENERATION</span></td></tr>
+<tr><td>3</td><td>1</td><td><span class=high-hits>local ECS_ID = jecs.ECS_ID</span></td></tr>
+<tr><td>4</td><td>1</td><td><span class=high-hits>local __ = jecs.Wildcard</span></td></tr>
+<tr><td>5</td><td>1</td><td><span class=high-hits>local pair = jecs.pair</span></td></tr>
+<tr><td>6</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>7</td><td>1</td><td><span class=high-hits>local prettify = require("@tools/entity_visualiser").prettify</span></td></tr>
+<tr><td>8</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>9</td><td>1</td><td><span class=high-hits>local pe = prettify</span></td></tr>
+<tr><td>10</td><td>1</td><td><span class=high-hits>local ansi = require("@tools/ansi")</span></td></tr>
+<tr><td>11</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>12</td><td>1</td><td><span class=high-hits>function print_centered_entity(entity, width: number)</span></td></tr>
+<tr><td>13</td><td>0</td><td><span class=zero-hits>local entity_str = tostring(entity)</span></td></tr>
+<tr><td>14</td><td>0</td><td><span class=zero-hits>local entity_length = #entity_str</span></td></tr>
+<tr><td>15</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>16</td><td>0</td><td><span class=zero-hits>local padding_total = width - 2 - entity_length</span></td></tr>
+<tr><td>17</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>18</td><td>0</td><td><span class=zero-hits>local padding_left = math.floor(padding_total / 2)</span></td></tr>
+<tr><td>19</td><td>0</td><td><span class=zero-hits>local padding_right = padding_total - padding_left</span></td></tr>
+<tr><td>20</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>21</td><td>0</td><td><span class=zero-hits>local centered_str = string.rep(" ", padding_left) .. entity_str .. string.rep(" ", padding_right)</span></td></tr>
+<tr><td>22</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>23</td><td>0</td><td><span class=zero-hits>print("|" .. centered_str .. "|")</span></td></tr>
+<tr><td>24</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>25</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>26</td><td>1</td><td><span class=high-hits>local function name(world, e)</span></td></tr>
+<tr><td>27</td><td>0</td><td><span class=zero-hits>return world:get(world, e, jecs.Name) or pe(e)</span></td></tr>
+<tr><td>28</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>29</td><td>1</td><td><span class=high-hits>local padding_enabled = false</span></td></tr>
+<tr><td>30</td><td>1</td><td><span class=high-hits>local function pad()</span></td></tr>
+<tr><td>31</td><td>0</td><td><span class=zero-hits>if padding_enabled then</span></td></tr>
+<tr><td>32</td><td>0</td><td><span class=zero-hits>print("")</span></td></tr>
+<tr><td>33</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>34</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>35</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>36</td><td>1</td><td><span class=high-hits>local function lifetime_tracker_add(world: jecs.World, opt)</span></td></tr>
+<tr><td>37</td><td>0</td><td><span class=zero-hits>local entity_index = world.entity_index</span></td></tr>
+<tr><td>38</td><td>0</td><td><span class=zero-hits>local dense_array = entity_index.dense_array</span></td></tr>
+<tr><td>39</td><td>0</td><td><span class=zero-hits>local component_index = world.component_index</span></td></tr>
+<tr><td>40</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>41</td><td>0</td><td><span class=zero-hits>local ENTITY_RANGE = (jecs.Rest :: any) + 1</span></td></tr>
+<tr><td>42</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>43</td><td>0</td><td><span class=zero-hits>local w = setmetatable({}, { __index = world })</span></td></tr>
+<tr><td>44</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>45</td><td>0</td><td><span class=zero-hits>padding_enabled = opt.padding_enabled</span></td></tr>
+<tr><td>46</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>47</td><td>0</td><td><span class=zero-hits>local world_entity = world.entity</span></td></tr>
+<tr><td>48</td><td>0</td><td><span class=zero-hits>w.entity = function(self, entity)</span></td></tr>
+<tr><td>49</td><td>0</td><td><span class=zero-hits>if entity then</span></td></tr>
+<tr><td>50</td><td>0</td><td><span class=zero-hits>return world_entity(world, entity)</span></td></tr>
+<tr><td>51</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>52</td><td>0</td><td><span class=zero-hits>local will_recycle = entity_index.max_id ~= entity_index.alive_count</span></td></tr>
+<tr><td>53</td><td>0</td><td><span class=zero-hits>local e = world_entity(world)</span></td></tr>
+<tr><td>54</td><td>0</td><td><span class=zero-hits>if will_recycle then</span></td></tr>
+<tr><td>55</td><td>0</td><td><span class=zero-hits>print(`*recycled {pe(e)}`)</span></td></tr>
+<tr><td>56</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
+<tr><td>57</td><td>0</td><td><span class=zero-hits>print(`*created {pe(e)}`)</span></td></tr>
+<tr><td>58</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>59</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
+<tr><td>60</td><td>0</td><td><span class=zero-hits>return e</span></td></tr>
+<tr><td>61</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>62</td><td>0</td><td><span class=zero-hits>w.print_entity_index = function(self)</span></td></tr>
+<tr><td>63</td><td>0</td><td><span class=zero-hits>local max_id = entity_index.max_id</span></td></tr>
+<tr><td>64</td><td>0</td><td><span class=zero-hits>local alive_count = entity_index.alive_count</span></td></tr>
+<tr><td>65</td><td>0</td><td><span class=zero-hits>local alive = table.move(dense_array, 1 + jecs.Rest :: any, alive_count, 1, {})</span></td></tr>
+<tr><td>66</td><td>0</td><td><span class=zero-hits>local dead = table.move(dense_array, alive_count + 1, max_id, 1, {})</span></td></tr>
+<tr><td>67</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>68</td><td>0</td><td><span class=zero-hits>local sep = "|--------|"</span></td></tr>
+<tr><td>69</td><td>0</td><td><span class=zero-hits>if #alive > 0 then</span></td></tr>
+<tr><td>70</td><td>0</td><td><span class=zero-hits>print("|-alive--|")</span></td></tr>
+<tr><td>71</td><td>0</td><td><span class=zero-hits>for i = 1, #alive do</span></td></tr>
+<tr><td>72</td><td>0</td><td><span class=zero-hits>local e = pe(alive[i])</span></td></tr>
+<tr><td>73</td><td>0</td><td><span class=zero-hits>print_centered_entity(e, 32)</span></td></tr>
+<tr><td>74</td><td>0</td><td><span class=zero-hits>print(sep)</span></td></tr>
+<tr><td>75</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>76</td><td>0</td><td><span class=zero-hits>print("\n")</span></td></tr>
+<tr><td>77</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>78</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>79</td><td>0</td><td><span class=zero-hits>if #dead > 0 then</span></td></tr>
+<tr><td>80</td><td>0</td><td><span class=zero-hits>print("|--dead--|")</span></td></tr>
+<tr><td>81</td><td>0</td><td><span class=zero-hits>for i = 1, #dead do</span></td></tr>
+<tr><td>82</td><td>0</td><td><span class=zero-hits>print_centered_entity(pe(dead[i]), 32)</span></td></tr>
+<tr><td>83</td><td>0</td><td><span class=zero-hits>print(sep)</span></td></tr>
+<tr><td>84</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>85</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>86</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
+<tr><td>87</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>88</td><td>0</td><td><span class=zero-hits>local timelines = {}</span></td></tr>
+<tr><td>89</td><td>0</td><td><span class=zero-hits>w.print_snapshot = function(self)</span></td></tr>
+<tr><td>90</td><td>0</td><td><span class=zero-hits>local timeline = #timelines + 1</span></td></tr>
+<tr><td>91</td><td>0</td><td><span class=zero-hits>local entity_column_width = 10</span></td></tr>
+<tr><td>92</td><td>0</td><td><span class=zero-hits>local status_column_width = 8</span></td></tr>
+<tr><td>93</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>94</td><td>0</td><td><span class=zero-hits>local header = string.format("| %-" .. entity_column_width .. "s |", "Entity")</span></td></tr>
+<tr><td>95</td><td>0</td><td><span class=zero-hits>for i = 1, timeline do</span></td></tr>
+<tr><td>96</td><td>0</td><td><span class=zero-hits>header = header .. string.format(" %-" .. status_column_width .. "s |", string.format("T%d", i))</span></td></tr>
+<tr><td>97</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>98</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>99</td><td>0</td><td><span class=zero-hits>local max_id = entity_index.max_id</span></td></tr>
+<tr><td>100</td><td>0</td><td><span class=zero-hits>local alive_count = entity_index.alive_count</span></td></tr>
+<tr><td>101</td><td>0</td><td><span class=zero-hits>local alive = table.move(dense_array, 1 + jecs.Rest :: any, alive_count, 1, {})</span></td></tr>
+<tr><td>102</td><td>0</td><td><span class=zero-hits>local dead = table.move(dense_array, alive_count + 1, max_id, 1, {})</span></td></tr>
+<tr><td>103</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>104</td><td>0</td><td><span class=zero-hits>local data = {}</span></td></tr>
+<tr><td>105</td><td>0</td><td><span class=zero-hits>print("-------------------------------------------------------------------")</span></td></tr>
+<tr><td>106</td><td>0</td><td><span class=zero-hits>print(header)</span></td></tr>
+<tr><td>107</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>108</td><td><span class='text-muted'>N/A</span></td><td>-- Store the snapshot data for this timeline</td>></tr>
+<tr><td>109</td><td>0</td><td><span class=zero-hits>for i = ENTITY_RANGE, max_id do</span></td></tr>
+<tr><td>110</td><td>0</td><td><span class=zero-hits>if dense_array[i] then</span></td></tr>
+<tr><td>111</td><td>0</td><td><span class=zero-hits>local entity = dense_array[i]</span></td></tr>
+<tr><td>112</td><td>0</td><td><span class=zero-hits>local id = ECS_ID(entity)</span></td></tr>
+<tr><td>113</td><td>0</td><td><span class=zero-hits>local status = "alive"</span></td></tr>
+<tr><td>114</td><td>0</td><td><span class=zero-hits>if not world:contains(entity) then</span></td></tr>
+<tr><td>115</td><td>0</td><td><span class=zero-hits>status = "dead"</span></td></tr>
+<tr><td>116</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>117</td><td>0</td><td><span class=zero-hits>data[id] = status</span></td></tr>
+<tr><td>118</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>119</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>120</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>121</td><td>0</td><td><span class=zero-hits>table.insert(timelines, data)</span></td></tr>
+<tr><td>122</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>123</td><td><span class='text-muted'>N/A</span></td><td>-- Create a table to hold entity data for sorting</td>></tr>
+<tr><td>124</td><td>0</td><td><span class=zero-hits>local entities = {}</span></td></tr>
+<tr><td>125</td><td>0</td><td><span class=zero-hits>for i = ENTITY_RANGE, max_id do</span></td></tr>
+<tr><td>126</td><td>0</td><td><span class=zero-hits>if dense_array[i] then</span></td></tr>
+<tr><td>127</td><td>0</td><td><span class=zero-hits>local entity = dense_array[i]</span></td></tr>
+<tr><td>128</td><td>0</td><td><span class=zero-hits>local id = ECS_ID(entity)</span></td></tr>
+<tr><td>129</td><td><span class='text-muted'>N/A</span></td><td>-- Push entity and id into the new `entities` table</td>></tr>
+<tr><td>130</td><td>0</td><td><span class=zero-hits>table.insert(entities, { entity = entity, id = id })</span></td></tr>
+<tr><td>131</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>132</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>133</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>134</td><td><span class='text-muted'>N/A</span></td><td>-- Sort the entities by ECS_ID</td>></tr>
+<tr><td>135</td><td>0</td><td><span class=zero-hits>table.sort(entities, function(a, b)</span></td></tr>
+<tr><td>136</td><td>0</td><td><span class=zero-hits>return a.id < b.id</span></td></tr>
+<tr><td>137</td><td><span class='text-muted'>N/A</span></td><td>end)</td>></tr>
+<tr><td>138</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>139</td><td><span class='text-muted'>N/A</span></td><td>-- Print the sorted rows</td>></tr>
+<tr><td>140</td><td>0</td><td><span class=zero-hits>for _, entity_data in ipairs(entities) do</span></td></tr>
+<tr><td>141</td><td>0</td><td><span class=zero-hits>local entity = entity_data.entity</span></td></tr>
+<tr><td>142</td><td>0</td><td><span class=zero-hits>local id = entity_data.id</span></td></tr>
+<tr><td>143</td><td>0</td><td><span class=zero-hits>local status = "alive"</span></td></tr>
+<tr><td>144</td><td>0</td><td><span class=zero-hits>if id > alive_count then</span></td></tr>
+<tr><td>145</td><td>0</td><td><span class=zero-hits>status = "dead"</span></td></tr>
+<tr><td>146</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>147</td><td>0</td><td><span class=zero-hits>local row = string.format("| %-" .. entity_column_width .. "s     |", pe(entity))</span></td></tr>
+<tr><td>148</td><td>0</td><td><span class=zero-hits>for j = 1, timeline do</span></td></tr>
+<tr><td>149</td><td>0</td><td><span class=zero-hits>local timeline_data = timelines[j]</span></td></tr>
+<tr><td>150</td><td>0</td><td><span class=zero-hits>local entity_data = timeline_data[id]</span></td></tr>
+<tr><td>151</td><td>0</td><td><span class=zero-hits>if entity_data then</span></td></tr>
+<tr><td>152</td><td>0</td><td><span class=zero-hits>row = row .. string.format(" %-" .. status_column_width .. "s |", entity_data)</span></td></tr>
+<tr><td>153</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
+<tr><td>154</td><td>0</td><td><span class=zero-hits>row = row .. string.format(" %-" .. status_column_width .. "s |", "-")</span></td></tr>
+<tr><td>155</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>156</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>157</td><td>0</td><td><span class=zero-hits>print(row)</span></td></tr>
+<tr><td>158</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>159</td><td>0</td><td><span class=zero-hits>print("-------------------------------------------------------------------")</span></td></tr>
+<tr><td>160</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
+<tr><td>161</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>162</td><td>0</td><td><span class=zero-hits>local world_add = world.add</span></td></tr>
+<tr><td>163</td><td>0</td><td><span class=zero-hits>local relations = {}</span></td></tr>
+<tr><td>164</td><td>0</td><td><span class=zero-hits>w.add = function(self, entity: any, component: any)</span></td></tr>
+<tr><td>165</td><td>0</td><td><span class=zero-hits>world_add(world, entity, component)</span></td></tr>
+<tr><td>166</td><td>0</td><td><span class=zero-hits>if jecs.IS_PAIR(component) then</span></td></tr>
+<tr><td>167</td><td>0</td><td><span class=zero-hits>local relation = jecs.pair_first(world, component)</span></td></tr>
+<tr><td>168</td><td>0</td><td><span class=zero-hits>local target = jecs.pair_second(world, component)</span></td></tr>
+<tr><td>169</td><td>0</td><td><span class=zero-hits>print(`*added ({pe(relation)}, {pe(target)}) to {pe(entity)}`)</span></td></tr>
+<tr><td>170</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
+<tr><td>171</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>172</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>173</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>174</td><td>0</td><td><span class=zero-hits>local world_delete = world.delete</span></td></tr>
+<tr><td>175</td><td>0</td><td><span class=zero-hits>w.delete = function(self, e)</span></td></tr>
+<tr><td>176</td><td>0</td><td><span class=zero-hits>world_delete(world, e)</span></td></tr>
+<tr><td>177</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>178</td><td>0</td><td><span class=zero-hits>local idr_t = component_index[pair(__, e)]</span></td></tr>
+<tr><td>179</td><td>0</td><td><span class=zero-hits>if idr_t then</span></td></tr>
+<tr><td>180</td><td>0</td><td><span class=zero-hits>for archetype_id in idr_t.cache do</span></td></tr>
+<tr><td>181</td><td>0</td><td><span class=zero-hits>local archetype = world.archetypes[archetype_id]</span></td></tr>
+<tr><td>182</td><td>0</td><td><span class=zero-hits>for _, id in archetype.types do</span></td></tr>
+<tr><td>183</td><td>0</td><td><span class=zero-hits>if not jecs.IS_PAIR(id) then</span></td></tr>
+<tr><td>184</td><td>0</td><td><span class=zero-hits>continue</span></td></tr>
+<tr><td>185</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>186</td><td>0</td><td><span class=zero-hits>local object = jecs.pair_second(world, id)</span></td></tr>
+<tr><td>187</td><td>0</td><td><span class=zero-hits>if object ~= e then</span></td></tr>
+<tr><td>188</td><td>0</td><td><span class=zero-hits>continue</span></td></tr>
+<tr><td>189</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>190</td><td>0</td><td><span class=zero-hits>local id_record = component_index[id]</span></td></tr>
+<tr><td>191</td><td>0</td><td><span class=zero-hits>local flags = id_record.flags</span></td></tr>
+<tr><td>192</td><td>0</td><td><span class=zero-hits>local flags_delete_mask: number = bit32.band(flags, jecs.ECS_ID_DELETE)</span></td></tr>
+<tr><td>193</td><td>0</td><td><span class=zero-hits>if flags_delete_mask ~= 0 then</span></td></tr>
+<tr><td>194</td><td>0</td><td><span class=zero-hits>for _, entity in archetype.entities do</span></td></tr>
+<tr><td>195</td><td>0</td><td><span class=zero-hits>print(`*deleted dependant {pe(entity)} of {pe(e)}`)</span></td></tr>
+<tr><td>196</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
+<tr><td>197</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>198</td><td>0</td><td><span class=zero-hits>break</span></td></tr>
+<tr><td>199</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
+<tr><td>200</td><td>0</td><td><span class=zero-hits>for _, entity in archetype.entities do</span></td></tr>
+<tr><td>201</td><td>0</td><td><span class=zero-hits>print(</span></td></tr>
+<tr><td>202</td><td>0</td><td><span class=zero-hits>`*removed dependency ({pe(jecs.pair_first(world, id))}, {pe(object)}) from {pe(entity)}`</span></td></tr>
+<tr><td>203</td><td>0</td><td><span class=zero-hits>)</span></td></tr>
+<tr><td>204</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>205</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>206</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>207</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>208</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>209</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>210</td><td>0</td><td><span class=zero-hits>print(`*deleted {pe(e)}`)</span></td></tr>
+<tr><td>211</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
+<tr><td>212</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>213</td><td>0</td><td><span class=zero-hits>return w</span></td></tr>
+<tr><td>214</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>215</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>216</td><td>1</td><td><span class=high-hits>return lifetime_tracker_add</span></td></tr>
+</tbody></table></body></html>

coverage/testkit.luau.html

@@ -0,0 +1,617 @@
+<html><head>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/js/bootstrap.bundle.min.js"></script>
+<style>
+body { font-family: monospace; text-align: center; }
+#funcTable table { margin: 0 auto; width: auto; max-width: 300px; font-size: 14px; border-collapse: collapse; }
+#funcTable th, #funcTable td { padding: 2px 6px; text-align: left; white-space: nowrap; }
+#funcTable th { background-color: #ddd; }
+#funcTable td:nth-child(2) { text-align: right; min-width: 50px; }
+.zero-hits { background-color: #fcc; font-weight: bold; color: red; }
+.nonzero-hits { color: green; font-weight: bold; }
+.low-hits { background-color: #ffe6b3; }
+.high-hits { background-color: #cfc; }
+.source-code-table { margin-left: 10px; }th, td { padding: 0px; font-size: 12px; }
+table.table { font-size: 14px; border-collapse: collapse; }
+table.table th, table.table td { padding: 1px; font-size: 12px; line-height: 1.2; }
+table.table tr { height: auto; }
+</style></head><body>
+<h1 class="text-center">testkit.luau Coverage</h1>
+<h2>Total Execution Hits: 1826</h2>
+<h2>Function Coverage Overview: 64.52%</h2>
+<button class="btn btn-primary mb-2" type="button" data-bs-toggle="collapse" data-bs-target="#funcTable">Toggle Function Coverage</button>
+<div class="collapse show" id="funcTable">
+<h2>Function Coverage:</h2><table class="table table-bordered"><thead><tr><th>Function</th><th>Hits</th></tr></thead><tbody>
+<tr><td style="padding: 1px; min-width: 22ch;"><main></td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">white_underline:11</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">white:15</td><td style="padding: 1px; color: green; font-weight: bold;">24</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">green:19</td><td style="padding: 1px; color: green; font-weight: bold;">77</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">red:23</td><td style="padding: 1px; color: green; font-weight: bold;">146</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">yellow:27</td><td style="padding: 1px; color: green; font-weight: bold;">76</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">red_highlight:31</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">green_highlight:35</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">gray:39</td><td style="padding: 1px; color: green; font-weight: bold;">84</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">orange:43</td><td style="padding: 1px; color: green; font-weight: bold;">73</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">convert_units:48</td><td style="padding: 1px; color: green; font-weight: bold;">6</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">output_test_result:131</td><td style="padding: 1px; color: green; font-weight: bold;">24</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">CASE:169</td><td style="padding: 1px; color: green; font-weight: bold;">73</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">CHECK_EXPECT_ERR:183</td><td style="padding: 1px; color: green; font-weight: bold;">9</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">CHECK:201</td><td style="padding: 1px; color: green; font-weight: bold;">1195</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">TEST:224</td><td style="padding: 1px; color: green; font-weight: bold;">24</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">FOCUS:237</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">FINISH:248</td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;"><anonymous>:264</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">SKIP:314</td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">START:330</td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">BENCH:342</td><td style="padding: 1px; color: green; font-weight: bold;">3</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;"><anonymous>:354</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">round:372</td><td style="padding: 1px; color: green; font-weight: bold;">6</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">print2:396</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">tos:401</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">shallow_eq:480</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">deep_eq:500</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">test:533</td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">benchmark:545</td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
+<tr><td style="padding: 1px; min-width: 22ch;">disable_formatting:549</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
+</tbody></table></div>
+<h2>Source Code:</h2><table class="table table-bordered source-code-table "><thead><tr><th>Line</th><th>Hits</th><th>Code</th></tr></thead><tbody>
+<tr><td>1</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>2</td><td><span class='text-muted'>N/A</span></td><td>-- testkit.luau</td>></tr>
+<tr><td>3</td><td><span class='text-muted'>N/A</span></td><td>-- v0.7.3</td>></tr>
+<tr><td>4</td><td><span class='text-muted'>N/A</span></td><td>-- MIT License</td>></tr>
+<tr><td>5</td><td><span class='text-muted'>N/A</span></td><td>-- Copyright (c) 2022 centau</td>></tr>
+<tr><td>6</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>7</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>8</td><td>1</td><td><span class=low-hits>local disable_ansi = false</span></td></tr>
+<tr><td>9</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>10</td><td>1</td><td><span class=low-hits>local color = {</span></td></tr>
+<tr><td>11</td><td>1</td><td><span class=low-hits>white_underline = function(s: string): string</span></td></tr>
+<tr><td>12</td><td>0</td><td><span class=zero-hits>return if disable_ansi then s else `\27[1;4m{s}\27[0m`</span></td></tr>
+<tr><td>13</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>14</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>15</td><td>1</td><td><span class=low-hits>white = function(s: string): string</span></td></tr>
+<tr><td>16</td><td>24</td><td><span class=low-hits>return if disable_ansi then s else `\27[37;1m{s}\27[0m`</span></td></tr>
+<tr><td>17</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>18</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>19</td><td>1</td><td><span class=low-hits>green = function(s: string): string</span></td></tr>
+<tr><td>20</td><td>77</td><td><span class=low-hits>return if disable_ansi then s else `\27[32;1m{s}\27[0m`</span></td></tr>
+<tr><td>21</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>22</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>23</td><td>1</td><td><span class=low-hits>red = function(s: string): string</span></td></tr>
+<tr><td>24</td><td>146</td><td><span class=low-hits>return if disable_ansi then s else `\27[31;1m{s}\27[0m`</span></td></tr>
+<tr><td>25</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>26</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>27</td><td>1</td><td><span class=low-hits>yellow = function(s: string): string</span></td></tr>
+<tr><td>28</td><td>76</td><td><span class=low-hits>return if disable_ansi then s else `\27[33;1m{s}\27[0m`</span></td></tr>
+<tr><td>29</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>30</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>31</td><td>1</td><td><span class=low-hits>red_highlight = function(s: string): string</span></td></tr>
+<tr><td>32</td><td>0</td><td><span class=zero-hits>return if disable_ansi then s else `\27[41;1;30m{s}\27[0m`</span></td></tr>
+<tr><td>33</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>34</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>35</td><td>1</td><td><span class=low-hits>green_highlight = function(s: string): string</span></td></tr>
+<tr><td>36</td><td>0</td><td><span class=zero-hits>return if disable_ansi then s else `\27[42;1;30m{s}\27[0m`</span></td></tr>
+<tr><td>37</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>38</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>39</td><td>1</td><td><span class=low-hits>gray = function(s: string): string</span></td></tr>
+<tr><td>40</td><td>84</td><td><span class=low-hits>return if disable_ansi then s else `\27[38;1m{s}\27[0m`</span></td></tr>
+<tr><td>41</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>42</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>43</td><td>1</td><td><span class=low-hits>orange = function(s: string): string</span></td></tr>
+<tr><td>44</td><td>73</td><td><span class=low-hits>return if disable_ansi then s else `\27[38;5;208m{s}\27[0m`</span></td></tr>
+<tr><td>45</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>46</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+<tr><td>47</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>48</td><td>1</td><td><span class=low-hits>local function convert_units(unit: string, value: number): (number, string)</span></td></tr>
+<tr><td>49</td><td>6</td><td><span class=low-hits>local sign = math.sign(value)</span></td></tr>
+<tr><td>50</td><td>6</td><td><span class=low-hits>value = math.abs(value)</span></td></tr>
+<tr><td>51</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>52</td><td>6</td><td><span class=low-hits>local prefix_colors = {</span></td></tr>
+<tr><td>53</td><td>6</td><td><span class=low-hits>[4] = color.red,</span></td></tr>
+<tr><td>54</td><td>6</td><td><span class=low-hits>[3] = color.red,</span></td></tr>
+<tr><td>55</td><td>6</td><td><span class=low-hits>[2] = color.yellow,</span></td></tr>
+<tr><td>56</td><td>6</td><td><span class=low-hits>[1] = color.yellow,</span></td></tr>
+<tr><td>57</td><td>6</td><td><span class=low-hits>[0] = color.green,</span></td></tr>
+<tr><td>58</td><td>6</td><td><span class=low-hits>[-1] = color.red,</span></td></tr>
+<tr><td>59</td><td>6</td><td><span class=low-hits>[-2] = color.yellow,</span></td></tr>
+<tr><td>60</td><td>6</td><td><span class=low-hits>[-3] = color.green,</span></td></tr>
+<tr><td>61</td><td>6</td><td><span class=low-hits>[-4] = color.red,</span></td></tr>
+<tr><td>62</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+<tr><td>63</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>64</td><td>6</td><td><span class=low-hits>local prefixes = {</span></td></tr>
+<tr><td>65</td><td>6</td><td><span class=low-hits>[4] = "T",</span></td></tr>
+<tr><td>66</td><td>6</td><td><span class=low-hits>[3] = "G",</span></td></tr>
+<tr><td>67</td><td>6</td><td><span class=low-hits>[2] = "M",</span></td></tr>
+<tr><td>68</td><td>6</td><td><span class=low-hits>[1] = "k",</span></td></tr>
+<tr><td>69</td><td>6</td><td><span class=low-hits>[0] = " ",</span></td></tr>
+<tr><td>70</td><td>6</td><td><span class=low-hits>[-1] = "m",</span></td></tr>
+<tr><td>71</td><td>6</td><td><span class=low-hits>[-2] = "u",</span></td></tr>
+<tr><td>72</td><td>6</td><td><span class=low-hits>[-3] = "n",</span></td></tr>
+<tr><td>73</td><td>6</td><td><span class=low-hits>[-4] = "p",</span></td></tr>
+<tr><td>74</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+<tr><td>75</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>76</td><td>6</td><td><span class=low-hits>local order = 0</span></td></tr>
+<tr><td>77</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>78</td><td>7</td><td><span class=low-hits>while value >= 1000 do</span></td></tr>
+<tr><td>79</td><td>1</td><td><span class=low-hits>order += 1</span></td></tr>
+<tr><td>80</td><td>1</td><td><span class=low-hits>value /= 1000</span></td></tr>
+<tr><td>81</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>82</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>83</td><td>11</td><td><span class=low-hits>while value ~= 0 and value < 1 do</span></td></tr>
+<tr><td>84</td><td>7</td><td><span class=low-hits>order -= 1</span></td></tr>
+<tr><td>85</td><td>7</td><td><span class=low-hits>value *= 1000</span></td></tr>
+<tr><td>86</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>87</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>88</td><td>6</td><td><span class=low-hits>if value >= 100 then</span></td></tr>
+<tr><td>89</td><td>1</td><td><span class=low-hits>value = math.floor(value)</span></td></tr>
+<tr><td>90</td><td>5</td><td><span class=low-hits>elseif value >= 10 then</span></td></tr>
+<tr><td>91</td><td>2</td><td><span class=low-hits>value = math.floor(value * 1e1) / 1e1</span></td></tr>
+<tr><td>92</td><td>3</td><td><span class=low-hits>elseif value >= 1 then</span></td></tr>
+<tr><td>93</td><td>1</td><td><span class=low-hits>value = math.floor(value * 1e2) / 1e2</span></td></tr>
+<tr><td>94</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>95</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>96</td><td>6</td><td><span class=low-hits>return value * sign, prefix_colors[order](prefixes[order] .. unit)</span></td></tr>
+<tr><td>97</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>98</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>99</td><td>1</td><td><span class=low-hits>local WALL = color.gray("│")</span></td></tr>
+<tr><td>100</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>101</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>102</td><td><span class='text-muted'>N/A</span></td><td>-- Testing</td>></tr>
+<tr><td>103</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>104</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>105</td><td>0</td><td><span class=zero-hits>type Test = {</span></td></tr>
+<tr><td>106</td><td>0</td><td><span class=zero-hits>name: string,</span></td></tr>
+<tr><td>107</td><td>0</td><td><span class=zero-hits>case: Case?,</span></td></tr>
+<tr><td>108</td><td>0</td><td><span class=zero-hits>cases: { Case },</span></td></tr>
+<tr><td>109</td><td>0</td><td><span class=zero-hits>duration: number,</span></td></tr>
+<tr><td>110</td><td>0</td><td><span class=zero-hits>error: {</span></td></tr>
+<tr><td>111</td><td>0</td><td><span class=zero-hits>message: string,</span></td></tr>
+<tr><td>112</td><td>0</td><td><span class=zero-hits>trace: string,</span></td></tr>
+<tr><td>113</td><td>0</td><td><span class=zero-hits>}?,</span></td></tr>
+<tr><td>114</td><td>0</td><td><span class=zero-hits>focus: boolean,</span></td></tr>
+<tr><td>115</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+<tr><td>116</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>117</td><td>0</td><td><span class=zero-hits>type Case = {</span></td></tr>
+<tr><td>118</td><td>0</td><td><span class=zero-hits>name: string,</span></td></tr>
+<tr><td>119</td><td>0</td><td><span class=zero-hits>result: number,</span></td></tr>
+<tr><td>120</td><td>0</td><td><span class=zero-hits>line: number?,</span></td></tr>
+<tr><td>121</td><td>0</td><td><span class=zero-hits>focus: boolean,</span></td></tr>
+<tr><td>122</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+<tr><td>123</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>124</td><td>1</td><td><span class=low-hits>local PASS, FAIL, NONE, ERROR, SKIPPED = 1, 2, 3, 4, 5</span></td></tr>
+<tr><td>125</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>126</td><td>1</td><td><span class=low-hits>local check_for_focused = false</span></td></tr>
+<tr><td>127</td><td>1</td><td><span class=low-hits>local skip = false</span></td></tr>
+<tr><td>128</td><td>1</td><td><span class=low-hits>local test: Test?</span></td></tr>
+<tr><td>129</td><td>1</td><td><span class=low-hits>local tests: { Test } = {}</span></td></tr>
+<tr><td>130</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>131</td><td>1</td><td><span class=low-hits>local function output_test_result(test: Test)</span></td></tr>
+<tr><td>132</td><td>24</td><td><span class=low-hits>if check_for_focused then</span></td></tr>
+<tr><td>133</td><td>0</td><td><span class=zero-hits>local any_focused = test.focus</span></td></tr>
+<tr><td>134</td><td>0</td><td><span class=zero-hits>for _, case in test.cases do</span></td></tr>
+<tr><td>135</td><td>0</td><td><span class=zero-hits>any_focused = any_focused or case.focus</span></td></tr>
+<tr><td>136</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>137</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>138</td><td>0</td><td><span class=zero-hits>if not any_focused then</span></td></tr>
+<tr><td>139</td><td>0</td><td><span class=zero-hits>return</span></td></tr>
+<tr><td>140</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>141</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>142</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>143</td><td>24</td><td><span class=low-hits>print(color.white(test.name))</span></td></tr>
+<tr><td>144</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>145</td><td>24</td><td><span class=low-hits>for _, case in test.cases do</span></td></tr>
+<tr><td>146</td><td>73</td><td><span class=low-hits>local status = ({</span></td></tr>
+<tr><td>147</td><td>73</td><td><span class=low-hits>[PASS] = color.green("PASS"),</span></td></tr>
+<tr><td>148</td><td>73</td><td><span class=low-hits>[FAIL] = color.red("FAIL"),</span></td></tr>
+<tr><td>149</td><td>73</td><td><span class=low-hits>[NONE] = color.orange("NONE"),</span></td></tr>
+<tr><td>150</td><td>73</td><td><span class=low-hits>[ERROR] = color.red("FAIL"),</span></td></tr>
+<tr><td>151</td><td>73</td><td><span class=low-hits>[SKIPPED] = color.yellow("SKIP"),</span></td></tr>
+<tr><td>152</td><td>73</td><td><span class=low-hits>})[case.result]</span></td></tr>
+<tr><td>153</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>154</td><td>73</td><td><span class=low-hits>local line = case.result == FAIL and color.red(`{case.line}:`) or ""</span></td></tr>
+<tr><td>155</td><td>73</td><td><span class=low-hits>if check_for_focused and case.focus == false and test.focus == false then</span></td></tr>
+<tr><td>156</td><td>0</td><td><span class=zero-hits>continue</span></td></tr>
+<tr><td>157</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>158</td><td>73</td><td><span class=low-hits>print(`{status}{WALL} {line}{color.gray(case.name)}`)</span></td></tr>
+<tr><td>159</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>160</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>161</td><td>24</td><td><span class=low-hits>if test.error then</span></td></tr>
+<tr><td>162</td><td>0</td><td><span class=zero-hits>print(color.gray("error: ") .. color.red(test.error.message))</span></td></tr>
+<tr><td>163</td><td>0</td><td><span class=zero-hits>print(color.gray("trace: ") .. color.red(test.error.trace))</span></td></tr>
+<tr><td>164</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
+<tr><td>165</td><td>24</td><td><span class=low-hits>print()</span></td></tr>
+<tr><td>166</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>167</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>168</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>169</td><td>1</td><td><span class=low-hits>local function CASE(name: string)</span></td></tr>
+<tr><td>170</td><td>73</td><td><span class=low-hits>skip = false</span></td></tr>
+<tr><td>171</td><td>73</td><td><span class=low-hits>assert(test, "no active test")</span></td></tr>
+<tr><td>172</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>173</td><td>73</td><td><span class=low-hits>local case = {</span></td></tr>
+<tr><td>174</td><td>73</td><td><span class=low-hits>name = name,</span></td></tr>
+<tr><td>175</td><td>73</td><td><span class=low-hits>result = NONE,</span></td></tr>
+<tr><td>176</td><td>73</td><td><span class=low-hits>focus = false,</span></td></tr>
+<tr><td>177</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+<tr><td>178</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>179</td><td>73</td><td><span class=low-hits>test.case = case</span></td></tr>
+<tr><td>180</td><td>73</td><td><span class=low-hits>table.insert(test.cases, case)</span></td></tr>
+<tr><td>181</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>182</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>183</td><td>1</td><td><span class=low-hits>local function CHECK_EXPECT_ERR(fn, ...)</span></td></tr>
+<tr><td>184</td><td>9</td><td><span class=low-hits>assert(test, "no active test")</span></td></tr>
+<tr><td>185</td><td>9</td><td><span class=low-hits>local case = test.case</span></td></tr>
+<tr><td>186</td><td>9</td><td><span class=low-hits>if not case then</span></td></tr>
+<tr><td>187</td><td>0</td><td><span class=zero-hits>CASE("")</span></td></tr>
+<tr><td>188</td><td>0</td><td><span class=zero-hits>case = test.case</span></td></tr>
+<tr><td>189</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>190</td><td>9</td><td><span class=low-hits>assert(case, "no active case")</span></td></tr>
+<tr><td>191</td><td>9</td><td><span class=low-hits>if case.result ~= FAIL then</span></td></tr>
+<tr><td>192</td><td>9</td><td><span class=low-hits>local ok, err = pcall(fn, ...)</span></td></tr>
+<tr><td>193</td><td>9</td><td><span class=low-hits>case.result = if ok then FAIL else PASS</span></td></tr>
+<tr><td>194</td><td>9</td><td><span class=low-hits>if skip then</span></td></tr>
+<tr><td>195</td><td>0</td><td><span class=zero-hits>case.result = SKIPPED</span></td></tr>
+<tr><td>196</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>197</td><td>9</td><td><span class=low-hits>case.line = debug.info(stack and stack + 1 or 2, "l")</span></td></tr>
+<tr><td>198</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>199</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>200</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>201</td><td>1</td><td><span class=low-hits>local function CHECK<T>(value: T, stack: number?): T?</span></td></tr>
+<tr><td>202</td><td>1195</td><td><span class=high-hits>assert(test, "no active test")</span></td></tr>
+<tr><td>203</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>204</td><td>1195</td><td><span class=high-hits>local case = test.case</span></td></tr>
+<tr><td>205</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>206</td><td>1195</td><td><span class=high-hits>if not case then</span></td></tr>
+<tr><td>207</td><td>9</td><td><span class=low-hits>CASE("")</span></td></tr>
+<tr><td>208</td><td>9</td><td><span class=low-hits>case = test.case</span></td></tr>
+<tr><td>209</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>210</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>211</td><td>1195</td><td><span class=high-hits>assert(case, "no active case")</span></td></tr>
+<tr><td>212</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>213</td><td>1195</td><td><span class=high-hits>if case.result ~= FAIL then</span></td></tr>
+<tr><td>214</td><td>1195</td><td><span class=high-hits>case.result = value and PASS or FAIL</span></td></tr>
+<tr><td>215</td><td>1195</td><td><span class=high-hits>if skip then</span></td></tr>
+<tr><td>216</td><td>1</td><td><span class=low-hits>case.result = SKIPPED</span></td></tr>
+<tr><td>217</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>218</td><td>1195</td><td><span class=high-hits>case.line = debug.info(stack and stack + 1 or 2, "l")</span></td></tr>
+<tr><td>219</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>220</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>221</td><td>1195</td><td><span class=high-hits>return value</span></td></tr>
+<tr><td>222</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>223</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>224</td><td>1</td><td><span class=low-hits>local function TEST(name: string, fn: () -> ())</span></td></tr>
+<tr><td>225</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>226</td><td>24</td><td><span class=low-hits>test = {</span></td></tr>
+<tr><td>227</td><td>24</td><td><span class=low-hits>name = name,</span></td></tr>
+<tr><td>228</td><td>24</td><td><span class=low-hits>cases = {},</span></td></tr>
+<tr><td>229</td><td>24</td><td><span class=low-hits>duration = 0,</span></td></tr>
+<tr><td>230</td><td>24</td><td><span class=low-hits>focus = false,</span></td></tr>
+<tr><td>231</td><td>24</td><td><span class=low-hits>fn = fn</span></td></tr>
+<tr><td>232</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+<tr><td>233</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>234</td><td>24</td><td><span class=low-hits>table.insert(tests, test)</span></td></tr>
+<tr><td>235</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>236</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>237</td><td>1</td><td><span class=low-hits>local function FOCUS()</span></td></tr>
+<tr><td>238</td><td>0</td><td><span class=zero-hits>assert(test, "no active test")</span></td></tr>
+<tr><td>239</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>240</td><td>0</td><td><span class=zero-hits>check_for_focused = true</span></td></tr>
+<tr><td>241</td><td>0</td><td><span class=zero-hits>if test.case then</span></td></tr>
+<tr><td>242</td><td>0</td><td><span class=zero-hits>test.case.focus = true</span></td></tr>
+<tr><td>243</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
+<tr><td>244</td><td>0</td><td><span class=zero-hits>test.focus = true</span></td></tr>
+<tr><td>245</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>246</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>247</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>248</td><td>1</td><td><span class=low-hits>local function FINISH(): boolean</span></td></tr>
+<tr><td>249</td><td>1</td><td><span class=low-hits>local success = true</span></td></tr>
+<tr><td>250</td><td>1</td><td><span class=low-hits>local total_cases = 0</span></td></tr>
+<tr><td>251</td><td>1</td><td><span class=low-hits>local passed_cases = 0</span></td></tr>
+<tr><td>252</td><td>1</td><td><span class=low-hits>local passed_focus_cases = 0</span></td></tr>
+<tr><td>253</td><td>1</td><td><span class=low-hits>local total_focus_cases = 0</span></td></tr>
+<tr><td>254</td><td>1</td><td><span class=low-hits>local duration = 0</span></td></tr>
+<tr><td>255</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>256</td><td>1</td><td><span class=low-hits>for _, t in tests do</span></td></tr>
+<tr><td>257</td><td>24</td><td><span class=low-hits>if check_for_focused and not t.focus then</span></td></tr>
+<tr><td>258</td><td>0</td><td><span class=zero-hits>continue</span></td></tr>
+<tr><td>259</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>260</td><td>24</td><td><span class=low-hits>test = t</span></td></tr>
+<tr><td>261</td><td>24</td><td><span class=low-hits>fn = t.fn</span></td></tr>
+<tr><td>262</td><td>24</td><td><span class=low-hits>local start = os.clock()</span></td></tr>
+<tr><td>263</td><td>24</td><td><span class=low-hits>local err</span></td></tr>
+<tr><td>264</td><td>24</td><td><span class=low-hits>local success = xpcall(fn, function(m: string)</span></td></tr>
+<tr><td>265</td><td>0</td><td><span class=zero-hits>err = { message = m, trace = debug.traceback(nil, 2) }</span></td></tr>
+<tr><td>266</td><td><span class='text-muted'>N/A</span></td><td>end)</td>></tr>
+<tr><td>267</td><td>24</td><td><span class=low-hits>test.duration = os.clock() - start</span></td></tr>
+<tr><td>268</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>269</td><td>24</td><td><span class=low-hits>if not test.case then</span></td></tr>
+<tr><td>270</td><td>0</td><td><span class=zero-hits>CASE("")</span></td></tr>
+<tr><td>271</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>272</td><td>24</td><td><span class=low-hits>assert(test.case, "no active case")</span></td></tr>
+<tr><td>273</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>274</td><td>24</td><td><span class=low-hits>if not success then</span></td></tr>
+<tr><td>275</td><td>0</td><td><span class=zero-hits>test.case.result = ERROR</span></td></tr>
+<tr><td>276</td><td>0</td><td><span class=zero-hits>test.error = err</span></td></tr>
+<tr><td>277</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>278</td><td>24</td><td><span class=low-hits>collectgarbage()</span></td></tr>
+<tr><td>279</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>280</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>281</td><td>1</td><td><span class=low-hits>for _, test in tests do</span></td></tr>
+<tr><td>282</td><td>24</td><td><span class=low-hits>duration += test.duration</span></td></tr>
+<tr><td>283</td><td>24</td><td><span class=low-hits>for _, case in test.cases do</span></td></tr>
+<tr><td>284</td><td>73</td><td><span class=low-hits>total_cases += 1</span></td></tr>
+<tr><td>285</td><td>73</td><td><span class=low-hits>if case.focus or test.focus then</span></td></tr>
+<tr><td>286</td><td>0</td><td><span class=zero-hits>total_focus_cases += 1</span></td></tr>
+<tr><td>287</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>288</td><td>73</td><td><span class=low-hits>if case.result == PASS or case.result == NONE or case.result == SKIPPED then</span></td></tr>
+<tr><td>289</td><td>73</td><td><span class=low-hits>if case.focus or test.focus then</span></td></tr>
+<tr><td>290</td><td>0</td><td><span class=zero-hits>passed_focus_cases += 1</span></td></tr>
+<tr><td>291</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>292</td><td>73</td><td><span class=low-hits>passed_cases += 1</span></td></tr>
+<tr><td>293</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
+<tr><td>294</td><td>0</td><td><span class=zero-hits>success = false</span></td></tr>
+<tr><td>295</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>296</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>297</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>298</td><td>24</td><td><span class=low-hits>output_test_result(test)</span></td></tr>
+<tr><td>299</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>300</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>301</td><td>1</td><td><span class=low-hits>print(color.gray(string.format(`{passed_cases}/{total_cases} test cases passed in %.3f ms.`, duration * 1e3)))</span></td></tr>
+<tr><td>302</td><td>1</td><td><span class=low-hits>if check_for_focused then</span></td></tr>
+<tr><td>303</td><td>0</td><td><span class=zero-hits>print(color.gray(`{passed_focus_cases}/{total_focus_cases} focused test cases passed`))</span></td></tr>
+<tr><td>304</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>305</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>306</td><td>1</td><td><span class=low-hits>local fails = total_cases - passed_cases</span></td></tr>
+<tr><td>307</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>308</td><td>1</td><td><span class=low-hits>print((fails > 0 and color.red or color.green)(`{fails} {fails == 1 and "fail" or "fails"}`))</span></td></tr>
+<tr><td>309</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>310</td><td>1</td><td><span class=low-hits>check_for_focused = false</span></td></tr>
+<tr><td>311</td><td>1</td><td><span class=low-hits>return success, table.clear(tests)</span></td></tr>
+<tr><td>312</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>313</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>314</td><td>1</td><td><span class=low-hits>local function SKIP()</span></td></tr>
+<tr><td>315</td><td>1</td><td><span class=low-hits>skip = true</span></td></tr>
+<tr><td>316</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>317</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>318</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>319</td><td><span class='text-muted'>N/A</span></td><td>-- Benchmarking</td>></tr>
+<tr><td>320</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>321</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>322</td><td>0</td><td><span class=zero-hits>type Bench = {</span></td></tr>
+<tr><td>323</td><td>0</td><td><span class=zero-hits>time_start: number?,</span></td></tr>
+<tr><td>324</td><td>0</td><td><span class=zero-hits>memory_start: number?,</span></td></tr>
+<tr><td>325</td><td>0</td><td><span class=zero-hits>iterations: number?,</span></td></tr>
+<tr><td>326</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+<tr><td>327</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>328</td><td>1</td><td><span class=low-hits>local bench: Bench?</span></td></tr>
+<tr><td>329</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>330</td><td>1</td><td><span class=low-hits>function START(iter: number?): number</span></td></tr>
+<tr><td>331</td><td>1</td><td><span class=low-hits>local n = iter or 1</span></td></tr>
+<tr><td>332</td><td>1</td><td><span class=low-hits>assert(n > 0, "iterations must be greater than 0")</span></td></tr>
+<tr><td>333</td><td>1</td><td><span class=low-hits>assert(bench, "no active benchmark")</span></td></tr>
+<tr><td>334</td><td>1</td><td><span class=low-hits>assert(not bench.time_start, "clock was already started")</span></td></tr>
+<tr><td>335</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>336</td><td>1</td><td><span class=low-hits>bench.iterations = n</span></td></tr>
+<tr><td>337</td><td>1</td><td><span class=low-hits>bench.memory_start = gcinfo()</span></td></tr>
+<tr><td>338</td><td>1</td><td><span class=low-hits>bench.time_start = os.clock()</span></td></tr>
+<tr><td>339</td><td>1</td><td><span class=low-hits>return n</span></td></tr>
+<tr><td>340</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>341</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>342</td><td>1</td><td><span class=low-hits>local function BENCH(name: string, fn: () -> ())</span></td></tr>
+<tr><td>343</td><td>3</td><td><span class=low-hits>local active = bench</span></td></tr>
+<tr><td>344</td><td>3</td><td><span class=low-hits>assert(not active, "a benchmark is already in progress")</span></td></tr>
+<tr><td>345</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>346</td><td>3</td><td><span class=low-hits>bench = {}</span></td></tr>
+<tr><td>347</td><td>3</td><td><span class=low-hits>assert(bench);</span></td></tr>
+<tr><td>348</td><td>3</td><td><span class=low-hits>(collectgarbage :: any)("collect")</span></td></tr>
+<tr><td>349</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>350</td><td>3</td><td><span class=low-hits>local mem_start = gcinfo()</span></td></tr>
+<tr><td>351</td><td>3</td><td><span class=low-hits>local time_start = os.clock()</span></td></tr>
+<tr><td>352</td><td>3</td><td><span class=low-hits>local err_msg: string?</span></td></tr>
+<tr><td>353</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>354</td><td>3</td><td><span class=low-hits>local success = xpcall(fn, function(m: string)</span></td></tr>
+<tr><td>355</td><td>0</td><td><span class=zero-hits>err_msg = m .. debug.traceback(nil, 2)</span></td></tr>
+<tr><td>356</td><td><span class='text-muted'>N/A</span></td><td>end)</td>></tr>
+<tr><td>357</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>358</td><td>3</td><td><span class=low-hits>local time_stop = os.clock()</span></td></tr>
+<tr><td>359</td><td>3</td><td><span class=low-hits>local mem_stop = gcinfo()</span></td></tr>
+<tr><td>360</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>361</td><td>3</td><td><span class=low-hits>if not success then</span></td></tr>
+<tr><td>362</td><td>0</td><td><span class=zero-hits>print(`{WALL}{color.red("ERROR")}{WALL} {name}`)</span></td></tr>
+<tr><td>363</td><td>0</td><td><span class=zero-hits>print(color.gray(err_msg :: string))</span></td></tr>
+<tr><td>364</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
+<tr><td>365</td><td>3</td><td><span class=low-hits>time_start = bench.time_start or time_start</span></td></tr>
+<tr><td>366</td><td>3</td><td><span class=low-hits>mem_start = bench.memory_start or mem_start</span></td></tr>
+<tr><td>367</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>368</td><td>3</td><td><span class=low-hits>local n = bench.iterations or 1</span></td></tr>
+<tr><td>369</td><td>3</td><td><span class=low-hits>local d, d_unit = convert_units("s", (time_stop - time_start) / n)</span></td></tr>
+<tr><td>370</td><td>3</td><td><span class=low-hits>local a, a_unit = convert_units("B", math.round((mem_stop - mem_start) / n * 1e3))</span></td></tr>
+<tr><td>371</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>372</td><td>3</td><td><span class=low-hits>local function round(x: number): string</span></td></tr>
+<tr><td>373</td><td>6</td><td><span class=low-hits>return x > 0 and x < 10 and (x - math.floor(x)) > 0 and string.format("%2.1f", x)</span></td></tr>
+<tr><td>374</td><td>6</td><td><span class=low-hits>or string.format("%3.f", x)</span></td></tr>
+<tr><td>375</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>376</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>377</td><td>3</td><td><span class=low-hits>print(</span></td></tr>
+<tr><td>378</td><td>3</td><td><span class=low-hits>string.format(</span></td></tr>
+<tr><td>379</td><td>3</td><td><span class=low-hits>`%s %s %s %s{WALL} %s`,</span></td></tr>
+<tr><td>380</td><td>3</td><td><span class=low-hits>color.gray(round(d)),</span></td></tr>
+<tr><td>381</td><td>3</td><td><span class=low-hits>d_unit,</span></td></tr>
+<tr><td>382</td><td>3</td><td><span class=low-hits>color.gray(round(a)),</span></td></tr>
+<tr><td>383</td><td>3</td><td><span class=low-hits>a_unit,</span></td></tr>
+<tr><td>384</td><td>3</td><td><span class=low-hits>color.gray(name)</span></td></tr>
+<tr><td>385</td><td>0</td><td><span class=zero-hits>)</span></td></tr>
+<tr><td>386</td><td>0</td><td><span class=zero-hits>)</span></td></tr>
+<tr><td>387</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>388</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>389</td><td>3</td><td><span class=low-hits>bench = nil</span></td></tr>
+<tr><td>390</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>391</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>392</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>393</td><td><span class='text-muted'>N/A</span></td><td>-- Printing</td>></tr>
+<tr><td>394</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>395</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>396</td><td>1</td><td><span class=low-hits>local function print2(v: unknown)</span></td></tr>
+<tr><td>397</td><td>0</td><td><span class=zero-hits>type Buffer = { n: number, [number]: string }</span></td></tr>
+<tr><td>398</td><td>0</td><td><span class=zero-hits>type Cyclic = { n: number, [{}]: number }</span></td></tr>
+<tr><td>399</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>400</td><td><span class='text-muted'>N/A</span></td><td>-- overkill concatenationless string buffer</td>></tr>
+<tr><td>401</td><td>0</td><td><span class=zero-hits>local function tos(value: any, stack: number, str: Buffer, cyclic: Cyclic)</span></td></tr>
+<tr><td>402</td><td>0</td><td><span class=zero-hits>local TAB = "    "</span></td></tr>
+<tr><td>403</td><td>0</td><td><span class=zero-hits>local indent = table.concat(table.create(stack, TAB))</span></td></tr>
+<tr><td>404</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>405</td><td>0</td><td><span class=zero-hits>if type(value) == "string" then</span></td></tr>
+<tr><td>406</td><td>0</td><td><span class=zero-hits>local n = str.n</span></td></tr>
+<tr><td>407</td><td>0</td><td><span class=zero-hits>str[n + 1] = "\""</span></td></tr>
+<tr><td>408</td><td>0</td><td><span class=zero-hits>str[n + 2] = value</span></td></tr>
+<tr><td>409</td><td>0</td><td><span class=zero-hits>str[n + 3] = "\""</span></td></tr>
+<tr><td>410</td><td>0</td><td><span class=zero-hits>str.n = n + 3</span></td></tr>
+<tr><td>411</td><td>0</td><td><span class=zero-hits>elseif type(value) ~= "table" then</span></td></tr>
+<tr><td>412</td><td>0</td><td><span class=zero-hits>local n = str.n</span></td></tr>
+<tr><td>413</td><td>0</td><td><span class=zero-hits>str[n + 1] = value == nil and "nil" or tostring(value)</span></td></tr>
+<tr><td>414</td><td>0</td><td><span class=zero-hits>str.n = n + 1</span></td></tr>
+<tr><td>415</td><td>0</td><td><span class=zero-hits>elseif next(value) == nil then</span></td></tr>
+<tr><td>416</td><td>0</td><td><span class=zero-hits>local n = str.n</span></td></tr>
+<tr><td>417</td><td>0</td><td><span class=zero-hits>str[n + 1] = "{}"</span></td></tr>
+<tr><td>418</td><td>0</td><td><span class=zero-hits>str.n = n + 1</span></td></tr>
+<tr><td>419</td><td>0</td><td><span class=zero-hits>else -- is table</span></td></tr>
+<tr><td>420</td><td>0</td><td><span class=zero-hits>local tabbed_indent = indent .. TAB</span></td></tr>
+<tr><td>421</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>422</td><td>0</td><td><span class=zero-hits>if cyclic[value] then</span></td></tr>
+<tr><td>423</td><td>0</td><td><span class=zero-hits>str.n += 1</span></td></tr>
+<tr><td>424</td><td>0</td><td><span class=zero-hits>str[str.n] = color.gray(`CYCLIC REF {cyclic[value]}`)</span></td></tr>
+<tr><td>425</td><td>0</td><td><span class=zero-hits>return</span></td></tr>
+<tr><td>426</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
+<tr><td>427</td><td>0</td><td><span class=zero-hits>cyclic.n += 1</span></td></tr>
+<tr><td>428</td><td>0</td><td><span class=zero-hits>cyclic[value] = cyclic.n</span></td></tr>
+<tr><td>429</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>430</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>431</td><td>0</td><td><span class=zero-hits>str.n += 3</span></td></tr>
+<tr><td>432</td><td>0</td><td><span class=zero-hits>str[str.n - 2] = "{ "</span></td></tr>
+<tr><td>433</td><td>0</td><td><span class=zero-hits>str[str.n - 1] = color.gray(tostring(cyclic[value]))</span></td></tr>
+<tr><td>434</td><td>0</td><td><span class=zero-hits>str[str.n - 0] = "\n"</span></td></tr>
+<tr><td>435</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>436</td><td>0</td><td><span class=zero-hits>local i, v = next(value, nil)</span></td></tr>
+<tr><td>437</td><td>0</td><td><span class=zero-hits>while v ~= nil do</span></td></tr>
+<tr><td>438</td><td>0</td><td><span class=zero-hits>local n = str.n</span></td></tr>
+<tr><td>439</td><td>0</td><td><span class=zero-hits>str[n + 1] = tabbed_indent</span></td></tr>
+<tr><td>440</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>441</td><td>0</td><td><span class=zero-hits>if type(i) ~= "string" then</span></td></tr>
+<tr><td>442</td><td>0</td><td><span class=zero-hits>str[n + 2] = "["</span></td></tr>
+<tr><td>443</td><td>0</td><td><span class=zero-hits>str[n + 3] = tostring(i)</span></td></tr>
+<tr><td>444</td><td>0</td><td><span class=zero-hits>str[n + 4] = "]"</span></td></tr>
+<tr><td>445</td><td>0</td><td><span class=zero-hits>n += 4</span></td></tr>
+<tr><td>446</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
+<tr><td>447</td><td>0</td><td><span class=zero-hits>str[n + 2] = tostring(i)</span></td></tr>
+<tr><td>448</td><td>0</td><td><span class=zero-hits>n += 2</span></td></tr>
+<tr><td>449</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>450</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>451</td><td>0</td><td><span class=zero-hits>str[n + 1] = " = "</span></td></tr>
+<tr><td>452</td><td>0</td><td><span class=zero-hits>str.n = n + 1</span></td></tr>
+<tr><td>453</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>454</td><td>0</td><td><span class=zero-hits>tos(v, stack + 1, str, cyclic)</span></td></tr>
+<tr><td>455</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>456</td><td>0</td><td><span class=zero-hits>i, v = next(value, i)</span></td></tr>
+<tr><td>457</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>458</td><td>0</td><td><span class=zero-hits>n = str.n</span></td></tr>
+<tr><td>459</td><td>0</td><td><span class=zero-hits>str[n + 1] = v ~= nil and ",\n" or "\n"</span></td></tr>
+<tr><td>460</td><td>0</td><td><span class=zero-hits>str.n = n + 1</span></td></tr>
+<tr><td>461</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>462</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>463</td><td>0</td><td><span class=zero-hits>local n = str.n</span></td></tr>
+<tr><td>464</td><td>0</td><td><span class=zero-hits>str[n + 1] = indent</span></td></tr>
+<tr><td>465</td><td>0</td><td><span class=zero-hits>str[n + 2] = "}"</span></td></tr>
+<tr><td>466</td><td>0</td><td><span class=zero-hits>str.n = n + 2</span></td></tr>
+<tr><td>467</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>468</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>469</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>470</td><td>0</td><td><span class=zero-hits>local str = { n = 0 }</span></td></tr>
+<tr><td>471</td><td>0</td><td><span class=zero-hits>local cyclic = { n = 0 }</span></td></tr>
+<tr><td>472</td><td>0</td><td><span class=zero-hits>tos(v, 0, str, cyclic)</span></td></tr>
+<tr><td>473</td><td>0</td><td><span class=zero-hits>print(table.concat(str))</span></td></tr>
+<tr><td>474</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>475</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>476</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>477</td><td><span class='text-muted'>N/A</span></td><td>-- Equality</td>></tr>
+<tr><td>478</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>479</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>480</td><td>1</td><td><span class=low-hits>local function shallow_eq(a: {}, b: {}): boolean</span></td></tr>
+<tr><td>481</td><td>0</td><td><span class=zero-hits>if #a ~= #b then</span></td></tr>
+<tr><td>482</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
+<tr><td>483</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>484</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>485</td><td>0</td><td><span class=zero-hits>for i, v in next, a do</span></td></tr>
+<tr><td>486</td><td>0</td><td><span class=zero-hits>if b[i] ~= v then</span></td></tr>
+<tr><td>487</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
+<tr><td>488</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>489</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>490</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>491</td><td>0</td><td><span class=zero-hits>for i, v in next, b do</span></td></tr>
+<tr><td>492</td><td>0</td><td><span class=zero-hits>if a[i] ~= v then</span></td></tr>
+<tr><td>493</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
+<tr><td>494</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>495</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>496</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>497</td><td>0</td><td><span class=zero-hits>return true</span></td></tr>
+<tr><td>498</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>499</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>500</td><td>1</td><td><span class=low-hits>local function deep_eq(a: {}, b: {}): boolean</span></td></tr>
+<tr><td>501</td><td>0</td><td><span class=zero-hits>if #a ~= #b then</span></td></tr>
+<tr><td>502</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
+<tr><td>503</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>504</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>505</td><td>0</td><td><span class=zero-hits>for i, v in next, a do</span></td></tr>
+<tr><td>506</td><td>0</td><td><span class=zero-hits>if type(b[i]) == "table" and type(v) == "table" then</span></td></tr>
+<tr><td>507</td><td>0</td><td><span class=zero-hits>if deep_eq(b[i], v) == false then</span></td></tr>
+<tr><td>508</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
+<tr><td>509</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>510</td><td>0</td><td><span class=zero-hits>elseif b[i] ~= v then</span></td></tr>
+<tr><td>511</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
+<tr><td>512</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>513</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>514</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>515</td><td>0</td><td><span class=zero-hits>for i, v in next, b do</span></td></tr>
+<tr><td>516</td><td>0</td><td><span class=zero-hits>if type(a[i]) == "table" and type(v) == "table" then</span></td></tr>
+<tr><td>517</td><td>0</td><td><span class=zero-hits>if deep_eq(a[i], v) == false then</span></td></tr>
+<tr><td>518</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
+<tr><td>519</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>520</td><td>0</td><td><span class=zero-hits>elseif a[i] ~= v then</span></td></tr>
+<tr><td>521</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
+<tr><td>522</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>523</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>524</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>525</td><td>0</td><td><span class=zero-hits>return true</span></td></tr>
+<tr><td>526</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
+<tr><td>527</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>528</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>529</td><td><span class='text-muted'>N/A</span></td><td>-- Return</td>></tr>
+<tr><td>530</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
+<tr><td>531</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>532</td><td>1</td><td><span class=low-hits>return {</span></td></tr>
+<tr><td>533</td><td>1</td><td><span class=low-hits>test = function()</span></td></tr>
+<tr><td>534</td><td>1</td><td><span class=low-hits>return {</span></td></tr>
+<tr><td>535</td><td>1</td><td><span class=low-hits>TEST = TEST,</span></td></tr>
+<tr><td>536</td><td>1</td><td><span class=low-hits>CASE = CASE,</span></td></tr>
+<tr><td>537</td><td>1</td><td><span class=low-hits>CHECK = CHECK,</span></td></tr>
+<tr><td>538</td><td>1</td><td><span class=low-hits>FINISH = FINISH,</span></td></tr>
+<tr><td>539</td><td>1</td><td><span class=low-hits>SKIP = SKIP,</span></td></tr>
+<tr><td>540</td><td>1</td><td><span class=low-hits>FOCUS = FOCUS,</span></td></tr>
+<tr><td>541</td><td>1</td><td><span class=low-hits>CHECK_EXPECT_ERR = CHECK_EXPECT_ERR,</span></td></tr>
+<tr><td>542</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+<tr><td>543</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>544</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>545</td><td>1</td><td><span class=low-hits>benchmark = function()</span></td></tr>
+<tr><td>546</td><td>1</td><td><span class=low-hits>return BENCH, START</span></td></tr>
+<tr><td>547</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>548</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>549</td><td>1</td><td><span class=low-hits>disable_formatting = function()</span></td></tr>
+<tr><td>550</td><td>0</td><td><span class=zero-hits>disable_ansi = true</span></td></tr>
+<tr><td>551</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
+<tr><td>552</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>553</td><td>1</td><td><span class=low-hits>print = print2,</span></td></tr>
+<tr><td>554</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>555</td><td>1</td><td><span class=low-hits>seq = shallow_eq,</span></td></tr>
+<tr><td>556</td><td>1</td><td><span class=low-hits>deq = deep_eq,</span></td></tr>
+<tr><td>557</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
+<tr><td>558</td><td>1</td><td><span class=low-hits>color = color,</span></td></tr>
+<tr><td>559</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
+</tbody></table></body></html>

demo/src/ReplicatedStorage/std/scheduler.luau

@@ -56,17 +56,21 @@ world:set(PreSimulation, Event, RunService.PreSimulation)
 world:add(PreAnimation, Phase)
 world:set(PreAnimation, Event, RunService.PreAnimation)
 
-table.insert(jabby.public, {
-	class_name = "World",
+jabby.register({
+	applet = jabby.applets.world,
 	name = "MyWorld",
+	configuration = {
 	world = world,
-	debug = Name,
-	entities = {},
+	},
 })
 
-jabby.public.updated = true
-
-table.insert(jabby.public, jabby_scheduler)
+jabby.register({
+	applet = jabby.applets.scheduler,
+	name = "Scheduler",
+	configuration = {
+		scheduler = jabby_scheduler,
+	},
+})
 
 if RunService:IsClient() then 
 	world:add(PreRender, Phase)

demo/src/ReplicatedStorage/track.luau

@@ -0,0 +1,48 @@
+local events = {}
+
+local function trackers_invoke(event, component, entity, ...)
+	local trackers = events[event][component]
+	if not trackers then
+		return
+	end
+
+	for _, tracker in trackers do
+		tracker(entity, data)
+	end
+end
+
+local function trackers_init(event, component, fn)
+	local ob = events[event]
+
+	return {
+		connect = function(component, fn)
+			local trackers = ob[component]
+			if not trackers then
+				trackers = {}
+				ob[component] = trackers
+			end
+
+			table.insert(trackers, fn)
+		end,
+		invoke = function(component, ...)
+			trackers_invoke(event, component, ...)
+		end
+	}
+	return function(component, fn)
+		local trackers = ob[component]
+		if not trackers then
+			trackers = {}
+			ob[component] = trackers
+		end
+
+		table.insert(trackers, fn)
+	end
+end
+
+local trackers = {
+	emplace = trackers_init("emplace"),
+	add = trackers_init("added"),
+	remove = trackers_init("removed")
+}
+
+return trackers

demo/src/StarterPlayer/StarterPlayerScripts/systems/lol.luau

@@ -0,0 +1,67 @@
+--!optimize 2
+--!native
+--!strict
+
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local jecs = require(ReplicatedStorage.ecs)
+local __ = jecs.Wildcard
+local std = ReplicatedStorage.std
+
+local world = require(std.world)
+
+local Position = world:component() :: jecs.Entity<vector>
+local Previous = jecs.Rest
+local pre = jecs.pair(Position, Previous)
+
+local added = world
+	:query(Position)
+	:without(pre)
+	:cached()
+local changed = world
+	:query(Position, pre)
+	:cached()
+local removed = world
+	:query(pre)
+	:without(Position)
+	:cached()
+
+local children = {}
+for i = 1, 10 do
+	local e = world:entity()
+	world:set(e, Position, vector.create(i, i, i))
+	table.insert(children, e)
+end
+local function flip()
+	return math.random() > 0.5
+end
+local function system()
+	for i, child in children do
+		world:set(child, Position, vector.create(i,i,i))
+	end
+	for e, p in added:iter() do
+		world:set(e, pre, p)
+	end
+	for i, child in children do
+		if flip() then
+			world:set(child, Position, vector.create(i + 1, i + 1, i + 1))
+		end
+	end
+	for e, new, old in changed:iter() do
+		if new ~= old then
+			world:set(e, pre, new)
+		end
+	end
+
+	for i, child in children do
+		world:remove(child, Position)
+	end
+
+	for e in removed:iter() do
+		world:remove(e, pre)
+	end
+end
+local scheduler = require(std.scheduler)
+
+scheduler.SYSTEM(system)
+
+return 0

demo/src/StarterPlayer/StarterPlayerScripts/systems/lol2.luau

@@ -0,0 +1,90 @@
+--!optimize 2
+--!native
+--!strict
+
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local jecs = require(ReplicatedStorage.ecs)
+local __ = jecs.Wildcard
+local std = ReplicatedStorage.std
+
+local world = require(std.world)
+
+local Position = world:component() :: jecs.Entity<vector>
+local Previous = jecs.Rest
+local pre = jecs.pair(Position, Previous)
+
+local added = world
+	:query(Position)
+	:without(pre)
+	:cached()
+local changed = world
+	:query(Position, pre)
+	:cached()
+local removed = world
+	:query(pre)
+	:without(Position)
+	:cached()
+
+local children = {}
+for i = 1, 10 do
+	local e = world:entity()
+	world:set(e, Position, vector.create(i, i, i))
+	table.insert(children, e)
+end
+local function flip()
+	return math.random() > 0.5
+end
+local entity_index = world.entity_index
+local function copy(archetypes, id)
+	for _, archetype in archetypes do
+
+		local to = jecs.archetype_traverse_add(world, pre, archetype)
+		local columns = to.columns
+		local records = to.records
+		local old = columns[records[pre].column]
+		local new =	columns[records[id].column]
+
+		if to ~= archetype then
+			for _, entity in archetype.entities do
+				local r = jecs.entity_index_try_get_fast(entity_index, entity)
+				jecs.entity_move(entity_index, entity, r, to)
+			end
+		end
+
+		table.move(new, 1, #new, 1, old)
+
+	end
+end
+local function system2()
+	for i, child in children do
+		world:set(child, Position, vector.create(i,i,i))
+	end
+	for e, p in added:iter() do
+	end
+	copy(added:archetypes(), Position)
+	for i, child in children do
+		if flip() then
+			world:set(child, Position, vector.create(i + 1, i + 1, i + 1))
+		end
+	end
+
+	for e, new, old in changed:iter() do
+		if new ~= old then
+		end
+	end
+
+	copy(changed:archetypes(), Position)
+
+	for i, child in children do
+		world:remove(child, Position)
+	end
+
+	for e in removed:iter() do
+		world:remove(e, pre)
+	end
+end
+local scheduler = require(std.scheduler)
+
+scheduler.SYSTEM(system2)
+
+return 0

demo/src/StarterPlayer/StarterPlayerScripts/systems/move.luau

@@ -9,15 +9,23 @@ local cts = require(std.components)
 local Model = cts.Model
 local Transform = cts.Transform
 
-local moving_models = world:query(Transform, Model):cached()
+local moved_models = world:query(Model, Transform):cached()
+local updated_models = {}
+local i = 0
+local function processed(n)
+	i += 1
+	if i > n then
+		i = 0
+		return true
+	end
+	return false
+end
+
 local function move(dt: number)
-	for _, transform, model in moving_models do
-		local cf = transform.new
-		if cf ~= transform.old then
-			local part = model.PrimaryPart :: BasePart
-			local origo = part.CFrame
-			part.CFrame = origo:Lerp(cf, 1)
-			transform.old = cf
+	for entity, model in moved_models do
+		if updated_models[entity] then
+			updated_models[entity] = nil
+			model.PrimaryPart.CFrame = transform
 		end
 	end
 end
@@ -25,11 +33,8 @@ end
 local function syncTransforms()
 	for _, id, cf in blink.UpdateTransform.Iter() do
 		local e = ref("server-" .. tostring(id))
-		local transform = world:get(e, Transform)
-		if not transform then
-			continue
-		end
-		transform.new = cf
+		world:set(e, Transform, cf)
+		moved_models[e] = true
 	end
 end
 
@@ -38,4 +43,4 @@ local scheduler = require(std.scheduler)
 scheduler.SYSTEM(move)
 scheduler.SYSTEM(syncTransforms)
 
-return 0
+return 0

demo/wally.toml

@@ -5,4 +5,4 @@ registry = "https://github.com/UpliftGames/wally-index"
 realm = "shared"
 
 [dependencies]
-jabby = "alicesaidhi/jabby@0.2.0-rc.3"
+jabby = "alicesaidhi/jabby@0.2.2"

docs/.vitepress/config.mts

@@ -1,69 +1,64 @@
-import { defineConfig } from 'vitepress'
-
-// https://vitepress.dev/reference/site-config
-export default defineConfig({
-    title: "Jecs",
-    base: "/jecs/",
-    description: "A VitePress Site",
-    themeConfig: {
-        // https://vitepress.dev/reference/default-theme-config
-        nav: [
-            { text: 'Learn', link: '/' },
-            { text: 'API', link: '/api/jecs.md' },
-            { text: 'Examples', link: 'https://github.com/Ukendio/jecs/tree/main/examples' },
-        ],
-
-        sidebar: {
-            "/api/": [
-                {
-                    text: "API reference",
-                    items: [
-                        { text: "jecs", link: "/api/jecs" },
-                        { text: "World", link: "/api/world" },
-                        { text: "Query", link: "/api/query" }
-                    ]
-                }
-            ],
-            "/learn/": [
-                {
-                    text: "Introduction",
-                    items: [
-                        { text: 'Getting Started', link: '/learn/overview/get-started' },
-                        { text: 'First Jecs Project', link: '/learn/overview/first-jecs-project' }
-                    ]
-                },
-                {
-                    text: 'Concepts',
-                    items: [
-                        { text: 'Entities and Components', link: '/learn/concepts/entities-and-components' },
-                        { text: 'Queries', link: '/learn/concepts/queries' },
-                        { text: 'Relationships', link: '/learn/concepts/relationships' },
-                        { text: 'Component Traits', link: 'learn/concepts/component-traits' },
-                        { text: 'Addons', link: '/learn/concepts/addons' }
-                    ]
-                },
-                {
-                    text: "FAQ",
-                    items: [
-                        { text: 'How can I contribute?', link: '/learn/faq/contributing' }
-                    ]
-                },
-
-            ],
-            "/contributing/": [
-                {
-                    text: 'Contributing',
-                    items: [
-                        { text: 'Contribution Guidelines', link: '/learn/contributing/guidelines' },
-                        { text: 'Submitting Issues', link: '/learn/contributing/issues' },
-                        { text: 'Submitting Pull Requests', link: '/learn/contributing/pull-requests' },
-                    ]
-                }
-            ]
-        },
-
-        socialLinks: [
-            { icon: 'github', link: 'https://github.com/ukendio/jecs' }
-        ]
-    }
-})
+import { defineConfig } from "vitepress";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+	title: "Jecs",
+	base: "/jecs/",
+	description: "A VitePress Site",
+	themeConfig: {
+		// https://vitepress.dev/reference/default-theme-config
+		nav: [
+			{ text: "Learn", link: "/" },
+			{ text: "API", link: "/api/jecs.md" },
+			{ text: "Examples", link: "https://github.com/Ukendio/jecs/tree/main/examples" },
+		],
+
+		sidebar: {
+			"/api/": [
+				{
+					text: "API reference",
+					items: [
+						{ text: "jecs", link: "/api/jecs" },
+						{ text: "World", link: "/api/world" },
+						{ text: "Query", link: "/api/query" },
+					],
+				},
+			],
+			"/learn/": [
+				{
+					text: "Introduction",
+					items: [
+						{ text: "Getting Started", link: "/learn/overview/get-started" },
+						{ text: "First Jecs Project", link: "/learn/overview/first-jecs-project" },
+					],
+				},
+				{
+					text: "Concepts",
+					items: [
+						{ text: "Entities and Components", link: "/learn/concepts/entities-and-components" },
+						{ text: "Queries", link: "/learn/concepts/queries" },
+						{ text: "Relationships", link: "/learn/concepts/relationships" },
+						{ text: "Component Traits", link: "learn/concepts/component-traits" },
+						{ text: "Addons", link: "/learn/concepts/addons" },
+					],
+				},
+				{
+					text: "FAQ",
+					items: [{ text: "How can I contribute?", link: "/learn/faq/contributing" }],
+				},
+			],
+			"/contributing/": [
+				{
+					text: "Contributing",
+					items: [
+						{ text: "Contribution Guidelines", link: "/learn/contributing/guidelines" },
+						{ text: "Submitting Issues", link: "/learn/contributing/issues" },
+						{ text: "Submitting Pull Requests", link: "/learn/contributing/pull-requests" },
+					],
+				},
+			],
+		},
+
+		socialLinks: [{ icon: "github", link: "https://github.com/ukendio/jecs" }],
+	},
+});

docs/api/jecs.md

@@ -45,6 +45,6 @@ function jecs.pair(
 ```
 ::: info
 
-Note that while relationship pairs can be used as components, meaning you can add data with it as an ID, however they cannot be used as entities. Meaning you cannot add components to a pair as the source of a binding.
+While relationship pairs can be used as components and have data associated with an ID, they cannot be used as entities. Meaning you cannot add components to a pair as the source of a binding.
 
 :::

docs/api/query.md

@@ -1,88 +1,110 @@
-# Query
-
-A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components.
-
-# Methods
-
-## with
-Adds components (IDs) to query with, but will not use their data. This is useful for Tags or generally just data you do not care for.
-
-```luau
-function query:with(
-    ...: Entity -- The IDs to query with
-): Query
-```
-
-Example:
-::: code-group
-
-```luau [luau]
-for id, position in world:query(Position):with(Velocity) do
-    -- Do something
-end
-```
-
-```ts [typescript]
-for (const [id, position] of world.query(Position).with(Velocity)) {
-    // Do something
-}
-```
-
-:::
-
-:::info
-Put the IDs inside of `world:query()` instead if you need the data.
-:::
-
-## without
-Removes entities with the provided components from the query.
-
-```luau
-function query:without(
-    ...: Entity -- The IDs to filter against.
-): Query -- Returns the Query
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-for entity, position in world:query(Position):without(Velocity) do
-    -- Do something
-end
-```
-
-```ts [typescript]
-for (const [entity, position] of world.query(Position).without(Velocity)) {
-    // Do something
-}
-```
-:::
-
-## archetypes
-Returns the matching archetypes of the query.
-```luau
-function query:archetypes(): { Archetype }
-```
-
-Example:
-
-```luau [luau]
-for i, archetype in world:query(Position, Velocity):archetypes() do
-    local columns = archetype.columns
-    local field = archetype.records
-
-    local P = field[Position]
-    local V = field[Velocity]
-
-    for row, entity in archetype.entities do
-        local position = columns[P][row]
-        local velocity = columns[V][row]
-        -- Do something
-    end
-end
-```
-
-:::info
-This function is meant for people who want to really customize their query behaviour at the archetype-level
-:::
+# Query
+
+A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components.
+
+# Methods
+
+## iter
+
+Returns an iterator that can be used to iterate over the query.
+
+```luau
+function Query:iter(): () -> (Entity, ...)
+```
+
+## with
+
+Adds components (IDs) to query with, but will not use their data. This is useful for Tags or generally just data you do not care for.
+
+```luau
+function Query:with(
+    ...: Entity -- The IDs to query with
+): Query
+```
+
+Example:
+::: code-group
+
+```luau [luau]
+for id, position in world:query(Position):with(Velocity) do
+    -- Do something
+end
+```
+
+```ts [typescript]
+for (const [id, position] of world.query(Position).with(Velocity)) {
+	// Do something
+}
+```
+
+:::
+
+:::info
+Put the IDs inside of `world:query()` instead if you need the data.
+:::
+
+## without
+
+Removes entities with the provided components from the query.
+
+```luau
+function Query:without(
+    ...: Entity -- The IDs to filter against.
+): Query -- Returns the Query
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+for entity, position in world:query(Position):without(Velocity) do
+    -- Do something
+end
+```
+
+```ts [typescript]
+for (const [entity, position] of world.query(Position).without(Velocity)) {
+	// Do something
+}
+```
+
+:::
+
+## archetypes
+
+Returns the matching archetypes of the query.
+
+```luau
+function Query:archetypes(): { Archetype }
+```
+
+Example:
+
+```luau [luau]
+for i, archetype in world:query(Position, Velocity):archetypes() do
+    local columns = archetype.columns
+    local field = archetype.records
+
+    local P = field[Position]
+    local V = field[Velocity]
+
+    for row, entity in archetype.entities do
+        local position = columns[P][row]
+        local velocity = columns[V][row]
+        -- Do something
+    end
+end
+```
+
+:::info
+This function is meant for people who want to really customize their query behaviour at the archetype-level
+:::
+
+## cached
+
+Returns a cached version of the query. This is useful if you want to iterate over the same query multiple times.
+
+```luau
+function Query:cached(): Query -- Returns the cached Query
+```

docs/api/world.md

@@ -1,402 +1,500 @@
-# World
-A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components and to perform different kinds of operations on them.
-
-# Functions
-## new
-`World` utilizes a class, meaning JECS allows you to create multiple worlds.
-```luau
-function World.new(): World
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local world = jecs.World.new()
-local myOtherWorld = jecs.World.new()
-```
-
-```ts [typescript]
-import { World } from "@rbxts/jecs";
-
-const world = new World();
-const myOtherWorld = new World();
-```
-:::
-
-# Methods
-## entity
-Creates a new entity.
-```luau
-function World:entity(): Entity
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local entity = world:entity()
-```
-
-```ts [typescript]
-const entity = world.entity();
-```
-:::
-
-## component
-Creates a new component. Do note components are entities as well, meaning JECS allows you to add other components onto them.
-
-These are meant to be added onto other entities through `add` and `set`
-```luau
-function World:component<T>(): Entity<T> -- The new componen.
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local Health = world:component() :: jecs.Entity<number> -- Typecasting this will allow us to know what kind of data the component holds!
-```
-
-```ts [typescript]
-const Health = world.component<number>();
-```
-:::
-
-## get
-Returns the data present in the component that was set in the entity. Will return nil if the component was a tag or is not present.
-```luau
-function World:get<T>(
-    entity: Entity, -- The entity
-    id: Entity<T> -- The component ID to fetch
-): T?
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local Health = world:component() :: jecs.Entity<number>
-
-local Entity = world:entity()
-world:set(Entity, Health, 100)
-
-print(world:get(Entity, Health))
-
--- Outputs:
--- 100
-```
-
-```ts [typescript]
-const Health = world.component<number>();
-
-const Entity = world.entity();
-world.set(Entity, Health, 100);
-
-print(world.get(Entity, Health))
-
-// Outputs:
-// 100
-```
-:::
-
-## has
-Returns whether an entity has a component (ID). Useful for checking if an entity has a tag or if you don't care of the data that is inside the component.
-```luau
-function World:has(
-    entity: Entity, -- The entity
-    id: Entity<T> -- The component ID to check
-): boolean
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local IsMoving = world:component()
-local Ragdolled = world:entity() -- This is a tag, meaning it won't contain data
-local Health = world:component() :: jecs.Entity<number>
-
-local Entity = world:entity()
-world:set(Entity, Health, 100)
-world:add(Entity, Ragdolled)
-
-print(world:has(Entity, Health))
-print(world:has(Entity, IsMoving)
-
-print(world:get(Entity, Ragdolled))
-print(world:has(Entity, Ragdolled))
-
--- Outputs:
--- true
--- false
--- nil
--- true
-```
-
-```ts [typescript]
-const IsMoving = world.component();
-const Ragdolled = world.entity(); // This is a tag, meaning it won't contain data
-const Health = world.component<number>();
-
-const Entity = world.entity();
-world.set(Entity, Health, 100);
-world.add(Entity, Ragdolled);
-
-print(world.has(Entity, Health));
-print(world.has(Entity, IsMoving));
-
-print(world.get(Entity, Ragdolled));
-print(world.has(Entity, Ragdolled));
-
-// Outputs:
-// true
-// false
-// nil
-// true
-```
-:::
-
-## add
-Adds a component (ID) to the entity. Useful for adding a tag to an entity, as this adds the component to the entity without any additional values inside
-
-```luau
-function World:add(
-    entity: Entity, -- The entity
-    id: Entity<T> -- The component ID to add
-): void
-```
-
-::: info
-This function is idempotent, meaning if the entity already has the id, this operation will have no side effects.
-:::
-
-## set
-Adds or changes data in the entity's component.
-```luau
-function World:set(
-    entity: Entity, -- The entity
-    id: Entity<T>, -- The component ID to set
-    data: T -- The data of the component's type
-): void
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local Health = world:component() :: jecs.Entity<number>
-
-local Entity = world:entity()
-world:set(Entity, Health, 100)
-
-print(world:get(Entity, Health))
-
-world:set(Entity, Health, 50)
-print(world:get(Entity, Health))
-
--- Outputs:
--- 100
--- 50
-```
-
-```ts [typescript]
-const Health = world.component<number>();
-
-const Entity = world.entity();
-world.set(Entity, Health, 100);
-
-print(world.get(Entity, Health)) 
-
-world.set(Entity, Health, 50);
-print(world.get(Entity, Health))
-
-// Outputs:
-// 100
-// 50
-```
-:::
-
-## query
-Creates a [`query`](query) with the given components (IDs). Entities that satisfies the conditions of the query will be returned and their corresponding data.
-```luau
-function World:query(
-    ...: Entity -- The components to query with
-): Query
-```
-
-Example:
-
-::: code-group
-```luau [luau]
--- Entity could also be a component if a component also meets the requirements, since they are also entities which you can add more components onto
-for entity, position, velocity in world:query(Position, Velocity) do
-	
-end
-```
-
-```ts [typescript]
-// Roblox-TS allows to deconstruct tuples on the act like if they were arrays!
-// Entity could also be a component if a component also meets the requirements, since they are also entities which you can add more components onto
-for (const [entity, position, velocity] of world.query(Position, Velocity) {
-    // Do something
-}
-```
-:::
-
-:::info
-Queries are uncached by default, this is generally very cheap unless you have high fragmentation from e.g. relationships.
-
-:::
-## target
-Get the target of a relationship.
-This will return a target (second element of a pair) of the entity for the specified relationship. The index allows for iterating through the targets, if a single entity has multiple targets for the same relationship.
-If the index is larger than the total number of instances the entity has for the relationship or if there is no pair with the specified relationship on the entity, the operation will return nil.
-```luau
-function World:target(
-    entity: Entity, -- The entity
-    relation: Entity, -- The relationship between the entity and the target
-    nth: number, -- The index
-): Entity? -- The target for the relationship at the specified index.
-```
-
-## parent
-Get parent (target of ChildOf relationship) for entity. If there is no ChildOf relationship pair, it will return nil.
-```luau
-function World:parent(
-    child: Entity -- The child ID to find the parent of
-): Entity? -- Returns the parent of the child
-```
-
-This operation is the same as calling:
-
-```luau
-world:target(entity, jecs.ChildOf, 0)
-```
-
-## contains
-Checks if an entity or component (id) exists in the world.
-```luau
-function World:contains(
-    entity: Entity,
-): boolean
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local entity = world:entity()
-print(world:contains(entity))
-print(world:contains(1))
-print(world:contains(2))
-
--- Outputs:
--- true
--- true
--- false
-```
-
-```ts [typescript]
-const entity = world.entity();
-print(world.contains(entity));
-print(world.contains(1));
-print(world.contains(2));
-
-// Outputs:
-// true
-// true
-// false
-```
-:::
-
-## remove
-Removes a component (ID) from an entity
-```luau
-function World:remove(
-    entity: Entity,
-	component: Entity<T>
-): void
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local IsMoving = world:component()
-
-local entity = world:entity()
-world:add(entity, IsMoving)
-
-print(world:has(entity, IsMoving)) 
-
-world:remove(entity, IsMoving)
-print(world:has(entity, IsMoving))
-
--- Outputs:
--- true
--- false
-```
-
-```ts [typescript]
-const IsMoving = world.component();
-
-const entity = world.entity();
-world.add(entity, IsMoving);
-
-print(world.has(entity, IsMoving));
-
-world.remove(entity, IsMoving);
-print(world.has(entity, IsMoving));
-
-// Outputs:
-// true
-// false
-```
-:::
-
-## delete
-Deletes an entity and all of its related components and relationships.
-```luau
-function World:delete(
-    entity: Entity
-): void
-```
-
-Example:
-
-::: code-group
-```luau [luau]
-local entity = world:entity()
-print(world:has(entity))
-
-world:delete(entity)
-
-print(world:has(entity))
-
--- Outputs:
--- true
--- false
-```
-
-```ts [typescript]
-const entity = world.entity();
-print(world.has(entity));
-
-world.delete(entity);
-
-print(world.has(entity));
-
-// Outputs:
-// true
-// false
-```
-:::
-
-## clear
-Clears all of the components and relationships of the entity without deleting it.
-```luau
-function World:clear(
-    entity: Entity
-): void
-```
+# World
+
+A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components and to perform different kinds of operations on them.
+
+# Functions
+
+## new
+
+`World` utilizes a class, meaning JECS allows you to create multiple worlds.
+
+```luau
+function World.new(): World
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+local world = jecs.World.new()
+local myOtherWorld = jecs.World.new()
+```
+
+```ts [typescript]
+import { World } from "@rbxts/jecs";
+
+const world = new World();
+const myOtherWorld = new World();
+```
+
+:::
+
+# Methods
+
+## entity
+
+Creates a new entity.
+
+```luau
+function World:entity(): Entity
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+local entity = world:entity()
+```
+
+```ts [typescript]
+const entity = world.entity();
+```
+
+:::
+
+## component
+
+Creates a new component. Do note components are entities as well, meaning JECS allows you to add other components onto them.
+
+These are meant to be added onto other entities through `add` and `set`
+
+```luau
+function World:component<T>(): Entity<T> -- The new componen.
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+local Health = world:component() :: jecs.Entity<number> -- Typecasting this will allow us to know what kind of data the component holds!
+```
+
+```ts [typescript]
+const Health = world.component<number>();
+```
+
+:::
+
+## get
+
+Returns the data present in the component that was set in the entity. Will return nil if the component was a tag or is not present.
+
+```luau
+function World:get<T>(
+    entity: Entity, -- The entity
+    id: Entity<T> -- The component ID to fetch
+): T?
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+local Health = world:component() :: jecs.Entity<number>
+
+local Entity = world:entity()
+world:set(Entity, Health, 100)
+
+print(world:get(Entity, Health))
+
+-- Outputs:
+-- 100
+```
+
+```ts [typescript]
+const Health = world.component<number>();
+
+const Entity = world.entity();
+world.set(Entity, Health, 100);
+
+print(world.get(Entity, Health));
+
+// Outputs:
+// 100
+```
+
+:::
+
+## has
+
+Returns whether an entity has a component (ID). Useful for checking if an entity has a tag or if you don't care of the data that is inside the component.
+
+```luau
+function World:has(
+    entity: Entity, -- The entity
+    id: Entity<T> -- The component ID to check
+): boolean
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+local IsMoving = world:component()
+local Ragdolled = world:entity() -- This is a tag, meaning it won't contain data
+local Health = world:component() :: jecs.Entity<number>
+
+local Entity = world:entity()
+world:set(Entity, Health, 100)
+world:add(Entity, Ragdolled)
+
+print(world:has(Entity, Health))
+print(world:has(Entity, IsMoving)
+
+print(world:get(Entity, Ragdolled))
+print(world:has(Entity, Ragdolled))
+
+-- Outputs:
+-- true
+-- false
+-- nil
+-- true
+```
+
+```ts [typescript]
+const IsMoving = world.component();
+const Ragdolled = world.entity(); // This is a tag, meaning it won't contain data
+const Health = world.component<number>();
+
+const Entity = world.entity();
+world.set(Entity, Health, 100);
+world.add(Entity, Ragdolled);
+
+print(world.has(Entity, Health));
+print(world.has(Entity, IsMoving));
+
+print(world.get(Entity, Ragdolled));
+print(world.has(Entity, Ragdolled));
+
+// Outputs:
+// true
+// false
+// nil
+// true
+```
+
+:::
+
+## add
+
+Adds a component (ID) to the entity. Useful for adding a tag to an entity, as this adds the component to the entity without any additional values inside
+
+```luau
+function World:add(
+    entity: Entity, -- The entity
+    id: Entity<T> -- The component ID to add
+): void
+```
+
+::: info
+This function is idempotent, meaning if the entity already has the id, this operation will have no side effects.
+:::
+
+## set
+
+Adds or changes data in the entity's component.
+
+```luau
+function World:set(
+    entity: Entity, -- The entity
+    id: Entity<T>, -- The component ID to set
+    data: T -- The data of the component's type
+): void
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+local Health = world:component() :: jecs.Entity<number>
+
+local Entity = world:entity()
+world:set(Entity, Health, 100)
+
+print(world:get(Entity, Health))
+
+world:set(Entity, Health, 50)
+print(world:get(Entity, Health))
+
+-- Outputs:
+-- 100
+-- 50
+```
+
+```ts [typescript]
+const Health = world.component<number>();
+
+const Entity = world.entity();
+world.set(Entity, Health, 100);
+
+print(world.get(Entity, Health));
+
+world.set(Entity, Health, 50);
+print(world.get(Entity, Health));
+
+// Outputs:
+// 100
+// 50
+```
+
+:::
+
+## query
+
+Creates a [`query`](query) with the given components (IDs). Entities that satisfies the conditions of the query will be returned and their corresponding data.
+
+```luau
+function World:query(
+    ...: Entity -- The components to query with
+): Query
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+-- Entity could also be a component if a component also meets the requirements, since they are also entities which you can add more components onto
+for entity, position, velocity in world:query(Position, Velocity) do
+
+end
+```
+
+```ts [typescript]
+// Roblox-TS allows to deconstruct tuples on the act like if they were arrays!
+// Entity could also be a component if a component also meets the requirements, since they are also entities which you can add more components onto
+for (const [entity, position, velocity] of world.query(Position, Velocity) {
+    // Do something
+}
+```
+
+:::
+
+:::info
+Queries are uncached by default, this is generally very cheap unless you have high fragmentation from e.g. relationships.
+
+:::
+
+## target
+
+Get the target of a relationship.
+This will return a target (second element of a pair) of the entity for the specified relationship. The index allows for iterating through the targets, if a single entity has multiple targets for the same relationship.
+If the index is larger than the total number of instances the entity has for the relationship or if there is no pair with the specified relationship on the entity, the operation will return nil.
+
+```luau
+function World:target(
+    entity: Entity, -- The entity
+    relation: Entity, -- The relationship between the entity and the target
+    nth: number, -- The index
+): Entity? -- The target for the relationship at the specified index.
+```
+
+## parent
+
+Get parent (target of ChildOf relationship) for entity. If there is no ChildOf relationship pair, it will return nil.
+
+```luau
+function World:parent(
+    child: Entity -- The child ID to find the parent of
+): Entity? -- Returns the parent of the child
+```
+
+This operation is the same as calling:
+
+```luau
+world:target(entity, jecs.ChildOf, 0)
+```
+
+## contains
+
+Checks if an entity or component (id) exists in the world.
+
+```luau
+function World:contains(
+    entity: Entity,
+): boolean
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+local entity = world:entity()
+print(world:contains(entity))
+print(world:contains(1))
+print(world:contains(2))
+
+-- Outputs:
+-- true
+-- true
+-- false
+```
+
+```ts [typescript]
+const entity = world.entity();
+print(world.contains(entity));
+print(world.contains(1));
+print(world.contains(2));
+
+// Outputs:
+// true
+// true
+// false
+```
+
+:::
+
+## remove
+
+Removes a component (ID) from an entity
+
+```luau
+function World:remove(
+    entity: Entity,
+	component: Entity<T>
+): void
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+local IsMoving = world:component()
+
+local entity = world:entity()
+world:add(entity, IsMoving)
+
+print(world:has(entity, IsMoving))
+
+world:remove(entity, IsMoving)
+print(world:has(entity, IsMoving))
+
+-- Outputs:
+-- true
+-- false
+```
+
+```ts [typescript]
+const IsMoving = world.component();
+
+const entity = world.entity();
+world.add(entity, IsMoving);
+
+print(world.has(entity, IsMoving));
+
+world.remove(entity, IsMoving);
+print(world.has(entity, IsMoving));
+
+// Outputs:
+// true
+// false
+```
+
+:::
+
+## delete
+
+Deletes an entity and all of its related components and relationships.
+
+```luau
+function World:delete(
+    entity: Entity
+): void
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+local entity = world:entity()
+print(world:has(entity))
+
+world:delete(entity)
+
+print(world:has(entity))
+
+-- Outputs:
+-- true
+-- false
+```
+
+```ts [typescript]
+const entity = world.entity();
+print(world.has(entity));
+
+world.delete(entity);
+
+print(world.has(entity));
+
+// Outputs:
+// true
+// false
+```
+
+:::
+
+## clear
+
+Clears all of the components and relationships of the entity without deleting it.
+
+```luau
+function World:clear(
+    entity: Entity
+): void
+```
+
+## each
+
+Iterate over all entities with the specified component.
+Useful when you only need the entity for a specific ID and you want to avoid creating a query.
+
+```luau
+function World:each(
+	id: Entity -- The component ID
+): () -> Entity
+```
+
+Example:
+
+::: code-group
+
+```luau [luau]
+local id = world:entity()
+for entity in world:each(id) do
+	-- Do something
+end
+```
+
+```ts [typescript]
+const id = world.entity();
+for (const entity of world.each(id)) {
+	// Do something
+}
+```
+
+:::
+
+## children
+
+Iterate entities in root of parent
+
+```luau
+function World:children(
+	parent: Entity -- The parent entity
+): () -> Entity
+```
+
+This is the same as calling:
+
+```luau
+world:each(pair(ChildOf, parent))
+```

docs/learn/concepts/addons.md

@@ -1,16 +1,56 @@
-# 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)!
-
-# Debuggers
-## [jabby](https://github.com/alicesaidhi/jabby)
-A jecs debugger with a string-based query language and entity editing capabilities.
-
-# Schedulers
-## [lockstep scheduler](https://gist.github.com/1Axen/6d4f78b3454cf455e93794505588354b)
-A simple fixed step system scheduler.
-
-## [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
-
-## [jam](https://github.com/revvy02/Jam)
-Provides hooks and a scheduler that implements jabby and a topographical runtime
+# 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](https://github.com/Ukendio/jecs)!
+
+# Development tools
+
+## [jabby](https://github.com/alicesaidhi/jabby)
+
+A jecs debugger with a string-based query language and entity editing capabilities.
+
+## [jecs_entity_visualiser](https://github.com/Ukendio/jecs/blob/main/addons/entity_visualiser.luau)
+
+A simple entity and component visualiser in the output
+
+## [jecs_lifetime_tracker](https://github.com/Ukendio/jecs/blob/main/addons/lifetime_tracker.luau)
+
+A tool for inspecting entity lifetimes
+
+# Helpers
+
+## [jecs_observers](https://github.com/Ukendio/jecs/blob/main/addons/observers.luau)
+
+Observers for queries and signals for components
+
+# Schedulers
+
+## [lockstep scheduler](https://gist.github.com/1Axen/6d4f78b3454cf455e93794505588354b)
+
+A simple fixed step system scheduler.
+
+## [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
+
+## [planck](https://github.com/YetAnotherClown/planck)
+
+An agnostic scheduler inspired by Bevy and Flecs, with core features including phases, pipelines, run conditions, and startup systems.
+Planck also provides plugins for Jabby, Matter Hooks, and more.
+
+# Replication
+
+## [feces](https://github.com/NeonD00m/feces)
+
+A generalized replication system for jecs
+
+# Input
+
+## [Axis](https://github.com/NeonD00m/axis)
+
+An agnostic, simple and versatile input library for ECS
+
+# Observers

docs/learn/concepts/component-traits.md

@@ -1,150 +1,191 @@
-# 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
-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.
-
-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.
-
-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.
-
-There are two cleanup actions:
-
-- `Remove`: removes instances of the specified (component) id from all entities (default)
-- `Delete`: deletes all entities with specified id
-
-There are two cleanup conditions:
-
-- `OnDelete`: the component, tag or relationship is deleted
-- `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]
-local Archer = world:component()
-world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
-
-local e = world:entity()
-world:add(e, Archer)
-
--- This will remove Archer from e
-world:delete(Archer)
-```
-
-```typescript [typescript]
-const Archer = world.component()
-world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
-
-const e = world:entity()
-world.add(e, Archer)
-
-// This will remove Archer from e
-world.delete(Archer)
-```
-
-:::
-
-### (OnDelete, Delete)
-::: code-group
-
-```luau [luau]
-local Archer = world:component()
-world:add(Archer, pair(jecs.OnDelete, jecs.Delete))
-
-local e = world:entity()
-world:add(e, Archer)
-
--- This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
-world:delete(Archer)
-```
-
-```typescript [typescript]
-const Archer = world.component()
-world.add(Archer, pair(jecs.OnDelete, jecs.Delete))
-
-const e = world:entity()
-world.add(e, Archer)
-
-// This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
-world.delete(Archer)
-```
-
-:::
-
-### (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 Archer = world.component()
-world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
-
-const e = world:entity()
-world.add(e, Archer)
-
-// This will delete e
-world.delete(Archer)
-```
-
-:::
-
-This page takes wording and terminology directly from Flecs [documentation](https://www.flecs.dev/flecs/md_docs_2ComponentTraits.html)
+# 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
+
+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.
+
+::: warning
+Hooks, added to a component that has already been added to other entities/components, will not be called.
+:::
+
+## 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.
+
+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.
+
+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.
+
+There are two cleanup actions:
+
+-   `Remove`: removes instances of the specified (component) id from all entities (default)
+-   `Delete`: deletes all entities with specified id
+
+There are two cleanup conditions:
+
+-   `OnDelete`: the component, tag or relationship is deleted
+-   `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]
+local Archer = world:component()
+world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
+
+local e = world:entity()
+world:add(e, Archer)
+
+-- This will remove Archer from e
+world:delete(Archer)
+```
+
+```typescript [typescript]
+const Archer = world.component();
+world.add(Archer, pair(jecs.OnDelete, jecs.Remove));
+
+const e = world.entity();
+world.add(e, Archer);
+
+// This will remove Archer from e
+world.delete(Archer);
+```
+
+:::
+
+### (OnDelete, Delete)
+
+::: code-group
+
+```luau [luau]
+local Archer = world:component()
+world:add(Archer, pair(jecs.OnDelete, jecs.Delete))
+
+local e = world:entity()
+world:add(e, Archer)
+
+-- This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
+world:delete(Archer)
+```
+
+```typescript [typescript]
+const Archer = world.component();
+world.add(Archer, pair(jecs.OnDelete, jecs.Delete));
+
+const e = world.entity();
+world.add(e, Archer);
+
+// This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
+world.delete(Archer);
+```
+
+:::
+
+### (OnDeleteTarget, Remove)
+
+::: code-group
+
+```luau [luau]
+local OwnedBy = world:component()
+world:add(OwnedBy, pair(jecs.OnDeleteTarget, jecs.Remove))
+local loot = world:entity()
+local player = world:entity()
+world:add(loot, pair(OwnedBy, player))
+
+-- This will remove (OwnedBy, player) from loot
+world:delete(player)
+```
+
+```typescript [typescript]
+const OwnedBy = world.component();
+world.add(OwnedBy, pair(jecs.OnDeleteTarget, jecs.Remove));
+const loot = world.entity();
+const player = world.entity();
+world.add(loot, pair(OwnedBy, player));
+
+// 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,113 +1,140 @@
-# Entities and Components
-
-## Entities
-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
-
-## 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").
-
-### Operations
-Operation | Description
-----------|------------
-`get`     | Get a specific component or set of components from an entity.
-`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`
-`remove`  | Removes component from entity. If entity doesn't have the component, `remove` does nothing.
-`clear`   | Remove all components from an entity. Clearing is more efficient than removing one by one.
-
-### Components are entities
-
-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:
-
-::: code-group
-
-```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))
-```
-
-:::
-
-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
-
-```luau [luau]
-local Networked = world:component()
-local Type = world:component()
-local Name = world:component()
-local Position = world:component() :: jecs.Entity<Vector3>
-world:add(Position, Networked)
-world:set(Position, Name, "Position")
-world:set(Position, Type, { size = 12, type = "Vector3" } ) -- 12 bytes to represent a Vector3
-
-for id, ty, name in world:query(Type, Name):with(Networked) do
-    local batch = {}
-    for entity, data in world:query(id) do
-        table.insert(batch, { entity = entity, data = data })
-    end
-    -- entities are sized f64
-    local packet = buffer.create(#batch * (8 + ty.size))
-    local offset = 0
-    for _, entityData in batch do
-        offset+=8
-        buffer.writef64(packet, offset, entityData.entity)
-        if ty.type == "Vector3" then
-            local vec3 = entity.data :: Vector3
-            offset += 4
-            buffer.writei32(packet, offset, vec3.X)
-            offset += 4
-            buffer.writei32(packet, offset, vec3.Y)
-            offset += 4
-            buffer.writei32(packet, offset, vec3.Z)
-        end
-    end
-
-    updatePositions:FireServer(packet)
-end
-```
-
-```typescript [typescript]
-const Networked = world.component()
-const Type = world.component()
-const Name = world.component()
-const Position = world.component<Vector3>();
-world.add(Position, Networked)
-world.set(Position, Name, "Position")
-world.set(Position, Type, { size: 12, type: "Vector3" } ) // 12 bytes to represent a Vector3
-
-for (const [id, ty, name] of world.query(Type, Name).with(Networked)) {
-    const batch = new Array<{ entity: Entity, data: unknown}>()
-
-    for (const [entity, data] of world.query(id)) {
-        batch.push({ entity, data })
-    }
-    // entities are sized f64
-    const packet = buffer.create(batch.size() * (8 + ty.size))
-    const offset = 0
-    for (const [_, entityData] of batch) {
-        offset+=8
-        buffer.writef64(packet, offset, entityData.entity)
-        if (ty.type == "Vector3") {
-            const vec3 = entity.data as Vector3
-            offset += 4
-            buffer.writei32(packet, offsetm, vec3.X)
-            offset += 4
-            buffer.writei32(packet, offset, vec3.Y)
-            offset += 4
-            buffer.writei32(packet, offset, vec3.Z)
-        }
-    }
-
-    updatePositions.FireServer(packet)
-}
-```
-
-:::
+# Entities and Components
+
+## Entities
+
+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
+
+## 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").
+
+## Operations
+
+| Operation | Description                                                                                    |
+| --------- | ---------------------------------------------------------------------------------------------- |
+| `get`     | Get a specific component or set of components from an entity.                                  |
+| `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` |
+| `remove`  | Removes component from entity. If entity doesn't have the component, `remove` does nothing.    |
+| `clear`   | Remove all components from an entity. Clearing is more efficient than removing one by one.     |
+
+## Components are entities
+
+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:
+
+::: code-group
+
+```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));
+```
+
+:::
+
+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
+
+```luau [luau]
+local Networked = world:component()
+local Type = world:component()
+local Name = world:component()
+local Position = world:component() :: jecs.Entity<Vector3>
+world:add(Position, Networked)
+world:set(Position, Name, "Position")
+world:set(Position, Type, { size = 12, type = "Vector3" } ) -- 12 bytes to represent a Vector3
+
+for id, ty, name in world:query(Type, Name, Networked) do
+    local batch = {}
+    for entity, data in world:query(id) do
+        table.insert(batch, { entity = entity, data = data })
+    end
+    -- entities are sized f64
+    local packet = buffer.create(#batch * (8 + ty.size))
+    local offset = 0
+    for _, entityData in batch do
+        offset+=8
+        buffer.writef64(packet, offset, entityData.entity)
+        if ty.type == "Vector3" then
+            local vec3 = entity.data :: Vector3
+            offset += 4
+            buffer.writei32(packet, offset, vec3.X)
+            offset += 4
+            buffer.writei32(packet, offset, vec3.Y)
+            offset += 4
+            buffer.writei32(packet, offset, vec3.Z)
+        end
+    end
+
+    updatePositions:FireServer(packet)
+end
+```
+
+```typescript [typescript]
+const Networked = world.component();
+const Type = world.component();
+const Name = world.component();
+const Position = world.component<Vector3>();
+world.add(Position, Networked);
+world.set(Position, Name, "Position");
+world.set(Position, Type, { size: 12, type: "Vector3" }); // 12 bytes to represent a Vector3
+
+for (const [id, ty, name] of world.query(Type, Name, Networked)) {
+	const batch = new Array<{ entity: Entity; data: unknown }>();
+
+	for (const [entity, data] of world.query(id)) {
+		batch.push({ entity, data });
+	}
+	// entities are sized f64
+	const packet = buffer.create(batch.size() * (8 + ty.size));
+	const offset = 0;
+	for (const [_, entityData] of batch) {
+		offset += 8;
+		buffer.writef64(packet, offset, entityData.entity);
+		if (ty.type == "Vector3") {
+			const vec3 = entity.data as Vector3;
+			offset += 4;
+			buffer.writei32(packet, offsetm, vec3.X);
+			offset += 4;
+			buffer.writei32(packet, offset, vec3.Y);
+			offset += 4;
+			buffer.writei32(packet, offset, vec3.Z);
+		}
+	}
+
+	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

@@ -1,106 +1,186 @@
-# Queries
-
-## Introductiuon
-
-Queries enable games to quickly find entities that satifies provided conditions.
-
-Jecs queries can do anything from returning entities that match a simple list of components, to matching against entity graphs.
-
-This manual contains a full overview of the query features available in Jecs. Some of the features of Jecs queries are:
-
-- Queries have support for relationships pairs which allow for matching against entity graphs without having to build complex data structures for it.
-- Queries support filters such as [`query:with(...)`](../../api/query.md#with) if entities are required to have the components but you don’t actually care about components value. And [`query:without(...)`](../../api/query.md#without) which selects entities without the components.
-- Queries can be drained or reset on when called, which lets you choose iterator behaviour.
-- Queries can be called with any ID, including entities created dynamically, this is useful for pairs.
-- Queries are already fast but can be futher inlined via [`query:archetypes()`](../../api/query.md#archetypes) for maximum performance to eliminate function call overhead which is roughly 70-80% of the cost for iteration.
-
-## Creating Queries
-This section explains how to create queries in the different language bindings.
-
-:::code-group
-```luau [luau]
-for _ in world:query(Position, Velocity) do end
-```
-```typescript [typescript]
-for (const [_] of world.query(Position, Velocity)) {}
-```
-:::
-
-### Components
-A component is any single ID that can be added to an entity. This includes tags and regular entities, which are IDs that do not have the builtin `Component` component. To match a query, an entity must have all the requested components. An example:
-
-```luau
-local e1 = world:entity()
-world:add(e1, Position)
-
-local e2 = world:entity()
-world:add(e2, Position)
-world:add(e2, Velocity)
-
-local e3 = world:entity()
-world:add(e3, Position)
-world:add(e3, Velocity)
-world:add(e3, Mass)
-
-```
-Only entities `e2` and `e3` match the query Position, Velocity.
-
-### Wildcards
-
-Jecs currently only supports the `Any` type of wildcards which a single result for the first component that it matches.
-
-When using the `Any` type wildcard it is undefined which component will be matched, as this can be influenced by other parts of the query. It is guaranteed that iterating the same query twice on the same dataset will produce the same result.
-
-If you want to iterate multiple targets for the same relation on a pair, then use [`world:target`](../../api/world.md#target)
-
-Wildcards are particularly useful when used in combination with pairs (next section).
-
-### Pairs
-
-A pair is an ID that encodes two elements. Pairs, like components, can be added to entities and are the foundation for [Relationships](relationships.md).
-
-The elements of a pair are allowed to be wildcards. When a query pair returns an `Any` type wildcard, the query returns at most a single matching pair on an entity.
-
-The following sections describe how to create queries for pairs in the different language bindings.
-
-:::code-group
-```luau [luau]
-local Likes = world:entity()
-local bob = world:entity()
-for _ in world:query(pair(Likes, bob)) do end
-```
-```typescript [typescript]
-const Likes = world.entity()
-const bob = world.entity()
-for (const [_] of world.query(pair(Likes, bob))) {}
-```
-:::
-
-When a query pair contains a wildcard, the `world:target()` function can be used to determine the target of the pair element that matched the query:
-
-:::code-group
-```luau [luau]
-for id in world:query(pair(Likes, jecs.Wildcard)) do
-    print(`entity {getName(id)} likes {getName(world, world:target(id, Likes))}`)
-end
-```
-```typescript [typescript]
-const Likes = world.entity()
-const bob = world.entity()
-for (const [_] of world.query(pair(Likes, jecs.Wildcard))) {
-    print(`entity ${getName(id)} likes ${getName(world.target(id, Likes))}`)
-}
-```
-:::
-
-### Filters
-Filters are extensions to queries which allow you to select entities from a more complex pattern but you don't actually care about the component values.
-
-The following filters are supported by queries:
-
-Identifier | Description
----------- | -----------
-With       | Must match with all terms.
-Without    | Must not match with provided terms.
-
-This page takes wording and terminology directly from Flecs [documentation](https://www.flecs.dev/flecs/md_docs_2Queries.html)
+# Queries
+
+## Introduction
+
+Queries enable games to quickly find entities that satifies provided conditions.
+
+Jecs queries can do anything from returning entities that match a simple list of components, to matching against entity graphs.
+
+This manual contains a full overview of the query features available in Jecs. Some of the features of Jecs queries are:
+
+-   Queries have support for relationships pairs which allow for matching against entity graphs without having to build complex data structures for it.
+-   Queries support filters such as [`query:with(...)`](../../api/query.md#with) if entities are required to have the components but you don’t actually care about components value. And [`query:without(...)`](../../api/query.md#without) which selects entities without the components.
+-   Queries can be drained or reset on when called, which lets you choose iterator behaviour.
+-   Queries can be called with any ID, including entities created dynamically, this is useful for pairs.
+-   Queries are already fast but can be futher inlined via [`query:archetypes()`](../../api/query.md#archetypes) for maximum performance to eliminate function call overhead which is roughly 70-80% of the cost for iteration.
+
+## 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
+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
+
+```luau [luau]
+local e1 = world:entity()
+world:set(e1, Position, Vector3.new(10, 20, 30)) -- create archetype [Position]
+world:set(e1, Velocity, Vector3.new(1, 2, 3))    -- create archetype [Position, Velocity]
+
+local e2 = world:entity()
+world:set(e2, Position, Vector3.new(10, 20, 30)) -- archetype [Position] already exists
+world:set(e2, Velocity, Vector3.new(1, 2, 3)) 	 -- archetype [Position, Velocity] already exists
+world:set(e3, Mass, 100) 						 -- create archetype [Position, Velocity, Mass]
+
+-- e1 is now in archetype [Position, Velocity]
+-- e2 is now in archetype [Position, Velocity, Mass]
+```
+
+```typescript [typescript]
+const e1 = world.entity();
+world.set(e1, Position, new Vector3(10, 20, 30)); // create archetype [Position]
+world.set(e1, Velocity, new Vector3(1, 2, 3)); // create archetype [Position, Velocity]
+
+const e2 = world.entity();
+world.set(e2, Position, new Vector3(10, 20, 30)); // archetype [Position] already exists
+world.set(e2, Velocity, new Vector3(1, 2, 3)); // archetype [Position, Velocity] already exists
+world.set(e3, Mass, 100); // create archetype [Position, Velocity, Mass]
+
+// e1 is now in archetype [Position, Velocity]
+// e2 is now in archetype [Position, Velocity, Mass]
+```
+
+:::
+
+Archetypes are important for queries. Since all entities in an archetype have the same components, and a query matches entities with specific components, a query can often match entire archetypes instead of individual entities. This is one of the main reasons why queries in an archetype ECS are fast.
+
+The second reason that queries in an archetype ECS are fast is that they are cheap to cache. While an archetype is created for each unique component combination, games typically only use a finite set of component combinations which are created quickly after game assets are loaded.
+
+This means that instead of searching for archetypes each time a query is evaluated, a query can instead cache the list of matching archetypes. This is a cheap cache to maintain: even though entities can move in and out of archetypes, the archetypes themselves are often stable.
+
+If none of that made sense, the main thing to remember is that a cached query does not actually have to search for entities. Iterating a cached query just means iterating a list of prematched results, and this is really, really fast.
+
+### Tradeoffs
+
+Jecs has both cached and uncached queries. If cached queries are so fast, why even bother with uncached queries? There are four main reasons:
+
+-   Cached queries are really fast to iterate, but take more time to create because the cache must be initialized first.
+-   Cached queries have a higher RAM utilization, whereas uncached queries have very little overhead and are stateless.
+-   Cached queries add overhead to archetype creation/deletion, as these changes have to get propagated to caches.
+-   While caching archetypes is fast, some query features require matching individual entities, which are not efficient to cache (and aren't cached).
+
+As a rule of thumb, if you have a query that is evaluated each frame (as is typically the case with systems), they will benefit from being cached. If you need to create a query ad-hoc, an uncached query makes more sense.
+
+Ad-hoc queries are often necessary when a game needs to find entities that match a condition that is only known at runtime, for example to find all child entities for a specific parent.
+
+## Creating Queries
+
+This section explains how to create queries in the different language bindings.
+
+:::code-group
+
+```luau [luau]
+for _ in world:query(Position, Velocity) do end
+```
+
+```typescript [typescript]
+for (const [_] of world.query(Position, Velocity)) {
+}
+```
+
+:::
+
+### Components
+
+A component is any single ID that can be added to an entity. This includes tags and regular entities, which are IDs that do not have the builtin `Component` component. To match a query, an entity must have all the requested components. An example:
+
+```luau
+local e1 = world:entity()
+world:add(e1, Position)
+
+local e2 = world:entity()
+world:add(e2, Position)
+world:add(e2, Velocity)
+
+local e3 = world:entity()
+world:add(e3, Position)
+world:add(e3, Velocity)
+world:add(e3, Mass)
+
+```
+
+Only entities `e2` and `e3` match the query Position, Velocity.
+
+### Wildcards
+
+Jecs currently only supports the `Any` type of wildcards which a single result for the first component that it matches.
+
+When using the `Any` type wildcard it is undefined which component will be matched, as this can be influenced by other parts of the query. It is guaranteed that iterating the same query twice on the same dataset will produce the same result.
+
+If you want to iterate multiple targets for the same relation on a pair, then use [`world:target`](../../api/world.md#target)
+
+Wildcards are particularly useful when used in combination with pairs (next section).
+
+### Pairs
+
+A pair is an ID that encodes two elements. Pairs, like components, can be added to entities and are the foundation for [Relationships](relationships.md).
+
+The elements of a pair are allowed to be wildcards. When a query pair returns an `Any` type wildcard, the query returns at most a single matching pair on an entity.
+
+The following sections describe how to create queries for pairs in the different language bindings.
+
+:::code-group
+
+```luau [luau]
+local Likes = world:entity()
+local bob = world:entity()
+for _ in world:query(pair(Likes, bob)) do end
+```
+
+```typescript [typescript]
+const Likes = world.entity();
+const bob = world.entity();
+for (const [_] of world.query(pair(Likes, bob))) {
+}
+```
+
+:::
+
+When a query pair contains a wildcard, the `world:target()` function can be used to determine the target of the pair element that matched the query:
+
+:::code-group
+
+```luau [luau]
+for id in world:query(pair(Likes, jecs.Wildcard)) do
+    print(`entity {getName(id)} likes {getName(world, world:target(id, Likes))}`)
+end
+```
+
+```typescript [typescript]
+const Likes = world.entity();
+const bob = world.entity();
+for (const [_] of world.query(pair(Likes, jecs.Wildcard))) {
+	print(`entity ${getName(id)} likes ${getName(world.target(id, Likes))}`);
+}
+```
+
+:::
+
+### Filters
+
+Filters are extensions to queries which allow you to select entities from a more complex pattern but you don't actually care about the component values.
+
+The following filters are supported by queries:
+
+| Identifier | Description                         |
+| ---------- | ----------------------------------- |
+| With       | Must match with all terms.          |
+| Without    | Must not match with provided terms. |
+
+This page takes wording and terminology directly from Flecs [documentation](https://www.flecs.dev/flecs/md_docs_2Queries.html)

docs/learn/concepts/relationships.md

@@ -47,22 +47,10 @@ Get parent for entity
 world:parent(bob)
 ```
 ```typescript [typescript]
-world.parent(bob, pair(Eats, jecs.Wildcard)
+world.parent(bob)
 ```
 :::
 
-Find first target of a relationship for entity
-
-:::code-group
-```luau [luau]
-world:target(bob, Eats)
-```
-```typescript [typescript]
-world.target(bob, Eats)
-```
-:::
-
-
 Find first target of a relationship for entity
 
 :::code-group

docs/learn/overview/get-started.md

@@ -15,7 +15,7 @@ Add the following to your wally configuration:
 ::: code-group
 
 ```toml [wally.toml]
-jecs = "ukendio/jecs@0.2.3"
+jecs = "ukendio/jecs@0.5.3"
 ```
 
 :::

examples/luau/queries/changetracking.luau

@@ -1,4 +1,5 @@
 local jecs = require("@jecs")
+local pair = jecs.pair
 
 local world = jecs.World.new()
 local Name = world:component()
@@ -12,39 +13,37 @@ local function name(e)
 	return world:get(e, Name)
 end
 
-local Position = named(world.component, "Position") :: jecs.Entity<Vector3>
+local Position = named(world.component, "Position") :: jecs.Entity<vector>
 local Previous = jecs.Rest
-local PreviousPosition = jecs.pair(Previous, Position)
 
 local added = world
 	:query(Position)
-	:without(PreviousPosition)
+	:without(pair(Previous, Position))
 	:cached()
 local changed = world
-	:query(Position, PreviousPosition)
+	:query(Position, pair(Previous, Position))
 	:cached()
 local removed = world
-	:query(PreviousPosition)
+	:query(pair(Previous, Position))
 	:without(Position)
 	:cached()
 
+
 local e1 = named(world.entity, "e1")
-world:set(e1, Position, Vector3.new(10, 20, 30))
-
+world:set(e1, Position, vector.create(10, 20, 30))
 local e2 = named(world.entity, "e2")
-world:set(e2, Position, Vector3.new(10, 20, 30))
-
-for e, p in added:iter() do
-	print(`Added {e}: \{{p.X}, {p.Y}, {p.Z}}`)
-	world:set(e, PreviousPosition, p)
+world:set(e2, Position, vector.create(10, 20, 30))
+for entity, p in added do
+	print(`Added {name(entity)}: \{{p.x}, {p.y}, {p.z}}`)
+	world:set(entity, pair(Previous, Position), p)
 end
 
-world:set(e1, Position, "")
+world:set(e1, Position, vector.create(999, 999, 1998))
 
-for e, new, old in changed:iter() do
+for _, archetype in changed:archetypes() do
 	if new ~= old then
-		print(`{name(new)}'s Position changed from \{{old.X}, {old.Y}, {old.Z}\} to \{{new.X}, {new.Y}, {new.Z}\}`)
-		world:set(e, PreviousPosition, new)
+		print(`{name(e)}'s Position changed from \{{old.x}, {old.y}, {old.z}\} to \{{new.x}, {new.y}, {new.z}\}`)
+		world:set(e, pair(Previous, Position), new)
 	end
 end
 
@@ -52,6 +51,7 @@ world:remove(e2, Position)
 
 for e in removed:iter() do
 	print(`Position was removed from {name(e)}`)
+	world:remove(e, pair(Previous, Position))
 end
 
 -- Output:

jecs.d.ts

@@ -31,15 +31,28 @@ export type Id<TData = unknown> = Entity<TData> | Pair<TData, unknown> | Pair<un
 export type InferComponent<E> = E extends Entity<infer D>
 	? D
 	: E extends Pair<infer P, infer O>
-		? P extends undefined
-			? O
-			: P
-		: never;
+	? P extends undefined
+		? O
+		: P
+	: never;
 
 type FlattenTuple<T extends unknown[]> = T extends [infer U] ? U : LuaTuple<T>;
 type Nullable<T extends unknown[]> = { [K in keyof T]: T[K] | undefined };
 type InferComponents<A extends Id[]> = { [K in keyof A]: InferComponent<A[K]> };
 
+type ArchetypeId = number;
+type Column = unknown[];
+
+export type Archetype = {
+	id: number;
+	types: number[];
+	type: string;
+	entities: number[];
+	columns: Column[];
+	records: number[];
+	counts: number[];
+};
+
 type Iter<T extends unknown[]> = IterableFunction<LuaTuple<[Entity, ...T]>>;
 
 export type CachedQuery<T extends unknown[]> = {
@@ -47,6 +60,12 @@ export type CachedQuery<T extends unknown[]> = {
 	 * Returns an iterator that produces a tuple of [Entity, ...queriedComponents].
 	 */
 	iter(): Iter<T>;
+
+	/**
+	 * Returns the matched archetypes of the query
+	 * @returns An array of archetypes of the query
+	 */
+	archetypes(): Archetype[];
 } & Iter<T>;
 
 export type Query<T extends unknown[]> = {
@@ -75,6 +94,12 @@ export type Query<T extends unknown[]> = {
 	 * @returns A new Query with the exclusion applied.
 	 */
 	without(...components: Id[]): Query<T>;
+
+	/**
+	 * Returns the matched archetypes of the query
+	 * @returns An array of archetypes of the query
+	 */
+	archetypes(): Archetype[];
 } & Iter<T>;
 
 export class World {
@@ -233,13 +258,13 @@ export function pair_second<P, O>(world: World, p: Pair<P, O>): Entity<O>;
 
 export declare const OnAdd: Entity<(e: Entity) => void>;
 export declare const OnRemove: Entity<(e: Entity) => void>;
-export declare const OnSet: Entity<(e: Entity, value: unknown) => void>;
-export declare const ChildOf: Entity;
+export declare const OnChange: Entity<(e: Entity, value: unknown) => void>;
+export declare const ChildOf: Tag;
 export declare const Wildcard: Entity;
 export declare const w: Entity;
-export declare const OnDelete: Entity;
-export declare const OnDeleteTarget: Entity;
-export declare const Delete: Entity;
-export declare const Remove: Entity;
+export declare const OnDelete: Tag;
+export declare const OnDeleteTarget: Tag;
+export declare const Delete: Tag;
+export declare const Remove: Tag;
 export declare const Name: Entity<string>;
 export declare const Rest: Entity;

mkdocs.yml

@@ -1,186 +0,0 @@
-site_name: Jecs
-site_url: jecs.github.io/jecs
-repo_name: ukendio/jecs
-repo_url: https://github.com/ukendio/jecs
-
-extra:
-  version:
-    provider: mike
-
-theme:
-  name: material
-  custom_dir: docs/assets/overrides
-  logo: assets/logo
-  favicon: assets/logo-dark.svg
-  palette:
-    - media: "(prefers-color-scheme: dark)"
-      scheme: fusiondoc-dark
-      toggle:
-        icon: octicons/sun-24
-        title: Switch to light theme
-    - media: "(prefers-color-scheme: light)"
-      scheme: fusiondoc-light
-      toggle:
-        icon: octicons/moon-24
-        title: Switch to dark theme
-  font:
-    text: Plus Jakarta Sans
-    code: JetBrains Mono
-  features:
-    - navigation.tabs
-    - navigation.top
-    - navigation.sections
-    - navigation.instant
-    - navigation.indexes
-    - search.suggest
-    - search.highlight
-  icon:
-    repo: octicons/mark-github-16
-
-extra_css:
-  - assets/theme/fusiondoc.css
-  - assets/theme/colours.css
-  - assets/theme/code.css
-  - assets/theme/paragraph.css
-  - assets/theme/page.css
-  - assets/theme/admonition.css
-  - assets/theme/404.css
-  - assets/theme/api-reference.css
-  - assets/theme/dev-tools.css
-
-extra_javascript:
-  - assets/scripts/smooth-scroll.js
-
-nav:
-  - Home: index.md
-  - Tutorials:
-    - Get Started: tutorials/index.md
-    - Installing Fusion: tutorials/get-started/installing-fusion.md
-    - Developer Tools: tutorials/get-started/developer-tools.md
-    - Getting Help: tutorials/get-started/getting-help.md
-    - Fundamentals:
-      - Scopes: tutorials/fundamentals/scopes.md
-      - Values: tutorials/fundamentals/values.md
-      - Observers: tutorials/fundamentals/observers.md
-      - Computeds: tutorials/fundamentals/computeds.md
-    - Tables:
-      - ForValues: tutorials/tables/forvalues.md
-      - ForKeys: tutorials/tables/forkeys.md
-      - ForPairs: tutorials/tables/forpairs.md
-    - Animation:
-      - Tweens: tutorials/animation/tweens.md
-      - Springs: tutorials/animation/springs.md
-    - Roblox:
-      - Hydration: tutorials/roblox/hydration.md
-      - New Instances: tutorials/roblox/new-instances.md
-      - Parenting: tutorials/roblox/parenting.md
-      - Events: tutorials/roblox/events.md
-      - Change Events: tutorials/roblox/change-events.md
-      - Outputs: tutorials/roblox/outputs.md
-      - References: tutorials/roblox/references.md
-    - Best Practices:
-      - Components: tutorials/best-practices/components.md
-      - Instance Handling: tutorials/best-practices/instance-handling.md
-      - Callbacks: tutorials/best-practices/callbacks.md
-      - State: tutorials/best-practices/state.md
-      - Sharing Values: tutorials/best-practices/sharing-values.md
-      - Error Safety: tutorials/best-practices/error-safety.md
-      - Optimisation: tutorials/best-practices/optimisation.md
-    
-  - Examples:
-    - Home: examples/index.md
-    - Cookbook:
-      - examples/cookbook/index.md
-      - Player List: examples/cookbook/player-list.md
-      - Animated Computed: examples/cookbook/animated-computed.md
-      - Fetch Data From Server: examples/cookbook/fetch-data-from-server.md
-      - Light & Dark Theme: examples/cookbook/light-and-dark-theme.md
-      - Button Component: examples/cookbook/button-component.md
-      - Loading Spinner: examples/cookbook/loading-spinner.md
-      - Drag & Drop: examples/cookbook/drag-and-drop.md
-  - API Reference:
-    - api-reference/index.md
-    - General:
-      - Errors: api-reference/general/errors.md
-      - Types:
-        - Contextual: api-reference/general/types/contextual.md
-        - Version: api-reference/general/types/version.md
-      - Members:
-        - Contextual: api-reference/general/members/contextual.md
-        - Safe: api-reference/general/members/safe.md
-        - version: api-reference/general/members/version.md
-    - Memory:
-      - Types:
-        - Scope: api-reference/memory/types/scope.md
-        - ScopedObject: api-reference/memory/types/scopedobject.md
-        - Task: api-reference/memory/types/task.md
-      - Members:
-        - deriveScope: api-reference/memory/members/derivescope.md
-        - doCleanup: api-reference/memory/members/docleanup.md
-        - scoped: api-reference/memory/members/scoped.md
-    - State:
-      - Types:
-        - UsedAs: api-reference/state/types/usedas.md 
-        - Computed: api-reference/state/types/computed.md 
-        - Dependency: api-reference/state/types/dependency.md 
-        - Dependent: api-reference/state/types/dependent.md 
-        - For: api-reference/state/types/for.md 
-        - Observer: api-reference/state/types/observer.md 
-        - StateObject: api-reference/state/types/stateobject.md 
-        - Use: api-reference/state/types/use.md 
-        - Value: api-reference/state/types/value.md 
-      - Members:
-        - Computed: api-reference/state/members/computed.md
-        - ForKeys: api-reference/state/members/forkeys.md
-        - ForPairs: api-reference/state/members/forpairs.md
-        - ForValues: api-reference/state/members/forvalues.md
-        - Observer: api-reference/state/members/observer.md
-        - peek: api-reference/state/members/peek.md
-        - Value: api-reference/state/members/value.md
-    - Roblox:
-      - Types:
-        - Child: api-reference/roblox/types/child.md
-        - PropertyTable: api-reference/roblox/types/propertytable.md
-        - SpecialKey: api-reference/roblox/types/specialkey.md
-      - Members:
-        - Attribute: api-reference/roblox/members/attribute.md
-        - AttributeChange: api-reference/roblox/members/attributechange.md
-        - AttributeOut: api-reference/roblox/members/attributeout.md
-        - Children: api-reference/roblox/members/children.md
-        - Hydrate: api-reference/roblox/members/hydrate.md
-        - New: api-reference/roblox/members/new.md
-        - OnChange: api-reference/roblox/members/onchange.md
-        - OnEvent: api-reference/roblox/members/onevent.md
-        - Out: api-reference/roblox/members/out.md
-        - Ref: api-reference/roblox/members/ref.md
-    - Animation:
-      - Types:
-        - Animatable: api-reference/animation/types/animatable.md
-        - Spring: api-reference/animation/types/spring.md
-        - Tween: api-reference/animation/types/tween.md
-      - Members:
-        - Tween: api-reference/animation/members/tween.md
-        - Spring: api-reference/animation/members/spring.md
-  - Extras:
-    - Home: extras/index.md
-    - Backgrounds: extras/backgrounds.md
-    - Brand Guidelines: extras/brand-guidelines.md
-
-markdown_extensions:
-  - admonition
-  - attr_list
-  - meta
-  - md_in_html
-  - pymdownx.superfences
-  - pymdownx.betterem
-  - pymdownx.details
-  - pymdownx.tabbed:
-      alternate_style: true
-  - pymdownx.inlinehilite
-  - toc:
-      permalink: true
-  - pymdownx.highlight:
-      guess_lang: false
-  - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rbxts/jecs",
-	"version": "0.5.2",
+	"version": "0.6.0-rc.1",
 	"description": "Stupidly fast Entity Component System",
 	"main": "jecs.luau",
 	"repository": {

rokit.toml

@@ -2,5 +2,4 @@
 wally = "upliftgames/wally@0.3.2"
 rojo = "rojo-rbx/rojo@7.4.4"
 stylua = "johnnymorganz/stylua@2.0.1"
-selene = "kampfkarren/selene@0.27.1"
 Blink = "1Axen/Blink@0.14.1"

selene.toml

@@ -1,4 +0,0 @@
-std = "roblox"
-
-[lints]
-global_usage = "allow"

test/addons/observers.luau

@@ -0,0 +1,106 @@
+local jecs = require("@jecs")
+local testkit = require("@testkit")
+local test = testkit.test()
+local CASE, TEST, FINISH, CHECK = test.CASE, test.TEST, test.FINISH, test.CHECK
+local observers_add = require("@addons/observers")
+
+
+TEST("addons/observers", function()
+	local world = observers_add(jecs.world())
+
+	do CASE "Ensure ordering between signals and observers"
+		local A = world:component()
+		local B = world:component()
+
+		local count = 0
+		local function counter()
+			count += 1
+		end
+		world:observer({
+			callback = counter,
+			query = world:query(A, B),
+		})
+
+		world:added(A, counter)
+		world:added(A, counter)
+
+		world:removed(A, counter)
+
+		local e = world:entity()
+		world:add(e, A)
+		CHECK(count == 2)
+
+		world:add(e, B)
+		CHECK(count == 3)
+
+		world:remove(e, A)
+		CHECK(count == 4)
+	end
+
+	do CASE "Rematch entities in observers"
+		local A = world:component()
+
+		local count = 0
+		local function counter()
+			count += 1
+		end
+		world:observer({
+			query = world:query(A),
+			callback = counter
+		})
+
+		local e = world:entity()
+		world:set(e, A, true)
+		CHECK(count == 1)
+		world:remove(e, A)
+		CHECK(count == 1)
+		world:set(e, A, true)
+		CHECK(count == 2)
+		world:set(e, A, true)
+		CHECK(count == 3)
+	end
+
+	do CASE "Don't report changed components in monitor"
+		local A = world:component()
+		local count = 0
+		local function counter()
+			count += 1
+		end
+
+		world:monitor({
+			query = world:query(A),
+			callback = counter
+		})
+
+		local e = world:entity()
+		world:set(e, A, true)
+		CHECK(count == 1)
+		world:remove(e, A)
+		CHECK(count == 2)
+		world:set(e, A, true)
+		CHECK(count == 3)
+		world:set(e, A, true)
+		CHECK(count == 3)
+	end
+
+	do CASE "Call on pairs"
+		local A = world:component()
+
+		local callcount = 0
+		world:added(A, function(entity)
+			callcount += 1
+		end)
+		world:added(A, function(entity)
+			callcount += 1
+		end)
+
+		local e = world:entity()
+		local e1 = world:entity()
+
+		world:add(e1, jecs.pair(A, e))
+		world:add(e, jecs.pair(A, e1))
+		CHECK(callcount == 4)
+	end
+end)
+
+return FINISH()

test/btree.luau

@@ -1,152 +0,0 @@
--- original author @centauri
-local bt
-do
-	local FAILURE = 0
-	local SUCCESS = 1
-	local RUNNING = 2
-
-	local function SEQUENCE(nodes)
-		return function(...)
-			for _, node in nodes do
-				local status = node(...)
-				if status == FAILURE or status == RUNNING then
-					return status
-				end
-			end
-			return SUCCESS
-		end
-	end
-	local function FALLBACK(nodes)
-		return function(...)
-			for _, node in nodes do
-				local status = node(...)
-				if status == SUCCESS or status == RUNNING then
-					return status
-				end
-			end
-			return FAILURE
-		end
-	end
-	bt = {
-		SEQUENCE = SEQUENCE,
-		FALLBACK = FALLBACK,
-		RUNNING = RUNNING,
-		SUCCESS = SUCCESS,
-		FAILURE = FAILURE,
-	}
-end
-
-local SEQUENCE, FALLBACK = bt.SEQUENCE, bt.FALLBACK
-local RUNNING, SUCCESS, FAILURE = bt.FAILURE, bt.SUCCESS, bt.FAILURE
-
-local btree = FALLBACK({
-	SEQUENCE({
-		function()
-			return 1
-		end,
-
-		function()
-			return 0
-		end,
-	}),
-	SEQUENCE({
-		function()
-			print(3)
-			local start = os.clock()
-			local now = os.clock()
-			while os.clock() - now < 4 do
-				print("yielding")
-				coroutine.yield()
-			end
-			return 0
-		end,
-	}),
-	function()
-		return 1
-	end,
-})
-
-function wait(seconds)
-	local start = os.clock()
-	while os.clock() - start < seconds do
-	end
-	return os.clock() - start
-end
-
-local function panic(str)
-	-- We don't want to interrupt the loop when we error
-	coroutine.resume(coroutine.create(function()
-		error(str)
-	end))
-end
-
-local jecs = require("@jecs")
-local world = jecs.World.new()
-
-local function Scheduler(world, ...)
-	local systems = { ... }
-	local systemsNames = {}
-	local N = #systems
-	local system
-	local dt
-
-	for i, module in systems do
-		local sys = if typeof(module) == "function" then module else require(module)
-		systems[i] = sys
-		local file, line = debug.info(2, "sl")
-		systemsNames[sys] = `{file}->::{line}::->{debug.info(sys, "n")}`
-	end
-
-	local function run()
-		local name = systemsNames[system]
-
-		--debug.profilebegin(name)
-		--debug.setmemorycategory(name)
-		system(world, dt)
-		--debug.profileend()
-	end
-
-	local function loop(sinceLastFrame)
-		--debug.profilebegin("loop()")
-		local start = os.clock()
-		for i = N, 1, -1 do
-			system = systems[i]
-
-			dt = sinceLastFrame
-
-			local didNotYield, why = xpcall(function()
-				for _ in run do
-				end
-			end, debug.traceback)
-
-			if didNotYield then
-				continue
-			end
-
-			if string.find(why, "thread is not yieldable") then
-				N -= 1
-				local name = table.remove(systems, i)
-				panic("Not allowed to yield in the systems." .. "\n" .. `System: {name} has been ejected`)
-			else
-				panic(why)
-			end
-		end
-
-		--debug.profileend()
-		--debug.resetmemorycategory()
-		return os.clock() - start
-	end
-
-	return loop
-end
-
-local co = coroutine.create(btree)
-local function ai(world, dt)
-	coroutine.resume(co)
-end
-
-local loop = Scheduler(world, ai)
-
-while wait(0.2) do
-	print("frame time: ", loop(0.2))
-end

test/gen.luau

@@ -1,183 +0,0 @@
-type i53 = number
-type i24 = number
-
-type Ty = { i53 }
-type ArchetypeId = number
-
-type Column = { any }
-
-type Map<K, V> = { [K]: V }
-
-type GraphEdge = {
-	from: Archetype,
-	to: Archetype?,
-	prev: GraphEdge?,
-	next: GraphEdge?,
-	id: number,
-}
-
-type GraphEdges = Map<i53, GraphEdge>
-
-type GraphNode = {
-	add: GraphEdges,
-	remove: GraphEdges,
-	refs: GraphEdge,
-}
-
-type ArchetypeRecord = {
-	count: number,
-	column: number,
-}
-
-export type Archetype = {
-	id: number,
-	node: GraphNode,
-	types: Ty,
-	type: string,
-	entities: { number },
-	columns: { Column },
-	records: { ArchetypeRecord },
-}
-type Record = {
-	archetype: Archetype,
-	row: number,
-	dense: i24,
-}
-
-type EntityIndex = {
-	dense_array: Map<i24, i53>,
-	sparse_array: Map<i53, Record>,
-	sparse_count: number,
-	alive_count: number,
-	max_id: number,
-}
-
-local ECS_PAIR_FLAG = 0x8
-local ECS_ID_FLAGS_MASK = 0x10
-local ECS_ENTITY_MASK = bit32.lshift(1, 24)
-local ECS_GENERATION_MASK = bit32.lshift(1, 16)
-
--- HIGH 24 bits LOW 24 bits
-local function ECS_GENERATION(e: i53): i24
-	return if e > ECS_ENTITY_MASK then (e // ECS_ID_FLAGS_MASK) % ECS_GENERATION_MASK else 0
-end
-
-local function ECS_COMBINE(source: number, target: number): i53
-	return (source * 268435456) + (target * ECS_ID_FLAGS_MASK)
-end
-
-local function ECS_GENERATION_INC(e: i53)
-	if e > ECS_ENTITY_MASK then
-		local flags = e // ECS_ID_FLAGS_MASK
-		local id = flags // ECS_ENTITY_MASK
-		local generation = flags % ECS_GENERATION_MASK
-		print(generation)
-		return ECS_COMBINE(id, generation + 1)
-	end
-	return ECS_COMBINE(e, 1)
-end
-local function ECS_ENTITY_T_LO(e: i53): i24
-	return if e > ECS_ENTITY_MASK then (e // ECS_ID_FLAGS_MASK) // ECS_ENTITY_MASK else e
-end
-
-local function entity_index_try_get_any(entity_index: EntityIndex, entity: number): Record?
-	local r = entity_index.sparse_array[ECS_ENTITY_T_LO(entity)]
-
-	if not r or r.dense == 0 then
-		return nil
-	end
-
-	return r
-end
-
-local function entity_index_try_get(entity_index: EntityIndex, entity: number): Record?
-	local r = entity_index_try_get_any(entity_index, entity)
-	if r then
-		local r_dense = r.dense
-		if r_dense > entity_index.alive_count then
-			return nil
-		end
-		if entity_index.dense_array[r_dense] ~= entity then
-			return nil
-		end
-	end
-	return r
-end
-
-local function entity_index_get_alive(entity_index: EntityIndex, entity: number): number
-	local r = entity_index_try_get_any(entity_index, entity)
-	if r then
-		return entity_index.dense_array[r.dense]
-	end
-	return 0
-end
-
-local function entity_index_remove(entity_index: EntityIndex, entity: number)
-	local r = entity_index_try_get(entity_index, entity)
-	if not r then
-		return
-	end
-	local dense_array = entity_index.dense_array
-	local index_of_deleted_entity = r.dense
-	local last_entity_alive_at_index = entity_index.alive_count
-	entity_index.alive_count -= 1
-
-	local last_alive_entity = dense_array[last_entity_alive_at_index]
-	local r_swap = entity_index_try_get_any(entity_index, last_alive_entity) :: Record
-	r_swap.dense = index_of_deleted_entity
-	r.archetype = nil :: any
-	r.row = nil :: any
-	r.dense = last_entity_alive_at_index
-
-	dense_array[index_of_deleted_entity] = last_alive_entity
-	dense_array[last_entity_alive_at_index] = ECS_GENERATION_INC(entity)
-end
-
-local function entity_index_new_id(entity_index: EntityIndex): i53
-	local dense_array = entity_index.dense_array
-	if entity_index.alive_count ~= #dense_array then
-		entity_index.alive_count += 1
-		local id = dense_array[entity_index.alive_count]
-		return id
-	end
-
-	entity_index.max_id += 1
-	local id = entity_index.max_id
-	entity_index.alive_count += 1
-
-	dense_array[entity_index.alive_count] = id
-	entity_index.sparse_array[id] = {
-		dense = entity_index.alive_count,
-	} :: Record
-
-	return id
-end
-
-local function entity_index_is_alive(entity_index: EntityIndex, entity: number)
-	return entity_index_try_get(entity_index, entity) ~= nil
-end
-
-local eidx = {
-	alive_count = 0,
-	max_id = 0,
-	sparse_array = {} :: { Record },
-	sparse_count = 0,
-	dense_array = {} :: { i53 },
-}
-local e1v0 = entity_index_new_id(eidx, "e1v0")
-local e2v0 = entity_index_new_id(eidx, "e2v0")
-local e3v0 = entity_index_new_id(eidx, "e3v0")
-local e4v0 = entity_index_new_id(eidx, "e4v0")
-local e5v0 = entity_index_new_id(eidx, "e5v0")
-
-local e6v0 = entity_index_new_id(eidx)
-entity_index_remove(eidx, e6v0)
-local e6v1 = entity_index_new_id(eidx)
-entity_index_remove(eidx, e6v1)
-local e6v2 = entity_index_new_id(eidx)
-print(ECS_ENTITY_T_LO(e6v2), ECS_GENERATION(e6v2))
-
-print("-----")
-local e2 = ECS_GENERATION_INC(ECS_GENERATION_INC(269))
-print("-----")
-print(ECS_ENTITY_T_LO(e2), ECS_GENERATION(e2))

test/hooks.luau

@@ -1,47 +0,0 @@
-local jecs = require("@jecs")
-
-local function create_cache(hook)
-	local columns = setmetatable({}, {
-		__index = function(self, component)
-			local column = {}
-			self[component] = column
-			return column
-		end,
-	})
-
-	return function(world, component, fn)
-		local column = columns[component]
-		table.insert(column, fn)
-		world:set(component, hook, function(entity, value)
-			for _, callback in column do
-				callback(entity, value)
-			end
-		end)
-	end
-end
-
-local hooks = {
-	OnSet = create_cache(jecs.OnSet),
-	OnAdd = create_cache(jecs.OnAdd),
-	OnRemove = create_cache(jecs.OnRemove),
-}
-
-local world = jecs.World.new()
-local Position = world:component()
-local order = ""
-hooks.OnSet(world, Position, function(entity, value)
-	print("$1", entity, `({value.x}, {value.y}, {value.z})`)
-	order ..= "$1"
-end)
-hooks.OnSet(world, Position, function(entity, value)
-	print("$2", entity, `\{{value.x}, {value.y}, {value.z}}`)
-	order ..= "-$2"
-end)
-
-world:set(world:entity(), Position, { x = 1, y = 0, z = 1 })
-
--- Output:
---  $1      270     (1, 0, 1)
---  $2      270     {1, 0, 1}
-
-assert(order == "$1" .. "-" .. "$2")

test/leaky.luau

@@ -1,57 +0,0 @@
-local function calculateAverage(times)
-	local sum = 0
-	for _, time in ipairs(times) do
-		sum = sum + time
-	end
-	return sum / #times
-end
-
--- Main logic to time the test function
-
-local CASES = {
-	jecs = function(world, ...)
-		for i = 1, 100 do
-			local q = world:query(...)
-			for _ in q do
-			end
-		end
-	end,
-	mirror = function(world, ...)
-		for i = 1, 100 do
-			local q = world:query(...)
-			for _ in q do
-			end
-		end
-	end,
-}
-
-for name, fn in CASES do
-	local times = {}
-	local allocations = {}
-	local ecs = require("@" .. name)
-	local world = ecs.World.new()
-	local A, B, C = world:component(), world:component(), world:component()
-
-	for i = 1, 5 do
-		local e = world:entity()
-		world:add(e, A)
-		world:add(e, B)
-		world:add(e, C)
-	end
-
-	collectgarbage("collect")
-	local count = collectgarbage("count")
-
-	for i = 1, 50000 do
-		local startTime = os.clock()
-		fn(world, A, B, C)
-		local allocated = collectgarbage("count")
-		collectgarbage("collect")
-		local endTime = os.clock()
-		table.insert(times, endTime - startTime)
-		table.insert(allocations, allocated)
-	end
-
-	print(name, "gc cycle time", calculateAverage(times))
-	print(name, "memory allocated", calculateAverage(allocations))
-end

test/lol.luau

@@ -1,157 +1,158 @@
-local c = {
-	white_underline = function(s: any)
-		return `\27[1;4m{s}\27[0m`
-	end,
-
-	white = function(s: any)
-		return `\27[37;1m{s}\27[0m`
-	end,
-
-	green = function(s: any)
-		return `\27[32;1m{s}\27[0m`
-	end,
-
-	red = function(s: any)
-		return `\27[31;1m{s}\27[0m`
-	end,
-
-	yellow = function(s: any)
-		return `\27[33;1m{s}\27[0m`
-	end,
-
-	red_highlight = function(s: any)
-		return `\27[41;1;30m{s}\27[0m`
-	end,
-
-	green_highlight = function(s: any)
-		return `\27[42;1;30m{s}\27[0m`
-	end,
-
-	gray = function(s: any)
-		return `\27[30;1m{s}\27[0m`
-	end,
-}
-
-
-local ECS_PAIR_FLAG =                      0x8
-local ECS_ID_FLAGS_MASK =                 0x10
-local ECS_ENTITY_MASK =     bit32.lshift(1, 24)
-local ECS_GENERATION_MASK = bit32.lshift(1, 16)
-
-type i53 = number
-type i24 = number
-
-local function ECS_ENTITY_T_LO(e: i53): i24
-	return if e > ECS_ENTITY_MASK then (e // ECS_ID_FLAGS_MASK) // ECS_ENTITY_MASK else e
-end
-
-local function ECS_GENERATION(e: i53): i24
-	return if e > ECS_ENTITY_MASK then (e // ECS_ID_FLAGS_MASK) % ECS_GENERATION_MASK else 0
-end
-
-local ECS_ID = ECS_ENTITY_T_LO
-
-local function ECS_COMBINE(source: number, target: number): i53
-	return (source * 268435456) + (target * ECS_ID_FLAGS_MASK)
-end
-
-local function ECS_GENERATION_INC(e: i53)
-	if e > ECS_ENTITY_MASK then
-		local flags = e // ECS_ID_FLAGS_MASK
-		local id = flags // ECS_ENTITY_MASK
-		local generation = flags % ECS_GENERATION_MASK
-
-		local next_gen = generation + 1
-		if next_gen > ECS_GENERATION_MASK then
-			return id
-		end
-
-		return ECS_COMBINE(id, next_gen) + flags
-	end
-	return ECS_COMBINE(e, 1)
-end
-
-local function bl()
-	print("")
-end
-
-local function pe(e)
-	local gen = ECS_GENERATION(e)
-	return c.green(`e{ECS_ID(e)}`)..c.yellow(`v{gen}`)
-end
-
-local function dprint(tbl: {  [number]: number })
-	bl()
-	print("--------")
-	for i, e in tbl do
-		print("| "..pe(e).." |")
-		print("--------")
-	end
-	bl()
-end
-
-local max_id = 0
-local alive_count = 0
-local dense = {}
-local sparse = {}
-local function alloc()
-	if alive_count ~= #dense then
-		alive_count += 1
-		print("*recycled", pe(dense[alive_count]))
-		return dense[alive_count]
-	end
-	max_id += 1
-	local id = max_id
-	alive_count += 1
-	dense[alive_count] = id
-	sparse[id] = {
-		dense = alive_count
-	}
-	print("*allocated", pe(id))
-	return id
-end
-
-local function remove(entity)
-	local id = ECS_ID(entity)
-	local r = sparse[id]
-	local index_of_deleted_entity = r.dense
-	local last_entity_alive_at_index = alive_count -- last entity alive
-	alive_count -= 1
-	local last_alive_entity = dense[last_entity_alive_at_index]
-	local r_swap = sparse[ECS_ID(last_alive_entity)]
-	r_swap.dense = r.dense
-	r.dense = last_entity_alive_at_index
-	dense[index_of_deleted_entity] = last_alive_entity
-	dense[last_entity_alive_at_index] = ECS_GENERATION_INC(entity)
-end
-
-local function alive(e)
-	local r = sparse[ECS_ID(e)]
-
-	return dense[r.dense] == e
-end
-
-local function pa(e)
-	print(`{pe(e)} is {if alive(e) then "alive" else "not alive"}`)
-end
-
-local tprint = require("@testkit").print
-local e1v0 = alloc()
-local e2v0 = alloc()
-local e3v0 = alloc()
-local e4v0 = alloc()
-local e5v0 = alloc()
-pa(e1v0)
-pa(e4v0)
-remove(e5v0)
-pa(e5v0)
-
-local e5v1 = alloc()
-pa(e5v0)
-pa(e5v1)
-pa(e2v0)
-print(ECS_ID(e2v0))
-
-dprint(dense)
-remove(e2v0)
-dprint(dense)
+local c = {
+	white_underline = function(s: any)
+		return `\27[1;4m{s}\27[0m`
+	end,
+
+	white = function(s: any)
+		return `\27[37;1m{s}\27[0m`
+	end,
+
+	green = function(s: any)
+		return `\27[32;1m{s}\27[0m`
+	end,
+
+	red = function(s: any)
+		return `\27[31;1m{s}\27[0m`
+	end,
+
+	yellow = function(s: any)
+		return `\27[33;1m{s}\27[0m`
+	end,
+
+	red_highlight = function(s: any)
+		return `\27[41;1;30m{s}\27[0m`
+	end,
+
+	green_highlight = function(s: any)
+		return `\27[42;1;30m{s}\27[0m`
+	end,
+
+	gray = function(s: any)
+		return `\27[30;1m{s}\27[0m`
+	end,
+}
+
+
+local ECS_PAIR_FLAG =                      0x8
+local ECS_ID_FLAGS_MASK =                 0x10
+local ECS_ENTITY_MASK =     bit32.lshift(1, 24)
+local ECS_GENERATION_MASK = bit32.lshift(1, 16)
+
+type i53 = number
+type i24 = number
+
+local function ECS_ENTITY_T_LO(e: i53): i24
+	return if e > ECS_ENTITY_MASK then (e // ECS_ID_FLAGS_MASK) // ECS_ENTITY_MASK else e
+end
+
+local function ECS_GENERATION(e: i53): i24
+	return if e > ECS_ENTITY_MASK then (e // ECS_ID_FLAGS_MASK) % ECS_GENERATION_MASK else 0
+end
+
+local ECS_ID = ECS_ENTITY_T_LO
+
+local function ECS_COMBINE(source: number, target: number): i53
+	return (source * 268435456) + (target * ECS_ID_FLAGS_MASK)
+end
+
+local function ECS_GENERATION_INC(e: i53)
+	if e > ECS_ENTITY_MASK then
+		local flags = e // ECS_ID_FLAGS_MASK
+		local id = flags // ECS_ENTITY_MASK
+		local generation = flags % ECS_GENERATION_MASK
+
+		local next_gen = generation + 1
+		if next_gen > ECS_GENERATION_MASK then
+			return id
+		end
+
+		return ECS_COMBINE(id, next_gen) + flags
+	end
+	return ECS_COMBINE(e, 1)
+end
+
+local function bl()
+	print("")
+end
+
+local function pe(e)
+	local gen = ECS_GENERATION(e)
+	return c.green(`e{ECS_ID(e)}`)..c.yellow(`v{gen}`)
+end
+
+local function dprint(tbl: {  [number]: number })
+	bl()
+	print("--------")
+	for i, e in tbl do
+		print("| "..pe(e).." |")
+		print("--------")
+	end
+	bl()
+end
+
+local max_id = 0
+local alive_count = 0
+local dense = {}
+local sparse = {}
+local function alloc()
+	if alive_count ~= #dense then
+		alive_count += 1
+		print("*recycled", pe(dense[alive_count]))
+		return dense[alive_count]
+	end
+	max_id += 1
+	local id = max_id
+	alive_count += 1
+	dense[alive_count] = id
+	sparse[id] = {
+		dense = alive_count
+	}
+	print("*allocated", pe(id))
+	return id
+end
+
+local function remove(entity)
+	local id = ECS_ID(entity)
+	local r = sparse[id]
+	local index_of_deleted_entity = r.dense
+	local last_entity_alive_at_index = alive_count -- last entity alive
+	alive_count -= 1
+	local last_alive_entity = dense[last_entity_alive_at_index]
+	local r_swap = sparse[ECS_ID(last_alive_entity)]
+	r_swap.dense = r.dense
+	r.dense = last_entity_alive_at_index
+	dense[index_of_deleted_entity] = last_alive_entity
+	dense[last_entity_alive_at_index] = ECS_GENERATION_INC(entity)
+	print("*dellocated", pe(id))
+end
+
+local function alive(e)
+	local r = sparse[ECS_ID(e)]
+
+	return dense[r.dense] == e
+end
+
+local function pa(e)
+	print(`{pe(e)} is {if alive(e) then "alive" else "not alive"}`)
+end
+
+local tprint = require("@testkit").print
+local e1v0 = alloc()
+local e2v0 = alloc()
+local e3v0 = alloc()
+local e4v0 = alloc()
+local e5v0 = alloc()
+pa(e1v0)
+pa(e4v0)
+remove(e5v0)
+pa(e5v0)
+
+local e5v1 = alloc()
+pa(e5v0)
+pa(e5v1)
+pa(e2v0)
+print(ECS_ID(e2v0))
+
+dprint(dense)
+remove(e2v0)
+dprint(dense)

test/memory.luau

@@ -1,14 +0,0 @@
-local jecs = require("@jecs")
-local testkit = require("@testkit")
-
-local world = jecs.World.new()
-
-local A = world:component()
-local B = world:component()
-
-local e = world:entity()
-world:add(e, A)
-world:add(e, B)
-local archetype_id = world.archetypeIndex["1_2"].id
-world:delete(e)
-testkit.print(world)

test/stress.client.luau

@@ -0,0 +1,122 @@
+local RunService = game:GetService("RunService")
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+_G.__JECS_HI_COMPONENT_ID = 300
+local ecs = require(ReplicatedStorage.ecs)
+
+-- 500 entities
+-- 2-30 components on each entity
+-- 300 unique components
+-- 200 systems
+-- 1-10 components to query per system
+
+local startTime = os.clock()
+
+local world = ecs.World.new()
+
+local components = {}
+
+for i = 1, 300 do -- 300 components
+	components[i] = world:component()
+end
+
+local archetypes = {}
+for i = 1, 50 do -- 50 archetypes
+	local archetype = {}
+
+	for _ = 1, math.random(2, 30) do
+		local componentId = math.random(1, #components)
+
+		table.insert(archetype, components[componentId])
+	end
+
+	archetypes[i] = archetype
+end
+
+for _ = 1, 1000 do -- 1000 entities in the world
+	local componentsToAdd = {}
+
+	local archetypeId = math.random(1, #archetypes)
+	local e = world:entity()
+	for _, component in ipairs(archetypes[archetypeId]) do
+		world:set(e, component, {
+			DummyData = math.random(1, 5000),
+		})
+	end
+end
+
+local function values(t)
+	local array = {}
+	for _, v in t do
+		table.insert(array, v)
+	end
+	return array
+end
+
+local contiguousComponents = values(components)
+local systemComponentsToQuery = {}
+
+for _ = 1, 200 do -- 200 systems
+	local numComponentsToQuery = math.random(1, 10)
+	local componentsToQuery = {}
+
+	for _ = 1, numComponentsToQuery do
+		table.insert(componentsToQuery, contiguousComponents[math.random(1, #contiguousComponents)])
+	end
+
+	table.insert(systemComponentsToQuery, componentsToQuery)
+end
+
+local worldCreateTime = os.clock() - startTime
+local results = {}
+startTime = os.clock()
+
+RunService.Heartbeat:Connect(function()
+	local added = 0
+	local systemStartTime = os.clock()
+	debug.profilebegin("systems")
+	for _, componentsToQuery in ipairs(systemComponentsToQuery) do
+		debug.profilebegin("system")
+		for entityId, firstComponent in world:query(unpack(componentsToQuery)) do
+			world:set(
+				entityId,
+				{
+					DummyData = firstComponent.DummyData + 1,
+				}
+			)
+			added += 1
+		end
+		debug.profileend()
+	end
+	debug.profileend()
+
+	if os.clock() - startTime < 4 then
+		-- discard first 4 seconds
+		return
+	end
+
+	if results == nil then
+		return
+	elseif #results < 1000 then
+		table.insert(results, os.clock() - systemStartTime)
+	else
+		print("added", added)
+		print("World created in", worldCreateTime * 1000, "ms")
+		local sum = 0
+		for _, result in ipairs(results) do
+			sum += result
+		end
+		print(("Average frame time: %fms"):format((sum / #results) * 1000))
+
+		results = nil
+
+		local n = #world.archetypes
+
+		print(
+			("X entities\n%d components\n%d systems\n%d archetypes"):format(
+				#components,
+				#systemComponentsToQuery,
+				n
+			)
+		)
+	end
+end)

test/stress.project.json

@@ -0,0 +1,19 @@
+{
+	"name": "Stress",
+	"tree": {
+		"$className": "DataModel",
+		"ReplicatedStorage": {
+			"$className": "ReplicatedStorage",
+			"$path": "DevPackages",
+			"ecs": {
+				"$path": "jecs.luau"
+			}
+		},
+		"ReplicatedFirst": {
+			"$className": "ReplicatedFirst",
+			"stres": {
+				"$path": "stress.client.luau"
+			}
+		}
+	}
+}

test/tools/entity_visualiser.luau

@@ -0,0 +1,24 @@
+local jecs = require("@jecs")
+local pair = jecs.pair
+local ChildOf = jecs.ChildOf
+local lifetime_tracker_add = require("@tools/lifetime_tracker")
+local world = lifetime_tracker_add(jecs.world(), {padding_enabled=false})
+local FriendsWith = world:component()
+world:print_snapshot()
+local e1 = world:entity()
+local e2 = world:entity()
+world:delete(e2)
+
+world:print_snapshot()
+local e3 = world:entity()
+world:add(e3, pair(ChildOf, e1))
+local e4 = world:entity()
+world:add(e4, pair(FriendsWith, e3))
+world:print_snapshot()
+world:delete(e1)
+world:delete(e3)
+world:print_snapshot()
+world:print_entity_index()
+world:entity()
+world:entity()
+world:print_snapshot()

testez.d.luau

@@ -1,24 +0,0 @@
-declare function afterAll(callback: () -> ()): ()
-declare function afterEach(callback: () -> ()): ()
-
-declare function beforeAll(callback: () -> ()): ()
-declare function beforeEach(callback: () -> ()): ()
-
-declare function describe(phrase: string, callback: () -> ()): ()
-declare function describeFOCUS(phrase: string, callback: () -> ()): ()
-declare function fdescribe(phrase: string, callback: () -> ()): ()
-declare function describeSKIP(phrase: string, callback: () -> ()): ()
-declare function xdescribe(phrase: string, callback: () -> ()): ()
-
-declare function expect(value: any): any
-
-declare function FIXME(optionalMessage: string?): ()
-declare function FOCUS(): ()
-declare function SKIP(): ()
-
-declare function it(phrase: string, callback: () -> ()): ()
-declare function itFOCUS(phrase: string, callback: () -> ()): ()
-declare function fit(phrase: string, callback: () -> ()): ()
-declare function itSKIP(phrase: string, callback: () -> ()): ()
-declare function xit(phrase: string, callback: () -> ()): ()
-declare function itFIXME(phrase: string, callback: () -> ()): ()

tools/entity_visualiser.luau

@@ -0,0 +1,120 @@
+local jecs = require("@jecs")
+local ECS_GENERATION = jecs.ECS_GENERATION
+local ECS_ID = jecs.ECS_ID
+
+local ansi = {
+	white_underline = function(s: any)
+		return `\27[1;4m{s}\27[0m`
+	end,
+
+	white = function(s: any)
+		return `\27[37;1m{s}\27[0m`
+	end,
+
+	green = function(s: any)
+		return `\27[32;1m{s}\27[0m`
+	end,
+
+	red = function(s: any)
+		return `\27[31;1m{s}\27[0m`
+	end,
+
+	yellow = function(s: any)
+		return `\27[33;1m{s}\27[0m`
+	end,
+
+	red_highlight = function(s: any)
+		return `\27[41;1;30m{s}\27[0m`
+	end,
+
+	green_highlight = function(s: any)
+		return `\27[42;1;30m{s}\27[0m`
+	end,
+
+	gray = function(s: any)
+		return `\27[30;1m{s}\27[0m`
+	end,
+}
+
+local function pe(e: any)
+	local gen = ECS_GENERATION(e)
+	return ansi.green(`e{ECS_ID(e)}`) .. ansi.yellow(`v{gen}`)
+end
+
+local function name(world: jecs.World, id: any)
+	return world:get(id, jecs.Name) or `${id}`
+end
+
+local function components(world: jecs.World, entity: any)
+	local r = jecs.entity_index_try_get(world.entity_index, entity)
+	if not r then
+		return false
+	end
+
+	local archetype = r.archetype
+	local row = r.row
+	print(`Entity {pe(entity)}`)
+	print("-----------------------------------------------------")
+	for i, column in archetype.columns do
+		local component = archetype.types[i]
+		local n
+		if jecs.IS_PAIR(component) then
+			n = `({name(world, jecs.pair_first(world, component))}, {name(world, jecs.pair_second(world, component))})`
+		else
+			n = name(world, component)
+		end
+		local data = column[row] or "TAG"
+		print(`| {n} | {data} |`)
+	end
+	print("-----------------------------------------------------")
+	return true
+end
+
+local entity_index_try_get_any = jecs.entity_index_try_get_any
+
+local function stringify(world: jecs.World)
+	local function record(e: jecs.Entity): jecs.Record
+		return entity_index_try_get_any(world.entity_index :: any, e :: any) :: any
+	end
+	local function tbl(e: jecs.Entity)
+		return record(e).archetype
+	end
+	local function archetype(e: jecs.Entity)
+		return tbl(e).type
+	end
+	local function records(e: jecs.Entity)
+		return tbl(e).records
+	end
+	local function columns(e: jecs.Entity)
+		return tbl(e).columns
+	end
+	local function row(e: jecs.Entity)
+		return record(e).row
+	end
+
+	-- Important to order them in the order of their columns
+	local function tuple(e, ...)
+		for i, column in columns(e) do
+			if select(i, ...) ~= column[row(e)] then
+				return false
+			end
+		end
+		return true
+	end
+
+	return {
+		record = record,
+		tbl = tbl,
+		archetype = archetype,
+		records = records,
+		row = row,
+		tuple = tuple,
+		columns = columns
+	}
+end
+
+return {
+	components = components,
+	prettify = pe,
+	stringify = stringify
+}

tools/lifetime_tracker.luau

@@ -0,0 +1,218 @@
+local jecs = require("@jecs")
+local ECS_GENERATION = jecs.ECS_GENERATION
+local ECS_ID = jecs.ECS_ID
+local __ = jecs.Wildcard
+local pair = jecs.pair
+
+local prettify = require("@tools/entity_visualiser").prettify
+
+local pe = prettify
+
+function print_centered_entity(entity, width: number)
+	local entity_str = tostring(entity)
+	local entity_length = #entity_str
+
+	local padding_total = width - 2 - entity_length
+
+	local padding_left = math.floor(padding_total / 2)
+	local padding_right = padding_total - padding_left
+
+	local centered_str = string.rep(" ", padding_left) .. entity_str .. string.rep(" ", padding_right)
+
+	print("|" .. centered_str .. "|")
+end
+
+local function name(world, e)
+	return world:get(world, e, jecs.Name) or pe(e)
+end
+local padding_enabled = false
+local function pad()
+	if padding_enabled then
+		print("")
+	end
+end
+
+type PatchedWorld = jecs.World & {
+	print_entity_index: (world: PatchedWorld) -> (),
+	print_snapshot: (world: PatchedWorld) -> (),
+}
+
+local function lifetime_tracker_add(world: jecs.World, opt): PatchedWorld
+	local entity_index = world.entity_index
+	local dense_array = entity_index.dense_array
+	local component_index = world.component_index
+
+	local ENTITY_RANGE = (jecs.Rest :: any) + 1
+
+	padding_enabled = opt.padding_enabled
+
+	local world_entity = world.entity
+	world.entity = function(_, entity)
+		if entity then
+			return world_entity(world, entity)
+		end
+		local will_recycle = entity_index.max_id ~= entity_index.alive_count
+		local e = world_entity(world)
+		if will_recycle then
+			print(`*recycled {pe(e)}`)
+		else
+			print(`*created {pe(e)}`)
+		end
+		pad()
+		return e
+	end
+	world.print_entity_index = function()
+		local max_id = entity_index.max_id
+		local alive_count = entity_index.alive_count
+		local alive = table.move(dense_array, 1 + jecs.Rest :: any, alive_count, 1, {})
+		local dead = table.move(dense_array, alive_count + 1, max_id, 1, {})
+
+		local sep = "|--------|"
+		if #alive > 0 then
+			print("|-alive--|")
+			for i = 1, #alive do
+				local e = pe(alive[i])
+				print_centered_entity(e, 32)
+				print(sep)
+			end
+			print("\n")
+		end
+
+		if #dead > 0 then
+			print("|--dead--|")
+			for i = 1, #dead do
+				print_centered_entity(pe(dead[i]), 32)
+				print(sep)
+			end
+		end
+		pad()
+	end
+	local timelines = {}
+	world.print_snapshot = function(_)
+		local timeline = #timelines + 1
+		local entity_column_width = 10
+		local status_column_width = 8
+
+		local header = string.format("| %-" .. entity_column_width .. "s |", "Entity")
+		for i = 1, timeline do
+			header = header .. string.format(" %-" .. status_column_width .. "s |", string.format("T%d", i))
+		end
+
+		local max_id = entity_index.max_id
+		local alive_count = entity_index.alive_count
+		local alive = table.move(dense_array, 1 + jecs.Rest :: any, alive_count, 1, {})
+		local dead = table.move(dense_array, alive_count + 1, max_id, 1, {})
+
+		local data = {}
+		print("-------------------------------------------------------------------")
+		print(header)
+
+		-- Store the snapshot data for this timeline
+		for i = ENTITY_RANGE, max_id do
+			if dense_array[i] then
+				local entity = dense_array[i]
+				local id = ECS_ID(entity)
+				local status = "alive"
+				if not world:contains(entity) then
+					status = "dead"
+				end
+				data[id] = status
+			end
+		end
+
+		table.insert(timelines, data)
+
+		-- Create a table to hold entity data for sorting
+		local entities = {}
+		for i = ENTITY_RANGE, max_id do
+			if dense_array[i] then
+				local entity = dense_array[i]
+				local id = ECS_ID(entity)
+				-- Push entity and id into the new `entities` table
+				table.insert(entities, { entity = entity, id = id })
+			end
+		end
+
+		-- Sort the entities by ECS_ID
+		table.sort(entities, function(a, b)
+			return a.id < b.id
+		end)
+
+		-- Print the sorted rows
+		for _, entity_data in ipairs(entities) do
+			local entity = entity_data.entity
+			local id = entity_data.id
+			local status = "alive"
+			if id > alive_count then
+				status = "dead"
+			end
+			local row = string.format("| %-" .. entity_column_width .. "s     |", pe(entity))
+			for j = 1, timeline do
+				local timeline_data = timelines[j]
+				local entity_data = timeline_data[id]
+				if entity_data then
+					row = row .. string.format(" %-" .. status_column_width .. "s |", entity_data)
+				else
+					row = row .. string.format(" %-" .. status_column_width .. "s |", "-")
+				end
+			end
+			print(row)
+		end
+		print("-------------------------------------------------------------------")
+		pad()
+	end
+	local world_add = world.add
+	local relations = {}
+	world.add = function(_, entity: any, component: any)
+		world_add(world, entity, component)
+		if jecs.IS_PAIR(component) then
+			local relation = jecs.pair_first(world, component)
+			local target = jecs.pair_second(world, component)
+			print(`*added ({pe(relation)}, {pe(target)}) to {pe(entity)}`)
+			pad()
+		end
+	end
+
+	local world_delete = world.delete
+	world.delete = function(world, e)
+		world_delete(world, e)
+
+		local idr_t = component_index[pair(__, e)]
+		if idr_t then
+			for archetype_id in idr_t.cache do
+				local archetype = world.archetypes[archetype_id]
+				for _, id in archetype.types do
+					if not jecs.IS_PAIR(id) then
+						continue
+					end
+					local object = jecs.pair_second(world, id)
+					if object ~= e then
+						continue
+					end
+					local id_record = component_index[id]
+					local flags = id_record.flags
+					local flags_delete_mask: number = bit32.band(flags, jecs.ECS_ID_DELETE)
+					if flags_delete_mask ~= 0 then
+						for _, entity in archetype.entities do
+							print(`*deleted dependant {pe(entity)} of {pe(e)}`)
+							pad()
+						end
+						break
+					else
+						for _, entity in archetype.entities do
+							print(
+								`*removed dependency ({pe(jecs.pair_first(world, id))}, {pe(object)}) from {pe(entity)}`
+							)
+						end
+					end
+				end
+			end
+		end
+
+		print(`*deleted {pe(e)}`)
+		pad()
+	end
+	return world
+end
+
+return lifetime_tracker_add

tools/perfgraph.py

@@ -0,0 +1,177 @@
+#!/usr/bin/python3
+# This file is part of the Luau programming language and is licensed under MIT License; see LICENSE.txt for details
+
+# Given a profile dump, this tool generates a flame graph based on the stacks listed in the profile
+# The result of analysis is a .svg file which can be viewed in a browser
+
+import svg
+import argparse
+import json
+
+argumentParser = argparse.ArgumentParser(description='Generate flamegraph SVG from Luau sampling profiler dumps')
+argumentParser.add_argument('source_file', type=open)
+argumentParser.add_argument('--json', dest='useJson',action='store_const',const=1,default=0,help='Parse source_file as JSON')
+
+class Node(svg.Node):
+    def __init__(self):
+        svg.Node.__init__(self)
+        self.function = ""
+        self.source = ""
+        self.line = 0
+        self.ticks = 0
+
+    def text(self):
+        return self.function
+
+    def title(self):
+        if self.line > 0:
+            return "{}\n{}:{}".format(self.function, self.source, self.line)
+        else:
+            return self.function
+
+    def details(self, root):
+        return "Function: {} [{}:{}] ({:,} usec, {:.1%}); self: {:,} usec".format(self.function, self.source, self.line, self.width, self.width / root.width, self.ticks)
+
+
+def nodeFromCallstackListFile(source_file):
+    dump = source_file.readlines()
+    root = Node()
+
+    for l in dump:
+        ticks, stack = l.strip().split(" ", 1)
+        node = root
+
+        for f in reversed(stack.split(";")):
+            source, function, line = f.split(",")
+
+            child = node.child(f)
+            child.function = function
+            child.source = source
+            child.line = int(line) if len(line) > 0 else 0
+
+            node = child
+
+        node.ticks += int(ticks)
+
+    return root
+
+
+def getDuration(nodes, nid):
+    node = nodes[nid - 1]
+    total = node['TotalDuration']
+
+    if 'NodeIds' in node:
+        for cid in node['NodeIds']:
+            total -= nodes[cid - 1]['TotalDuration']
+
+    return total
+
+def getFunctionKey(fn):
+    source = fn['Source'] if 'Source' in fn else ''
+    name = fn['Name'] if 'Name' in fn else ''
+    line = str(fn['Line']) if 'Line' in fn else '-1'
+
+    return source + "," + name + "," + line
+
+def recursivelyBuildNodeTree(nodes, functions, parent, fid, nid):
+    ninfo = nodes[nid - 1]
+    finfo = functions[fid - 1]
+
+    child = parent.child(getFunctionKey(finfo))
+    child.source = finfo['Source'] if 'Source' in finfo else ''
+    child.function = finfo['Name'] if 'Name' in finfo else ''
+    child.line = int(finfo['Line']) if 'Line' in finfo and finfo['Line'] > 0 else 0
+
+    child.ticks = getDuration(nodes, nid)
+
+    if 'FunctionIds' in ninfo:
+        assert(len(ninfo['FunctionIds']) == len(ninfo['NodeIds']))
+
+        for i in range(0, len(ninfo['FunctionIds'])):
+            recursivelyBuildNodeTree(nodes, functions, child, ninfo['FunctionIds'][i], ninfo['NodeIds'][i])
+
+    return
+
+def nodeFromJSONV2(dump):
+    assert(dump['Version'] == 2)
+
+    nodes = dump['Nodes']
+    functions = dump['Functions']
+    categories = dump['Categories']
+
+    root = Node()
+
+    for category in categories:
+        nid = category['NodeId']
+        node = nodes[nid - 1]
+        name = category['Name']
+
+        child = root.child(name)
+        child.function = name
+        child.ticks = getDuration(nodes, nid)
+
+        if 'FunctionIds' in node:
+            assert(len(node['FunctionIds']) == len(node['NodeIds']))
+
+            for i in range(0, len(node['FunctionIds'])):
+                recursivelyBuildNodeTree(nodes, functions, child, node['FunctionIds'][i], node['NodeIds'][i])
+
+    return root
+
+def getDurationV1(obj):
+    total = obj['TotalDuration']
+
+    if 'Children' in obj:
+        for key, obj in obj['Children'].items():
+            total -= obj['TotalDuration']
+
+    return total
+
+
+def nodeFromJSONObject(node, key, obj):
+    source, function, line = key.split(",")
+
+    node.function = function
+    node.source = source
+    node.line = int(line) if len(line) > 0 else 0
+
+    node.ticks = getDurationV1(obj)
+
+    if 'Children' in obj:
+        for key, obj in obj['Children'].items():
+            nodeFromJSONObject(node.child(key), key, obj)
+
+    return node
+
+def nodeFromJSONV1(dump):
+    assert(dump['Version'] == 1)
+    root = Node()
+
+    if 'Children' in dump:
+        for key, obj in dump['Children'].items():
+            nodeFromJSONObject(root.child(key), key, obj)
+
+    return root
+
+def nodeFromJSONFile(source_file):
+    dump = json.load(source_file)
+
+    if dump['Version'] == 2:
+        return nodeFromJSONV2(dump)
+    elif dump['Version'] == 1:
+        return nodeFromJSONV1(dump)
+
+    return Node()
+
+
+arguments = argumentParser.parse_args()
+
+if arguments.useJson:
+    root = nodeFromJSONFile(arguments.source_file)
+else:
+    root = nodeFromCallstackListFile(arguments.source_file)
+
+
+
+svg.layout(root, lambda n: n.ticks)
+svg.display(root, "Flame Graph", "hot", flip = True)

tools/read_lcov.py

@@ -0,0 +1,153 @@
+import os
+
+LCOV_FILE = "coverage.out"
+OUTPUT_DIR = "coverage"
+
+os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+def parse_lcov(content):
+    """Parses LCOV data from a single string."""
+    files = {}
+    current_file = None
+
+    for line in content.splitlines():
+        if line.startswith("SF:"):
+            current_file = line[3:].strip()
+            files[current_file] = {"coverage": {}, "functions": []}
+        elif line.startswith("DA:") and current_file:
+            parts = line[3:].split(",")
+            line_num = int(parts[0])
+            execution_count = int(parts[1])
+            files[current_file]["coverage"][line_num] = execution_count
+        elif line.startswith("FN:") and current_file:
+            parts = line[3:].split(",")
+            line_num = int(parts[0])
+            function_name = parts[1].strip()
+            files[current_file]["functions"].append({"name": function_name, "line": line_num, "hits": 0})
+        elif line.startswith("FNDA:") and current_file:
+            parts = line[5:].split(",")
+            hit_count = int(parts[0])
+            function_name = parts[1].strip()
+            for func in files[current_file]["functions"]:
+                if func["name"] == function_name:
+                    func["hits"] = hit_count
+                    break
+
+    return files
+
+def read_source_file(filepath):
+    """Reads source file content if available."""
+    if not os.path.exists(filepath):
+        return []
+
+    with open(filepath, "r", encoding="utf-8") as f:
+        return f.readlines()
+
+def generate_file_html(filepath, coverage_data, functions_data):
+    """Generates an HTML file for a specific source file."""
+    filename = os.path.basename(filepath)
+    source_code = read_source_file(filepath)
+    html_path = os.path.join(OUTPUT_DIR, f"{filename}.html")
+
+    total_hits = sum(func["hits"] for func in functions_data)
+    max_hits = max((func["hits"] for func in functions_data), default=0)
+
+    total_functions = len(functions_data)
+    covered_functions = sum(1 for func in functions_data if func["hits"] > 0)
+    function_coverage_percent = (covered_functions / total_functions * 100) if total_functions > 0 else 0
+
+    lines = [
+        "<html><head>",
+        '<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">',
+        '<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/js/bootstrap.bundle.min.js"></script>',
+        "<style>",
+        "body { font-family: monospace; text-align: center; }",
+        "#funcTable table { margin: 0 auto; width: auto; max-width: 300px; font-size: 14px; border-collapse: collapse; }",
+        "#funcTable th, #funcTable td { padding: 2px 6px; text-align: left; white-space: nowrap; }",
+        "#funcTable th { background-color: #ddd; }",
+        "#funcTable td:nth-child(2) { text-align: right; min-width: 50px; }",
+        ".zero-hits { background-color: #fcc; font-weight: bold; color: red; }",
+        ".nonzero-hits { color: green; font-weight: bold; }",
+        ".low-hits { background-color: #ffe6b3; }",
+        ".high-hits { background-color: #cfc; }",
+        ".source-code-table { margin-left: 10px; }"
+        "th, td { padding: 0px; font-size: 12px; }",
+        "table.table { font-size: 14px; border-collapse: collapse; }",
+        "table.table th, table.table td { padding: 1px; font-size: 12px; line-height: 1.2; }",
+        "table.table tr { height: auto; }",
+        "</style></head><body>",
+        f'<h1 class="text-center">{filename} Coverage</h1>',
+        f'<h2>Total Execution Hits: {total_hits}</h2>',
+        f'<h2>Function Coverage Overview: {function_coverage_percent:.2f}%</h2>',
+
+        '<button class="btn btn-primary mb-2" type="button" data-bs-toggle="collapse" data-bs-target="#funcTable">'
+        'Toggle Function Coverage</button>',
+
+        '<div class="collapse show" id="funcTable">',
+        '<h2>Function Coverage:</h2><table class="table table-bordered"><thead><tr><th>Function</th><th>Hits</th></tr></thead><tbody>'
+    ]
+
+    longest_name = max((len(func["name"]) for func in functions_data), default=0)
+
+    for func in functions_data:
+        hit_color = "red" if func["hits"] == 0 else "green"
+        lines.append(
+            f'<tr><td style="padding: 1px; min-width: {longest_name}ch;">{func["name"]}</td>'
+            f'<td style="padding: 1px; color: {hit_color}; font-weight: bold;">{func["hits"]}</td></tr>'
+        )
+
+    lines.append('</tbody></table></div>')  # Close collapsible div
+
+    lines.append('<h2>Source Code:</h2><table class="table table-bordered source-code-table "><thead><tr><th>Line</th><th>Hits</th><th>Code</th></tr></thead><tbody>')
+
+    for i, line in enumerate(source_code, start=1):
+        stripped_line = line.strip()
+        class_name = "text-muted"
+        if not stripped_line or stripped_line.startswith("end") or stripped_line.startswith("--"):
+            count_display = "<span class='text-muted'>N/A</span>"
+            lines.append(f'<tr><td>{i}</td><td>{count_display}</td><td>{line.strip()}</td>></tr>')
+        else:
+            count = coverage_data.get(i, 0)
+            class_name = "zero-hits" if count == 0 else "low-hits" if count < max_hits * 0.3 else "high-hits"
+            count_display = f'{count}'
+            marked_text = f'<span class={class_name}>{line.strip()}</span>'
+            lines.append(f'<tr><td>{i}</td><td>{count_display}</td><td>{marked_text}</td></tr>')
+
+    lines.append("</tbody></table></body></html>")
+
+    with open(html_path, "w", encoding="utf-8") as f:
+        f.write("\n".join(lines))
+
+def generate_index(files):
+    """Generates an index.html summarizing the coverage."""
+    index_html = [
+        "<html><head>",
+        '<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">',
+        "</head><body>",
+        '<h1 class="text-center">Coverage Report</h1>',
+        '<table class="table table-striped table-bordered"><thead><tr><th>File</th><th>Total Hits</th><th>Functions</th></tr></thead><tbody>'
+    ]
+
+    for filepath, data in files.items():
+        filename = os.path.basename(filepath)
+        total_hits = sum(func["hits"] for func in data["functions"])
+        total_functions = len(data["functions"])
+
+        index_html.append(f'<tr><td><a href="{filename}.html">{filename}</a></td><td>{total_hits}</td><td>{total_functions}</td></tr>')
+
+    index_html.append("</tbody></table></body></html>")
+
+    with open(os.path.join(OUTPUT_DIR, "index.html"), "w", encoding="utf-8") as f:
+        f.write("\n".join(index_html))
+
+with open(LCOV_FILE, "r", encoding="utf-8") as f:
+    lcov_content = f.read()
+
+files_data = parse_lcov(lcov_content)
+
+for file_path, data in files_data.items():
+    generate_file_html(file_path, data["coverage"], data["functions"])
+
+generate_index(files_data)
+
+print(f"Coverage report generated in {OUTPUT_DIR}/index.html")

tools/runtime_lints.luau

@@ -0,0 +1,108 @@
+local function dbg_info(n: number): any
+	return debug.info(n, "s")
+end
+local function throw(msg: string)
+	local s = 1
+	local root = dbg_info(1)
+	repeat
+		s += 1
+	until dbg_info(s) ~= root
+	if warn then
+		error(msg, s)
+	else
+		print(`[jecs] error: {msg}\n`)
+	end
+end
+
+local function ASSERT<T>(v: T, msg: string)
+	if v then
+		return
+	end
+	throw(msg)
+end
+
+local function runtime_lints_add(world)
+	local function get_name(id)
+		return world_get_one_inline(world, id, EcsName)
+	end
+
+	local function bname(id): string
+		local name: string
+		if ECS_IS_PAIR(id) then
+			local first = get_name(world, ecs_pair_first(world, id))
+			local second = get_name(world, ecs_pair_second(world, id))
+			name = `pair({first}, {second})`
+		else
+			return get_name(world, id)
+		end
+		if name then
+			return name
+		else
+			return `${id}`
+		end
+	end
+
+	local function ID_IS_TAG(world: World, id)
+		if ECS_IS_PAIR(id) then
+			id = ecs_pair_first(world, id)
+		end
+		return not world_has_one_inline(world, id, EcsComponent)
+	end
+
+	World.query = function(world: World, ...)
+		ASSERT((...), "Requires at least a single component")
+		return world_query(world, ...)
+	end
+
+	World.set = function(world: World, entity: i53, id: i53, value: any): ()
+		local is_tag = ID_IS_TAG(world, id)
+		if is_tag and value == nil then
+			local _1 = bname(world, entity)
+			local _2 = bname(world, id)
+			local why = "cannot set component value to nil"
+			throw(why)
+			return
+		elseif value ~= nil and is_tag then
+			local _1 = bname(world, entity)
+			local _2 = bname(world, id)
+			local why = `cannot set a component value because {_2} is a tag`
+			why ..= `\n[jecs] note: consider using "world:add({_1}, {_2})" instead`
+			throw(why)
+			return
+		end
+
+		world_set(world, entity, id, value)
+	end
+
+	World.add = function(world: World, entity: i53, id: i53, value: any)
+		if value ~= nil then
+			local _1 = bname(world, entity)
+			local _2 = bname(world, id)
+			throw("You provided a value when none was expected. " .. `Did you mean to use "world:add({_1}, {_2})"`)
+		end
+
+		world_add(world, entity, id)
+	end
+
+	World.get = function(world: World, entity: i53, ...)
+		local length = select("#", ...)
+		ASSERT(length < 5, "world:get does not support more than 4 components")
+		local _1
+		for i = 1, length do
+			local id = select(i, ...)
+			local id_is_tag = not world_has(world, id, EcsComponent)
+			if id_is_tag then
+				local name = get_name(world, id)
+				if not _1 then
+					_1 = get_name(world, entity)
+				end
+				throw(
+					`cannot get (#{i}) component {name} value because it is a tag.`
+						.. `\n[jecs] note: If this was intentional, use "world:has({_1}, {name}) instead"`
+				)
+			end
+		end
+
+		return world_get(world, entity, ...)
+	end
+end

tools/svg.py

@@ -0,0 +1,501 @@
+# This file is part of the Luau programming language and is licensed under MIT License; see LICENSE.txt for details
+
+class Node:
+    def __init__(self):
+        self.name = ""
+        self.children = {}
+        # computed
+        self.depth = 0
+        self.width = 0
+        self.offset = 0
+
+    def child(self, name):
+        node = self.children.get(name)
+        if not node:
+            node = self.__class__()
+            node.name = name
+            self.children[name] = node
+        return node
+
+    def subtree(self):
+        result = [self]
+        offset = 0
+
+        while offset < len(result):
+            p = result[offset]
+            offset += 1
+            for c in p.children.values():
+                result.append(c)
+
+        return result
+
+def escape(s):
+    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+def layout(root, widthcb):
+    for n in reversed(root.subtree()):
+        # propagate width to the parent
+        n.width = widthcb(n)
+        for c in n.children.values():
+            n.width += c.width
+
+        # compute offset from parent for every child in width order (layout order)
+        offset = 0
+        for c in sorted(n.children.values(), key = lambda x: x.width, reverse = True):
+            c.offset = offset
+            offset += c.width
+
+    for n in root.subtree():
+        for c in n.children.values():
+            c.depth = n.depth + 1
+            c.offset += n.offset
+
+# svg template (stolen from framegraph.pl)
+template = r"""<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" width="1200" height="$height" onload="init(evt)" viewBox="0 0 1200 $height" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<!-- Flame graph stack visualization. See https://github.com/brendangregg/FlameGraph for latest version, and http://www.brendangregg.com/flamegraphs.html for examples. -->
+<defs>
+    <linearGradient id="background" y1="0" y2="1" x1="0" x2="0" >
+        <stop stop-color="$gradient-start" offset="5%" />
+        <stop stop-color="$gradient-end" offset="95%" />
+    </linearGradient>
+</defs>
+<style type="text/css">
+    text { font-family:Verdana; font-size:12px; fill:rgb(0,0,0); }
+    #search, #ignorecase { opacity:0.1; cursor:pointer; }
+    #search:hover, #search.show, #ignorecase:hover, #ignorecase.show { opacity:1; }
+    #subtitle { text-anchor:middle; font-color:rgb(160,160,160); }
+    #title { text-anchor:middle; font-size:17px}
+    #unzoom { cursor:pointer; }
+    #frames > *:hover { stroke:black; stroke-width:0.5; cursor:pointer; }
+    .hide { display:none; }
+    .parent { opacity:0.5; }
+</style>
+<script type="text/ecmascript">
+<![CDATA[
+    "use strict";
+    var details, searchbtn, unzoombtn, matchedtxt, svg, searching, currentSearchTerm, ignorecase, ignorecaseBtn;
+    function init(evt) {
+        details = document.getElementById("details").firstChild;
+        searchbtn = document.getElementById("search");
+        ignorecaseBtn = document.getElementById("ignorecase");
+        unzoombtn = document.getElementById("unzoom");
+        matchedtxt = document.getElementById("matched");
+        svg = document.getElementsByTagName("svg")[0];
+        searching = 0;
+        currentSearchTerm = null;
+    }
+
+    window.addEventListener("click", function(e) {
+        var target = find_group(e.target);
+        if (target) {
+            if (target.nodeName == "a") {
+                if (e.ctrlKey === false) return;
+                e.preventDefault();
+            }
+            if (target.classList.contains("parent")) unzoom();
+            zoom(target);
+        }
+        else if (e.target.id == "unzoom") unzoom();
+        else if (e.target.id == "search") search_prompt();
+        else if (e.target.id == "ignorecase") toggle_ignorecase();
+    }, false)
+
+    // mouse-over for info
+    // show
+    window.addEventListener("mouseover", function(e) {
+        var target = find_group(e.target);
+        if (target) details.nodeValue = g_to_text(target);
+    }, false)
+
+    // clear
+    window.addEventListener("mouseout", function(e) {
+        var target = find_group(e.target);
+        if (target) details.nodeValue = ' ';
+    }, false)
+
+    // ctrl-F for search
+    window.addEventListener("keydown",function (e) {
+        if (e.keyCode === 114 || (e.ctrlKey && e.keyCode === 70)) {
+            e.preventDefault();
+            search_prompt();
+        }
+    }, false)
+
+    // ctrl-I to toggle case-sensitive search
+    window.addEventListener("keydown",function (e) {
+        if (e.ctrlKey && e.keyCode === 73) {
+            e.preventDefault();
+            toggle_ignorecase();
+        }
+    }, false)
+
+    // functions
+    function find_child(node, selector) {
+        var children = node.querySelectorAll(selector);
+        if (children.length) return children[0];
+        return;
+    }
+    function find_group(node) {
+        var parent = node.parentElement;
+        if (!parent) return;
+        if (parent.id == "frames") return node;
+        return find_group(parent);
+    }
+    function orig_save(e, attr, val) {
+        if (e.attributes["_orig_" + attr] != undefined) return;
+        if (e.attributes[attr] == undefined) return;
+        if (val == undefined) val = e.attributes[attr].value;
+        e.setAttribute("_orig_" + attr, val);
+    }
+    function orig_load(e, attr) {
+        if (e.attributes["_orig_"+attr] == undefined) return;
+        e.attributes[attr].value = e.attributes["_orig_" + attr].value;
+        e.removeAttribute("_orig_"+attr);
+    }
+    function g_to_text(e) {
+        var text = find_child(e, "details").firstChild.nodeValue;
+        return (text)
+    }
+    function g_to_func(e) {
+        var child = find_child(e, "rawtext");
+        return child ? child.textContent : null;
+    }
+    function update_text(e) {
+        var r = find_child(e, "rect");
+        var t = find_child(e, "text");
+        var w = parseFloat(r.attributes.width.value) -3;
+        var txt = find_child(e, "rawtext").textContent.replace(/\([^(]*\)$/,"");
+        t.attributes.x.value = parseFloat(r.attributes.x.value) + 3;
+
+        // Smaller than this size won't fit anything
+        if (w < 2 * 12 * 0.59) {
+            t.textContent = "";
+            return;
+        }
+
+        t.textContent = txt;
+        // Fit in full text width
+        if (/^ *$/.test(txt) || t.getSubStringLength(0, txt.length) < w)
+            return;
+
+        for (var x = txt.length - 2; x > 0; x--) {
+            if (t.getSubStringLength(0, x + 2) <= w) {
+                t.textContent = txt.substring(0, x) + "..";
+                return;
+            }
+        }
+        t.textContent = "";
+    }
+
+    // zoom
+    function zoom_reset(e) {
+        if (e.attributes != undefined) {
+            orig_load(e, "x");
+            orig_load(e, "width");
+        }
+        if (e.childNodes == undefined) return;
+        for (var i = 0, c = e.childNodes; i < c.length; i++) {
+            zoom_reset(c[i]);
+        }
+    }
+    function zoom_child(e, x, ratio) {
+        if (e.attributes != undefined) {
+            if (e.attributes.x != undefined) {
+                orig_save(e, "x");
+                e.attributes.x.value = (parseFloat(e.attributes.x.value) - x - 10) * ratio + 10;
+                if (e.tagName == "text")
+                    e.attributes.x.value = find_child(e.parentNode, "rect[x]").attributes.x.value + 3;
+            }
+            if (e.attributes.width != undefined) {
+                orig_save(e, "width");
+                e.attributes.width.value = parseFloat(e.attributes.width.value) * ratio;
+            }
+        }
+
+        if (e.childNodes == undefined) return;
+        for (var i = 0, c = e.childNodes; i < c.length; i++) {
+            zoom_child(c[i], x - 10, ratio);
+        }
+    }
+    function zoom_parent(e) {
+        if (e.attributes) {
+            if (e.attributes.x != undefined) {
+                orig_save(e, "x");
+                e.attributes.x.value = 10;
+            }
+            if (e.attributes.width != undefined) {
+                orig_save(e, "width");
+                e.attributes.width.value = parseInt(svg.width.baseVal.value) - (10 * 2);
+            }
+        }
+        if (e.childNodes == undefined) return;
+        for (var i = 0, c = e.childNodes; i < c.length; i++) {
+            zoom_parent(c[i]);
+        }
+    }
+    function zoom(node) {
+        var attr = find_child(node, "rect").attributes;
+        var width = parseFloat(attr.width.value);
+        var xmin = parseFloat(attr.x.value);
+        var xmax = parseFloat(xmin + width);
+        var ymin = parseFloat(attr.y.value);
+        var ratio = (svg.width.baseVal.value - 2 * 10) / width;
+
+        // XXX: Workaround for JavaScript float issues (fix me)
+        var fudge = 0.0001;
+
+        unzoombtn.classList.remove("hide");
+
+        var el = document.getElementById("frames").children;
+        for (var i = 0; i < el.length; i++) {
+            var e = el[i];
+            var a = find_child(e, "rect").attributes;
+            var ex = parseFloat(a.x.value);
+            var ew = parseFloat(a.width.value);
+            var upstack;
+            // Is it an ancestor
+            if ($flip == 1) {
+                upstack = parseFloat(a.y.value) > ymin;
+            } else {
+                upstack = parseFloat(a.y.value) < ymin;
+            }
+            if (upstack) {
+                // Direct ancestor
+                if (ex <= xmin && (ex+ew+fudge) >= xmax) {
+                    e.classList.add("parent");
+                    zoom_parent(e);
+                    update_text(e);
+                }
+                // not in current path
+                else
+                    e.classList.add("hide");
+            }
+            // Children maybe
+            else {
+                // no common path
+                if (ex < xmin || ex + fudge >= xmax) {
+                    e.classList.add("hide");
+                }
+                else {
+                    zoom_child(e, xmin, ratio);
+                    update_text(e);
+                }
+            }
+        }
+        search();
+    }
+    function unzoom() {
+        unzoombtn.classList.add("hide");
+        var el = document.getElementById("frames").children;
+        for(var i = 0; i < el.length; i++) {
+            el[i].classList.remove("parent");
+            el[i].classList.remove("hide");
+            zoom_reset(el[i]);
+            update_text(el[i]);
+        }
+        search();
+    }
+
+    // search
+    function toggle_ignorecase() {
+        ignorecase = !ignorecase;
+        if (ignorecase) {
+            ignorecaseBtn.classList.add("show");
+        } else {
+            ignorecaseBtn.classList.remove("show");
+        }
+        reset_search();
+        search();
+    }
+    function reset_search() {
+        var el = document.querySelectorAll("#frames rect");
+        for (var i = 0; i < el.length; i++) {
+            orig_load(el[i], "fill")
+        }
+    }
+    function search_prompt() {
+        if (!searching) {
+            var term = prompt("Enter a search term (regexp " +
+                "allowed, eg: ^ext4_)"
+                + (ignorecase ? ", ignoring case" : "")
+                + "\nPress Ctrl-i to toggle case sensitivity", "");
+            if (term != null) {
+                currentSearchTerm = term;
+                search();
+            }
+        } else {
+            reset_search();
+            searching = 0;
+            currentSearchTerm = null;
+            searchbtn.classList.remove("show");
+            searchbtn.firstChild.nodeValue = "Search"
+            matchedtxt.classList.add("hide");
+            matchedtxt.firstChild.nodeValue = ""
+        }
+    }
+    function search(term) {
+        if (currentSearchTerm === null) return;
+        var term = currentSearchTerm;
+
+        var re = new RegExp(term, ignorecase ? 'i' : '');
+        var el = document.getElementById("frames").children;
+        var matches = new Object();
+        var maxwidth = 0;
+        for (var i = 0; i < el.length; i++) {
+            var e = el[i];
+            var func = g_to_func(e);
+            var rect = find_child(e, "rect");
+            if (func == null || rect == null)
+                continue;
+
+            // Save max width. Only works as we have a root frame
+            var w = parseFloat(rect.attributes.width.value);
+            if (w > maxwidth)
+                maxwidth = w;
+
+            if (func.match(re)) {
+                // highlight
+                var x = parseFloat(rect.attributes.x.value);
+                orig_save(rect, "fill");
+                rect.attributes.fill.value = "rgb(230,0,230)";
+
+                // remember matches
+                if (matches[x] == undefined) {
+                    matches[x] = w;
+                } else {
+                    if (w > matches[x]) {
+                        // overwrite with parent
+                        matches[x] = w;
+                    }
+                }
+                searching = 1;
+            }
+        }
+        if (!searching)
+            return;
+
+        searchbtn.classList.add("show");
+        searchbtn.firstChild.nodeValue = "Reset Search";
+
+        // calculate percent matched, excluding vertical overlap
+        var count = 0;
+        var lastx = -1;
+        var lastw = 0;
+        var keys = Array();
+        for (k in matches) {
+            if (matches.hasOwnProperty(k))
+                keys.push(k);
+        }
+        // sort the matched frames by their x location
+        // ascending, then width descending
+        keys.sort(function(a, b){
+            return a - b;
+        });
+        // Step through frames saving only the biggest bottom-up frames
+        // thanks to the sort order. This relies on the tree property
+        // where children are always smaller than their parents.
+        var fudge = 0.0001; // JavaScript floating point
+        for (var k in keys) {
+            var x = parseFloat(keys[k]);
+            var w = matches[keys[k]];
+            if (x >= lastx + lastw - fudge) {
+                count += w;
+                lastx = x;
+                lastw = w;
+            }
+        }
+        // display matched percent
+        matchedtxt.classList.remove("hide");
+        var pct = 100 * count / maxwidth;
+        if (pct != 100) pct = pct.toFixed(1)
+        matchedtxt.firstChild.nodeValue = "Matched: " + pct + "%";
+    }
+]]>
+</script>
+<rect x="0.0" y="0" width="1200.0" height="$height.0" fill="url(#background)"  />
+<text id="title" x="600.00" y="24" >$title</text>
+<text id="unzoom" x="10.00" y="24" class="hide">Reset Zoom</text>
+<text id="search" x="1090.00" y="24" >Search</text>
+<text id="ignorecase" x="1174.00" y="24" >ic</text>
+<text id="matched" x="1090.00" y="$status" > </text>
+<text id="details" x="10.00" y="$status" > </text>
+<g id="frames">
+"""
+
+def namehash(s):
+    # FNV-1a
+    hval = 0x811c9dc5
+    for ch in s:
+        hval = hval ^ ord(ch)
+        hval = hval * 0x01000193
+        hval = hval % (2 ** 32)
+    return (hval % 31337) / 31337.0
+
+def display(root, title, colors, flip = False):
+    if colors == "cold":
+        gradient_start = "#eef2ee"
+        gradient_end = "#e0ffe0"
+    else:
+        gradient_start = "#eeeeee"
+        gradient_end = "#eeeeb0"
+
+    maxdepth = 0
+    for n in root.subtree():
+        maxdepth = max(maxdepth, n.depth)
+
+    svgheight = maxdepth * 16 + 3 * 16 + 2 * 16
+
+    print(template
+        .replace("$title", title)
+        .replace("$gradient-start", gradient_start)
+        .replace("$gradient-end", gradient_end)
+        .replace("$height", str(svgheight))
+        .replace("$status", str((svgheight - 16 + 3 if flip else 3 * 16 - 3)))
+        .replace("$flip", str(int(flip)))
+    )
+
+    framewidth = 1200 - 20
+
+    def pixels(x):
+        return float(x) / root.width * framewidth if root.width > 0 else 0
+
+    for n in root.subtree():
+        if pixels(n.width) < 0.1:
+            continue
+
+        x = 10 + pixels(n.offset)
+        y = (maxdepth - 1 - n.depth if flip else n.depth) * 16 + 3 * 16
+        width = pixels(n.width)
+        height = 15
+
+        if colors == "cold":
+            fillr = 0
+            fillg = int(190 + 50 * namehash(n.name))
+            fillb = int(210 * namehash(n.name[::-1]))
+        else:
+            fillr = int(205 + 50 * namehash(n.name))
+            fillg = int(230 * namehash(n.name[::-1]))
+            fillb = int(55 * namehash(n.name[::-2]))
+
+        fill = "rgb({},{},{})".format(fillr, fillg, fillb)
+        chars = width / (12 * 0.59)
+
+        text = n.text()
+
+        if chars >= 3:
+            if chars < len(text):
+                text = text[:int(chars-2)] + ".."
+        else:
+            text = ""
+
+        print("<g>")
+        print("<title>{}</title>".format(escape(n.title())))
+        print("<details>{}</details>".format(escape(n.details(root))))
+        print("<rect x='{}' y='{}' width='{}' height='{}' fill='{}' rx='2' ry='2' />".format(x, y, width, height, fill))
+        print("<text x='{}' y='{}'>{}</text>".format(x + 3, y + 10.5, escape(text)))
+        print("<rawtext>{}</rawtext>".format(escape(n.text())))
+        print("</g>")
+
+    print("</g>\n</svg>\n")

tools/testkit.luau

@@ -3,6 +3,10 @@
 -- v0.7.3
 -- MIT License
 -- Copyright (c) 2022 centau
+--
+-- Some changes that I have made to this module is to evaluate the tests lazily,
+-- this way only focused tests will actually be ran rather than just focusing their output.
+--
 --------------------------------------------------------------------------------
 
 local disable_ansi = false
@@ -112,6 +116,7 @@ type Test = {
 		trace: string,
 	}?,
 	focus: boolean,
+	fn: () -> ()
 }
 
 type Case = {
@@ -180,6 +185,24 @@ local function CASE(name: string)
 	table.insert(test.cases, case)
 end
 
+local function CHECK_EXPECT_ERR(fn, ...)
+	assert(test, "no active test")
+	local case = test.case
+	if not case then
+		CASE("")
+		case = test.case
+	end
+	assert(case, "no active case")
+	if case.result ~= FAIL then
+		local ok, err = pcall(fn, ...)
+		case.result = if ok then FAIL else PASS
+		if skip then
+			case.result = SKIPPED
+		end
+		case.line = debug.info(stack and stack + 1 or 2, "l")
+	end
+end
+
 local function CHECK<T>(value: T, stack: number?): T?
 	assert(test, "no active test")
 
@@ -203,59 +226,66 @@ local function CHECK<T>(value: T, stack: number?): T?
 	return value
 end
 
+local test_focused = false
+
 local function TEST(name: string, fn: () -> ())
-	local active = test
-	assert(not active, "cannot start test while another test is in progress")
 
 	test = {
 		name = name,
 		cases = {},
 		duration = 0,
 		focus = false,
+		fn = fn
 	}
-	assert(test)
 
-	table.insert(tests, test)
+	local t = test
 
-	local start = os.clock()
-	local err
-	local success = xpcall(fn, function(m: string)
-		err = { message = m, trace = debug.traceback(nil, 2) }
-	end)
-	test.duration = os.clock() - start
-
-	if not test.case then
-		CASE("")
+	if check_for_focused and not test_focused then
+		test.focus = true
+		test_focused = true
 	end
-	assert(test.case, "no active case")
-
-	if not success then
-		test.case.result = ERROR
-		test.error = err
-	end
-
-	test = nil
+	table.insert(tests, t)
 end
 
 local function FOCUS()
 	assert(test, "no active test")
 
 	check_for_focused = true
-	if test.case then
-		test.case.focus = true
-	else
-		test.focus = true
-	end
+	test_focused = false
 end
 
-local function FINISH(): boolean
-	local success = true
+local function FINISH(): number
 	local total_cases = 0
 	local passed_cases = 0
 	local passed_focus_cases = 0
 	local total_focus_cases = 0
 	local duration = 0
 
+	for _, t in tests do
+		if check_for_focused and not t.focus then
+			continue
+		end
+		test = t
+		local fn = t.fn
+		local start = os.clock()
+		local err
+		local ok = xpcall(fn, function(m: string)
+			err = { message = m, trace = debug.traceback(nil, 2) }
+		end)
+		t.duration = os.clock() - start
+
+		if not t.case then
+			CASE("")
+		end
+		assert(t.case, "no active case")
+
+		if not ok then
+			t.case.result = ERROR
+			t.error = err
+		end
+		collectgarbage()
+	end
+
 	for _, test in tests do
 		duration += test.duration
 		for _, case in test.cases do
@@ -286,7 +316,8 @@ local function FINISH(): boolean
 	print((fails > 0 and color.red or color.green)(`{fails} {fails == 1 and "fail" or "fails"}`))
 
 	check_for_focused = false
-	return success, table.clear(tests)
+	table.clear(tests)
+	return math.clamp(fails, 0, 1)
 end
 
 local function SKIP()
@@ -509,7 +540,15 @@ end
 
 return {
 	test = function()
-		return TEST, CASE, CHECK, FINISH, SKIP, FOCUS
+		return {
+			TEST = TEST,
+			CASE = CASE,
+			CHECK = CHECK,
+			FINISH = FINISH,
+			SKIP = SKIP,
+			FOCUS = FOCUS,
+			CHECK_EXPECT_ERR = CHECK_EXPECT_ERR,
+		}
 	end,
 
 	benchmark = function()

wally.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ukendio/jecs"
-version = "0.5.2"
+version = "0.5.5"
 registry = "https://github.com/UpliftGames/wally-index"
 realm = "shared"
 license = "MIT"