scenario-roblox-animation

Roblox 动画和角色

目标平台：macOS 上的 Roblox Studio（2026 年 10 月构建版），通过 scenario-roblox-expert 工具包驱动。

这里所说的专家级，意味着每个片段、图层、IK 链和面部表现都要在 Studio 中用数据验证：哪些轨道控制各个关节、每个标记何时触发、服务器看到什么，以及逐帧推进的姿势是否与源数据一致。Agent 无法操作 Animation Editor，因此会通过代码构建片段，在 Edit 中逐帧推进，在 playtest 中播放，并测量关节和轨道，之后才会判定完成。如果这里提到的同级技能不在你的可用技能中，请让用户安装它（npx skills add scenario-labs/skills --skill <name>）；若无人值守，则根据工具架构继续操作，并标明这一缺口。

必备背景： scenario-roblox-expert（通道、审查流程、工具包、当前 Roblox 的常见陷阱）。

立场（专家级差异）

1. Avatar 关节是 AnimationConstraint，不是 Motor6D。 Avatar Joint Upgrade 使 R15 的 C0 和 C1 变为只读（L1、L8）。程序化运动会在 PreSimulation 中乘入 Transform，并以延迟批处理方式应用，且不会复制到客户端（Suphi Kaner，BRYp2-rdpXQ 00:00:33）。查找关节的代码必须同时支持这两种类。
2. 通过 Animator 加载动画，并由拥有骨架的一方负责。 拥有角色的客户端播放其轨道，服务器可以看到这些轨道（L6）；服务器播放 NPC 轨道，客户端可以看到这些轨道（L7）。Humanoid:LoadAnimation 已弃用。
3. 优先级划分关节；关键帧占用关节。 较高优先级只会控制它有关键帧的关节，恒等关键帧也会占用关节（L4）。通过代码构建片段时，仅用于路径的父级 Pose 必须将 Weight 设为 0，否则会覆盖较低优先级的轨道 [added]（L4）。
4. 用标记而非等待来控制游戏逻辑时序。 使用一个事件名称并附带参数（Develuper，d5GGIJJyMpg 00:02:52）。GetMarkerReachedSignal 会在一帧内触发（L6）；KeyframeReached 则需要使用命名关键帧（BrawlDev，zSK7bOoxuig 00:25:25）。
5. 面部表现通过片段播放，而非写入属性。 在玩家的动态头部上，FaceControls 写入或已完成的补间会在 0.5 秒内恢复为 0，即使所有轨道都已停止 [added]（L10、L16）。面部片段会保持效果、复制到客户端，并且不会被情绪动画覆盖。
6. 在服务器上创建 IKControls；注视目标的权重为 0.999。 权重为 1 时，目标移到身后会导致脖子扭转；IKControl.Priority 用于排列求解顺序；Pole 通过代码设置（Suphi Kaner，8fV-XOOj6O4 00:18:56、00:53:00、00:54:40）。
7. Blender 片段使用 24 fps，仅包含骨架，不包含缩放关键帧。 关闭 Leaf bones、NLA strips 和 All Actions；保持 Force Start/End Keying 和 Simplify 0 开启（Mykaiju，NI7GXKLwk6U 00:23:45 至 00:27:07）。60 fps 会使关键帧数量翻倍，却不会改善游戏表现（Nisky，EM9u4gIHoRg 00:07:55）。
8. 临时 id 是测试夹具。 RegisterKeyframeSequence 哈希和 active:// id 仅在 Studio 中有效；发布的游戏引用由体验所有者拥有的 rbxassetid:// id（Animation Editor 文档）。

先确认

