はじめに

生成AIの進歩は目覚ましく、音楽や3Dモデル、果てはゲームエンジンですら既にAIが触る時代が来ています。
しかし、エフェクトに関してはあまりAIがどうこうとういう話は聞きません。
そこで、生成AIにゲーム制作で使えそうな3Dエフェクトを作成させてみました。

環境

Antigravity 2.0 (安価なので)
- モデル：Gemini 3.5 Flash (Low)
Effekseer 1.70

エフェクト作成

実際に作らせてみます。

拡張子

Effekseerで使われる拡張子はいくつかあります。

.efkproj (ver1.40までの標準)
.efkefc (ver1.50からの標準)
.efcpkg
.efkmat
.efkmodel 等

このうち、.efkprojはXMLで記述されています。今回はこの拡張子のファイルをAIに直接書かせる形にしました。

解析

まずはAIに.efkprojを解析させてみます。
解析するデータは以下のサンプルを使用しました。(CC0で提供されています)

プロンプト

./Pierre01 にあるのはeffekseerの.efkproj(xml)のサンプル群です
このサンプル群を解析し、XMLの各メタデータをAIが参照しやすく間違いを犯しにくいドキュメントとしてまとめてください

英語のMarkdownが出てきたので、日本語訳させて見てみます。

effeseer_xml_reference_ja.md(一部)

# Effekseer `.efkproj` (XML) 構造リファレンスガイド

本ドキュメントは、`./Pierre01` にあるサンプルファイルを解析して構築した、Effekseer のプロジェクトファイルである `.efkproj`（XML形式）の仕様解説書です。
人間およびAIが正確に構造を理解し、XMLの自動生成や書き換えタスクにおいて構文エラーや構造エラーを犯さないよう、非常に厳密かつ直感的な例を挙げて構成されています。

---

## 1. 最上位（プロジェクト）の構造

Effekseer プロジェクトは、`<EffekseerProject>` をルートとする XML ドキュメントです。

