@quenty/streamingutils 10.20.0 → 10.22.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [10.22.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/streamingutils@10.21.0...@quenty/streamingutils@10.22.0) (2026-07-22)
+
+**Note:** Version bump only for package @quenty/streamingutils
+
+# [10.21.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/streamingutils@10.20.0...@quenty/streamingutils@10.21.0) (2026-07-20)
+
+### Features
+
+- Integrate teleport data service directly into save slots for cross-game continuation ([ffa7496](https://github.com/Quenty/NevermoreEngine/commit/ffa7496047b80a82623440221c019fdfe09e31ea))
+- **streamingutils:** add StreamingCinematicsService for camera streaming focus ([4853cd6](https://github.com/Quenty/NevermoreEngine/commit/4853cd6d64c9ca32ea454ca7ebe69697c0baba1e))
+
 # [10.20.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/streamingutils@10.19.0...@quenty/streamingutils@10.20.0) (2026-07-18)
 
 **Note:** Version bump only for package @quenty/streamingutils

package/deploy.nevermore.json

@@ -0,0 +1,10 @@
+{
+  "targets": {
+    "test": {
+      "universeId": 9716264427,
+      "placeId": 93308475016118,
+      "project": "test/default.project.json",
+      "scriptTemplate": "test/scripts/Server/ServerMain.server.lua"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/streamingutils",
-  "version": "10.20.0",
+  "version": "10.22.0",
   "description": "Provides utilities for working with Roblox's streaming system",
   "keywords": [
     "Roblox",
@@ -29,11 +29,18 @@
     "Quenty"
   ],
   "dependencies": {
+    "@quenty/instanceutils": "13.32.0",
     "@quenty/loader": "10.11.0",
-    "@quenty/promise": "10.20.0"
+    "@quenty/maid": "3.10.0",
+    "@quenty/nevermore-test-runner": "1.4.0",
+    "@quenty/promise": "10.20.0",
+    "@quenty/remoting": "12.35.0",
+    "@quenty/rx": "13.30.0",
+    "@quenty/servicebag": "11.19.0",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "647acfad93dca41c38f59cda247d2bfc0fff36d4"
+  "gitHead": "93f15b200c0f465a0b5304fcf05f5cfe7fdcbd1d"
 }

package/src/Client/StreamingCinematicsServiceClient.lua

@@ -0,0 +1,122 @@
+--!strict
+--[=[
+	Client half of the streaming-cinematics system. While a cinematic camera is active, feeds the
+	camera position up to the [StreamingCinematicsService] (throttled) so the server can stream world
+	content in around it -- covering the cases where the player has no character, or the character is
+	far from the camera.
+
+	@client
+	@class StreamingCinematicsServiceClient
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local Workspace = game:GetService("Workspace")
+
+local Maid = require("Maid")
+local Observable = require("Observable")
+local Remoting = require("Remoting")
+local Rx = require("Rx")
+local RxInstanceUtils = require("RxInstanceUtils")
+local ServiceBag = require("ServiceBag")
+
+-- 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.
+local SEND_RATE_SECONDS = 0.25
+
+local StreamingCinematicsServiceClient = {}
+StreamingCinematicsServiceClient.ServiceName = "StreamingCinematicsServiceClient"
+
+export type StreamingCinematicsServiceClient = typeof(setmetatable(
+	{} :: {
+		_serviceBag: ServiceBag.ServiceBag,
+		_maid: Maid.Maid,
+		_remoting: any,
+	},
+	{} :: typeof({ __index = StreamingCinematicsServiceClient })
+))
+
+function StreamingCinematicsServiceClient.Init(
+	self: StreamingCinematicsServiceClient,
+	serviceBag: ServiceBag.ServiceBag
+): ()
+	assert(not (self :: any)._remoting, "Already initialized")
+	self._serviceBag = assert(serviceBag, "No serviceBag")
+	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)
+end
+
+--[=[
+	Observes the current camera's position, following [Workspace.CurrentCamera] as it changes.
+	@return Observable<Vector3?>
+]=]
+function StreamingCinematicsServiceClient.ObserveCurrentCameraPosition(
+	_self: StreamingCinematicsServiceClient
+): 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 })
+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].
+
+	@param observePosition Observable<Vector3?>? -- Optional override
+	@return function -- Cleanup; clears the focus when called
+]=]
+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
+end
+
+function StreamingCinematicsServiceClient.Destroy(self: StreamingCinematicsServiceClient): ()
+	self._maid:DoCleaning()
+end
+
+return StreamingCinematicsServiceClient

package/src/Server/StreamingCinematicsService.lua

@@ -0,0 +1,91 @@
+--!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.
+
+	@server
+	@class StreamingCinematicsService
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Players = game:GetService("Players")
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Maid = require("Maid")
+local Remoting = require("Remoting")
+local ReplicationFocusTracker = require("ReplicationFocusTracker")
+
+local StreamingCinematicsService = {}
+StreamingCinematicsService.ServiceName = "StreamingCinematicsService"
+
+export type StreamingCinematicsService = typeof(setmetatable(
+	{} :: {
+		_maid: Maid.Maid,
+		_trackers: { [Player]: ReplicationFocusTracker.ReplicationFocusTracker },
+		_remoting: any,
+	},
+	{} :: typeof({ __index = StreamingCinematicsService })
+))
+
+function StreamingCinematicsService.Init(self: StreamingCinematicsService): ()
+	assert(not (self :: any)._remoting, "Already initialized")
+	self._maid = Maid.new()
+
+	self._trackers = {}
+
+	self._remoting = self._maid:Add(Remoting.Server.new(ReplicatedStorage, "StreamingCinematics"))
+	self._remoting:DeclareEvent("SetFocus")
+
+	self._maid:GiveTask(self._remoting.SetFocus:Connect(function(player: Player, position: Vector3?)
+		self:_setFocus(player, position)
+	end))
+
+	self._maid:GiveTask(Players.PlayerRemoving:Connect(function(player: Player)
+		self:_clearFocus(player)
+	end))
+end
+
+function StreamingCinematicsService._setFocus(self: StreamingCinematicsService, player: Player, position: Vector3?): ()
+	if position == nil then
+		self:_clearFocus(player)
+		return
+	end
+
+	if typeof(position) ~= "Vector3" then
+		return
+	end
+
+	-- Never create a tracker for a player who is already leaving/gone; PlayerRemoving owns their
+	-- cleanup, so a late remote must not resurrect per-player state.
+	if not player:IsDescendantOf(game) then
+		return
+	end
+
+	local tracker = self._trackers[player]
+	if not tracker then
+		tracker = ReplicationFocusTracker.new(player)
+		self._trackers[player] = tracker
+	end
+
+	tracker:SetPosition(position)
+end
+
+function StreamingCinematicsService._clearFocus(self: StreamingCinematicsService, player: Player): ()
+	local tracker = self._trackers[player]
+	if tracker then
+		tracker:Destroy()
+		self._trackers[player] = nil
+	end
+end
+
+function StreamingCinematicsService.Destroy(self: StreamingCinematicsService): ()
+	for player in self._trackers do
+		self:_clearFocus(player)
+	end
+	self._maid:DoCleaning()
+end
+
+return StreamingCinematicsService

package/src/Shared/ReplicationFocusTracker.lua

@@ -0,0 +1,87 @@
+--!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.
+
+	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].
+
+	@class ReplicationFocusTracker
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Workspace = game:GetService("Workspace")
+
+local Maid = require("Maid")
+
+local FOCUS_PART_NAME = "StreamingCinematicFocus"
+
+local ReplicationFocusTracker = {}
+ReplicationFocusTracker.ClassName = "ReplicationFocusTracker"
+ReplicationFocusTracker.__index = ReplicationFocusTracker
+
+export type ReplicationFocusTracker = typeof(setmetatable(
+	{} :: {
+		_subject: Player,
+		_maid: Maid.Maid,
+		_part: BasePart?,
+	},
+	{} :: typeof({ __index = ReplicationFocusTracker })
+))
+
+function ReplicationFocusTracker.new(subject: Player): ReplicationFocusTracker
+	local self: ReplicationFocusTracker = setmetatable({} :: any, ReplicationFocusTracker)
+
+	self._subject = assert(subject, "No subject")
+	self._maid = Maid.new()
+
+	return self
+end
+
+--[=[
+	Moves the focus to `position`, creating and assigning the part on first call.
+	@param position Vector3
+]=]
+function ReplicationFocusTracker.SetPosition(self: ReplicationFocusTracker, position: Vector3): ()
+	assert(typeof(position) == "Vector3", "Bad position")
+
+	local existing = self._part
+	if existing then
+		existing.Position = position
+		return
+	end
+
+	local part = Instance.new("Part")
+	part.Name = FOCUS_PART_NAME
+	part.Anchored = true
+	part.CanCollide = false
+	part.CanQuery = false
+	part.CanTouch = false
+	part.Transparency = 1
+	part.Size = Vector3.one
+	part.Archivable = false
+	part.Position = position
+	part.Parent = Workspace.Terrain
+
+	self._part = part
+	self._maid:GiveTask(part)
+	self._subject.ReplicationFocus = part
+end
+
+--[=[
+	Whether a focus part currently exists (i.e. [ReplicationFocusTracker:SetPosition] has run).
+	@return boolean
+]=]
+function ReplicationFocusTracker.IsActive(self: ReplicationFocusTracker): boolean
+	return self._part ~= nil
+end
+
+function ReplicationFocusTracker.Destroy(self: ReplicationFocusTracker): ()
+	self._subject.ReplicationFocus = nil
+	self._maid:DoCleaning()
+	self._part = nil
+end
+
+return ReplicationFocusTracker

package/src/Shared/ReplicationFocusTracker.spec.lua

@@ -0,0 +1,84 @@
+--!strict
+--[[
+	@class ReplicationFocusTracker.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local ReplicationFocusTracker = require("ReplicationFocusTracker")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+type FakeSubject = { ReplicationFocus: BasePart? }
+
+describe("ReplicationFocusTracker", function()
+	it("creates a hidden part and assigns it as the subject's ReplicationFocus", function()
+		local subject: FakeSubject = {}
+		local tracker = ReplicationFocusTracker.new(subject :: any)
+
+		tracker:SetPosition(Vector3.new(1, 2, 3))
+
+		local part = subject.ReplicationFocus
+		assert(part, "expected a focus part")
+		expect(part:IsA("BasePart")).toEqual(true)
+		expect(part.Position).toEqual(Vector3.new(1, 2, 3))
+		expect(part.Anchored).toEqual(true)
+		expect(part.CanCollide).toEqual(false)
+
+		tracker:Destroy()
+	end)
+
+	it("reuses the same part across position updates", function()
+		local subject: FakeSubject = {}
+		local tracker = ReplicationFocusTracker.new(subject :: any)
+
+		tracker:SetPosition(Vector3.new(1, 0, 0))
+		local first = subject.ReplicationFocus
+		assert(first, "expected a focus part")
+
+		tracker:SetPosition(Vector3.new(5, 0, 0))
+
+		expect(subject.ReplicationFocus).toBe(first)
+		expect(first.Position).toEqual(Vector3.new(5, 0, 0))
+
+		tracker:Destroy()
+	end)
+
+	it("reports active state", function()
+		local subject: FakeSubject = {}
+		local tracker = ReplicationFocusTracker.new(subject :: any)
+
+		expect(tracker:IsActive()).toEqual(false)
+		tracker:SetPosition(Vector3.new(0, 0, 0))
+		expect(tracker:IsActive()).toEqual(true)
+
+		tracker:Destroy()
+	end)
+
+	it("clears the ReplicationFocus and destroys the part on Destroy", function()
+		local subject: FakeSubject = {}
+		local tracker = ReplicationFocusTracker.new(subject :: any)
+
+		tracker:SetPosition(Vector3.new(1, 2, 3))
+		local part = subject.ReplicationFocus
+		assert(part, "expected a focus part")
+
+		tracker:Destroy()
+
+		expect(subject.ReplicationFocus).toEqual(nil)
+		-- 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 tracker = ReplicationFocusTracker.new(subject :: any)
+
+		tracker:Destroy()
+
+		expect(subject.ReplicationFocus).toEqual(nil)
+	end)
+end)

package/src/jest.config.lua

@@ -0,0 +1,3 @@
+return {
+	testMatch = { "**/*.spec" },
+}

package/test/default.project.json

@@ -0,0 +1,17 @@
+{
+  "name": "StreamingUtilsTest",
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "$properties": {
+        "LoadStringEnabled": true
+      },
+      "streamingutils": {
+        "$path": ".."
+      },
+      "Script": {
+        "$path": "scripts/Server"
+      }
+    }
+  }
+}

package/test/scripts/Server/ServerMain.server.lua

@@ -0,0 +1,15 @@
+--!nonstrict
+--[[
+	@class ServerMain
+]]
+local ServerScriptService = game:GetService("ServerScriptService")
+
+local root = ServerScriptService.streamingutils
+local loader = root:FindFirstChild("LoaderUtils", true).Parent
+local require = require(loader).bootstrapGame(root)
+
+local NevermoreTestRunnerUtils = require("NevermoreTestRunnerUtils")
+
+if NevermoreTestRunnerUtils.runTestsIfNeededAsync(root) then
+	return
+end