#Players and characters

This page covers the Players service, each Player, and the Humanoid that gives a character health and movement.

#The Players service

#Why ForEachPlayer

PlayerAdded only fires for players who join after you connect. A script that starts after someone arrived would miss them. ForEachPlayer handles both groups:

Players:ForEachPlayer(function(player)
    print("hello", player.Name)
end)

#The Player

#Properties

#Events

#Methods

#Chat

To message everyone, use the chat helper in Globals and services.

#Outfits

These server-side methods change what everyone sees. They also work on the player's Character and Humanoid. Accessories are identified by their catalog id.

#Limbs

A character has six parts a script can pose: Head, Torso, LeftArm, RightArm, LeftLeg and RightLeg (the Roblox spellings such as character["Left Arm"] work too). Use them for emotes, poses and small animations. They work on a player's Character and on a rig, and everyone sees the result.

-- Raise the right arm, make the head a little bigger, tint the left leg.
local character = player.Character
character.RightArm.Transform = CFrame.Angles(0, 0, math.rad(150))
character.Head.Scale = Vector3.new(1.3, 1.3, 1.3)
character.LeftLeg.Color = Color3.fromRGB(255, 80, 80)

Rotations turn the limb about its joint around the character's own axes, so the right arm raises with a turn about Z and swings forward and back with a turn about X. Tweens work on limbs: TweenService:Create(arm, TweenInfo.new(1), { Transform = CFrame.Angles(0, 0, math.rad(90)) }):Play(). For a loop of poses see the animation player in Examples.

Things to know:

• A limb you never touch keeps the built-in animation. A pose that goes back to nothing is dropped, so an untouched limb costs no network traffic.
• Numbers are limited: a shift is at most 64 studs and a scale at most 16, and NaN counts as zero.
• Poses are kept until you reset them. They are cleared when the character dies.
• A LocalScript can pose its own character, shown on that player's screen only.
• Anything can follow a limb: part:WeldTo(character.RightArm). See Welds.
• A dead character's limbs fall apart and ignore poses.

#Animations

A character plays one clip chosen by what it is doing: the run cycle while it moves, the jump clip in the air, and the rest pose otherwise. character.Animator (also rig.Animator and humanoid.Animator) lets a script play those clips itself and take over the automatic ones. Everyone sees the result.

The clips Studz ships are listed in animator.Clips: "Run" (it repeats; "Walk" is another name for it) and "Jump" (it plays once). They only move the arms and legs (Run) or the arms (Jump). Custom clips and an animation editor are not available yet.

The options of Play, all optional:

An option that does not exist, or a value of the wrong type, is an error that says what is allowed.

#Animation tracks

animator:Play returns a track.

-- Make an NPC run on the spot for three seconds, then ease out.
local guard = workspace.Guard
guard.Animator.Locomotion = false
local run = guard.Animator:Play("Run", { Speed = 2, Fade = 0.3 })
task.wait(3)
run:Stop(0.3)
print(run:Await())   --> Stopped

-- Swing only the arms, with the legs standing still.
local animator = player.Character.Animator
animator.Locomotion = false
animator:Play("Run", { Limbs = "Arms" })

-- Slow motion for a power-up: the built-in run cycle at half speed.
animator.LocomotionSpeed = 0.5

-- A jump flourish, then carry on.
local flourish = animator:Play("Jump", { Speed = 0.6 })
flourish.Finished:On(function(reason) print("done:", reason) end)

Things to know:

• A character plays at most four tracks at once. A fifth Play ends the one that has been playing longest (its Finished gives "Interrupted").
• Tracks are layered in the order they started: each one is blended over everything below it, limb by limb, by its Weight. Poses (limbs) are applied on top of all of it.
• A clip that does not loop ends by itself. Finished fires, and the limbs go back to what is below.
• When the character dies and respawns, its tracks are interrupted and Locomotion is true again.
• Only what is playing and how is sent to other players, not every frame. Each player's game keeps its own clock, so two screens can differ by a few frames.
• The server does not draw the characters, so a part welded to a limb follows the player and the limb's pose, but not a clip that is playing.
• A LocalScript can animate its own character, shown on that player's screen only.
• ResetLimbs removes poses and leaves tracks playing. animator:Stop() stops the tracks and leaves poses alone.

#Game passes and badges

Server only. See Earning on Studz for how to create them.

local VIP_PASS = 12
Players:ForEachPlayer(function(player)
    if player:HasGamePass(VIP_PASS) then
        player:Tell("Welcome back, VIP!")
    end
end)

#Clans

Server only.

#The Humanoid

Every character has a Humanoid. Find it with character:FindChild("Humanoid") or character.Humanoid.

Health, speed and jump power are decided by the server. A LocalScript cannot change them. A player's Humanoid has no HealthChanged yet: poll Health, or use Died. (Rigs below do have it.)

-- A lava part
lava.PlayerTouched:On(function(player, character)
    character.Humanoid:Damage(25)
end)

#Rigs (NPCs)

A Humanoid part placed in the workspace (Studio: Insert > Humanoid Dummy) is a rig: a character that no player controls. It is drawn as an avatar with a nametag, it is solid, and it has the same Humanoid a player does. A rig is its own character, so there is no model to dig through:

local guard = workspace.Guard        -- the rig part: Position, CFrame, Orientation, CanCollide ...
local humanoid = guard.Humanoid      -- its Humanoid (also FindChildOfClass("Humanoid"))
print(humanoid.Parent == guard, guard.HumanoidRootPart == guard)   --> true  true

Everything in the Humanoid table above works on a rig's Humanoid (Health, MaxHealth, Speed, JumpForce, DisplayName, :Damage, :Heal, .Died). The values are stored on the part, so they are saved with the place and set in the Studio Properties panel. DisplayName is the name shown over the rig; leave it empty to show the part's Name.

Rigs add these members:

When a rig's health reaches zero it fires Died, disappears and stops blocking the way. Setting Health above zero (or :Respawn()) brings it back. Walking rigs animate by themselves. Everything runs on the server.

A rig has the same six limbs as a player: guard.Head, guard.RightArm and so on. The poses are stored on the part with the rest of the rig's settings, so they are replicated to everyone, and guard.Humanoid:ResetLimbs() clears them. A rig that a script poses is the quickest way to build a looping dance or an idle animation for an NPC.

local guard = workspace.Guard.Humanoid
guard.DisplayName = "Captain Brick"
local a = workspace.Guard.Position
local b = a + Vector3.new(20, 0, 0)

-- Patrol back and forth, resting a second at each end.
local toB = true
guard.MoveToFinished:On(function()
    task.wait(1)
    toB = not toB
    guard:MoveTo(toB and b or a)
end)
guard:MoveTo(b)

guard.Died:On(function()
    task.wait(5)
    guard:Respawn()
end)

A rig walks through walls and does not follow the ground: :MoveTo only changes its X and Z. Rigs do not hurt players on touch; use a Touched handler on the rig part and Damage for that.