PcoWSkbVqDnWTu_dm2ix
We use cookies on this site to enhance your user experience

HumanoidDescription System

HumanoidDescription System

Jun 14 2019, 2:11 PM PST

HumanoidDescription is an Instance which can be placed anywhere in the Explorer hierarchy. It allows you to dynamically change Humanoid traits like body parts/colors, body scaling, accessories, clothing, and default animations.

Best Practices / Caveats

When using the HumanoidDescription system, note these important points:

  • The system assumes the current HumanoidDescription for a character is not manually edited and reflects the current assets on the character.
  • Changing the assets on a character while also using the HumanoidDescription system could lead to undefined behavior.

HumanoidDescription Properties

Accessories
BackAccessory
FaceAccessory
FrontAccessory
HairAccessory
HatAccessory
NeckAccessory
ShouldersAccessory
WaistAccessory
Scale
BodyTypeScale 0.3
DepthScale 1
HeadScale 1
HeightScale 1
ProportionScale 1
WidthScale 1
Animation
ClimbAnimation 0
FallAnimation 0
IdleAnimation 0
JumpAnimation 0
RunAnimation 0
SwimAnimation 0
WalkAnimation 0
Body Parts
Face 0
Head 0
LeftArm 0
LeftLeg 0
RightArm 0
RightLeg 0
Torso 0
Clothes
GraphicTShirt 0
Pants 0
Shirt 0
Body Colors
HeadColor [0, 0, 0]
LeftArmColor [0, 0, 0]
LeftLegColor [0, 0, 0]
RightArmColor [0, 0, 0]
RightLegColor [0, 0, 0]
TorsoColor [0, 0, 0]

Creating a HumanoidDescription

A new HumanoidDescription instance can be created directly within the Explorer hierarchy:

Alternatively, you can create one within a Script:

local humanoidDescription = Instance.new("HumanoidDescription")

Scripting Examples

The following examples show how you can use HumanoidDescription in scripts.

Edit Properties

In the HumanoidDescription instance, different property groups have different types:

  • Accessories are strings and they expect a comma-separated list of asset identifiers like "2551510151,2535600138".
  • Scale properties are numbers.
  • Each Animation, Body Parts, and Clothes property is a single asset identifier.
  • Each Body Colors property is a datatype/Color3|Color3 type.

To customize these properties, simply set them directly on the HumanoidDescription instance:

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 Characters With HumanoidDescription

To create a HumanoidDescription and then spawn a character with that description applied, add a Script (not a LocalScript) to the workspace and add this code to it:

-- Stop automatic spawning so it can be done in the "PlayerAdded" callback
game.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
game.Players.PlayerAdded:Connect(onPlayerAdded)

Alternatively, if you created a HumanoidDescription within Studio and parented it to the workspace, add a Script (not a LocalScript) to the workspace and put this code in it:

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

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

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

Apply to All Characters

The following code, placed in a Script, will apply a HumanoidDescription located in the workspace to all current players in the game:

 for _, player in pairs(game.Players:GetChildren()) do
	local humanoid = player.Character and player.Character:FindFirstChild("Humanoid")
	if humanoid then
		-- Apply "game.Workspace.StudioHumanoidDescription" to "humanoid"
		humanoid:ApplyDescription(game.Workspace.StudioHumanoidDescription)
	end
end

Revert a Character to its Default State

To revert a character to a state where no assets are applied from the avatar editor, put the following code in a Script. Note that this will still apply body colors/scales from the default HumanoidDescription.

local humanoid = player.Character and player.Character:FindFirstChild("Humanoid")
if humanoid then
	local defaultHumanoidDescription = Instance.new("HumanoidDescription")
	humanoid:ApplyDescription(defaultHumanoidDescription)
end

Change an Existing Character’s Assets

To add a new pair of sunglasses and a new torso to a character (but change nothing else), put this code in a Script:

local humanoid = player.Character and player.Character:FindFirstChild("Humanoid")
if humanoid then
	local descriptionClone = humanoid:GetAppliedDescription()
	-- Only one torso is allowed
	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

To revert to the blocky torso and remove all of the current face accessories (but change nothing else), put this code in a Script:

local humanoid = player.Character and player.Character:FindFirstChild("Humanoid")
if humanoid then
	local descriptionClone = humanoid:GetAppliedDescription()
	-- Revert to default torso
	descriptionClone.Torso = 0
	-- Remove all face accessories
	descriptionClone.FaceAccessory = ""
	-- Apply modified "descriptionClone" to humanoid
	humanoid:ApplyDescription(descriptionClone)
end

Change an Existing Character’s Colors

To give a character a magenta colored left arm (but change nothing else), put this code in a Script:

local humanoid = player.Character and player.Character:FindFirstChild("Humanoid")
if humanoid then
	local descriptionClone = humanoid:GetAppliedDescription()
	descriptionClone.LeftArmColor = Color3.new(1, 0, 1)
	-- Apply modified "descriptionClone" to humanoid
	humanoid:ApplyDescription(descriptionClone)
end

Change an Existing Character’s Scale

To double the height of a character (but change nothing else), put this code in a Script:

local humanoid = player.Character and player.Character:FindFirstChild("Humanoid")
if humanoid then
	local descriptionClone = humanoid:GetAppliedDescription()
	descriptionClone.HeightScale = descriptionClone.HeightScale*2
	-- Apply modified "descriptionClone" to humanoid
	humanoid:ApplyDescription(descriptionClone)
end

Change an Existing Character’s Animations

To change a character’s “idle” animation (but change nothing else), put the following in a Script:

local humanoid = player.Character and player.Character:FindFirstChild("Humanoid")
if humanoid then
	local descriptionClone = humanoid:GetAppliedDescription()
	descriptionClone.IdleAnimation = 754637456
	-- Apply modified "descriptionClone" to humanoid
	humanoid:ApplyDescription(descriptionClone)
end

Spawn Characters With User Specification

To make all spawning characters match the avatar editor setup of the user whose ID is 491243243, put the following in a Script within the workspace:

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

local function onPlayerAdded(player)
	local humanoidDescriptionForUser = game.Players:GetHumanoidDescriptionFromUserId(491243243)
	-- Spawn character with the HumanoidDescription
	player:LoadCharacterWithHumanoidDescription(humanoidDescriptionForUser)
end

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

Spawn Characters With Outfit Specification

To make all spawning characters match the avatar editor setup of an outfit with ID 480059254, put the following in a Script within the workspace:

-- Stop automatic spawning so it can be done in the "PlayerAdded" callback
game.Players.CharacterAutoLoads = false
 
local function onPlayerAdded(player)
	local humanoidDescriptionForOutfit = game.Players:GetHumanoidDescriptionFromOutfitId(480059254)
	-- Spawn character with the HumanoidDescription
	player:LoadCharacterWithHumanoidDescription(humanoidDescriptionForOutfit)
end

-- Connect "PlayerAdded" event to "onPlayerAdded()" function
game.Players.PlayerAdded:Connect(onPlayerAdded)
Tags:
  • humanoid
  • accessories
  • scale
  • body
  • clothes