关于本手册
本手册讲解 ACTION GAME MAKER 的为 AI 导出与写回功能。它们的作用是：把你做的游戏内容导出成 AI（Claude、ChatGPT 等对话型 AI，以及 Claude Code 这类编程辅助工具）能读懂的形式，再把 AI 写出的内容带回游戏里。
有了它，「说明一下这个敌人的动作」「我想在跳跃之后插入攻击，该怎么搭？」这类问题，就可以在 AI 实际看着你的项目内容的前提下来讨论了。
本功能设想的使用方式
本功能设想与能够直接读写电脑中文件的 AI配合使用，也就是 Claude Code、Codex、Cursor 这类会打开本地文件夹进行工作的工具。
只要让它打开项目文件夹，AI 就会自己查找并读取需要的文件，还能直接编辑副本。 你不需要一个个挑出文件交给它。
对话型 AI 能做到哪一步
在浏览器或应用中使用的对话型 AI（ChatGPT 或 Claude 的界面），读取和讨论是可以的，但无法整个文件夹交给它。
| 想做的事 | 对话型 AI | 能读写文件的 AI |
|---|---|---|
| 就某一个对象进行讨论 | 可以（粘贴 1 个副本文件） | 可以 |
| 让它整体查看整个项目 | 不行 | 可以 |
| 提供可用动作的一览 | 太大，不现实 | 可以 |
| 让它编辑副本 | 可以（让它把结果贴回来） | 可以 |
| 把编辑结果保存到文件 | 自己复制并保存 | AI 来保存 |
| 跨多个对象一起修改 | 很费事 | 可以 |
.ai/vs_catalog.json 大约有 300 KB。 因为其中收录了 82 种动作和 33 种条件的全部说明与设置项，对话型 AI 根本粘不下。如果想从「能做什么」开始讨论，请使用能读取文件的 AI。
使用对话型 AI 时
按下面的方式收窄范围就比较实用了。
- 只粘贴想讨论的那个对象的一个副本文件（几 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/ |
每个可视化脚本对应一份副本（.json） |
.ai/vs_catalog.json |
动作与条件的一览（说明有哪些功能的词典） |
.ai/plugin_samples/ |
用 GDScript 自制动作・条件时的模板 |
.ai 文件夹不会出现在编辑器的「文件系统」中。 因为以点开头的文件夹是 ACTION GAME MAKER 约定忽略的对象。它也不会被包含在游戏的导出中，所以不会进入成品。在资源管理器中则可以正常看到。
副本（.ai/visual_scripts/）
一个可视化脚本会变成一个 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 种条件各自的作用及设置项。只交出副本的话，AI 并不知道「DirectionalMove 是做什么的」，所以需要这份文件。
{
"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 的情况请参阅「本功能设想的使用方式」。由于无法交出文件夹，只能一个个粘贴副本文件。）
表述示例
.ai/visual_scripts/objects/enemy.vs.json是这个敌人的动作。
.ai/vs_catalog.json中有可用的动作与条件一览。
我想加入「体力低于一半时改变攻击模式」，该怎么搭？
如果希望它编辑副本，也请一并说明。
请直接编辑
.ai/visual_scripts/objects/enemy.vs.json。
之后我会从编辑器写回。
写回
AI 编辑完副本后，就把这些内容反映到可视化脚本中。
执行方法
项目 → 高级设置 → 工具 → 「应用 AI 写入的内容」
会弹出确认对话框，点击**「写回」**。
写回的范围
只有发生变化的副本。 系统会与当前的可视化脚本逐一比对，只写回有差异的那些。AI 没有碰过的对象，一个字符都不会被改写。
即使格式（缩进或键的顺序）发生变化，也不会被视为「有变化」，比较的是内容。
写回的流程
会依次执行以下步骤。中途一旦发现问题，就什么都不写并停止。
- 检查打开的文件 — 如果写回目标的可视化脚本、或使用它的场景处于打开状态，就中止
- 检查内容 — 检查是否存在不存在的动作名、设置项、变量名等
- 备份 — 把将要改写的文件保存到
.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/<日期时间>/ 中。只保留一次的份，下次写回时上一次的就会被覆盖。
如果对写回的结果不满意，可以从这个文件夹中手动恢复原文件。
实用示例
让它说明敌人的动作
- 执行「导出可视化脚本供 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 写了错误的键名也不会被拦下，因此写回之后请确认实际运行情况。
- 备份只保留一次的份。 写回两次的话，上上次的状态就再也回不去了。要委托大规模修改时，事先把整个项目复制一份会比较安心。
- 不要盲目相信 AI 的提案。 写回时的检查只看到「作为设置是否成立」这一层。它是否会成为有趣的游戏、是否按你的意图运作，并没有被检查。 写回后请务必进行测试游玩。
- 自定义动作的方法名写错时，不会报错也什么都不会发生。 装了插件却没有反应时，请先怀疑
on_state_update等的拼写。与模板对照是最稳妥的办法。 - 副本中的实数会写出较多位数（例如
0.20999999344348907）。这是为了让写回时数值不产生偏差，并非异常。 .ai文件夹不会被包含在游戏的导出中。删掉也没关系，再执行一次「导出」就能重新生成。