### ルートドキュメント・スキーマ
```xml
<?xml version="1.0" encoding="utf-8"?>
<EffekseerProject>
  <Root>
    <Name>Root</Name>
    <Children>
      <!-- 子 <Node> 要素が再帰的に配置されるリスト -->
    </Children>
  </Root>
  <ToolVersion>1.43</ToolVersion>
  <Version>3</Version>
  <StartFrame>0</StartFrame>
  <EndFrame>240</EndFrame>
  <IsLoop>True</IsLoop>
</EffekseerProject>

### トップレベルのメタデータ要素
* **`<ToolVersion>`**: 保存・作成した Effekseer エディタのバージョン（例: `1.01`, `1.30`, `1.43`）。
* **`<Version>`**: ファイルフォーマットのバージョン（通常は `3`）。
* **`<StartFrame>`**: プレビュー再生を開始するフレーム（通常は `0`）。
* **`<EndFrame>`**: 再生終了フレーム（例: `120`, `240`, `300`）。
* **`<IsLoop>`**: ループ再生をするかどうかの真偽値文字列（頭文字大文字の `True` または `False`）。

---

## 2. `<Node>` 要素（再帰的な木構造）

.
.
.

このMarkdownを基にして一度AIにエフェクトを作らせます。

描画タイプ

プロンプト

effekseer_xml_reference.md を基に爆発のエフェクトを./Explosion作成してください

出来上がったものをEffekseerエディタで見てみます。

既におかしいです。再生してもリング部分しか描画されていません。
とりあえずExplosion_Emitter以下のノードの描画タイプをスプライトに変更してみます。

再生されました。(スパーク部分がおかしいですが)

とりあえずノードの描画設定の部分をAIに聞いてみます。

プロンプト

開いた直後でエフェクト生成ノードの描画の種類が「無し」になっていた
「無し」から「スプライト」に変更するとエフェクトが表示される

結果としては、描画タイプがスプライトの場合、XML中の<type>タグは省略するべき所を<type>0</type>としていたのが原因でした。AIが既にエフェクトとリファレンスを修正したようです。

スパークの修正

スパークが変になっているのはここが原因のようです。

外側部分が繰り返しの設定になっています。クランプにすると正常に表示されます。

AIに指摘して直させます。

プロンプト

sparksの描画共通の"外側"の設定が"繰り返し"になっています
.efkprojから"外側"を設定("外側"と"クランプ"の二つ)することはできますか

回答

はい、.efkproj から「外側」の設定を個別に制御することが可能です！

Effekseerエディタの「描画共通」パネル内にある**「外側」**（Wrap Mode / テクスチャリピート）設定は、XML内の <RendererCommonValues> ブロックにある <Wrap> タグで設定できます。

設定値は以下の通り対応しています：

1（または省略時）: 繰り返し（Repeat）
0: クランプ（Clamp）

.
.
.

実際は0が繰り返しで1がクランプですが、AIが勘違いしているようです。エフェクトとリファレンスを直させます。

プロンプト

0が繰り返しで1がクランプのようです
今後間違えないようにドキュメントに書き加えてください

これでひとまず完成とします。

成果物

実際に出来たエフェクト

リファレンス

effekseer_xml_reference_ja.md

# Effekseer `.efkproj` (XML) 構造リファレンスガイド

本ドキュメントは、`./Pierre01` にあるサンプルファイルを解析して構築した、Effekseer のプロジェクトファイルである `.efkproj`（XML形式）の仕様解説書です。
人間およびAIが正確に構造を理解し、XMLの自動生成や書き換えタスクにおいて構文エラーや構造エラーを犯さないよう、非常に厳密かつ直感的な例を挙げて構成されています。

---

## 1. 最上位（プロジェクト）の構造

Effekseer プロジェクトは、`<EffekseerProject>` をルートとする XML ドキュメントです。

### ルートドキュメント・スキーマ
```xml
<?xml version="1.0" encoding="utf-8"?>
<EffekseerProject>
  <Root>
    <Name>Root</Name>
    <Children>
      <!-- 子 <Node> 要素が再帰的に配置されるリスト -->
    </Children>
  </Root>
  <ToolVersion>1.43</ToolVersion>
  <Version>3</Version>
  <StartFrame>0</StartFrame>
  <EndFrame>240</EndFrame>
  <IsLoop>True</IsLoop>
</EffekseerProject>
```

### トップレベルのメタデータ要素
* **`<ToolVersion>`**: 保存・作成した Effekseer エディタのバージョン（例: `1.01`, `1.30`, `1.43`）。
* **`<Version>`**: ファイルフォーマット of バージョン（通常は `3`）。
* **`<StartFrame>`**: プレビュー再生を開始するフレーム（通常は `0`）。
* **`<EndFrame>`**: 再生終了フレーム（例: `120`, `240`, `300`）。
* **`<IsLoop>`**: ループ再生をするかどうかの真偽値文字列（頭文字大文字の `True` または `False`）。

---

## 2. `<Node>` 要素（再帰的な木構造）

Effekseer のエフェクトの核となるのが、`<Node>` 要素の階層構造です。各 `<Node>` はパーティクルの生成器（エミッター）や描画パーツを表します。`<Node>` は内部に `<Children>` タグを持ち、その下にさらに `<Node>` を内包することで再帰的な親子関係を構築します。

### `<Node>` の型定義イメージ
```typescript
interface Node {
  Name: string;                     // エディタ上での表示名
  CommonValues: CommonValues;       // パーティクル生成時間、寿命、親子関係の継承設定
  LocationValues: LocationValues;   // 位置データおよび補間方法
  RotationValues: RotationValues;   // 回転データおよび補間方法
  ScalingValues: ScalingValues;     // 拡大縮小データおよび補間方法
  RendererCommonValues?: RendererCommonValues; // テクスチャ、ブレンド、UV、フェードなど
  DrawingValues: DrawingValues;     // 描画方式（Sprite, Ring, Ribbon, Track, Modelなど）
  Children: { Node: Node[] };       // 再帰的な子ノードの配列
}
```

---

## 3. 値の補間パターンと XML 構造の変化（最重要）

Effekseer では、空間プロパティ（位置・回転・拡大縮小）や色などの計算に、複数の補間モード（Fixed, PVA, Easing, FCurve など）を使用できます。**指定する `<Type>` に応じて、そのブロック全体のタグ構造が根本的に変化します。**

> [!WARNING]
> **構造変化の罠**:
> * **Fixed（固定値）** モードの場合、座標要素（`<X>`, `<Y>`, `<Z>`）は直接 float のテキスト値（例: `<X>1.5</X>`）を持ちます。
> * **PVA（位置・速度・加速度）** や **Easing（イージング）** モードなどの場合、座標要素は内部に `<Center>`, `<Max>`, `<Min>` という子タグを内包する構造になります。

### A. Fixed（固定値）モード (Type = 0 またはタグ省略時のデフォルト)
値が一定で変化しない場合に使用します。座標要素の中に直接数値を記述します。
```xml
<LocationValues>
  <Type>0</Type>
  <Fixed>
    <Location>
      <X>1.5</X>
      <Y>3.0</Y>
      <Z>-2.5</Z>
    </Location>
  </Fixed>
