Add entity ranges (#221)

* Add component registration and metadata API

* Fix test case erroring

* Initial commit

* Simplify entity swap logic in world_entity function

* Allow to disconnect signals

* Remove appending to array

* Add ecs_assert and fix entity range handling

* Fix listener array indexing in observers

* Only max_id and alive_count if range_begin is larger than built in
ranges

* No nullable records

* Index is not a stable pointer

CHANGELOG.md

@@ -11,6 +11,7 @@ The format is based on [Keep a Changelog][kac], and this project adheres to
 ## [Unreleased]
 
 -   `[world]`:
+    -   Added `world:range` to allow for creating
     -   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

addons/observers.luau

@@ -89,12 +89,6 @@ local function join(world, component)
 	end
 end
 
-local positions_join = join(world, Position)
-
-for e, v in positions_join() do
-
-end
-
 local function query_changed(world, component)
 	assert(jecs.IS_PAIR(component) == false)
 	local callerid = debug.info(2, "sl")
@@ -208,12 +202,12 @@ local function observers_add(world: jecs.World & { [string]: any }): PatchedWorl
 
 	world.added = function(_, component, fn)
 		local listeners = signals.added[component]
-		local max = #listeners + 1
 		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)
@@ -221,22 +215,21 @@ local function observers_add(world: jecs.World & { [string]: any }): PatchedWorl
 			end
 			world:set(component, jecs.OnAdd, on_add)
 		end
-		listeners[max] = fn
+		table.insert(listeners, fn)
 		return function()
 			local n = #listeners
-			listeners[max] = listeners[n]
+			local i = table.find(listeners, fn)
+			listeners[i] = listeners[n]
 			listeners[n] = nil
 		end
 	end
 
 	world.changed = function(_, component, fn)
 		local listeners = signals.emplaced[component]
-		local max = 0
 		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 = {}
-			max = 1
 			signals.emplaced[component] = listeners
 			local function on_change(entity: number, id: number, value: any)
 				for _, listener in listeners :: any do
@@ -244,18 +237,18 @@ local function observers_add(world: jecs.World & { [string]: any }): PatchedWorl
 				end
 			end
 			world:set(component, jecs.OnChange, on_change)
-		else
-			max = #listeners + 1
 		end
-		listeners[max] = fn
+		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)
 		local listeners = signals.removed[component]
-		local max = #listeners
 		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
@@ -268,10 +261,11 @@ local function observers_add(world: jecs.World & { [string]: any }): PatchedWorl
 			end
 			world:set(component, jecs.OnRemove, on_remove)
 		end
-		listeners[max] = fn
+		table.insert(listeners, fn)
 		return function()
 			local n = #listeners
-			listeners[max] = listeners[n]
+			local i = table.find(listeners, fn)
+			listeners[i] = listeners[n]
 			listeners[n] = nil
 		end
 	end

benches/visual/insertion.bench.luau

@@ -4,10 +4,9 @@
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
 local Matter = require(ReplicatedStorage.DevPackages.Matter)
 local ecr = require(ReplicatedStorage.DevPackages.ecr)
-local jecs = require(ReplicatedStorage.Lib)
-local newWorld = Matter.World.new()
+local jecs = require(ReplicatedStorage.Lib:Clone())
 local ecs = jecs.World.new()
-local mirror = require(ReplicatedStorage.mirror)
+local mirror = require(ReplicatedStorage.mirror:Clone())
 local mcs = mirror.World.new()
 
 local A1 = Matter.component()

benches/visual/spawn.bench.luau

