Skip to main content

TemplateProvider

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.

Additionally, you can provide template overrides as the last added template will always be used.

-- shared/MyCustomTemplateProvider.lua

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. 

-- Server
local serviceBag = ServiceBag.new()
local templates = serviceBag:GetService(require("MyCustomTemplateProvider"))
serviceBag:Init()
serviceBag:Start()

-- Client
local serviceBag = ServiceBag.new()
local templates = serviceBag:GetService(require("MyCustomTemplateProvider"))
serviceBag:Init()
serviceBag:Start()

templates:PromiseCloneTemplate("CopCar"):Then(function(crate)
	print("Got crate!")
end)

Functions​

new​

</>
TemplateProvider.new(
providerName: string,
initialTemplates: TemplateDeclaration
) → TemplateProvider

Types

​

type TemplateDeclaration = Instance | Observable<Brio<Instance>> | table

Constructs a new TemplateProvider.

isTemplateProvider​

</>
TemplateProvider.isTemplateProvider(value: any) → boolean

Returns if the value is a template provider

Init​

</>
TemplateProvider.Init(
serviceBag: ServiceBag
) → ()

Initializes the container provider. Should be done via ServiceBag.

The replication mode follows the bag's TieRealmService realm when one was set, and is otherwise inferred from RunService.

ObserveTemplate​

</>
TemplateProvider.ObserveTemplate(
templateName: string
) → Observable<Instance>

Observes the given template by name

GetChildTemplateNameList​

</>
TemplateProvider.GetChildTemplateNameList(
folderTemplateName: string
) → {string}

Lists the names of the templates directly inside a folder template without replicating the folder or any of its contents. On the client this reads the tombstones the server left behind, so it works before anything is loaded. Use this to pick one template by name and then TemplateProvider.PromiseTemplate just that one.

Returns an empty list if the folder template is not known yet, or if it does not hold child templates. Only folders and roots passed to TemplateProvider.AddTemplates hold child templates.

INFO

The order of the names is not stable. Sort them if you need a deterministic order.

ObserveChildTemplateNameList​

</>
TemplateProvider.ObserveChildTemplateNameList(
folderTemplateName: string
) → Observable<{string}>

Observes TemplateProvider.GetChildTemplateNameList. Emits a new list whenever the set of child template names changes, starting with an empty list until the folder template is known.

Adding or removing a template that leaves the set of names unchanged does not emit, and neither does anything deeper than a direct child.

GetTemplate​

</>
TemplateProvider.GetTemplate(
templateName: string
) → Instance?

Returns the raw template

PromiseCloneTemplate​

</>
TemplateProvider.PromiseCloneTemplate(
templateName: string
) → Promise<Instance>

Promises to clone the template as soon as it exists

PromiseTemplate​

</>
TemplateProvider.PromiseTemplate(
templateName: string
) → Promise<Instance>

Promise to resolve the raw template as soon as it exists

CloneTemplate​

</>
TemplateProvider.CloneTemplate(
templateName: string
) → Instance?

Clones the template.

INFO

If the template name has a prefix of "Template" then it will remove it on the cloned instance.

AddTemplates​

</>
TemplateProvider.AddTemplates(
container: Template
) → MaidTask

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.

IsTemplateAvailable​

</>
TemplateProvider.IsTemplateAvailable(
templateName: string
) → boolean

Returns whether or not a template is registered at the time

GetTemplateList​

</>
TemplateProvider.GetTemplateList(self: TemplateProvider) → {Instance}

Returns all current registered items.

GetContainerList​

</>
TemplateProvider.GetContainerList(self: TemplateProvider) → {Instance}

Gets all current the containers.

Destroy​

</>
TemplateProvider.Destroy(self: TemplateProvider) → ()

