InsertService

Show Deprecated
Not Creatable
Service

InsertService is used to insert assets from the Roblox website, typically the LoadAsset function.

To load an asset, the asset must be accessible by the creator of the game loading it, which can be either a user or group. Due to these restrictions, InsertService is useful for loading sensitive data, typically API or secret keys to be used with HttpService. Should a game be uploaded by a different creator, the sensitive data would not be accessible. See the LoadAsset function for more details on this security check.

See also:

  • AssetService, which can provide information about assets you might want to load using InsertService

Summary

Properties

Events

Methods

LoadLocalAsset(assetPath: string): Instance  


CreateMeshPartAsync(meshId: Content, collisionFidelity: CollisionFidelity, renderFidelity: RenderFidelity): MeshPart  YIELDS

Create a new MeshPart with specified meshId and fidelity values.

GetBaseSets(): Array  YIELDS

Returns an array of dictionaries, containing information about various Roblox approved sets.

GetCollection(categoryId: number): Array  YIELDS

Returns the most recently uploaded models in the specified category.

GetFreeDecals(searchText: string, pageNum: number): Array  YIELDS

Retrieves a list of Free Decals from the Catalog.

GetFreeModels(searchText: string, pageNum: number): Array  YIELDS

Retrieves a list of Free Models from the Catalog.


Returns the latest AssetVersionId of an asset for assets created by the place creator. Can be used in combination with InsertService:LoadAssetVersion() to load the latest version of a model, even if it gets updated while the game is running.

GetUserSets(userId: number): Array  YIELDS

Returns an array of dictionaries, containing information about sets owned by the user.

LoadAsset(assetId: number): Instance  YIELDS

Returns a Model containing the asset.

LoadAssetVersion(assetVersionId: number): Instance  YIELDS

Returns a model inserted into InsertService containing the asset with the given assetVersionId.

Properties

AllowClientInsertModels

Not Scriptable

Events

Methods

LoadLocalAsset

Roblox Script Security

Parameters

assetPath: string

Returns

LoadPackageAsset

Roblox Script Security

Parameters

url: Content

Returns

CreateMeshPartAsync

Yields
Plugin Security

CreateMeshPartAsync can create a MeshPart with specified CollisionFidelity and RenderFidelity. Because MeshPart.MeshId is read only, this is the way of creating MeshPart with any MeshId through scripts, without having to clone an existing MeshPart. It throws errors if creation fails.

Parameters

meshId: Content

Mesh asset id.

collisionFidelity: CollisionFidelity

Set MeshPart.CollisionFidelity.

renderFidelity: RenderFidelity

Set MeshPart.RenderFidelity.


Returns

New MeshPart instance.

GetBaseSets

Yields

Returns an array of dictionaries, containing information about various Roblox approved sets.


Returns

GetCollection

Yields

Returns the most recently uploaded models in the specified category.

Parameters

categoryId: number

Returns

Code Samples

InsertService:GetCollection

1local InsertService = game:GetService("InsertService")
2
3local set = InsertService:GetBaseSets()[1]
4local list = InsertService:GetCollection(set["CategoryId"])
5
6print(list)

GetFreeDecals

Yields

The GetFreeDecals function retrieves a list of Free Decals from the Catalog. The return type for this method is very odd, as it returns a single table wrapped in a table.

The best way to explain it is to show a visual of the array returned:


1[1] = {
2 CurrentStartIndex = 1, -- This can vary depending on the page you input.
3 TotalCount = 21, -- Always 21.
4 Results = {
5 -- All parameters here are psuedo. They can vary depending on the asset.
6 [1] = {
7 Name = "Asset Name",
8 AssetId = 0000000,
9 AssetVersionId = 0000000,
10 CreatorName = "Roblox",
11 },
12 -- [2], [3], and so on... up to [21]
13 },
14}
15

Yikes! That quite confusing. Unfortunately this method was added in the earlier days of Roblox, where easy to understand return-types weren't a priority.

Thankfully, an example for iterating over this list has been provided at the bottom of this page.

Additionally, if you want to insert Models instead, you can use the InsertService:GetFreeModels() function.

Note: The page argument starts at 0. So Page 1 = 0, Page 2 = 1, etc.

Parameters

searchText: string

String used to search for free decals in the Catalog.

pageNum: number

The page number in the Catalog to return.


Returns

A single table (of returned free decals) wrapped in a table.

Code Samples

InsertService:GetFreeDecals

