Humanoids are essentially used instances in Roblox and foundations for the bodies of characters. This tutorial explains the API and uses of functions, events, and properties.
Basic properties & HumanoidRootPart
Humanoid has the well known properties, Health, MaxHealth, and WalkSpeed. The default max health is 100 and default WalkSpeed is 16. WalkSpeed is measured in studs per second.
You can affect a player’s health by manually changing health or using :TakeDamage(), best to avoid damaging when a forcefield is on the character.
There is also JumpPower which determines the upward force you can jump constrained from 0 to 1000 and default at 50. There is a UseJumpPower property (enabled by default) if disabled, just forces the JumpPower to be just like default.
You can read the rig type with RigType property (R6/R15).
The HumanoidRootPart is found by locating it like you normally do with a child, :WaitForChild() and :FindFirstChild(). Humanoid however, has a property called RootPart that may be convenient when the Humanoid is already a defined variable.
The HumanoidRootPart can be found either using the property RootPart (aforementioned) or just as normal children finding methods (aforementioned) or the PrimaryPart of the Character model.
The HumanoidRootPart is especially used to teleport Humanoid bodies, just set their CFrame and it’ll bring the whole character with it or you can use :SetPrimaryPartCFrame() on the body model (Character for example) alternatively.
RootPart property can be nil or the actual RootPart, for if statements that need to check the RootPart’s existence (if the Humanoid’s body has fallen into the void, the RootPart is nil).
SeatPart references the seat the Humanoid is sitting in (if it is sitting in one) which when they’re sitting, enables the Sit property of Humanoid.
:MoveTo(Vector3)
The :MoveTo function is a function that takes in a Vector3 argument into the Humanoid and commands the Humanoid to move to that Vector3.
This also changes the WalkToPoint property of Humanoid to the Vector3 argument.
It can take a second argument: a part that the Humanoid will move to while staying relative with the first argument position. It edits the WalkToPart property.
This is commonly used in NPCs that track other players. Some beginners go through the whole workspace to fight a target for a NPC. Instead, you should loop through players instead to find the nearest player, check the example code below.
:MoveTo for nearest players
local NPCHumanoid = script.Parent.Humanoid
local NPCRootPart = NPCHumanoid.RootPart
local gamePlayers = game.Players
while true do
local players = gamePlayers:GetChildren()
if #players == 0 then
gamePlayers.PlayerAdded:Wait()
continue
end
local closestDistance = 100 -- max range
local closestPosition
for _, player in pairs(players) do
local character = player.Character
local humanoid = character.Humanoid
local hrpPos = humanoid.RootPart.Position
local dist = (NPCRootPart.Position - hrpPos).Magnitude
if dist < closestDistance then
closestDistance = dist
closestPosition = hrpPos
end
end
NPCHumanoid:MoveTo(closestPosition)
end
Humanoid and the Camera
Humanoid is normally used as the CameraSubject for players’ characters so that the camera focuses on their character. There is also a CameraOffset property that can set a relative offset to the Humanoid (10 studs above the Humanoid for example).
Humanoid States
Humanoid states are in Enums called HumanoidStateTypes (which you can look here for reference of what they are defined as).
Only one state exists at a time so you can get this state through calling :GetState() on the Humanoid, which returns a HumanoidStateType Enum.
A state may be manually entered through :ChangeState() entering a state Enum argument. This is forcing a state so it may not keep the state for example if you try to make a player “swim” on land.
Two states (Flying, Physics) can only be set with :ChangeState() and one state called StrafingNoPhysics can never be set with :ChangeState().
You can manually set whether a state can be used as well with a boolean (true/false) through :SetStateEnabled() entering the state Enum argument and then the booelan value as the second argument. Once a state is disabled, it is no longer able to be entered even when using :ChangeState().
There are events related to the states, called StateChanged and StateEnabledChanged. StateChanged can be self-explained and StateEnabledChanged is called if :SetStateEnabled() is used.
Lastly, you can check if a state is enabled by using :GetStateEnabled().
Humanoid with manual tool functions
Humanoid has the following functions :EquipTool() and :UnequipTools(). :EquipTool() lets you equip a tool manually by putting the tool as an argument while :UnequipTools() unequips the currently equipped tool.
This is useful for custom inventories without Roblox’s backpack system.
Humanoid events
The useful events I will cover are Running, Died, and HealthChanged.
Running is fired each time the Humanoid’s speed changes, either by moving or stopping. It sends a speed parameter of how fast the Humanoid is going.
Died and HealthChanged are self-explanatory but they are useful in scenarios where the Humanoid’s health is important to track.
Humanoid & Animations
I won’t cover what the Animation and AnimationTrack instances are here but only how to use them. For brief use of Animation instances, you just create them with Instance.new and set their AnimationId.
The Humanoid uses :LoadAnimation() where you input the Animation instance that returns an AnimationTrack you can use to play animations with by calling :Play(). More details here.
When an AnimationTrack plays, the Humanoid event AnimationPlayed is called.
You may get all playing AnimationTracks by using :GetPlayingAnimationTracks() which returns a table. This can be used to stop animations you have not defined.
The functionality of running animations is not limited to Humanoids but can also be used on AnimationControllers which are substitutes for Humanoids when the properties of Humanoids are not needed that much.
HumanoidDescription system
HumanoidDescriptions can be used to set the appearance of the Humanoid including body colors, worn accessories, body scale, and clothing.
You can apply a HumanoidDescription by using :ApplyDescription() with it as an argument.
While you may be able to manually create a HumanoidDescription and set it to a Humanoid, you can get the HumanoidDescription of any Humanoid at all or even a specific player if you need this. You can fetch a HumanoidDescription of a Humanoid via :GetAppliedDescription().
For involving players that you want to get a HumanoidDescription for, you can use these functions on the Players service (game.Players):
Humanoid properties that changes the way Humanoid works
BreakJointsOnDeath prevents the separation of limbs from the body of a Humanoid if disabled which is by default enabled.
PlatformStand sets the Humanoid’s body in a state (Enum.HumanoidStateType.PlatformStanding) that prevents them from moving in a free-falling state.
Non-API section
This part of the tutorial will cover other things aside from how Humanoid works in general since you could really just reference the wiki for the most part.
When the Humanoid body falls into the void
As I previously mentioned, the HumanoidRootPart disappears when a character/NPC falls into the void. What remains is the Model representing the character/NPC and only the Humanoid.
Loading an animation on the client-side
If you’re ever trying to load an animation in a LocalScript and noticed an error called Humanoid is not a descendant of DataModel, this is due to the Humanoid having to wait to become a descendant of game (DataModel), here is an event-based approach that fixes that problem:
Solution
local humanoid = player.Character:WaitForChild("Humanoid") -- I find that you shouldn't use player.Character or player.CharacterAdded:Wait() when defining this.
while humanoid and not humanoid:IsDescendantOf(workspace) do
humanoid.AncestryChanged:Wait()
end
Some changes on the Humanoid replicates to the server from the client
Some of Humanoid’s properties will occur if changed from the client, this includes WalkSpeed and JumpPower, so you technically can cheat to increase your speed fast without authorization. The solution to this is to just constantly check the Humanoid’s position with a bit of extra leeway for latency.
Of players, their characters are not to be trusted by the server is the point here.
Detecting Humanoids
Commonly, lava bricks use their Touched property that gives a hit parameter which you can go through its Parent and use :FindFirstChild() to locate a Humanoid. This only works on body parts since Accessory parts are under an Accessory which you must then get a second parent if you want Accessories to detect Humanoids as well.
Humanoid also has a Touched property as well.
End
It’s important to learn Humanoids in the Roblox game environment. If you would like to learn more about Humanoids, check out the wiki API page for it.
EDIT
Simplified wording and trimmed the first half of the post down.