Time queries currently only support one query per node. However, there may be cases where this is not enough: In particular, nested animation graph nodes may have an arbitrary number of time-dependent inputs and outputs, and currently the system will not be able to handle that correctly.

This is not a big change, since we only support an arbitrary number of time-dependent inputs/outputs with specific duration values for each, so the foundation is there.

Objective

The generality of the current graph architecture causes complications during processing, especially when it comes to cache output. Most other animation graph implementations (as far as I'm aware of) restrict pose outputs to one per node and only allow pose outputs to be connected to one other pin. This ensures that each pose output will be queried once per frame, simplifying caching and computation.

This should also enable performance improvements, as it will be easier to replace string IDs with integers and hashmap lookups with integer indexing.

Solution

Refactored the code to enforce the following graph invariant:

• Each node can only have a single pose output
• Each pose output can only be connected to a single input

Breaking changes

As part of the refactoring, the animation graph format was changed slightly. Refer to the updated examples for instructions on how to use the updated format.

Objective

Currently the only way to set input parameters of a top-level graph (i.e. a graph assigned directly to an AnimationGraphPlayer) is to access the asset mutably and modify its parameter node. This would require cloning the asset every time we would like to have a new actor play the graph, which is inefficient. Ideally, we would set the parameters on AnimationGraphPlayer directly, and the player would then pass the parameters when querying the graph as a node overlay.

Solution

Enable setting parameters in the AnimationGraphPlayer, similarly to how GraphNode does it.

Objective

This plugin is currently not very convenient to use: the target scene needs to be added, a system must then find the bevy::animation::AnimationPlayer in the instantiated scene, replace it with an AnimationGraphPlayer and finally add the desired animation graph to it.

This would be better handled by having an asset specifying the scene to be loaded together with the path (using entity Names) of the AnimationPlayer to be replaced and the asset path of the animation graph that should be played.

Solution

Provide AnimatedScene assets and an appropriate asset loader. Animated scenes are defined in .animscn.ron asset files as follows:

(
    source: "models/character_rigged.gltf#Scene0",
    path_to_player: ["Main Controller"],
    animation_graph: "animation_graphs/locomotion.animgraph.ron",
)

where

• source is the asset path of the original scene
• path_to_player is the path (vector of entity Names) to the original AnimationPlayer.
• animation_graph is the asset path of the AnimationGraph we want to playback.

We can now simply instantiate an AnimatedSceneBundle with the given AnimatedScene handle, just like we would do with a regular scene:

    //...
    commands.spawn(AnimatedSceneBundle {
        animated_scene: asset_server.load("animated_scenes/character.animscn.ron"),
        ..default()
    });
    //...

Once the animated scene is finished successfully spawning, an AnimatedSceneInstance component will be added to it. For convenience, this component contains the entity id of the child containing the AnimationGraphPlayer, in case the user decides to manually set some animation graph parameters. If the animated scene spawning fails, (e.g. because the given path_to_player is incorrect), an error will be printed and the AnimatedSceneFailed component will be added instead.

Animated scenes spawning sometimes proceeds seemingly without issue (entities are spawned with correct components and animation works as expected) but the resulting meshes are invisible.

This occurs relatively rarely (<1/10 times) and I have not found a way to reliably reproduce it.

Any additional reports would be appreciated :)

The character example is not great: Plenty of candy-wrapper artefacts) are visible in the model during animation (which make the joints look weirdly thin), and I somehow got the walk/run cycle wrong (left arm moves forward while left leg is moving forward and vice versa).

It might be better for now to replace with an example based on the Bevy fox.

Tracking issue for state machine nodes.

Requirements

1. Arbitrary number of states, with an arbitrary number of transitions between every two of them (note that this is different from the core animation graph: in the animation graph there can only be one edge into every node input).
2. Every node is an animation graph with a single pose output.
3. Every node transition is an animation graph which takes as input the source state pose and the target state pose (plus some parameters such as transition percentage, etc) , and returns single pose.
4. Transitions may need to be cut short under certain events; this needs to be configurable.

Questions

For requirements 2 and 3, should we support arbitrary FSM outputs as long as every state and transition has the same output schema?

I currently cannot think of a use-case for this, but if anything comes up it does seem doable.

Currently the docs.rs page is pretty barren. before leaving alpha this needs to be populated with enough information for users to get started.

TODO:

• [x] Minimal examples
  • [x] How to use graph animation player, and how to replace bevy's own animation players is specific entities.
  • [x] Graphs as assets
  • [ ] Programmatically creating graphs with API (Won't do in this PR)
  • [ ] Graph with custom node (Won't do in this PR)
• [x] Explanation of how the animation graph works.
• [x] Documentation of available nodes with inputs and outputs specified. This should be linked from front page. (Inputs and outputs will be documented in future patch).