godot-animation-player

AnimationPlayer

基于时间轴的关键帧动画：轨道选择、RESET、根运动、动画库——由脚本负责具体实现。

绝对不要

• 绝对不要忘记 RESET 轨道——否则动画属性会在场景切换后保持原值。
• 绝对不要将 Animation.CALL_MODE_CONTINUOUS 用于单次逻辑——请使用 CALL_MODE_DISCRETE。
• 绝对不要直接为嵌入式资源的属性制作动画——优先使用实例化 uniform／自有材质。
• 绝对不要将 animation_finished 用于循环片段——请使用 animation_looped 或轮询 current_animation。
• 绝对不要在大规模场景中硬编码动画名称字符串——使用常量／StringName。
• 当同一帧内的读取很重要时，绝对不要在未设置 update=true 的情况下调用 seek()。
• 绝对不要让屏幕外、仅用于视觉效果的播放器保持 active——使用通知器剔除。
• 绝对不要修改正在播放的 AnimationLibrary——先停止播放／等待播放完成。
• 绝对不要依赖 speed_scale 进行长时间同步——优先使用共享时钟调用 seek()。

---

可用脚本（强制触发条件）

在实现相应模式之前，先打开匹配的脚本。详细实现方案：track-authoring.md、root-motion-and-sequences.md、edge-cases.md。

需求	脚本
方法轨道命中／状态关键帧	method_track_logic.gd
姿态／武器动画库切换	runtime_anim_lib_swapper.gd
Shader uniform 时间轴	dynamic_shader_animation.gd
运行时轨道调整	procedural_track_modifier.gd
强制 RESET 编排	reset_track_orchestrator.gd
Bezier → 程序化驱动	bezier_curve_extraction.gd
屏幕外 active 剔除	active_animation_culler.gd
根运动 ↔ 物理	root_motion_physics_sync.gd
部件／装备轨道	character_part_swapper_tracks.gd
TYPE_AUDIO 脚步同步	precise_audio_sync.gd
排队／分支序列	animation_sequencer.gd
代码构建 Animation 资源	programmatic_anim.gd
备用音频轨道设置说明	audio_sync_tracks.gd

关键原因（保留在正文中）

