gamedev-skills/awesome-gamedev-agent-skills / skills/other-engines/roblox-characters
roblox-characters
VerifiedRoblox player characters: CharacterAdded lifecycle, Humanoid and HumanoidRootPart, R6, R15 and custom rigs, respawn and Tools. Use when a character script breaks after respawn, animations do not play or replicate, or sprint code fights the Humanoid. Not for hit validation (`roblox-networking`), forces and raycasts (`roblox-physics`) or cameras (`camera-systems`).
Roblox characters
A Player is the durable identity; each Character is a replaceable session with its own
references, connections, animation tracks, and cleanup. Most character bugs are one character's
state leaking into the next.
Workflow
- Read the character contract. Avatar Settings (rig type, movement system),
StarterCharacter,StarterCharacterScripts,Players.CharacterAutoLoads,Workspace.PlayerCharacterDestroyBehavior, the existing Animate or controller scripts, tools, tags, and collision groups. Extend what is there; do not add a second controller. - Separate scopes. Player-scope state survives respawn; character-scope state does not. Put each character's connections, tracks, and temporary instances in one cleanup scope.
- Bind existing and future characters. Connect
CharacterAdded, then bindplayer.Characterif it already exists. On the server, do this for players already inPlayers:GetPlayers(). - Resolve parts defensively.
WaitForChildwith a timeout forHumanoid, the root part, andAnimator; after every yield, check the character is still the current one before acting. - Choose one movement owner per state. Standard avatars use Humanoid movement or the Character Controller Library. Physical mechanics (dash, knockback, grapple) use an impulse or a constraint for their duration and hand control back cleanly.
- Own animation lifecycle. Load through the rig's
Animator, keep tracks and marker connections in the character scope, and stop them on cleanup. Markers drive presentation; any gameplay effect they trigger is validated on the server. - Run the lifecycle check. With the Studio MCP server connected, start play, respawn the
player several times from
execute_luauon theServerdatamodel (for _ = 1, 5 do player:LoadCharacterAsync() task.wait(1) end), then readget_console_output: expect no errors and exactly one setup log per spawn. Without MCP, ask the user to reset five times in Test and once with two players in Server & Clients, and to report duplicated logs, stuck animations, or errors.
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 call must not clear a binding that is already current.
if player.Character ~= character or currentCharacter == character then return end
clearCharacter()
currentCharacter = character
local thisGeneration = generation
local humanoid = character:WaitForChild("Humanoid", 10)
local root = character:WaitForChild("HumanoidRootPart", 10)
-- 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 rather than introducing a 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 only; the server validates any hit
end)
track:Play(0.1)
-- On character teardown:
markerConnection:Disconnect()
track:Stop(0.1)
animation:Destroy()
Rigs without a Humanoid need an AnimationController with an Animator. Humanoid:LoadAnimation()
is deprecated; always load through the Animator.
Movement and rig rules
- If R6 is supported, do not hardcode R15 limb names. Prefer attachments, tags, or a small rig
adapter; branch on
Humanoid.RigTypeonly where topology really differs. HumanoidRootPartis the usual assembly root, not a guarantee for custom models. Write down the custom rig contract and validate it at spawn.- Setting
AssemblyLinearVelocityis an instant change; useApplyImpulsefor one-off pushes and aLinearVelocityconstraint for sustained control (details inroblox-physics). - For new actions such as sprint or rebinding jump, use the Input Action System (
InputContext,InputAction,InputBinding) instead of rawUserInputServicehooks. Give your context a higherPriority(andSink) than the default player contexts so it wins. - If the place uses the Character Controller Library (Avatar Settings → Movement → Abilities) or a
ControllerManager, extend its abilities and controllers. LayeringHumanoidStateTypechanges on top of it fights the library. - Tools move between
Backpackand the character on equip. Listen to ancestry and the tool'sEquipped/Unequippedevents instead of assuming one parent. - Change appearance with
Humanoid:ApplyDescriptionAsync()and keep the appliedHumanoidDescriptionup to date. - Under Server Authority (
Workspace.AuthorityMode = Server), gameplay animation runs inside bound simulation functions and the client may replace tracks during rollback, so look tracks up each frame withAnimator:GetTrackByAnimationId()instead of caching them. Tools are not fully supported there yet; seeroblox-networking.
Gotchas
| Symptom | Likely cause | Remedy |
|---|---|---|
| works once, breaks after reset | cached character, Humanoid or root | rebuild per CharacterAdded; clear on removal |
| callbacks fire twice after deaths | old character connections survived | character-scoped cleanup plus generation checks |
| memory grows with every respawn | old characters are only unparented, and tables still reference them | clear Instance-keyed tables; check PlayerCharacterDestroyBehavior |
| delayed setup edits the wrong rig | async work outlived its spawn | compare current character or generation after every yield |
| animation plays only locally or not at all | wrong Animator, side, or asset permission | inspect the rig's Animator, who loads it, and the asset owner |
| hit marker awards impossible hits | marker trusted as authority | marker for timing; server validates combat state |
| R6 or custom rig errors | R15 names assumed | rig contract and adapter; test every supported rig |
| tool disappears from a system | fixed Backpack or Character parent assumed | handle equip, unequip, and character replacement |
| custom force fights the Humanoid | two controllers own motion | one movement owner per state; restore on exit |
Resources
- Read
references/lifecycle-and-animation.mdwhen a system spans respawns, supports several rigs, or owns animation and tool resources: server binding, death vs removal, custom-character checklist, and the lifecycle stress matrix.
Related skills
roblox-physics: forces, constraints, assemblies, and network ownership.roblox-networking: validating character actions and rejecting stale requests.input-systems: action mapping and responsive movement intent.camera-systems: cameras that follow a replaceable character.
Version notes
Last verified: 2026-11-11.
Player:LoadCharacter(),Humanoid:ApplyDescription()andHumanoid:PlayEmote()are deprecated in favour ofLoadCharacterAsync(),ApplyDescriptionAsync()andPlayEmoteAsync().- The Character Controller Library was announced as released for live experiences in April 2026; its docs page still carried a beta note on the verification date. Avatar Settings needs a saved or published place.
Workspace.PlayerCharacterDestroyBehavior, when enabled, destroys the old character on respawn and thePlayerobject on leave.- To re-check an API: append
.mdto its Creator Hub URL, or start fromhttps://create.roblox.com/docs/llms.txt.
Sources: https://create.roblox.com/docs/characters,
https://create.roblox.com/docs/animation/using,
https://create.roblox.com/docs/characters/character-controller-library,
https://create.roblox.com/docs/reference/engine/classes/Player,
https://create.roblox.com/docs/reference/engine/classes/Humanoid,
https://create.roblox.com/docs/reference/engine/classes/Workspace,
https://create.roblox.com/docs/projects/server-authority,
https://devforum.roblox.com/t/full-release-the-future-of-character-movement-character-controller-library/4565267.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |