Roblox characters
Treat a Player as the durable identity and each Character as a replaceable session with its own
references, connections, animation tracks, and cleanup. Targets Roblox's rolling platform APIs.
When to use
- Use for player-character lifecycle, Humanoid state/movement, rigs, animations, tools,
accessories, custom characters, death, or respawn defects.
- Use whenever code stores a Character/Humanoid/root reference longer than one spawn.
When not to use: general physics queries and constraints belong to roblox-physics; remote
trust belongs to roblox-networking; camera logic belongs to camera-systems.
Workflow
- Inspect the character contract. Check avatar settings,
StarterCharacter,
StarterCharacterScripts, CharacterAutoLoads, R6/R15 support, existing Animate/controller
scripts, tools, tags, collision groups, and server/client ownership.
- Separate scopes. Player-scope state survives respawn; character-scope state does not. Put
character connections/tracks/resources in one cleanup scope and destroy it on removal.
- Bind existing and future characters. Connect
CharacterAdded, then bind player.Character
if present. Do not assume event subscription alone sees a character that already spawned.
- Resolve required components defensively. Wait with a timeout where replication warrants it;
validate
Humanoid, root, Animator, and rig assumptions. Abort if that character is no longer
current before applying delayed work.
- Choose movement ownership. Use Humanoid movement for standard avatars; use
AssemblyLinearVelocity, BasePart:ApplyImpulse(), or a LinearVelocity/AlignPosition
constraint only for mechanics that need physical control. Keep gameplay
authority and network ownership implications explicit.
- Own animation lifecycle. Load via the rig's
Animator; store tracks/connections; use named
markers for gameplay timing only with server validation; stop/disconnect on character cleanup.
- Verify lifecycle stress. Spawn, die, reset, rapid-respawn, swap rig if supported, equip/drop
tools, leave during setup, and run with at least two players when character interactions matter.
Pattern: replaceable character scope
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local generation = 0
local connections: {RBXScriptConnection} = {}
local currentCharacter: Model? = nil
local function clearCharacter()
generation += 1
for _, connection in connections do connection:Disconnect() end
table.clear(connections)
currentCharacter = nil
end
local function bindCharacter(character: Model)
-- Guard BEFORE teardown. A stale invocation (see the CharacterAdded/defer race below) must not
-- clear a binding that is already current, or nothing ends up bound at all.
if player.Character ~= character then return end
clearCharacter()
currentCharacter = character
local thisGeneration = generation
local humanoid = character:WaitForChild("Humanoid", 10)
local root = character:WaitForChild("HumanoidRootPart", 10)
-- Re-check after the yields: a respawn during WaitForChild bumps generation and makes this call stale.
if not humanoid or not root or generation ~= thisGeneration then return end
table.insert(connections, humanoid.Died:Connect(function()
if generation ~= thisGeneration then return end
setCharacterUiEnabled(false)
end))
attachCurrentCharacterSystems(character, humanoid, root)
end
player.CharacterRemoving:Connect(function(character)
if currentCharacter == character then clearCharacter() end
end)
player.CharacterAdded:Connect(bindCharacter)
if player.Character then task.defer(bindCharacter, player.Character) end
Use the project's cleanup utility when one exists; do not introduce a new framework for three
connections. Server systems repeat this binding per Player and clear player-scope tables on
PlayerRemoving.
Pattern: animation through Animator and markers
local animation = Instance.new("Animation")
animation.AnimationId = "rbxassetid://1234567890"
local track = animator:LoadAnimation(animation)
local markerConnection = track:GetMarkerReachedSignal("Commit"):Connect(function(parameter)
playLocalSwingEffect(parameter) -- presentation; server still validates any hit
end)
track:Play(0.1)
-- On character teardown:
markerConnection:Disconnect()
track:Stop(0.1)
animation:Destroy()
For rigs without a Humanoid, use an AnimationController with an Animator. Do not use the
deprecated convenience path as a substitute for owning the actual Animator and track lifecycle.
Movement and rig rules
- Do not hardcode R15 limb names if R6 is supported. Prefer attachments, tags, or a rig-type
adapter; branch on
Humanoid.RigType only where topology materially differs.
HumanoidRootPart is the usual character assembly root, not a universal guarantee for every
custom model. Define the custom rig contract and validate it at spawn.
- Prefer
Humanoid:Move()/standard controls for ordinary avatar locomotion. Directly changing
AssemblyLinearVelocity is an instantaneous physical action; use forces/constraints or impulses
when continuous or instantaneous physics is the real intent.
- To rebind movement/jump or add actions like sprint, prefer the Input Action System
(
InputContext/InputAction/InputBinding, defined at edit time and cross-device)
over hooking UserInputService directly. Default player and character control scripts
run on this system when Workspace.PlayerScriptsUseInputActionSystem is enabled,
exposing default PlayerScripts contexts; give your own InputContext a higher
Priority (and Sink) to take precedence over the default bindings. See the
roblox-ui input and navigation reference for the UI-focus side of this.
- Check whether the place opted into the Character Controller Library (beta; Avatar Settings ⟩
Movement ⟩ Abilities) or a
ControllerManager setup. Those replace HumanoidStateType-driven
logic with abilities/controllers, so extend that system instead of layering Humanoid state
changes on top of it.
- Never grant damage or movement authority because a client owns its character physics. Validate
cross-player consequences on the server.
- Tools move between Backpack and Character during equip; listen to lifecycle/state rather than
assuming one fixed parent. Modify accessories/appearance through current character APIs and
preserve an up-to-date applied
HumanoidDescription when editing avatar appearance.
Common failures
| Symptom |
Likely cause |
Remedy |
| works once, breaks after reset |
cached character/Humanoid/root |
rebuild per CharacterAdded; clear on removal |
| callbacks fire twice after deaths |
old character connections survived |
character-scoped cleanup and generation/current checks |
| delayed load edits wrong rig |
async work outlived spawn |
compare current Character/generation after every yield |
| animation visible only locally or not at all |
wrong Animator/context/asset ownership |
inspect rig Animator, execution side, permissions, and replication |
| hit marker awards impossible hit |
animation marker trusted as authority |
use marker for timing/presentation; server validates combat state |
| R6/custom rig errors |
R15 names assumed |
define rig contract; attachments/adapter; test each supported rig |
| tool disappears from system |
fixed Backpack/Character parent assumed |
handle equip/unequip ancestry and character replacement |
| custom force fights Humanoid |
two controllers own motion |
choose one movement authority per state and restore cleanly |
Resources
- Read
references/lifecycle-and-animation.md for server binding, death vs removal, rig and
animation verification, custom characters, and the lifecycle stress matrix.
Related skills
roblox-physics — forces, constraints, assemblies, collision, and network ownership.
roblox-networking — server validation of character actions and stale requests.
input-systems — action mapping and responsive movement intent.
camera-systems — camera behavior following replaceable characters.
Primary references
https://create.roblox.com/docs/characters
https://create.roblox.com/docs/animation/using
https://create.roblox.com/docs/characters/appearance
https://create.roblox.com/docs/characters/character-controller-library
1---2name: roblox-characters3description: >4 Build respawn-safe Roblox character systems around Players, CharacterAdded/CharacterRemoving,5 Humanoid, HumanoidRootPart, Animator, R6/R15 rigs, movement, animations and markers, death,6 tools, accessories, ownership, and custom characters. Use when character scripts break after7 respawn, cache stale Humanoids, control movement or velocity, load AnimationTracks, handle death,8 equip Tools, modify avatars, or support custom player rigs.9metadata:10 source: https://skillmd.com/skills/junmystery/roblox-characters11---1213# Roblox characters1415Treat a `Player` as the durable identity and each `Character` as a replaceable session with its own16references, connections, animation tracks, and cleanup. Targets Roblox's rolling platform APIs.1718## When to use1920- Use for player-character lifecycle, Humanoid state/movement, rigs, animations, tools,21 accessories, custom characters, death, or respawn defects.22- Use whenever code stores a Character/Humanoid/root reference longer than one spawn.2324**When not to use:** general physics queries and constraints belong to `roblox-physics`; remote25trust belongs to `roblox-networking`; camera logic belongs to `camera-systems`.2627## Workflow28291. **Inspect the character contract.** Check avatar settings, `StarterCharacter`,30 `StarterCharacterScripts`, `CharacterAutoLoads`, R6/R15 support, existing Animate/controller31 scripts, tools, tags, collision groups, and server/client ownership.322. **Separate scopes.** Player-scope state survives respawn; character-scope state does not. Put33 character connections/tracks/resources in one cleanup scope and destroy it on removal.343. **Bind existing and future characters.** Connect `CharacterAdded`, then bind `player.Character`35 if present. Do not assume event subscription alone sees a character that already spawned.364. **Resolve required components defensively.** Wait with a timeout where replication warrants it;37 validate `Humanoid`, root, `Animator`, and rig assumptions. Abort if that character is no longer38 current before applying delayed work.395. **Choose movement ownership.** Use Humanoid movement for standard avatars; use40 `AssemblyLinearVelocity`, `BasePart:ApplyImpulse()`, or a `LinearVelocity`/`AlignPosition`41 constraint only for mechanics that need physical control. Keep gameplay42 authority and network ownership implications explicit.436. **Own animation lifecycle.** Load via the rig's `Animator`; store tracks/connections; use named44 markers for gameplay timing only with server validation; stop/disconnect on character cleanup.457. **Verify lifecycle stress.** Spawn, die, reset, rapid-respawn, swap rig if supported, equip/drop46 tools, leave during setup, and run with at least two players when character interactions matter.4748## Pattern: replaceable character scope4950```lua51local Players = game:GetService("Players")52local player = Players.LocalPlayer53local generation = 054local connections: {RBXScriptConnection} = {}55local currentCharacter: Model? = nil5657local function clearCharacter()58 generation += 159 for _, connection in connections do connection:Disconnect() end60 table.clear(connections)61 currentCharacter = nil62end6364local function bindCharacter(character: Model)65 -- Guard BEFORE teardown. A stale invocation (see the CharacterAdded/defer race below) must not66 -- clear a binding that is already current, or nothing ends up bound at all.67 if player.Character ~= character then return end68 clearCharacter()69 currentCharacter = character70 local thisGeneration = generation71 local humanoid = character:WaitForChild("Humanoid", 10)72 local root = character:WaitForChild("HumanoidRootPart", 10)73 -- Re-check after the yields: a respawn during WaitForChild bumps generation and makes this call stale.74 if not humanoid or not root or generation ~= thisGeneration then return end7576 table.insert(connections, humanoid.Died:Connect(function()77 if generation ~= thisGeneration then return end78 setCharacterUiEnabled(false)79 end))80 attachCurrentCharacterSystems(character, humanoid, root)81end8283player.CharacterRemoving:Connect(function(character)84 if currentCharacter == character then clearCharacter() end85end)86player.CharacterAdded:Connect(bindCharacter)87if player.Character then task.defer(bindCharacter, player.Character) end88```8990Use the project's cleanup utility when one exists; do not introduce a new framework for three91connections. Server systems repeat this binding per `Player` and clear player-scope tables on92`PlayerRemoving`.9394## Pattern: animation through Animator and markers9596```lua97local animation = Instance.new("Animation")98animation.AnimationId = "rbxassetid://1234567890"99local track = animator:LoadAnimation(animation)100local markerConnection = track:GetMarkerReachedSignal("Commit"):Connect(function(parameter)101 playLocalSwingEffect(parameter) -- presentation; server still validates any hit102end)103104track:Play(0.1)105-- On character teardown:106markerConnection:Disconnect()107track:Stop(0.1)108animation:Destroy()109```110111For rigs without a `Humanoid`, use an `AnimationController` with an `Animator`. Do not use the112deprecated convenience path as a substitute for owning the actual Animator and track lifecycle.113114## Movement and rig rules115116- Do not hardcode R15 limb names if R6 is supported. Prefer attachments, tags, or a rig-type117 adapter; branch on `Humanoid.RigType` only where topology materially differs.118- `HumanoidRootPart` is the usual character assembly root, not a universal guarantee for every119 custom model. Define the custom rig contract and validate it at spawn.120- Prefer `Humanoid:Move()`/standard controls for ordinary avatar locomotion. Directly changing121 `AssemblyLinearVelocity` is an instantaneous physical action; use forces/constraints or impulses122 when continuous or instantaneous physics is the real intent.123- To rebind movement/jump or add actions like sprint, prefer the Input Action System124 (`InputContext`/`InputAction`/`InputBinding`, defined at edit time and cross-device)125 over hooking `UserInputService` directly. Default player and character control scripts126 run on this system when `Workspace.PlayerScriptsUseInputActionSystem` is enabled,127 exposing default `PlayerScripts` contexts; give your own `InputContext` a higher128 `Priority` (and `Sink`) to take precedence over the default bindings. See the129 `roblox-ui` input and navigation reference for the UI-focus side of this.130- Check whether the place opted into the Character Controller Library (beta; Avatar Settings ⟩131 Movement ⟩ Abilities) or a `ControllerManager` setup. Those replace `HumanoidStateType`-driven132 logic with abilities/controllers, so extend that system instead of layering Humanoid state133 changes on top of it.134- Never grant damage or movement authority because a client owns its character physics. Validate135 cross-player consequences on the server.136- Tools move between Backpack and Character during equip; listen to lifecycle/state rather than137 assuming one fixed parent. Modify accessories/appearance through current character APIs and138 preserve an up-to-date applied `HumanoidDescription` when editing avatar appearance.139140## Common failures141142| Symptom | Likely cause | Remedy |143|---|---|---|144| works once, breaks after reset | cached character/Humanoid/root | rebuild per `CharacterAdded`; clear on removal |145| callbacks fire twice after deaths | old character connections survived | character-scoped cleanup and generation/current checks |146| delayed load edits wrong rig | async work outlived spawn | compare current Character/generation after every yield |147| animation visible only locally or not at all | wrong Animator/context/asset ownership | inspect rig Animator, execution side, permissions, and replication |148| hit marker awards impossible hit | animation marker trusted as authority | use marker for timing/presentation; server validates combat state |149| R6/custom rig errors | R15 names assumed | define rig contract; attachments/adapter; test each supported rig |150| tool disappears from system | fixed Backpack/Character parent assumed | handle equip/unequip ancestry and character replacement |151| custom force fights Humanoid | two controllers own motion | choose one movement authority per state and restore cleanly |152153## Resources154155- Read `references/lifecycle-and-animation.md` for server binding, death vs removal, rig and156 animation verification, custom characters, and the lifecycle stress matrix.157158## Related skills159160- `roblox-physics` — forces, constraints, assemblies, collision, and network ownership.161- `roblox-networking` — server validation of character actions and stale requests.162- `input-systems` — action mapping and responsive movement intent.163- `camera-systems` — camera behavior following replaceable characters.164165## Primary references166167- `https://create.roblox.com/docs/characters`168- `https://create.roblox.com/docs/animation/using`169- `https://create.roblox.com/docs/characters/appearance`170- `https://create.roblox.com/docs/characters/character-controller-library`