From db2650b9c9b722ed6554b24ad650f3c0bbe33152 Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Mon, 16 Nov 2026 14:29:48 +0100 Subject: [PATCH] Add godot_dev_tools 0.1.0 Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01WzxdWXs4gEhEUMr9rgYG9V --- .github/workflows/godot-dev-tools-tests.yml | 37 +++ godot_dev_tools/.gdlintrc | 4 + godot_dev_tools/.gitignore | 3 + godot_dev_tools/.gutconfig.json | 9 + godot_dev_tools/README.md | 120 +++++++++ .../addons/dev_tools/annotate_bar.gd | 111 ++++++++ .../addons/dev_tools/annotate_bar.gd.uid | 1 + .../addons/dev_tools/annotate_shapes.gd | 147 +++++++++++ .../addons/dev_tools/annotate_shapes.gd.uid | 1 + godot_dev_tools/addons/dev_tools/annotator.gd | 249 ++++++++++++++++++ .../addons/dev_tools/annotator.gd.uid | 1 + godot_dev_tools/addons/dev_tools/dev_frame.gd | 20 ++ .../addons/dev_tools/dev_frame.gd.uid | 1 + .../addons/dev_tools/dev_glyphs.gd | 70 +++++ .../addons/dev_tools/dev_glyphs.gd.uid | 1 + godot_dev_tools/addons/dev_tools/dev_hint.gd | 52 ++++ .../addons/dev_tools/dev_hint.gd.uid | 1 + godot_dev_tools/addons/dev_tools/dev_host.gd | 107 ++++++++ .../addons/dev_tools/dev_host.gd.uid | 1 + godot_dev_tools/addons/dev_tools/dev_log.gd | 97 +++++++ .../addons/dev_tools/dev_log.gd.uid | 1 + .../addons/dev_tools/dev_logger.gd | 72 +++++ .../addons/dev_tools/dev_logger.gd.uid | 1 + godot_dev_tools/addons/dev_tools/dev_style.gd | 32 +++ .../addons/dev_tools/dev_style.gd.uid | 1 + .../addons/dev_tools/dev_tools.cfg | 4 + godot_dev_tools/addons/dev_tools/dev_tools.gd | 171 ++++++++++++ .../addons/dev_tools/dev_tools.gd.uid | 1 + .../addons/dev_tools/feedback_context.gd | 49 ++++ .../addons/dev_tools/feedback_context.gd.uid | 1 + .../addons/dev_tools/feedback_entry.gd | 103 ++++++++ .../addons/dev_tools/feedback_entry.gd.uid | 1 + .../addons/dev_tools/feedback_saver.gd | 90 +++++++ .../addons/dev_tools/feedback_saver.gd.uid | 1 + .../addons/dev_tools/glyph_texture.gd | 48 ++++ .../addons/dev_tools/glyph_texture.gd.uid | 1 + godot_dev_tools/addons/dev_tools/telemetry.gd | 63 +++++ .../addons/dev_tools/telemetry.gd.uid | 1 + .../addons/dev_tools/vector_glyph.gd | 200 ++++++++++++++ .../addons/dev_tools/vector_glyph.gd.uid | 1 + godot_dev_tools/lint.sh | 31 +++ godot_dev_tools/project.godot | 19 ++ godot_dev_tools/requirements-dev.txt | 1 + godot_dev_tools/test.sh | 98 +++++++ godot_dev_tools/tests/stub_host.gd | 48 ++++ godot_dev_tools/tests/stub_host.gd.uid | 1 + godot_dev_tools/tests/test_annotator.gd | 177 +++++++++++++ godot_dev_tools/tests/test_annotator.gd.uid | 1 + .../tests/test_annotator_bundle.gd | 249 ++++++++++++++++++ .../tests/test_annotator_bundle.gd.uid | 1 + godot_dev_tools/tests/test_dev_host.gd | 61 +++++ godot_dev_tools/tests/test_dev_host.gd.uid | 1 + godot_dev_tools/tests/test_dev_tools.gd | 246 +++++++++++++++++ godot_dev_tools/tests/test_dev_tools.gd.uid | 1 + godot_dev_tools/tests/test_feedback_saver.gd | 27 ++ .../tests/test_feedback_saver.gd.uid | 1 + godot_dev_tools/tests/tmp_dir.gd | 26 ++ godot_dev_tools/tests/tmp_dir.gd.uid | 1 + 58 files changed, 2865 insertions(+) create mode 100644 .github/workflows/godot-dev-tools-tests.yml create mode 100644 godot_dev_tools/.gdlintrc create mode 100644 godot_dev_tools/.gitignore create mode 100644 godot_dev_tools/.gutconfig.json create mode 100644 godot_dev_tools/README.md create mode 100644 godot_dev_tools/addons/dev_tools/annotate_bar.gd create mode 100644 godot_dev_tools/addons/dev_tools/annotate_bar.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/annotate_shapes.gd create mode 100644 godot_dev_tools/addons/dev_tools/annotate_shapes.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/annotator.gd create mode 100644 godot_dev_tools/addons/dev_tools/annotator.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/dev_frame.gd create mode 100644 godot_dev_tools/addons/dev_tools/dev_frame.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/dev_glyphs.gd create mode 100644 godot_dev_tools/addons/dev_tools/dev_glyphs.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/dev_hint.gd create mode 100644 godot_dev_tools/addons/dev_tools/dev_hint.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/dev_host.gd create mode 100644 godot_dev_tools/addons/dev_tools/dev_host.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/dev_log.gd create mode 100644 godot_dev_tools/addons/dev_tools/dev_log.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/dev_logger.gd create mode 100644 godot_dev_tools/addons/dev_tools/dev_logger.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/dev_style.gd create mode 100644 godot_dev_tools/addons/dev_tools/dev_style.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/dev_tools.cfg create mode 100644 godot_dev_tools/addons/dev_tools/dev_tools.gd create mode 100644 godot_dev_tools/addons/dev_tools/dev_tools.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/feedback_context.gd create mode 100644 godot_dev_tools/addons/dev_tools/feedback_context.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/feedback_entry.gd create mode 100644 godot_dev_tools/addons/dev_tools/feedback_entry.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/feedback_saver.gd create mode 100644 godot_dev_tools/addons/dev_tools/feedback_saver.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/glyph_texture.gd create mode 100644 godot_dev_tools/addons/dev_tools/glyph_texture.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/telemetry.gd create mode 100644 godot_dev_tools/addons/dev_tools/telemetry.gd.uid create mode 100644 godot_dev_tools/addons/dev_tools/vector_glyph.gd create mode 100644 godot_dev_tools/addons/dev_tools/vector_glyph.gd.uid create mode 100755 godot_dev_tools/lint.sh create mode 100644 godot_dev_tools/project.godot create mode 100644 godot_dev_tools/requirements-dev.txt create mode 100755 godot_dev_tools/test.sh create mode 100644 godot_dev_tools/tests/stub_host.gd create mode 100644 godot_dev_tools/tests/stub_host.gd.uid create mode 100644 godot_dev_tools/tests/test_annotator.gd create mode 100644 godot_dev_tools/tests/test_annotator.gd.uid create mode 100644 godot_dev_tools/tests/test_annotator_bundle.gd create mode 100644 godot_dev_tools/tests/test_annotator_bundle.gd.uid create mode 100644 godot_dev_tools/tests/test_dev_host.gd create mode 100644 godot_dev_tools/tests/test_dev_host.gd.uid create mode 100644 godot_dev_tools/tests/test_dev_tools.gd create mode 100644 godot_dev_tools/tests/test_dev_tools.gd.uid create mode 100644 godot_dev_tools/tests/test_feedback_saver.gd create mode 100644 godot_dev_tools/tests/test_feedback_saver.gd.uid create mode 100644 godot_dev_tools/tests/tmp_dir.gd create mode 100644 godot_dev_tools/tests/tmp_dir.gd.uid diff --git a/.github/workflows/godot-dev-tools-tests.yml b/.github/workflows/godot-dev-tools-tests.yml new file mode 100644 index 0000000..1df57bf --- /dev/null +++ b/.github/workflows/godot-dev-tools-tests.yml @@ -0,0 +1,37 @@ +name: godot_dev_tools tests + +on: + push: + branches: [main] + paths: ['godot_dev_tools/**', '.github/workflows/godot-dev-tools-tests.yml'] + pull_request: + branches: [main] + paths: ['godot_dev_tools/**', '.github/workflows/godot-dev-tools-tests.yml'] + +env: + GODOT_VERSION: "4.7.2" + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: { python-version: "3.x" } + + - name: Install Godot + run: | + curl -fsSL -o godot.zip "https://github.com/godotengine/godot/releases/download/${GODOT_VERSION}-stable/Godot_v${GODOT_VERSION}-stable_linux.x86_64.zip" + unzip -q godot.zip + sudo mv "Godot_v${GODOT_VERSION}-stable_linux.x86_64" /usr/local/bin/godot + rm godot.zip + + - name: Install gdtoolkit (pinned) + run: pip install -r godot_dev_tools/requirements-dev.txt + + - name: Lint (gdlint, gdformat) + run: godot_dev_tools/lint.sh + + - name: GUT against the stub host (GUT is fetched at its pinned tag) + run: godot_dev_tools/test.sh diff --git a/godot_dev_tools/.gdlintrc b/godot_dev_tools/.gdlintrc new file mode 100644 index 0000000..67c6799 --- /dev/null +++ b/godot_dev_tools/.gdlintrc @@ -0,0 +1,4 @@ +# gdlint: every check on, no rule disabled. The cap matches the shared 250-line gate. +max-file-lines: 250 +max-line-length: 100 +disable: [] diff --git a/godot_dev_tools/.gitignore b/godot_dev_tools/.gitignore new file mode 100644 index 0000000..eb549e6 --- /dev/null +++ b/godot_dev_tools/.gitignore @@ -0,0 +1,3 @@ +# fetched by test.sh at the pinned tag, never committed +addons/gut/ +.godot/ diff --git a/godot_dev_tools/.gutconfig.json b/godot_dev_tools/.gutconfig.json new file mode 100644 index 0000000..689355e --- /dev/null +++ b/godot_dev_tools/.gutconfig.json @@ -0,0 +1,9 @@ +{ + "dirs": ["res://tests/"], + "include_subdirs": true, + "prefix": "test_", + "suffix": ".gd", + "should_exit": true, + "should_exit_on_success": true, + "log_level": 1 +} diff --git a/godot_dev_tools/README.md b/godot_dev_tools/README.md new file mode 100644 index 0000000..eae5e7d --- /dev/null +++ b/godot_dev_tools/README.md @@ -0,0 +1,120 @@ +# 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`. + +## 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.0 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/_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/_binaries/feedback` on `--dev` when that `_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) + +`//` 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-.md` gets one `##