Character Customization

To create a unique experience that alters the appearance of your users, you can customize the default character properties with the following:

  • Configure the Avatar Game Settings to set basic global avatar appearance defaults for all users.
  • Use HumanoidDescription at any point to apply a wide-range of specific character customizations to one or more users in your experience.

Game Settings

The Avatar section in Game Settings menu allows you to quickly set several global character properties in your experience. When editing the Avatar Game Settings, your avatar displays in the workspace as a visual preview.

You can adjust the following character properties in your experience using the Avatar Game Settings:

Setting Description
Presets Applies a common set of BodyTypeScale and ProportionScale combinations. You can further adjust these properties with HumanoidDescription after selecting a preset.
Avatar Type Sets the default avatar type to either R15 or R6.
Animation The set of Animations a user has access to.
Collision Sets the collision boundaries for characters in the experience.
Body Parts The Asset IDs of the Face, Head, Torso, RightArm, LeftArm, RightLeg and LeftLeg parts of a character.
Clothing The Asset IDs of the classic Shirt, Pants, and ShirtGraphic image textures that you can apply to the character.

Avatar Types

The Avatar Type setting sets your experience to only load R15 or R6 character models.

  • R15 is the default modern avatar with 15 limbs. This avatar allows for more flexible customization, accessory options, and animations.

  • R6 is a classic simple avatar with 6 limbs. This avatar type provides a retro feel but is limited in animations and additional customization. Body scale property changes do not affect R6 characters.

R15 Character Model.
R6 Character Model.

Collision Boundaries

The Collision setting sets the collision boundaries for characters in the experience. This doesn't impact the physical appearance of the characters in your experience.

Setting this option to Outer Box dynamically sizes the collision boxes of characters based on their individual models. This is the default and recommended setting for most experiences.

Setting this option to Inner Box provides fixed collision boundaries for all characters in your experience.

HumanoidDescription

Playable character models contain a Humanoid object that allows the model special characteristics, such as walking, jumping, equipping items, and interacting with the environment. To customize a Humanoid character's appearance, you can apply a new HumanoidDescription to change character properties.

You can adjust the following character properties in your experience using HumanoidDescription:

Character Property Description
Scale Number values for physical traits height, width, head, body type and proportion. This doesn't affect R6 body types.
Accessories The Asset IDs of accessories equipped by a character.
Classic Clothing The Asset IDs of the Shirt, Pants, and ShirtGraphic image textures that you can apply to the character.
Body Part The Asset IDs of the Face, Head, Torso, RightArm, LeftArm, RightLeg and LeftLeg parts of a character.
Body Colors The BodyColors of the character's individual parts.
Animations The Asset IDs of Animations you can use on a character.

You can customize a character with HumanoidDescription using the following steps:

  1. Create a description from the user's character, a specific Outfit ID, or from a specific User ID.
  2. Modify the description to customize the properties that you want to apply to the Humanoid character.
  3. Apply the description on either a single character, all player characters, or even on all spawning characters.

Creating HumanoidDescription

You can create a new HumanoidDescription instance directly within the Explorer hierarchy or within a Script with the following code:


1local humanoidDescription = Instance.new("HumanoidDescription")
2

In most cases, you should use an existing HumanoidDescription instead of a default new HumanoidDescription by referencing an existing player character, avatar outfit, or user ID.

From the Player Character

Use the following code sample to create a new HumanoidDescription based on the player character's current properties:


1local humanoid = player.Character and player.Character:FindFirstChild("Humanoid")
2
3local humanoidDescription = Instance.new("HumanoidDescription")
4
5if humanoid then
6 humanoidDescription = humanoid:GetAppliedDescription()
7end
8

From an Existing Outfit

Use the following sample code to create a HumanoidDescription from an outfit ID using Players.GetHumanoidDescriptionFromOutfitID:


1local outfitId = 480059254
2
3local humanoidDescriptionFromOutfit = game.Players:GetHumanoidDescriptionFromOutfitId(outfitId)
4

From a Specific User

Use the following sample code to create a HumanoidDescription from a user ID using Players:GetHumanoidDescriptionFromUserId():


1local userId = 491243243
2
3local humanoidDescriptionFromUser = game.Players:GetHumanoidDescriptionFromUserId(userId)
4

Modifying HumanoidDescription

To customize HumanoidDescription properties, set them directly on the HumanoidDescription or use a specified method before applying the HumanoidDescription to a character.

The following code sample provides examples of setting the the different types of HumanoidDescription properties:


