用途
本技能面向 Bevy 引擎的动画混合场景。当动画片段需要混合(blend)、叠加(add)或遮罩(mask)时加载本技能;如果只是单片段播放,则仍使用 bevy-animation。
主要能力
- 动画图资源:AnimationGraph 描述片段如何混合。add_clip 添加一个片段节点,add_blend 添加一个混合节点,add_clip_with_mask 存储一个 u64 遮罩(由你分配的骨骼组,0 表示无遮罩)。
- 组件:AnimationGraphHandle 是同一实体上 AnimationPlayer 所用图的句柄;AnimationTransitions 用于在节点之间交叉淡入淡出。
- 权重:在播放之后,通过播放器上的 ActiveAnimation::set_weight 驱动已在图中的节点。
- 系统:求值仍通过动画播放器系统运行,不要添加第二个播放器。
使用方式
技能提供了完整的 Rust 代码示例,包括:
- 构建移动动画图(build_locomotion_graph):创建 AnimationGraph,用 add_blend 添加混合节点,用 add_clip 添加行走片段,用 add_clip_with_mask 添加带遮罩的奔跑片段,并将图存入 Assets<AnimationGraph>,同时把句柄与节点索引存入 Resource。
- 挂载播放器(attach_player):为实体插入 AnimationGraphHandle 与 AnimationTransitions,并播放行走与奔跑节点。
- 同步权重(sync_blend):通过 player.animation_mut 获取 ActiveAnimation 并调用 set_weight,按 RunBlend 值在行走与奔跑之间分配权重。
- 淡入奔跑(fade_to_run):当混合值大于 0.5 时,用 AnimationTransitions::play 配合 Duration::from_millis(180) 切换到奔跑节点。
依赖声明为 bevy = "0.20"。
适用场景
- 需要在多个动画片段之间进行混合、叠加或遮罩的项目。
- 需要按权重动态调节片段贡献(如行走与奔跑之间的过渡)。
- 需要带时长的交叉淡入淡出切换。
限制与注意事项
- 目标版本为 Bevy 0.20+。
- 游戏玩法模式(App 或实体状态)应使用 bevy-state-machines,动画图不是那种状态类型。
- 叠加层使用 AnimationGraph::add_additive_blend 插入 AnimationNodeType::Add,片段权重仍通过 ActiveAnimation::set_weight 控制。
- 持久化图使用 SerializedAnimationGraph 加 ron。1D 或 2D 混合空间类型不属于 AnimationGraph,应通过节点权重进行混合。
- 不要在文档 URL 中固定 /0.20.0/;不要在无序的两个系统中可变查询同一组件;不要在本技能中引入物理、导航、网络或 XR 相关 crate;不要使用 AnimationTree、BlendSpace 或场景树状态机类型;不要使用虚构 API 或未命名的第三方 crate。
- 相关技能:前置为 bevy-master、bevy-ecs-composition、bevy-animation;互补为 bevy-state-machines、godot-animation-tree-mastery。