Beginner's guide to Humanoids

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.

46 Likes

Just something to add; humanoids lag… like a lot. Avoid them if you can, or use luanoids where possible.

5 Likes

I agree and disagree,

Using humanoids badly can cause a lot of lag, and yes it is a lot. However if you learn how to use them well i personally have achieved 300 hunt and kill humanoid rigs with neglible lag.

I also have a custom humanoid system and I tested the same system on that, while they were more efficient the difference was too small to really care about, and given the extra work and the lack of features I don really think it’s always worth the playoff.


Then again it does depend what you want from them, for example if you just wanted 100 robloxians cheering in the stands then you would be better off without humanoids.

6 Likes

I use Animation Control more, but this was helpful!

2 Likes