jecs/CHANGELOG.md

@@ -11,6 +11,8 @@ The format is based on [Keep a Changelog][kac], and this project adheres to
 ## [Unreleased]
 
 -   `[world]`:
+    -   Added `world:range` to restrict entity range
+    -       Changed `world:entity` to accept the overload to create an entity at the desired index
     -   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

jecs/addons/observers.luau

@@ -24,7 +24,7 @@ local function observers_new(world, description)
 	end
 
 	local entity_index = world.entity_index :: any
-	local function emplaced(entity: jecs.Entity)
+	local function emplaced(entity, id, value)
 		local r = jecs.entity_index_try_get_fast(
 			entity_index, entity :: any)
 
@@ -45,6 +45,106 @@ local function observers_new(world, description)
  	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
+	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 query_changed(world, component)
+	assert(jecs.IS_PAIR(component) == false)
+	local callerid = debug.info(2, "sl")
+
+	local tracker = world.trackers[callerid]
+	if not tracker then
+		local records = {}
+		local connections = {}
+		tracker = {
+			records = records,
+			connections = connections
+		}
+		world.trackers[callerid] = tracker
+
+		table.insert(connections, world:added(component, function(entity, id, v)
+			tracker[entity] = {
+				new = v
+			}
+		end))
+		table.insert(connections, world:changed(component, function(entity, id, v)
+			local record = tracker[entity]
+			record.old = record.new
+			record.new = v
+		end))
+
+		table.insert(connections, world:removed(component, function(entity, id)
+			local record = tracker[entity]
+			record.old = record.new
+			record.new = nil
+		end))
+	end
+
+	local entity = nil
+	local record = nil
+	return function()
+		entity, record = next(tracker, entity)
+		if entity == nil then
+			return
+		end
+		return entity, record
+	end
+end
+
+local function spy_on_world_delete(world)
+	local world_delete = world.delete
+	world.delete = function(world, entity)
+		world_delete(world, entity)
+		for _, tracker in world.trackers do
+			tracker.records[entity] = nil
+			for _, connection in tracker.connections do
+				connection()
+			end
+		end
+	end
+end
+
 local function monitors_new(world, description)
 	local query = description.query
 	local callback = description.callback
@@ -93,10 +193,11 @@ local function monitors_new(world, description)
 end
 
 local function observers_add(world: jecs.World & { [string]: any }): PatchedWorld
+	type Signal = { [jecs.Entity]: { (...any) -> () } }
 	local signals = {
-		added = {},
+		added = {} :: Signal,
-		emplaced = {},
+		emplaced = {} :: Signal,
-		removed = {}
+		removed = {} :: Signal
 	}
 
 	world.added = function(_, component, fn)
@@ -106,13 +207,21 @@ local function observers_add(world: jecs.World & { [string]: any }): PatchedWorl
 		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
+			world:set(component, jecs.OnAdd, on_add)
+		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.changed = function(_, component, fn)
@@ -130,6 +239,12 @@ local function observers_add(world: jecs.World & { [string]: any }): PatchedWorl
 			world:set(component, jecs.OnChange, on_change)
 		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.removed = function(_, component, fn)
@@ -147,6 +262,12 @@ local function observers_add(world: jecs.World & { [string]: any }): PatchedWorl
 			world:set(component, jecs.OnRemove, on_remove)
 		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.signals = signals
@@ -155,6 +276,8 @@ local function observers_add(world: jecs.World & { [string]: any }): PatchedWorl
 
 	world.monitor = monitors_new
 
+	world.trackers = {}
+
 	return world :: PatchedWorld
 end
 

jecs/build.txt

@@ -1,2 +1,2 @@
-modified = ["addons/observers.luau", "jecs.luau"]
+modified = ["addons/observers.luau", "CHANGELOG.md", "jecs.luau"]
-version = "0.5.5-nightly.20250423T001100Z"
+version = "0.5.5-nightly.20250426T001101Z"