</LocationValues>
```

### B. PVA（位置・速度・加速度）モード (Type = 1)
パーティクル生成時に `<Min>` から `<Max>` の範囲でランダムに初期値が決定され、時間経過によって速度・加速度を適用します。
* 座標要素の内部に `<Center>`, `<Max>`, `<Min>` を持ちます。
```xml
<LocationValues>
  <Type>1</Type>
  <PVA>
    <Location>
      <X><Center>0</Center><Max>10</Max><Min>-10</Min></X>
      <Y><Center>0</Center><Max>10</Max><Min>-10</Min></Y>
      <Z><Center>0</Center><Max>10</Max><Min>-10</Min></Z>
    </Location>
    <Velocity>
      <X><Max>0.05</Max><Min>-0.05</Min></X>
      <Y><Center>0.1</Center><Max>0.15</Max><Min>0.05</Min></Y>
      <Z><Max>0.05</Max><Min>-0.05</Min></Z>
    </Velocity>
    <Acceleration>
      <Y><Center>-0.003</Center><Max>-0.003</Max><Min>-0.003</Min></Y>
    </Acceleration>
  </PVA>
</LocationValues>
```

### C. Easing（イージング）モード (Type = 2)
ランダム化された `<Start>` 位置から、同じくランダム化された `<End>` 位置まで、指定されたカーブ（速度）で補間移動させます。
```xml
<LocationValues>
  <Type>2</Type>
  <Easing>
    <Start>
      <X><Max>5</Max><Min>-5</Min></X>
      <Y><Center>2</Center><Max>3</Max><Min>1</Min></Y>
      <Z><Max>5</Max><Min>-5</Min></Z>
    </Start>
    <End>
      <X><Max>10</Max><Min>-10</Min></X>
      <Y><Center>8</Center><Max>10</Max><Min>6</Min></Y>
      <Z><Max>10</Max><Min>-10</Min></Z>
    </End>
    <StartSpeed>20</StartSpeed>
    <EndSpeed>-20</EndSpeed>
  </Easing>
</LocationValues>
```

### D. FCurve（ファンクションカーブ）モード (位置は Type=3, 回転は Type=5)
ベジェ曲線を用いたキーフレームアニメーションを行います。
```xml
<LocationValues>
  <Type>3</Type>
  <LocationFCurve>
    <FCurve>
      <Keys>
        <Z>
          <Key0>
            <Frame>0</Frame>
            <InterpolationType>0</InterpolationType>
            <LeftX>0</LeftX>
            <LeftY>0</LeftY>
            <RightX>0</RightX>
            <RightY>0</RightY>
            <Value>5.62</Value>
          </Key0>
          <Key1>
            <Frame>30</Frame>
            <InterpolationType>0</InterpolationType>
            <LeftX>25</LeftX>
            <LeftY>8.0</LeftY>
            <RightX>30</RightX>
            <RightY>8.0</RightY>
            <Value>8.0</Value>
          </Key1>
        </Z>
      </Keys>
    </FCurve>
  </LocationFCurve>
