Merge 96bed9bd7e into 6ec8ed69e9

.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

.luaurc

@@ -4,7 +4,7 @@
         "testkit": "tools/testkit",
         "mirror": "mirror",
         "tools": "tools",
-        "addons": "addons",
+        "addons": "addons"
     },
     "languageMode": "strict"
 }

CHANGELOG.md

@@ -23,6 +23,8 @@ The format is based on [Keep a Changelog][kac], and this project adheres 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.
 
 ## [0.5.0] - 2024-12-26
 

addons/observers.luau

@@ -1,20 +1,32 @@
 local jecs = require("@jecs")
-local testkit = require("@testkit")
+
+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
+	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
-	local function emplaced(entity)
+	local entity_index = world.entity_index :: any
+	local function emplaced(entity: jecs.Entity)
 		local r = jecs.entity_index_try_get_fast(
-			entity_index, entity)
+			entity_index, entity :: any)
 
 		if not r then
 			return
@@ -33,18 +45,20 @@ local function observers_new(world, description)
  	end
 end
 
-local function world_track(world, ...)
-	local entity_index = world.entity_index
-	local terms = { ... }
-	local q_shim = { filter_with = terms }
+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 n = 0
-	local dense_array = {}
-	local sparse_array = {}
-
-	local function emplaced(entity)
+	local entity_index = world.entity_index :: any
+	local function emplaced(entity: jecs.Entity)
 		local r = jecs.entity_index_try_get_fast(
-			entity_index, entity)
+			entity_index, entity :: any)
 
 		if not r then
 			return
@@ -52,55 +66,39 @@ local function world_track(world, ...)
 
 		local archetype = r.archetype
 
-		if jecs.query_match(q_shim :: any, archetype) then
-			n += 1
-			dense_array[n] = entity
-			sparse_array[entity] = n
+		if jecs.query_match(query, archetype) then
+			callback(entity, jecs.OnAdd)
 		end
 	end
 
-	local function removed(entity)
-		local i = sparse_array[entity]
-		if i ~= n then
-			dense_array[i] = dense_array[n]
+	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
 
-		dense_array[n] = nil
+		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:changed(term, emplaced)
+		world:removed(term, removed)
  	end
-
-	local function iter()
-		local i = n
-		return function()
-			local row = i
-			if row == 0 then
-				return nil
-			end
-			i -= 1
-			return dense_array[row] :: any
-		end
-	end
-
-	local it = {
-		__iter = iter,
-		without = function(self, ...)
-			q_shim.filter_without = { ... }
-			return self
-		end
-	}
-	return setmetatable(it, it)
 end
 
-local function observers_add(world)
+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]
 		if not listeners then
@@ -109,7 +107,7 @@ local function observers_add(world)
 			local idr = jecs.id_record_ensure(world, component)
 			idr.hooks.on_add = function(entity)
 				for _, listener in listeners do
-					listener(entity)
+					listener(entity, component)
 				end
 			end
 		end
@@ -124,7 +122,7 @@ local function observers_add(world)
 			local idr = jecs.id_record_ensure(world, component)
 			idr.hooks.on_change = function(entity, value)
 				for _, listener in listeners do
-					listener(entity, value)
+					listener(entity, component, value)
 				end
 			end
 		end
@@ -139,7 +137,7 @@ local function observers_add(world)
 			local idr = jecs.id_record_ensure(world, component)
 			idr.hooks.on_remove = function(entity)
 				for _, listener in listeners do
-					listener(entity)
+					listener(entity, component)
 				end
 			end
 		end
@@ -148,9 +146,10 @@ local function observers_add(world)
 
 	world.signals = signals
 
-	world.track = world_track
-
 	world.observer = observers_new
+
+	world.monitor = monitors_new
+
 	return world
 end
 

jecs.luau

@@ -466,7 +466,9 @@ local function world_has_one_inline(world: ecs_world_t, entity: i53, id: i53): b
 	return records[id] ~= nil
 end
 
-local function world_has(world: ecs_world_t, entity: i53, ...: i53): boolean
+local function world_has(world: ecs_world_t, entity: i53,
+	a: i53, b: i53?, c: i53?, d: i53?, e: i53?): boolean
+
 	local record = entity_index_try_get_fast(world.entity_index, entity)
 	if not record then
 		return false
