7 min read

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

Character appearance

Most games let players use their own Roblox avatar, although some implement an in-game customization system like the UGC Homestore template. Other games make limited modifications to player avatars such as helmets, wings, or accessories that match the genre.

To create a unique game that alters the appearance of your users, you can customize the default character properties through avatar settings or a manually modify appearance.

Global avatar settings

Studio's File ⟩ Avatar Settings allows you to quickly set several global player character properties in your game. These settings apply globally to all player character models joining your game. To modify specific characters, such as non-player character models, see manually modify appearance.

In this window, you can set various presets for clothing, accessories, body parts, collision behavior, animations and more. When editing these settings, a preview of the applied settings displays in the workspace.

For more information, see Avatar Settings.

Manually modify appearance

Character models contain a Humanoid object that gives the model special characteristics, such as walking, jumping, equipping items, and interacting with the environment.

You can programmatically modify a Humanoid by updating HumanoidDescription. This includes player character models or non-player character models in your game.

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

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.

Note

When updating a character's properties through HumanoidDescription, it is important to use an up-to-date HumanoidDescription of that specific Humanoid with Humanoid:GetAppliedDescription().

Create HumanoidDescription

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

local humanoidDescription = Instance.new("HumanoidDescription")

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:

local humanoid = player.Character and player.Character:FindFirstChildWhichIsA("Humanoid")

local humanoidDescription = Instance.new("HumanoidDescription")

if humanoid then
	humanoidDescription = humanoid:GetAppliedDescription()
end

From an existing outfit

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

local Players = game:GetService("Players")

local outfitId = 480059254

local humanoidDescriptionFromOutfit = Players:GetHumanoidDescriptionFromOutfitId(outfitId)

From a specific user

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

local Players = game:GetService("Players")

local userId = 491243243

local humanoidDescriptionFromUser = Players:GetHumanoidDescriptionFromUserId(userId)

Modify 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 different types of HumanoidDescription properties:

local humanoidDescription = Instance.new("HumanoidDescription")
humanoidDescription.HatAccessory = "2551510151,2535600138"
humanoidDescription.BodyTypeScale = 0.1
humanoidDescription.ClimbAnimation = 619521311
humanoidDescription.Face = 86487700
humanoidDescription.GraphicTShirt = 1711661
humanoidDescription.HeadColor = Color3.new(0, 1, 0)

Set 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:

local humanoidDescription = Instance.new("HumanoidDescription")
local accessoryTable = {
	{
		Order = 1,
		AssetId = 6984769289,
		AccessoryType = Enum.AccessoryType.Sweater
	},
	{
		Order = 2,
		AssetId = 6984767443,
		AccessoryType = Enum.AccessoryType.Jacket
	}
}

humanoidDescription:SetAccessories(accessoryTable, false)

Apply HumanoidDescription

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

Note

Changing the assets on a character while also changing HumanoidDescription might lead to undefined behavior.

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:

local humanoid = player.Character and player.Character:FindFirstChildWhichIsA("Humanoid")
if humanoid then
	local descriptionClone = humanoid:GetAppliedDescription()
	descriptionClone.Torso = 86500008
	-- Multiple face accessory assets are allowed in a comma-separated string
	descriptionClone.FaceAccessory = descriptionClone.FaceAccessory .. ",2535420239"
	-- Apply modified "descriptionClone" to humanoid
	humanoid:ApplyDescription(descriptionClone)
end

On all player characters

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

local Players = game:GetService("Players")

for _, player in Players:GetPlayers() do
	local humanoid = player.Character and player.Character:FindFirstChildWhichIsA("Humanoid")
	if humanoid then
		-- Create a HumanoidDescription
		local humanoidDescription = Instance.new("HumanoidDescription")
		humanoidDescription.HatAccessory = "2551510151,2535600138"
		humanoidDescription.BodyTypeScale = 0.1
		humanoidDescription.ClimbAnimation = 619521311
		humanoidDescription.Face = 86487700
		humanoidDescription.GraphicTShirt = 1711661
		humanoidDescription.HeadColor = Color3.new(0, 1, 0)
		humanoid:ApplyDescription(humanoidDescription)
	end
end

On all spawning characters

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

local Players = game:GetService("Players")

-- Stop automatic spawning so it can be done in the "PlayerAdded" callback
Players.CharacterAutoLoads = false

local function onPlayerAdded(player)
	-- Create a HumanoidDescription
	local humanoidDescription = Instance.new("HumanoidDescription")
	humanoidDescription.HatAccessory = "2551510151,2535600138"
	humanoidDescription.BodyTypeScale = 0.1
	humanoidDescription.ClimbAnimation = 619521311
	humanoidDescription.Face = 86487700
	humanoidDescription.GraphicTShirt = 1711661
	humanoidDescription.HeadColor = Color3.new(0, 1, 0)

	-- Spawn character with the HumanoidDescription
	player:LoadCharacterWithHumanoidDescription(humanoidDescription)
end

-- Connect "PlayerAdded" event to "onPlayerAdded()" function
Players.PlayerAdded:Connect(onPlayerAdded)

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 workspace instance:

local Players = game:GetService("Players")

-- Stop automatic spawning so it can be done in the "PlayerAdded" callback
Players.CharacterAutoLoads = false

local function onPlayerAdded(player)
	-- Spawn character with "workspace.StudioHumanoidDescription"
	player:LoadCharacterWithHumanoidDescription(workspace.StudioHumanoidDescription)
end

-- Connect "PlayerAdded" event to "onPlayerAdded()" function
Players.PlayerAdded:Connect(onPlayerAdded)

Layered accessories on non-R15

Caged accessories, like layered accessories, use WrapTarget and WrapLayer to stretch and wrap over a target Model. Layered accessories can work with both standard player characters and non-R15 models.

Custom implementation of layered accessories, such as a model using a unique cage UV map, cannot be uploaded and published to the Marketplace. However, you can create custom cage meshes for in-game assets like buildings, game-specific clothing, and props.

Whether you are implementing layered accessories on an R15 rigging armature, or using a custom rig, ensure that your accessories and bodies include the following:

• The target model, typically the body, has a WrapTarget component on the meshes that additional models are intended to wrap around.
• The layering model, typically the clothing or accessory, has a WrapLayer component on the meshes meant to wrap the target model.
• The outer cage of the target model, and the inner and outer cage of the layering model have matching UV maps.
  • The corresponding vertices on the target cage should have the same UVs as those vertices on the layer cage.
• If your target model is not R15, or doesn't include a Humanoid, you must add a Weld object to the layering MeshPart.
  • The Weld must have Part0 and Part1 set to link the layering MeshPart to the Part hierarchy of the Model. For example, Part0 refers to the accessory and Part1 refers to the parent Part.
• If your target model is both R15 and includes a Humanoid, this weld is created automatically.

Note

See the following resources for additional information on layered accessories and caging:

• Layered accessories caging overview
• Layered accessories caging best practices
• Layered accessories cage mesh specifications
• Avatar body cage specifications