[Godot 4.2] AnimationLibrary を .res/.tres ファイルから読み込んで使う

手順

1. 「アニメーションの管理...」から AnimationLibrary を .res/.tres ファイルに保存する
2. スクリプト上で preload() や ResourceLoader などを使って AnimationLibrary をロードする
3. AnimationMixer.add_animation_library() でロードした AnimationLibrary を追加する

AnimationLibrary をファイルに保存する

まずはそもそもファイルを作らなければなりません。
適宜アニメーションを作成した後、 Introduction to the animation features — Godot Engine (4.x)の日本語のドキュメント を参考に、アニメーションを管理するウィンドウを開いてください。

アニメーションやアニメーションライブラリが並んでいる右の方に、フロッピーディスクのアイコンがあります。
これを押すことでファイル保存に関連するメニューが出てきて、リソースファイルとして保存することができます。

.tres ファイルとして保存してからテキストエディタで開くとわかりますが、 AnimationLibrary をファイルに保存しても、それに属している Animation のプロパティがまるごと保存されるわけではありません。参照が並んでいるだけです。
そのため、 Animation も全部ファイル化する必要があることに気をつけてください。

ファイルの保存ができたら、必要ないときは読み込まないようにするために AnimationPlayer ノード内に保存されている参照は消してしまいましょう。
フロッピーディスクの隣にあるゴミ箱アイコンを押すと消すことができます。

スクリプト上で AnimationLibrary のファイルをロードする

通常の Resource と変わらないため、解説は割愛します。

add_animation_library() でロードした AnimationLibrary を追加する

sample.gd

var additional_animation_library = preload("res://additional_animation_library.tres")

func _ready():
    $AnimationPlayer.add_animation_library("additional", additional_animation_library)
    $AnimationPlayer.play("additional/any_animation")

AnimationMixer.add_animation_library() の引数に、 AnimationLibrary の名前 (コード中 additional) と追加対象の AnimationLibrary (コード中 additional_animation_library) を渡せば、 AnimationPlayer.play() などから再生できるようになります。

add_animation_library() で AnimationLibrary を追加するとき、既存の名前やインスタンスと重複している場合はエラーになります。
sample.gd の例でいけば、 additional という別のアニメーションライブラリが存在しているとエラーになりますし、別名で additional_animation_library.tres が追加されていてもエラーになります。

使いたい場面

例えばRPGなどで、キャラクターが技を発動したことによってキャラクターそのものが動くだけでなくカメラ振動や効果音再生、任意タイミングでのHUD更新なども行う場合です。
アニメーション機能を使えば様々な操作をタイムライン上で管理できますから、技ごとのアニメーションにこういった要素も含めたいです。
というわけで、技の発動に応じてシーンルートに近いところでアニメーションを再生することになります。

しかし、ゲームに存在するすべての技を最初から読み込むわけにはいきません。
序盤の「スライム」と戦うだけなのに「メラゾーマ」とかを読み込むのは非効率的です。

そこで、技の情報を収めたリソースと一緒に技のアニメーションもファイル化して、必要なときに読み込めるようにしたいというわけです。

編集が面倒になることへの対策

場合に応じて使用するアニメーションを適宜読み込めるようになったのはいいのですが、編集のためにはいちいち開いたり消したりする必要があり、大変面倒になってしまいました。

この対策には、アニメーションを再生したいシーン(オリジナル)を継承した新しいシーン(クローン)を作成し、そこで各アニメーションを編集するという方法があります。
オリジナルは実際のゲームで使うためのシーンですが、クローンは開発用でリリースには含めません。
そして、アニメーションの追加や編集をするときはクローンで行います。
クローンにいくらアニメーションを追加しても、オリジナルには影響がありません。
そしてクローンで編集したアニメーションをファイルに保存し、オリジナルで使うときはロードするという要領です。

クローンはオリジナルを継承しているため、オリジナルが変更された場合、クローンにも反映されます。
また、アニメーション以外にもいろいろな動作確認を行う場として使ってもいいでしょう。

Animation 単品でファイル保存する場合

既存の AnimationLibrary にロードした Animation を追加する場合です。
基本的には AnimationLibrary をロードして使う場合と同様です。

sample2.gd

var animation_library = $AnimationPlayer.get_animation_library("sample_library")
animation_library.add_animation("sample_animation", loaded_animation)
$AnimationPlayer.play("sample_library/sample_animation")

• get_animation_library("") と書くことでグローバルのライブラリーを取得できます。
• クローンのシーンを使ってアニメーションの編集をする場合、アニメーションを追加したいライブラリーをオリジナルの built-in のままにしておくと編集できないのでファイル化だけしておきましょう。
• うっかりアニメーションの名前の重複が起こることを避けたい場合、 Resource.get_rid() を利用して str(animation.get_rid().get_id()) と書くなどの方法が使えます。

参考文献

AnimationMixer — Godot Engine (4.x)の日本語のドキュメント
Introduction to the animation features — Godot Engine (4.x)の日本語のドキュメント
AnimationLibrary — Godot Engine (4.x)の日本語のドキュメント