utils/godot_dev_tools/README.md
Krzysztof kuhy Rudnicki 1869fdee02
Some checks failed
dependency freshness / dependencies on newest stable (push) Waiting to run
file length / file-length (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
palette drift / palette (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
shared gate tests / gate unit tests (push) Waiting to run
godot_dev_tools tests / test (push) Has been cancelled
Fix godot_dev_tools lint race, release 0.1.1
lint.sh ran gdlint/gdformat via xargs -P; on a cold cache the
processes race in os.makedirs and report a file as unopenable.
Run one process per tool. Pin CI Python 3.15.2, chmod Godot.
Bump version and README tags to 0.1.1.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWXs4gEhEUMr9rgYG9V
2026-11-16 14:48:32 +01:00

121 lines
5.7 KiB
Markdown

# godot_dev_tools
The dev feedback mode of kuhy's Godot games, as one addon every game mounts at
a pinned tag. Press F12 in a `--dev` run: the frame freezes, you draw red marks
over it (rect, arrow, circle, pen, text label, select a game object), type an
optional note, press Enter, and a bundle folder lands in the game's feedback
folder. `feedback_inbox` (this repo) turns each bundle into a todo task.
First written by kuhy for one of his Godot games, generalised here into a host
interface.
Godot 4.7.2, GDScript. Version in `addons/dev_tools/dev_tools.cfg`; the tag is
`godot-dev-tools-v<version>`.
## Layout
| Path | Holds |
|---|---|
| `addons/dev_tools/` | the addon: the only folder a game mounts |
| `tests/` | GUT tests and a stub host (`tests/stub_host.gd`) |
| `project.godot` | the stub host project the tests run in |
| `test.sh` | fetches GUT at its pinned tag, runs the tests headless (about 2 s) |
| `lint.sh` | gdlint + gdformat --check (gdtoolkit pinned in `requirements-dev.txt`) |
The addon scripts have no `class_name` (they stay out of the global class cache,
so a game that excludes the folder from exports loses nothing) and reach each
other by relative `preload`, so the mount path is yours to choose, under
`Dev`-prefixed aliases (a game's own `class_name` Style or Frame cannot shadow them). They name no
class of any game, ship no image or sound (the icons are vector shapes), and
show no text: every icon-only control carries an `accessibility_name`, and the
only words on screen are the ones the developer types.
## Mount it in a game
Pin the tag, never copy the folder and never use a submodule. Fetch the repo at
the tag (shallow), then link or copy `godot_dev_tools/addons/dev_tools` to
`res://addons/dev_tools` and gitignore that path:
```bash
git clone --depth 1 --branch godot-dev-tools-v0.1.1 https://github.com/kuhyx/utils "$cache"
ln -sfn "$cache/godot_dev_tools/addons/dev_tools" addons/dev_tools # CI: cp -a instead
```
Load it only for `--dev` runs, and only if it is there (an export has none of
it, and a missing mount must not stop the game):
```gdscript
const ADDON := "res://addons/dev_tools/dev_tools.gd"
if options.dev and ResourceLoader.exists(ADDON):
var tools: Node = (load(ADDON) as GDScript).new()
tools.setup(MyHost.new(self)) # before add_child
add_child(tools)
```
Exclude `addons/dev_tools/*` from every export preset, and keep the host glue
out of exports too.
## The host interface
`setup(host)` takes ONE object of the game's own: any Object, no base class,
no addon path in its source. The addon calls only what the object has and
falls back to a default for the rest (`dev_host.gd` documents each member):
| Member | Meaning | Default |
|---|---|---|
| `game` | game name: `~/data/<game>_binaries/feedback`, bundle field `game` | `"game"` |
| `feedback_env` | env variable overriding the feedback folder | `"DEV_FEEDBACK_DIR"` |
| `colors` | `{mark, armed, panel, panel_pressed, ink}` overrides | the addon's own |
| `debug_state()` | the whole visible state as data: `snapshot.json` | `{}` |
| `pick_at(at)` | the game object under a canvas point, `{}` for none | no select tool |
| `context(state)` | game fields of the bundle (mode, screen, combo, pose...) | `{}` |
| `reset_progress()` | F9: wipe saved progress, return files removed | F9 does nothing |
| `add_menu_entry(id, icon, spoken, on_press)` | put the camera into the pause menu | none |
| `close_menu()` | close that menu before a frame is frozen | none |
| `attach_telemetry(t)` | connect game signals to `t.entry(event, fields)` | none |
| `summary_line(record)` | the Markdown entry's game line | the `Game ..., combo ...` line |
| `entity_line(entity)` | the Markdown entry's selected-object line | a generic line |
Keep `summary_line` out unless the game cannot fill the default's `game` and
`combo` fields: `feedback_inbox` parses `- Game `x`, combo `y``.
## Keys and arguments
F12 annotate (also the camera glyph top right and the pause menu entry), F9
reset. In the annotator: R A C P T S pick rect / arrow / circle / pen / text /
select, Ctrl+Z undo, Enter save, Esc cancel (with unsaved work the first press
only arms the cross). While it is open it sits in the group `annotator`:
a game leaves Esc and the mouse alone then.
Command line (after `--`): `--dev-shot=/abs/out.png` scripted annotate and save
into `/abs/out/` then quit, `--feedback-dir=DIR`, `--save-dir=DIR` (logs go to
`DIR/dev`), `--session-id=ID`, `--dev-tag=T`. The feedback folder is, first
match: `--feedback-dir`, `--save-dir`, the host's env variable,
`~/data/<game>_binaries/feedback` on `--dev` when that `<game>_binaries`
directory exists, else `user://dev`. A headless run
(a bot, a test) gets a blank frame instead of a screenshot.
## The bundle on disk (the contract `feedback_inbox` reads)
`<feedback dir>/<YYYY-MM-DDTHH-MM-SS-mmm>/` holds `screenshot.png`,
`annotated.png` (marks burned in), `report.json`, `game.log` (tail of
`dev.log`) and `snapshot.json`. `report.json` carries `kind` (`annotation`),
`time`, `note`, `session`, `build`, `godot`, `game`, the host's `context`
fields, `paused`, `scene`, `window`, `canvas`, `shapes` and `selected` (in
`annotated.png` pixels), `image` and `files` (absolute paths). Beside it
`feedback-<date>.md` gets one `## <time>: <note>` section per bundle, ending in
a ready-to-run prompt, and `feedback.jsonl` one line per moment (`annotation`
on save, plus `session_start`, `recording_sync`, `engine_error`, `session_end`
and whatever the host's telemetry adds).
## Tests
```bash
godot_dev_tools/test.sh # all, under 60 s
godot_dev_tools/test.sh -gselect=test_dev_host # one file
godot_dev_tools/lint.sh
```
CI: `.github/workflows/godot-dev-tools-tests.yml` (path-filtered).