Return nil if nth is over count

* Add rbxts typings for signals

* Correct arguments

addons/ob.luau

@@ -0,0 +1,217 @@
+--!strict
+local jecs = require("@jecs")
+
+type World = jecs.World
+type Query<T...> = jecs.Query<T...>
+
+type Id<T=any> = jecs.Id<T>
+
+type Entity<T> = jecs.Entity<T>
+
+export type Iter<T...> = (Observer<T...>) -> () -> (jecs.Entity, T...)
+
+export type Observer<T...> = typeof(setmetatable(
+	{} :: {
+		iter: Iter<T...>,
+		entities: { Entity<nil> },
+		disconnect: (Observer<T...>) -> ()
+	},
+	{} :: {
+		__iter: Iter<T...>,
+	}
+))
+
+local function observers_new<T...>(
+	query: Query<T...>,
+	callback: ((Entity<nil>, Id<any>, value: any?) -> ())?
+): Observer<T...>
+
+	query:cached()
+
+	local world = (query :: Query<T...> & { world: World }).world
+	callback = callback
+
+	local archetypes = {}
+	local terms = query.ids
+	local first = terms[1]
+
+	local observers_on_create = world.observable[jecs.ArchetypeCreate][first]
+	local observer_on_create = observers_on_create[#observers_on_create]
+	observer_on_create.callback = function(archetype)
+		archetypes[archetype.id] = true
+	end
+	local observers_on_delete = world.observable[jecs.ArchetypeDelete][first]
+	local observer_on_delete = observers_on_delete[#observers_on_delete]
+	observer_on_delete.callback = function(archetype)
+		archetypes[archetype.id] = nil
+	end
+
+	local entity_index = world.entity_index :: any
+	local i = 0
+	local entities = {}
+
+	local function emplaced<T, a>(
+		entity: jecs.Entity<T>,
+		id: jecs.Id<a>,
+		value: a?
+	)
+		local r = entity_index.sparse_array[jecs.ECS_ID(entity)]
+
+		local archetype = r.archetype
+
+		if archetypes[archetype.id] then
+			i += 1
+			entities[i] = entity
+			if callback ~= nil then
+				callback(entity, id, value)
+			end
+		end
+	end
+
+	for _, term in terms do
+		if jecs.IS_PAIR(term) then
+			term = jecs.ECS_PAIR_FIRST(term)
+		end
+		world:added(term, emplaced)
+		world:changed(term, emplaced)
+ 	end
+
+  	local function disconnect()
+   		table.remove(observers_on_create, table.find(
+     		observers_on_create,
+       		observer_on_create
+     	))
+
+     	table.remove(observers_on_delete, table.find(
+      		observers_on_delete,
+        	observer_on_delete
+       	))
+   	end
+
+    local function iter()
+  		local row = i
+  		return function()
+ 			if row == 0 then
+     			i = 0
+      			table.clear(entities)
+      		end
+           	local entity = entities[row]
+           	row -= 1
+           	return entity
+        end
+    end
+
+  	local observer = {
+   		disconnect = disconnect,
+     	entities = entities,
+     	__iter = iter,
+      	iter = iter
+   	}
+
+    setmetatable(observer, observer)
+
+    return (observer :: any) :: Observer<T...>
+end
+
+local function monitors_new<T...>(
+	query: Query<T...>,
+	callback: ((Entity<nil>, Id<any>, value: any?) -> ())?
+): Observer<T...>
+
+	query:cached()
+
+	local world = (query :: Query<T...> & { world: World }).world
+
+	local archetypes = {}
+	local terms = query.ids
+	local first = terms[1]
+
+	local observers_on_create = world.observable[jecs.ArchetypeCreate][first]
+	local observer_on_create = observers_on_create[#observers_on_create]
+	observer_on_create.callback = function(archetype)
+		archetypes[archetype.id] = true
+	end
+	local observers_on_delete = world.observable[jecs.ArchetypeDelete][first]
+	local observer_on_delete = observers_on_delete[#observers_on_delete]
+	observer_on_delete.callback = function(archetype)
+		archetypes[archetype.id] = nil
+	end
+	local entity_index = world.entity_index :: any
+	local i = 0
+	local entities = {}
+
+	local function emplaced<T, a>(
+		entity: jecs.Entity<T>,
+		id: jecs.Id<a>,
+		value: a?
+	)
+		local r = jecs.entity_index_try_get_fast(
+			entity_index, entity :: any) :: jecs.Record
+
+		local archetype = r.archetype
+
+		if archetypes[archetype.id] then
+			i += 1
+			entities[i] = entity
+			if callback ~= nil then
+				callback(entity, jecs.OnAdd)
+			end
+		end
+	end
+
+	local function removed(entity: jecs.Entity, component: jecs.Id)
+		local EcsOnRemove = jecs.OnRemove :: jecs.Id
+		if callback ~= nil then
+			callback(entity, EcsOnRemove)
+		end
+	end
+
+	for _, term in terms do
+		if jecs.IS_PAIR(term) then
+			term = jecs.ECS_PAIR_FIRST(term)
+		end
+		world:added(term, emplaced)
+		world:removed(term, removed)
+ 	end
+
+ 	local function disconnect()
+  		table.remove(observers_on_create, table.find(
+	  		observers_on_create,
+	    	observer_on_create
+	   	))
+
+	   	table.remove(observers_on_delete, table.find(
+	      	observers_on_delete,
+	       	observer_on_delete
+       	))
+   	end
+
+    local function iter()
+  		local row = i
+  		return function()
+ 			if row == 0 then
+     			i = 0
+     			table.clear(entities)
+      		end
+           	local entity = entities[row]
+           	row -= 1
+           	return entity
+        end
+    end
+
+	local observer = {
+  		disconnect = disconnect,
+	   	entities = entities,
+	   	__iter = iter,
+       	iter = iter
+   	}
+
+    setmetatable(observer, observer)
+
+    return (observer :: any) :: Observer<T...>
+end
+
+return {
+	monitor = monitors_new,
+	observer = observers_new
+}

addons/observers.luau

@@ -1,334 +0,0 @@
---!strict
-local jecs = require("@jecs")
-
-
-type Description<T...> = jecs.Query<T...>
-
-type ObserverArm = (<a>(
-	PatchedWorld,
-	{
-		query: jecs.Query<a>,
-		callback: ((jecs.Entity) -> ())?
-	}
-) -> () -> () -> (jecs.Entity)) & (<a, b>(
-	PatchedWorld,
-	{
-		query: jecs.Query<a, b>,
-		callback: ((jecs.Entity) -> ())?
-	}
-) -> () -> () -> (jecs.Entity)) & (<a, b, c>(
-	PatchedWorld,
-	{
-		query: jecs.Query<a, b, c>,
-		callback: ((jecs.Entity) -> ())?
-	}
-) -> () -> () -> (jecs.Entity))
-
-export type PatchedWorld = jecs.World & {
-	added: <T>(PatchedWorld, jecs.Id<T>, <e>(e: jecs.Entity<e>, id: jecs.Id<T>, value: T?) -> ()) -> () -> (),
-	removed: <T>(PatchedWorld, jecs.Id<T>, (e: jecs.Entity, id: jecs.Id) -> ()) -> () -> (),
-	changed:  <T>(PatchedWorld, jecs.Id<T>, <e>(e: jecs.Entity<e>, id: jecs.Id<T>, value: T) -> ()) -> () -> (),
-	observer: ObserverArm & any,
-	monitor: ObserverArm & any
-}
-
-local function observers_new(
-	world: PatchedWorld,
-	query: any,
-	callback: (<T, a>(jecs.Entity<T>, jecs.Id<a>, value: a?) -> ())?
-)
-	query = query:cached()
-
-	local archetypes = {}
-	local terms = query.ids
-	local first = terms[1]
-
-	local observers_on_create = world.observable[jecs.ArchetypeCreate][first]
-	observers_on_create[#observers_on_create].callback = function(archetype)
-		archetypes[archetype.id] = true
-	end
-	local observers_on_delete = world.observable[jecs.ArchetypeDelete][first]
-	observers_on_delete[#observers_on_delete].callback = function(archetype)
-		archetypes[archetype.id] = nil
-	end
-
-	local entity_index = world.entity_index :: any
-	local i = 0
-	local entities = {}
-
-	local function emplaced<T, a>(
-		entity: jecs.Entity<T>,
-		id: jecs.Id<a>,
-		value: a?
-	)
-		local r = entity_index.sparse_array[jecs.ECS_ID(entity)]
-
-		local archetype = r.archetype
-
-		if archetypes[archetype.id] then
-			i += 1
-			entities[i] = entity
-			if callback ~= nil then
-				callback(entity, id, value)
-			end
-		end
-	end
-
-	for _, term in terms do
-		world:added(term, emplaced)
-		world:changed(term, emplaced)
- 	end
-
-  	return function()
-  		local row = i
-  		return function()
- 			if row == 0 then
-     			i = 0
-	      		table.clear(entities)
-      		end
-           	local entity = entities[row]
-           	row -= 1
-           	return entity
-		end
-    end
-end
-
-local function join(world, component)
-	local sparse_array = {}
-	local dense_array = {}
-	local values = {}
-	local max_id = 0
-
-	world:added(component, function(entity, id, value)
-		max_id += 1
-		sparse_array[entity] = max_id
-		dense_array[max_id] = entity
-		values[max_id] = value
-	end)
-
-	world:removed(component, function(entity, id)
-		local e_swap = dense_array[max_id]
-		local v_swap = values[max_id]
-
-		local dense = sparse_array[entity]
-		dense_array[dense] = e_swap
-		values[dense] = v_swap
-
-		sparse_array[entity] = nil
-		dense_array[max_id] = nil
-		values[max_id] = nil
-		max_id -= 1
-	end)
-
-	world:changed(component, function(entity, id, value)
-		values[sparse_array[entity]] = value
-	end)
-
-	return function()
-		local i = max_id
-		return function(): ...any
-			i -= 1
-			if i == 0 then
-				return nil
-			end
-			local e = dense_array[i]
-			return e, values[i]
-		end
-	end
-end
-
-local function monitors_new(world, query, callback)
-	query = query:cached()
-
-	local archetypes = {}
-	local terms = query.ids
-	local first = terms[1]
-
-	local observers_on_create = world.observable[jecs.ArchetypeCreate][first]
-	observers_on_create[#observers_on_create].callback = function(archetype)
-		archetypes[archetype.id] = true
-	end
-	local observers_on_delete = world.observable[jecs.ArchetypeDelete][first]
-	observers_on_delete[#observers_on_delete].callback = function(archetype)
-		archetypes[archetype.id] = nil
-	end
-
-	local entity_index = world.entity_index :: any
-	local i = 0
-	local entities = {}
-
-	local function emplaced<T, a>(
-		entity: jecs.Entity<T>,
-		id: jecs.Id<a>,
-		value: a?
-	)
-		local r = jecs.entity_index_try_get_fast(
-			entity_index, entity :: any) :: jecs.Record
-
-		local archetype = r.archetype
-
-		if archetypes[archetype.id] then
-			i += 1
-			entities[i] = entity
-			if callback ~= nil then
-				callback(entity, id, value)
-			end
-		end
-	end
-
-	local function removed(entity: jecs.Entity, component: jecs.Id)
-		local EcsOnRemove = jecs.OnRemove :: jecs.Id
-		if callback ~= nil then
-			callback(entity, EcsOnRemove)
-		end
-	end
-
-	for _, term in terms do
-		world:added(term, emplaced)
-		world:removed(term, removed)
- 	end
-
-	return function()
-		local row = i
-		return function()
-			if row == 0 then
-				i = 0
-				table.clear(entities)
-			end
-			local entity = entities[row]
-			row -= 1
-			return entity
-		end
-	end
-end
-
-local function observers_add(world: jecs.World): PatchedWorld
-	type Signal = { [jecs.Entity]: { (...any) -> () } }
-
-	local world_mut = world :: jecs.World & {[string]: any}
-
-	local signals = {
-		added = {} :: Signal,
-		emplaced = {} :: Signal,
-		removed = {} :: Signal
-	}
-
-	world_mut.added = function<T>(
-		_: jecs.World,
-		component: jecs.Id<T>,
-		fn: (e: jecs.Entity, id: jecs.Id, value: T) -> ()
-	)
-		local listeners = signals.added[component]
-		if not listeners then
-			listeners = {}
-			signals.added[component] = listeners
-
-			local function on_add(entity, id, value)
-				for _, listener in listeners :: any do
-					listener(entity, id, value)
-				end
-			end
-			local existing_hook = world:get(component, jecs.OnAdd)
-			if existing_hook then
-				table.insert(listeners, existing_hook)
-			end
-
-			local idr = world.component_index[component]
-			if idr then
-				idr.on_add = on_add
-			else
-				world:set(component, jecs.OnAdd, on_add)
-			end
-		end
-		table.insert(listeners, fn)
-		return function()
-			local n = #listeners
-			local i = table.find(listeners, fn)
-			listeners[i] = listeners[n]
-			listeners[n] = nil
-		end
-	end
-
-	world_mut.changed = function<T>(
-		_: jecs.World,
-		component: jecs.Id<T>,
-		fn: (e: jecs.Entity, id: jecs.Id, value: T) -> ()
-	)
-		local listeners = signals.emplaced[component]
-		if not listeners then
-			listeners = {}
-			signals.emplaced[component] = listeners
-			local function on_change(entity, id, value: any)
-				for _, listener in listeners :: any do
-					listener(entity, id, value)
-				end
-			end
-			local existing_hook = world:get(component, jecs.OnChange)
-			if existing_hook then
-				table.insert(listeners, existing_hook)
-			end
-			local idr = world.component_index[component]
-			if idr then
-				idr.on_change = on_change
-			else
-				world:set(component, jecs.OnChange, on_change)
-			end
-		end
-		table.insert(listeners, fn)
-		return function()
-			local n = #listeners
-			local i = table.find(listeners, fn)
-			listeners[i] = listeners[n]
-			listeners[n] = nil
-		end
-	end
-
-	world_mut.removed = function<T>(
-		_: jecs.World,
-		component: jecs.Id<T>,
-		fn: (e: jecs.Entity, id: jecs.Id) -> ()
-	)
-		local listeners = signals.removed[component]
-		if not listeners then
-			listeners = {}
-			signals.removed[component] = listeners
-			local function on_remove(entity, id)
-				for _, listener in listeners :: any do
-					listener(entity, id)
-				end
-			end
-			local existing_hook = world:get(component, jecs.OnRemove)
-			if existing_hook then
-				table.insert(listeners, existing_hook)
-			end
-
-			local idr = world.component_index[component]
-			if idr then
-				idr.on_remove = on_remove
-			else
-				world:set(component, jecs.OnRemove, on_remove)
-			end
-		end
-
-		table.insert(listeners, fn)
-
-		return function()
-			local n = #listeners
-			local i = table.find(listeners, fn)
-			listeners[i] = listeners[n]
-			listeners[n] = nil
-		end
-	end
-
-	world_mut.signals = signals
-
-	world_mut.observer = observers_new
-
-	world_mut.monitor = monitors_new
-
-	world_mut.trackers = {}
-
-	return world_mut :: PatchedWorld
-end
-
-return observers_add

demo/src/ReplicatedStorage/collect.luau

@@ -1,13 +1,11 @@
-local function collect<T...>(
+
-	signal: {
+--!strict
-		Connect: (RBXScriptSignal<T...>, fn: (T...) -> ()) -> RBXScriptConnection
+local function collect(signal)
-	}
-): () -> (T...)
 	local enqueued = {}
 
 	local i = 0
 
-	local connection = (signal :: any):Connect(function(...)
+	local connection = signal:Connect(function(...)
 		table.insert(enqueued, { ... })
 		i += 1
 	end)
@@ -25,4 +23,11 @@ local function collect<T...>(
 	end, connection
 end
 
-return collect
+type Signal<T... = ...any> = {
+    Connect: (self: Signal<T...>, callback: (T...) -> ()) -> RBXScriptConnection,
+    ConnectParallel: (self: Signal<T...>, callback: (T...) -> ()) -> RBXScriptConnection,
+    Once: (self: Signal<T...>, callback: (T...) -> ()) -> RBXScriptConnection,
+    Wait: (self: Signal<T...>) -> (T...)
+}
+
+return collect :: <T...>(Signal<T...>) -> (() -> (T...), RBXScriptConnection)

demo/src/ReplicatedStorage/main.client.luau

@@ -1,12 +1,11 @@
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
 local jecs = require(ReplicatedStorage.ecs)
 local schedule = require(ReplicatedStorage.schedule)
-local observers_add = require(ReplicatedStorage.observers_add)
 
 local SYSTEM = schedule.SYSTEM
 local RUN = schedule.RUN
 require(ReplicatedStorage.components)
-local world = observers_add(jecs.world())
+local world = jecs.world()
 
 local systems = ReplicatedStorage.systems
 SYSTEM(world, systems.receive_replication)

demo/src/ReplicatedStorage/observers_add.luau

@@ -1,190 +0,0 @@
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local jecs = require(ReplicatedStorage.ecs)
-
-type Observer<T...> = {
-	callback: (jecs.Entity) -> (),
-	query: jecs.Query<T...>,
-}
-
-export type PatchedWorld = jecs.World & {
-	added: <T>(PatchedWorld, jecs.Id<T>, (e: jecs.Entity, id: jecs.Id<T>, value: T) -> ()) -> (),
-	removed: (PatchedWorld, jecs.Id, (e: jecs.Entity, id: jecs.Id) -> ()) -> (),
-	changed: <T>(PatchedWorld, jecs.Id<T>, (e: jecs.Entity, id: jecs.Id<T>, value: T) -> ()) -> (),
-	-- deleted: (PatchedWorld, () -> ()) -> () -> (),
-	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): PatchedWorld
-	local signals = {
-		added = {},
-		emplaced = {},
-		removed = {},
-		deleted = {}
-	}
-
-	world = world :: jecs.World & {[string]: any}
-
-	world.added = function(_, component, fn)
-		local listeners = signals.added[component]
-		if not listeners then
-			listeners = {}
-			signals.added[component] = listeners
-
-			local idr = jecs.id_record_ensure(world :: any, component :: any)
-			local rw = jecs.pair(component, jecs.Wildcard)
-			local idr_r = jecs.id_record_ensure(world :: any, rw :: any)
-			local function on_add(entity: number, id: number, value: any)
-				for _, listener in listeners do
-					listener(entity, id, value)
-				end
-			end
-			world:set(component, jecs.OnAdd, on_add)
-			idr.hooks.on_add = on_add :: any
-			idr_r.hooks.on_add = on_add :: any
-		end
-		table.insert(listeners, fn)
-	end
-
-	world.changed = function(_, component, fn)
-		local listeners = signals.emplaced[component]
-		if not listeners then
-			listeners = {}
-			signals.emplaced[component] = listeners
-			local idr = jecs.id_record_ensure(world :: any, component :: any)
-			local rw = jecs.pair(component, jecs.Wildcard)
-			local idr_r = jecs.id_record_ensure(world :: any, rw :: any)
-			local function on_change(entity: number, id: number, value: any)
-				for _, listener in listeners do
-					listener(entity, id, value)
-				end
-			end
-			world:set(component, jecs.OnChange, on_change)
-			idr.hooks.on_change = on_change :: any
-			idr_r.hooks.on_change = on_change :: any
-		end
-		table.insert(listeners, fn)
-	end
-
-	world.removed = function(_, component, fn)
-		local listeners = signals.removed[component]
-		if not listeners then
-			listeners = {}
-			signals.removed[component] = listeners
-			local idr = jecs.id_record_ensure(world :: any, component :: any)
-			local rw = jecs.pair(component, jecs.Wildcard)
-			local idr_r = jecs.id_record_ensure(world :: any, rw :: any)
-			local function on_remove(entity: number, id: number, value: any)
-				for _, listener in listeners do
-					listener(entity, id, value)
-				end
-			end
-			world:set(component, jecs.OnRemove, on_remove)
-			idr.hooks.on_remove = on_remove :: any
-			idr_r.hooks.on_remove = on_remove :: any
-		end
-		table.insert(listeners, fn)
-	end
-
-	world.signals = signals
-
-	world.observer = observers_new
-
-	world.monitor = monitors_new
-
-	-- local world_delete = world.delete
-
-	-- world.deleted = function(_, fn)
-	-- 	local listeners = signals.deleted
-	-- 	table.insert(listeners, fn)
-	-- end
-	-- world.delete = function(world, entity)
-	-- 	world_delete(world, entity)
-	-- 	for _, fn in signals.deleted do
-	-- 		fn(entity)
-	-- 	end
-	-- end
-
-	return world :: PatchedWorld
-end
-
-return observers_add

demo/src/ReplicatedStorage/remotes.luau

@@ -1,40 +1,32 @@
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
 local types = require("../ReplicatedStorage/types")
 
-type Signal<T...> = {
-	Connect: (Signal<T...>, fn: (T...) -> ()) -> RBXScriptConnection
-}
 type Remote<T...> = {
-	FireClient: (Remote<T...>, T...) -> (),
+	FireClient: (Remote<T...>, Player, T...) -> (),
 	FireAllClients: (Remote<T...>, T...) -> (),
-	FireServer: (Remote<T...>) -> (),
+	FireServer: (Remote<T...>, T...) -> (),
-	OnServerEvent: {
+	OnServerEvent: RBXScriptSignal<(Player, T...)>,
-		Connect: (any, fn: (Player, T...) -> () ) -> ()
+	OnClientEvent: RBXScriptSignal<T...>
-	},
-	OnClientEvent: {
-		Connect: (any, fn: (T...) -> () ) -> ()
-	}
-
 }
 
-local function stream_ensure(name): Remote<any>
+local function stream_ensure(name)
 	local remote = ReplicatedStorage:FindFirstChild(name)
 	if not remote then
 		remote = Instance.new("RemoteEvent")
 		remote.Name = name
 		remote.Parent = ReplicatedStorage
 	end
-	return remote :: any
+	return remote
 end
 
-local function datagram_ensure(name): Remote<any>
+local function datagram_ensure(name)
 	local remote = ReplicatedStorage:FindFirstChild(name)
 	if not remote then
 		remote = Instance.new("UnreliableRemoteEvent")
 		remote.Name = name
 		remote.Parent = ReplicatedStorage
 	end
-	return remote :: any
+	return remote
 end
 
 return {

demo/src/ReplicatedStorage/systems/receive_replication.luau

@@ -88,9 +88,6 @@ return function(world: types.World)
             if removed then
                 for _, entity in removed do
                     entity = ecs_ensure_entity(world, entity)
-                    if not world:contains(entity) then
-                        continue
-                    end
                     world:remove(entity, id)
                 end
             end

demo/src/ReplicatedStorage/types.luau

@@ -1,7 +1,6 @@
 local jecs = require(game:GetService("ReplicatedStorage").ecs)
-local observers_add = require("../ReplicatedStorage/observers_add")
 
-export type World = typeof(observers_add(jecs.world()))
+export type World = typeof(jecs.world())
 export type Entity = jecs.Entity
 export type Id<T> = jecs.Id<T>
 export type Snapshot = {

demo/src/ServerScriptService/main.server.luau

@@ -2,13 +2,12 @@ local ReplicatedStorage = game:GetService("ReplicatedStorage")
 local ServerScriptService = game:GetService("ServerScriptService")
 local jecs = require(ReplicatedStorage.ecs)
 local schedule = require(ReplicatedStorage.schedule)
-local observers_add = require(ReplicatedStorage.observers_add)
 
 local SYSTEM = schedule.SYSTEM
 local RUN = schedule.RUN
 
 require(ReplicatedStorage.components)
-local world = observers_add(jecs.world())
+local world = jecs.world()
 
 local systems = ServerScriptService.systems
 

demo/src/ServerScriptService/systems/replication.luau

@@ -1,4 +1,3 @@
-
 --!strict
 local Players = game:GetService("Players")
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
@@ -177,7 +176,7 @@ return function(world: ty.World)
 		            set_n += 1
 		            set_ids[set_n] = e
 		            set_values[set_n] = v or true
-		        elseif not world:contains(e) then
+		        elseif world:contains(e) then
 		            removed_n += 1
 		            removed_ids[removed_n] = e
 		        end

docs/api/jecs.md

@@ -2,7 +2,7 @@
 
 Jecs. Just an Entity Component System.
 
-# Properties
+# Members
 
 ## World
 ```luau
@@ -12,27 +12,93 @@ A world is a container of all ECS data. Games can have multiple worlds but compo
 
 ## Wildcard
 ```luau
-jecs.Wildcard: Entity
+jecs.Wildcard: Id
 ```
 Builtin component type. This ID is used for wildcard queries.
 
 ## Component
 ```luau
-jecs.Component: Entity
+jecs.Component: Id
 ```
 Builtin component type. Every ID created with [world:component()](world.md#component()) has this type added to it. This is meant for querying every component ID.
 
 ## ChildOf
 ```luau
-jecs.ChildOf: Entity
+jecs.ChildOf: Id
 ```
 Builtin component type. This ID is for creating parent-child hierarchies.
 
+## OnAdd
+
+```luau
+jecs.OnAdd: Id
+```
+Builtin component type. This ID is for setting up a callback that is invoked when an instance of a component is added.
+
+## OnRemove
+
+```luau
+jecs.OnRemove: Id
+```
+
+Builtin component type. This ID is for setting up a callback that is invoked when an instance of a component is removed.
+
+## OnChange
+
+```luau
+jecs.OnChange: Id
+```
+
+Builtin component type. This ID is for setting up a callback that is invoked when an instance of a component is changed.
+
+## Exclusive
+
+```lua
+jecs.Exclusive: Id
+```
+
+Builtin component type. This ID is for encoding that an ID is Exclusive meaning that an entity can never have more than one target for that exclusive relation.
+
+:::code-group
+```luau [luau]
+local ChildOf = world:entity()
+world:add(ChildOf, jecs.Exclusive)
+
+local pop = world:entity()
+local dad = world:entity()
+local kid = world:entity()
+
+world:add(kid, pair(ChildOf, dad))
+print(world:target(kid, ChildOf, 0) == dad)
+world:add(kid, pair(ChildOf, pop))
+print(world:target(kid, ChildOf, 1) == dad) -- If ChildOf was not exclusive this would have been true
+print(world:target(kid, ChildOf, 0) == pop)
+
+-- Output:
+--  true
+--  false
+--  true
+```
+
+:::info
+By default, jecs.ChildOf is already an exclusive relationship and this is just a demonstration of how to use it.
+In some cases you can use Exclusive relationships as a performance optimization as you can guarantee there will only be one target, therefore
+retrieving the data from a wildcard pair with that exclusive relationship can be deterministic.
+:::
+
+## Name
+```luau
+jecs.Name: Id
+```
+Builtin component type. This ID is for naming components, but realistically you could use any component to do that.
+
 ## Rest
 ```luau
-jecs.Rest: Entity
+jecs.Rest: Id
 ```
 
+Builtin component type. This ID is simply for denoting the end of the range for builtin component IDs.
+
 # Functions
 
 ## pair()
@@ -48,3 +114,30 @@ function jecs.pair(
 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.
 
 :::
+
+## pair_first()
+```luau
+function jecs.pair_first(
+   	pair: Id, -- A full pair ID encoded using a relation-target pair.
+): Entity -- The ID of the first element. Returns 0 if the ID is not alive.
+```
+Returns the first element (the relation part) of a pair ID.
+
+**Example:**
+```luau
+local Likes = world:component()
+local alice = world:entity()
+local bob = world:entity()
+
+local pair_id = pair(Likes, alice)
+local relation = jecs.pair_first(pair_id)
+print(relation == Likes) -- true
+```
+
+## pair_second()
+```luau
+function jecs.pair_second(
+   	pair: Id, -- A full pair ID encoded using a relation-target pair.
+): Entity -- The ID of the second element. Returns 0 if the ID is not alive.
+```
+Returns the second element (the target part) of a pair ID.

docs/api/observers.md

@@ -0,0 +1,196 @@
+# Observers
+
+The observers addon extends the World with signal-based reactivity and query-based observers. This addon provides a more ergonomic way to handle component lifecycle events and query changes.
+
+## Installation
+
+The observers addon is included with jecs and can be imported directly:
+
+```luau
+local jecs = require(path/to/jecs)
+local observers_add = require(path/to/jecs/addons/observers)
+
+local world = observers_add(jecs.world())
+```
+
+## Methods
+
+### added
+
+Registers a callback that is invoked when a component is added to any entity.
+
+```luau
+function World:added<T>(
+    component: Id<T>,
+    callback: (entity: Entity, id: Id<T>, value: T?) -> ()
+): () -> () -- Returns an unsubscribe function
+```
+
+**Parameters:**
+- `component` - The component ID to listen for additions
+- `callback` - Function called when component is added, receives entity, component ID, and value
+
+**Returns:** An unsubscribe function that removes the listener when called
+
+**Example:**
+```luau
+local Health = world:component() :: jecs.Entity<number>
+
+local unsubscribe = world:added(Health, function(entity, id, value)
+    print("Health component added to entity", entity, "with value", value)
+end)
+
+-- Later, to stop listening:
+unsubscribe()
+```
+
+### removed
+
+Registers a callback that is invoked when a component is removed from any entity.
+
+```luau
+function World:removed<T>(
+    component: Id<T>,
+    callback: (entity: Entity, id: Id<T>) -> ()
+): () -> () -- Returns an unsubscribe function
+```
+
+**Parameters:**
+- `component` - The component ID to listen for removals
+- `callback` - Function called when component is removed, receives entity and component ID
+
+**Returns:** An unsubscribe function that removes the listener when called
+
+**Example:**
+```luau
+local Health = world:component() :: jecs.Entity<number>
+
+local unsubscribe = world:removed(Health, function(entity, id)
+    print("Health component removed from entity", entity)
+end)
+```
+
+### changed
+
+Registers a callback that is invoked when a component's value is changed on any entity.
+
+```luau
+function World:changed<T>(
+    component: Id<T>,
+    callback: (entity: Entity, id: Id<T>, value: T) -> ()
+): () -> () -- Returns an unsubscribe function
+```
+
+**Parameters:**
+- `component` - The component ID to listen for changes
+- `callback` - Function called when component value changes, receives entity, component ID, and new value
+
+**Returns:** An unsubscribe function that removes the listener when called
+
+**Example:**
+```luau
+local Health = world:component() :: jecs.Entity<number>
+
+local unsubscribe = world:changed(Health, function(entity, id, value)
+    print("Health changed to", value, "for entity", entity)
+end)
+```
+
+### observer
+
+Creates a query-based observer that triggers when entities match or stop matching a query.
+
+```luau
+function World:observer<T...>(
+    query: Query<T...>,
+    callback: ((entity: Entity, id: Id, value: any?) -> ())?
+): () -> () -> Entity -- Returns an iterator function
+```
+
+**Parameters:**
+- `query` - The query to observe for changes
+- `callback` - Optional function called when entities match the query
+
+**Returns:** An iterator function that returns entities that matched the query since last iteration
+
+**Example:**
+```luau
+local Position = world:component() :: jecs.Id<Vector3>
+local Velocity = world:component() :: jecs.Id<Vector3>
+
+local moving_entities = world:observer(
+    world:query(Position, Velocity),
+    function(entity, id, value)
+        print("Entity", entity, "started moving")
+    end
+)
+
+-- In your game loop:
+for entity in moving_entities() do
+    -- Process newly moving entities
+end
+```
+
+### monitor
+
+Creates a query-based monitor that triggers when entities are added to or removed from a query.
+
+```luau
+function World:monitor<T...>(
+    query: Query<T...>,
+    callback: ((entity: Entity, id: Id, value: any?) -> ())?
+): () -> () -> Entity -- Returns an iterator function
+```
+
+**Parameters:**
+- `query` - The query to monitor for additions/removals
+- `callback` - Optional function called when entities are added or removed from the query
+
+**Returns:** An iterator function that returns entities that were added or removed since last iteration
+
+**Example:**
+```luau
+local Health = world:component() :: jecs.Id<number>
+
+local health_changes = world:monitor(
+    world:query(Health),
+    function(entity, id, value)
+        print("Health component changed for entity", entity)
+    end
+)
+
+-- In your game loop:
+for entity in health_changes() do
+    -- Process entities with health changes
+end
+```
+
+## Usage Patterns
+
+### Component Lifecycle Tracking
+
+```luau
+local Player = world:component()
+local Health = world:component() :: jecs.Id<number>
+
+-- Track when players are created
+world:added(Player, function(entity, id, instance)
+	instance:SetAttribute("entityid", entity)
+end)
+
+world:removed(Player, function(entity, id)
+	world:add(entity, Destroy) -- process its deletion later!
+end)
+```
+
+## Performance Considerations
+
+- **Signal listeners** are called immediately when components are added/removed/changed
+- **Query observers** cache the query for better performance
+- **Multiple listeners** for the same component are supported and called in registration order
+- **Unsubscribe functions** should be called when listeners are no longer needed to prevent memory leaks
+- **Observer iterators** should be called regularly to clear the internal buffer
+
+## Integration with Built-in Hooks
+
+The observers addon integrates with the built-in component hooks (`OnAdd`, `OnRemove`, `OnChange`). If a component already has these hooks configured, the observers addon will preserve them and call both the original hook and any registered signal listeners.

docs/api/query.md

@@ -4,13 +4,38 @@ A World contains entities which have components. The World is queryable and can
 
 # Methods
 
-## iter
+## cached
 
-Returns an iterator that can be used to iterate over the query.
+Returns a cached version of the query. This is useful if you want to create a query that you can iterate multiple times.
 
 ```luau
-function Query:iter(): () -> (Entity, ...)
+function Query:cached(): Query -- Returns the cached Query
 ```
+Example:
+
+::: code-group
+
+```luau [luau]
+local lerps = world:query(Lerp):cached() -- Ensure that you cache this outside a system so you do not create a new cache for a query every frame
+
+local function system(dt)
+	for entity, lerp in lerps do
+		-- Do something
+	end
+end
+```
+
+```ts [typescript]
+const lerps = world.query(Lerp).cached()
+
+function system(dt) {
+	for (const [entity, lerp] of lerps) {
+		// Do something
+	}
+}
+```
+
+:::
 
 ## with
 
@@ -83,15 +108,13 @@ Example:
 
 ```luau [luau]
 for i, archetype in world:query(Position, Velocity):archetypes() do
-    local columns = archetype.columns
+    local field = archetype.columns_map
-    local field = archetype.records
+    local positions = field[Position]
-
+    local velocities = field[Velocity]
-    local P = field[Position]
-    local V = field[Velocity]
 
     for row, entity in archetype.entities do
-        local position = columns[P][row]
+        local position = positions[row]
-        local velocity = columns[V][row]
+        local velocity = velocities[row]
         -- Do something
     end
 end
@@ -101,10 +124,27 @@ end
 This function is meant for people who want to really customize their query behaviour at the archetype-level
 :::
 
-## cached
+## iter
-
+In most cases, you can iterate over queries directly using `for entity, ... in query do`. The `:iter()` method is mainly useful if you are on the old solver, to get types for the returned values.
-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
+function Query:iter(): () -> (Entity, ...)
+```
+
+Example:
+
+::: code-group
+```luau [luau]
+local query = world:query(Position, Velocity)
+
+-- Direct iteration (recommended)
+for entity, position, velocity in query do
+    -- Process entity
+end
+
+-- Using explicit iterator (when needed for the old solver)
+local iterator = query:iter()
+for entity, position, velocity in iterator do
+    -- Process entity
+end
 ```

docs/api/world.md

@@ -6,7 +6,7 @@ A World contains entities which have components. The World is queryable and can
 
 ## new
 
-`World` utilizes a class, meaning JECS allows you to create multiple worlds.
+`World` utilizes a class, meaning jecs allows you to create multiple worlds.
 
 ```luau
 function World.new(): World
@@ -55,12 +55,12 @@ 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.
+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.
+function World:component<T>(): Entity<T> -- The new component.
 ```
 
 Example:
@@ -241,7 +241,10 @@ print(world.get(Entity, Health));
 // 100
 // 50
 ```
+:::
 
+:::info
+`world:set(entity, component, value)` propagates that a change has happened for thes component on this entity, while mutating a value directly would not.
 :::
 
 ## query
@@ -289,10 +292,52 @@ If the index is larger than the total number of instances the entity has for the
 ```luau
 function World:target(
     entity: Entity, -- The entity
-    relation: Entity, -- The relationship between the entity and the target
+    relation: Id, -- The relationship between the entity and the target
     nth: number, -- The index
-): Entity? -- The target for the relationship at the specified index.
+): Id? -- The target for the relationship at the specified index.
 ```
+Example:
+
+::: code-group
+
+```luau [luau]
+local function timers_count(world: types.World)
+	local timers = world
+		:query(jecs.pair(ct.Timer, jecs.w))
+		:without(ct.Destroy)
+		:cached()
+
+	return function(_, dt: number)
+		for entity in timers do
+			local index = 0
+			local nth = world:target(entity, ct.Timer, index)
+			while nth do
+				local timer = world:get(entity, jecs.pair(ct.Timer, nth))
+				local elapsed = timer.elapsed + dt
+				if elapsed >= timer.duration then
+					world:add(entity, ct.Destroy)
+				end
+				timer.elapsed = elapsed
+			end
+		end
+	end
+end
+```
+
+```ts [typescript]
+const entity = world.entity();
+print(world.contains(entity));
+print(world.contains(1));
+print(world.contains(2));
+
+// Outputs:
+// true
+// true
+// false
+```
+
+:::
+
 
 ## parent
 
@@ -355,9 +400,9 @@ print(world.contains(2));
 Removes a component (ID) from an entity
 
 ```luau
-function World:remove(
+function World:remove<T>(
     entity: Entity,
-	component: Entity<T>
+	component: Id<T>
 ): void
 ```
 
@@ -458,20 +503,20 @@ Useful when you only need the entity for a specific ID and you want to avoid cre
 
 ```luau
 function World:each(
-	id: Entity -- The component ID
+	component: Id -- The component ID
 ): () -> Entity
 ```
 
 Example:
 ::: code-group
 ```luau [luau]
-local id = world:entity()
+local id = world:component()
 for entity in world:each(id) do
 	-- Do something
 end
 ```
 ```ts [typescript]
-const id = world.entity();
+const id = world.component();
 for (const entity of world.each(id)) {
 	// Do something
 }
@@ -500,6 +545,122 @@ Enforces a check for entities to be created within a desired range.
 ```luau
 function World:range(
 	range_begin: number -- The starting point,
-	range_begin: number? -- The end point (optional)
+	range_end: number? -- The end point (optional)
 )
 ```
+
+Example:
+
+::: code-group
+```luau [luau]
+world:range(1000, 5000) -- Entities will be created with IDs 1000-5000
+
+local entity = world:entity()
+print(entity) -- Will be >= 1000 and < 5000
+```
+```ts [typescript]
+world.range(1000, 5000) // Entities will be created with IDs 1000-5000
+
+const entity = world.entity()
+print(entity) // Will be >= 1000 and < 5000
+```
+:::
+
+## parent
+
+Gets the parent entity of the specified entity using the built-in `ChildOf` relationship.
+
+```luau
+function World:parent(
+    entity: Entity
+): Entity? -- Returns the parent entity or nil if no parent
+```
+
+Example:
+
+::: code-group
+```luau [luau]
+local parent = world:entity()
+local child = world:entity()
+
+world:add(child, pair(jecs.ChildOf, parent))
+
+local retrieved_parent = world:parent(child)
+print(retrieved_parent == parent) -- true
+```
+```ts [typescript]
+const parent = world.entity()
+const child = world.entity()
+
+world.add(child, pair(jecs.ChildOf, parent))
+
+const retrievedParent = world.parent(child)
+print(retrievedParent === parent) // true
+```
+:::
+
+## contains
+
+Checks if an entity exists and is alive in the world.
+
+```luau
+function World:contains(
+    entity: Entity
+): boolean
+```
+
+Example:
+
+::: code-group
+```luau [luau]
+local entity = world:entity()
+print(world:contains(entity)) -- true
+
+world:delete(entity)
+print(world:contains(entity)) -- false
+```
+```ts [typescript]
+const entity = world.entity()
+print(world.contains(entity)) // true
+
+world.delete(entity)
+print(world.contains(entity)) // false
+```
+:::
+
+## exists
+
+Checks if the entity ID exists regardless of whether it is alive or not. Useful to know if the ID is occupied in the entity index.
+
+```luau
+function World:exists(
+    entity: Entity
+): boolean
+```
+
+## cleanup
+
+Cleans up deleted entities and their associated data. This is automatically called by jecs, but can be called manually if needed.
+
+```luau
+function World:cleanup(): void
+```
+
+Example:
+
+::: code-group
+```luau [luau]
+local entity = world:entity()
+world:delete(entity)
+
+-- Cleanup is usually automatic, but can be called manually
+world:cleanup()
+```
+```ts [typescript]
+const entity = world.entity()
+world.delete(entity)
+
+// Cleanup is usually automatic, but can be called manually
+world.cleanup()
+```
+:::

docs/learn/overview.md

@@ -27,8 +27,8 @@ local jecs = require(path/to/jecs)
 local world = jecs.world()
 ```
 ```typescript [typescript]
-import { World } from "@rbxts/jecs"
+import * as jecs from "@rbxts/jecs"
-const world = new World()
+const world = jecs.world()
 // creates a new entity with no components and returns its identifier
 const entity = world.entity()
 
@@ -156,6 +156,13 @@ world.set(Transform, OnChange, (entity, id, data) => {
 ```
 :::
 
+:::info
+Children are cleaned up before parents
+When a parent and its children are deleted, OnRemove hooks will be invoked for children first, under the condition that there are no cycles in the relationship graph of the deleted entities. This order is maintained for any relationship that has the (OnDeleteTarget, Delete) trait (see Component Traits for more details).
+
+When an entity graph contains cycles, order is undefined. This includes cycles that can be formed using different relationships.
+:::
+
 ### 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.
@@ -166,13 +173,20 @@ This is what cleanup traits are for: to specify which action needs to be execute
 
 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:
+#### Cleanup Traits Summary
 
+| Condition | Action | Description | Use Case |
+|-----------|--------|-------------|----------|
+| `OnDelete` | `Remove` | Removes the component from all entities when the component is deleted | Default behavior, safe cleanup |
+| `OnDelete` | `Delete` | Deletes all entities that have the component when the component is deleted | Cascading deletion, dangerous |
+| `OnDeleteTarget` | `Remove` | Removes the relationship from all entities when the target is deleted | Safe relationship cleanup |
+| `OnDeleteTarget` | `Delete` | Deletes all entities that have the relationship when the target is deleted | Hierarchical deletion (e.g., parent-child) |
+
+**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:
+**Cleanup Conditions:**
-
 - `OnDelete`: the component, tag or relationship is deleted
 - `OnDeleteTarget`: a target used with the relationship is deleted
 
@@ -285,9 +299,10 @@ jecs.world() -- Position gets registered here
 ```
 
 ```typescript [typescript]
+import { world } from "@rbxts/jecs"
 const Position = jecs.component<Vector3>();
 
-new World() // Position gets registered here
+world() // Position gets registered here
 ```
 :::
 
@@ -301,9 +316,11 @@ jecs.world() -- Position gets registered here with its name "Position"
 ```
 
 ```typescript [typescript]
+import { world } from "@rbxts/jecs"
+
 jecs.meta(Position, jecs.Name, "Position")
 
-new World() // Position gets registered here with its name "Position"
+world() // Position gets registered here with its name "Position"
 ```
 :::
 
@@ -632,7 +649,7 @@ world:set(e, pair(Eats, Apples), { amount = 1 })
 world:set(e, pair(Begin, Position), Vector3.new(0, 0, 0))
 world:set(e, pair(End, Position), Vector3.new(10, 20, 30))
 
-world:add(e, jecs.ChildOf, Position)
+world:add(e, pair(jecs.ChildOf, Position))
 
 ```
 ```typescript [typescript]
@@ -648,7 +665,7 @@ world.set(e, pair(Eats, Apples), { amount: 1 })
 world.set(e, pair(Begin, Position), new Vector3(0, 0, 0))
 world.set(e, pair(End, Position), new Vector3(10, 20, 30))
 
-world.add(e, jecs.ChildOf, Position)
+world.add(e, pair(jecs.ChildOf, Position))
 ```
 :::
 
@@ -695,3 +712,7 @@ To improve the speed of evaluating queries, Jecs has indices that store all arch
 While registering an archetype for a relationship index is not more expensive than registering an archetype for a regular index, an archetype with relationships has to also register itself with the appropriate wildcard indices for its relationships. For example, an archetype with relationship `pair(Likes, Apples)` registers itself with the `pair(Likes, Apples)`, `pair(Likes, jecs.Wildcard)` and `pair(jecs.Wildcard, Apples)` indices. For this reason, creating new archetypes with relationships has a higher overhead than an archetype without relationships.
 
 This page takes wording and terminology directly from Flecs, the first ECS with full support for [Entity Relationships](https://www.flecs.dev/flecs/md_docs_2Relationships.html).
+
+## Next Steps
+
+- [API Reference](../api/jecs.md) - Complete API documentation

docs/resources.md

@@ -49,8 +49,8 @@ A tool for inspecting entity lifetimes
 
 ### Helpers
 
-#### [jecs_observers](https://github.com/Ukendio/jecs/blob/main/addons/observers.luau)
+#### [jecs_ob](https://github.com/Ukendio/jecs/blob/main/addons/ob.luau)
-Observers for queries and signals for components
+Observers & Monitors for queries
 
 ### [hammer](https://github.com/Mark-Marks/hammer)
 A set of utilities for Jecs

jecs.d.ts

@@ -49,7 +49,7 @@ export type Archetype<T extends unknown[]> = {
 	type: string;
 	entities: number[];
 	columns: Column<unknown>[];
-	columns_map: { [K in keyof T]: Column<T[K]> }
+	columns_map: Record<Id, Column<T[number]>>
 };
 
 type Iter<T extends unknown[]> = IterableFunction<LuaTuple<[Entity, ...T]>>;
@@ -156,8 +156,8 @@ export class World {
 	 * @param hook The hook to install.
 	 * @param value The hook callback.
 	 */
-	set<T>(component: Entity<T>, hook: StatefulHook, value: (e: Entity<T>, id: Id<T>, data: T) => void): void;
+	set<T>(component: Entity<T>, hook: StatefulHook, value: (e: Entity, id: Id<T>, data: T) => void): void;
-	set<T>(component: Entity<T>, hook: StatelessHook, value: (e: Entity<T>, id: Id<T>) => void): void;
+	set<T>(component: Entity<T>, hook: StatelessHook, value: (e: Entity, id: Id<T>) => void): void;
 	/**
 	 * Assigns a value to a component on the given entity.
 	 * @param entity The target entity.
@@ -247,6 +247,10 @@ export class World {
 	 * @returns A Query object to iterate over results.
 	 */
 	query<T extends Id[]>(...components: T): Query<InferComponents<T>>;
+
+	added<T>(component: Entity<T>, listener: (e: Entity, id: Id<T>, value: T) => void): () => void
+	changed<T>(component: Entity<T>, listener: (e: Entity, id: Id<T>, value: T) => void): () => void
+	removed<T>(component: Entity<T>, listener: (e: Entity, id: Id<T>) => void): () => void
 }
 
 export function world(): World;

package.json

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

test/addons/observers.luau

@@ -2,43 +2,28 @@ 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 FOCUS = test.FOCUS
+local ob = require("@addons/ob")
 
 TEST("addons/observers", function()
-	local world = observers_add(jecs.world())
 
-	do CASE "Should work even if set after the component has been used"
+	local world = jecs.world()
+	do CASE "monitors should accept pairs"
 		local A = world:component()
+		local B = world:component()
 
-		world:set(world:entity(), A, 2)
+		local c = 1
-		local ran = false
+		ob.monitor(world:query(jecs.pair(A, B)), function (_, event)
-		world:added(A, function()
+			c += 1
-			ran = true
 		end)
 
-		local entity = world:entity()
+		local child = world:entity()
-		world:set(entity, A, 3)
+		world:add(child, jecs.pair(A, B))
+		CHECK(c == 2)
 
-		CHECK(ran)
+		world:remove(child, jecs.pair(A, B))
+		CHECK(c == 3)
 	end
-
-	do CASE "Should not override hook"
-		local A = world:component()
-
-		local count = 1
-		local function counter()
-			count += 1
-		end
-
-		world:set(A, jecs.OnAdd, counter)
-		world:added(A, counter)
-		world:set(world:entity(), A, false)
-		CHECK(count == (1 + 2))
-		world:set(world:entity(), A, false)
-
-		CHECK(count == (1 + (2 * 2)))
-	end
-
 	do CASE "Ensure ordering between signals and observers"
 		local A = world:component()
 		local B = world:component()
@@ -48,11 +33,15 @@ TEST("addons/observers", function()
 			count += 1
 		end
 
-		world:observer(world:query(A, B), counter)
+		ob.observer(world:query(A, B), counter)
 
 		world:added(A, counter)
 		world:added(A, counter)
 
+		for _ in world:query(A) do
+
+		end
+
 		local e = world:entity()
 		world:add(e, A)
 		CHECK(count == 3)
@@ -69,7 +58,7 @@ TEST("addons/observers", function()
 			count += 1
 		end
 
-		world:observer(world:query(A), counter)
+		ob.observer(world:query(A), counter)
 
 		local e = world:entity()
 		world:set(e, A, false)
@@ -89,7 +78,7 @@ TEST("addons/observers", function()
 			count += 1
 		end
 
-		world:monitor(world:query(A), counter)
+		ob.monitor(world:query(A), counter)
 
 		local e = world:entity()
 		world:set(e, A, false)

test/tests.luau

@@ -175,9 +175,9 @@ TEST("repro", function()
 	world:delete(e1)
 
 	local e1v1 = world:entity()
-	CHECK(ECS_ID(e1v1) == e1)
+	CHECK(ECS_ID(e1v1) == e1::any)
 	local e2v1 = world:entity()
-	CHECK(ECS_ID(e2v1) == e2)
+	CHECK(ECS_ID(e2v1) == e2::any)
 	world:set(e2v1, data, 456)
 
 	CHECK(world:contains(e1v1))
@@ -341,28 +341,17 @@ TEST("world:add()", function()
 		local B = world:component()
 		local C = world:component()
 
-		local e_ptr = jecs.Rest :: number + 1
+		local e_ptr: jecs.Entity = (jecs.Rest :: any) + 1
 
 		world:add(A, jecs.Exclusive)
 		local on_remove_call = false
 		world:set(A, jecs.OnRemove, function(e, id)
-			CHECK(e == e_ptr)
-			CHECK(id == jecs.pair(A, B))
 			on_remove_call = true
 		end)
 
 		local on_add_call_count = 0
 		world:set(A, jecs.OnAdd, function(e, id)
 			on_add_call_count += 1
-			if on_add_call_count == 1 then
-				CHECK(e == e_ptr)
-				CHECK(id == jecs.pair(A, B))
-			elseif on_add_call_count == 2 then
-				CHECK(e == e_ptr)
-				CHECK(id == jecs.pair(A, C))
-			else
-				CHECK(false)
-			end
 		end)
 
 
@@ -377,6 +366,17 @@ TEST("world:add()", function()
 		CHECK(world:has(e, pair(A, B)) == false)
 		CHECK(world:has(e, pair(A, C)) == true)
 
+		-- We have to ensure that it actually invokes hooks everytime it
+		-- traverses the archetype
+		e = world:entity()
+		world:add(e, pair(A, B))
+		CHECK(on_add_call_count == 3)
+		world:add(e, pair(A, C))
+		CHECK(on_add_call_count == 4)
+		CHECK(on_remove_call)
+
+		CHECK(world:has(e, pair(A, B)) == false)
+		CHECK(world:has(e, pair(A, C)) == true)
 	end
 
 	do CASE "idempotent"
@@ -1062,6 +1062,81 @@ TEST("world:each()", function()
 	end
 end)
 
+TEST("world:added", function()
+	local world = jecs.world()
+	do CASE "Should work even if set after the component has been used"
+		local A = world:component()
+		world:set(world:entity(), A, 2)
+		local ran = false
+		world:added(A, function()
+			ran = true
+		end)
+		local entity = world:entity()
+		world:set(entity, A, 3)
+		CHECK(ran)
+	end
+
+
+	do CASE "Should work even if set after the pair has been used"
+		local A = world:component()
+		local B = world:component()
+
+		world:set(world:entity(), A, 2)
+		world:set(world:entity(), pair(A, B), 2)
+
+		world:added(A, function()
+			ran = true
+		end)
+
+		local entity = world:entity()
+		world:set(entity, pair(A, B), 3)
+		CHECK(ran)
+	end
+
+	do CASE "Should allow setting signal after Relation has been used as a component"
+		local A = world:component()
+		local B = world:component()
+
+		world:add(world:entity(), A)
+
+		world:added(A, function()
+			ran = true
+		end)
+
+		world:add(world:entity(), pair(A, B))
+		CHECK(ran)
+	end
+
+	do CASE "Should invoke signal for the Relation being set as a key despite a pair with Relation having been cached"
+		local A = world:component()
+		local B = world:component()
+
+		world:add(world:entity(), pair(A, B))
+
+		world:added(A, function()
+			ran = true
+		end)
+
+		world:add(world:entity(), A)
+
+		CHECK(ran)
+	end
+
+	do CASE "Should not override hook"
+		local A = world:component()
+		local count = 1
+		local function counter()
+			count += 1
+		end
+		world:set(A, jecs.OnAdd, counter)
+		world:added(A, counter)
+		world:set(world:entity(), A, false)
+		CHECK(count == (1 + 2))
+		world:set(world:entity(), A, false)
+		CHECK(count == (1 + (2 * 2)))
+	end
+end)
+
 TEST("world:range()", function()
 
 	do CASE "spawn entity under min range"
@@ -1127,7 +1202,7 @@ TEST("world:range()", function()
 		client:range(1000, 5000)
 
 		local e1 = server:entity()
-		CHECK((e1::number)< 1000)
+		CHECK((e1::any)< 1000)
 		server:delete(e1)
 		local e2 = client:entity(e1)
 		CHECK(e2 == e1)
@@ -1137,12 +1212,12 @@ TEST("world:range()", function()
 
 		client:delete(e2)
 		local e3 = client:entity()
-		CHECK(ECS_ID(e3::number) == 1000)
+		CHECK(ECS_ID(e3) == 1000)
 
 		local e1v1 = server:entity()
 		local e4 = client:entity(e1v1)
-		CHECK(ECS_ID(e4::number) == e1)
+		CHECK(ECS_ID(e4) == e1::any)
-		CHECK(ECS_GENERATION(e4::number) == 1)
+		CHECK(ECS_GENERATION(e4) == 1)
 		CHECK(not client:contains(e2))
 		CHECK(client:contains(e4))
 	end
@@ -1151,15 +1226,16 @@ TEST("world:range()", function()
 
 		local world = jecs.world()
 		world:range(400, 1000)
-		local id = world:entity() :: number
+		local id = world:entity()
-		local e = world:entity(id + 5)
+		local e = world:entity(id::any + 5)
-		CHECK(e == id + 5)
+		CHECK(e::any == (id::any) + 5)
+
 		CHECK(world:contains(e))
 		local e2 = world:entity(399)
 		CHECK(world:contains(e2))
 		world:delete(e2)
 		CHECK(not world:contains(e2))
-		local e2v1 = world:entity(399) :: number
+		local e2v1 = world:entity(399)
 		CHECK(world:contains(e2v1))
 		CHECK(ECS_ID(e2v1) == 399)
 		CHECK(ECS_GENERATION(e2v1) == 0)
@@ -1172,13 +1248,13 @@ TEST("world:range()", function()
 		CHECK(world:contains(e2))
 		world:delete(e2)
 		CHECK(not world:contains(e2))
-		local e2v1 = world:entity(405) :: number
+		local e2v1 = world:entity(405)
 		CHECK(world:contains(e2v1))
 		CHECK(ECS_ID(e2v1) == 405)
 		CHECK(ECS_GENERATION(e2v1) == 0)
 
 		world:delete(e2v1)
-		local e2v2 = world:entity(e2v1) :: number
+		local e2v2 = world:entity(e2v1)
 		CHECK(ECS_ID(e2v2) == 405)
 		CHECK(ECS_GENERATION(e2v2) == 0)
 	end
@@ -1187,9 +1263,10 @@ end)
 TEST("world:entity()", function()
 	do CASE "desired id"
 		local world = jecs.world()
-		local id = world:entity() :: number
+		local id = world:entity()
-		local e = world:entity(id + 5)
+		local offset: jecs.Entity = (id ::any) + 5
-		CHECK(e == id + 5)
+		local e = world:entity(offset)
+		CHECK(e == offset)
 		CHECK(world:contains(e))
 		local e2 = world:entity(399)
 		CHECK(world:contains(e2))
@@ -1207,7 +1284,7 @@ TEST("world:entity()", function()
 	end
 	do CASE "generations"
 		local world = jecs.world()
-		local e = world:entity() :: any
+		local e = world:entity()
 		CHECK(ECS_ID(e) == 1 + jecs.Rest :: any)
 		CHECK(ECS_GENERATION(e) == 0) -- 0
 		e = ECS_GENERATION_INC(e)
@@ -1257,11 +1334,11 @@ TEST("world:entity()", function()
 			local e = world:entity()
 			world:delete(e)
 		end
-		local e = world:entity() :: number
+		local e = world:entity()
 		CHECK(ECS_ID(e) == pin)
 		CHECK(ECS_GENERATION(e) == 2^16-1)
 		world:delete(e)
-		e = world:entity() :: number
+		e = world:entity()
 		CHECK(ECS_ID(e) == pin)
 		CHECK(ECS_GENERATION(e) == 0)
 	end
@@ -1536,6 +1613,7 @@ TEST("world:query()", function()
 
 		for i = 1, 9 do
 			local id = world:component()
+			world:component() -- make the components sparsely interleaved
 			components[i] = id
 		end
 		local e1 = world:entity()
@@ -1779,7 +1857,7 @@ TEST("world:query()", function()
 		world:add(e2, B)
 
 		local count = 0
-		for id in world:query(A) :: any do
+		for id in world:query(A) do
 			world:clear(id)
 			count += 1
 		end
@@ -2219,14 +2297,14 @@ TEST("change tracking", function()
 		world:set(e2, Foo, 2)
 
 		local i = 0
-		for e, new in q1 :: any do
+		for e, new in q1 do
 			i += 1
 			world:set(e, pair(Previous, Foo), new)
 		end
 
 		CHECK(i == 2)
 		local j = 0
-		for e, new in q1 :: any do
+		for e, new in q1 do
 			j += 1
 			world:set(e, pair(Previous, Foo), new)
 		end
@@ -2247,14 +2325,14 @@ TEST("change tracking", function()
 		world:set(testEntity, component, 10)
 
 		local i = 0
-		for entity, number in q1 :: any do
+		for entity, number in q1 do
 			i += 1
 			world:add(testEntity, tag)
 		end
 
 		CHECK(i == 1)
 
-		for e, n in q1 :: any do
+		for e, n in q1 do
 			world:set(e, pair(previous, component), n)
 		end
 	end

wally.toml

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