Manual: Exporting for AI and Writing Back

[Moonling]

About this manual

This manual explains exporting for AI and writing back. They exist so you can hand the contents of your game to an AI in a form it can read, and bring what the AI wrote back into the game.

They turn questions like “explain what this enemy does” or “I want an attack after the jump — how do I build that?” into something you can ask while the AI is looking at your actual project.

What this is meant to be used with

This feature assumes an AI that can read and write files on your computer — Claude Code, Codex, Cursor and similar tools that open a folder on your machine and work in it.

Open your project folder with one of those, and the AI finds and reads the files it needs by itself, and can edit the copies as well. You do not have to pick out files and hand them over.

How far a chat-style AI gets

A chat-style AI (ChatGPT or Claude in a browser or app) can still read and discuss. What it cannot do is take the folder.

What you want to do	Chat-style AI	AI that can read and write files
Ask about one object	Yes (paste one copy)	Yes
Have the whole project looked at	No	Yes
Hand over the list of available actions	Too large to be practical	Yes
Have a copy edited	Yes (it pastes the result back)	Yes
Save the edit into the file	You copy and save it yourself	The AI saves it
Fix things across several objects at once	Laborious	Yes

.ai/vs_catalog.json is about 300 KB. It holds the description and settings of all 82 actions and 33 conditions, which is far too much to paste into a chat. If you want to start from “what can I even do here?”, use an AI that can read files.

Using a chat-style AI

Narrow it down like this and it becomes workable.

• Paste one copy file for the object you want to talk about (a few KB up to about 15 KB, so it fits)
• If you already know which action you want, pull just that entry out of .ai/vs_catalog.json and paste it
• Take the JSON it gives back and save it over the original file yourself. Once it is saved, “Write Visual Scripts Back from AI” works exactly the same way

Formatting does not matter — indentation and key order can change. Writing back compares the contents, not the text.

How AI reads a project in ACTION GAME MAKER

Of everything in a project, only visual scripts (.vs) are unreadable to an AI. Maps and objects (.tscn), the database (project_database.tres) and the project settings are text already, so handing over the folder is enough for those.

Content	Readable by an AI
Maps and objects (.tscn)	Yes
Database (project_database.tres)	Yes
Project settings (project.godot)	Yes
Visual scripts (.vs)	No

This feature fills that gap. It writes the contents of your .vs files out as JSON copies for the AI to read.

The .vs files themselves do not change. A copy is only ever a copy, and the game still reads the .vs as before. Exporting changes neither how the game behaves nor how fast it loads.

---

Exporting

Running it

Project → Advanced Settings → Tools → “Export Visual Scripts for AI”

(In Godot mode it sits directly under Project → Tools)

It exports every visual script in the project. It is done when the count appears.

What gets exported

A folder called .ai appears inside your project folder, holding three things.

Where	What
.ai/visual_scripts/	One copy (.json) per visual script
.ai/vs_catalog.json	The list of actions and conditions (a dictionary of what is available)
.ai/plugin_samples/	Templates for writing your own actions and conditions in GDScript

The .ai folder does not appear in the editor’s FileSystem dock. Folders starting with a dot are ones ACTION GAME MAKER deliberately ignores. It is not included when you export your game either, so it never reaches the finished product. It is perfectly visible in Explorer or Finder.

The copies (.ai/visual_scripts/)

One visual script becomes one JSON file. States, transitions, conditions and action settings all line up in a readable form.

{
  "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": "Transition 001"
  },
  "pos": [200.0, -20.0]
}

• __class__ is the kind of action or condition.
• Settings still at their default are not written. What is written is what you changed.
• Scenes and assets are stored as uid://…, so a …__resolved entry is written alongside with the readable file path.

The list of actions and conditions (.ai/vs_catalog.json)

A dictionary of what 82 actions and 33 conditions do, along with their settings. Handing over the copies alone is not enough — the AI has no way of knowing what DirectionalMove is.

{
  "class": "DirectionalMove",
  "name": "DirectionalMove",
  "category": "Move",
  "description": "Moves this object to the specified angle.",
  "properties": [
    { "name": "move_angle", "label": "Set Movement Angle", "type": "float", "default": 0.0,
      "description": "Specifies the movement direction in degrees; 0° is directly right." }
  ]
}

It is written in the editor’s language. Use the editor in English and the descriptions come out in English.

In English, name is usually just the class name again. Almost every action and condition has an English description but no separate display name, so name falls back to class. The description is the part that carries the meaning — that is what the AI reads.

The GDScript templates (.ai/plugin_samples/)

For behaviour you cannot build with a visual script, nine official templates are copied here. .ai/vs_catalog.json also carries the rules for writing one, so you can have an AI write a plugin for you.

---

Handing it to the AI

Hand over the whole project folder. Handing over only .ai hides the maps and the database. With an AI that can read files, opening the project folder is all there is to it.

