Merge pull request #24 from C6H15/add-tests

Player Tracking Stability & Testing

Author: LDGerrits

docs/intro.md

@@ -89,7 +89,7 @@ This test highlights the fundamental flaw in traditional Zone-Centric libraries.
 Add the following to your wally.toml file:
 
 ```toml
-ldgerrits/quickzone@1.4.4
+ldgerrits/quickzone@1.4.5
 ```
 
 ### NPM

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rbxts/quickzone",
-	"version": "1.4.4",
+	"version": "1.4.5",
 	"description": "A high-performance, physics-free spatial query library for Roblox. Maintain 60 FPS with 1M+ zones.",
 	"main": "src/init.lua",
 	"keywords": [

src/Classes/Group.luau

@@ -685,7 +685,7 @@ function Group._remove(self: Types.InternalGroup, reference: any): Types.Group
 		State.dirtyTopology[entity] = nil
 
 		local ref = State.entityToReference[entity]
-		if ref then
+		if ref and not (typeof(ref) == 'Instance' and ref:IsA('Player')) then
 			State.entityToReference[entity] = nil
 			-- Ensure we only clear the reverse map if it still points to this exact entity
 			if State.referenceToEntity[ref] == entity then

src/Classes/Observer.luau

@@ -113,31 +113,34 @@ local Observer = {}
 Observer.__index = Observer
 
 --[=[ 
-	Creates an Observer. Observers listen for entities entering or exiting assigned Zones.
+	Creates an Observer. Observers listen for entities subscribed Groups entering or exiting attached Zones.
 
 	```lua
 	local observer = QuickZone.Observer.new({
 		groups = { enemyGroup, playerGroup } -- Immediately subscribe to these groups
 		zones = { damageZone } -- Immediately subscribe to these zones
-		priority = 20, -- The priority value is used to resolve overlaps
-		updateRate = 20, -- Check at 20Hz
-		precision = 0.5, -- Ignore movement smaller than 0.5 studs
-		enabled = false, -- Observer will not start processing spatial checks
-		safety = false, -- Do not wrap callbacks in task.spawn
+		priority = 20, -- The priority value is used to resolve overlaps (defaults to 0)
+		updateRate = 20, -- Check at 20Hz (defaults to 30)
+		precision = 0.5, -- Ignore movement smaller than 0.5 studs (defaults to 0.1)
+		enabled = false, -- Observer will not start processing spatial checks (defaults to true)
+		safety = false, -- Wrap callbacks in task.spawn (defaults to true)
 	})
 	```
 
+	:::warning Safety 
+	If safety is set to false, any yielding will result in breaking QuickZone.
+	Only set it to false if you do not want the overhead of virtual threads.
+	:::
+
 	:::info Resolution Priority
 	When an entity is inside multiple zones watched by different observers, 
 	higher priority observers take complete control.
 	:::
 
-	:::warning Safety 
-	If set to unsafe, you are not allowed to yield in the callbacks anymore. If you do, QuickZone will throw errors.
-	:::
-
 	:::note Dynamic Instantiation
-	QuickZone will warn you if an Observer is created without groups or zones. To suppress this warning when building observers dynamically, explicitly pass an empty table (`zones = {}`) or instantiate the observer as disabled (`enabled = false`).
+	QuickZone will warn you if an Observer is created without groups or zones. 
+	To suppress this warning when building observers dynamically, 
+	explicitly pass an empty table (`zones = {}`) or instantiate the observer as disabled (`enabled = false`).
 	:::
 
 	@tag Constructor

src/Classes/Zone.luau

@@ -100,6 +100,7 @@ local function setupAutoSync(zone: Types.InternalZone, reference: BasePart | Att
 	end
 
 	zone.syncConnections = connections
+	zone:sync()
 end
 
 local function updateObserverZoneCount(observerId: number, isDynamic: boolean, delta: number)
@@ -110,6 +111,11 @@ local function updateObserverZoneCount(observerId: number, isDynamic: boolean, d
 
 	-- Only flag entities dirty if the observer's topology fundamentally changed
 	if (current == 0 and newCount == 1) or (current == 1 and newCount == 0) then
+		-- Only force a global logic override when an observer loses its last zone
+		if current == 1 and newCount == 0 then
+			State.logicVersion += 1
+		end
+
 		for groupId, observers in State.groupToObservers do
 			if not observers[observerId] then
 				continue

src/Core/Scheduler.luau

@@ -460,6 +460,10 @@ function Scheduler.update(dt: number)
 					ctx_candidateIndex[observerId] = nil
 					ctx_candidateList[i] = nil
 
+					if not observerTrackingEntities[observerId] then
+						continue
+					end
+
 					if priority < ctx_highestWin then
 						continue
 					end

src/init.luau

@@ -1,5 +1,5 @@
 --!strict
---v1.4.4 • LDGerrits
+--v1.4.5 • LDGerrits
 --[=[
 	@class QuickZone
 
@@ -169,17 +169,22 @@ end
 	@return QuickZone
 ]=]
 function QuickZone:setReference(entity: Entity, reference: any?): QuickZone
+	local oldReference = entityToReference[entity]
+
 	if reference == nil then
-		local oldReference = entityToReference[entity]
-		if oldReference then
-			referenceToEntity[oldReference] = nil
+		if not (typeof(oldReference) == 'Instance' and oldReference:IsA('Player')) then
+			if oldReference then
+				referenceToEntity[oldReference] = nil
+			end
+			entityToReference[entity] = nil
 		end
-		entityToReference[entity] = nil
 		return self
 	end
 
-	entityToReference[entity] = reference
-	referenceToEntity[reference] = entity
+	if not (typeof(reference) == 'Instance' and reference:IsA('Player')) then
+		entityToReference[entity] = reference
+		referenceToEntity[reference] = entity
+	end
 
 	return self
 end

tests/Specifications/2-Zone.spec.luau

@@ -616,13 +616,17 @@ return function(Tiniest: Tiniest)
 		end)
 
 		Test('Rewires autoSync to the new reference, disconnecting from the old one.', function()
-			local size = Vector3.one * 20
+			local size = Vector3.one * 50
 			local partA = CreatePart({ Size = Vector3.one * 10 })
-			local partB = CreatePart({ Size = Vector3.one * 10 })
+			local partB = CreatePart({ Size = Vector3.one * 25 })
 			local zone = Zone.fromPart(partA, { autoSync = true })
 
+			Expect(zone:getSize()).is(Vector3.one * 10)
+
 			zone:setReference(partB)
 
+			Expect(zone:getSize()).is(Vector3.one * 25)
+
 			partB.Size = size
 			task.wait()
 

tests/Specifications/4-Observer.spec.luau

@@ -237,6 +237,32 @@ return function(Tiniest: Tiniest)
 			observer:destroy()
 			zone:destroy()
 		end)
+
+		Test('Detaching the only attached zone fires onExit for its entities.', function()
+			local exits = 0
+			local part = CreatePart()
+			local zone = Zone.new({ cframe = CFrame.identity, size = Vector3.one * 10 })
+			local group = Group.new({ entities = { part } })
+			local observer = Observer.new({ zones = { zone }, groups = { group }, safety = false })
+
+			observer:onExit(function()
+				exits += 1
+			end)
+			QuickZone:update(1 / 10)
+
+			Expect(exits).is(0)
+
+			observer:detach(zone)
+			QuickZone:update(1 / 10)
+
+			Expect(exits).is(1)
+			Expect(#observer:getEntitiesInside()).is(0)
+
+			observer:destroy()
+			group:destroy()
+			zone:destroy()
+			part:Destroy()
+		end)
 	end)
 
 	Describe('Observer:observe', function()
@@ -1067,7 +1093,7 @@ return function(Tiniest: Tiniest)
 			local part = CreatePart({ CFrame = CFrame.new(3, 0, 0) })
 			local zone = Zone.new({ cframe = CFrame.identity, size = Vector3.one * 10 })
 			local group = Group.new({ entities = { part } })
-			local observer = Observer.new({ zones = { zone }, groups = { group }, precision = 0.1, safety = false })
+			local observer = Observer.new({ zones = { zone }, groups = { group }, precision = 0.5, safety = false })
 
 			observer:onExit(function()
 				exits += 1
@@ -1086,6 +1112,34 @@ return function(Tiniest: Tiniest)
 			zone:destroy()
 			part:Destroy()
 		end)
+
+		Test('The tighter precision applies when two observers share an entity.', function()
+			local laxExits, tightExits = 0, 0
+			local part = CreatePart({ CFrame = CFrame.new(3, 0, 0) })
+			local zone = Zone.new({ cframe = CFrame.identity, size = Vector3.one * 10 })
+			local group = Group.new({ entities = { part } })
+			local lax = Observer.new({ zones = { zone }, groups = { group }, precision = 5, safety = false })
+			local tight = Observer.new({ zones = { zone }, groups = { group }, precision = 0.5, safety = false })
+
+			lax:onExit(function()
+				laxExits += 1
+			end)
+			tight:onExit(function()
+				tightExits += 1
+			end)
+			QuickZone:update(1 / 10)
+			part.CFrame = CFrame.new(5.5, 0, 0)
+			QuickZone:update(1 / 10)
+
+			Expect(laxExits).is(1)
+			Expect(tightExits).is(1)
+
+			tight:destroy()
+			lax:destroy()
+			group:destroy()
+			zone:destroy()
+			part:Destroy()
+		end)
 	end)
 
 	Describe('Observer:isPointInside', function()
@@ -1166,12 +1220,14 @@ return function(Tiniest: Tiniest)
 			group = Group.new({ entities = { entity } })
 			observer = Observer.new({ zones = { zones }, groups = { group } })
 			task.wait()
+			QuickZone:update(1 / 10)
 
 			Expect(#observer:getEntitiesInside()).is(1)
 
 			-- Streaming out
 			part.Parent = nil
 			task.wait()
+			QuickZone:update(1 / 10)
 
 			Expect(#observer:getEntitiesInside()).is(0)
 
@@ -1587,5 +1643,26 @@ return function(Tiniest: Tiniest)
 			zone:destroy()
 			part:Destroy()
 		end)
+
+		Test('Observer keeps tracking the shared entity after destroying another observer.', function()
+			local part = CreatePart()
+			local zone = Zone.new({ cframe = CFrame.identity, size = Vector3.one * 10 })
+			local group = Group.new({ entities = { part } })
+			local observerA = Observer.new({ zones = { zone }, groups = { group }, safety = false })
+			local observerB = Observer.new({ zones = { zone }, groups = { group }, safety = false })
+
+			observerA:onEnter(function()
+				observerB:destroy()
+			end)
+			QuickZone:update(1 / 10)
+
+			Expect(observerA:getEntitiesInside()).has_value(part)
+			Expect(observerA:getZoneOfEntity(part)).is(zone)
+
+			observerA:destroy()
+			group:destroy()
+			zone:destroy()
+			part:Destroy()
+		end)
 	end)
 end

tests/Util.luau

@@ -6,14 +6,13 @@ type InstanceTree = {
 }
 
 local PART_DEFAULTS: { [string]: any } = {
-  Transparency = 1,
+	Transparency = 1,
 	Anchored = true,
 	CanCollide = false,
 	CanQuery = false,
 	CanTouch = false,
 	AudioCanCollide = false,
 	EnableFluidForces = false,
-	Parent = workspace,
 }
 
 local Util = {}
@@ -25,6 +24,7 @@ function Util.create<C>(tree: InstanceTree): C
 		for property, value in PART_DEFAULTS do
 			object[property] = value
 		end
+		object.Parent = workspace
 	end
 	if tree.properties ~= nil then
 		for property, value in tree.properties do
@@ -49,11 +49,9 @@ end
 
 function Util.createParts(count: number, properties: { [string]: any }?): { BasePart }
 	local parts: { BasePart } = table.create(count)
-
 	for i = 1, count do
 		table.insert(parts, Util.createPart(properties))
 	end
-	
 	return parts
 end