Godot AnimationLibrary 管理：角色动作、复用和版本更新的组织方式

动画数量上来后，AnimationPlayer 也需要治理

Godot 的 AnimationPlayer 很直观：创建动画，添加轨道，播放名称。角色少、动作少时非常舒服。项目扩大后，一个角色几十个动作，多个角色共用部分动作，剧情、战斗、UI 都有动画。动画名、库、复用、更新和引用开始变得复杂。如果所有动画都塞在一个 AnimationPlayer 里，维护会很痛苦。

Godot 的 AnimationLibrary 可以帮助组织动画。它允许把动画按库分组，运行时通过库和动画名访问。真正的价值不只是分类，而是让动作来源、版本和复用边界更清楚。

flowchart TD
    A[动作来源] --> B[AnimationLibrary]
    B --> C[Base Locomotion]
    B --> D[Combat Actions]
    B --> E[Emotes/Cutscene]
    F[AnimationPlayer] --> B
    G[状态机/Ability] --> H[动作 ID]
    H --> I[动画映射表]
    I --> F
    F --> J[运行时播放]

动画名要成为稳定接口

脚本里播放动画，实际是在引用一个字符串。attack_01、run_forward、hurt_light 一旦被状态机、技能配置、剧情轨道引用，就成为接口。随手改名会破坏很多地方。

建议定义动作 ID 和动画映射。技能配置引用 action_id，映射表决定当前角色使用哪个 AnimationLibrary 和动画名。这样不同角色可以用不同动画实现同一个动作 ID。角色没有某个动作时，也能有 fallback。

动画命名要规范：类别、方向、变体、版本。比如 combat/attack_light_01、locomotion/run_forward。不要使用导入工具生成的混乱名称作为业务引用。

Library 按来源和生命周期拆分

基础移动动作、战斗动作、表情动作、剧情专用动作可以放不同 AnimationLibrary。基础库多个角色共用，战斗库按武器或职业区分，剧情库只在特定 cutscene 加载。这样资源加载和维护更清楚。

不要为了分类把库拆得过碎。每次播放都要能找到动画，过多库会增加映射复杂度。拆分标准是来源和复用边界：谁维护、谁复用、什么时候加载。

剧情专用动画如果只在一段演出出现，不必常驻角色库。演出开始前加载对应库，结束后释放或卸载引用。这样主玩法角色资源更轻。

导入动画要保留人工映射

3D 动画常从 DCC 或动作库导入，名字可能不稳定。导入后应通过工具映射到项目动作 ID。不要让程序直接引用原始导入名。导入名变了，映射工具报错，人工确认后更新。

2D 动画也类似。Aseprite tag、SpriteFrames 动画名、AnimationPlayer 名，都要进入映射。统一动作 ID 能让技能、AI、剧情不关心底层动画来源。

映射表也能支持皮肤或体型差异。大型角色攻击动画可能更慢，但仍对应 attack_heavy_01。状态机只看动作事件和窗口配置，不硬编码具体动画名。

动画事件和版本

AnimationPlayer 动画里可能有方法轨道、音效事件、特效事件。动画更新时，这些事件也可能变化。需要工具检查关键事件是否存在：攻击动画必须有 hit_window_open，脚步动画必须有 footstep 事件，剧情动画必须有 camera marker。

动画版本更新后，旧配置可能引用不存在事件。构建前扫描动画和动作配置，发现缺事件就报错。不要等战斗里某个技能没有命中窗口才发现。

方法轨道调用要轻量。复杂业务逻辑不要写进动画事件，事件只通知时间点。规则仍由状态机或 Ability 系统执行。

运行时调试

动画问题需要可视化。调试面板显示当前 AnimationLibrary、当前动画、播放时间、速度、上一个动作 ID、事件触发记录。角色动作错了，先看映射是否正确，再看动画是否存在。

还可以做动作浏览器。选择角色，列出所有 action_id，逐个播放，显示缺失和 fallback。美术、策划和程序都能用。动作数量多时，这个工具非常省时间。

小结

Godot AnimationLibrary 管理的重点，是把动画从“可播放资源”变成“稳定动作接口”。用动作 ID 隔离脚本和具体动画名，按来源拆分库，导入后通过映射确认，构建前校验关键事件，运行时提供动作调试。动画越多，越需要这层治理。
我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。

我会把动作映射表作为角色资源的一部分，并在角色预览工具里显示每个 action_id 是否有实现。新增角色时先通过动作覆盖率检查，再进入玩法联调。