@@ -479,13 +481,11 @@ local function world_has(world: ecs_world_t, entity: i53, ...: i53): boolean
 
 	local records = archetype.records
 
-	for i = 1, select("#", ...) do
-		if not records[select(i, ...)] then
-			return false
-		end
-	end
-
-	return true
+	return records[a] ~= nil and
+		(b == nil or records[b] ~= nil) and
+		(c == nil or records[c] ~= nil) and
+		(d == nil or records[d] ~= nil) and
+		(e == nil or error("args exceeded"))
 end
 
 local function world_target(world: ecs_world_t, entity: i53, relation: i24, index: number?): i24?
@@ -1260,7 +1260,7 @@ local function world_delete(world: ecs_world_t, entity: i53)
 				local tr = idr_r_archetype.records[rel]
 				local tr_count = idr_r_archetype.counts[rel]
 				local types = idr_r_archetype.types
-				for i = tr, tr_count - 1 do
+				for i = tr, tr_count do
 					ids[types[tr]] = true
 				end
 				local n = #entities
@@ -2420,7 +2420,10 @@ export type World = {
 		& <A, B, C, D>(self: World, id: Entity, Id<A>, Id<B>, Id<C>, Id<D>) -> (A?, B?, C?, D?),
 
 	--- Returns whether the entity has the ID.
-	has: (self: World, entity: Entity, ...Id) -> boolean,
+	has: (<A>(World, Entity, A) -> boolean)
+		& (<A, B>(World, Entity, A, B) -> boolean)
+		& (<A, B, C>(World, Entity, A, B, C) -> boolean)
+		& <A, B, C, D>(World, Entity, A, B, C, D) -> boolean,
 
 	--- Get parent (target of ChildOf relationship) for entity. If there is no ChildOf relationship pair, it will return nil.
 	parent:(self: World, entity: Entity) -> Entity,
@@ -2487,9 +2490,9 @@ return {
 
 	ECS_ID_DELETE = ECS_ID_DELETE,
 
-	IS_PAIR = ECS_IS_PAIR,
-	pair_first = ecs_pair_first,
-	pair_second = ecs_pair_second,
+	IS_PAIR = (ECS_IS_PAIR :: any) :: <P, O>(pair: Pair<P, O>) -> boolean,
+	pair_first = (ecs_pair_first :: any) :: <P, O>(world: World, pair: Pair<P, O>) -> Id<P>,
+	pair_second = (ecs_pair_second :: any) :: <P, O>(world: World, pair: Pair<P, O>) -> Id<O>,
 	entity_index_get_alive = entity_index_get_alive,
 
 	archetype_append_to_records = archetype_append_to_records,

test/addons/observers.luau

@@ -1,46 +1,87 @@
 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")
 
-local world = jecs.world()
-observers_add(world)
 
-local A = world:component()
-local B = world:component()
-local C = world:component()
+TEST("addons/observers", function()
+	local world = observers_add(jecs.world())
 
-world:observer({
-	query = world:query(),
-	callback = function(entity)
-		buf ..= debug.info(2, "sl")
+	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
-})
-
-local i = 0
-world:added(A, function(entity)
-	assert(i == 0)
-	i += 1
-end)
-world:added(A, function(entity)
-	assert(i == 1)
-	i += 1
-end)
-
-world:removed(A, function(entity)
-	assert(false)
-end)
-
-local observer = world:observer({
+		world:observer({
+			callback = counter,
 			query = world:query(A, B),
-	callback = function(entity)
-		assert(i == 2)
-		i += 1
+		})
+
+		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 e = world:entity()
-world:add(e, A)
-assert(i == 2)
+		local count = 0
+		local function counter()
+			count += 1
+		end
+		world:observer({
+			query = world:query(A),
+			callback = counter
+		})
 
-world:add(e, B)
-assert(i == 3)
+		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
+end)
+
+return FINISH()

tools/entity_visualiser.luau

@@ -70,7 +70,51 @@ local function components(world: jecs.World, entity: any)
 	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

@@ -32,7 +32,12 @@ local function pad()
 	end
 end
 
-local function lifetime_tracker_add(world: jecs.World, opt)
+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

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
@@ -248,7 +252,7 @@ local function FOCUS()
 	end
 end
 
-local function FINISH(): boolean
+local function FINISH(): number
 	local success = true
 	local total_cases = 0
 	local passed_cases = 0
@@ -311,7 +315,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()