</LocationValues>
```

---

## 4. 各 XML 要素のスキーマ解説

### 4.1. `<CommonValues>` (共通設定)
パーティクルの寿命や生成タイミング、親ノードからの影響設定を行います。
```xml
<CommonValues>
  <MaxGeneration>
    <!-- 無限生成の場合は <Infinite> を True に、有限個の場合は <Value> を設定 -->
    <Infinite>True</Infinite> 
    <!-- もしくは: <Value>150</Value> -->
  </MaxGeneration>
  <Life>
    <Center>90</Center>
    <Max>120</Max>
    <Min>60</Min>
  </Life>
  <GenerationTime>
    <Center>5</Center>
    <Max>5</Max>
    <Min>5</Min>
  </GenerationTime>
  <GenerationTimeOffset>
    <Center>0</Center>
    <Max>0</Max>
    <Min>0</Min>
  </GenerationTimeOffset>
  
  <!-- 親からの影響設定: 0 = 影響あり (Inherit), 1 = 影響なし (Do Not Inherit), 2 = 位置のみ追従 -->
  <LocationEffectType>1</LocationEffectType>
  <RotationEffectType>1</RotationEffectType>
  <ScaleEffectType>0</ScaleEffectType>
  
  <RemoveWhenParentIsRemoved>True</RemoveWhenParentIsRemoved>
  <RemoveWhenAllChildrenAreRemoved>True</RemoveWhenAllChildrenAreRemoved>
</CommonValues>
```

---

### 4.2. `<RendererCommonValues>` (描画共通設定)
テクスチャの選択、合成ブレンドモード、フェードイン・アウト、UV制御などを設定します。
```xml
<RendererCommonValues>
  <ColorTexture>Texture/Smoke.png</ColorTexture>
  
  <!-- ブレンドモード: 0 = 通常ブレンド, 1 = 加算, 2 = 減算, 3 = 乗算 -->
  <AlphaBlend>2</AlphaBlend>
  
  <!-- フェードイン・アウト設定: Type = 1 でフレーム単位フェード有効 -->
  <FadeInType>1</FadeInType>
  <FadeIn>
    <Frame>20</Frame>
    <StartSpeed>-20</StartSpeed>
    <EndSpeed>20</EndSpeed>
  </FadeIn>
  <FadeOutType>1</FadeOutType>
  <FadeOut>
    <Frame>30</Frame>
    <EndSpeed>10</EndSpeed>
  </FadeOut>
  
  <!-- UV モード: 1 = 固定 (UVFixed), 2 = アニメーション (UVAnimation) -->
  <UV>1</UV>
  <UVFixed>
    <Start>
      <X>256</X>
      <Y>0</Y>
    </Start>
    <Size>
      <X>256</X>
      <Y>256</Y>
    </Size>
  </UVFixed>
  
  <!-- UVアニメーション（スプライトシート）の場合 -->
  <!--
  <UV>2</UV>
  <UVAnimation>
    <FrameCountX>4</FrameCountX>
    <FrameCountY>4</FrameCountY>
    <FrameLength><Value>3</Value></FrameLength>
    <LoopType>1</LoopType>
    <Size><X>512</X><Y>512</Y></Size>
  </UVAnimation>
  -->
  
  <!-- 歪み（屈折）エフェクト -->
  <Distortion>True</Distortion>
  <DistortionIntensity>0.5</DistortionIntensity>
  
  <!-- フィルタモード: 0 = バイリニア -->
  <Filter>0</Filter>
  <!-- テクスチャの繰り返し設定: 1 = リピート, 0 = クランプ -->
  <Wrap>1</Wrap>
  
  <ZWrite>True</ZWrite>
