Skip to Content
Kinemium

Humanoid

Give a character health, movement, jumping, and simple walk-to behavior.

Humanoid is the character controller's interface. Put one inside a character model and you get health, walk speed, jumping, and a small state machine with a dead state.

The humanoid doesn't move anything itself. It reads and writes the character controller that sits next to it in the character model, so its movement properties only have an effect when a controller exists.

Getting started

local character = player.Character
local humanoid = character:FindFirstChildOfClass("Humanoid")

if humanoid then
    print(humanoid.Health, humanoid.MaxHealth)
    humanoid.WalkSpeed = 20
end

Properties

PropertyTypeAccessDefaultDescription
HealthnumberRead/write100Current health, clamped between 0 and MaxHealth.
MaxHealthnumberRead/write100Upper bound for health. Negative values clamp to 0.
WalkSpeednumberRead/writeController valueMovement speed. Reads nil when there's no character controller.
JumpHeightnumberRead/writeController valueJump height. Reads nil without a controller.
AutoRotatebooleanRead/writeController valueWhether the character turns toward its movement direction.
HumanoidStateTypestringRead-onlyCurrent stateThe state machine's current state name, or nil when there's no controller.

Setting Health above MaxHealth is clamped, and dropping MaxHealth doesn't retroactively raise or lower health beyond the clamp. Health at 0 moves the character to the Dead state on the next update.

humanoid.MaxHealth = 250
humanoid.Health = 250

Methods

SignatureDescription
TakeDamage(amount: number): ()Subtracts health and fires HealthChanged.
Move(direction: Vector3): booleanSets the character's movement direction. Returns true when a controller was found.
Jump(): booleanQueues a jump. Returns true when a controller was found.
WalkTo(position: Vector3): booleanWalks toward a world position until it arrives or gets stuck.
MoveTo(position: Vector3): booleanAlias of WalkTo().
GetState(): string?Returns the current state name, or nil without a controller.
humanoid:TakeDamage(25)
humanoid:WalkTo(Vector3.new(10, 0, 10))

TakeDamage() only fires HealthChanged when the value actually changes, so hitting a dead humanoid doesn't produce a notification.

Move() takes a direction, not a speed. Scale it if you want slower or faster movement than the controller's default.

WalkTo() clears itself when the character gets within about 1.5 studs of the target, or after roughly two seconds without progress. It doesn't pathfind around obstacles, so use PathfindingService when the route isn't a straight line.

Events

EventCallback argumentsWhen it fires
HealthChangedhealth: numberHealth changed after damage or assignment.
StateChangedNot specifiedThe character's state changed.

StateChanged is forwarded from the character's state machine. The class doesn't guarantee a particular argument list, so inspect the value from a known state source instead of relying on the callback parameters.

humanoid.HealthChanged:Connect(function(health)
    print("Health is now", health)
end)

Notes

  • Movement properties are proxies. Without a CharacterController child in the model, reading them gives nil and writing them does nothing.
  • AutoRotate is a controller setting, not a humanoid one; it disappears with the controller.
  • Health is stored on the humanoid, so it survives character model setup as long as the model is kept.
  • Cloning a humanoid copies health and max health, but not its live walk target or connections.

See also

  • Players, loading characters and responding to spawns.
  • Model, moving the character model as a unit.
  • RunService, per-frame movement logic.

On this page