# Effects Engine — シーンのためのアニメーション視覚エフェクト

Effects Engine は、シナリオがシーンの上に短い視覚エフェクトを再生できるようにします。閃光、煙、火花、魔法の輝きなどです。エフェクトとは、MOD が自分の `effects/` フォルダーに入れて配る小さな Godot シーンのこと。シナリオが名前で呼び出すと画面に現れ、自分で終わるかダイアログが終わるまで表示され続けます。

単独では何も見せないエンジン MOD です。現在収録されているゲームはエフェクトシーンをまだ一つも同梱していないため、プレイ中にエフェクトに出会うことはありません。この MOD は、エフェクトを追加したい作者のためのものです。

## エフェクトはどう現れるか

1. シナリオの行 `effect <名前>` が実行されます。
2. Effects Engine が読み込み済みの MOD の中から `effects/<名前>.tscn` を探します。
3. エフェクトはシーンの絵の上、つまり背景やその物体より上、ダイアログボックスより下に置かれ、再生されます。
4. 呼び出したダイアログが終わると、先に自分で消えていない限り、エフェクトは取り除かれます。

シナリオはエフェクトを待ちません。次の行はすぐに表示されます。

## 作者向け:エフェクトを追加する

エフェクトのシーンを MOD に入れます:

```filestree
my_mod/
└── effects/
    └── sparks.tscn
```

シナリオから呼び出します:

```scenario
text "ランプが瞬いた。"
effect sparks
text "暗闇で何かが動いた。"
end
```

**MOD はフォルダーであること。** Godot のシーンは、フォルダーとしてインストールされた MOD からしか読み込めません。`.zip` アーカイブで配られた MOD のエフェクトはスキップされ、ログに警告が残ります。

### エフェクトシーンの積み木

Effects Engine は、エフェクトシーンの中でフレームをアニメーションさせる方法を三つ用意しています:

- **クロスフェードつきフレームセット** — `EffectDataSet` スクリプトのついたノード、フレーム画像のリスト、そしてフレームからフレームへ溶かしてつなぐ `AnimationController`。速度とフェード時間はインスペクターで設定します。フレームは一度だけ再生され、エフェクトは自分で消えます。
- **シェーダー内のスプライトシート** — `EffectAnimator` が、フレームシート素材のついた `TextureRect` を決められた枚数だけ決められた時間で進めます。
- **シェーダーなしのスプライトシート** — `EffectAnimNode` が横一列のスプライトシートを送り(フレーム幅 = シート幅 ÷ 枚数)、終わりで自分を消します。コードから `EffectAnimNode.SpawnOn(target, sheet, frameCount, seconds)` で作ることもできます。

フレームセットとコードだけで済むスプライトシートはシーンいっぱいに引き伸ばされるので、シーンのサイズに合わせて描いたフレームは背景とぴったり重なります。

### コードなしの最初のエフェクト

一番簡単なエフェクトは、ルートが `TextureRect` のシーンに画像一枚を全画面に引き伸ばして置くだけのものです。たとえば半透明の輝き。`effect <名前>` で現れ、ダイアログが終わると消えます。

## うまく動かないとき

1. **何も現れず、ログにエフェクトが見つからないと出る。** ファイルは、ゲームに含まれる MOD の `effects/<名前>.tscn` として存在し、シナリオの名前と一致していなければなりません。
2. **開発中は動くのに、プレイヤー環境では動かない。** MOD が `.zip` として公開されています。フォルダーとして公開してください。
3. **エフェクトが消えない。** ダイアログが終わるまで残ります。ダイアログを終えるか、フレームセットやスプライトシートの積み木でエフェクトを作ってください。それらは終わると自分を消します。