23 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

AvatarCreationService

Inherits from: Instance → Object

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

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, Service

Methods

Inherited from Instance

Inherited from Object

AvatarCreationService:AutoSetupAvatarAsync

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.

Note: this API requires the Enable Mesh / Image APIs setting to be turned on under Content Settings for your experience.

Parameters

Returns

Code samples: View on Creator Hub (AvatarCreationService-AutoSetupAvatarAsync).

AvatarCreationService:GenerateAvatar2DPreviewAsync

Creates a 2D avatar image preview, taking as input the FileId from PromptSelectAvatarGenerationImageAsync() and an optional text prompt. It returns a previewId which can be passed to LoadAvatar2DPreviewAsync() to retrieve the preview image on the client. This API can only be used on the game server.

Note: this API requires the Enable Mesh / Image APIs setting to be turned on under Content Settings for your experience.

Parameters

Returns

Code samples: View on Creator Hub (AvatarCreationService-GenerateAvatar2DPreviewAsync).

AvatarCreationService:GenerateAvatarAsync

Generate an avatar from a preview and return the generationId. The LoadGeneratedAvatarAsync() method is then called to retrieve the generated HumanoidDescription avatar. This API can only be used on the game server.

Note: this API requires the Enable Mesh / Image APIs setting to be turned on under Content Settings for your experience.

Parameters

Returns

Code samples: View on Creator Hub (AvatarCreationService-GenerateAvatarAsync).

AvatarCreationService:GetBatchTokenDetailsAsync

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

Returns

AvatarCreationService: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,
		},
		...
      	},
        ["MakeupRules"] = {
		["ReferenceCageMeshId"]: number,
		["WrapTextureTransferUVBounds"] = {
			["MinBound"]: Vector2,
            		["MaxBound"]: Vector2,
          	},
          	["ExcludeUVBounds"] = {
            		[Enum.AssetType.FaceMakeup] = {
              			["LeftEye"] = {
                			["MinBound"]: Vector2,
                			["MaxBound"]: Vector2,
              			},
              			["RightEye"] = {
                			["MinBound"]: Vector2,
                			["MaxBound"]: Vector2,
              			},
              			["Lips"] = {
                			["MinBound"]: Vector2,
                			["MaxBound"]: Vector2,
              			},
            		},
          	},
          	["IncludeUVBounds"] = {
			[Enum.AssetType.LipMakeup] = {
				["MinBound"]: Vector2,
				["MaxBound"]: Vector2,
		    	},
		    	[Enum.AssetType.EyeMakeup] = {
		      		["MinBound"]: Vector2,
		      		["MaxBound"]: Vector2,
		    	},
          	}
	}
}

Returns

AvatarCreationService:LoadAvatar2DPreviewAsync

Load an AvatarGeneration 2D preview as an EditableImage on the client for the given previewId. This API can only be used on the client.

Note: this API requires the Enable Mesh / Image APIs setting to be turned on under Content Settings for your experience.

Parameters

Returns

Code samples: View on Creator Hub (AvatarCreationService-LoadAvatar2DPreviewAsync).

AvatarCreationService:LoadGeneratedAvatarAsync

Loads a generated avatar using an avatar generation ID, as returned by AutoSetupAvatarAsync() or GenerateAvatarAsync(). 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.

Note: this API requires the Enable Mesh / Image APIs setting to be turned on under Content Settings for your experience.

Parameters

Returns

Code samples: View on Creator Hub (AvatarCreationService-LoadGeneratedAvatarAsync).

AvatarCreationService:PrepareAvatarForPreviewAsync

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

Returns

AvatarCreationService:PromptCreateAvatarAssetAsync

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

For avatar asset creation, the Instance is expected to include a new accessory to be created. This includes the following types: Hat, Hair, FaceAccessory, NeckAccessory, ShoulderAccessory, FrontAccessory, BackAccessory, WaistAccessory, TShirtAccessory, ShirtAccessory, PantsAccessory, JacketAccessory, SweaterAccessory, ShortsAccessory, DressSkirtAccessory.

To support this, the Instance should be an Accessory instance or contain an Accessory child instance. This should include a MeshPart child instance which makes up the accessory.

The avatar asset MeshPart will also need to include:

• An EditableImage.
• An EditableMesh.

If creating a layered clothing accessory such as a shirt, the MeshPart should include a WrapDeformer with an EditableMesh.

Finally, the provided AvatarAssetType should match the creation type of the token and the type of Accessory for upload.

Parameters

Returns

Code samples: View on Creator Hub (AvatarCreationService-PromptCreateAvatarAssetAsync).

AvatarCreationService:PromptCreateAvatarAsync

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 BodyPart.

Each body part MeshPart will also need to include:

• An EditableImage.
• A WrapDeformer with an EditableMesh.

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

• The AccessoryDescription.Instance property references the Accessory instance.
• The AccessoryDescription.AccessoryType property is set to the relevant AccessoryType.

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

Returns

Code samples: View on Creator Hub (AvatarCreationService-PromptCreateAvatarAsync).

AvatarCreationService:PromptSelectAvatarGenerationImageAsync

Prompt the Player to take a selfie and return the FileId of the selfie. This FileId is then passed as an argument to GenerateAvatar2DPreviewAsync(). This API can only be used on the game server.

local AvatarCreationService = game:GetService("AvatarCreationService")

function promptSelectAvatarGenerationImage(player)
    local pcallSuccess, result = pcall(function()
        return AvatarCreationService:PromptSelectAvatarGenerationImageAsync(player)
    end)

    if not pcallSuccess then
        errName, errDesc = unpack(string.split(result, ": "))
        if errName == "SelfieConsentDenied" then
            warn("Player must accept consent to use feature.")
        else
            warn("Failed to prompt for image: ", errDesc)
        end
    end

    return result
end

On failure, the result string has the format ErrorName: Error description, allowing the error type to be identified programmatically.

Parameters

Returns

AvatarCreationService:RequestAvatarGenerationSessionAsync

Request an AvatarGeneration session for a Player. Information about the session is returned via the callback, including the SessionId which is passed to the GenerateAvatar2DPreviewAsync() and GenerateAvatarAsync() methods. Additional session information includes allowed 2d preview generations, allowed 3d avatar generations, and the session time. The method returns a Tuple with an RBXScriptConnection and estimated waitTime. The RBXScriptConnection allows canceling a session request. The estimated waitTime is used to provide the player an estimated time in seconds until the session will be ready. This API can only be used on the game server.

Parameters

Returns

Code samples: View on Creator Hub (AvatarCreationService-RequestAvatarGenerationSessionAsync).

AvatarCreationService:ValidateUGCAccessoryAsync

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

Parameters

Returns

AvatarCreationService:ValidateUGCBodyPartAsync

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

• LeftArm (Folder)
  • R15ArtistIntent (Folder)
    • LeftLowerArm (MeshPart)
    • LeftUpperArm (MeshPart)
    • LeftHand (MeshPart)

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

Parameters

Returns

AvatarCreationService:ValidateUGCFullBodyAsync

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 six required BodyPart values. Optionally, it can include instances set on AccessoryDescription children for any supported AccessoryType.

Parameters

Returns

Events

Inherited from Instance

Inherited from Object

AvatarCreationService.AvatarAssetModerationCompleted

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

Note that this event only fires for avatar assets created within the current experience and will trigger when the ModerationStatus changes from NotReviewed to any other status. The event fires on the client only.

Parameters

Code samples: View on Creator Hub (AvatarCreationService-AvatarAssetModerationCompleted).

AvatarCreationService.AvatarModerationCompleted

Deprecated. This event is deprecated. Use AvatarCreationService.AvatarOutfitModerationCompleted instead; the replacement event supports avatar outfits and other in-experience-created outfit types.

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 ModerationStatus changes from NotReviewed to any other status. The event fires on the client only. GetOutfitDetailsAsync can be used on the server to verify the current moderation status if needed.

Parameters

AvatarCreationService.AvatarOutfitModerationCompleted

Fires on the client when an in-experience-created outfit's moderation status changes from NotReviewed to another status. Use this event for any in-experience-created outfit type. Current outfit creation flows include PromptCreateAvatarAsync(). Future in-experience outfit types will use this event as well (AvatarModerationCompleted is deprecated).

Use outfitType to determine the kind of outfit that completed moderation. This event is informational: an outfit cannot be used until its moderation status permits it.

Parameters

Properties

Inherited from Instance

Inherited from Object