Godot Spreadsheet Database
A VS Code extension for creating and editing JSON database files for Godot games using a spreadsheet interface.
*.godotdb.json files are human-editable, diff-friendly JSON data tables designed for game data such as enemies, items, abilities, quests, resources, balance values, and references to Godot assets.
MVP Usage
Commands
| Command |
Description |
GodotDB: Create Sample Sheet |
Creates a sample monsters.godotdb.json in your workspace root |
GodotDB: Export to Flattened JSON |
Exports the active .godotdb.json as a flat dictionary (first column → key) |
GodotDB: Validate Current Sheet |
Validates the active sheet (types, resource paths, etc.) |
Custom Editor
Files matching *.godotdb.json automatically open in the spreadsheet editor — a webview table with:
- Editable cells (text, number, boolean dropdown, enum dropdown)
- Add / delete rows
- Add / delete columns (with type selection)
- Image preview for
godot_texture columns (resolves res:// paths when a Godot project is found)
- Resource picker — cells typed
godot_texture or godot_scene show a Pick button that opens a file dialog filtered to the appropriate extensions (png, jpg, webp, svg, tga, bmp, exr, hdr for textures; tscn, scn for scenes). The selected path is stored as { "path": "res://…" } and converted automatically. Manual typing is still supported as a fallback.
- Inline validation results
Data Model
{
"columns": [
{ "key": "id", "type": "string" },
{ "key": "hp", "type": "number" },
{ "key": "icon", "type": "godot_texture" }
],
"rows": [
{ "id": "goblin", "hp": 10, "icon": "res://assets/goblin.png" }
]
}
Supported column types:
| Type |
Description |
string |
Plain text |
number |
Numeric |
boolean |
true / false |
enum |
Picks from a defined set of options |
godot_texture |
res:// path to a texture (shows preview) |
godot_scene |
res:// path to a scene |
reference:<sheet> |
Foreign-key reference to another sheet |
Resource cells may also use the Godot 4 UID shape:
{ "uid": "uid://abc123", "path": "res://assets/goblin.png" }
Resource Picker & UID Resolution
When you click Pick, the extension:
- Opens a file dialog rooted at the detected Godot project root (or workspace root).
- Converts the chosen file to a
res:// relative path.
- Attempts UID extraction — reads the selected file (and its
.import sidecar) looking for a uid://… token.
- If found, it is stored alongside the path as
{ "uid": "uid://…", "path": "res://…" }.
- If not found, a non-blocking warning is shown and only the
path is stored. UIDs require Godot 4's .import sidecar files (generated when the resource is imported by the Godot editor).
- The cell is updated and the document saved immediately.
UID limitations: Godot 4 writes UIDs to .import files and .tscn/.res files that reference resources. Files that have never been imported by the Godot editor (e.g., raw PNGs dropped into the project) may not have UIDs yet. Opening the project in the Godot editor and re-importing will generate them.
Validation warns when UIDs are present without a matching path (likely unresolved reference) but never treats it as an error.
Godot Project Detection
The extension walks upward from the workspace root looking for project.godot. When found, res:// paths are checked for file existence (warnings only).
Future — Godot Plugin Manifest
A future version could ship a Godot plugin manifest (addons/godot_json_spreadsheet/plugin.gd) that:
- Reads the runtime-flattened JSON at startup.
- Registers each sheet as an autoload singleton (e.g.
GameData.monsters).
- Provides a
GameData.get(sheet, key) lookup API.
- Hot-reloads sheets when the
.godotdb.json file changes on disk.
This would allow game designers to edit balance data in VS Code and see live updates inside the running Godot project.
Development
npm install
npm run compile
Then press F5 to launch the extension in a new Extension Development Host window.
License
MIT
