@quenty/streamingutils 10.26.0 → 10.27.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [10.27.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/streamingutils@10.26.0...@quenty/streamingutils@10.27.0) (2026-07-25)
+
+### Bug Fixes
+
+- Streaming cinematic allows latest focus to work (for now) ([528cb41](https://github.com/Quenty/NevermoreEngine/commit/528cb41a8c4f233d0903faf66c67dd6e71450cea))
+
+### Features
+
+- Use ReplicationFocus instead of overwriting the focus ([daaf82f](https://github.com/Quenty/NevermoreEngine/commit/daaf82f22862570e1eaafd48188c8ed067005ef9))
+
 # [10.26.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/streamingutils@10.25.0...@quenty/streamingutils@10.26.0) (2026-07-24)
 
 **Note:** Version bump only for package @quenty/streamingutils

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/streamingutils",
-  "version": "10.26.0",
+  "version": "10.27.0",
   "description": "Provides utilities for working with Roblox's streaming system",
   "keywords": [
     "Roblox",
@@ -29,19 +29,20 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/instanceutils": "13.34.0",
+    "@quenty/instanceutils": "13.35.0",
     "@quenty/loader": "10.11.0",
     "@quenty/maid": "3.11.0",
     "@quenty/nevermore-test-runner": "1.5.0",
-    "@quenty/playermock": "1.4.0",
-    "@quenty/promise": "10.22.0",
-    "@quenty/remoting": "12.39.0",
-    "@quenty/rx": "13.32.0",
+    "@quenty/playermock": "1.5.0",
+    "@quenty/promise": "10.23.0",
+    "@quenty/remoting": "12.40.0",
+    "@quenty/rx": "13.33.0",
     "@quenty/servicebag": "11.20.0",
+    "@quenty/statestack": "14.37.0",
     "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "04f569a7981517ae20394ec3ca3923c421a93d43"
+  "gitHead": "8677b70e89a1ef1585f8492b0638ec4a29aba8a3"
 }

package/src/Client/StreamingCinematicsServiceClient.lua

@@ -20,6 +20,7 @@ local Remoting = require("Remoting")
 local Rx = require("Rx")
 local RxInstanceUtils = require("RxInstanceUtils")
 local ServiceBag = require("ServiceBag")
+local StateStack = require("StateStack")
 
 -- A handful of updates per second is plenty for streaming; the pan is slow and the streaming radius
 -- dwarfs the per-update movement. leading+trailing so the first and final resting positions both send.
@@ -33,6 +34,7 @@ export type StreamingCinematicsServiceClient = typeof(setmetatable(
 		_serviceBag: ServiceBag.ServiceBag,
 		_maid: Maid.Maid,
 		_remoting: any,
+		_observableStack: StateStack.StateStack<Observable.Observable<Vector3?>?>,
 	},
 	{} :: typeof({ __index = StreamingCinematicsServiceClient })
 ))
@@ -46,15 +48,28 @@ function StreamingCinematicsServiceClient.Init(
 	self._maid = Maid.new()
 
 	self._remoting = self._maid:Add(Remoting.Client.new(ReplicatedStorage, "StreamingCinematics"))
-end
 
---[=[
-	Sends a single focus position to the server (or nil to clear). Low-level; prefer
-	[StreamingCinematicsServiceClient:PushCameraFocus].
-	@param position Vector3?
-]=]
-function StreamingCinematicsServiceClient.SetFocus(self: StreamingCinematicsServiceClient, position: Vector3?): ()
-	self._remoting.SetFocus:FireServer(position)
+	-- The server tracks one focus, but anything cinematic can want to drive it, so pushes stack: the
+	-- newest wins, and popping hands streaming back to whatever was underneath instead of clearing.
+	self._observableStack = self._maid:Add(StateStack.new(nil :: Observable.Observable<Vector3?>?))
+
+	-- Sending is the service's job rather than each caller's. A caller that outlives its own cleanup
+	-- can no longer fire at a torn-down remoting, and the throttle bounds the whole client instead of
+	-- being reapplied per push.
+	self._maid:GiveTask(self._observableStack
+		:Observe()
+		:Pipe({
+			Rx.switchMap(function(observePosition: Observable.Observable<Vector3?>?): any
+				return observePosition or Rx.of(nil)
+			end) :: any,
+			Rx.throttleTime(SEND_RATE_SECONDS, {
+				leading = true,
+				trailing = true,
+			}) :: any,
+		})
+		:Subscribe(function(position: Vector3?)
+			self._remoting.SetFocus:FireServer(position)
+		end))
 end
 
 --[=[
@@ -66,53 +81,32 @@ function StreamingCinematicsServiceClient.ObserveCurrentCameraPosition(
 ): Observable.Observable<Vector3?>
 	local observeCamera: any = RxInstanceUtils.observeProperty(Workspace, "CurrentCamera")
 
-	local switchToCFrame: any = Rx.switchMap(function(camera): any
-		if not camera then
-			return Rx.of(nil)
-		end
-		return RxInstanceUtils.observeProperty(camera, "CFrame")
-	end)
-	local toPosition: any = Rx.map(function(cframe): Vector3?
-		return if cframe then cframe.Position else nil
-	end)
-
-	return observeCamera:Pipe({ switchToCFrame, toPosition })
+	return observeCamera:Pipe({
+		Rx.switchMap(function(camera): any
+			if not camera then
+				return Rx.of(nil)
+			end
+			return RxInstanceUtils.observeProperty(camera, "CFrame")
+		end),
+		Rx.map(function(cframe): Vector3?
+			return if cframe then cframe.Position else nil
+		end),
+	} :: { any })
 end
 
 --[=[
 	Streams world content around a cinematic camera until the returned cleanup runs. Defaults to
 	following the current camera; pass an observable of `Vector3?` to drive the focus explicitly.
-	Sends are throttled to [SEND_RATE_SECONDS].
+	Sends are throttled to [SEND_RATE_SECONDS] across every push.
 
 	@param observePosition Observable<Vector3?>? -- Optional override
-	@return function -- Cleanup; clears the focus when called
+	@return function -- Cleanup; hands the focus back to the push underneath, or clears it
 ]=]
 function StreamingCinematicsServiceClient.PushCameraFocus(
 	self: StreamingCinematicsServiceClient,
 	observePosition: Observable.Observable<Vector3?>?
 ): () -> ()
-	local source: any = observePosition or self:ObserveCurrentCameraPosition()
-
-	local maid = Maid.new()
-
-	maid:GiveTask(source
-		:Pipe({
-			Rx.throttleTime(SEND_RATE_SECONDS, {
-				leading = true,
-				trailing = true,
-			}),
-		})
-		:Subscribe(function(position: Vector3?)
-			self:SetFocus(position)
-		end))
-
-	maid:GiveTask(function()
-		self:SetFocus(nil)
-	end)
-
-	return function()
-		maid:DoCleaning()
-	end
+	return self._observableStack:PushState(observePosition or self:ObserveCurrentCameraPosition())
 end
 
 function StreamingCinematicsServiceClient.Destroy(self: StreamingCinematicsServiceClient): ()

package/src/Server/StreamingCinematicsService.lua

@@ -1,9 +1,9 @@
 --!strict
 --[=[
 	Server half of the streaming-cinematics system. Receives a focus position from a client
-	(who has no character, or whose character is far from a cinematic camera) and points that
-	player's `ReplicationFocus` at it via a [ReplicationFocusTracker], so world content streams
-	in around the cinematic camera. Sending nil clears it.
+	(who has no character, or whose character is far from a cinematic camera) and adds a
+	replication focus there via a [ReplicationFocusTracker], so world content streams in around
+	the cinematic camera. Sending nil clears it.
 
 	@server
 	@class StreamingCinematicsService

package/src/Shared/ReplicationFocusTracker.lua

@@ -1,11 +1,12 @@
 --!strict
 --[=[
-	Keeps a single hidden part positioned at a point and assigned as a [Player]'s
-	`ReplicationFocus`, so Roblox streams world content around that point. Reuses one part
-	across position updates and clears the focus (and destroys the part) on cleanup.
+	Keeps a single hidden part positioned at a point and added as a [Player] replication focus, so
+	Roblox streams world content around that point. Reuses one part across position updates and
+	removes the focus (and destroys the part) on cleanup.
 
-	The subject is duck-typed at runtime -- anything with a settable `ReplicationFocus` -- so tests
-	pass a plain table; the production caller always passes a [Player].
+	The subject is duck-typed at runtime -- anything with `AddReplicationFocus` /
+	`RemoveReplicationFocus` methods -- so tests pass a plain table; the production caller always
+	passes a [Player].
 
 	@class ReplicationFocusTracker
 ]=]
@@ -68,7 +69,7 @@ function ReplicationFocusTracker.SetPosition(self: ReplicationFocusTracker, posi
 
 	self._part = part
 	self._maid:GiveTask(part)
-	self:_writeReplicationFocus(part)
+	self:_addReplicationFocus(part)
 end
 
 --[=[
@@ -80,17 +81,29 @@ function ReplicationFocusTracker.IsActive(self: ReplicationFocusTracker): boolea
 end
 
 function ReplicationFocusTracker.Destroy(self: ReplicationFocusTracker): ()
-	self:_writeReplicationFocus(nil)
+	local part = self._part
+	if part then
+		self:_removeReplicationFocus(part)
+	end
+
 	self._maid:DoCleaning()
 	self._part = nil
 end
 
--- Mock-safe: a PlayerMock's backing Folder has no ReplicationFocus property; write its stand-in.
-function ReplicationFocusTracker._writeReplicationFocus(self: ReplicationFocusTracker, part: BasePart?): ()
+-- Mock-safe: a PlayerMock's backing Folder has no AddReplicationFocus method; call its stand-in.
+function ReplicationFocusTracker._addReplicationFocus(self: ReplicationFocusTracker, part: BasePart): ()
+	if PlayerMock.isMock(self._subject) then
+		PlayerMock.addReplicationFocus(self._subject, part)
+	else
+		self._subject:AddReplicationFocus(part)
+	end
+end
+
+function ReplicationFocusTracker._removeReplicationFocus(self: ReplicationFocusTracker, part: BasePart): ()
 	if PlayerMock.isMock(self._subject) then
-		PlayerMock.write(self._subject, "ReplicationFocus", part)
+		PlayerMock.removeReplicationFocus(self._subject, part)
 	else
-		self._subject.ReplicationFocus = part
+		self._subject:RemoveReplicationFocus(part)
 	end
 end
 

package/src/Shared/ReplicationFocusTracker.spec.lua

@@ -6,22 +6,44 @@
 local require = require(script.Parent.loader).load(script)
 
 local Jest = require("Jest")
+local PlayerMock = require("PlayerMock")
 local ReplicationFocusTracker = require("ReplicationFocusTracker")
 
 local describe = Jest.Globals.describe
 local expect = Jest.Globals.expect
 local it = Jest.Globals.it
 
-type FakeSubject = { ReplicationFocus: BasePart? }
+type FakeSubject = {
+	focuses: { BasePart },
+	AddReplicationFocus: (FakeSubject, BasePart) -> (),
+	RemoveReplicationFocus: (FakeSubject, BasePart) -> (),
+}
+
+local function newFakeSubject(): FakeSubject
+	local focuses: { BasePart } = {}
+
+	return {
+		focuses = focuses,
+		AddReplicationFocus = function(_self, part)
+			table.insert(focuses, part)
+		end,
+		RemoveReplicationFocus = function(_self, part)
+			local index = table.find(focuses, part)
+			if index then
+				table.remove(focuses, index)
+			end
+		end,
+	}
+end
 
 describe("ReplicationFocusTracker", function()
-	it("creates a hidden part and assigns it as the subject's ReplicationFocus", function()
-		local subject: FakeSubject = {}
+	it("creates a hidden part and adds it as a replication focus", function()
+		local subject = newFakeSubject()
 		local tracker = ReplicationFocusTracker.new(subject :: any)
 
 		tracker:SetPosition(Vector3.new(1, 2, 3))
 
-		local part = subject.ReplicationFocus
+		local part = subject.focuses[1]
 		assert(part, "expected a focus part")
 		expect(part:IsA("BasePart")).toEqual(true)
 		expect(part.Position).toEqual(Vector3.new(1, 2, 3))
@@ -32,23 +54,24 @@ describe("ReplicationFocusTracker", function()
 	end)
 
 	it("reuses the same part across position updates", function()
-		local subject: FakeSubject = {}
+		local subject = newFakeSubject()
 		local tracker = ReplicationFocusTracker.new(subject :: any)
 
 		tracker:SetPosition(Vector3.new(1, 0, 0))
-		local first = subject.ReplicationFocus
+		local first = subject.focuses[1]
 		assert(first, "expected a focus part")
 
 		tracker:SetPosition(Vector3.new(5, 0, 0))
 
-		expect(subject.ReplicationFocus).toBe(first)
+		expect(#subject.focuses).toEqual(1)
+		expect(subject.focuses[1]).toBe(first)
 		expect(first.Position).toEqual(Vector3.new(5, 0, 0))
 
 		tracker:Destroy()
 	end)
 
 	it("reports active state", function()
-		local subject: FakeSubject = {}
+		local subject = newFakeSubject()
 		local tracker = ReplicationFocusTracker.new(subject :: any)
 
 		expect(tracker:IsActive()).toEqual(false)
@@ -58,27 +81,44 @@ describe("ReplicationFocusTracker", function()
 		tracker:Destroy()
 	end)
 
-	it("clears the ReplicationFocus and destroys the part on Destroy", function()
-		local subject: FakeSubject = {}
+	it("removes the replication focus and destroys the part on Destroy", function()
+		local subject = newFakeSubject()
 		local tracker = ReplicationFocusTracker.new(subject :: any)
 
 		tracker:SetPosition(Vector3.new(1, 2, 3))
-		local part = subject.ReplicationFocus
+		local part = subject.focuses[1]
 		assert(part, "expected a focus part")
 
 		tracker:Destroy()
 
-		expect(subject.ReplicationFocus).toEqual(nil)
+		expect(#subject.focuses).toEqual(0)
 		-- Destroyed parts are reparented to nil.
 		expect(part.Parent).toEqual(nil)
 	end)
 
 	it("does nothing to a subject that was never positioned", function()
-		local subject: FakeSubject = {}
+		local subject = newFakeSubject()
 		local tracker = ReplicationFocusTracker.new(subject :: any)
 
 		tracker:Destroy()
 
-		expect(subject.ReplicationFocus).toEqual(nil)
+		expect(#subject.focuses).toEqual(0)
+	end)
+
+	it("adds and removes the focus through the PlayerMock seam", function()
+		local player = PlayerMock.new()
+		local tracker = ReplicationFocusTracker.new(player)
+
+		tracker:SetPosition(Vector3.new(1, 2, 3))
+
+		local focuses = PlayerMock.getReplicationFocuses(player)
+		expect(#focuses).toEqual(1)
+		expect(focuses[1].Position).toEqual(Vector3.new(1, 2, 3))
+
+		tracker:Destroy()
+
+		expect(#PlayerMock.getReplicationFocuses(player)).toEqual(0)
+
+		player:Destroy()
 	end)
 end)