</RendererCommonValues>
```

---

### 4.3. `<DrawingValues>` (描画タイプ固有設定)
どのような形状でパーティクルを描画するかを決定します。

> [!NOTE]
> **描画タイプの数値定義（最新の標準仕様）**:
> * **`0`**: **無し (None)** - 何も描画しない。主にエミッター（生成器）専用の親ノードに使用されます。
> * **`1`**: **スプライト (Sprite)** - 一般的な平面ビルボードパーティクル。（`<Type>` タグ省略時の既定値）。
> * **`2`**: **リボン (Ribbon)** - パーティクル同士を線で繋いで描画します。
> * **`3`**: **軌跡 (Track)** - 移動するパーティクルの背後に軌跡を描画します。
> * **`4`**: **リング (Ring)** - 円形の輪や円筒を描画します。
> * **`5`**: **モデル (Model)** - 3Dモデル（メッシュ）を描画します。

> [!IMPORTANT]
> **旧バージョンアセット（Pierre01サンプル等）解析時の注意点**:
> 旧いバージョンのエディタ（ToolVersion 1.43 以下）で保存されたプロジェクトファイルでは、XMLスキーマの歴史的変遷により内部的な `<Type>` の数値の割り振りが異なっています。
> * 旧仕様ファイルでは、**リボン** が `<Type>3</Type>`、**軌跡** が `<Type>6</Type>` と記録されています。
> * AIが過去のサンプルファイルをパース（解析）する際は、このレガシーなマッピング（`3` であっても `<Ribbon>` 要素があるため判別可能）を読み替える必要があります。
> * ただし、AIが**新規にXMLファイルを生成する場合**は、常に最新の**標準仕様（0～5）**の定義に従って記述してください。

#### A. Sprite（スプライト描画）(Type = 1 / デフォルト)
最も一般的な平面のパーティクル描画です。
```xml
<DrawingValues>
  <Type>1</Type>
  <Sprite>
    <!-- ビルボード方式: 2 = 軸固定, 3 = スクリーンビルボード（カメラ正対） -->
    <Billboard>3</Billboard>
    
    <!-- 色変化の設定: 1 = 固定値, 2 = イージング/ランダム -->
    <ColorAll>1</ColorAll>
    <ColorAll_Fixed>
      <R>255</R>
      <G>128</G>
      <B>64</B>
      <A>192</A>
    </ColorAll_Fixed>
  </Sprite>
</DrawingValues>
```

#### B. Ribbon（リボン描画）(Type = 2)
生成された複数のパーティクルを紐のように繋いで描画します。
```xml
<DrawingValues>
  <Type>2</Type>
  <Ribbon>
    <ColorAll_Fixed>
      <R>240</R>
      <G>192</G>
      <B>255</B>
    </ColorAll_Fixed>
    <ViewpointDependent>True</ViewpointDependent>
  </Ribbon>
</DrawingValues>
```

#### C. Track（軌跡描画）(Type = 3)
親パーティクルが移動した背後に軌跡（軌跡板）を残します。
```xml
<DrawingValues>
  <Type>3</Type>
  <Track>
    <ColorCenter_Fixed><A>128</A></ColorCenter_Fixed>
    <ColorCenterMiddle_Fixed><A>64</A></ColorCenterMiddle_Fixed>
    <ColorLeft_Fixed><A>32</A></ColorLeft_Fixed>
    <ColorRight_Fixed><A>32</A></ColorRight_Fixed>
    <TrackSizeMiddle_Fixed>4</TrackSizeMiddle_Fixed>
    <TrackSizeBack_Fixed>0</TrackSizeBack_Fixed>
    <TrackSizeFor_Fixed>0</TrackSizeFor_Fixed>
  </Track>
