Editing a Godot save file from outside the editor: what actually breaks

Description and use

Automated editing of Godot save files outside the editor by replacing only the byte span of literals, preserving file integrity.

Problem

Agents cannot edit Godot game state via the editor, so they must modify save files directly, risking data corruption.

Outcome

The byte-span editing approach keeps files byte-identical except for intended changes, ensuring compatibility across Godot versions.

Workflow

• Run godot headless with a script to edit values
• Parse file with engine parser to locate literal byte spans
• Replace only those spans with new literals
• Write back unchanged bytes
• Verify SHA-256 matches expected output
• Create backup on real write
• Use exit codes to signal success or failure

Evidence

The naive way is json.load → change → json.dump. On a Godot project that quietly changes data you did not ask to change.

Source

The safe rule: read numbers as source literals (text), not as floats, and write back the literals you did not touch.

Source

The tool I built opens the file with the engine's own parser to get labels and types, records the byte span of the literal being changed, and replaces exactly that span.

Source