Cleans up the provider

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new [TemplateProvider].",
            "params": [
                {
                    "name": "providerName",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "initialTemplates",
                    "desc": "",
                    "lua_type": "TemplateDeclaration"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "TemplateProvider\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 110,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "isTemplateProvider",
            "desc": "Returns if the value is a template provider",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 136,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "Init",
            "desc": "Initializes the container provider. Should be done via [ServiceBag].\n\nThe replication mode follows the bag's [TieRealmService] realm when one was set, and is otherwise\ninferred from [RunService].",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                },
                {
                    "name": "serviceBag",
                    "desc": "",
                    "lua_type": "ServiceBag"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 149,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "ObserveTemplate",
            "desc": "Observes the given template by name",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                },
                {
                    "name": "templateName",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<Instance>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 323,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "GetChildTemplateNameList",
            "desc": "Lists the names of the templates directly inside a folder template without\nreplicating the folder or any of its contents. On the client this reads the\ntombstones the server left behind, so it works before anything is loaded.\nUse this to pick one template by name and then [TemplateProvider.PromiseTemplate]\njust that one.\n\nReturns an empty list if the folder template is not known yet, or if it does not\nhold child templates. Only folders and roots passed to [TemplateProvider.AddTemplates]\nhold child templates.\n\n:::info\nThe order of the names is not stable. Sort them if you need a deterministic order.\n:::",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                },
                {
                    "name": "folderTemplateName",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ string }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 365,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "ObserveChildTemplateNameList",
            "desc": "Observes [TemplateProvider.GetChildTemplateNameList]. Emits a new list whenever\nthe set of child template names changes, starting with an empty list until the\nfolder template is known.\n\nAdding or removing a template that leaves the set of names unchanged does not emit,\nand neither does anything deeper than a direct child.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                },
                {
                    "name": "folderTemplateName",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<{ string }>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 392,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "GetTemplate",
            "desc": "Returns the raw template",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                },
                {
                    "name": "templateName",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 532,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "PromiseCloneTemplate",
            "desc": "Promises to clone the template as soon as it exists",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                },
                {
                    "name": "templateName",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<Instance>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 544,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "PromiseTemplate",
            "desc": "Promise to resolve the raw template as soon as it exists",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                },
                {
                    "name": "templateName",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<Instance>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 558,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "CloneTemplate",
            "desc": "Clones the template.\n\n:::info\nIf the template name has a prefix of \"Template\" then it will remove it on the cloned instance.\n:::",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                },
                {
                    "name": "templateName",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 720,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "AddTemplates",
            "desc": "Adds a new container to the provider for provision of assets. The initial container\nis considered a template. Additionally, we will include any children that are in a folder\nas a potential root\n\n:::tip\nThe last template with a given name added will be considered the canonical template.\n:::",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                },
                {
                    "name": "container",
                    "desc": "",
                    "lua_type": "Template"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "MaidTask"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 761,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "IsTemplateAvailable",
            "desc": "Returns whether or not a template is registered at the time",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                },
                {
                    "name": "templateName",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 867,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "GetTemplateList",
            "desc": "Returns all current registered items.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ Instance }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 878,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "GetContainerList",
            "desc": "Gets all current the containers.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ Instance }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 887,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        },
        {
            "name": "Destroy",
            "desc": "Cleans up the provider",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TemplateProvider"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 916,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "TemplateDeclaration",
            "desc": "",
            "lua_type": "Instance | Observable<Brio<Instance>> | table",
            "source": {
                "line": 83,
                "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
            }
        }
    ],
    "name": "TemplateProvider",
    "desc": "Base of a template retrieval system. Templates can be retrieved from Roblox and then retrieved by name. If a folder is used\nall of their children are also included as templates, which allows for flexible organization by artists.\n\nAdditionally, you can provide template overrides as the last added template will always be used.\n\n```lua\n-- shared/MyCustomTemplateProvider.lua\n\nreturn TemplateProvider.new(script.Name, script) -- Load locally\n```\n\n:::tip\nIf the TemplateProvider is initialized on the server, the the templates will be hidden from the client until the\nclient requests them.\n\nThis prevents large amounts of templates from being rendered to the client, taking up memory on the client. This especially\naffects meshes, but can also affect sounds and other similar templates.\n:::\n\n```lua\n-- Server\nlocal serviceBag = ServiceBag.new()\nlocal templates = serviceBag:GetService(require(\"MyCustomTemplateProvider\"))\nserviceBag:Init()\nserviceBag:Start()\n```\n\n```lua\n-- Client\nlocal serviceBag = ServiceBag.new()\nlocal templates = serviceBag:GetService(require(\"MyCustomTemplateProvider\"))\nserviceBag:Init()\nserviceBag:Start()\n\ntemplates:PromiseCloneTemplate(\"CopCar\"):Then(function(crate)\n\tprint(\"Got crate!\")\nend)\n```",
    "source": {
        "line": 44,
        "path": "src/templateprovider/src/Shared/TemplateProvider.lua"
    }
}