• Rig 类型。 R15 avatar（AnimationConstraint、BallSocket 限制）、自定义部件 rig（Motor6D）、 蒙皮网格（Bones）或 AnimationController 生物。不要猜测，运行 P1。
• 谁播放什么。 客户端播放玩家动画片段，服务端播放 NPC 动画片段，装饰层在本地播放。
• 服务端权威。 启用后，Animator 最多保留 8 个活动轨道，每个 tick 都通过 GetTrackByAnimationId 查找轨道，绝不缓存。
• Character Controller Library。 启用后，移动由 ControllerManager 和能力驱动； 能力回调绝不让出执行权。
• 面部。 是否有动态头部（Head 是否包含 FaceControls）？
• 动作来源。 Blender FBX、Scenario 生成的 rig 或动作、Animation Editor，或代码。
• 发布所有者。 用户或群组；动画片段必须以体验所有者的名义发布。
• 默认值：R15，玩法动画片段使用 Action，移动动画使用 Idle 和 Movement，24 fps，标记以事件命名并带参数。

流程

每个步骤的代码都在 references/procedures.md（P1 到 P15）中，并附有运行该步骤的测试及其数据。

1. 检查 rig（P1）。 对模型运行 AnimRig.joints、AnimRig.tree 和 AnimRig.path。 GATE：已知关节类，每个动画部件都有一条从根部出发的路径，并且存在 Animator。
2. 构建或导入动画片段（P2、P3、P10）。 代码动画片段使用 AnimClip.keyframes 或 AnimClip.curves， 通过 AnimClip.register 注册，并使用 AnimClip.load 加载；它会等待 Length > 0。Blender 动画片段通过 blender_roblox_anim.py（审查、导出、采样）处理，再交给 AnimClip.fromSamples。GATE：阶梯式关节角度与关键帧的偏差在 0.3 度以内；Blender 骨骼末端的偏差在 0.01 studs 以内。
3. 图层与计时（P4）。 设置优先级、权重和淡入淡出；每个动画片段只为其控制的关节设置关键帧； 在接触帧添加标记。GATE：AnimClip.tracks(animator) 显示每个关节的预期胜出动画片段，且每个标记每个周期触发一次。
4. 在编辑模式中预览（P5）。 先调用 AnimClip.settle：自行结束的动画片段仍会混合到下一个动画片段中（P3）。rbx_animation.pose_sheet 使用 Animator:StepAnimations 逐步播放轨道，捕获每个时间点并生成一张接触表。GATE：检查接触表；帧间差异大于零；保存 place 前，AnimRig.reset 不会留下任何摆好姿势的关节。
5. 游戏测试（P6、P8）。 客户端播放玩家动画片段，服务端播放 NPC 动画片段；在两端读取关节。GATE：服务端能找到客户端的轨道，两端报告相同的关节角度，且捕获画面中显示了该姿势。
6. 图层、IK 和面部（P9、P12、P7）。 程序化偏移写入 PreSimulation 中的 Transform，并在 Animator.EvaluationThrottled 为 true 时跳过。IK 使用 AnimIK.reach 和 AnimIK.lookAt，面部使用 AnimFace.clip。GATE：服务端测得的颈部偏航角、IK 间隙和面部值，以及各一份捕获画面。
7. 默认值与审查（P13、P14）。 通过 Animate 值替换默认动画；运行 AnimAudit.all。GATE：没有错误或警告；状态改变后，客户端播放新动画片段，并通过 Length 和关节角度验证，而不是通过 id。
8. 发布清单。 列出每个要发布的动画片段、其优先级、循环设置、标记及所有者。 GATE：发布代码中没有临时 id（AnimAudit 规则 temp-animation-id）。

数值

