@quenty/templateprovider 11.6.0 → 11.7.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [11.7.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/templateprovider@11.6.0...@quenty/templateprovider@11.7.0) (2024-10-06)
+
+
+### Features
+
+* Modernize template provider to new specifications ([7b5df24](https://github.com/Quenty/NevermoreEngine/commit/7b5df24cd0759668d2a5a7d59f1798bca9ddf0f9))
+* Remove TemplateContainerUtils.reparentFromWorkspaceIfNeeded() ([ecf8939](https://github.com/Quenty/NevermoreEngine/commit/ecf893949ba127d97b45c946cf320cf7b987e9eb))
+
+
+
+
+
 # [11.6.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/templateprovider@11.5.0...@quenty/templateprovider@11.6.0) (2024-10-04)
 
 **Note:** Version bump only for package @quenty/templateprovider

package/README.md

@@ -20,28 +20,12 @@ Base of a template retrieval system
 npm install @quenty/templateprovider --save
 ```
 
-## Usage
-Usage is designed to be simple.
+## Deferred replication template behavior
 
-### `TemplateProvider.new(container, replicationParent)`
+1. We want to defer replication of templates until client requests the template
+2. Then we want to send the template to the client via PlayerGui methods
+3. We want to decide whether or not to bother doing this
 
-If `replicationParent` is given then contents loaded from the cloud will be replicated to the replicationParent when on the server.
-
-### `TemplateProvider:Init()`
-
-Initializes the template provider, downloading components and other things needed
-
-### `TemplateProvider:Clone(templateName)`
-
-### `TemplateProvider:Get(templateName)`
-
-### `TemplateProvider:AddContainer(container)`
-
-### `TemplateProvider:RemoveContainer(container)`
-
-### `TemplateProvider:IsAvailable(templateName)`
-
-### `TemplateProvider:GetAll()`
-
-### `TemplateProvider:GetContainers()`
+This will prevent memory usage of unused templates on the client, which happens with the cars and a variety of other game-systems.
 
+We can't store the stuff initially in cameras or in team-create Roblox won't replicate the stuff. But we can move on run-time and hope...

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/templateprovider",
-  "version": "11.6.0",
+  "version": "11.7.0",
   "description": "Base of a template retrieval system",
   "keywords": [
     "Roblox",
@@ -25,15 +25,22 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/baseobject": "^10.6.0",
-    "@quenty/insertserviceutils": "^10.6.0",
-    "@quenty/loader": "^10.6.0",
+    "@quenty/baseobject": "^10.7.0",
+    "@quenty/brio": "^14.9.0",
+    "@quenty/collectionserviceutils": "^8.9.0",
+    "@quenty/ducktype": "^5.7.0",
+    "@quenty/insertserviceutils": "^10.7.0",
+    "@quenty/instanceutils": "^13.9.0",
+    "@quenty/loader": "^10.7.0",
     "@quenty/maid": "^3.4.0",
-    "@quenty/promise": "^10.6.0",
+    "@quenty/observablecollection": "^12.9.0",
+    "@quenty/promise": "^10.7.0",
+    "@quenty/promisemaid": "^5.7.0",
+    "@quenty/rx": "^13.9.0",
     "@quenty/string": "^3.3.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "035abfa088c854a73e1c65b350267eaa17669646"
+  "gitHead": "67c5dbf46f6f45213812f3f117419a5534936a0b"
 }

package/src/Shared/Replication/Util/TemplateReplicationModes.lua

@@ -0,0 +1,13 @@
+--[=[
+	@class TemplateReplicationModes
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Table = require("Table")
+
+return Table.readonly({
+	CLIENT = "client";
+	SERVER = "server";
+	SHARED = "shared";
+})

package/src/Shared/Replication/Util/TemplateReplicationModesUtils.lua

@@ -0,0 +1,26 @@
+--[=[
+	@class TemplateReplicationModesUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local RunService = game:GetService("RunService")
+local TemplateReplicationModes = require("TemplateReplicationModes")
+
+local TemplateReplicationModesUtils = {}
+
+function TemplateReplicationModesUtils.inferReplicationMode()
+	if not RunService:IsRunning() then
+		return TemplateReplicationModes.SHARED
+	end
+
+	if RunService:IsServer() then
+		return TemplateReplicationModes.SERVER
+	elseif RunService:IsClient() then
+		return TemplateReplicationModes.CLIENT
+	else
+		return TemplateReplicationModes.SHARED
+	end
+end
+
+return TemplateReplicationModesUtils

package/src/Shared/TaggedTemplateProvider.lua

@@ -1,59 +1,21 @@
 --[=[
 	Like a template provider, but it also reparents and retrieves tagged objects
+
 	@class TaggedTemplateProvider
 ]=]
 
 local require = require(script.Parent.loader).load(script)
 
-local CollectionService = game:GetService("CollectionService")
-local RunService = game:GetService("RunService")
-
 local TemplateProvider = require("TemplateProvider")
+local RxCollectionServiceUtils = require("RxCollectionServiceUtils")
 
-local TaggedTemplateProvider = setmetatable({}, TemplateProvider)
-TaggedTemplateProvider.ClassName = "TaggedTemplateProvider"
-TaggedTemplateProvider.__index = TaggedTemplateProvider
-
-function TaggedTemplateProvider.new(containerTagName)
-	local self = setmetatable(TemplateProvider.new(), TaggedTemplateProvider)
-
-	assert(type(containerTagName) == "string", "Bad containerTagName")
-
-	-- We prefer a default tag name so test scripts can still read assets for testing
-	self._tagsToInitializeSet = { [containerTagName] = true }
-
-	return self
-end
-
-function TaggedTemplateProvider:Init()
-	assert(not self._maid, "Should not have a maid")
-
-	getmetatable(TaggedTemplateProvider).Init(self)
-
-	assert(self._maid, "Should have a maid")
-
-	for tag, _ in pairs(self._tagsToInitializeSet) do
-		self:AddContainersFromTag(tag)
-	end
-end
-
-function TaggedTemplateProvider:AddContainersFromTag(containerTagName)
-	assert(self._maid, "Not initialized")
-	assert(type(containerTagName) == "string", "Bad containerTagName")
-
-	if RunService:IsRunning() then
-		self._maid:GiveTask(CollectionService:GetInstanceAddedSignal(containerTagName):Connect(function(inst)
-			self:AddContainer(inst)
-		end))
+local TaggedTemplateProvider = {}
 
-		self._maid:GiveTask(CollectionService:GetInstanceRemovedSignal(containerTagName):Connect(function(inst)
-			self:RemoveContainer(inst)
-		end))
-	end
+function TaggedTemplateProvider.new(providerName, tagName)
+	assert(type(providerName) == "string", "bad providerName")
+	assert(type(tagName) == "string", "Bad tagName")
 
-	for _, inst in pairs(CollectionService:GetTagged(containerTagName)) do
-		self:AddContainer(inst)
-	end
+	return TemplateProvider.new(providerName, RxCollectionServiceUtils.observeTaggedBrio(tagName))
 end
 
 return TaggedTemplateProvider

package/src/Shared/TemplateProvider.lua

@@ -1,19 +1,27 @@
 --[=[
-	Base of a template retrieval system. Templates can be retrieved from Roblox, or from the cloud,
-	and then retrieved by name. Folders are ignored, so assets may be organized however you want.
+	Base of a template retrieval system. Templates can be retrieved from Roblox and then retrieved by name. If a folder is used
+	all of their children are also included as templates, which allows for flexible organization by artists.
 
-	Templates can repliate to client if desired.
+	Additionally, you can provide template overrides as the last added template will always be used.
 
 	```lua
-	-- shared/Templates.lua
+	-- shared/CarTemplates.lua
 
-	return TemplateProvider.new(182451181, script) -- Load from Roblox cloud
+	return TemplateProvider.new(script.Name, script) -- Load locally
 	```
 
+	:::tip
+	If the TemplateProvider is initialized on the server, the the templates will be hidden from the client until the
+	client requests them.
+
+	This prevents large amounts of templates from being rendered to the client, taking up memory on the client. This especially
+	affects meshes, but can also affect sounds and other similar templates.
+	:::
+
 	```lua
 	-- Server
 	local serviceBag = ServiceBag.new()
-	local templates = serviceBag:GetService(require("Templates"))
+	local templates = serviceBag:GetService(require("CarTemplates"))
 	serviceBag:Init()
 	serviceBag:Start()
 	```
@@ -21,12 +29,12 @@
 	```lua
 	-- Client
 	local serviceBag = ServiceBag.new()
-	local templates = serviceBag:GetService(require("Templates"))
+	local templates = serviceBag:GetService(require("CarTemplates"))
 	serviceBag:Init()
 	serviceBag:Start()
 
-	templates:PromiseClone("Crate"):Then(function(crate)
-		print("Got crate from the cloud!")
+	templates:PromiseCloneTemplate("CopCar"):Then(function(crate)
+		print("Got crate!")
 	end)
 	```
 
@@ -35,13 +43,27 @@
 
 local require = require(script.Parent.loader).load(script)
 
-local RunService = game:GetService("RunService")
-local StarterGui = game:GetService("StarterGui")
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local HttpService = game:GetService("HttpService")
 
+local Brio = require("Brio")
+local DuckTypeUtils = require("DuckTypeUtils")
 local Maid = require("Maid")
-local String = require("String")
-local InsertServiceUtils = require("InsertServiceUtils")
+local Observable = require("Observable")
+local ObservableCountingMap = require("ObservableCountingMap")
+local ObservableMapList = require("ObservableMapList")
 local Promise = require("Promise")
+local PromiseMaidUtils = require("PromiseMaidUtils")
+local Remoting = require("Remoting")
+local Rx = require("Rx")
+local RxInstanceUtils = require("RxInstanceUtils")
+local String = require("String")
+local TemplateReplicationModes = require("TemplateReplicationModes")
+local TemplateReplicationModesUtils = require("TemplateReplicationModesUtils")
+
+local TOMBSTONE_ID_ATTRIBUTE = "UnreplicatedTemplateId"
+local TOMBSTONE_NAME_POSTFIX_UNLOADED = "_Unloaded"
+local TOMBSTONE_NAME_POSTFIX_LOADED = "_Loaded"
 
 local TemplateProvider = {}
 TemplateProvider.ClassName = "TemplateProvider"
@@ -49,144 +71,220 @@ TemplateProvider.ServiceName = "TemplateProvider"
 TemplateProvider.__index = TemplateProvider
 
 --[=[
-	Constructs a new [TemplateProvider].
-	@param container Instance | table | number -- Value
-	@param replicationParent Instance? -- Place to replicate instances to.
+	@type Template Instance | Observable<Brio<Instance>> | table
+	@within TemplateProvider
 ]=]
-function TemplateProvider.new(container, replicationParent)
-	local self = setmetatable({}, TemplateProvider)
-
-	self._replicationParent = replicationParent
-	self._containersToInitializeSet = {}
-	self._containersToInitializeList = {}
-
-	if typeof(container) == "Instance" or type(container) == "number" then
-		self:_registerContainer(container)
-	elseif typeof(container) == "table" then
-		for _, item in pairs(container) do
-			assert(typeof(item) == "Instance" or type(item) == "number", "Bad item in initialization set")
 
-			self:_registerContainer(item)
+--[=[
+	Constructs a new [TemplateProvider].
 
-			-- For easy debugging/iteration loop
-			if typeof(item) == "Instance"
-				and item:IsDescendantOf(StarterGui)
-				and item:IsA("ScreenGui")
-				and RunService:IsRunning() then
+	@param providerName string
+	@param initialTemplates Template
+]=]
+function TemplateProvider.new(providerName, initialTemplates)
+	assert(type(providerName) == "string", "Bad providerName")
+	local self = setmetatable({}, TemplateProvider)
 
-				item.Enabled = false
-			end
-		end
-	end
+	self.ServiceName = assert(providerName, "No providerName")
+	self._initialTemplates = initialTemplates
 
-	-- Make sure to replicate our parent
-	if self._replicationParent then
-		self:_registerContainer(self._replicationParent)
+	if not (self:_isValidTemplate(self._initialTemplates) or self._initialTemplates == nil) then
+		error(string.format("[TemplateProvider.%s] - Bad initialTemplates of type %s", self.ServiceName, typeof(initialTemplates)))
 	end
 
 	return self
 end
 
-function TemplateProvider:_registerContainer(container)
-	assert(typeof(container) == "Instance" or type(container) == "number", "Bad container")
+--[=[
+	Returns if the value is a template provider
 
-	if not self._containersToInitializeSet[container] then
-		self._containersToInitializeSet[container] = true
-		table.insert(self._containersToInitializeList, container)
-	end
+	@param value any
+	@return boolean
+]=]
+
+function TemplateProvider.isTemplateProvider(value)
+	return DuckTypeUtils.isImplementation(TemplateProvider, value)
 end
 
 --[=[
 	Initializes the container provider. Should be done via [ServiceBag].
-]=]
-function TemplateProvider:Init()
-	assert(not self._initialized, "Already initialized")
 
+	@param serviceBag ServiceBag
+]=]
+function TemplateProvider:Init(serviceBag)
+	assert(not self._serviceBag, "Already initialized")
+	self._serviceBag = assert(serviceBag, "No serviceBag")
 	self._maid = Maid.new()
-	self._initialized = true
-	self._registry = {} -- [name] = rawTemplate
-	self._containersSet = {} -- [parentOrAssetId] = true
 
-	self._promises = {} -- [name]  = Promise
+	self._replicationMode = TemplateReplicationModesUtils.inferReplicationMode()
 
-	for _, container in pairs(self._containersToInitializeList) do
-		self:AddContainer(container)
-	end
+	-- There can be multiple templates for a given name
+	self._templateMapList = self._maid:Add(ObservableMapList.new())
+	self._unreplicatedTemplateMapList = self._maid:Add(ObservableMapList.new())
+
+	self._containerRootCountingMap = self._maid:Add(ObservableCountingMap.new())
+	self._pendingTemplatePromises = {} -- [templateName] = Promise
+
+	self:_setupTemplateCache()
 end
 
---[=[
-	Promises to clone the template as soon as it exists.
-	@param templateName string
-	@return Promise<Instance>
-]=]
-function TemplateProvider:PromiseClone(templateName)
-	assert(type(templateName) == "string", "templateName must be a string")
+function TemplateProvider:_setupTemplateCache()
+	if self._replicationMode == TemplateReplicationModes.SERVER then
+		self._tombstoneLookup = {}
+		self._remoting = self._maid:Add(Remoting.Server.new(ReplicatedStorage, self.ServiceName .. "TemplateProvider"))
+
+		-- TODO: Maybe de-duplicate and use a centralized service
+		self._maid:GiveTask(self._remoting.ReplicateTemplate:Bind(function(player, tombstoneId)
+			assert(type(tombstoneId) == "string", "Bad tombstoneId")
+			assert(self._tombstoneLookup[tombstoneId], "Not a valid tombstone")
+
+			-- Stuff doesn't replicate in the PlayerGui
+			local playerGui = player:FindFirstChildWhichIsA("PlayerGui")
+			if not playerGui then
+				return Promise.rejected("No playerGui")
+			end
+
+			-- Just group stuff to simplify things
+			local replicationParent = playerGui:FindFirstChild("TemplateProviderReplication")
+			if not replicationParent then
+				replicationParent = Instance.new("Folder")
+				replicationParent.Name = "TemplateProviderReplication"
+				replicationParent.Archivable = false
+				replicationParent.Parent = playerGui
+			end
+
+			local copy = self._tombstoneLookup[tombstoneId]:Clone()
+			copy.Parent = playerGui
+
+			task.delay(0.1, function()
+				copy:Remove()
+			end)
 
-	self:_verifyInit()
+			return copy
+		end))
+	elseif self._replicationMode == TemplateReplicationModes.CLIENT then
+		self._pendingTombstoneRequests = {}
 
-	local template = self._registry[templateName]
-	if template then
-		return Promise.resolved(self:Clone(templateName))
+		self._remoting = self._maid:Add(Remoting.Client.new(ReplicatedStorage, self.ServiceName .. "TemplateProvider"))
 	end
 
-	if not self._promises[templateName] then
-		local promise = Promise.new()
-		self._promises[templateName] = promise
+	if self._initialTemplates then
+		self._maid:GiveTask(self:AddTemplates(self._initialTemplates))
+	end
 
-		-- Make sure to clean up the promise afterwards
-		self._maid[promise] = promise
-		promise:Then(function()
-			self._maid[promise] = nil
-		end)
+	-- Recursively adds roots, but also de-duplicates them as necessary
+	self._maid:GiveTask(self._containerRootCountingMap:ObserveKeysBrio():Subscribe(function(containerBrio)
+		if containerBrio:IsDead() then
+			return
+		end
+
+		local containerMaid, container = containerBrio:ToMaidAndValue()
+		self:_handleContainer(containerMaid,  container)
+	end))
+end
+
+function TemplateProvider:_handleContainer(containerMaid, container)
+	if self._replicationMode == TemplateReplicationModes.SERVER
+		and not container:IsA("Camera")
+		and not container:FindFirstAncestorWhichIsA("Camera") then
+		-- Prevent replication to client immediately
 
-		task.delay(5, function()
-			if promise:IsPending() then
-				warn(string.format("[TemplateProvider.PromiseClone] - May fail to replicate template %q from cloud. %s", templateName, self:_getReplicationHint()))
+		local camera = containerMaid:Add(Instance.new("Camera"))
+		camera.Name = "PreventReplication"
+		camera.Parent = container
+
+		local function handleChild(child)
+			if child == camera then
+				return
 			end
-		end)
+			if child:GetAttribute(TOMBSTONE_ID_ATTRIBUTE) then
+				return
+			end
+
+			child.Parent = camera
+		end
+
+		containerMaid:GiveTask(container.ChildAdded:Connect(handleChild))
+
+		for _, child in pairs(container:GetChildren()) do
+			handleChild(child)
+		end
+
+		self:_replicateTombstones(containerMaid, camera, container)
+
+		return
 	end
 
-	return self._promises[templateName]
-		:Then(function()
-			-- Get a new copy
-			return self:Clone(templateName)
-		end)
+	containerMaid:GiveTask(RxInstanceUtils.observeChildrenBrio(container):Subscribe(function(brio)
+		if brio:IsDead() then
+			return
+		end
+
+		local maid, child = brio:ToMaidAndValue()
+		self:_addInstanceTemplate(maid, child)
+	end))
 end
 
-function TemplateProvider:_getReplicationHint()
-	local hint = ""
+function TemplateProvider:_replicateTombstones(topMaid, unreplicatedParent, replicatedParent)
+	assert(self._replicationMode == TemplateReplicationModes.SERVER, "Only should be invoked on server")
 
-	if RunService:IsClient() then
-		hint = "Make sure the template provider is initialized on the server."
-	end
+	-- Tombstone each child so the client knows what is replicated
+	topMaid:GiveTask(RxInstanceUtils.observeChildrenBrio(unreplicatedParent):Subscribe(function(brio)
+		if brio:IsDead() then
+			return
+		end
+
+		local maid, child = brio:ToMaidAndValue()
+		self:_addInstanceTemplate(maid, child)
+
+		local tombstoneId = HttpService:GenerateGUID(false)
+
+		-- Tell the client something exists here
+		local tombstone = maid:Add(Instance.new("Folder"))
+		tombstone.Name = child.Name .. TOMBSTONE_NAME_POSTFIX_UNLOADED
+		tombstone:SetAttribute(TOMBSTONE_ID_ATTRIBUTE, tombstoneId)
+
+		-- Recursively replicate other tombstones
+		if self:_shouldAddChildrenAsTemplates(child) then
+			self:_replicateTombstones(maid, child, tombstone)
+		end
+
+		self._tombstoneLookup[tombstoneId] = child
+
+		maid:GiveTask(function()
+			self._tombstoneLookup[tombstoneId] = nil
+		end)
 
-	return hint
+		tombstone.Parent = replicatedParent
+	end))
 end
 
 --[=[
-	Clones the template.
-
-	:::info
-	If the template name has a prefix of "Template" then it will remove it on the cloned instance.
-	:::
+	Observes the given template by name
 
 	@param templateName string
-	@return Instance?
+	@return Observable<Instance>
 ]=]
-function TemplateProvider:Clone(templateName)
+function TemplateProvider:ObserveTemplate(templateName)
 	assert(type(templateName) == "string", "templateName must be a string")
 
-	self:_verifyInit()
+	return self._templateMapList:ObserveList(templateName):Pipe({
+		Rx.switchMap(function(list)
+			if not list then
+				return Rx.of(nil);
+			end
 
-	local template = self._registry[templateName]
-	if not template then
-		error(string.format("[TemplateProvider.Clone] - Cannot provide %q", tostring(templateName)))
-		return nil
-	end
+			return list:ObserveAtIndex(-1)
+		end);
+	})
+end
 
-	local newItem = template:Clone()
-	newItem.Name = String.removePostfix(templateName, "Template")
-	return newItem
+function TemplateProvider:ObserveTemplateNamesBrio()
+	return self._templateMapList:ObserveKeysBrio()
+end
+
+function TemplateProvider:ObserveUnreplicatedTemplateNamesBrio()
+	return self._unreplicatedTemplateMapList:ObserveKeysBrio()
 end
 
 --[=[
@@ -195,197 +293,330 @@ end
 	@param templateName string
 	@return Instance?
 ]=]
-function TemplateProvider:Get(templateName)
+function TemplateProvider:GetTemplate(templateName)
 	assert(type(templateName) == "string", "templateName must be a string")
-	self:_verifyInit()
 
-	return self._registry[templateName]
+	return self._templateMapList:GetItemForKeyAtIndex(templateName, -1)
 end
 
 --[=[
-	Adds a new container to the provider for provision of assets.
+	Promises to clone the template as soon as it exists
 
-	@param container Instance | number
-]=]
-function TemplateProvider:AddContainer(container)
-	assert(typeof(container) == "Instance" or type(container) == "number", "Bad container")
-	self:_verifyInit()
-
-	if not self._containersSet[container] then
-		self._containersSet[container] = true
-		if type(container) == "number" then
-			self._maid[container] = self:_loadCloudAsset(container)
-		elseif typeof(container) == "Instance" then
-			self._maid[container] = self:_loadFolder(container)
-		else
-			error("Unknown container type to load")
-		end
-	end
-end
-
---[=[
-	Removes a container from the provisioning set.
-
-	@param container Instance | number
+	@param templateName string
+	@return Promise<Instance>
 ]=]
-function TemplateProvider:RemoveContainer(container)
-	assert(typeof(container) == "Instance", "Bad container")
-	self:_verifyInit()
+function TemplateProvider:PromiseCloneTemplate(templateName)
+	assert(type(templateName) == "string", "templateName must be a string")
 
-	self._containersSet[container] = nil
-	self._maid[container] = nil
+	return self:PromiseTemplate(templateName)
+		:Then(function(template)
+			return self:_cloneTemplate(template)
+		end)
 end
 
 --[=[
-	Returns whether or not a template is registered at the time
+	Promise to resolve the raw template as soon as it exists
+
 	@param templateName string
-	@return boolean
+	@return Promise<Instance>
 ]=]
-function TemplateProvider:IsAvailable(templateName)
+function TemplateProvider:PromiseTemplate(templateName)
 	assert(type(templateName) == "string", "templateName must be a string")
-	self:_verifyInit()
 
-	return self._registry[templateName] ~= nil
+	local foundTemplate = self._templateMapList:GetItemForKeyAtIndex(templateName, -1)
+	if foundTemplate then
+		return Promise.resolved(foundTemplate)
+	end
+
+	if self._pendingTemplatePromises[templateName] then
+		return self._pendingTemplatePromises[templateName]
+	end
+
+	local promiseTemplate = Promise.new()
+
+	-- Observe thet template
+	PromiseMaidUtils.whilePromise(promiseTemplate, function(topMaid)
+		topMaid:GiveTask(self:ObserveTemplate(templateName):Subscribe(function(template)
+			if template then
+				promiseTemplate:Resolve(template)
+			end
+		end))
+
+		if self._replicationMode == TemplateReplicationModes.SERVER then
+			-- There's a chance an external process will stream in our template
+
+			topMaid:GiveTask(task.delay(5, function()
+				warn(string.format("[TemplateProvider.%s.PromiseTemplate] - Missing template %q", self.ServiceName, templateName))
+			end))
+		elseif self._replicationMode == TemplateReplicationModes.CLIENT then
+			-- Replicate from the unfound area
+			topMaid:GiveTask(self._unreplicatedTemplateMapList:ObserveAtListIndexBrio(templateName, -1):Subscribe(function(brio)
+				if brio:IsDead() then
+					return
+				end
+
+				local maid, templateTombstone = brio:ToMaidAndValue()
+
+				local originalName = templateTombstone.Name
+
+				maid:GivePromise(self:_promiseReplicateTemplateFromTombstone(templateTombstone))
+					:Then(function(template)
+						-- Cache the template here which then loads it into the known templates naturally
+						templateTombstone.Name = String.removePostfix(originalName, TOMBSTONE_NAME_POSTFIX_UNLOADED) .. TOMBSTONE_NAME_POSTFIX_LOADED
+						template.Parent = templateTombstone
+
+						promiseTemplate:Resolve(template)
+					end)
+			end))
+
+			topMaid:GiveTask(task.delay(5, function()
+				if self._unreplicatedTemplateMapList:GetListForKey(templateName) then
+					warn(string.format("[TemplateProvider.%s.PromiseTemplate] - Failed to replicate template %q from server to client", self.ServiceName, templateName))
+				else
+					warn(string.format("[TemplateProvider.%s.PromiseTemplate] - Template %q is not a known template", self.ServiceName, templateName))
+				end
+			end))
+		elseif self._replicationMode == TemplateReplicationModes.SHARED then
+			-- There's a chance an external process will stream in our template
+
+			topMaid:GiveTask(task.delay(5, function()
+				warn(string.format("[TemplateProvider.%s.PromiseTemplate] - Missing template %q", self.ServiceName, templateName))
+			end))
+		else
+			error("Bad replicationMode")
+		end
+	end)
+
+	self._maid[promiseTemplate] = promiseTemplate
+	self._pendingTemplatePromises[templateName] = promiseTemplate
+
+	promiseTemplate:Finally(function()
+		self._maid[promiseTemplate] = nil
+		self._pendingTemplatePromises[templateName] = nil
+	end)
+
+	return promiseTemplate
 end
 
---[=[
-	Returns all current registered items.
+function TemplateProvider:_promiseReplicateTemplateFromTombstone(templateTombstone)
+	assert(self._replicationMode == TemplateReplicationModes.CLIENT, "Bad replicationMode")
+	assert(typeof(templateTombstone) == "Instance", "Bad templateTombstone")
 
-	@return { Instance }
-]=]
-function TemplateProvider:GetAll()
-	self:_verifyInit()
+	local tombstoneId = templateTombstone:GetAttribute(TOMBSTONE_ID_ATTRIBUTE)
+	if type(tombstoneId) ~= "string" then
+		return Promise.rejected("tombstoneId must be a string")
+	end
 
-	local list = {}
-	for _, item in pairs(self._registry) do
-		table.insert(list, item)
+	if self._pendingTombstoneRequests[tombstoneId] then
+		return self._pendingTombstoneRequests[tombstoneId]
 	end
 
-	return list
+	local promiseTemplate = Promise.new()
+
+	PromiseMaidUtils.whilePromise(promiseTemplate, function(topMaid)
+		topMaid:GivePromise(self._remoting.ReplicateTemplate:PromiseInvokeServer(tombstoneId))
+			:Then(function(tempTemplate)
+				if not tempTemplate then
+					return Promise.rejected("Failed to get any template")
+				end
+
+				-- This tempTemplate will get destroyed by the server soon to free up server memory
+				-- TODO: cache on client
+				local copy = tempTemplate:Clone()
+				promiseTemplate:Resolve(copy)
+			end, function(...)
+				promiseTemplate:Reject(...)
+			end)
+	end)
+
+	self._maid[promiseTemplate] = promiseTemplate
+	self._pendingTombstoneRequests[tombstoneId] = promiseTemplate
+
+	promiseTemplate:Finally(function()
+		self._maid[promiseTemplate] = nil
+		self._pendingTombstoneRequests[tombstoneId] = nil
+	end)
+
+	return promiseTemplate
 end
 
 --[=[
-	Gets all current the containers.
+	Clones the template.
+
+	:::info
+	If the template name has a prefix of "Template" then it will remove it on the cloned instance.
+	:::
 
-	@return { Instance | number }
+	@param templateName string
+	@return Instance?
 ]=]
-function TemplateProvider:GetContainers()
-	self:_verifyInit()
+function TemplateProvider:CloneTemplate(templateName)
+	assert(type(templateName) == "string", "templateName must be a string")
 
-	local list = {}
-	for parent, _ in pairs(self._containersSet) do
-		table.insert(list, parent)
-	end
-	return list
-end
+	local template = self._templateMapList:GetItemForKeyAtIndex(templateName, -1)
+	if not template then
+		local unreplicated = self._unreplicatedTemplateMapList:GetListForKey(templateName)
 
-function TemplateProvider:_verifyInit()
-	if not RunService:IsRunning() then
-		if not self._initialized then
-			-- Initialize for hoarcecat!
-			self:Init()
+		if unreplicated then
+			error(string.format("[TemplateProvider.%s.CloneTemplate] - Template %q is not replicated. Use PromiseCloneTemplate instead", self.ServiceName, tostring(templateName)))
+		else
+			error(string.format("[TemplateProvider.%s.CloneTemplate] - Cannot provide template %q", self.ServiceName, tostring(templateName)))
 		end
+
+		return nil
 	end
 
-	assert(self._initialized, "TemplateProvider is not initialized")
+	return self:_cloneTemplate(template)
 end
 
-function TemplateProvider:_loadCloudAsset(assetId)
-	assert(type(assetId) == "number", "Bad assetId")
-	local maid = Maid.new()
-
-	-- Load on server
-	if RunService:IsServer() or not RunService:IsRunning() then
-		maid:GivePromise(InsertServiceUtils.promiseAsset(assetId)):Then(function(result)
-			if RunService:IsRunning() then
-				for _, item in pairs(result:GetChildren()) do
-					-- Replicate in children
-					item.Parent = self._replicationParent
-				end
+--[=[
+	Adds a new container to the provider for provision of assets. The initial container
+	is considered a template. Additionally, we will include any children that are in a folder
+	as a potential root
+
+	:::tip
+	The last template with a given name added will be considered the canonical template.
+	:::
+
+	@param container Template
+	@return MaidTask
+]=]
+function TemplateProvider:AddTemplates(container)
+	assert(self:_isValidTemplate(container), "Bad container")
+
+	if typeof(container) == "Instance" then
+		-- Always add this instance as we explicitly asked for it to be added as a root. This could be a
+		-- module script, or other component.
+		return self._containerRootCountingMap:Add(container)
+	elseif Observable.isObservable(container) then
+		local topMaid = Maid.new()
+
+		self:_addObservableTemplates(topMaid, container)
+
+		self._maid[topMaid] = topMaid
+		topMaid:GiveTask(function()
+			self._maid[topMaid] = nil
+		end)
+
+		return topMaid
+	elseif type(container) == "table" then
+		local topMaid = Maid.new()
+
+		for _, value in pairs(container) do
+			if typeof(value) == "Instance" then
+				-- Always add these as we explicitly ask for this to be a root too.
+				topMaid:GiveTask(self._containerRootCountingMap:Add(value))
+			elseif Observable.isObservable(value) then
+				self:_addObservableTemplates(topMaid, value)
 			else
-				-- Load without parenting
-				maid:GiveTask(self:_loadFolder(result))
+				error(string.format("[TemplateProvider.%s] - Bad value of type %q in container table", self.ServiceName, typeof(value)))
 			end
-		end)
-	end
+		end
 
-	return maid
-end
+		self._maid[topMaid] = topMaid
+		topMaid:GiveTask(function()
+			self._maid[topMaid] = nil
+		end)
 
-function TemplateProvider:_transformParent(getParent)
-	if typeof(getParent) == "Instance" then
-		return getParent
-	elseif type(getParent) == "function" then
-		local container = getParent()
-		assert(typeof(container) == "Instance", "Bad container")
-		return container
+		return topMaid
 	else
-		error("Bad getParent type")
+		error(string.format("[TemplateProvider.%s] - Bad container of type %s", self.ServiceName, typeof(container)))
 	end
 end
 
-function TemplateProvider:_loadFolder(parent)
-	local maid = Maid.new()
+function TemplateProvider:_addObservableTemplates(topMaid, observable)
+	topMaid:GiveTask(observable:Subscribe(function(result)
+		if Brio.isBrio(result) then
+			if result:IsDead() then
+				return
+			end
 
-	-- Only connect events if we're running
-	if RunService:IsRunning() then
-		maid:GiveTask(parent.ChildAdded:Connect(function(child)
-			self:_handleChildAdded(maid, child)
-		end))
-		maid:GiveTask(parent.ChildRemoved:Connect(function(child)
-			self:_handleChildRemoved(maid, child)
-		end))
+			local maid, template = result:ToMaidAndValue()
+			if typeof(template) == "Instance" then
+				self:_addInstanceTemplate(maid, template)
+			else
+				error("Cannot add non-instance from observable template")
+			end
+		else
+			error("Cannot add non Brio<Instance> from observable")
+		end
+	end))
+end
+
+function TemplateProvider:_addInstanceTemplate(topMaid, template)
+	if self:_shouldAddChildrenAsTemplates(template) then
+		topMaid:GiveTask(self._containerRootCountingMap:Add(template))
 	end
 
-	for _, child in pairs(parent:GetChildren()) do
-		self:_handleChildAdded(maid, child)
+	if template:GetAttribute(TOMBSTONE_ID_ATTRIBUTE) then
+		topMaid:GiveTask(self._unreplicatedTemplateMapList:Push(RxInstanceUtils.observeProperty(template, "Name"):Pipe({
+			Rx.map(function(name)
+				if String.endsWith(name, TOMBSTONE_NAME_POSTFIX_UNLOADED) then
+					return String.removePostfix(name, TOMBSTONE_NAME_POSTFIX_UNLOADED)
+				elseif String.endsWith(name, TOMBSTONE_NAME_POSTFIX_LOADED) then
+					return String.removePostfix(name, TOMBSTONE_NAME_POSTFIX_LOADED)
+				else
+					return name
+				end
+			end);
+			Rx.distinct();
+		}), template))
+	else
+		topMaid:GiveTask(self._templateMapList:Push(RxInstanceUtils.observeProperty(template, "Name"), template))
 	end
+end
 
-	maid:GiveTask(function()
-		maid:DoCleaning()
+--[=[
+	Returns whether or not a template is registered at the time
 
-		-- Deregister children
-		for _, child in pairs(parent:GetChildren()) do
-			self:_handleChildRemoved(maid, child)
-		end
-	end)
+	@param templateName string
+	@return boolean
+]=]
+function TemplateProvider:IsTemplateAvailable(templateName)
+	assert(type(templateName) == "string", "templateName must be a string")
 
-	return maid
+	return self._templateMapList:GetItemForKeyAtIndex(templateName, -1) ~= nil
 end
 
-function TemplateProvider:_handleChildRemoved(maid, child)
-	maid[child] = nil
-	self:_removeFromRegistry(child)
-end
+--[=[
+	Returns all current registered items.
 
-function TemplateProvider:_handleChildAdded(maid, child)
-	if child:IsA("Folder") then
-		maid[child] = self:_loadFolder(child)
-	else
-		self:_addToRegistery(child)
-	end
+	@return { Instance }
+]=]
+function TemplateProvider:GetTemplateList()
+	return self._templateMapList:GetListOfValuesAtListIndex(-1)
 end
 
-function TemplateProvider:_addToRegistery(child)
-	local childName = child.Name
-	-- if self._registry[childName] then
-		-- warn(string.format("[TemplateProvider._addToRegistery] - Duplicate %q in registery. Overridding", childName))
-	-- end
+--[=[
+	Gets all current the containers.
+
+	@return { Instance }
+]=]
+function TemplateProvider:GetContainerList()
+	return self._containerRootCountingMap:GetList()
+end
 
-	self._registry[childName] = child
+-- Backwards compatibility
+TemplateProvider.IsAvailable = assert(TemplateProvider.IsTemplateAvailable, "Missing method")
+TemplateProvider.Get = assert(TemplateProvider.GetTemplate, "Missing method")
+TemplateProvider.Clone = assert(TemplateProvider.CloneTemplate, "Missing method")
+TemplateProvider.PromiseClone = assert(TemplateProvider.PromiseCloneTemplate, "Missing method")
+TemplateProvider.GetAllTemplates = assert(TemplateProvider.GetTemplateList, "Missing method")
 
-	if self._promises[childName] then
-		self._promises[childName]:Resolve(child)
-		self._promises[childName] = nil
-	end
+function TemplateProvider:_cloneTemplate(template)
+	local newItem = template:Clone()
+	newItem.Name = String.removePostfix(template.Name, "Template")
+	return newItem
 end
 
-function TemplateProvider:_removeFromRegistry(child)
-	local childName = child.Name
+function TemplateProvider:_shouldAddChildrenAsTemplates(container)
+	return container:IsA("Folder")
+end
 
-	if self._registry[childName] == child then
-		self._registry[childName] = nil
-	end
+function TemplateProvider:_isValidTemplate(container)
+	return typeof(container) == "Instance"
+		or Observable.isObservable(container)
+		or type(container) == "table"
 end
 
 --[=[

package/src/Shared/TemplateContainerUtils.lua

@@ -1,39 +0,0 @@
---[=[
-	Utility functions for the TemplateProvider
-	@class TemplateContainerUtils
-]=]
-
-local Workspace = game:GetService("Workspace")
-local RunService = game:GetService("RunService")
-
-local TemplateContainerUtils = {}
-
-function TemplateContainerUtils.reparentFromWorkspaceIfNeeded(parent, name)
-	assert(typeof(parent) == "Instance", "Bad parent")
-	assert(type(name) == "string", "Bad name")
-
-	local workspaceContainer = Workspace:FindFirstChild(name)
-	local parentedContainer = parent:FindFirstChild(name)
-	if workspaceContainer then
-		if parentedContainer then
-			error(string.format("Duplicate container in %q and %q",
-				workspaceContainer:GetFullName(),
-				parentedContainer:GetFullName()))
-		end
-
-		-- Reparent
-		if RunService:IsRunning() then
-			workspaceContainer.Parent = parent
-		end
-
-		return workspaceContainer
-	end
-
-	if not parentedContainer then
-		error(string.format("No template container with name %q in %q", parent:GetFullName(), name))
-	end
-
-	return parentedContainer
-end
-
-return TemplateContainerUtils