Reading and editing Godot ConfigFile/JSON from a script or an agent: three silent failures

I write a Godot addon that reads and edits save/config files (ConfigFile and JSON), from an editor panel and from a headless CLI so a CI job or a coding agent can use it. Testing it against files that the engine itself wrote turned up three failure modes that share one property: they are silent. Sharing the measurements, because they apply to any script, tool or agent that touches these files.

1. ConfigFile is not INI, and not JSON.

ConfigFile.save() writes values in GDScript literal form. From a file Godot 4.7.2 wrote by itself (343 bytes, 11 values):

typed_array=Array[int]([1, 2, 3])
dict=Dictionary[String, int]({
"a": 1
})
path_array=Array[NodePath]([NodePath("A/B")])

A project.godot with an input map contains Object(InputEventKey,"resource_local_to_scene":false,...) as a value. A parser that only understands scalars has two options: refuse the whole file, or drop what it cannot represent and save. The first is annoying; the second silently rewrites settings around a value it did not understand. Refusing is the right default — a tool that cannot represent a value should not rewrite the file containing it.

If you do support them, keep them opaque: read the type annotation, then count brackets while skipping string contents. Array[String](["a)b", "c(d"]) is a valid value whose first ) is inside a string.

2. A JSON round-trip through a float changes values with no error at all.

JSON numbers are not limited to IEEE-754 doubles. 9007199254740993 (2^53+1), 9223372036854775807, 1e10, 0.7500, -0.0 are all legal. Parse into a double, write back, and 2^53+1 becomes …989.0 while 0.7500 becomes 0.75. Nothing throws. The game just reads different numbers, and a save file that worked before no longer does.

What worked instead: keep the source literal as text, and when a value is edited replace only that byte range. On a 409-byte JSON test file, changing one integer changed exactly 1 byte (offset 13, 13 bytes identical before it, 395 after). A 78-byte ConfigFile edit touched only the spans that were edited, and a typed container next to it stayed byte-identical. Check SHA-256 before and after, and write the backup before the first write, not after.

3. If an agent or CI calls your CLI, test the failure paths, not the happy path.

Three things that pass a manual check and break automation:

  • A misspelled flag must exit non-zero. If --jsno is quietly ignored and the tool prints its human-readable output with exit 0, the CI step is green and nobody notices the difference.
  • Errors must be machine-readable (a JSON object with an error code), not only prose.
  • Don’t assume --json means “stdout is exactly one line”: Godot prints its own banner line first. Read the last non-empty line, or you will feed a banner to json.load.

I had to add all three to my own CLI after a 31-case contract test found them in it — each one failed silently, which is exactly why I would test for them in any tool an agent calls.

What I am using. Save Value Editor — open, search, edit, review, save and restore ConfigFile/JSON values, in an editor panel or headless (inspect / edit, --json, exit codes, dry run by default). A free, read-only MIT version is on the Asset Library: Save Value Viewer - Godot Asset Library. The published CLI contract (flags, JSON fields, exit codes) is in godot-save-value-cli.

Limits, so nobody is surprised: Windows only for now, 8 MiB per file, no binary or encrypted saves, and if the running game writes the same file the game wins — the tool refuses to save when the file changed since it was read.

If someone has a file shape that trips a tool like this, I am happy to test it.