roblox-characters-animation

角色与动画

角色基础

• 玩家角色是一个 Model，包含 Humanoid、HumanoidRootPart（根部件；使用 character:PivotTo(cframe) 移动角色）、R15 身体部件，以及一个 Animate LocalScript。
• 默认值（行走速度、跳跃、生命值、R6/R15、碰撞、身体缩放）在 Studio 的 Avatar Settings 窗口和 StarterPlayer 中配置（CharacterWalkSpeed、CharacterJumpHeight 或 CharacterUseJumpPower + CharacterJumpPower）。
• 自定义角色：在 StarterPlayer 中放置一个名为 StarterCharacter 的 Model。按玩家自定义 生成：设置 Players.CharacterAutoLoads = false，然后在准备就绪时调用 player:LoadCharacterAsync() （例如数据加载完成后）。LoadCharacter（非 Async 版本）已弃用。
• 角色在死亡/重生时会被销毁并重新创建：在 CharacterAdded 中绑定每个角色的逻辑。
• 客户端设置的 WalkSpeed/JumpHeight 极易被利用；需在服务端强制限制，或使用 服务端权威（roblox-security、roblox-physics）。

生命值与伤害（服务端）

--!strict
local Players = game:GetService("Players")

local function damage(target: Model, amount: number, source: Player?)
	local humanoid = target:FindFirstChildOfClass("Humanoid")
	if not humanoid or humanoid.Health <= 0 then
		return
	end
	humanoid:SetAttribute("LastDamagedBy", if source then source.UserId else 0)
	humanoid:TakeDamage(amount) -- respects ForceField; use Health -= amount to bypass
end

Players.PlayerAdded:Connect(function(player)
	player.CharacterAdded:Connect(function(character)
		local humanoid = character:WaitForChild("Humanoid") :: Humanoid
		humanoid.MaxHealth = 150
		humanoid.Health = 150
		humanoid.Died:Once(function()
			local killerId = humanoid:GetAttribute("LastDamagedBy")
			print(`{player.Name} died (killer {killerId})`)
		end)
	end)
end)

return damage

• 通过 StarterCharacterScripts 删除/替换 Health 脚本以禁用默认回复。
• 布娃娃：Humanoid.BreakJointsOnDeath = false + 布娃娃约束。
• 状态：humanoid:ChangeState(Enum.HumanoidStateType.Jumping)、SetStateEnabled(state, false)、 StateChanged。MoveDirection、FloorMaterial、RootPart、SeatPart 是只读辅助属性。
• humanoid:MoveTo(position) 让 NPC 行走（8 秒后超时；长路径需重新发出——参见 roblox-npc-ai）。

外观

--!strict
local Players = game:GetService("Players")

local function applyUniform(player: Player)
	local character = player.Character
	local humanoid = character and character:FindFirstChildOfClass("Humanoid")
	if not humanoid then
		return
	end
	local ok, description = pcall(function()
		return Players:GetHumanoidDescriptionFromUserIdAsync(player.UserId)
	end)
	if not ok then
		return
	end
	description.Shirt = 123456 -- asset ids
	description.Pants = 654321
	description.HeightScale = 1.05
	pcall(function()
		humanoid:ApplyDescriptionAsync(description) -- server-side; replicates
	end)
end

return applyUniform

Player:LoadCharacterWithHumanoidDescriptionAsync(description) 可直接以某套装扮生成角色。 所有非 Async 变体（ApplyDescription、GetHumanoidDescriptionFromUserId 等）均已弃用。

动画播放

--!strict
local function playAttack(character: Model, animation: Animation): AnimationTrack?
	local humanoid = character:FindFirstChildOfClass("Humanoid")
	local animator = humanoid and humanoid:FindFirstChildOfClass("Animator")
	if not animator then
		return nil
	end
	local track = animator:LoadAnimation(animation) -- Humanoid:LoadAnimation is deprecated
	track.Priority = Enum.AnimationPriority.Action
	track.Looped = false
	track:GetMarkerReachedSignal("Hit"):Connect(function(param)
		print("hit frame reached", param) -- apply damage window, play sound, etc.
	end)
	track:Play(0.1) -- fade time
	return track
end

return playAttack

• 在哪里播放：本地玩家自己的角色 → 在客户端播放（通过其 Animator 自动复制）； NPC → 在服务端播放（或对于纯装饰性、数量众多的 NPC 在客户端播放）。
• 每个 Animator 只需加载每个 Animation 一次并复用轨道；不要在每次动作发生时都调用 LoadAnimation （每个 Animator 有轨道数量限制）。例外：服务端权威（查询实时轨道）。
• 优先级：Core < Idle < Movement < Action < Action2 < Action3 < Action4。使用 AdjustWeight 混合，使用 AdjustSpeed 改变速度，使用 Stop(fadeTime) 停止。
• 事件：track.Stopped、track.Ended，通过 GetMarkerReachedSignal 获取标记（KeyframeReached 已被取代）。
• 动画资源必须由体验的所有者拥有（或通过资源权限与之共享）—— 否则它们会在线上服务器中静默播放失败。
• 通过在 CharacterAdded 时编辑 Animate 脚本的 StringValue/Animation 子项 （animate.run.RunAnim.AnimationId）来替换默认动画，或在 StarterCharacterScripts 中提供自定义 Animate。
• 程序化：使用 IKControl（注视、脚部着地、伸手）而非手写关节数学。

补间动画

--!strict
local TweenService = game:GetService("TweenService")

local door = Instance.new("Part")
door.Anchored = true
door.Parent = workspace

local info = TweenInfo.new(0.6, Enum.EasingStyle.Quad, Enum.EasingDirection.Out)
local open = TweenService:Create(door, info, { CFrame = door.CFrame * CFrame.new(0, 8, 0) })
open.Completed:Once(function(state)
	print("door tween finished:", state)
end)
open:Play()

• 对锚定的部件或 UI 进行补间。对于未锚定/物理对象，使用约束。
• 在服务端补间会每帧复制并导致卡顿：对于纯视觉运动，在每个客户端上补间 （服务端设置最终状态或客户端响应的属性）。
• 模型：补间一个 CFrameValue 并在其 Changed 处理器中调用 model:PivotTo(value)，或补间 主部件并将其余部件焊接到它上面。
• TweenService:GetValue(alpha, style, direction) 用于自定义插值；SmoothDamp 用于跟随运动。

工具

StarterPack/Backpack 中的 Tool，带有一个 Handle 部件（或 RequiresHandle = false）。Equipped、 Unequipped、Activated 在客户端和服务端都会触发（Activated 来自客户端：需在服务端验证 频率和状态）。将武器逻辑放在模块中，并使用标签而非在每个工具克隆中放置脚本。

Character Controller Library（测试版）

Roblox 的 CCL（require("@rbx/AvatarAbilities")）用可组合的 能力（Running、Jumping、Climbing、自定义 Dash……）取代了固定的 Humanoid 状态机，这些能力由标签、传感器、条件（StartsWhen/RunsWhile，配合 All/Any/Not）、冲突（Blocks/Stops/Suspends）以及生命周期回调进行协调。通过 File → Beta Features 和 Avatar Settings → Movement → Abilities 启用它。仅当项目已选择启用时才使用；测试版期间 API 可能发生变化。 概要：references/character-controller-library.md。

相关技能

roblox-npc-ai（NPC 移动）、roblox-physics（布娃娃、击退）、roblox-input（能力输入）、 roblox-security（移动/伤害验证）、roblox-game-systems（战斗）。