值	数值	相对于
优先级顺序	Core < Idle < Movement < Action < Action2 < Action3 < Action4	Enum.AnimationPriority
默认 Animate 轨道	idle 为 Core，mood 为 Idle	L6，玩家角色
淡入	Play(0.4) 每 0.1 s 将权重提升 0.25	L4
相同优先级混合	加权平均：权重相同时，90 和 60 度得到 75 度；权重为 1 和 0.25 时得到 84 度	L4
权重为 0.5 的 Action 覆盖 Idle	在 90 和 30 度之间得到 60 度	L4
播放 0.25 s 时的标记	在 266 ms 触发，帧长 16.3 ms	L6，速度为 2
Stopped 和 Ended	播放时长为 0.5 s 时，分别为 500 和 816 ms	L6
自然结束后播放新片段	旧姿势会继续混合 0.25 到 0.375 s（在 0.25 s 时为 31.8 度，而不是 22.5 度）	L3
首次加载	LoadAnimation 时 Length 为 0；在 Edit 中加载需 14 ms	L2
45 度的颈部图层	关节为 41.9 度，头部相对根部偏转 45.5 度	L8
IK 可达范围	在 0.1 s 内，手与可达目标相距 0.20 到 0.23 studs；客户端结果相同	L9
IK 限制	与不可达目标相距 4.17 studs；Weight 为 0.5 时为 1.13 studs	L9
IK SmoothTime 为 0.5	间距在 0.6 s 内从 1.81 缩小到 0.37 studs	L9
注视目标	Weight 为 0.999；头部与目标的偏差小于 0.05 度	L9；Suphi Kaner
面部写入或补间	在 0.5 s 内恢复到 0	L10
面部片段	客户端和服务端的 JawDrop 均为 0.55；录制中可见张开的嘴巴	L10
从 Blender 导入 Studio	最差骨骼尾端误差为 0.0002 studs，共 10 根骨骼、25 帧	L12
蒙皮权重	每个顶点最多有 4 个影响源	蒙皮文档
Server Authority	每个 Animator 最多有 8 个活动轨道	Server Authority 文档
动态头部	4,000 个三角形；验证会检查来自 17 个 FACS 姿势的 5 个动画	规范；Roblox Learn，OwhkWzSBnf0

质量门槛

可衡量：

• AnimAudit.all(game) 不返回错误或警告（P14）。
• 代码播放的每个轨道在静止时均满足 Length > 0、具有预期优先级且 WeightCurrent 为 1（AnimClip.tracks）。
• 代码监听的每个标记在每个周期的指定时间触发一次，误差不超过一帧。
• 对于已复制的轨道，服务端和客户端报告相同的关节角度。
• Blender 导出通过 audit，且没有任何问题；P10 的尾部误差低于 0.01 studs。
• 保存 place 前，每个 rig 的 AnimRig.dirty 均为空。

视觉（接触表尺寸不超过 1,600 px，rbx_review.contact_sheet）：

• 每个片段在 4 到 6 个时间点的姿势表：剪影清晰、动作弧线流畅、无相互穿插、循环闭合。
• 游戏测试截图：玩家片段、NPC 片段、目标可见的 IK 触及动作，以及与中性表情截图并排的面部特写。
• 根据 references/critique.md 进行评判。

常见错误

错误	症状	修复
在 Core 或 Idle 上播放动画片段	播放了，但默认 Idle 占据优先级	将游戏动画片段设为 Action
动作动画片段为腿部关节设置关键帧	行走时腿部僵住	仅为动画片段拥有的关节设置关键帧
使用 Weight 1 父级创建代码构建的动画片段	上半身覆盖 Idle 和行走动画	对仅用于路径的 Pose 设置 Weight 0（AnimClip.keyframes）
刚注册后立即播放	没有动作，Length 为 0	AnimClip.load 会等待 Length > 0
在 avatar 关节上写入 C0	“属性为只读”	在 PreSimulation 中将其乘入 Transform
在 R15 上调用 FindFirstChildOfClass("Motor6D")	升级后的 avatar 返回 nil	AnimRig.joint 支持这两个类
对 FaceControls 使用 Tween	表情闪现后恢复中性状态	在 Animator 上播放 AnimFace.clip
使用 task.wait 控制命中时机	命中时机随速度和延迟而漂移	使用带参数的标记
在 Edit 中预览后留下姿势	保存的场景会显示该姿势	AnimRig.reset(rig)
在 Custom 蒙皮导入模型上使用 rig.HumanoidRootPart	nil：导入器将根节点命名为 RootPart（2 x 2 x 1），且骨骼永不发生碰撞	AnimRig.prepareImport；在此之前制作的动画片段仍会绑定（references/characters.md）
在另一个动画片段结束后立即测量	前 0.3 s 会向旧的结束姿势混合	在 Edit 中使用 AnimClip.settle；在游戏中使用刻意设置的淡入淡出
通过 id 检查被替换的默认动画	id 匹配，但播放的仍是旧动画	检查状态改变后的 Length 和关节
在 Blender 中使用 60 fps 或缩放关键帧	动画片段过大，缩放会被忽略	使用 24 fps，且仅使用旋转和位置关键帧
LookAt Weight 1	目标位于后方时颈部会扭曲	使用 0.999
发布临时 id	在 Studio 中可用，在线上环境中失效	在体验所有者名下发布
在客户端为共享 rig 创建 Animator	其他人看不到它	在服务器上创建它

