godot-2d-animation

绝对不要做

• 绝对不要使用 AnimatedTexture — 此类已弃用，在现代渲染器中效率极低，并且可能会在未来的 Godot 版本中移除。请改用 AnimatedSprite2D 或 AnimationPlayer。
• 绝对不要让多个 Tween 争用同一属性 — 如果多个 Tween 为同一属性设置动画，最后创建的 Tween 会强行获得优先权。请始终将 Tween 赋值给变量，并在创建新的 Tween 前对上一个实例调用 kill()。
• 绝对不要在物理帧之外处理运动学移动 — 如果 AnimationPlayer 移动 CharacterBody2D，请确保将 AnimationPlayer 的回调模式设为 Physics。在 Idle（渲染）帧中为物理实体设置动画会破坏固定时间步物理插值，并导致卡顿。
• 绝对不要对循环动画使用 animation_finished — 此信号只会在非循环动画结束时触发。请改用 animation_looped 检测循环。
• 绝对不要调用 play() 并期待状态立即改变 — AnimatedSprite2D 会在下一帧处理时应用 play()。如果需要同步更新属性（例如同时更改动画和 flip_h），请在调用 play() 后立即调用 advance(0)。
• 绝对不要在保留动画进度时直接设置 frame — 设置 frame 会将 frame_progress 重置为 0.0。请使用 set_frame_and_progress(frame, progress)，以便在帧中途切换动画时保持平滑过渡。
• 绝对不要忘记缓存 @onready var anim_sprite — 在 _physics_process() 等高频路径中，节点查找 getter 的速度出乎意料地慢。请始终使用 @onready。
• 绝对不要混用 AnimationPlayer 轨道和代码驱动的 AnimatedSprite2D — 每个精灵只能选择一种动画控制方式。混用会导致闪烁和状态冲突。
• 绝对不要使用过于稀疏的骨架进行变形 — 2D 网格需要均衡的顶点密度。如果网格变形效果不佳，请在 Mesh2D 编辑器中增加关节附近的顶点数量。

---

可用脚本

必须遵守：请阅读你要实现的模式所对应的脚本。与这些脚本重复的内联示例已移除——脚本才是唯一可信来源。

根据场景不要加载

场景	加载	不要加载
单个角色 / 玩家	one_frame_sync_fix.gd、animation_state_sync.gd，可选 animation_tree_step.gd / tween_lifecycle_manager.gd	multimesh_swarm_anim.gd、gpu_mesh_optimizer.gd（除非填充率分析有此要求）
帧事件 / 碰撞箱 / SFX 同步	animation_sync.gd（以及 AnimationPlayer 方法轨道）	群集 / MultiMesh 脚本
挤压 / 拉伸的游戏手感	必须 procedural_squash_stretch.gd	此技能中的内联着陆条件片段
剪影 / IK 肢体	skeleton_2d_rig_helper.gd	MultiMesh 群集脚本
动画中的着色器闪烁 / 溶解	shader_hook.gd	—
数千只蝙蝠 / 鱼 / 道具	multimesh_swarm_anim.gd（以及鱼类教程文档）	为每个实体使用 AnimatedSprite2D / Tween 管理器

脚本索引

• one_frame_sync_fix.gd — 黄金同步路径：使用 play() + advance(0)，配合 flip_h / 属性更改。
• animation_state_sync.gd — 状态驱动的动画 + 转场队列。
• animation_sync.gd — 方法轨道、信号编排、混合空间钩子。
• animation_tree_step.gd — AnimationNodeStateMachinePlayback.travel()。
• procedural_squash_stretch.gd — 唯一来源，用于物理驱动的挤压与拉伸（不要在此重新实现着陆检测）。
• tween_lifecycle_manager.gd — 终止 / 重用 Tweens；防止属性冲突。
• skeleton_2d_rig_helper.gd — FABRIK/CCDIK 堆栈、静止姿势。
• shader_hook.gd — 将 AnimationPlayer 连接到 ShaderMaterial uniform。
• gpu_mesh_optimizer.gd — 将 Sprite 转换为紧凑的 2D 网格，以提升填充率。
• multimesh_swarm_anim.gd — 仅用于 GPU 群体运动。
• animation_data_extractor.gd — 将值 / 方法轨道与视觉 SpriteFrames 解耦，分离碰撞箱 / 生成元数据。
• procedural_walker_2d.gd — 通过射线检测目标进行 TwoBoneIK 足部固定（与 skeleton_2d_rig_helper.gd 配套）。
• sprite_sheet_memory_manager.gd — 线程化注入高分辨率帧 + 卸载，以应对 VRAM 峰值。

