bevy-animation-graph
Bevy ECS skill for animation blending. Keywords: Bevy, AnimationGraph, blend, AnimationGraphHandle, AnimationNodeType.
thedivergentai · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add thedivergentai/Game-Dev-Agentic-Skills --skill bevy-animation-graph技能说明
name: bevy-animation-graph description: "Bevy ECS skill for animation blending. Keywords: Bevy, AnimationGraph, blend, AnimationGraphHandle, AnimationNodeType."
Bevy animation graph
When to use
Load this when clips must blend, add, or mask. Single-clip playback stays on bevy-animation.
ECS shape
- Assets:
AnimationGraphdescribes how clips blend.add_clipparents a clip node.add_blendparents a blend node.add_clip_with_maskstores au64mask (bone groups you assign;0means no mask). - Components:
AnimationGraphHandleis a handle to the graph used by theAnimationPlayeron the same entity.AnimationTransitionscrossfades between nodes. - Weights:
ActiveAnimation::set_weighton the player, afterplay, drives a node that is already in the graph. - Systems: evaluation still runs through the animation player systems. Do not add a second player.
#[derive(Resource)]
struct LocomotionNodes {
graph: Handle<AnimationGraph>,
walk: AnimationNodeIndex,
run: AnimationNodeIndex,
}
fn build_locomotion_graph(
mut commands: Commands,
asset_server: Res<AssetServer>,
mut graphs: ResMut<Assets<AnimationGraph>>,
) {
let mut graph = AnimationGraph::new();
let blend = graph.add_blend(0.5, graph.root);
let walk = graph.add_clip(
asset_server.load(GltfAssetLabel::Animation(0).from_asset("models/fox.glb")),
1.0,
blend,
);
let run = graph.add_clip_with_mask(
asset_server.load(GltfAssetLabel::Animation(1).from_asset("models/fox.glb")),
0b0011,
1.0,
blend,
);
let handle = graphs.add(graph);
commands.insert_resource(LocomotionNodes {
graph: handle,
walk,
run,
});
}
#[derive(Resource)]
struct LocomotionNodes {
graph: Handle<AnimationGraph>,
walk: AnimationNodeIndex,
run: AnimationNodeIndex,
}
fn attach_player(
mut commands: Commands,
nodes: Res<LocomotionNodes>,
mut players: Query<(Entity, &mut AnimationPlayer), Without<AnimationGraphHandle>>,
) {
for (entity, mut player) in &mut players {
commands.entity(entity).insert((
AnimationGraphHandle(nodes.graph.clone()),
AnimationTransitions::new(),
));
player.play(nodes.walk).repeat();
player.play(nodes.run).repeat();
}
}
#[derive(Resource)]
struct LocomotionNodes {
graph: Handle<AnimationGraph>,
walk: AnimationNodeIndex,
run: AnimationNodeIndex,
}
#[derive(Component)]
struct RunBlend(f32);
fn sync_blend(mut players: Query<(&mut AnimationPlayer, &RunBlend)>, nodes: Res<LocomotionNodes>) {
for (mut player, blend) in &mut players {
if let Some(active) = player.animation_mut(nodes.run) {
active.set_weight(blend.0.clamp(0.0, 1.0));
}
if let Some(active) = player.animation_mut(nodes.walk) {
active.set_weight(1.0 - blend.0.clamp(0.0, 1.0));
}
}
}
use std::time::Duration;
#[derive(Resource)]
struct LocomotionNodes {
graph: Handle<AnimationGraph>,
walk: AnimationNodeIndex,
run: AnimationNodeIndex,
}
#[derive(Component)]
struct RunBlend(f32);
fn fade_to_run(
nodes: Res<LocomotionNodes>,
mut query: Query<(&mut AnimationPlayer, &mut AnimationTransitions, &RunBlend)>,
) {
for (mut player, mut transitions, blend) in &mut query {
if blend.0 > 0.5 {
transitions.play(&mut player, nodes.run, Duration::from_millis(180));
}
}
}
[dependencies]
bevy = "0.20"
Graph choices
| Need | Bevy approach |
|---|---|
| Blend clips | AnimationGraph plus AnimationGraphHandle |
| Gameplay mode | App or entity states stay on bevy-state-machines. The graph is not that state type. |
| Additive layer | AnimationGraph::add_additive_blend inserts AnimationNodeType::Add. Clip weights still go through ActiveAnimation::set_weight. |
Scope
- Crossfades use
AnimationTransitions::playwith aDuration, as infade_to_run. - Persisting a graph is
SerializedAnimationGraphplusron. A 1D or 2D blend-space type is not part ofAnimationGraph; blend with node weights.
Expert Knowledge Delta
Target: Bevy 0.20+.
Core ECS types: Component, Resource, Query, Commands, Startup, Update, Fixed / FixedMain (bevy::time), .chain(), Plugin, DefaultPlugins, MinimalPlugins. Messages and observers are an ownership slot. See bevy-events-messaging for their APIs. Systems run in parallel unless .chain() orders the ones that conflict.
Who owns state
| Piece | Owner | Who may mutate | Schedule |
|---|---|---|---|
| Data on one entity | Component | One system via Query | Update or FixedMain |
| One value for the whole app | Resource | One system | Startup to insert, then the schedule that reads it |
| Spawn | Commands | The spawning system | Startup for the initial world; later schedules for runtime spawn |
| Order that must not race | .chain() | The chained systems only | Same schedule |
| Plugin boundary | Plugin | build registers systems and resources | Before the app runs |
Borrow rule: two systems that both mutably query the same component must be ordered (.chain()) or split so only one writes. Unrelated systems stay parallel. That is the ECS page rule, not a guess at a system-set API.
Decision
| If you need | Do this | Do not |
|---|---|---|
| Per-entity data | Component + Query | A script field copied onto the entity |
| App-wide config or clock | Resource | Copy the value onto every entity |
| Stable simulation step | FixedMain and the Fixed clock | Tie simulation to raw frame Update |
| Startup spawn | Commands in Startup | Spawn from a render system |
| Cross-system notice that is not shared state | Message or observer slot in bevy-events-messaging | A new event type invented in this file |
| An API outside the d |