Index of every page on this site: llms.txt
All skills
gamedev-skills avatar

/roblox-characters

@c6ca6c4
Run it yourself

Roblox 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`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/roblox-characters

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈96 tokens for metadata: the name and description. ≈2.3k when used: this file. ≈708 more on demand in 2 files.

Description uses 4.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈385 characters, or 4.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

  1. 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.
  2. 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.
  3. Bind existing and future characters. Connect CharacterAdded, then bind player.Character if it already exists. On the server, do this for players already in Players:GetPlayers().
  4. Resolve parts defensively. WaitForChild with a timeout for Humanoid, the root part, and Animator; after every yield, check the character is still the current one before acting.
  5. 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.
  6. 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.
  7. Run the lifecycle check. With the Studio MCP server connected, start play, respawn the player several times from execute_luau on the Server datamodel (for _ = 1, 5 do player:LoadCharacterAsync() task.wait(1) end), then read get_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.RigType only where topology really differs.
  • HumanoidRootPart is the usual assembly root, not a guarantee for custom models. Write down the custom rig contract and validate it at spawn.
  • Setting AssemblyLinearVelocity is an instant change; use ApplyImpulse for one-off pushes and a LinearVelocity constraint for sustained control (details in roblox-physics).
  • For new actions such as sprint or rebinding jump, use the Input Action System (InputContext, InputAction, InputBinding) instead of raw UserInputService hooks. Give your context a higher Priority (and Sink) 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. Layering HumanoidStateType changes on top of it fights the library.
  • Tools move between Backpack and the character on equip. Listen to ancestry and the tool's Equipped/Unequipped events instead of assuming one parent.
  • Change appearance with Humanoid:ApplyDescriptionAsync() and keep the applied HumanoidDescription up 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 with Animator:GetTrackByAnimationId() instead of caching them. Tools are not fully supported there yet; see roblox-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.md when 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() and Humanoid:PlayEmote() are deprecated in favour of LoadCharacterAsync(), ApplyDescriptionAsync() and PlayEmoteAsync().
  • 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 the Player object on leave.
  • To re-check an API: append .md to its Creator Hub URL, or start from https://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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts9d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    The skill provides guidelines and patterns for managing Roblox character lifecycles, focusing on respawn safety and animation handling. It includes a testing workflow that uses agent tools to execute Luau code and inspect logs. A minor attack surface for indirect prompt injection exists where the agent parses tool output, which is standard for interactive development skills. No malicious behavior or obfuscation was detected.

  • Socket9d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/roblox-characters