Hi Creators,
We’re excited to announce the next phase of creation on Roblox: in-experience avatar creation. Following the Client Beta of EditableMesh and EditableImage APIs and the introduction of WrapDeformer, we’re introducing Add Avatar to Inventory and the PromptCreateAvatarAsync API as a Client Beta. This API lets users — for the first time — create a Roblox Avatar from within an experience, save it to their inventory, and use it across the platform.
Our vision for in-experience avatar creation is for users to fully embody the character of your game — from realistic soldiers for your first-person shooter to custom fashion models for dress-up games.
We’re starting with the ability to generate Avatar Bodies (torso, limbs, dynamic head outfit, and optional hair) with this launch, and we plan to expand the tooling to include clothing and accessories in the future. These creations are a personal copy added to the user’s inventory, are not listed on Marketplace, and cannot be sold or traded.
Creating Avatars Within an Experience
PromptCreateAvatarAsync allows your users to create a custom avatar. After creating, users will be prompted to pay for and submit a Roblox Avatar Body through the same moderation and validation flow that avatar creators go through today when submitting to the Marketplace. When paired with the Editable* APIs and WrapDeformer, your users can:
- Select from avatar bodies you provide (note: this does not allow users to edit any body from the Avatar Marketplace)
- Adjust the mesh (muscle size, face shape, etc.)
- Modify the texture (paint-fill, add decals, pattern, free draw, etc.)
- Name their creation, pay for and submit to moderation, and — upon successful completion — have it in their inventory to use across the platform. Note that these avatars users create in-experience cannot be placed on Avatar Marketplace, traded or resold at this time.
These custom avatars are another way to earn on Roblox and can also increase the discoverability of your experience. Each avatar has an attribution link back to the experience, allowing anyone on the platform to view and access the experience from a friend’s avatar.
You can test these capabilities in Roblox Avatar Creator, an experience we made that lets you adjust the mesh, add decals, pattern and paint a Robot, and then submit and purchase. Download the placefile to see how these APIs all interact and can work together to build a creation experience.
Let’s dive into how to incorporate Add Avatar to Inventory into your experience.
Avatar Creation Token
To get started, you’ll need to set up your Avatar Creation Token for your experience. This allows you to indicate the universe you’re adding the API to, pay for the token, and configure the details.
-
Navigate to Creator Hub, and choose “View as” on the top left to indicate whether you’re going to be choosing an experience you own or one that you’re part of as a group.
-
Go to
Creationson the left panel and click on your experience. -
On the left panel, under
Monetization, click onAvatar Creation Tokens. ClickCreate Tokento begin. -
To enable the API in your experience, you or the owner of your group need to be ID-verified and Premium. These are the same Creator Requirements for listing on the Marketplace. Make sure that you meet these requirements, as you won’t be able to enable the API without them. Note that for the token to remain valid you’ll need to maintain these statuses.
-
Enter a name and description for your token. These names are for internal use only and won’t be user-facing. Next, select Item Type: Body (the only selection available at launch). You may change the name and description after creating the token, but the type and experience it’s tied to cannot be changed after creation.
-
Next, you can set the price that users pay for bodies in your experience: you may list at a specified amount above the price floor (if the price floor fluctuates, your pricing will update automatically) or also optionally never below a certain amount. You may change the price after creating the token. Note that if you’d like to have different price points for bodies in your experience, the best way to achieve this is by purchasing multiple tokens.
-
Finally, to pay for your token, similar to avatar items on Marketplace, there’s a flat fee and an advance. At launch, the fee and advance mirror listing a Body on the Marketplace, with R$750 as a flat Creation Fee and a R$4000 Creation Advance. Just like with the advance on Marketplace, you get paid back the Roblox portion of all sales until you’ve made that R$4000 back, at which point the typical split returns.
-
Once you’ve completed the purchase of your token, it’s time to get your Token ID. Tap the three dots on the thumbnail or click the image to get the Token ID, and copy the ID. You’ll use this ID in the PromptCreateAvatarAsync API implementation to allow for adding to inventory from within your experience.
PromptCreateAvatarAsync
This new API allows you to prompt a user to purchase and create an avatar from a HumanoidDescription. To get started, you’ll want a HumanoidDescription that includes the 6 body parts (Torso, Right Arm, Left Arm, Right Leg, Left Leg) and can also optionally include a Hair accessory. To learn more about how to implement, see this documentation.
The HumanoidDescription and the new instances it references that are required for the PromptCreateAvatarAsync API are expected in the following format:
-
HumanoidDescriptionshould have 6BodyPartDescriptioninstances as children representing each of the required body parts. The Instance property on each of these should reference a folder containing the relevantMeshPartinstances (in the case of the Head, it can reference theMeshPartdirectly as there is only one). The BodyPart property on each of these should be set to the correspondingEnum.BodyPartfor which body part the Instance property is referencing. -
Optionally,
HumanoidDescriptioncan include anAccessoryDescriptionchild for Hair. The Instance property will need to reference theAccessoryinstance, and theAccessoryTypeproperty should be set to the correspondingEnum.AccessoryType -
Each
MeshPartfor the body parts must include anEditableImageandWrapDeformer. TheWrapDeformermust include anEditableMesh. -
The
MeshPartfor Hair (if Hair is included) must include anEditableImageandEditableMeshset directly with noWrapDeformer. -
The
Scalevalues on theHumanoidDescriptionmay also optionally be set which will scale the avatar intended for creation.
As part of the API, there’s a tokenID parameter that’s expecting a string, and here you’ll put in the Token ID that you copied from above. This will pull in the price and item type.
Click to expand for the full code snippet
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 pcallComplete, result, resultMessage = pcall(function()
return AvatarCreationService:PromptCreateAvatarAsync(tokenId, player, humanoidDescription)
end)
if pcallComplete then
if result == Enum.PromptCreateAvatarResult.Success then
print("Successfully uploaded with BundleId: ", resultMessage)
else
print("Unsuccessfully uploaded with error message:", resultMessage)
end
end
end
GetBatchTokenDetailsAsync
This new API allows you to fetch the details of any Avatar Creation Tokens you may be interested in for your experience. To learn more about the specifics of the API, refer to the documentation. The API accepts a table of Avatar Creation Token ID strings and will give useful information about them like:
- Name of the token
- Description of the token
- UniverseId the token is attributed to
- CreatorId of the user or group that generated the token
- CreatorType describing whether the creator was a group or user
- OnSale value informing if the token is valid and available for use in PromptCreateAvatarAsync
- Price that an end user will be charged for creations based on this token
Permissions
This API allows your users to create net-new bodies from within your experience, and you’ll need to provide users with meshes/bodies that you or your group own. As a reminder, the rules for EditableMesh and EditableImage APIs only allow you to load assets that are:
- Owned by the creator of the experience if the experience is owned by an individual.
- Owned by a group, if the experience is owned by the group.
- Owned by the logged in Studio user if the place file has not yet been saved or published to Roblox.
Validation
All Avatar Bodies that are added to Inventory must abide by our Marketplace policies and must pass validation. The meshes that you provide in your experience should pass validation and the tooling that you create using Editable* and WrapDeformer should prevent a user from creating a body that fails validation.
To help ensure your users are creating bodies that will pass validation, we’re providing APIs that allow you to check if UGC Validation passes before the user pays for and uploads the body:
- ValidateUGCBodyPartAsync
- ValidateUGCAccessoryAsync
- ValidateUGCFullBodyAsync
- GetValidationRules
ValidateUGCBodyPartAsync, ValidateUGCAccessoryAsync, ValidateUGCFullBodyAsync will start off as studio-only API’s. These will be useful during development of Avatar creation experiences to verify that the body users will be building on top of comply with UGC Validation.
For those wishing to design their creation tools in such a way that the finished avatar can’t fail UGC Validation as a result of a user’s edit, we added the GetValidationRules API, which provides a table of values that UGC Validation checks against. This includes asset minimum and maximum sizes, mesh triangle limits, maximum and minimum attachment offsets, etc.
Moderation, Appeals and Consequences
All bodies that are submitted to be added to inventory go through our moderation systems and, upon passing, are available in a user’s inventory. If a body does not pass moderation, users receive a notification and can tap into the item details in the app to see the moderation status and request an appeal through our Appeals System if they feel the item was incorrectly moderated.
Bodies created in-experience must follow Marketplace Policy and both Safety and Civility and body-specific policies, including Modesty Layer, and no baked-in clothing or accessories, tattoos or makeup. We recommend communicating to users that bodies with these will not pass moderation and, when creating your tooling, ensure you’re providing guardrails that make it difficult for users to create violative content.
At an individual level, users are responsible for the content they create and, if they’re creating content that’s not appropriate for the platform, they will be subject to moderation consequences and losing the spent Robux. However, if an experience appears to be the source of much more violative content than would be expected, we will notify the developer that the creation tooling in their experience is allowing for bad content to be made. In some cases, we reserve the right to take action immediately upon the experience and developer.
Attribution
When an avatar has been successfully created, that avatar will be viewable by the person who created it in app and on the web. In the app, the details of the avatar can be inspected to find the attribution link. This will link directly into the experience the avatar was created in from the app. Developers who want to respond to users entering their experiences from these attribution links can leverage the following table on a Player:
player.GetJoinData().GameJoinContext
Developers can index into this table with the following values to cater towards users entering experience via attribution:
-
gameJoinContext.JoinSource -
gameJoinContext.ItemType -
gameJoinContext.AssetType -
gameJoinContext.OutfitId -
gameJoinContext.AssetId
If ItemType is Enum.AvatarItemType.Bundle — which for full avatars should always be the case — the AssetId and AssetType will not be populated. Otherwise, the OutfitId will not be populated.JoinSource will always be Enum.JoinSource.CreatedItemAttribution for avatar creation attributions.
Example place file
As mentioned, we have an experience, Roblox Avatar Creator, that shows how these APIs all work together in concert. That place is uncopylocked, and we’re also providing the placefile so that you can load it into Studio and see how this all works together.
Known Issues
-
Eyebrows and Eyelashes
- We’re working on a fix right now to allow you to enable the creation of net-new eyebrows and eyelashes as part of the Body bundle, but it’s not currently possible to create these assets net-new at launch. Since these are optional assets in the bundle, we recommend not including them until this issue is resolved.
-
3D Projection
- Currently, painting on texture is done by directly drawing an image on the texture location determined by a raycast, this can cause issues with edges and seams and does not take into account the geometry of the model. Accounting for those issues will incur performance penalty.
- We’re working on an ability to support 3D projection painting and anticipate having this functionality available very soon. In the meantime, painting is possible using 2D drawing on the texture map, and we’ll support both options going forward.
-
Body part seams with
WrapDeformer- Individual body parts may be able to be deformed in such a way that seams appear near joints. We’re working on fixes that help make the WrapDeformer more contextually aware of the holistic avatar to avoid seams showing up between joints.
FAQs
How are developers paid?
- When a user makes a purchase, developers will receive 70% (30% as ‘creator’ and 40% as the experience developer) of sales that come from in-experience creation.
Can users sell their avatar creation?
- Currently, we are not allowing generated avatar content to be sold on the Marketplace. In-experience created bodies go the user’s inventory, and cannot be sold on Marketplace, traded, or resold to other users.
What are the developer requirements?
- The requirements for developers here are the same as they are for UGC avatar creators: you must be ID-verified and Premium to allow the implementation of the publishing APIs. Additionally, developers will have to buy a token tied to a UniverseID and asset type with a price point. Developers pay for this token and a publishing fee, similar to the process for avatar creators.
Can users edit any UGC body?
- No, EditableMesh and EditableImage objects can only be created from assets that are owned (as in created) by you (or your group if the experience is owned by a group).
Do users need to be ID-verified to publish?
- Users do not need to be ID-verified or have Premium to create an avatar in an experience.
If an avatar fails moderation, does the user receive a refund?
- No, if the avatar violates Roblox community standards, the user will not be able to receive a refund. They may appeal the decision if they believe their avatar was incorrectly moderated and should be approved.
Try out Add Avatar to Inventory and let us know your feedback below - we can’t wait to see what you build with it!
Thanks,
@FarazTheGreat @TheGamer101 @CackleAtGrackle @guigi59 @timetopretend8 @RadioNoggin @manyglacier @meiyonnaize @JollySunbro6 @TheBabananaMilk @Bug_0xFF @slamborgen @srathore @virtualcurr @vk_rObl0x @mrgshprm @tara1gian @YoungAla132 @shaperotator @discosalamander @knknGoing @CowTheCow27 @NoahWillCode @legendRf20 @TokoyakiGohan @G_xerces @misterpebblez @feelsofgold @prussian_marinade @monsterjunjun @BloxMachina @FGmm_r2 @portenio @ContextLost @pearpod48 @fullmetal2042 @icouldblox @poorcharlie99 @safetymod @kanehaloz @pbloxi @aSW33T @flipnic13 @frecklesnspectacles @discodorothy @Photoguy82 @Bodacious_Abzz @naahchos @GeneralRelish @gelkros