1local InsertService = game:GetService("InsertService")
2
3local page = unpack(InsertService:GetFreeDecals("Cats", 0)) -- Search for "Cats" on Page 1.
4
5for i = 1, page.TotalCount do
6 local item = page.Results[i]
7 print("Item #" .. i)
8 for key, value in pairs(item) do
9 print(" " .. key .. ": " .. value)
10 end
11end

GetFreeModels

Yields

The GetFreeModels function retrieves a list of Free Models from the Catalog. The return type for this method is very odd, as it returns a single table wrapped in a table.

The best way to explain it is to show a visual of the array returned:


1[1] = {
2 CurrentStartIndex = 1, -- This can vary depending on the page you input.
3 TotalCount = 21, -- Always 21.
4 Results = {
5 -- All parameters here are psuedo. They can vary depending on the asset.
6 [1] = {
7 Name = "Asset Name",
8 AssetId = 0000000,
9 AssetVersionId = 0000000,
10 CreatorName = "Roblox",
11 }
12 -- [2], [3], and so on... up to [21]
13 }
14}
15

An example for iterating over this list has been provided at the bottom of this page.

Additionally, if you would like to insert free Decals, you can use the InsertService:GetFreeDecals() function.

Parameters

searchText: string

String used to search for free decals in the Catalog.

pageNum: number

The page number in the Catalog to return.


Returns

A single table (of returned free models) wrapped in a table.

Code Samples

InsertService:GetFreeModels

1local InsertService = game:GetService("InsertService")
2
3local page = unpack(InsertService:GetFreeModels("Cats", 0)) -- Search for "Cats" on Page 1.
4
5for i = 1, page.TotalCount do
6 local item = page.Results[i]
7 print("Item #" .. i)
8 for key, value in pairs(item) do
9 print(" " .. key .. ": " .. value)
10 end
11end

GetLatestAssetVersionAsync

Yields

Returns the latest AssetVersionId of an asset for assets created by the place creator. Can be used in combination with InsertService:LoadAssetVersion() to load the latest version of a model, even if it gets updated while the game is running.

Parameters

assetId: number

Returns

GetUserSets

Yields

Returns an array of dictionaries, containing information about sets owned by the user. This includes

  • Sets the user is subscribed to.
  • Sets that the user created.
  • A single set containing the models created by the user.
  • A single set containing the decals created by the user.

Note:

  • All values in the dictionaries are strings, even if they are a number.
NameDescription
NameThe name of the set.
DescriptionThe description of the set.
ImageAssetIdAn assetId for the icon of the set.
CreatorNameThe creator of the set.
AssetSetIdThe set's unique ID on the website.
CategoryIdIdentical to AssetSetId
SetTypeThe type of set that this set is.

Parameters

userId: number

Returns

LoadAsset

Yields

The LoadAsset function fetches an asset given its ID and returns a Model containing the asset. For example, to load this public Doge Model, which has the asset Id 257489726, you can use:


1local assetId = 257489726
2local InsertService = game:GetService("InsertService")
3local model = InsertService:LoadAsset(assetId)
4model.Parent = workspace
5

Calls to this function may fail if a server providing a model is having problems. As such, it's generally a good idea to wrap calls to this function in pcall to catch these kinds of errors.


1local assetId = 257489726
2local InsertService = game:GetService("InsertService")
3local success, model = pcall(InsertService.LoadAsset, InsertService, assetId)
4if success and model then
5 print("Model loaded successfully")
6 model.Parent = workspace
7else
8 print("Model failed to load!")
9end
10

Security Check

An asset loaded by this function must be created or owned by either the game creator or Roblox. Additionally, benign asset types such as t-shirts, shirts, pants and avatar accessories are loadable from any game as they are public.

See also:

Parameters

assetId: number

The asset Id of the asset being loaded.


Returns

An instance of the loaded asset.

Code Samples

InsertService:LoadAsset

1local InsertService = game:GetService("InsertService")
2
3local ASSET_ID = 82353
4
5local asset = InsertService:LoadAsset(ASSET_ID)
6
7asset.Parent = workspace

LoadAssetVersion

Yields

Returns a model inserted into InsertService containing the asset with the given assetVersionId.

Parameters

assetVersionId: number

Returns

Code Samples

InsertService:LoadAssetVersion

1local InsertService = game:GetService("InsertService")
2
3local ASSET_VERSION_ID = 296050499
4
5local asset = InsertService:LoadAssetVersion(ASSET_VERSION_ID)
6
7asset.Parent = game.Workspace

LoadPackageAssetAsync

Yields
Roblox Script Security

Parameters

url: Content

Returns