1local humanoidDescription = Instance.new("HumanoidDescription")
2humanoidDescription.HatAccessory = "2551510151,2535600138"
3humanoidDescription.BodyTypeScale = 0.1
4humanoidDescription.ClimbAnimation = 619521311
5humanoidDescription.Face = 86487700
6humanoidDescription.GraphicTShirt = 1711661
7humanoidDescription.HeadColor = Color3.new(0, 1, 0)
8

Setting Multiple Accessories

For layered or bulk accessory changes, you can use HumanoidDescription:SetAccessories() to make accessory related updates. The following code sample adds a layered sweater and jacket in that order to a HumanoidDescription:


1local humanoidDescription = Instance.new("HumanoidDescription")
2local accessoryTable = {
3 {
4 Order = 1,
5 AssetId = 6984769289,
6 AccessoryType = Enum.AccessoryType.Sweater
7 },
8 {
9 Order = 2,
10 AssetId = 6984767443,
11 AccessoryType = Enum.AccessoryType.Jacket
12 }
13}
14
15humanoidDescription:SetAccessories(accessoryTable, false)
16

Applying HumanoidDescription

Apply HumanoidDescription to specific Humanoid characters in your experience with Humanoid:ApplyDescription() or Humanoid.LoadCharacterWithHumanoidDescription.

On a Single Character

ApplyDescription() can target any Humanoid. Use the following code to add a new pair of sunglasses and a new torso to the player character:


1local humanoid = player.Character and player.Character:FindFirstChild("Humanoid")
2if humanoid then
3 local descriptionClone = humanoid:GetAppliedDescription()
4 descriptionClone.Torso = 86500008
5 -- Multiple face accessory assets are allowed in a comma-separated string
6 descriptionClone.FaceAccessory = descriptionClone.FaceAccessory .. ",2535420239"
7 -- Apply modified "descriptionClone" to humanoid
8 humanoid:ApplyDescription(descriptionClone)
9end
10

On All Player Characters

Use the following sample code to apply a HumanoidDescription to all current players in the game:


1for \_, player in pairs(game.Players:GetChildren()) do
2local humanoid = player.Character and player.Character:FindFirstChild("Humanoid")
3 -- Create a HumanoidDescription
4 local humanoidDescription = Instance.new("HumanoidDescription")
5 humanoidDescription.HatAccessory = "2551510151,2535600138"
6 humanoidDescription.BodyTypeScale = 0.1
7 humanoidDescription.ClimbAnimation = 619521311
8 humanoidDescription.Face = 86487700
9 humanoidDescription.GraphicTShirt = 1711661
10 humanoidDescription.HeadColor = Color3.new(0, 1, 0)
11
12 if humanoid then
13 humanoid:ApplyDescription(humanoidDescription)
14 end
15end
16

On All Spawning Characters

Use the following sample code to set a specific HumanoidDescription for all spawning player characters:


1-- Stop automatic spawning so it can be done in the "PlayerAdded" callback
2game.Players.CharacterAutoLoads = false
3
4local function onPlayerAdded(player)
5 -- Create a HumanoidDescription
6 local humanoidDescription = Instance.new("HumanoidDescription")
7 humanoidDescription.HatAccessory = "2551510151,2535600138"
8 humanoidDescription.BodyTypeScale = 0.1
9 humanoidDescription.ClimbAnimation = 619521311
10 humanoidDescription.Face = 86487700
11 humanoidDescription.GraphicTShirt = 1711661
12 humanoidDescription.HeadColor = Color3.new(0, 1, 0)
13
14 -- Spawn character with the HumanoidDescription
15 player:LoadCharacterWithHumanoidDescription(humanoidDescription)
16end
17
18-- Connect "PlayerAdded" event to "onPlayerAdded()" function
19game.Players.PlayerAdded:Connect(onPlayerAdded)
20

If the HumanoidDescription instance was created in the Explorer and parented to the workspace, use the following sample code in a Script to access the workplace instance:


1-- Stop automatic spawning so it can be done in the "PlayerAdded" callback
2game.Players.CharacterAutoLoads = false
3
4local function onPlayerAdded(player)
5 -- Spawn character with "game.Workspace.StudioHumanoidDescription"
6 player:LoadCharacterWithHumanoidDescription(game.Workspace.StudioHumanoidDescription)
7end
8
9-- Connect "PlayerAdded" event to "onPlayerAdded()" function
10game.Players.PlayerAdded:Connect(onPlayerAdded)
11