@@ -2,36 +2,32 @@
 --!native
 
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
-local Matter = require(ReplicatedStorage.DevPackages.Matter)
-local ecr = require(ReplicatedStorage.DevPackages.ecr)
-local jecs = require(ReplicatedStorage.Lib)
-local newWorld = Matter.World.new()
-local ecs = jecs.World.new()
+local jecs = require(ReplicatedStorage.Lib:Clone())
+local mirror = require(ReplicatedStorage.mirror:Clone())
+
+
 
 return {
 	ParameterGenerator = function()
-		local registry2 = ecr.registry()
-
-		return registry2
+		local ecs = jecs.world()
+		ecs:range(1000, 20000)
+		local mcs = mirror.World.new()
+		return ecs, mcs
 	end,
 
 	Functions = {
-		Matter = function()
-			for i = 1, 1000 do
-				newWorld:spawn()
+		Mirror = function(_, ecs, mcs)
+			for i = 1, 100 do
+
+				mcs:entity()
 			end
 		end,
 
-		ECR = function(_, registry2)
-			for i = 1, 1000 do
-				registry2.create()
-			end
-		end,
+		Jecs = function(_, ecs, mcs)
+			for i = 1, 100 do
 
-		Jecs = function()
-			for i = 1, 1000 do
 				ecs:entity()
 			end
 		end,
-	},
+},
 }

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 r = entity_index_try_get_any(index, entity)
+local function entity_index_get_alive(entity_index: ecs_entity_index_t, entity: i53): i53?
+	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,100 @@ 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
-	return entity_index_new_id(world.entity_index)
+local function world_range(world: ecs_world_t, range_begin: number, range_end: number?)
+	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, 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
+					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 +2422,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 +2445,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 = {
@@ -2454,6 +2568,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 +2675,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,

test/tests.luau

@@ -247,6 +247,7 @@ TEST("world:component()", function()
 end)
 
 TEST("world:contains()", function()
+
 	local tag = jecs.tag()
 	local world = jecs.world()
 	local id = world:entity()
@@ -258,6 +259,7 @@ TEST("world:contains()", function()
 		CHECK(not world:contains(id))
 	end
 
+
 	CHECK(world:contains(tag))
 	jecs.ECS_META_RESET()
 end)
@@ -631,7 +633,62 @@ TEST("world:each()", function()
 	end
 end)
 
+TEST("world:range()", function()
+	do CASE ""
+		local world = jecs.world()
+		world = lifetime_tracker_add(world, {})
+		world:range(1000, 2000)
+		local e = world:entity()
+		CHECK(e == 1000)
+
+		world:entity(1590)
+
+		CHECK(world:entity(5000) == 5000)
+
+		CHECK(world:contains(1590))
+		world:set(591, jecs.Name, "9888")
+		CHECK(not world:contains(591))
+		CHECK(world:contains(5000))
+		CHECK(not world:contains(988))
+
+		local e = world:entity(2000)
+		CHECK(e == 2000)
+	end
+end)
+
 TEST("world:entity()", function()
+	do CASE "desired id"
+		local world = jecs.world()
+		local id = world:entity()
+		local e = world:entity(id + 5)
+		CHECK(e == id + 5)
+		CHECK(world:contains(e))
+		local e2 = world:entity()
+		CHECK(world:contains(e2))
+
+		-- world:print_entity_index()
+		local e3 = world:entity(275)
+
+		CHECK(e3 == 275)
+		CHECK(world:contains(e3))
+
+		CHECK(e3 == world:entity(e3))
+
+		world:delete(e3)
+
+		local e3v1 = world:entity(275)
+		CHECK(not world:contains(275))
+		CHECK(jecs.ECS_GENERATION(e3v1) == 1)
+		CHECK(jecs.ECS_ID(e3v1) == 275)
+
+
+		CHECK(world:contains(e3v1))
+		-- world:print_entity_index()
+		world:entity(e3)
+
+		world:entity(e3)
+		world:entity(275)
+	end
 	local N = 2^8
 
 	do CASE "unique IDs"

tools/lifetime_tracker.luau

@@ -28,7 +28,7 @@ end
 local padding_enabled = false
 local function pad()
 	if padding_enabled then
-		print("")
+		print("------------------")
 	end
 end
 
@@ -64,7 +64,8 @@ local function lifetime_tracker_add(world: jecs.World, opt): PatchedWorld
 	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 range_begin = entity_index.range_begin or jecs.Rest + 1
+		local alive = table.move(dense_array, range_begin :: any, alive_count, 1, {})
 		local dead = table.move(dense_array, alive_count + 1, max_id, 1, {})
 
 		local sep = "|--------|"

tools/testkit.luau

@@ -229,7 +229,6 @@ end
 local test_focused = false
 
 local function TEST(name: string, fn: () -> ())
-
 	test = {
 		name = name,
 		cases = {},
@@ -244,12 +243,11 @@ local function TEST(name: string, fn: () -> ())
 		test.focus = true
 		test_focused = true
 	end
+
 	table.insert(tests, t)
 end
 
 local function FOCUS()
-	assert(test, "no active test")
-
 	check_for_focused = true
 	test_focused = false
 end