---

专家决策树：选择合适的动画工具

场景	推荐节点	专家见解
独立、纯逐帧精灵表	AnimatedSprite2D	无法为非视觉属性或方法轨道制作动画——需要这些功能时，请升级到 AnimationPlayer。
剪纸动画、非视觉同步、音频 / 粒子	AnimationPlayer	管理变换、网格变形、方法 / 值轨道。
复杂状态机、混合、移动	AnimationTree	构建在 AnimationPlayer 之上的逻辑图；通过 animation_tree_step.gd 使用 travel()。
程序化、动态、即用即弃的 UI/特效	Tween	运行时目标；始终通过 tween_lifecycle_manager.gd 操作。
数千个实体的群体	MultiMeshInstance2D + Shader	仅加载 multimesh_swarm_anim.gd；跳过角色同步脚本。

---

黄金路径：单帧同步（play + advance(0)）

在同一帧更改动画和精灵属性时，仅调用 play() 会等到下一个处理周期才生效，导致一帧闪烁。

必须：阅读 one_frame_sync_fix.gd。最简约定：

# After any play() that must match flip/modulate/etc. this frame:
anim.flip_h = dir < 0
anim.play(&"run")
anim.advance(0)  # force pose now

相关内容：循环动画使用 animation_looped，单次动画使用 animation_finished；在片段中途切换皮肤时，使用 set_frame_and_progress（参见 AnimatedSprite2D 类文档）。

---

程序化挤压与拉伸

不要将着陆代码片段粘贴到 Agent 中。之前的实现包含一个不可能成立的条件（not is_on_floor() and is_on_floor()）。

唯一指定来源：procedural_squash_stretch.gd — 处理冲击挤压、速度拉伸和 lerp 恢复。搭配 godot-characterbody-2d / godot-2d-physics，以确保地面 / 速度判定准确。

---

快速路由（脚本负责实现方案）

• Tween 中断 / 闪烁循环 → tween_lifecycle_manager.gd（切勿让两个 Tweens 同时争用一个属性）。
• AnimationTree 转场 → animation_tree_step.gd（先调用 start，再调用 travel）。
• IK 足部固定 → skeleton_2d_rig_helper.gd + SkeletonModification2DTwoBoneIK 文档。
• 填充率 / 群体 → 根据“禁止加载”表使用 gpu_mesh_optimizer.gd / multimesh_swarm_anim.gd。
• 像素滤镜 / 共享 SpriteFrames → 官方文档（2D 精灵动画、SpriteFrames）；通过 preload 保持资源共享。

专家见解（WHY — 保留在正文中）

• 混合剪纸 + 逐帧动画 — 为身体动作添加骨骼动画；对子精灵的 frame/texture 进行关键帧设置，以切换手部/面部。WHY：仅变换动画成本低；逐帧切换无需重新绑定骨骼，同时仍可由美术指导把控。
• GPU 填充率 — 大型透明精灵会浪费填充率。WHY：紧凑的 MeshInstance2D 多边形可跳过透明纹素；搭配 gpu_mesh_optimizer.gd 使用。
• Tween 属性冲突 — WHY：针对同一属性，最后一个 Tween 会静默生效。始终对之前的实例调用 kill()（tween_lifecycle_manager.gd）。
• AnimationTree 状态跳转 — WHY：StateMachine 会在状态之间使用内部 A*；调用 travel() 前先调用 start()（animation_tree_step.gd）。

