PcoWSkbVqDnWTu_dm2ix
Collapse Sidebar
  1. API Reference
  2. Humanoid

Humanoid

Show deprecated
Hide content
  1. apireference
  2. humanoid

Humanoid

Show deprecated

The Humanoid is a special object that gives models the functionality of a character. It grants the model with the ability to physically walk around and interact with various components of a Roblox level.

Humanoids are always parented inside of a Model, and the model is expected to be an assembly of BasePart and Motor6D; the root part of the assembly is expected to be named HumanoidRootPart. It also expects a part named Head to be connected to the character’s torso part, either directly or indirectly.

By default, there are two official types of character rigs supplied by Roblox, each with their own set of rules:

R6

  • A basic character rig that uses 6 parts for limbs.

  • The Head part must be attached to a part named Torso, or the Humanoid will die immediately.
  • BodyPart appearances are applied using CharacterMesh objects.
  • Certain properties, such as Humanoid/LeftLeg and Humanoid/RightLeg, only work with R6.

    • R15

  • More complex than R6, but also far more flexible and robust.
  • Uses 15 parts for limbs.
  • The Head part must be attached to a part named UpperTorso or the Humanoid will die immediately.
  • BodyPart appearances have to be assembled directly.
  • Can be dynamically rescaled by using special NumberValue objects parented inside of the Humanoid.
    • The Humanoid will automatically create Vector3Value objects named OriginalSize inside of each limb.
    • If a NumberValue is parented inside of the Humanoid and is named one of the following, it will be used to control the scaling functionality:
      • BodyDepthScale
      • BodyHeightScale
      • BodyWidthScale
      • HeadScale

    • Properties

    bool

    AutoJumpEnabled

    Sets whether the character will automatically jump when they hit an obstacle as a player on a mobile device.
    bool

    AutoRotate

    AutoRotate sets whether or not the Humanoid will automatically rotate to face in the direction they are moving in.
    bool

    AutomaticScalingEnabled

    bool

    BreakJointsOnDeath

    Determines whether a Humanoid|Humanoid's joints break when in the Dead state
    Vector3

    CameraOffset

    An offset applied to the Camera’s subject position when its CameraSubject is set to this Humanoid.
    HumanoidCollisionType

    CollisionType

    Selects the Enum/HumanoidCollisionType for R15 and Rthro non-player characters
    HumanoidDisplayDistanceType

    DisplayDistanceType

    Controls the distance behavior of the Humanoid’s name and health display.
    string

    DisplayName

    Sets the text of a Humanoid, displayed above their head.
    Material

    FloorMaterial

    [ReadOnly] [NotReplicated]

    Describes the Enum/Material that the Humanoid is currently standing on. If the Humanoid isn’t standing on anything, the value of this property will be Air.
    float

    Health

    [NotReplicated]

    Describes the current health of the Humanoid on the range [0, Humanoid/MaxHealth].
    float

    HealthDisplayDistance

    Used in conjunction with the Humanoid’s Humanoid/DisplayDistanceType property to either determine how far a player controlling this Humanoid can see another humanoid’s health bar, or how far this Humanoid’s health displays to other viewing players.
    HumanoidHealthDisplayType

    HealthDisplayType

    Controls when the Humanoid|Humanoid's health bar is allowed to be displayed.
    float

    HipHeight

    Determines the distance off the ground the Humanoid/RootPart should be.
    bool

    Jump

    [NotReplicated]

    Whether the Humanoid is jumping. If set to true, it will cause the Humanoid to jump.
    float

    JumpHeight

    Provides control over the force with which a Humanoid jumps
    float

    JumpPower

    Determines how much upwards force is applied to the Humanoid when jumping
    BasePart

    LeftLeg

    [Hidden] [NotReplicated] [Deprecated]

    A reference to the humanoid’s Left Leg part.
    float

    MaxHealth

    The maximum value of a Humanoid|Humanoid's Humanoid/Health.
    float

    MaxSlopeAngle

    The maximum slope angle that a humanoid can walk on without slipping
    Vector3

    MoveDirection

    [ReadOnly] [NotReplicated]

    Describes the direction that the Humanoid is walking in, as a unit vector along the X/Z axis.
    float

    NameDisplayDistance

    Used in conjunction with the Humanoid’s DisplayDistanceType property to either determine how far a player controlling this Humanoid can see another humanoid’s name, or how far this Humanoid’s name displays to other viewing players.
    NameOcclusion

    NameOcclusion

    Controls whether a Humanoid|Humanoid's name can be seen behind walls or other objects.
    bool

    PlatformStand

    Determines whether the Humanoid is currently in the PlatformStanding Enum/HumanoidStateType.
    bool

    RequiresNeck

    Allows developers to disable the behavior where a player Character|character dies if the Neck Motor6D is removed or disconnected even momentarily
    HumanoidRigType

    RigType

    Describes whether this Humanoid is utilizing the legacy R6 character rig, or the new R15 character rig.
    BasePart

    RightLeg

    [Hidden] [NotReplicated] [Deprecated]

    A reference to the humanoid’s Right Leg part.
    BasePart

    RootPart

    [ReadOnly] [NotReplicated]

    A reference to the Humanoid|Humanoid's HumanoidRootPart.
    BasePart

    SeatPart

    [ReadOnly] [NotReplicated]

    A reference to the seat that a Humanoid is currently sitting in, if any.
    bool

    Sit

    Describes whether the Humanoid is currently sitting.
    Vector3

    TargetPoint

    Describes the 3D position where the Player controlling the Humanoid last clicked in the world while using a Tool
    BasePart

    Torso

    [Hidden] [NotReplicated] [Deprecated]

    A reference to a humanoid’s root driving part.
    bool

    UseJumpPower

    Determines whether the StarterPlayer/CharacterJumpHeight|CharacterJumpHeight (false) or StarterPlayer/CharacterJumpPower (true) property is used
    float

    WalkSpeed

    Describes the Humanoid|Humanoid's maximum movement speed in studs/sec
    BasePart

    WalkToPart

    A reference to a part whose position is trying to be reached by a humanoid.
    Vector3

    WalkToPoint

    The position that a humanoid is trying to reach, after a call to Humanoid/MoveTo is made.
    float

    maxHealth

    [NotReplicated] [Deprecated]

    Inherited from Instance: Show Hide

    bool

    Archivable

    Determines if an Instance can be cloned using /Instance/Clone or saved to file.
    string

    ClassName

    [ReadOnly] [NotReplicated]

    A read-only string representing the class this Instance belongs to
    int

    DataCost

    [Hidden] [ReadOnly] [NotReplicated] [Deprecated]

    The cost of saving the instance using data persistence.
    string

    Name

    A non-unique identifier of the Instance
    Instance

    Parent

    [NotReplicated]

    Determines the hierarchical parent of the Instance
    bool

    RobloxLocked

    [Hidden]

    A deprecated property that used to protect CoreGui objects
    bool

    archivable

    [Hidden] [NotReplicated] [Deprecated]
    string

    className

    [ReadOnly] [NotReplicated] [Deprecated]

    Functions

    void

    AddAccessory ( Instance accessory )

    Attaches the specified Accessory to the Humanoid|Humanoid’s parent
    bool

    AddCustomStatus ( string status )

    [Deprecated]

    Adds a custom status to the Humanoid.
    bool

    AddStatus ( Status status )

    [Deprecated]

    Adds a BoolValue to the Humanoid’s Status object.
    void

    ApplyDescription ( Instance humanoidDescription , AssetTypeVerification assetTypeVerification )

    [Yields]

    Makes the Player/Character|character's look match that of the passed in HumanoidDescription
    void

    BuildRigFromAttachments ( )

    Assembles a tree of Motor6D joints by attaching together Attachment objects in a Humanoid|Humanoid's character
    void

    ChangeState ( HumanoidStateType state )

    Set the Humanoid to enter the given Enum/HumanoidStateType
    void

    EquipTool ( Instance tool )

    Makes the Humanoid equip the given Tool
    Array

    GetAccessories ( )

    Returns an array of Accessory|Accessories that the Humanoid|Humanoid’s parent is currently wearing
    Instance

    GetAppliedDescription ( )

    Returns back a copy of the Humanoid|Humanoid's cached HumanoidDescription, which describes its current look
    BodyPartR15

    GetBodyPartR15 ( Instance part )

    Limb

    GetLimb ( Instance part )

    Returns the Enum/Limb enum that is associated with the given Part
    Array

    GetPlayingAnimationTracks ( )

    [Deprecated]

    Returns an array of all AnimationTrack|AnimationTracks that are currently being played on the Humanoid
    HumanoidStateType

    GetState ( )

    Returns the Humanoid|Humanoid's current Enum/HumanoidStateType
    bool

    GetStateEnabled ( HumanoidStateType state )

    Returns whether a Enum/HumanoidStateType is enabled for the Humanoid
    Array

    GetStatuses ( )

    [Deprecated]

    Returns a table of the Humanoid’s statuses, and custom statuses.
    bool

    HasCustomStatus ( string status )

    [Deprecated]

    Returns boolean based on if custom statuses exist.
    bool

    HasStatus ( Status status )

    [Deprecated]

    Returns a boolean based on if a status exists.
    Instance

    LoadAnimation ( Instance animation )

    [Deprecated]

    Loads an Animation onto a Humanoid, returning an AnimationTrack that can be used for playback
    void

    Move ( Vector3 moveDirection , bool relativeToCamera )

    Causes the Humanoid to walk in the given direction
    void

    MoveTo ( Vector3 location , Instance part )

    Causes the Humanoid to attempt to walk to the given location by setting the Humanoid/WalkToPoint and Humanoid/WalkToPart properties
    bool

    PlayEmote ( string emoteName )

    [Yields]

    Plays emotes and returns if was successfully ran.
    void

    RemoveAccessories ( )

    Removes all Accessory|Accessories worn by the Humanoid|Humanoid’s parent
    bool

    RemoveCustomStatus ( string status )

    [Deprecated]

    Removes the defined custom status from the Status model in the Humanoid…
    bool

    RemoveStatus ( Status status )

    [Deprecated]

    .Removes the defined status from the Status model in the Humanoid.
    bool

    ReplaceBodyPartR15 ( BodyPartR15 bodyPart , Instance part )

    Dynamically replaces a Humanoid body part with a different part.
    void

    SetStateEnabled ( HumanoidStateType state , bool enabled )

    Sets whether a given Enum/HumanoidStateType is enabled for the Humanoid
    void

    TakeDamage ( float amount )

    Lowers the Humanoid/Health of the Humanoid by the given amount if it is not protected by a ForceField
    void

    UnequipTools ( )

    Unequips any Tool currently equipped by the Humanoid
    Instance

    loadAnimation ( Instance animation )

    [Deprecated]
    void

    takeDamage ( float amount )

    [Deprecated]

    Inherited from Instance: Show Hide

    void

    ClearAllChildren ( )

    This function destroys all of an Instance’s children.
    Instance

    Clone ( )

    Create a copy of an object and all its descendants, ignoring objects that are not Instance/Archivable|Archivable
    void

    Destroy ( )

    Sets the Instance/Parent property to nil, locks the Instance/Parent property, disconnects all connections and calls Destroy on all children.
    Instance

    FindFirstAncestor ( string name )

    Returns the first ancestor of the Instance whose Instance/Name is equal to the given name.
    Instance

    FindFirstAncestorOfClass ( string className )

    Returns the first ancestor of the Instance whose Instance/ClassName is equal to the given className.
    Instance

    FindFirstAncestorWhichIsA ( string className )

    Returns the first ancestor of the Instance for whom Instance/IsA returns true for the given className.
    Instance

    FindFirstChild ( string name , bool recursive )

    Returns the first child of the Instance found with the given name.
    Instance

    FindFirstChildOfClass ( string className )

    Returns the first child of the Instance whose Instance/ClassName|ClassName is equal to the given className.
    Instance

    FindFirstChildWhichIsA ( string className , bool recursive )

    Returns the first child of the Instance for whom Instance/IsA returns true for the given className.
    Instance

    GetActor ( )

    Variant

    GetAttribute ( string attribute )

    Returns the attribute which has been assigned to the given name
    RBXScriptSignal

    GetAttributeChangedSignal ( string attribute )

    Returns an event that fires when the given attribute changes
    Dictionary

    GetAttributes ( )

    Returns a dictionary of string → variant pairs for each of the Instance|Instance’s attributes
    Objects

    GetChildren ( )

    Returns an array containing all of the Instance’s children.
    string

    GetDebugId ( int scopeLength )

    [NotBrowsable]

    Returns a coded string of the Instances DebugId used internally by Roblox.
    Array

    GetDescendants ( )

    [CustomLuaState]

    Returns an array containing all of the descendants of the instance
    string

    GetFullName ( )

    Returns a string describing the Instance’s ancestry.
    RBXScriptSignal

    GetPropertyChangedSignal ( string property )

    Get an event that fires when a given property of an object changes.
    bool

    IsA ( string className )

    [CustomLuaState]

    Returns true if an Instance’s class matches or inherits from a given class
    bool

    IsAncestorOf ( Instance descendant )

    Returns true if an Instance is an ancestor of the given descendant.
    bool

    IsDescendantOf ( Instance ancestor )

    Returns true if an Instance is a descendant of the given ancestor.
    void

    Remove ( )

    [Deprecated]

    Sets the object’s Parent to nil, and does the same for all its descendants.
    void

    SetAttribute ( string attribute , Variant value )

    Sets the attribute with the given name to the given value
    Instance

    WaitForChild ( string childName , double timeOut )

    [CustomLuaState] [CanYield]

    Returns the child of the Instance with the given name. If the child does not exist, it will yield the current thread until it does.
    Objects

    children ( )

    [Deprecated]

    Returns an array of the object’s children.
    Instance

    clone ( )

    [Deprecated]
    void

    destroy ( )

    [Deprecated]
    Instance

    findFirstChild ( string name , bool recursive )

    [Deprecated]
    Objects

    getChildren ( )

    [Deprecated]
    bool

    isA ( string className )

    [Deprecated] [CustomLuaState]
    bool

    isDescendantOf ( Instance ancestor )

    [Deprecated]
    void

    remove ( )

    [Deprecated]

    Events

    RBXScriptSignal

    AnimationPlayed ( Instance animationTrack )

    [Deprecated]

    Fires when an AnimationTrack begins playing on the Humanoid
    RBXScriptSignal

    Climbing ( float speed )

    Fires when the speed at which a Humanoid is climbing changes
    RBXScriptSignal

    CustomStatusAdded ( string status )

    [Deprecated]

    Fired when a status is added to the Humanoid.
    RBXScriptSignal

    CustomStatusRemoved ( string status )

    [Deprecated]

    Fired when a status is removed from the Humanoid.
    RBXScriptSignal

    Died ( )

    Fires when the Humanoid dies
    RBXScriptSignal

    FallingDown ( bool active )

    Fires when the Humanoid enters or leaves the FallingDown Enum/HumanoidStateType
    RBXScriptSignal

    FreeFalling ( bool active )

    Fires when the Humanoid enters or leaves the Freefall Enum/HumanoidStateType
    RBXScriptSignal

    GettingUp ( bool active )

    Fires when the Humanoid enters or leaves the GettingUp Enum/HumanoidStateType
    RBXScriptSignal

    HealthChanged ( float health )

    Fires when the Humanoid/Health changes
    RBXScriptSignal

    Jumping ( bool active )

    Fires when the Humanoid enters and leaves the Jumping Enum/HumanoidStateType
    RBXScriptSignal

    MoveToFinished ( bool reached )

    Fires when the Humanoid finishes walking to a goal declared by Humanoid/MoveTo
    RBXScriptSignal

    PlatformStanding ( bool active )

    Fires when the Humanoid enters or leaves the PlatformStanding Enum/HumanoidStateType
    RBXScriptSignal

    Ragdoll ( bool active )

    Fires when the Humanoid enters or leaves the Ragdoll Enum/HumanoidStateType
    RBXScriptSignal

    Running ( float speed )

    Fires when the speed at which a Humanoid is running changes
    RBXScriptSignal

    Seated ( bool active , Instance currentSeatPart )

    Fired when a Humanoid either sits in a Seat or VehicleSeat or gets up
    RBXScriptSignal

    StateChanged ( HumanoidStateType old , HumanoidStateType new )

    Fired when the state of the Humanoid is changed
    RBXScriptSignal

    StateEnabledChanged ( HumanoidStateType state , bool isEnabled )

    Fires when Humanoid/SetStateEnabled is called on the Humanoid
    RBXScriptSignal

    StatusAdded ( Status status )

    [Deprecated]

    Fired when a status is added to the Humanoid.
    RBXScriptSignal

    StatusRemoved ( Status status )

    [Deprecated]

    Fired when a status is removed from the Humanoid.
    RBXScriptSignal

    Strafing ( bool active )

    Fires when the Humanoid enters or leaves the StrafingNoPhysics Enum/HumanoidStateType
    RBXScriptSignal

    Swimming ( float speed )

    Fires when the speed at which a Humanoid is swimming in Terrain water changes
    RBXScriptSignal

    Touched ( Instance touchingPart , Instance humanoidPart )

    Fires when one of the Humanoid|Humanoid's limbs come in contact with another BasePart

    Inherited from Instance: Show Hide

    RBXScriptSignal

    AncestryChanged ( Instance child , Instance parent )

    Fires when the Instance/Parent property of the object or one of its ancestors is changed.
    RBXScriptSignal

    AttributeChanged ( string attribute )

    Fires whenever an attribute is changed on the Instance
    RBXScriptSignal

    Changed ( string property )

    Fired immediately after a property of an object changes.
    RBXScriptSignal

    ChildAdded ( Instance child )

    Fires when an object is parented to this Instance.
    RBXScriptSignal

    ChildRemoved ( Instance child )

    Fires when a child is removed from this Instance.
    RBXScriptSignal

    DescendantAdded ( Instance descendant )

    Fires when a descendant is added to the Instance
    RBXScriptSignal

    DescendantRemoving ( Instance descendant )

    Fires immediately before a descendant of the Instance is removed.
    RBXScriptSignal

    childAdded ( Instance child )

    [Deprecated]

    Code Samples

    Walking Camera Bobble Effect

    This LocalScript makes the camera bobble as the player’s character walks around, utilizing both the Humanoid’s CameraOffset and MoveDirection.
    It should be parented inside of the StarterCharacterScripts so that it is distributed into a player’s character as expected.

    local RunService = game:GetService("RunService")

local playerModel = script.Parent
local humanoid = playerModel:WaitForChild("Humanoid")

local function updateBobbleEffect()
	local now = tick()
	if humanoid.MoveDirection.Magnitude > 0 then -- Are we walking?
		local velocity = humanoid.RootPart.Velocity
		local bobble_X = math.cos(now * 9) / 5
		local bobble_Y = math.abs(math.sin(now * 12)) / 5
		
		local bobble = Vector3.new(bobble_X,bobble_Y,0) * math.min(1, velocity.Magnitude / humanoid.WalkSpeed)
		humanoid.CameraOffset = humanoid.CameraOffset:lerp(bobble,.25)
	else
		-- Scale down the CameraOffset so that it shifts back to its regular position.
		humanoid.CameraOffset = humanoid.CameraOffset * 0.75
	end
end

-- Update the effect on every single frame.
RunService.RenderStepped:Connect(updateBobbleEffect)
    ForceField HumanoidDescription