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

Humanoid

Show deprecated

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.

    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

    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.
    This value is clamped between 0° and 89°.

    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.

    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

    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

    [ReadOnly] [NotReplicated] [Deprecated]

    The cost of saving the instance using data persistence.

    string

    Name

    A non-unique identifier of the Instance

    Instance

    Parent

    Determines the hierarchical parent of the Instance

    bool

    RobloxLocked

    If true, the Instance and its descendants cannot be indexed or edited by a Script or LocalScript and will throw an error if it is attempted

    bool

    archivable

    [Hidden] [NotReplicated] [Deprecated]
    string

    className

    [ReadOnly] [NotReplicated] [Deprecated]

    Functions

    void

    AddAccessory ( Instance accessory )

    Attaches the specified Accessory to the Humanoid

    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 )

    [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 ( )

    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 )

    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]
    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 deep copy of a Roblox instance and descendants where Archivable = true.

    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.

    Variant

    GetAttribute ( string attribute )

    RBXScriptSignal

    GetAttributeChangedSignal ( string attribute )

    Dictionary

    GetAttributes ( )

    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 )

    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 )

    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 )

    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)