• CALL_MODE_CONTINUOUS 会在关键帧时间跨度内每帧调用该方法——单次命中框／VFX 需要使用 CALL_MODE_DISCRETE。
• 为嵌入式子资源属性（例如 material.albedo_color）制作动画会将资源复制到场景中——请使用实例化材质／shader_parameter/* 轨道。
• 循环片段不会触发 animation_finished——请使用 animation_looped 或轮询 current_animation。
• 修改正在播放的 AnimationLibrary 会导致崩溃或变换异常——切换前先停止播放或等待播放完成。
• speed_scale 会在节奏同步／多人游戏中产生偏移——长时间同步应使用共享时钟调用 seek(t, true)。

轨道选择矩阵

轨道	适用场景	避免使用的场景
Value	为属性制作动画（位置、调制、uniform）	一次性运行时效果 → Tween
Method	在指定时间触发命中框、SFX 钩子、状态切换	CONTINUOUS 调用模式／路径上缺少对应方法
Audio	与帧锁定的脚步声／VO	不同步的 AudioStreamPlayer.play()
Bezier	在运行时采样自定义缓动曲线	简单的线性淡入淡出

轨道制作示例 → track-authoring.md。

根运动（物理）

CharacterBody3D + Skeleton3D + AnimationPlayer：在物理帧调用 get_root_motion_position()／旋转方法提取根运动——root_motion_physics_sync.gd。仅移动骨骼的步行循环会让物体碰撞体留在原地。

序列、混合、RESET

• 串联：animation_set_next / queue / animation_sequencer.gd。
• 为行走↔跑步打磨混合时间；使用 play("run", -1, 1.0, 0.5) 或 set_default_blend_time。
• 始终创建带有默认值的 RESET 片段；编辑时启用保存时重置。
• 反向播放：使用 play("clip", -1, -1.0) 实现门的反向运动或电影式倒带。

完整配方 → root-motion-and-sequences.md。

AnimationPlayer 与 Tween

需求	优先使用
时间轴／多个属性／可复用	AnimationPlayer
一次性运行时动画／可中断	Tween（godot-tweening）

专家级架构（脚本）

模式	脚本	原因
共享人形角色库	runtime_anim_lib_swapper.gd	一个库，多个模型——播放 lib/clip
解耦时间轴事件	method_track_logic.gd	方法轨道 → 信号发送器 → 游戏逻辑监听器
屏幕外 CPU 预算	active_animation_culler.gd	设置 active = false 或手动调用 advance()
通过代码构建片段	programmatic_anim.gd	FBX 中不存在的动态目标

参考

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

官方文档

• 动画功能简介 — 了解 AnimationPlayer 与 Tweens／精灵各自负责的时间轴，以及动画库、RESET 和编辑器如何配合使用。
• 动画轨道类型 — 值、方法、贝塞尔和音频轨道，以及此技能所用模式依赖的调用模式和关键帧规则。
• AnimationPlayer — play／queue／seek、混合时间、animation_finished 与 animation_looped 的区别，以及 active 剔除。
• Animation — 轨道 API（track_insert_key、调用模式、音频／贝塞尔辅助函数）以及长度／循环元数据。
• AnimationLibrary — 通过 add_animation_library 添加共享的姿势／武器片段包，无需为每个模型重复轨道。
• AnimationMixer — 用于物理同步和预算管理器的根运动获取器、回调处理模式和 advance()。
• 使用 AnimationTree — 了解何时应由混合／状态机驱动底层 AnimationPlayer，而不是手动使用 queue。
• Tween — 作为 AnimationPlayer 与 Tween 决策矩阵中对应项的运行时一次性动作。
• 添加动画（你的第一个 3D 游戏） — 在高级轨道制作之前，了解从导入到通过 AnimationPlayer 播放的实际流程。
• VisibleOnScreenNotifier3D — 用于切换 AnimationPlayer.active 以节省屏幕外 CPU 开销的屏幕进入／退出信号。

相关技能

前置条件

• godot-signal-architecture — 安全使用 animation_finished / animation_looped / 自定义方法轨道发出信号，避免生命周期泄漏。
• godot-resource-data-patterns — 共享 .tres AnimationLibrary 的所有权管理，确保运行时切换不会重复创建资源，也不会不安全地修改正在播放的资源。
• godot-gdscript-mastery — 类型化的程序化轨道生成、路径字符串和 Dictionary 方法轨道负载。

互补内容

• godot-animation-tree-mastery — 当移动逻辑超出 AnimationPlayer queue / set_next 的适用范围时，使用混合树、OneShot 层和 travel()。
• godot-2d-animation — AnimatedSprite2D / Skeleton2D 表现形式仍依赖 AnimationPlayer 方法轨道和属性轨道。
• godot-tweening — 当制作完整的 Animation 资源过于繁琐时，使用可中断的运行时补间。
• godot-shaders-basics — 使用值轨道（shader_parameter/*）驱动 ShaderMaterial uniform，而无需嵌入材质。
• godot-audio-systems — 围绕 TYPE_AUDIO 轨道进行总线／语音池管理，以及时间轴上的脚步声／音效时序。
• godot-physics-3d — 在物理帧中集成 CharacterBody3D，以提取根运动的位置／旋转。

下游／使用方

• godot-genre-fighting — 帧精准的命中框窗口，以及用于取消窗口的离散方法轨道。
• godot-genre-platformer — 适用于 2D/3D 移动角色的跳跃／落地／奔跑动画片段、RESET 规范，以及混合时长。
• godot-combat-system — 通过 AnimationPlayer 方法轨道发出伤害／VFX 事件的攻击时间线。

主入口

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