移交

• 接收自 scenario-roblox-assets： 导入的骨架和蒙皮网格，包括使用 scenario-3d 生成的带骨架角色和动作。动作以 FBX 或 Blender 文件的形式提供，并经过 P10；骨架以 Models 的形式提供，由 P1 检查。
• 交付给 scenario-roblox-gameplay： 在接触帧带有标记的动画片段及其参数；游戏玩法负责调用这些动画片段的命中箱、状态和 NPC 行为。
• 交付给 scenario-roblox-vfx-audio： 脚步声、撞击和拖尾的标记名称与时间。
• 与 scenario-roblox-networking 协作： 视线方向同步、Server Authority 轨道规则、仅客户端的装饰层。
• 与 scenario-roblox-performance 协作： Animator 数量、NPC 剔除（将范围外的对象锚定并禁用 Animator，RDC 2025 rwLEnBtXr30 00:09:24）、stepAnimation 开销。
• 与 scenario-roblox-architecture 协作： 动画控制器的位置（玩家角色使用客户端模块，NPC 使用服务端服务）。
• 要求用户发布列出的动画片段；Agent 不会上传。

当前 Roblox 说明

• Avatar Joint Upgrade：R15 头像会生成 15 个 AnimationConstraint 关节和 14 个 BallSocketConstraints（L1）。
• 插件级 Luau 无法读取 Workspace.AuthorityMode（RobloxScript capability）：询问用户是否启用了 Server Authority。
• Character Controller Library 需选择启用。关闭时，客户端的 require("@rbx/AvatarAbilities") 永远不会返回，服务端则会返回一个表（L15）。
• Adaptive Animation：HumanoidRigDescription:AutoRig 需要 RobloxScript capability；关节映射和 T 姿在 Adaptive Animation 工具（GUI）中设置。通过代码映射关节无法将动画片段重定向到重命名后的部件（L14）。
• AnimationGraphDefinition 已存在；动画图在 Graph Editor（GUI）中编辑。
• 在当前 UI 中，可通过 Avatar > Clip Editor 打开 Animation Editor。

参考资料

• references/procedures.md：P1 至 P15，包含完整代码、测试 ID 和结果。
• references/characters.md：自定义蒙皮导入到骨架、玩家和 NPC 播放脚本、生物脚部着地、动态头部笼和验证、FBX 导入检查、角色开销。
• references/expert-notes.md：按专家整理的原则，附带时间戳。
• references/critique.md：评判动画作品的标准。
• references/gui-paths.md：供人类或计算机操作 Agent 使用的 Animation Editor、导入、面部和 Beta 开关路径。
• references/sources.md：所有来源及其凭据和时间戳。
• scripts/rbx_animation.py：工具包内联、Blender 封装器、示例加载器、Edit 姿势表。
• scripts/blender_roblox_anim.py：无头 Blender 测试骨架、审计、FBX 导出、重新导入和示例。
• scripts/agentkit/animation/：AnimRig、AnimClip、AnimAudit、AnimIK 和 AnimFace Luau 模块。