AvatarCreationService

Show Deprecated
Not Creatable
Service

AvatarCreationService is a service that supports developer avatar creators, providing methods that support the prompting of avatar creation from within experiences.

Summary

Methods

Events

Properties

Methods

AutoSetupAvatarAsync

Yields

Automatically sets up a custom Model as an avatar asset. This method returns a string generation ID which can be passed to LoadGeneratedAvatarAsync() to load the generated avatar and return a HumanoidDescription with all the generated instances and properties. The load method can be called on both the server and client, allowing the generated avatar to be loaded in both places (on the client for previewing, and on the server for saving the generated avatar to the player's inventory using PromptCreateAvatarAsync()).

Auto-setup has specific model requirements and accepts certain configurations of models. For more information, see Auto-setup requirements. In addition to the above requirements, the input model must use EditableMesh and EditableImage objects for all mesh and texture assets.

Parameters

player: Player

The Player that the avatar is being set up for.

model: Model

The humanoid Model that will be set up as an avatar.


Returns

A unique identifier for the generated avatar.

Code Samples

The following code invokes AutoSetup on the given Model. The setup avatar is then loaded on the server and an event is sent to the client to load the avatar for local preview.

A separate saveAvatarToInventory function is provided to demonstrate how to pass the generated avatar to PromptCreateAvatarAsync if the player wants to save it to their inventory.

AutoSetupAvatarAsync

local AvatarCreationService = game:GetService("AvatarCreationService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LoadAvatarEvent = ReplicatedStorage.LoadAvatarEvent
local generatedAvatars = {}
-- Must be called on the server
local function setupAvatar(player: Player, avatarModel: Model)
local pcallSuccess, result = pcall(function()
local generationId = AvatarCreationService:AutoSetupAvatarAsync(
player,
avatarModel
)
-- Load and store on the server to use with PromptCreateAvatarAsync
local humanoidDescription =
AvatarCreationService:LoadGeneratedAvatarAsync(generationId)
generatedAvatars[generationId] = humanoidDescription
-- Signal the client so it can load the avatar for local preview
LoadAvatarEvent:FireClient(player, generationId)
end)
if not pcallSuccess then
warn("Avatar setup failed:", result)
end
end
local avatarCreationToken = "xyz" -- https://create.roblox.com/docs/production/monetization/avatar-creation-token
local function saveAvatarToInventory(generationId: string, player: Player)
local humanoidDescription = generatedAvatars[generationId]
return AvatarCreationService:PromptCreateAvatarAsync(avatarCreationToken, player, humanoidDescription)
end

GenerateAvatar2DPreviewAsync

Yields

Parameters

avatarGeneration2dPreviewParams: Dictionary

Returns

GenerateAvatarAsync

Yields

Parameters

avatarGenerationParams: Dictionary

Returns

GetBatchTokenDetailsAsync

Yields

Gets the avatar creation token details for a list of avatar creation tokens at once (tokens are generated through the token creation process). Returns an array of avatar creation token details; each token detail is a dictionary with the fields indicated in the example result below:


{
["Name"] = "string",
["Description"] = "string",
["UniverseId"] = 0,
["CreatorId"] = 0,
["CreatorType"] = Enum.CreatorType.User,
["OnSale"] = true,
["Price"] = 0,
["OffSaleReasons"] = {
"string",
}
}

Parameters

tokenIds: Array

The list of avatar creation token IDs to get details of.


Returns

Array of avatar creation token details as outlined above.

GetValidationRules

Gets data regarding rules that assets must abide by to pass UGC validation. Validation is an essential step before creating avatars and there are various checks that occur, including mesh triangle limits, texture sizes, body part size limits, attachment positions, and more.

The returned dictionary of validation rules takes the following form:


{
["MeshRules"] = {
["BodyPartMaxTriangles"] = {
Enum.AssetType.DynamicHead: number,
Enum.AssetType.LeftArm: number,
Enum.AssetType.RightArm: number,
Enum.AssetType.Torso: number,
Enum.AssetType.LeftLeg: number,
Enum.AssetType.RightLeg: number,
},
["AccessoryMaxTriangles"]: number,
["MeshVertColor"]: Color3,
["CageMeshMaxDistanceFromRenderMesh"]: number,
},
["TextureRules"] = {
["MaxTextureSize"]: number,
},
["BodyPartRules"] = {
[Enum.AssetType.DynamicHead] = {
["Bounds"] = {
["Classic"] = {
["MinSize"]: Vector3,
["MaxSize"]: Vector3,
},
["ProportionsSlender"] = {
["MinSize"]: Vector3,
["MaxSize"]: Vector3,
},
["ProportionsNormal"] = {
["MinSize"]: Vector3,
["MaxSize"]: Vector3,
},
},
["SubParts"] = {
["Head"] = {
["NeckRigAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
["FaceFrontAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
["HatAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
["HairAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
["FaceCenterAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
},
},
},
[Enum.AssetType.LeftArm] = {
["Bounds"] = {
["Classic"] = {
["MinSize"]: Vector3,
["MaxSize"]: Vector3,
},
["ProportionsSlender"] = {
["MinSize"]: Vector3,
["MaxSize"]: Vector3,
},
["ProportionsNormal"] = {
["MinSize"]: Vector3,
["MaxSize"]: Vector3,
},
},
["SubParts"] = {
["LeftHand"] = {
["LeftWristRigAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
["LeftGripAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
},
["LeftUpperArm"] = {
["LeftShoulderRigAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
["LeftShoulderAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
["LeftElbowRigAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
},
["LeftLowerArm"] = {
["LeftElbowRigAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
["LeftWristRigAttachment"] = {
["LowerBound"]: Vector3,
["UpperBound"]: Vector3,
},
},
},
},
...
},
["AccessoryRules"] = {
[Enum.AssetType.HairAccessory] = {
["Attachments"] = {
{
["Size"]: Vector3,
["Offset"]: Vector3,
["Name"]: string,
},
},
["RigidAllowed"]: boolean,
},
...
}
}

Returns

Dictionary of validation rules as detailed above.

LoadAvatar2DPreviewAsync

Yields

Parameters

previewId: string

Returns

LoadGeneratedAvatarAsync

Yields

Loads a generated avatar using an avatar generation ID, as returned by AutoSetupAvatarAsync(). The generated avatar will be returned as a HumanoidDescription with all the generated instances and properties. Mesh and texture assets will be provided as EditableMesh and EditableImage objects, respectively, to allow continued editing of the generated avatar.

This method can be called on both the server and client, allowing the generated avatar to be loaded in both places (on the client for previewing, and on the server for saving the generated avatar to the player's inventory using PromptCreateAvatarAsync()). Once the method has been invoked on both the client and server, the data associated with the generation ID will be erased and subsequent calls to his method with the same generation ID will fail.

Parameters

generationId: string

A unique string that identifies the generated avatar, as returned by AutoSetupAvatarAsync().


Returns

The HumanoidDescription of the generated avatar, which includes all the generated instances and properties.

Code Samples

The following code loads a generated avatar using an avatar generation ID provided by AvatarCreationService:AutoSetupAvatarAsync(). The result is returned as a HumanoidDescription.

LoadGeneratedAvatarAsync

local AvatarCreationService = game:GetService("AvatarCreationService")
local Players = game:GetService("Players")
-- Can be called on either the server or client
local function loadAvatar(generationId: string): Model?
local pcallSuccess, result = pcall(function()
local humanoidDescription = AvatarCreationService:LoadGeneratedAvatarAsync(generationId)
local model = Players:CreateHumanoidModelFromDescription(
humanoidDescription,
Enum.HumanoidRigType.R15
)
return model
end)
if pcallSuccess then
return result
else
print("Avatar failed to load:", result)
return nil
end
end

PrepareAvatarForPreviewAsync

()
Yields

Triggers HSR generation and attachment point updating for in-experience avatar previews. This allows for previewing of avatars created in experience with layered clothing and accessories in the same way they will appear when published through PromptCreateAvatarAsync().

When developers use EditableMesh and WrapDeformer to modify avatars before publishing, the original HSR data may not accurately account for the new deformations. This method generates updated HSR data and corrects attachment points based on the WrapDeformer modifications, ensuring consistent preview and published avatar appearance.

Parameters

humanoidModel: Model

The Model containing MeshPart children with WrapDeformer instances that require HSR data updating for preview.


Returns

()

PromptCreateAvatarAsync

Yields

Prompts a Player to purchase and create an avatar from a HumanoidDescription. The price of the creation is dictated by the price attributed to the avatar creation token. This avatar creation token is required for the purchasing and creation of the body and can be generated by following the token creation process.

For avatar creation, the HumanoidDescription is expected to include new assets to be created for each of the 6 body parts (Head, Torso, RightLeg, LeftLeg, RightArm, LeftArm). Optionally, it can also include a new Hair accessory.

To support this, the HumanoidDescription should include 6 BodyPartDescription children (one for each body part). For each, the BodyPartDescription.Instance property references a Folder which includes all of the MeshPart instances which make up the body part, for example a LeftArm folder which has LeftHand, LeftUpperArm, and LeftLowerArm MeshParts. The BodyPartDescription.BodyPart property should also be set to the relevant Enum.BodyPart.

Each body part MeshPart will also need to include:

If including an accessory such as hair, the HumanoidDescription should include a child AccessoryDescription where:

Finally, the HumanoidDescription should include the humanoid scales of BodyTypeScale, HeadScale, HeightScale, WidthScale, and ProportionScale. Be mindful of the scales that a base body is imported with so that they match the scales provided to the HumanoidDescription.

Parameters

tokenId: string

The ID of an avatar creation token. The token must be valid in that the universe the method is called from is the same universe the token was created for. Furthermore, the token creator must maintain ID verification and Roblox Premium. To create a token for utilization in this API, follow the token creation process.

player: Player

The Player intended to be presented with the creation prompt.

humanoidDescription: HumanoidDescription

The HumanoidDescription of the avatar intended for creation.


Returns

A tuple containing, in order:

Code Samples

The following code populates a HumanoidDescription in the expected format, prompts for avatar creation, and responds to the result.

PromptCreateAvatarAsync

local AvatarCreationService = game:GetService("AvatarCreationService")
export type BodyPartInfo = {
bodyPart: Enum.BodyPart,
instance: Instance, --Folder with Created MeshParts
}
export type BodyPartList = { BodyPartInfo }
local function publishAvatar(bodyPartInstances: BodyPartList, player: Player, tokenId: string)
local humanoidDescription = Instance.new("HumanoidDescription")
for _, bodyPartInfo in bodyPartInstances do
local bodyPartDescription = Instance.new("BodyPartDescription")
bodyPartDescription.Instance = bodyPartInfo.instance
bodyPartDescription.BodyPart = bodyPartInfo.bodyPart
bodyPartDescription.Parent = humanoidDescription
end
local pcallSuccess, result, resultMessage = pcall(function()
return AvatarCreationService:PromptCreateAvatarAsync(tokenId, player, humanoidDescription)
end)
if pcallSuccess then
if result == Enum.PromptCreateAvatarResult.Success then
print("Successfully uploaded with BundleId: ", resultMessage)
else
print("Unsuccessfully uploaded with error message:", resultMessage)
end
else
print("Avatar failed to create.")
end
end

PromptSelectAvatarGenerationImageAsync

Yields

Parameters

player: Player

Returns

RequestAvatarGenerationSessionAsync

Yields

Parameters

player: Player
callback: function

Returns

ValidateUGCAccessoryAsync

Yields

Studio only. Given a Player and Instance for an Enum.AccessoryType, determines if UGC validation passes.

Parameters

player: Player

The Player validation is completed for.

accessory: Instance

The instance validation is run on.

accessoryType: Enum.AccessoryType

Enum.AccessoryType the instance is expected to be. Expects Eyebrow, Eyelash, or Hair.


Returns

A tuple containing, in order:

  • A boolean indicating if validation was successful for the accessory.
  • An optional table of strings. This includes failure reasons if validation was unsuccessful; otherwise nil if validation was successful.

ValidateUGCBodyPartAsync

Yields

Studio only. Given a Player and Instance for an Enum.BodyPart, determines if UGC validation passes. The instance parameter is expected as a Folder in the following example format with relevant MeshParts:

However, if the expected bodyPart is Enum.BodyPart.Head, the function takes a singular Head MeshPart directly.

Parameters

player: Player

The Player validation is completed for.

instance: Instance

The instance validation is run on.

bodyPart: Enum.BodyPart

Enum.BodyPart the instance is expected to be.


Returns

A tuple containing, in order:

  • A boolean indicating if validation was successful for the body part.
  • An optional table of strings. This includes failure reasons if validation was unsuccessful; otherwise nil if validation was successful.

ValidateUGCFullBodyAsync

Yields

Studio only. Given a Player and HumanoidDescription, all instances in the HumanoidDescription will be validated.

The HumanoidDescription is expected to include instances set on BodyPartDescription children for each of the 6 required Enum.BodyPart values. Optionally, it can include instances set on AccessoryDescription children for Eyebrow, Eyelash, and Hair AccessoryTypes.

Parameters

player: Player

The Player validation is completed for.

humanoidDescription: HumanoidDescription

HumanoidDescription representing the body that validation is run on.


Returns

A tuple containing, in order:

  • A boolean indicating if validation was successful for the body.
  • An optional table of strings. This includes failure reasons if validation was unsuccessful; otherwise nil if validation was successful.

Events

AvatarModerationCompleted

Fires when an in-experience-created avatar's moderation status has been updated from pending. This event provides a streamlined way to know when an avatar created through PromptCreateAvatarAsync() has completed the moderation process and is ready for use in-experience.

Note that this event only fires for avatars created within the current experience and will trigger when the Enum.ModerationStatus changes from NotReviewed to any other status. The event fires on the client only. GetOutfitDetails can be used on the server to verify the current moderation status if needed.

Parameters

outfitId: number

The outfit ID of the avatar that has completed moderation.

moderationStatus: Enum.ModerationStatus

The final Enum.ModerationStatus result after moderation completion.