roblox-characters

Roblox 角色

将 Player 视为持久身份，将每个 Character 视为可替换的会话；每个会话都有自己的引用、连接、动画轨道和清理流程。面向 Roblox 持续更新的平台 API。

适用场景

• 用于玩家角色生命周期、Humanoid 状态／移动、角色模型、动画、工具、配件、自定义角色、死亡或重生方面的问题。
• 只要代码存储的 Character／Humanoid／根部引用跨越一次生成，就适用。

不适用场景： 通用物理查询和约束请使用 roblox-physics；远程信任请使用 roblox-networking；摄像机逻辑请使用 camera-systems。

工作流

1. 检查角色契约。 检查头像设置、StarterCharacter、StarterCharacterScripts、CharacterAutoLoads、R6／R15 支持、现有的 Animate／控制器脚本、工具、标签、碰撞组，以及服务器／客户端所有权。
2. 区分作用域。 Player 作用域状态会在重生后保留；角色作用域状态不会。将角色连接／轨道／资源放在同一个清理作用域中，并在移除角色时销毁该作用域。
3. 绑定现有角色和未来角色。 连接 CharacterAdded，然后在 player.Character 存在时绑定它。不要假设仅订阅事件就能捕获已经生成的角色。
4. 防御性地解析所需组件。 在复制情况需要时，使用超时等待；验证 Humanoid、根部、Animator 和角色模型假设。在应用延迟操作前，如果该角色已不再是当前角色，则中止。
5. 选择移动控制权。 标准角色使用 Humanoid 移动；只有需要物理控制的机制才使用 AssemblyLinearVelocity、BasePart:ApplyImpulse() 或 LinearVelocity／AlignPosition 约束。明确游戏逻辑权威和网络所有权方面的影响。
6. 管理动画生命周期。 通过角色模型的 Animator 加载动画；存储轨道／连接；仅在服务器验证的情况下，使用命名标记控制游戏逻辑时序；角色清理时停止动画／断开连接。
7. 验证生命周期压力场景。 测试生成、死亡、重置、快速重生、切换角色模型（若支持）、装备／丢弃工具、设置期间离开，以及在角色交互重要时至少用两名玩家运行。

模式：可替换的角色作用域

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

如果项目已有清理工具，请使用它；不要为了三个连接引入新框架。服务器系统会为每个 Player 重复此绑定，并在 PlayerRemoving 时清除玩家作用域表。

模式：通过 Animator 和标记播放动画

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()

对于没有 Humanoid 的角色模型，请使用带有 Animator 的 AnimationController。不要用已弃用的便捷方式来替代对实际 Animator 和轨道生命周期的管理。

移动与角色绑定规则

• 如果支持 R6，请勿将 R15 肢体名称硬编码。优先使用附件、标签或绑定类型适配器；仅在拓扑结构存在实质差异时，才根据 Humanoid.RigType 分支处理。
• HumanoidRootPart 通常是角色装配体的根部，但并非所有自定义模型都必定具备。请定义自定义绑定的契约，并在角色生成时进行验证。
• 普通角色移动优先使用 Humanoid:Move()／标准控制。直接更改 AssemblyLinearVelocity 是瞬时物理操作；只有在确实需要持续或瞬时物理效果时，才使用力／约束或冲量。
• 若要重新绑定移动／跳跃操作，或添加冲刺等操作，优先使用输入操作系统（在编辑时定义且支持跨设备的 InputContext／InputAction／InputBinding），而不是直接连接 UserInputService。启用 Workspace.PlayerScriptsUseInputActionSystem 后，默认玩家和角色控制脚本会运行在该系统上，并公开默认的 PlayerScripts 上下文；为自定义的 InputContext 设置更高的 Priority（并设置 Sink），即可优先于默认绑定。有关 UI 焦点方面的内容，请参阅 roblox-ui 输入与导航参考。
• 绝不能仅因客户端拥有其角色物理模拟的所有权，就授予其造成伤害或控制移动的权限。对于会影响其他玩家的操作，必须在服务器上进行验证。
• 装备工具时，工具会在 Backpack 和 Character 之间移动；请监听生命周期／状态，而不要假设工具始终属于某个固定父级。通过当前角色 API 修改配件／外观，并在编辑角色外观时保留最新应用的 HumanoidDescription。

常见故障

现象	可能原因	解决方法
运行一次后正常，重置后失效	缓存的角色／Humanoid／根部对象	每次 CharacterAdded 后重新构建；移除时清理
死亡后回调触发两次	旧角色的连接未清理	执行角色级清理，并检查代数／当前角色
延迟加载修改了错误的绑定	异步任务的存续时间超出角色生成周期	每次让出执行后，都比较当前 Character／代数
动画仅在本地可见或完全不可见	Animator／上下文／资源所有权错误	检查绑定中的 Animator、执行端、权限和复制行为
命中标记判定了不可能的命中	将动画标记当作权威依据	用标记控制时序／展示；由服务器验证战斗状态
R6／自定义绑定报错	假设存在 R15 名称	定义绑定契约；使用附件／适配器；测试每种受支持的绑定
工具从系统中消失	假设工具属于固定的 Backpack／Character 父级	处理装备／卸下时的祖先关系变化及角色替换
自定义力与 Humanoid 冲突	两个控制器同时控制移动	每种状态选择唯一的移动控制方，并在结束后妥善恢复

资源

• 阅读 references/lifecycle-and-animation.md，了解服务器绑定、死亡与移除的区别、绑定和动画验证、自定义角色以及生命周期压力测试矩阵。

相关技能

• roblox-physics — 力、约束、装配体、碰撞和网络所有权。
• roblox-networking — 服务器对角色操作及过期请求的验证。
• input-systems — 操作映射和响应式移动意图。
• camera-systems — 跟随可替换角色的摄像机行为。

主要参考资料

• https://create.roblox.com/docs/characters
• https://create.roblox.com/docs/animation/using
• https://create.roblox.com/docs/characters/appearance