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 `##