jecs/jecs.luau

@@ -62,6 +62,8 @@ type ecs_entity_index_t = {
 	sparse_array: Map<i24, ecs_record_t>,
 	alive_count: number,
 	max_id: number,
+	range_begin: number?,
+	range_end: number?
 }
 
 type ecs_query_data_t = {
@@ -125,6 +127,12 @@ local ECS_INTERNAL_ERROR = [[
 	https://github.com/Ukendio/jecs/issues/new?template=BUG-REPORT.md
 ]]
 
+local function ecs_assert(condition, msg: string?)
+	if not condition then
+		error(msg)
+	end
+end
+
 local ecs_metadata: Map<i53, Map<i53, any>> = {}
 local ecs_max_component_id = 0
 local ecs_max_tag_id = EcsRest
@@ -185,6 +193,10 @@ local function ECS_ENTITY_T_LO(e: i53): i24
 	return e % ECS_ENTITY_MASK
 end
 
+local function ECS_ID(e: i53)
+	return e % ECS_ENTITY_MASK
+end
+
 local function ECS_GENERATION(e: i53)
 	return e // ECS_ENTITY_MASK
 end
@@ -249,10 +261,10 @@ local function entity_index_is_alive(entity_index: ecs_entity_index_t, entity: i
 	return entity_index_try_get(entity_index, entity) ~= nil
 end
 
-local function entity_index_get_alive(index: ecs_entity_index_t, entity: i53): i53?
+local function entity_index_get_alive(entity_index: ecs_entity_index_t, entity: i53): i53?
-	local r = entity_index_try_get_any(index, entity)
+	local r = entity_index_try_get_any(entity_index, entity)
 	if r then
-		return index.dense_array[r.dense]
+		return entity_index.dense_array[r.dense]
 	end
 	return nil
 end
@@ -280,11 +292,15 @@ local function ecs_get_alive(world, entity)
 	return current
 end
 
+local ECS_INTERNAL_ERROR_INCOMPATIBLE_ENTITY = "Entity is outside range"
+
 local function entity_index_new_id(entity_index: ecs_entity_index_t): i53
 	local dense_array = entity_index.dense_array
 	local alive_count = entity_index.alive_count
+	local sparse_array = entity_index.sparse_array
 	local max_id = entity_index.max_id
-	if alive_count ~= max_id then
+
+	if alive_count < max_id then
 		alive_count += 1
 		entity_index.alive_count = alive_count
 		local id = dense_array[alive_count]
@@ -292,11 +308,14 @@ local function entity_index_new_id(entity_index: ecs_entity_index_t): i53
 	end
 
 	local id = max_id + 1
+	local range_end = entity_index.range_end
+	ecs_assert(range_end == nil or id < range_end, ECS_INTERNAL_ERROR_INCOMPATIBLE_ENTITY)
+
 	entity_index.max_id = id
 	alive_count += 1
 	entity_index.alive_count = alive_count
 	dense_array[alive_count] = id
-	entity_index.sparse_array[id] = { dense = alive_count } :: ecs_record_t
+	sparse_array[id] = { dense = alive_count } :: ecs_record_t
 
 	return id
 end
@@ -583,10 +602,10 @@ local function id_record_ensure(world: ecs_world_t, id: number): ecs_id_record_t
 	local is_pair = ECS_IS_PAIR(id)
 	if is_pair then
 		relation = entity_index_get_alive(entity_index, ECS_PAIR_FIRST(id)) :: i53
-		assert(relation and entity_index_is_alive(
+		ecs_assert(relation and entity_index_is_alive(
 			entity_index, relation), ECS_INTERNAL_ERROR)
 		target = entity_index_get_alive(entity_index, ECS_PAIR_SECOND(id)) :: i53
-		assert(target and entity_index_is_alive(
+		ecs_assert(target and entity_index_is_alive(
 			entity_index, target), ECS_INTERNAL_ERROR)
 	end
 
@@ -719,8 +738,101 @@ local function archetype_create(world: ecs_world_t, id_types: { i24 }, ty, prev:
 	return archetype
 end
 
-local function world_entity(world: ecs_world_t): i53
+local function world_range(world: ecs_world_t, range_begin: number, range_end: number?)
-	return entity_index_new_id(world.entity_index)
+	local entity_index = world.entity_index
+
+	entity_index.range_begin = range_begin
+	entity_index.range_end = range_end
+
+	local max_id = entity_index.max_id
+
+	if range_begin > max_id then
+		local dense_array = entity_index.dense_array
+		local sparse_array = entity_index.sparse_array
+
+		for i = max_id + 1, range_begin do
+			dense_array[i] = i
+			sparse_array[i] = {
+				dense = 0
+			} :: ecs_record_t
+		end
+		entity_index.max_id = range_begin - 1
+		entity_index.alive_count = range_begin - 1
+	end
+end
+
+local function world_entity(world: ecs_world_t, entity: i53?): i53
+	local entity_index = world.entity_index
+	if entity then
+		local index = ECS_ID(entity)
+		local max_id = entity_index.max_id
+		local sparse_array = entity_index.sparse_array
+		local dense_array = entity_index.dense_array
+		local alive_count = entity_index.alive_count
+		local r = sparse_array[index]
+		if r then
+			local dense = r.dense
+			if not dense or dense == 0 then
+				dense = index
+			end
+			local any = dense_array[dense]
+			if any == entity then
+				if alive_count > dense then
+					r.dense = dense
+					return entity
+				end
+				local e_swap = dense_array[alive_count]
+				local r_swap = sparse_array[alive_count]
+				r_swap.dense = dense
+				r.dense = alive_count
+				dense_array[alive_count] = entity
+				dense_array[dense] = e_swap
+				return entity
+			end
+
+			-- assert(any ~= 0) should never happen
+
+			local e_swap = dense_array[alive_count]
+			local r_swap = sparse_array[alive_count]
+
+			if dense <= alive_count then
+				alive_count += 1
+				entity_index.alive_count = alive_count
+			end
+
+			r_swap.dense = dense
+			r.dense = alive_count
+			dense_array[alive_count] = any
+			dense_array[dense] = e_swap
+			return any
+		else
+			for i = max_id + 1, index do
+				sparse_array[i]	= { dense = i } :: ecs_record_t
+				dense_array[i] = i
+			end
+			entity_index.max_id = index
+
+			local e_swap = dense_array[alive_count]
+			local r_swap = sparse_array[alive_count]
+			r_swap.dense = index
+
+			alive_count += 1
+			entity_index.alive_count = alive_count
+
+			r = sparse_array[index]
+
+			r.dense = alive_count
+
+			sparse_array[index] = r
+
+			dense_array[index] = e_swap
+			dense_array[alive_count] = entity
+
+
+			return entity
+		end
+	end
+	return entity_index_new_id(entity_index, entity)
 end
 
 local function world_parent(world: ecs_world_t, entity: i53)
@@ -2311,6 +2423,8 @@ export type EntityIndex = {
 	sparse_array: Map<i24, Record>,
 	alive_count: number,
 	max_id: number,
+	range_begin: number?,
+	range_end: number?
 }
 
 local World = {}
@@ -2332,6 +2446,7 @@ World.contains = world_contains
 World.cleanup = world_cleanup
 World.each = world_each
 World.children = world_children
+World.range = world_range
 
 local function world_new()
 	local entity_index = {
@@ -2370,16 +2485,7 @@ local function world_new()
 	for i = EcsRest + 1, ecs_max_tag_id do
 		-- Initialize built-in components
 		entity_index_new_id(entity_index)
-	end
+		print("hm...", i)
-
-	for i, bundle in ecs_metadata do
-		for ty, value in bundle do
-			if value == NULL then
-				world_add(self, i, ty)
-			else
-				world_set(self, i, ty, value)
-			end
-		end
 	end
 
 	world_add(self, EcsName, EcsComponent)
@@ -2404,6 +2510,16 @@ local function world_new()
 
 	world_add(self, EcsChildOf, ECS_PAIR(EcsOnDeleteTarget, EcsDelete))
 
+	for i, bundle in ecs_metadata do
+		for ty, value in bundle do
+			if value == NULL then
+				world_add(self, i, ty)
+			else
+				world_set(self, i, ty, value)
+			end
+		end
+	end
+
 	return self
 end
 
@@ -2454,6 +2570,9 @@ export type World = {
 
 	observable: any,
 
+	--- Enforce a check on entities to be created within desired range
+	range: (self: World, range_begin: number, range_end: number?) -> (),
+
 	--- Creates a new entity
 	entity: (self: World, id: Entity?) -> Entity,
 	--- Creates a new entity located in the first 256 ids.
@@ -2558,6 +2677,8 @@ return {
 	ECS_META_RESET = ECS_META_RESET,
 
 	IS_PAIR = (ECS_IS_PAIR :: any) :: <P, O>(pair: Pair<P, O>) -> boolean,
+	ECS_PAIR_FIRST = ECS_PAIR_FIRST,
+	ECS_PAIR_SECOND = ECS_PAIR_SECOND,
 	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,

jecs/pesde-rbx.toml

@@ -3,7 +3,7 @@ includes = ["init.luau", "pesde.toml", "README.md", "CHANGELOG.md", "LICENSE", "
 license = "MIT"
 name = "marked/jecs_nightly"
 repository = "https://git.devmarked.win/marked/jecs-nightly"
-version = "0.5.5-nightly.20250423T001100Z"
+version = "0.5.5-nightly.20250426T001101Z"
 
 [indices]
 default = "https://github.com/pesde-pkg/index"

jecs/pesde.toml

@@ -3,7 +3,7 @@ includes = ["init.luau", "pesde.toml", "README.md", "CHANGELOG.md", "LICENSE", "
 license = "MIT"
 name = "marked/jecs_nightly"
 repository = "https://git.devmarked.win/marked/jecs-nightly"
-version = "0.5.5-nightly.20250423T001100Z"
+version = "0.5.5-nightly.20250426T001101Z"
 
 [indices]
 default = "https://github.com/pesde-pkg/index"

jecs/test.txt

@@ -1,2 +1,2 @@
 passed = true
-timestamp = "20250425T001100Z"
+timestamp = "20250426T001103Z"

jecs/test_fulllog.txt

@@ -1,6 +1,8 @@
-7.3 us   2 kB│ delete children of entity
+hm...	271
-8.8 us   1 kB│ remove friends of entity
+7.7 us   3 kB│ delete children of entity
-346 ns   0  B│ simple deletion of entity
+9.3 us   1 kB│ remove friends of entity
+349 ns   0  B│ simple deletion of entity
+*created e1000v0
 world:add()
 PASS│ idempotent
 PASS│ archetype move
@@ -37,7 +39,11 @@
 world:each()
 PASS│ 
 
+world:range()
+PASS│ 
+
 world:entity()
+PASS│ desired id
 PASS│ unique IDs
 PASS│ generations
 PASS│ pairs
@@ -113,5 +119,5 @@
 PASS│ #2
 PASS│ #3
 
-70/70 test cases passed in 32.159 ms.
+72/72 test cases passed in 31.076 ms.
 0 fails

jecs/wally.toml

@@ -5,4 +5,4 @@ license = "MIT"
 name = "mark-marks/jecs-nightly"
 realm = "shared"
 registry = "https://github.com/UpliftGames/wally-index"
-version = "0.5.5-nightly.20250423T001100Z"
+version = "0.5.5-nightly.20250426T001101Z"