Bevy でのアニメーション理解入門：メンタルモデルの構築

はじめに

Bevy エンジンにおいて、アニメーション付きの 3D モデル（

.glb

ファイルなど）を動作させる際、公式例を見ても仕組みが複雑に見えます。本記事では、ECS 基礎知識がある方に向けて、直感的な理解から始めて Bevy のアニメーションシステムを体系化します。

• 目的: Bevy のアニメーションの仕組みを理解し、公式例のコードとメンタルモデルを一致させる。
• 前提:

  AnimationPlayer

  ,

  AnimationGraph

  ,

  NodeIndex

  の役割と関係性を把握する。

---

1. 直感からの始め方 (First Intuition)

まずは Bevy の ECS 詳細を一旦 aside に置いて、**「アニメーション付きの 3D モデルを動かすために最低限必要なもの」**を考えます。

必要な要素は以下の二つです：

• 3D モデル: スポーンされたエンティティ（またはその参照）。
• アニメーション: 再生するデータ（またはその参照）。

直感的には、これらを結びつける関数は以下のように見えるでしょう：

my_model.play_animation(my_animation);

しかし、実際の Bevy ではこの単純な構造とは異なり、内部の仕組みを知る必要があります。

AnimationPlayer: モデルを制御するための手段

.glb

ファイルを読み込んだ際、単一のエンティティではなく**エンティティの階層（親と子の関係）**としてスポーンされます。

// 図：モデルの階層構造 (イメージ)
RootEntity
└── ChildEntity_1
    └── MeshComponent // メッシュはここに付いている

この階層全体をアニメーション化するために、Bevy は自動的に**

AnimationPlayer

**というコンポーネントを挿入します。

• 役割: アニメーションの再生・一時停止・現在進行中のアニメーションの取得を行うコントローラー。
• 配置場所: モデルが存在するエンティティ階層内のどこか（通常は根に近い子エンティティ）に自動挿入される。

AnimationGraph: アニメーションの保存および結合のための手段

Bevy のアニメーションデータ構造は単一ではありません。

AnimationGraph

というグラフ構造を使い、複数のアニメーションクリップを組み合わせて管理します。

基本的な参照には以下の要素が必要です：

• AnimationGraph

  : グラフそのもののインスタンス。

• NodeIndex

  : グラフ内で特定のアニメーションを指す識別子（インデックス）。

---

2. まとめ (Putting it Together)

AnimationPlayer

、

AnimationGraph

、

NodeIndex

を持つ場合、アニメーション再生の流れは以下となります。

接続された構造

1. AnimationGraph

   の登録: グラフを

   WorldAssetRoot

   に読み込み、

   AnimationPlayer

   と同じエンティティ上にコンポーネントとして挿入します（これは

   AnimationGraphHandle

   の役割）。

2. 再生指令の発出:

   my_animation_player.play(my_node_index)

   を呼び出します。

内部での処理フロー

この関数呼び出しにより、以下が自動的に行われます：

• AnimationPlayer

  が同じエンティティ上の**

  AnimationGraph

  コンポーネントを検索**。
• グラフ内で

  NodeIndex

  に指定されたアニメーションを見つけ。
• 所属するモデル（メッシュ階層）をアニメーション化して再生開始。

// 概念図：接続された構造
[AnimationPlayer Component] --(holds)--> [AnimationGraph Component]
       |                                      |
       +--------------------------------------|
       | (calls)                              v
       play(NodeIndex)                  [Specific Animation Plays]

---

3. 例のコードの walkthrough (A Walk through the Example Code)

公式の「Basic Animated Mesh」例を、上記のメンタルモデルと関連付けて解説します。

ステップ 1: アセット読み込みと初期設定

起動時に実行されるシステムで、まず

.glb

ファイルからアニメーションデータを抽出します。

// グラフとインデックス（NodeIndex）を取得
let (graph, index) = AnimationGraph::from_clip(
    asset_server.load(GltfAssetLabel::Animation(2).from_asset(GLTF_PATH)),
);

重要なポイント:

• GltfAssetLabel::Animation(n)

  は、ファイル内のアニメーションクリップのインデックス（0, 1, 2...）を受け取ります。構造が不明な場合は試行錯誤が必要です。

• from_clip

  メソッドは、グラフインスタンスそのものだけでなく、参照するための**

  NodeIndex

  も返却**します。

// アセットストアへの登録（ハンドラーを取得）
let graph_handle = graphs.add(graph);

ステップ 2: メッシュのロードとスポーン

メッシュも同様にロードし、利便性のためにカスタムコンポーネント

animation_to_play

とバウンディングします。

let mesh_scene = asset_server.load(GltfAssetLabel::Scene(0).from_asset(GLTF_PATH));
commands.spawn((animation_to_play, mesh_scene));

• animation_to_play

  コンポーネント: 必要なアニメーションデータの 2 パーツ（グラフハンドラーとインデックス）を保持します。
• システムとの連携: スポーン直後に

  play_animation_when_ready

  システムに制御が渡されます。

ステップ 3:

AnimationPlayer

の探索と設定

ここが最も重要かつやや複雑な部分です。

.glb

をロードした際、メッシュは階層としてスポーンするため、

AnimationPlayer

がどの子エンティティにあるか特定する必要があります。

探索処理

ルートエンティティから全子孫を回遊し、

AnimationPlayer

コンポーネントを持っているエンティティを検出します。

for child in children.iter_descendants(scene_ready.entity) {
    if let Ok(mut player) = players.get_mut(child) {
        // 処理...
    }
}

• iter_descendants

  は

  Query<&Children>

  のメソッドを使用して、階層を辿るために呼び出されます。

コンポーネントの追加と再生指令

見つけた

AnimationPlayer

にグラフハンドラーを追加し、アニメーション再生を開始します。

// 1. エンティティコマンドを取得
commands.entity(child)

// 2. アニメーショングラフハンドラーを追加（グラフ自体は既に存在する）
.insert(AnimationGraphHandle(animation_to_play.graph_handle.clone()))

// 3. アニメーションの再生指令を発行
.player.play(animation_to_play.index).repeat();

これで、無償で入手した 3D キャラクターを Bevy アプリにスポーンさせ、アニメーションさせるための基本構造が完成します。