# マニュアル: AI 用の書き出しと書き戻し

**URL:** <https://guild.rpgmakerofficial.com/t/topic/2949>\
**Category:** チュートリアル\
**Tags:** manual\
**Created:** [2026 年 9 月 15 日午前 5:45 UTC](https://guild.rpgmakerofficial.com/t/topic/2949 "2026-09-15T05:45:55Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![Moonling](https://sea2.discourse-cdn.com/flex002/user_avatar/guild.rpgmakerofficial.com/moonling/32/369_2.png) [@Moonling](https://guild.rpgmakerofficial.com/u/Moonling)\
**Post date:** [2026 年 9 月 15 日午前 5:45 UTC](https://guild.rpgmakerofficial.com/t/topic/2949/1 "2026-09-15T05:45:55Z")

</div>

## このマニュアルについて

このマニュアルでは、ACTION GAME MAKER の **AI 用の書き出し** と **書き戻し** について解説します。作ったゲームの中身を AI（Claude や ChatGPT などの対話型 AI、Claude Code のようなコーディング支援ツール）に読める形へ出し、AI が書いた内容をゲームへ戻すための機能です。

「この敵の動きを説明して」「ジャンプの後に攻撃を挟みたいけど、どう組めばいい？」といった相談を、 **実際のプロジェクトの中身を見てもらいながら** できるようになります。

## 想定している使い方

この機能は、 **パソコンの中のファイルを直接読み書きできる AI** と一緒に使うことを想定しています。Claude Code や Codex、Cursor のような、手元のフォルダを開いて作業するタイプのものです。

プロジェクトフォルダを開いてもらえば、 **必要なファイルを AI が自分で探して読み、副本の編集まで行えます。** こちらがファイルを選んで渡す必要はありません。

### チャット型の AI ではどこまでできるか

ブラウザやアプリで使う対話型の AI（ChatGPT や Claude の画面）でも、 **読んで相談するところまでは** できます。ただし **フォルダごと渡すことはできません。**

| やりたいこと | チャット型の AI | ファイルを読み書きできる AI |
| --- | --- | --- |
| オブジェクト 1 つについて相談する | できる（副本を 1 ファイル貼る） | できる |
| プロジェクト全体をまとめて見てもらう | できない | できる |
| 使えるアクションの一覧を渡す | 大きすぎて現実的でない | できる |
| 副本を編集してもらう | できる（結果を貼り直してもらう） | できる |
| 編集結果をファイルへ保存する | **自分でコピーして保存する** | AI が保存する |
| 複数のオブジェクトをまたいで直す | 手間がかかる | できる |

**`.ai/vs_catalog.json` が約 300 KB あります。** アクション 82 種類・条件 33 種類の説明と設定項目がすべて入っているためで、チャット型の AI に貼り付けるには大きすぎます。「何ができるか」から相談したい場合は、ファイルを読める AI を使ってください。

### チャット型の AI を使う場合

次のように絞ると実用的です。

- 相談したいオブジェクトの **副本を 1 ファイルだけ** 貼ります（数 KB 〜 15 KB 程度なので貼れます）
- 使いたいアクションの見当がついているなら、`.ai/vs_catalog.json` からそのアクションの項目だけを抜き出して貼ります
- 編集してもらった JSON は、 **自分で元のファイルへ上書き保存します** 。保存さえすれば、あとは同じように「AI が書いた内容を反映」で書き戻せます

整形（字下げや項目の並び順）が変わっていても問題ありません。書き戻しは中身で比べています。

## ACTION GAME MAKER で AI を使うときの概要

プロジェクトの中身のうち、 **ビジュアルスクリプト（`.vs`）だけが AI から読めません。** マップやオブジェクト（`.tscn`）、データベース（`project_database.tres`）、プロジェクト設定は元々テキストなので、フォルダを渡せばそのまま読んでもらえます。

| 中身 | AI から読めるか |
| --- | --- |
| マップ・オブジェクト（`.tscn`） | 読める |
| データベース（`project_database.tres`） | 読める |
| プロジェクト設定（`project.godot`） | 読める |
| **ビジュアルスクリプト（`.vs`）** | **読めない** |

この機能は、その穴を埋めるものです。`.vs` の中身を\*\*副本（ふくほん）\*\*として JSON で書き出し、AI に読ませます。

**`.vs` そのものは変わりません。** 副本はあくまで写しで、ゲームが読むのは今までどおり `.vs` です。書き出しても、ゲームの動きも読み込みの速さも一切変わりません。

* * *

## 書き出す

### 実行の仕方

**プロジェクト** → **高度な設定** → **ツール** → **「ヴィジュアルスクリプトを AI 用に書き出し」**

（Godot モードでは **プロジェクト** → **ツール** の直下にあります）

プロジェクト内のビジュアルスクリプトをすべて書き出します。件数が出たら完了です。

### 何が書き出されるか

プロジェクトフォルダの中に `.ai` というフォルダができ、次の 3 つが入ります。

| 場所 | 中身 |
| --- | --- |
| `.ai/visual_scripts/` | ビジュアルスクリプト 1 本ごとの副本（`.json`） |
| `.ai/vs_catalog.json` | アクションと条件の一覧（何ができるかの辞書） |
| `.ai/plugin_samples/` | GDScript でアクション・条件を自作するときのひな形 |

**`.ai` フォルダはエディタの「ファイルシステム」には出てきません。** 先頭がドットのフォルダは ACTION GAME MAKER が見ない決まりになっているためです。ゲームの書き出し（エクスポート）にも含まれないので、製品には入りません。エクスプローラーからは普通に見えます。

### 副本（`.ai/visual_scripts/`）

ビジュアルスクリプト 1 本が JSON 1 ファイルになります。ステート・遷移・条件・アクションの設定が、そのまま読める形で並びます。

```json
{
  "id": 18,
  "node": {
    " __class__": "VisualScriptActionLink",
    "from_node_id": 15,
    "to_node_id": 17,
    "other_conditions": [{ " __class__": "ElapsedTime", "constant_value": 6.0 }],
    "visual_script_node_title": "ステートリンク001"
  },
  "pos": [200.0, -20.0]
}

```

- ` __class__ ` がアクション・条件の種類です。
- 既定値のままの設定は書かれません。 **書いてある項目＝変更した項目** です。
- シーンや素材の指定は `uid://…` で保存されているので、読めるように `〜__resolved` という欄でファイルのパスを併記しています。

### アクションと条件の一覧（`.ai/vs_catalog.json`）

**アクション 82 種類・条件 33 種類** について、何をするものかと設定項目を並べた辞書です。副本だけ渡しても「`DirectionalMove` が何をするのか」は AI が知らないので、こちらが必要になります。

```json
{
  "class": "DirectionalMove",
  "name": "移動方向を指定して移動",
  "category": "Move",
  "description": "指定の角度にこのオブジェクトを移動します。",
  "properties": [
    { "name": "move_angle", "label": "移動方向", "type": "float", "default": 0.0,
      "description": "移動方向を360度で指定します。右方向が0度です。" }
  ]
}

```

**エディタの言語で書き出されます。** 日本語で使っていれば日本語、英語なら英語の説明が入ります。

### GDScript のひな形（`.ai/plugin_samples/`）

ビジュアルスクリプトでは作れない動きを GDScript で足したいときのために、公式のひな形 9 ファイルをコピーします。`.ai/vs_catalog.json` にも書き方の決まりが入っているので、 **AI にプラグインを書いてもらうことができます。**

* * *

## AI に渡す

**プロジェクトフォルダごと渡してください。** `.ai` だけ渡すと、マップやデータベースが見えなくなります。ファイルを読み書きできる AI なら、プロジェクトフォルダを開くだけです。

（チャット型の AI の場合は「想定している使い方」を参照してください。フォルダは渡せないので、副本を 1 ファイルずつ貼ることになります）

### 伝え方の例

> `.ai/visual_scripts/objects/enemy.vs.json` がこの敵の動きです。  
> `.ai/vs_catalog.json` に使えるアクションと条件の一覧があります。  
> 「体力が半分を切ったら攻撃パターンを変える」を足したいのですが、どう組めばいいですか。

副本を編集してもらう場合は、そのことも伝えてください。

> `.ai/visual_scripts/objects/enemy.vs.json` を直接編集してください。  
> あとでエディタから書き戻します。

* * *

## 書き戻す

AI が副本を編集したら、その内容をビジュアルスクリプトへ反映します。

### 実行の仕方

**プロジェクト** → **高度な設定** → **ツール** → **「AI が書いた内容を反映」**

確認のダイアログが出るので、\*\*「書き戻す」\*\*を押します。

### 書き戻される範囲

**変更された副本だけです。** 今のビジュアルスクリプトと見比べて、違っているものだけを書き戻します。AI が触っていないオブジェクトは 1 文字も書き換わりません。

整形（字下げやキーの並び）が変わっていても「変更」とは見なしません。中身で比べています。

### 書き戻しの流れ

順番に次のことが行われます。 **途中で問題が見つかったら、何も書かずに止まります。**

1. **開いているファイルの確認** — 書き戻し先のビジュアルスクリプトや、それを使っているシーンを開いていると中止します
2. **内容の確認** — 存在しないアクション名・設定項目・変数名などが無いか調べます
3. **バックアップ** — 書き換えるファイルを `.ai/backup/` に控えます
4. **書き戻し**
5. **確認** — 書いたファイルを読み直して、副本の内容が入っているか確かめます
6. **失敗したら巻き戻し** — 5 で問題があればバックアップから元に戻します

### 中止されたときの表示

**開いているファイルがある場合**

```auto
次のファイルを閉じてから、もう一度実行してください:
res://objects/enemy.tscn

```

開いたまま書き換えると、エディタが持っている古い状態が後から保存されて、 **書き戻した内容が消えてしまいます。** そのため一切書かずに止めています。

**内容に問題がある場合**

```auto
確認で問題が見つかったため、何も変更しませんでした。

4 件のエラーが発生しました:
graze_object.vs (ステート 1): データベースのセクション "no_such_section" は存在しません。
player_hit_checker.vs (ステート 1): 変数 "hp_typo" は player.tscn に存在しません。
enemy.vs / nodes[0].node: "VisualScriptAction" に "speeeed" というプロパティはありません。
bomb.vs / nodes[0].node / other_actions[0]: クラス "DisplayParticl" は存在しません。

```

どのファイルのどのステートで何が違うのかまで出ます。 **AI に、このメッセージをそのまま貼って直してもらうのが早いです。**

### バックアップ

書き戻す直前の状態が `.ai/backup/<日時>/` に残ります。 **保持されるのは 1 回分だけ** で、次に書き戻すと前回のぶんは消えます。

書き戻しの結果に納得できないときは、このフォルダから元のファイルを手で戻せます。

* * *

## 実用例

### 敵の動きを説明してもらう

1. 「ヴィジュアルスクリプトを AI 用に書き出し」を実行します。
2. AI に「`.ai/visual_scripts/objects/enemy.vs.json` の動きを説明して」と伝えます。
3. ステートの流れと遷移条件を読んで説明してくれます。

書き戻しは要りません。読むだけなら安全です。

### 待ち時間をまとめて調整してもらう

1. 書き出します。
2. 「この敵の待ち時間が長いので、全部 3 秒にしてください。副本を直接編集して」と伝えます。
3. 「AI が書いた内容を反映」で書き戻します。
4. エディタで開いて確認します。

### ビジュアルスクリプトで作れない動きを足す

1. 書き出します。
2. 「`.ai/vs_catalog.json` の `plugins` と `.ai/plugin_samples/` を見て、〜するカスタムアクションを書いてください」と伝えます。
3. AI が `.gd` ファイルを書きます。これは **書き戻しの対象ではありません** 。オブジェクトの下にノードを置いてアタッチしてください。
4. エディタを開き直すと、アクション追加の一覧に出てきます。

### 書き戻しが「確認で問題が見つかった」で止まる

1. エラーメッセージをそのまま AI に貼ります。
2. 直してもらいます。
3. もう一度「AI が書いた内容を反映」を実行します。

ファイルは何も書き換わっていないので、何度でもやり直せます。

* * *

## 注意点

- **`.ai` フォルダを渡すだけでは足りません。** マップやデータベースはプロジェクトの他の場所にあります。フォルダごと渡してください。
- **AI に渡す前に一度「書き出し」を実行してください。** エディタで編集した内容は、書き出すまで副本に反映されません。古い副本を書き戻すと、エディタでの編集が巻き戻ります。
- **書き戻す前に、対象のオブジェクトとシーンを閉じてください。** 開いていると中止されます（ファイルは書き換わりません）。
- **シーンの中に直接書いたビジュアルスクリプトは対象外です。** 書き出されるのは `.vs` ファイルとして独立しているものだけです。オブジェクトに `.vs` を割り当てて使っている通常の作り方であれば問題ありません。
- **共有ボードのキー名は確認されません。** 変数・スイッチ・データベースの名前は存在チェックが入りますが、共有ボードのキーだけは素通りします。AI が間違ったキー名を書いても止まらないので、書き戻したあとに動作を確かめてください。
- **バックアップは 1 回分だけです。** 2 回書き戻すと、1 回前の状態はもう戻せません。大きな変更を頼むときは、事前にプロジェクトごとコピーしておくと安心です。
- **AI の提案をそのまま信じないでください。** 書き戻しの確認は「設定として成立するか」までしか見ません。 **それが面白いゲームになるか、意図したとおりに動くかは確認していません。** 書き戻したら必ずテストプレイしてください。
- **カスタムアクションのメソッド名を間違えると、エラーも出ずに何も起きません。** プラグインを入れたのに反応しないときは、まず `on_state_update` などの綴りを疑ってください。ひな形と見比べるのが確実です。
- 副本の実数は桁数が多めに書かれます（`0.20999999344348907` など）。書き戻しで値がずれないようにするためで、異常ではありません。
- `.ai` フォルダはゲームの書き出しに含まれません。消しても、もう一度「書き出し」を実行すれば作り直せます。