</DrawingValues>
```

#### D. Ring（リング・円盤描画）(Type = 4)
円形の輪や円筒を描画します。
```xml
<DrawingValues>
  <Type>4</Type>
  <Ring>
    <VertexCount>16</VertexCount>
    
    <!-- 円の半径（外径・内径） -->
    <Outer_Fixed>
      <Location>
        <X>1.5</X> <!-- 半径 -->
      </Location>
    </Outer_Fixed>
    <Inner_Fixed>
      <Location>
        <X>1.0</X>
      </Location>
    </Inner_Fixed>
    
    <!-- 外輪・内輪・中心の頂点カラー -->
    <OuterColor_Fixed><R>255</R><G>128</G><B>0</B><A>255</A></OuterColor_Fixed>
    <InnerColor_Fixed><R>255</R><G>255</G><B>128</B><A>255</A></InnerColor_Fixed>
    <CenterColor_Fixed><R>255</R><G>192</G><B>64</B><A>128</A></CenterColor_Fixed>
  </Ring>
</DrawingValues>
```

#### E. Model（モデル描画）(Type = 5)
3Dのポリゴンメッシュモデルを描画します（3Dモデルデータ `.efkmodel` へのパスが必要です）。
```xml
<DrawingValues>
  <Type>5</Type>
  <Model>
    <!-- 3Dモデルデータをレンダリング -->
  </Model>
</DrawingValues>
```

---

## 5. 自動生成・書き換え時の「黄金の掟」（AI参照用）

XMLをコードなどで自動生成・修正する際は、以下のルールを厳密に遵守してください。ルール違反があると、エディタでの読み込みエラーやクラッシュの原因となります。

1. **タグのケースセンシティブ（大文字・小文字の区別）**:
   すべてのタグ名は厳密に区別されます。
   * 座標は必ず大文字: `<X>`, `<Y>`, `<Z>`
   * 色チャンネルは必ず大文字: `<R>`, `<G>`, `<B>`, `<A>`
   * 要素タグはパスカルケース: `<EffekseerProject>`, `<LocationValues>`, `<DrawingValues>` など

2. **真偽値（Boolean）の表記ルール**:
   XML内の真偽値は、必ず**頭文字のみ大文字**の文字列にしてください: `<Infinite>True</Infinite>`, `<IsLoop>True</IsLoop>`, `<ZWrite>True</ZWrite>`。小文字の `true` / `false` はパースエラーを引き起こします。

3. **固定値（Fixed）と分布（Distribution）タグの排他**:
   `<Fixed>` ブロックの中に、`<Center>`, `<Min>`, `<Max>` タグを決して混入させないでください。
   * **正しい（Fixed値）**: `<X>2.5</X>`
   * **正しい（PVA等の範囲値）**: `<X><Center>2.5</Center><Max>3.0</Max><Min>2.0</Min></X>`
   * **誤り**: `<Fixed><Location><X><Center>2.5</Center></X></Location></Fixed>`

4. **描画を伴わないダミー・親ノードの構成**:
   ノードが「子ノードを生成するためだけのエミッター」として機能し、自身を描画しない場合、`<DrawingValues><Type>0</Type></DrawingValues>` を指定し、かつ内部の `<RendererCommonValues>` や `<Sprite>` ブロックを**省略**します。これにより余計な描画アセットのバインドエラーを防げます。

5. **ファイルパスの区切り文字**:
   テクスチャなどの外部アセットパスには、バックスラッシュ（`\`）ではなく必ずフォワードスラッシュ（`/`）を使用してください。パスは常に `.efkproj` ファイルからの相対パスである必要があります（例: `Texture/Smoke.png`）。

6. **空の要素の記述方式**:
   子要素を持たない配列タグなどは、自己クローズドタグで表す必要があります（例: 子要素が空のときは `<Children />`）。

おわりに

今回は.efkprojを編集させる形にしました。しかし、.efkprojは古いファイル形式(現行verでも読込はできる)であり、ver1.50からは.efkefc(バイナリ)が標準です。
ver1.50から使えるようになる便利な機能が複数あるため、次は.efkefcをAIに作らせる方法を探ろうと思います。