(For a chat-style AI, see “What this is meant to be used with”. You cannot hand over a folder, so you paste the copies one file at a time.)

Example of what to say

.ai/visual_scripts/objects/enemy.vs.json is what this enemy does.
.ai/vs_catalog.json lists the actions and conditions available.
I want to add “switch attack pattern once health drops below half”. How should I build that?

If you want the copy edited, say so.

Edit .ai/visual_scripts/objects/enemy.vs.json directly.
I will write it back from the editor afterwards.

---

Writing back

Once the AI has edited a copy, this brings it into the visual script.

Running it

Project → Advanced Settings → Tools → “Write Visual Scripts Back from AI”

A confirmation appears. Press “Write Back”.

What gets written back

Only the copies that changed. Each copy is compared against the visual script as it stands now, and only the ones that differ are written back. Objects the AI did not touch are not altered by a single character.

Formatting — indentation, key order — changing does not count as a change. The comparison is on contents.

The order it happens in

These run in turn. If anything looks wrong, it stops without writing at all.

1. Checks for open files — stops if the target visual script, or a scene using it, is open
2. Checks the contents — looks for action names, settings and variable names that do not exist
3. Backs up — copies the files it is about to change into .ai/backup/
4. Writes back
5. Verifies — reads the written files back off disk and confirms the copy’s contents are in them
6. Rolls back on failure — if step 5 finds a problem, the backup is restored

When it stops

With a file open

Close these files first, then run it again:
res://objects/enemy.tscn

Rewriting a file while it is open means the old state the editor is holding gets saved afterwards, and your write-back silently disappears. So nothing is written at all.

With something wrong in the contents

The check did not pass, so nothing was changed.

4 error(s) occurred:
graze_object.vs (state 1): the database section "no_such_section" does not exist.
player_hit_checker.vs (state 1): the variable "hp_typo" does not exist in player.tscn.
enemy.vs / nodes[0].node: "VisualScriptAction" has no property named "speeeed".
bomb.vs / nodes[0].node / other_actions[0]: the class "DisplayParticl" does not exist.

It names the file, the state and what is wrong. Pasting this message straight back to the AI and asking it to fix it is the quickest route.

The backup

The state just before writing is kept in .ai/backup/<date and time>/. Only one round is kept — the next write-back replaces it.

If you are unhappy with the result, you can restore the original files from that folder by hand.

---

Worked examples

Having an enemy’s behaviour explained

1. Run “Export Visual Scripts for AI”.
2. Ask the AI to “explain what .ai/visual_scripts/objects/enemy.vs.json does”.
3. It reads the flow of states and the transition conditions and explains them.

No write-back needed. Reading alone is safe.

Adjusting a set of wait times at once

1. Export.
2. Say “the wait times on this enemy are too long, make them all 3 seconds — edit the copy directly”.
3. Run “Write Visual Scripts Back from AI”.
4. Open it in the editor and check.

Adding behaviour a visual script cannot build

1. Export.
2. Say “look at plugins in .ai/vs_catalog.json and at .ai/plugin_samples/, then write me a custom action that does X”.
3. The AI writes a .gd file. That is not part of writing back — place a node under the object and attach it.
4. Reopen the editor and it appears in the list when adding an action.

Writing back stops with “the check did not pass”

1. Paste the error message straight to the AI.
2. Have it fixed.
3. Run “Write Visual Scripts Back from AI” again.

Nothing was written, so you can retry as often as you like.

---

Things to watch out for

• Handing over the .ai folder alone is not enough. The maps and the database live elsewhere in the project. Hand over the whole folder.
• Run “Export” once before handing anything to the AI. Edits you made in the editor do not reach the copies until you export. Writing back an out-of-date copy rolls your editor work back.
• Close the object and the scene before writing back. It stops if they are open (nothing is written).
• Visual scripts written directly inside a scene are not covered. Only ones that exist as standalone .vs files are exported. The usual way of working — assigning a .vs to an object — is fine.
• Shared board key names are not checked. Variable, switch and database names are checked for existence, but shared board keys slip through. A wrong key name from the AI will not stop the write-back, so test the result afterwards.
• Only one round of backup is kept. Write back twice and the state before the first one is gone. For a large change, copy the whole project beforehand.
• Do not take the AI’s suggestion on trust. The write-back check only goes as far as “does this hold together as settings”. Whether it makes a good game, or does what you meant, is not checked. Always play-test after writing back.
• Getting a custom action’s method name wrong fails silently. If a plugin does nothing at all, suspect the spelling of on_state_update and friends first. Comparing against a template is the sure way.
• Numbers in the copies are written with a lot of decimal places (0.20999999344348907 and so on). That is so values do not drift when written back; nothing is wrong.
• The .ai folder is not included when you export your game. Deleting it is fine — running “Export” again rebuilds it.