このマニュアルについて
このマニュアルでは、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 ファイルになります。ステート・遷移・条件・アクションの設定が、そのまま読める形で並びます。
{
"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 が知らないので、こちらが必要になります。
{
"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 文字も書き換わりません。
整形（字下げやキーの並び）が変わっていても「変更」とは見なしません。中身で比べています。
書き戻しの流れ
順番に次のことが行われます。途中で問題が見つかったら、何も書かずに止まります。
- 開いているファイルの確認 — 書き戻し先のビジュアルスクリプトや、それを使っているシーンを開いていると中止します
- 内容の確認 — 存在しないアクション名・設定項目・変数名などが無いか調べます
- バックアップ — 書き換えるファイルを
.ai/backup/に控えます - 書き戻し
- 確認 — 書いたファイルを読み直して、副本の内容が入っているか確かめます
- 失敗したら巻き戻し — 5 で問題があればバックアップから元に戻します
中止されたときの表示
開いているファイルがある場合
次のファイルを閉じてから、もう一度実行してください:
res://objects/enemy.tscn
開いたまま書き換えると、エディタが持っている古い状態が後から保存されて、書き戻した内容が消えてしまいます。 そのため一切書かずに止めています。
内容に問題がある場合
確認で問題が見つかったため、何も変更しませんでした。
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 回分だけで、次に書き戻すと前回のぶんは消えます。
書き戻しの結果に納得できないときは、このフォルダから元のファイルを手で戻せます。
実用例
敵の動きを説明してもらう
- 「ヴィジュアルスクリプトを AI 用に書き出し」を実行します。
- AI に「
.ai/visual_scripts/objects/enemy.vs.jsonの動きを説明して」と伝えます。 - ステートの流れと遷移条件を読んで説明してくれます。
書き戻しは要りません。読むだけなら安全です。
待ち時間をまとめて調整してもらう
- 書き出します。
- 「この敵の待ち時間が長いので、全部 3 秒にしてください。副本を直接編集して」と伝えます。
- 「AI が書いた内容を反映」で書き戻します。
- エディタで開いて確認します。
ビジュアルスクリプトで作れない動きを足す
- 書き出します。
- 「
.ai/vs_catalog.jsonのpluginsと.ai/plugin_samples/を見て、〜するカスタムアクションを書いてください」と伝えます。 - AI が
.gdファイルを書きます。これは書き戻しの対象ではありません。オブジェクトの下にノードを置いてアタッチしてください。 - エディタを開き直すと、アクション追加の一覧に出てきます。
書き戻しが「確認で問題が見つかった」で止まる
- エラーメッセージをそのまま AI に貼ります。
- 直してもらいます。
- もう一度「AI が書いた内容を反映」を実行します。
ファイルは何も書き換わっていないので、何度でもやり直せます。
注意点
.aiフォルダを渡すだけでは足りません。 マップやデータベースはプロジェクトの他の場所にあります。フォルダごと渡してください。- AI に渡す前に一度「書き出し」を実行してください。 エディタで編集した内容は、書き出すまで副本に反映されません。古い副本を書き戻すと、エディタでの編集が巻き戻ります。
- 書き戻す前に、対象のオブジェクトとシーンを閉じてください。 開いていると中止されます（ファイルは書き換わりません）。
- シーンの中に直接書いたビジュアルスクリプトは対象外です。 書き出されるのは
.vsファイルとして独立しているものだけです。オブジェクトに.vsを割り当てて使っている通常の作り方であれば問題ありません。 - 共有ボードのキー名は確認されません。 変数・スイッチ・データベースの名前は存在チェックが入りますが、共有ボードのキーだけは素通りします。AI が間違ったキー名を書いても止まらないので、書き戻したあとに動作を確かめてください。
- バックアップは 1 回分だけです。 2 回書き戻すと、1 回前の状態はもう戻せません。大きな変更を頼むときは、事前にプロジェクトごとコピーしておくと安心です。
- AI の提案をそのまま信じないでください。 書き戻しの確認は「設定として成立するか」までしか見ません。それが面白いゲームになるか、意図したとおりに動くかは確認していません。 書き戻したら必ずテストプレイしてください。
- カスタムアクションのメソッド名を間違えると、エラーも出ずに何も起きません。 プラグインを入れたのに反応しないときは、まず
on_state_updateなどの綴りを疑ってください。ひな形と見比べるのが確実です。 - 副本の実数は桁数が多めに書かれます（
0.20999999344348907など）。書き戻しで値がずれないようにするためで、異常ではありません。 .aiフォルダはゲームの書き出しに含まれません。消しても、もう一度「書き出し」を実行すれば作り直せます。