深入配方（按需查阅）

主题	参考资料 / 脚本
信号 / 帧事件 / 皮肤切换	signals-and-frame-events.md
剪纸绑定 / 程序化 IK 足部	cutout-and-skeletal.md
GPU 网格 / 群集 / 内存流式传输	expert-techniques.md
帧元数据 / 生成偏移	animation_data_extractor.gd
异步 SpriteFrames 显存管理	sprite_sheet_memory_manager.gd

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接； 将工作转交给相关领域时再加载相关技能——不要预加载整个技能网络。

官方文档

• 2D 精灵动画 — 基于帧的图集和信号时序所采用的标准 AnimatedSprite2D + SpriteFrames 工作流。
• 动画功能简介 — 了解何时应从精灵图集转向使用 AnimationPlayer 来处理轨道、方法和非视觉属性。
• 剪纸动画 — 在使用完整骨骼 IK 前，了解纸娃娃层级结构以及混合剪纸/逐帧动画设置。
• 2D 骨骼 — 面向剪纸网格的 Skeleton2D / Bone2D 绑定、静止姿势和变形预期。
• 使用 AnimationTree — 用于驱动底层 AnimationPlayer 的混合空间和状态机图。
• 动画轨道类型 — 用于精确到帧的音效、命中框和着色器统一变量钩子的方法/值/属性轨道。
• AnimatedSprite2D — play()、advance()、set_frame_and_progress()，以及 animation_looped 与 animation_finished 的行为约定。
• SpriteFrames — AnimatedSprite2D 使用的共享帧资源、循环标记和每个动画的时序。
• Tween — 运行时挤压/拉伸和可中断的单次动作，无需烘焙 AnimationPlayer 动画片段。
• 为数千条鱼制作动画 — 群集运动所需的 GPU 顶点 / MultiMesh 模式，以摆脱节点树的限制。
• SkeletonModification2DTwoBoneIK — 适用于 Skeleton2D 骨骼层级中程序化脚部/手部定位的轻量级双骨骼 IK。

相关技能

前置条件

• godot-animation-player — AnimationPlayer 的所有权、回调模式和轨道编写；本技能的混合／剪影模式依赖这些内容。
• godot-characterbody-2d — 在物理帧中移动，确保动画驱动的 CharacterBody2D 运动保持在固定时间步长上。
• godot-signal-architecture — 安全连接 animation_finished / animation_looped / frame_changed，避免生命周期泄漏。

补充

• godot-animation-tree-mastery — 深入了解混合树、OneShot 层和 travel() 路径查找，超越此处介绍的 2D 移动基础。
• godot-tweening — 更全面地组合 Tween，适用于挤压／拉伸或 UI 弹出效果超出内联 create_tween() 代码片段所能满足的场景。
• godot-shaders-basics — 由 AnimationPlayer 轨道或 MultiMesh 群集材质驱动的 CanvasItem 着色器 uniform。
• godot-2d-physics — 为程序化形变提供冲击速度、用于 IK 目标的射线检测和插值规则。
• godot-state-machine-advanced — 应由游戏玩法 FSM 负责意图、由 AnimationTree/AnimatedSprite2D 负责呈现的场景。
• godot-particles — 通过方法轨道或帧事件生成的尘土、命中火花和拖尾。
• godot-adapt-3d-to-2d — 方向性图集、广告牌和伪深度排序，仍使用 2D 动画节点。

下游／使用方

• godot-genre-platformer — 跳跃／着地／奔跑的表现层会用到同步、挤压／拉伸和状态机跳转模式。
• godot-genre-fighting — 帧级精确的命中框和方法轨道依赖此处介绍的 AnimationPlayer + AnimatedSprite2D 使用规范。
• godot-resource-data-patterns — 共享 .tres SpriteFrames 和皮肤包，用于内存安全的多实例角色。

主入口

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。