Add godot_dev_tools 0.1.0

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWXs4gEhEUMr9rgYG9V
This commit is contained in:
Krzysztof Rudnicki 2026-11-16 14:29:48 +01:00
parent 65e72d8ded
commit db2650b9c9
58 changed files with 2865 additions and 0 deletions

View File

@ -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

View File

@ -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: []

3
godot_dev_tools/.gitignore vendored Normal file
View File

@ -0,0 +1,3 @@
# fetched by test.sh at the pinned tag, never committed
addons/gut/
.godot/

View File

@ -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
}

120
godot_dev_tools/README.md Normal file
View File

@ -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<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.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/<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).

View File

@ -0,0 +1,111 @@
extends RefCounted
## Widgets of the annotator's bars: glyph buttons, the note field and the dark
## strip they sit on. No class_name (the addon's scripts reach each other with relative preload).
const DevGlyphs = preload("dev_glyphs.gd")
const DevShapes = preload("annotate_shapes.gd")
const DevStyle = preload("dev_style.gd")
const BUTTON_PX := 72
const LABEL_WIDTH_PX := 420.0
## Builds the toolbar (tools, undo, clear, save, cancel), the note strip and the
## floating label field of `owner` (an annotator) and fills its bars,
## tool_buttons, action_buttons, note and text_field.
static func build(owner: Control) -> void:
var top := _strip(owner, Control.PRESET_TOP_WIDE)
for id: String in DevShapes.TOOLS:
owner.tool_buttons[id] = icon_button(top, id, owner.set_tool.bind(id))
owner.action_buttons["undo"] = icon_button(top, "undo", owner.undo)
owner.action_buttons["clear"] = icon_button(top, "clear", owner.clear)
var gap := Control.new()
gap.size_flags_horizontal = Control.SIZE_EXPAND_FILL
top.add_child(gap)
owner.action_buttons["save"] = icon_button(top, "save", owner.save)
owner.action_buttons["cancel"] = icon_button(top, "cancel", owner.cancel)
var bottom := _strip(owner, Control.PRESET_BOTTOM_WIDE)
bottom.add_child(glyph("note"))
owner.note = note_field()
owner.note.text_submitted.connect(func(_text: String) -> void: owner.save())
owner.note.text_changed.connect(func(_text: String) -> void: owner.disarm())
owner.note.gui_input.connect(_leave_on_escape.bind(owner.note, false))
bottom.add_child(owner.note)
# The label field floats at the click; Enter adds the label, Esc drops it.
var field := note_field()
field.size_flags_horizontal = Control.SIZE_FILL
field.custom_minimum_size.x = LABEL_WIDTH_PX
field.size.x = LABEL_WIDTH_PX
field.hide()
field.text_submitted.connect(func(_text: String) -> void: owner.commit_text())
field.gui_input.connect(_leave_on_escape.bind(field, true))
owner.add_child(field)
owner.text_field = field
## Esc inside a text field only leaves it (a label is dropped); a second Esc cancels.
static func _leave_on_escape(event: InputEvent, field: LineEdit, drop: bool) -> void:
var key := event as InputEventKey
if key != null and key.pressed and key.keycode == KEY_ESCAPE:
if drop:
field.text = ""
field.hide()
field.release_focus()
field.accept_event()
static func _strip(owner: Control, preset: Control.LayoutPreset) -> HBoxContainer:
var strip := panel(preset)
owner.add_child(strip)
strip.set_anchors_and_offsets_preset(preset)
owner.bars.append(strip)
return strip.get_child(0)
static func icon_button(row: Control, kind: String, on_press: Callable) -> Button:
var button := Button.new()
button.icon = DevGlyphs.texture(kind)
button.accessibility_name = kind
button.expand_icon = true
button.custom_minimum_size = Vector2.ONE * BUTTON_PX
button.focus_mode = Control.FOCUS_NONE
button.pressed.connect(on_press)
row.add_child(button)
return button
static func glyph(kind: String) -> TextureRect:
var rect := TextureRect.new()
rect.texture = DevGlyphs.texture(kind)
rect.accessibility_name = kind
rect.custom_minimum_size = Vector2.ONE * 48.0
rect.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
rect.mouse_filter = Control.MOUSE_FILTER_IGNORE
return rect
static func note_field() -> LineEdit:
var field := LineEdit.new()
field.size_flags_horizontal = Control.SIZE_EXPAND_FILL
field.custom_minimum_size.y = 56.0
field.accessibility_name = "note"
field.add_theme_font_size_override("font_size", 28)
var style := StyleBoxFlat.new()
style.bg_color = DevStyle.panel_pressed
style.set_content_margin_all(8)
field.add_theme_stylebox_override("normal", style)
return field
## A dark strip (the caller anchors it to `preset`) holding one HBoxContainer row.
static func panel(preset: Control.LayoutPreset) -> PanelContainer:
var strip := PanelContainer.new()
var style := StyleBoxFlat.new()
style.bg_color = Color(DevStyle.panel, 0.88)
style.set_content_margin_all(8)
strip.add_theme_stylebox_override("panel", style)
var bottom := preset == Control.PRESET_BOTTOM_WIDE
strip.grow_vertical = Control.GROW_DIRECTION_BEGIN if bottom else Control.GROW_DIRECTION_END
var row := HBoxContainer.new()
row.add_theme_constant_override("separation", 10)
strip.add_child(row)
return strip

View File

@ -0,0 +1 @@
uid://dyc2xpv5ct3s1

View File

@ -0,0 +1,147 @@
extends RefCounted
## The red marks of the annotator as plain data, so a test or a bot draws the
## same marks a mouse does. A shape is {tool, a, b, points}: rect/circle span
## the box a..b, an arrow points at b, a pen stroke follows `points`, a text
## label starts at a (key `text`), a select ring sits at a around the game
## object that was under the cursor (key `entity`, the host's pick_at).
## No class_name (the addon's scripts reach each other with relative preload).
const DevStyle = preload("dev_style.gd")
const TOOLS: Array[String] = ["rect", "arrow", "circle", "pen", "text", "select"]
const KEYS := {
KEY_R: "rect", KEY_A: "arrow", KEY_C: "circle", KEY_P: "pen", KEY_T: "text", KEY_S: "select"
}
const WIDTH := 5.0
const HEAD_LEN := 26.0
const HEAD_ANGLE := 0.45
const MIN_DRAG := 3.0
## Pen samples closer than this (px) are dropped.
const PEN_STEP := 3.0
const FONT_PX := 32
const OUTLINE_PX := 8
const RING_PX := 20.0
static func make(
shape_tool: String, a: Vector2, b: Vector2, points := PackedVector2Array(), extra := {}
) -> Dictionary:
var shape := {"tool": shape_tool, "a": a, "b": b, "points": points}
shape.merge(extra)
return shape
## A mouse drag moved `shape` on to `at`: a pen stroke also keeps the point.
static func extend(shape: Dictionary, at: Vector2) -> void:
shape["b"] = at
var points: PackedVector2Array = shape["points"]
if shape["tool"] == "pen" and points[points.size() - 1].distance_to(at) >= PEN_STEP:
points.append(at)
shape["points"] = points
## A drag too short to mean anything is a stray click, not a mark.
static func meaningful(shape: Dictionary) -> bool:
match shape["tool"]:
"pen":
return (shape["points"] as PackedVector2Array).size() >= 2
"text":
return str(shape.get("text", "")).strip_edges() != ""
"select":
return not (shape.get("entity", {}) as Dictionary).is_empty()
return (shape["a"] as Vector2).distance_to(shape["b"]) > MIN_DRAG
static func paint(canvas: CanvasItem, shape: Dictionary) -> void:
var a: Vector2 = shape["a"]
var b: Vector2 = shape["b"]
match shape["tool"]:
"rect":
canvas.draw_rect(Rect2(a, b - a).abs(), DevStyle.mark, false, WIDTH)
"circle":
canvas.draw_polyline(ellipse(Rect2(a, b - a).abs()), DevStyle.mark, WIDTH)
"arrow":
canvas.draw_line(a, b, DevStyle.mark, WIDTH)
canvas.draw_colored_polygon(arrow_head(a, b), DevStyle.mark)
"pen":
var points: PackedVector2Array = shape["points"]
if points.size() >= 2:
canvas.draw_polyline(points, DevStyle.mark, WIDTH, true)
"text":
_label(canvas, a, str(shape["text"]))
"select":
canvas.draw_polyline(
ellipse(Rect2(a - Vector2.ONE * RING_PX, Vector2.ONE * RING_PX * 2)),
DevStyle.mark,
WIDTH
)
canvas.draw_line(
a - Vector2(RING_PX * 1.6, 0), a + Vector2(RING_PX * 1.6, 0), DevStyle.mark, 2.0
)
canvas.draw_line(
a - Vector2(0, RING_PX * 1.6), a + Vector2(0, RING_PX * 1.6), DevStyle.mark, 2.0
)
_label(canvas, a + Vector2(RING_PX + 10, -RING_PX), str(shape["entity"].get("id", "")))
## Red words with a dark outline, `at` = the top-left of the text.
static func _label(canvas: CanvasItem, at: Vector2, text: String) -> void:
var font := ThemeDB.fallback_font
var base := at + Vector2(0, FONT_PX)
canvas.draw_string_outline(
font, base, text, HORIZONTAL_ALIGNMENT_LEFT, -1, FONT_PX, OUTLINE_PX, DevStyle.panel
)
canvas.draw_string(font, base, text, HORIZONTAL_ALIGNMENT_LEFT, -1, FONT_PX, DevStyle.mark)
static func ellipse(box: Rect2) -> PackedVector2Array:
var points := PackedVector2Array()
for i in 49:
var angle := TAU * i / 48.0
points.append(box.get_center() + Vector2(cos(angle), sin(angle)) * box.size / 2.0)
return points
static func arrow_head(a: Vector2, b: Vector2) -> PackedVector2Array:
var back := (a - b).normalized() * HEAD_LEN
return PackedVector2Array([b, b + back.rotated(HEAD_ANGLE), b + back.rotated(-HEAD_ANGLE)])
## JSON-safe shape in the saved PNG's pixels (`scale` = png size / canvas size).
static func to_json(shape: Dictionary, scale: Vector2) -> Dictionary:
var out := {"tool": shape["tool"], "a": _pt(shape["a"], scale), "b": _pt(shape["b"], scale)}
if shape["tool"] == "pen":
var points := []
for p: Vector2 in shape["points"]:
points.append(_pt(p, scale))
out["points"] = points
if shape["tool"] == "text":
out["text"] = shape["text"]
if shape["tool"] == "select":
out["entity"] = entity_json(shape, scale)
return out
## {shapes, selected} for the report: every mark, and the game objects the
## select marks name, all in the saved PNG's pixels.
## `first`: an object selected without a click (the painting held up in an
## inspection, its "at" already in PNG pixels); a click on it is not listed twice.
static func marks_json(shapes: Array[Dictionary], scale: Vector2, first := {}) -> Dictionary:
var marks := []
var selected := [] if first.is_empty() else [first.duplicate(true)]
for shape in shapes:
marks.append(to_json(shape, scale))
var entity: Dictionary = shape.get("entity", {})
if shape["tool"] == "select" and (first.is_empty() or entity.get("id") != first["id"]):
selected.append(entity_json(shape, scale))
return {"shapes": marks, "selected": selected}
## The selected game object plus where you clicked, in the PNG's pixels.
static func entity_json(shape: Dictionary, scale: Vector2) -> Dictionary:
var out: Dictionary = (shape["entity"] as Dictionary).duplicate(true)
out["at"] = _pt(shape["a"], scale)
return out
static func _pt(p: Vector2, scale: Vector2) -> Array:
return [roundi(p.x * scale.x), roundi(p.y * scale.y)]

View File

@ -0,0 +1 @@
uid://cb24t2ue75l4a

View File

@ -0,0 +1,249 @@
extends Control
## F12 (or the camera glyph): the frozen frame with red tools over it, text-free.
## Mouse: tool glyphs (rect, arrow, circle, pen, text label, select-entity), undo,
## clear (undoable), an optional note, save (check) or cancel (cross; with unsaved
## work the first press only arms it). Keys: R A C P T S tools, Ctrl+Z undo, Enter
## save, Esc cancel (in a text field it only leaves it). Save burns the marks in.
signal closed(saved_to: String)
const DevShapes = preload("annotate_shapes.gd")
const DevBar = preload("annotate_bar.gd")
const DevEntry = preload("feedback_entry.gd")
const DevFrame = preload("dev_frame.gd")
const DevSaver = preload("feedback_saver.gd")
const DevStyle = preload("dev_style.gd")
const LOG_TAIL := 200
var dev_log: RefCounted
var shapes: Array[Dictionary] = []
var drawing_tool: String = "rect"
## The bundle folder; "" = <dev_log.dir>/<stamp>.
var save_path: String = ""
var raw: Image
## What F12 froze: the bundle context (feedback_context.gd) and the host's debug_state.
var context: Dictionary = {}
var snapshot: Dictionary = {}
## Callable(at: Vector2) -> Dictionary: the game object under a canvas point.
var picker := Callable()
## The host's summary_line / entity_line Callables (feedback_entry.gd).
var markdown_hooks: Dictionary = {}
var note: LineEdit
var text_field: LineEdit
## Filled by DevBar.build: the strips, buttons by tool id, buttons by action name.
var bars: Array[Control] = []
var tool_buttons: Dictionary = {}
var action_buttons: Dictionary = {}
## True after a first cancel with unsaved work: the next cancel closes.
var cancel_pending := false
var _stroke: Dictionary = {}
var _texture: ImageTexture
var _history: Array = []
var _text_at := Vector2.ZERO
func open(frame: Image, p_log: RefCounted, p_context := {}, p_snapshot := {}) -> void:
process_mode = Node.PROCESS_MODE_ALWAYS
add_to_group(&"annotator") # the game leaves Esc and the mouse alone while this is open
set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
mouse_filter = Control.MOUSE_FILTER_STOP
raw = frame
dev_log = p_log
context = p_context
snapshot = p_snapshot
_texture = ImageTexture.create_from_image(frame)
DevBar.build(self)
set_tool("rect")
func set_tool(shape_tool: String) -> void:
commit_text()
drawing_tool = shape_tool
for id: String in tool_buttons:
tool_buttons[id].modulate = Color(Color.WHITE, 1.0 if id == shape_tool else 0.5)
## False (nothing added) for a drag too short to mean anything.
func add_shape(shape_tool: String, from: Vector2, to: Vector2) -> bool:
return _add(DevShapes.make(shape_tool, from, to))
func add_stroke(points: PackedVector2Array) -> bool:
return _add(DevShapes.make("pen", points[0], points[points.size() - 1], points))
## A typed label whose top-left sits at `at`; false for empty text.
func add_text(at: Vector2, text: String) -> bool:
return _add(DevShapes.make("text", at, at, PackedVector2Array(), {"text": text.strip_edges()}))
## Attaches the game object under `at` (the picker's answer); false when there
## is none or no picker.
func select_at(at: Vector2) -> bool:
if not picker.is_valid():
return false
var entity: Dictionary = picker.call(at)
return _add(DevShapes.make("select", at, at, PackedVector2Array(), {"entity": entity}))
func undo() -> void:
if not _history.is_empty():
shapes.assign(_history.pop_back())
disarm()
queue_redraw()
## Removes every mark; one undo brings them all back.
func clear() -> void:
if shapes.is_empty():
return
_remember()
shapes.clear()
queue_redraw()
func has_unsaved() -> bool:
return not shapes.is_empty() or (note != null and note.text != "")
## The report: the frozen context, note, marks and selected objects (PNG pixels).
func record() -> Dictionary:
var out := context.duplicate(true)
var scale := Vector2.ONE
if raw != null and size.x > 0.0 and size.y > 0.0:
scale = Vector2(raw.get_width() / size.x, raw.get_height() / size.y)
out["kind"] = "annotation"
out["time"] = Time.get_datetime_string_from_system()
out["note"] = note.text if note != null else ""
out.merge(DevShapes.marks_json(shapes, scale))
return out
## Burns the marks in (viewport capture without the bars) and writes.
func save() -> void:
_stroke = {}
commit_text()
for bar in bars:
bar.hide()
var annotated: Image = await DevFrame.grab(get_viewport())
for bar in bars:
bar.show()
if annotated != null and raw != null and annotated.get_size() != raw.get_size():
annotated.resize(raw.get_width(), raw.get_height(), Image.INTERPOLATE_NEAREST)
write(annotated)
## Writes the bundle folder + Markdown entry; emits `closed` with the PNG path ("" = failed).
func write(annotated: Image) -> void:
var dir := save_path if save_path != "" else DevSaver.bundle_dir(dev_log.dir)
var saved := DevSaver.save(dir, record(), annotated, raw, dev_log.tail(LOG_TAIL), snapshot)
DevEntry.append(dev_log.dir, saved, markdown_hooks)
var png: String = saved["files"].get("annotated", "")
dev_log.entry(DevSaver.log_entry(dir, saved, shapes.size()))
dev_log.write("feedback saved %s ok=%s" % [dir, png != ""])
closed.emit(png)
## With unsaved marks or a note the first cancel only arms the cross.
func cancel() -> void:
if has_unsaved() and not cancel_pending:
cancel_pending = true
action_buttons["cancel"].modulate = DevStyle.armed
return
closed.emit("")
func _add(shape: Dictionary) -> bool:
if not DevShapes.meaningful(shape):
return false
_remember()
shapes.append(shape)
queue_redraw()
return true
## The undo step before a change; any change also disarms the cancel ask.
func _remember() -> void:
_history.append(shapes.duplicate())
disarm()
func disarm() -> void:
cancel_pending = false
if action_buttons.has("cancel"):
action_buttons["cancel"].modulate = Color.WHITE
func _gui_input(event: InputEvent) -> void:
var button := event as InputEventMouseButton
var motion := event as InputEventMouseMotion
if button != null and button.button_index == MOUSE_BUTTON_LEFT:
if button.pressed:
_press(button.position)
else:
_release(button.position)
accept_event()
elif motion != null and not _stroke.is_empty():
_drag(motion.position)
accept_event()
func _press(at: Vector2) -> void:
commit_text()
if drawing_tool == "select":
select_at(at)
elif drawing_tool == "text":
_text_at = at
text_field.position = at
text_field.show()
text_field.grab_focus()
else:
_stroke = DevShapes.make(drawing_tool, at, at, PackedVector2Array([at]))
queue_redraw()
func _drag(at: Vector2) -> void:
DevShapes.extend(_stroke, at)
queue_redraw()
func _release(at: Vector2) -> void:
if _stroke.is_empty():
return
_drag(at)
_add(_stroke)
_stroke = {}
queue_redraw()
func commit_text() -> void:
if text_field != null and text_field.visible:
add_text(_text_at, text_field.text)
text_field.text = ""
text_field.hide()
func _unhandled_key_input(event: InputEvent) -> void:
var key := event as InputEventKey
if key == null or not key.pressed or key.echo:
return
if DevShapes.KEYS.has(key.keycode) and not key.ctrl_pressed:
set_tool(DevShapes.KEYS[key.keycode])
elif key.keycode == KEY_Z and key.ctrl_pressed:
undo()
elif key.keycode == KEY_ENTER or key.keycode == KEY_KP_ENTER:
save()
elif key.keycode == KEY_ESCAPE:
cancel()
else:
return
get_viewport().set_input_as_handled()
func _draw() -> void:
draw_texture_rect(_texture, Rect2(Vector2.ZERO, size), false)
for shape in shapes:
DevShapes.paint(self, shape)
if not _stroke.is_empty():
DevShapes.paint(self, _stroke)

View File

@ -0,0 +1 @@
uid://bncbwba6r1j0a

View File

@ -0,0 +1,20 @@
extends RefCounted
## The frame as drawn, for the annotator. A headless run (a bot, a test) draws
## nothing and never emits frame_post_draw, so it gets a blank frame of the
## viewport's size at once: the bundle is still written, only the picture is empty.
## No class_name (the addon's scripts reach each other with relative preload).
const BLANK := Color(0.1, 0.1, 0.1)
## The viewport's last drawn frame (waits for the draw; instant when headless).
static func grab(viewport: Viewport) -> Image:
if DisplayServer.get_name() == "headless":
var size := viewport.get_visible_rect().size
var blank := Image.create(
maxi(1, int(size.x)), maxi(1, int(size.y)), false, Image.FORMAT_RGBA8
)
blank.fill(BLANK)
return blank
await RenderingServer.frame_post_draw
return viewport.get_texture().get_image()

View File

@ -0,0 +1 @@
uid://vik3wxknlotp

View File

@ -0,0 +1,70 @@
extends RefCounted
## Icons of the dev tools, drawn as vector glyphs (sharp at any size, no text,
## no icon words). Kinds: rect arrow circle pen undo clear text select save
## cancel note camera. No class_name (the addon's scripts use relative preload).
const DevVectorGlyph = preload("vector_glyph.gd")
const DevGlyphTexture = preload("glyph_texture.gd")
static var _textures: Dictionary = {}
static func texture(kind: String) -> Texture2D:
if not _textures.has(kind):
_textures[kind] = DevGlyphTexture.of(_build(kind))
return _textures[kind]
static func _build(kind: String) -> DevVectorGlyph:
var g := DevVectorGlyph.new()
match kind:
"rect":
g.frame(18, 30, 92, 68, 10)
"arrow":
g.line(Vector2(22, 106), Vector2(80, 48), 13)
g.polygon(PackedVector2Array([Vector2(106, 22), Vector2(62, 34), Vector2(94, 66)]))
"circle":
g.ring(Vector2(64, 64), 46, 36)
"pen":
var path := [Vector2(18, 92), Vector2(44, 40), Vector2(66, 90)]
path.append_array([Vector2(90, 38), Vector2(110, 78)])
for i in path.size() - 1:
g.line(path[i], path[i + 1], 10)
g.ring(path[i + 1], 5)
"undo":
g.polygon(PackedVector2Array([Vector2(14, 54), Vector2(50, 22), Vector2(50, 86)]))
g.line(Vector2(46, 54), Vector2(84, 54), 14)
g.line(Vector2(84, 54), Vector2(106, 74), 14)
g.line(Vector2(106, 74), Vector2(84, 98), 14)
g.line(Vector2(84, 98), Vector2(40, 98), 14)
"clear":
g.rect(30, 44, 68, 12)
g.rect(40, 62, 48, 44)
g.rect(52, 28, 24, 12)
"text":
g.rect(18, 24, 92, 14)
g.rect(57, 24, 14, 80)
"select":
g.ring(Vector2(64, 64), 34, 22)
g.rect(60, 10, 8, 30)
g.rect(60, 88, 8, 30)
g.rect(10, 60, 30, 8)
g.rect(88, 60, 30, 8)
"save":
g.line(Vector2(22, 66), Vector2(52, 96), 16)
g.line(Vector2(52, 96), Vector2(106, 30), 16)
"cancel":
g.line(Vector2(26, 26), Vector2(102, 102), 16)
g.line(Vector2(102, 26), Vector2(26, 102), 16)
"note":
g.rect(18, 30, 92, 12)
g.rect(18, 58, 92, 12)
g.rect(18, 86, 58, 12)
"camera":
g.rect(12, 38, 104, 72)
g.rect(44, 24, 40, 18)
g.ring(Vector2(64, 74), 26, 0.0, true)
g.ring(Vector2(64, 74), 15)
_:
push_error("unknown dev glyph %s" % kind)
return g

View File

@ -0,0 +1 @@
uid://drx1hdo3u8h0q

View File

@ -0,0 +1,52 @@
extends Control
## The dev mode's discoverability hint: a small camera glyph in a corner of the
## screen (no text). Click it (when the mouse is free: hub, pause menu) or press
## F12 to annotate the frame. Faint until hovered; never takes focus.
## No class_name (the addon's scripts reach each other with relative preload).
signal pressed
const DevGlyphs = preload("dev_glyphs.gd")
const DevStyle = preload("dev_style.gd")
const SIZE_PX := 56.0
const MARGIN_PX := 14
var _hover := false
func _init() -> void:
custom_minimum_size = Vector2.ONE * SIZE_PX
accessibility_name = "annotate"
mouse_filter = Control.MOUSE_FILTER_STOP
focus_mode = Control.FOCUS_NONE
mouse_entered.connect(_set_hover.bind(true))
mouse_exited.connect(_set_hover.bind(false))
func _ready() -> void:
set_anchors_preset(Control.PRESET_TOP_RIGHT)
offset_right = -MARGIN_PX
offset_left = -MARGIN_PX - SIZE_PX
offset_top = MARGIN_PX
offset_bottom = MARGIN_PX + SIZE_PX
func _gui_input(event: InputEvent) -> void:
var button := event as InputEventMouseButton
if button != null and button.button_index == MOUSE_BUTTON_LEFT and button.pressed:
accept_event()
pressed.emit()
func _set_hover(on: bool) -> void:
_hover = on
queue_redraw()
func _draw() -> void:
# A dark copy under the white one keeps it readable on a light wall too.
var glyph := DevGlyphs.texture("camera")
var shadow := Color(DevStyle.panel, 0.45)
var ink := Color(DevStyle.ink, 0.95 if _hover else 0.38)
draw_texture_rect(glyph, Rect2(Vector2(2, 2), size), false, shadow)
draw_texture_rect(glyph, Rect2(Vector2.ZERO, size), false, ink)

View File

@ -0,0 +1 @@
uid://tdvupd68rlj4

View File

@ -0,0 +1,107 @@
extends RefCounted
## What the dev tools know about the game they sit in. A game hands in ONE
## object (any Object: a RefCounted of its own, no base class, no addon path in
## its source) and this wrapper asks it, with a default for everything the game
## does not provide. A method the object lacks is simply not called.
##
## Values (a property or a method of the same name, either works):
## game name of the game: the folder ~/data/<game>_binaries/feedback
## and the "game" field of a bundle (default "game")
## feedback_env environment variable that overrides the feedback folder
## (default DEV_FEEDBACK_DIR)
## colors Dictionary, keys mark armed panel panel_pressed ink (dev_style.gd)
## Methods:
## debug_state() -> Dictionary the whole visible state: snapshot.json
## pick_at(at: Vector2) -> Dictionary the game object under a canvas point ({} = none)
## context(state: Dictionary) -> Dictionary
## game fields of the bundle (mode, screen, ...)
## reset_progress() -> int F9: wipe saved progress, return files removed
## (without it F9 does nothing)
## add_menu_entry(id, icon, spoken, on_press) -> void
## put the camera into the game's pause menu
## close_menu() -> void close that menu before a frame is frozen
## attach_telemetry(telemetry) -> void
## connect the game's signals to telemetry.entry(
## event: String, fields: Dictionary)
## summary_line(record) -> String the Markdown entry's "Game ..." line
## entity_line(entity) -> String the Markdown entry's "Selected ..." line
## No class_name (the addon's scripts reach each other with relative preload).
const DEFAULT_GAME := "game"
const DEFAULT_ENV := "DEV_FEEDBACK_DIR"
var _impl: Object
func _init(impl: Object = null) -> void:
_impl = impl
func game() -> String:
return str(_value("game", DEFAULT_GAME))
func feedback_env() -> String:
return str(_value("feedback_env", DEFAULT_ENV))
func colors() -> Dictionary:
return _value("colors", {})
func debug_state() -> Dictionary:
return _call("debug_state", [], {})
func pick_at(at: Vector2) -> Dictionary:
return _call("pick_at", [at], {})
func context(state: Dictionary) -> Dictionary:
return _call("context", [state], {})
func can_reset() -> bool:
return _has("reset_progress")
func reset_progress() -> int:
return _call("reset_progress", [], 0)
func add_menu_entry(id: String, icon: Texture2D, spoken: String, on_press: Callable) -> void:
_call("add_menu_entry", [id, icon, spoken, on_press], null)
func close_menu() -> void:
_call("close_menu", [], null)
func attach_telemetry(telemetry: RefCounted) -> void:
_call("attach_telemetry", [telemetry], null)
## {summary_line, entity_line} Callables for feedback_entry.gd (only the ones the game has).
func markdown_hooks() -> Dictionary:
var hooks := {}
for hook: String in ["summary_line", "entity_line"]:
if _has(hook):
hooks[hook] = Callable(_impl, hook)
return hooks
func _has(member: String) -> bool:
return _impl != null and _impl.has_method(member)
## A method's answer, else a property of the same name, else `fallback`.
func _value(member: String, fallback: Variant) -> Variant:
if _has(member):
return _impl.call(member)
if _impl != null and member in _impl:
return _impl.get(member)
return fallback
func _call(member: String, args: Array, fallback: Variant) -> Variant:
return _impl.callv(member, args) if _has(member) else fallback

View File

@ -0,0 +1 @@
uid://bdmewivxn04u7

View File

@ -0,0 +1,97 @@
extends RefCounted
## Aggressive dev logging: every line goes to stdout (prefix DEV) and is
## appended to <dir>/dev.log. Feedback entries go to <dir>/feedback.jsonl.
## No class_name (the addon's scripts reach each other with relative preload).
const DEFAULT_GAME := "game"
const DEFAULT_ENV := "DEV_FEEDBACK_DIR"
var dir: String
## Joins the entries of one run: random id, set by the telemetry (`--session-id=` wins).
var session: String = ""
## Which build/playtest this run is (`--dev-tag=v01`), stamped on every entry.
var tag: String = arg_value(OS.get_cmdline_user_args(), "--dev-tag=")
var _seq := 0
var _start_ms := Time.get_ticks_msec()
## `game` names the default folder (~/data/<game>_binaries/feedback) and
## `env_name` the environment variable that overrides the folder.
func _init(game := DEFAULT_GAME, env_name := DEFAULT_ENV) -> void:
dir = default_dir(OS.get_cmdline_user_args(), game, env_name)
## The value of the first `<prefix>value` argument, "" when absent.
static func arg_value(args: Array, prefix: String) -> String:
for arg: String in args:
if arg.begins_with(prefix):
return arg.trim_prefix(prefix)
return ""
## Where the logs go, first match wins: `--feedback-dir=` (a recorder passes
## it); an unattended run's own save dir (`--save-dir=`); the environment
## variable `env_name` (a test script sets it: GUT never logs into a real
## folder); kuhy's feedback folder (~/data/<game>_binaries/feedback) on an
## explicit --dev when that folder's parent exists; else the user folder.
static func default_dir(args: Array, game := DEFAULT_GAME, env_name := DEFAULT_ENV) -> String:
var forced := arg_value(args, "--feedback-dir=")
if forced != "":
return forced
for arg: String in args:
if arg.begins_with("--save-dir="):
return arg.trim_prefix("--save-dir=").path_join("dev")
forced = OS.get_environment(env_name)
if forced != "":
return forced
var home := OS.get_environment("HOME")
if home == "":
home = OS.get_environment("USERPROFILE") # Windows has no HOME
var binaries := home.path_join("data/%s_binaries" % game)
if "--dev" in args and home != "" and DirAccess.dir_exists_absolute(binaries):
return binaries.path_join("feedback")
return "user://dev"
func write(message: String) -> void:
var line := "%s %s" % [Time.get_datetime_string_from_system(), message]
print("DEV ", line)
_append("dev.log", line)
## The last `lines` lines of dev.log (the run's own log), "" when there is none.
func tail(lines: int) -> String:
var path := dir.path_join("dev.log")
if not FileAccess.file_exists(path):
return ""
var all := FileAccess.get_file_as_string(path).strip_edges().split("\n")
return "\n".join(all.slice(maxi(0, all.size() - lines))) + "\n"
## One feedback entry as a JSON line (screenshot path, scene, game, time). Every
## entry also gets the run's session id, a sequence number, milliseconds since
## the log opened, the frame and the build tag, so a log can be ordered and joined.
func entry(fields: Dictionary) -> void:
_seq += 1
fields["time"] = Time.get_datetime_string_from_system()
fields["session"] = session
fields["seq"] = _seq
fields["ms"] = Time.get_ticks_msec() - _start_ms
fields["frame"] = Engine.get_process_frames()
if tag != "":
fields["tag"] = tag
_append("feedback.jsonl", JSON.stringify(fields))
func _append(file_name: String, line: String) -> void:
DirAccess.make_dir_recursive_absolute(dir)
var path := dir.path_join(file_name)
var mode := FileAccess.READ_WRITE if FileAccess.file_exists(path) else FileAccess.WRITE
var file := FileAccess.open(path, mode)
if file == null:
push_warning("dev log: cannot open %s" % path)
return
file.seek_end()
file.store_line(line)
file.close()

View File

@ -0,0 +1 @@
uid://bxirga0haf7wb

View File

@ -0,0 +1,72 @@
extends Logger
## Catches what the engine prints to stderr (script errors, push_error,
## push_warning, shader errors, stderr lines) so the telemetry can write it
## into feedback.jsonl next to what the player did. The engine calls this from
## any thread, so it only queues under a mutex; `drain` hands the queue to the
## main thread once per frame. Identical entries fold into one with a count.
## No class_name (dev files reach each other with preload).
const KINDS: Array[String] = ["error", "warning", "script_error", "shader_error"]
## Distinct entries kept between two drains; the rest is only counted.
const MAX_DISTINCT := 20
var dropped := 0
var _mutex := Mutex.new()
var _queue: Dictionary = {}
func _log_error(
function: String,
file: String,
line: int,
code: String,
rationale: String,
_editor_notify: bool,
error_type: int,
script_backtraces: Array[ScriptBacktrace]
) -> void:
var kind := KINDS[error_type] if error_type >= 0 and error_type < KINDS.size() else "error"
var entry := {
"kind": kind,
"message": code,
"detail": rationale,
"file": file,
"line": line,
"function": function,
}
if not script_backtraces.is_empty(): # where in the GDScript it came from
entry["where"] = script_backtraces[0].format().left(400)
_add(entry)
func _log_message(message: String, error: bool) -> void:
if error:
_add({"kind": "stderr", "message": message.strip_edges()})
## The queued entries (each with a `count`), oldest first; empties the queue.
func drain() -> Array[Dictionary]:
_mutex.lock()
var out: Array[Dictionary] = []
for entry: Dictionary in _queue.values():
out.append(entry)
_queue = {}
_mutex.unlock()
return out
func _add(entry: Dictionary) -> void:
var key := (
"%s|%s|%s|%s"
% [entry["kind"], entry.get("file", ""), entry.get("line", 0), entry["message"]]
)
_mutex.lock()
if _queue.has(key):
_queue[key]["count"] += 1
elif _queue.size() < MAX_DISTINCT:
entry["count"] = 1
_queue[key] = entry
else:
dropped += 1
_mutex.unlock()

View File

@ -0,0 +1 @@
uid://cr2j444lvai1k

View File

@ -0,0 +1,32 @@
extends RefCounted
## The few colours of the dev tools. The defaults suit any game; a host (see
## dev_host.gd) can restyle them through its `colors()` keys: mark, armed,
## panel, panel_pressed, ink. Shared by every script of the addon, set once by
## dev_tools.gd before any widget is built.
## No class_name (the addon's scripts reach each other with relative preload).
const DEFAULT_MARK := Color("#FF2626")
const DEFAULT_ARMED := Color("#FF5959")
const DEFAULT_PANEL := Color("#0F121A")
const DEFAULT_PANEL_PRESSED := Color("#333B4D")
const DEFAULT_INK := Color("#FFFFFF")
## The red of the marks and the label text.
static var mark := DEFAULT_MARK
## The cancel button after a first press with unsaved work.
static var armed := DEFAULT_ARMED
## Dark strips, label outlines, the hint's shadow.
static var panel := DEFAULT_PANEL
## The note field's background.
static var panel_pressed := DEFAULT_PANEL_PRESSED
## The hint glyph.
static var ink := DEFAULT_INK
## Takes the host's overrides over the defaults (an unknown key is ignored).
static func apply(colors: Dictionary) -> void:
mark = colors.get("mark", DEFAULT_MARK)
armed = colors.get("armed", DEFAULT_ARMED)
panel = colors.get("panel", DEFAULT_PANEL)
panel_pressed = colors.get("panel_pressed", DEFAULT_PANEL_PRESSED)
ink = colors.get("ink", DEFAULT_INK)

View File

@ -0,0 +1 @@
uid://dl7t6varplgqn

View File

@ -0,0 +1,4 @@
; Release of the dev_tools addon. The git tag is godot-dev-tools-v<version>.
[addon]
version = "0.1.0"

View File

@ -0,0 +1,171 @@
extends Node
## The dev feedback mode. A game adds this node (after `setup(host)`, see
## dev_host.gd) when it was started with --dev; nothing of the addon belongs in
## an exported build.
## F12 freeze the frame and annotate it (rect/arrow/circle/pen/text/select
## + note) -> a bundle folder + a Markdown entry + a jsonl line. The
## camera glyph (top right) and the game's pause menu entry do the same.
## F9 reset the game's saved progress (when its host can)
## always: every key / button press and the host's moments are logged
## --dev-shot=/abs/out.png scripted annotate-and-save into the folder
## /abs/out/ (bundle + overlay.png), then quit (Xvfb proof)
## While the annotator is open it is in the group "annotator": a game leaves
## Esc and the mouse alone then.
## No class_name (the addon's scripts reach each other with relative preload).
const DevAnnotator = preload("annotator.gd")
const DevFrame = preload("dev_frame.gd")
const DevHost = preload("dev_host.gd")
const DevLog = preload("dev_log.gd")
const DevFeedbackContext = preload("feedback_context.gd")
const DevGlyphs = preload("dev_glyphs.gd")
const DevHint = preload("dev_hint.gd")
const DevStyle = preload("dev_style.gd")
const DevTelemetry = preload("telemetry.gd")
const SHOT_PREFIX := "--dev-shot="
const LAYER := 120
const PROBE_GRID := Vector2i(48, 27)
const MENU_ENTRY := "annotate"
var host: RefCounted
var dev_log: RefCounted
var telemetry := DevTelemetry.new()
var annotator: Control = null
var hint: Control
var _layer: CanvasLayer
var _shot_path := ""
## Hands the game in: `impl` is its host object (any Object, see dev_host.gd).
## Call before add_child.
func setup(impl: Object) -> void:
host = DevHost.new(impl)
DevStyle.apply(host.colors())
dev_log = DevLog.new(host.game(), host.feedback_env())
func _ready() -> void:
if host == null:
setup(null)
process_mode = Node.PROCESS_MODE_ALWAYS
_layer = CanvasLayer.new()
_layer.layer = LAYER
add_child(_layer)
hint = DevHint.new()
hint.pressed.connect(func() -> void: annotate())
_layer.add_child(hint)
host.add_menu_entry(MENU_ENTRY, DevGlyphs.texture("camera"), "annotate", _annotate_from_menu)
dev_log.write("dev tools on; logs in %s" % dev_log.dir)
telemetry.attach(dev_log, host)
_shot_path = dev_log.arg_value(OS.get_cmdline_user_args(), SHOT_PREFIX)
if _shot_path != "":
_scripted_shot.call_deferred()
func _process(_delta: float) -> void:
telemetry.tick()
func _input(event: InputEvent) -> void:
_log_input(event)
var key := event as InputEventKey
if key == null or not key.pressed or key.echo:
return
if key.keycode == KEY_F12:
get_viewport().set_input_as_handled()
annotate()
elif key.keycode == KEY_F9 and host.can_reset():
get_viewport().set_input_as_handled()
var removed: int = host.reset_progress()
dev_log.write("reset progress: %d files removed" % removed)
telemetry.entry("reset_progress", {"files": removed})
## The window's close button / Alt-F4 / SIGTERM reach every node in the tree.
func _notification(what: int) -> void:
if what == NOTIFICATION_WM_CLOSE_REQUEST:
telemetry.shutdown("window_close")
func _exit_tree() -> void:
telemetry.shutdown("exit")
## Freezes the game and opens the annotator over the frame as it was; the
## previous pause state comes back on close. `path` = scripted marks and save.
func annotate(path := "") -> void:
if annotator != null:
return
var was_paused := get_tree().paused
var state: Dictionary = host.debug_state()
var context := DevFeedbackContext.capture(host, get_tree(), dev_log, was_paused, state)
hint.hide()
get_tree().paused = true
var frame: Image = await DevFrame.grab(get_viewport())
annotator = DevAnnotator.new()
annotator.save_path = path
annotator.markdown_hooks = host.markdown_hooks()
_layer.add_child(annotator)
annotator.open(frame, dev_log, context, state)
annotator.picker = func(at: Vector2) -> Dictionary: return host.pick_at(at)
if path != "":
await _scripted_marks(path)
annotator.save()
await annotator.closed
annotator.remove_from_group(&"annotator") # Esc is the game's again now
annotator.queue_free()
annotator = null
hint.show()
get_tree().paused = was_paused
## The pause menu's camera: the menu goes away first, so the frame is the game.
func _annotate_from_menu() -> void:
host.close_menu()
await get_tree().process_frame
annotate()
func _scripted_shot() -> void:
await get_tree().create_timer(1.5).timeout
await annotate(_shot_path.get_basename())
var png := _shot_path.get_basename().path_join("annotated.png")
get_tree().quit(0 if FileAccess.file_exists(png) else 1)
## The marks a mouse would draw, and a frame of the overlay itself
## (<bundle>/overlay.png, toolbar visible) for a human to read, with a label
## and a select mark on the first thing the current screen lets you pick.
func _scripted_marks(dir: String) -> void:
annotator.add_shape("rect", Vector2(260, 220), Vector2(760, 640))
annotator.add_shape("arrow", Vector2(1100, 300), Vector2(820, 420))
annotator.add_shape("circle", Vector2(1150, 600), Vector2(1500, 860))
var squiggle := [Vector2(300, 800), Vector2(380, 760), Vector2(460, 820)]
annotator.add_stroke(PackedVector2Array(squiggle))
annotator.add_text(Vector2(300, 860), "wrong place?")
var target := first_pickable()
if target != Vector2.INF:
annotator.select_at(target)
var overlay: Image = await DevFrame.grab(get_viewport())
DirAccess.make_dir_recursive_absolute(dir)
overlay.save_png(dir.path_join("overlay.png"))
## The first canvas point of a coarse grid where the screen has something to
## select (Vector2.INF when it has nothing).
func first_pickable() -> Vector2:
var view := get_viewport().get_visible_rect().size
for y in PROBE_GRID.y:
for x in PROBE_GRID.x:
var at := Vector2((x + 0.5) / PROBE_GRID.x, (y + 0.5) / PROBE_GRID.y) * view
if not host.pick_at(at).is_empty():
return at
return Vector2.INF
func _log_input(event: InputEvent) -> void:
if not event.is_pressed() or event.is_echo():
return
if event is InputEventKey or event is InputEventJoypadButton or event is InputEventMouseButton:
dev_log.write("input %s" % event.as_text())

View File

@ -0,0 +1 @@
uid://dq382tvox5bfm

View File

@ -0,0 +1,49 @@
extends RefCounted
## What the game shows when F12 froze it, as the fields of one feedback record:
## the generic ones (session, build, engine, game, pause state, scene, window
## sizes, tag) plus the host's own (mode, screen, combo, pose, settings...).
## The session id and tag come from the dev log (the telemetry's session).
## No class_name (the addon's scripts reach each other with relative preload).
static var _build: Dictionary = {}
## `host` is a dev_host.gd wrapper; `state` its debug_state() (taken here when the caller has none).
static func capture(
host: RefCounted, tree: SceneTree, dev_log: RefCounted, was_paused: bool, state := {}
) -> Dictionary:
if state.is_empty():
state = host.debug_state()
var window := DisplayServer.window_get_size()
var canvas := tree.root.get_visible_rect().size
var out := {
"session": dev_log.session,
"build": build_info(),
"godot": Engine.get_version_info()["string"],
"game": host.game(),
}
out.merge(host.context(state), true)
out["paused"] = was_paused
out["scene"] = tree.current_scene.scene_file_path if tree.current_scene != null else ""
out["window"] = [window.x, window.y]
out["canvas"] = [canvas.x, canvas.y]
if dev_log.tag != "":
out["tag"] = dev_log.tag
return out
## {id: the git commit of a source run ("export" in a build), version, debug}.
static func build_info() -> Dictionary:
if _build.is_empty():
var output: Array = []
var id := "export"
var root := ProjectSettings.globalize_path("res://")
if not OS.has_feature("template") and root != "":
if OS.execute("git", ["-C", root, "rev-parse", "--short", "HEAD"], output) == 0:
id = str(output[0]).strip_edges()
_build = {
"id": id,
"version": str(ProjectSettings.get_setting("application/config/version", "")),
"debug": OS.is_debug_build(),
}
return _build

View File

@ -0,0 +1 @@
uid://c864os77cmq75

View File

@ -0,0 +1,103 @@
extends RefCounted
## One saved feedback as Markdown: a ready-to-run prompt for a later Claude
## session. Entries go to <feedback dir>/feedback-<date>.md (kuhy's
## ~/data/<game>_binaries/feedback, never a TODO file in the repo). The inbox
## (utils feedback_inbox) reads the file paths and, by default, the `Game ..., combo ...`
## line: a host may replace that line and the selected-object line with the
## `summary_line` and `entity_line` callables (record / entity -> String).
## No class_name (the addon's scripts reach each other with relative preload).
const TITLE_CHARS := 60
## Appends the entry for `record` (as returned by FeedbackSaver.save) to the
## day's file in `root`; returns that file's path.
static func append(root: String, record: Dictionary, hooks := {}) -> String:
DirAccess.make_dir_recursive_absolute(root)
var path := root.path_join("feedback-%s.md" % Time.get_date_string_from_system())
var mode := FileAccess.READ_WRITE if FileAccess.file_exists(path) else FileAccess.WRITE
var file := FileAccess.open(path, mode)
if file == null:
push_warning("feedback: cannot open %s" % path)
return ""
file.seek_end()
file.store_string(("\n" if file.get_position() > 0 else "") + markdown(record, hooks))
file.close()
return path
static func markdown(record: Dictionary, hooks := {}) -> String:
var note: String = str(record.get("note", "")).strip_edges()
var title := note.get_slice("\n", 0).left(TITLE_CHARS)
var out: Array[String] = ["## %s: %s" % [record.get("time", "?"), title], ""]
out.append(note if note != "" else "(no note)")
out.append("")
out.append_array(_facts(record, hooks))
out.append("")
out.append(_task(record))
return "\n".join(out) + "\n"
static func _facts(record: Dictionary, hooks: Dictionary) -> Array[String]:
var files: Dictionary = record.get("files", {})
var facts: Array[String] = []
var annotated: String = files.get("annotated", "-")
var raw: String = files.get("screenshot", "-")
facts.append("- Screenshot (red marks are kuhy's): `%s` (raw: `%s`)" % [annotated, raw])
facts.append("- Report: `%s` (marks in screenshot pixels)" % files.get("report", "-"))
facts.append(
(
"- Game state: `%s`; log tail: `%s`"
% [files.get("snapshot", "-"), files.get("game_log", "-")]
)
)
facts.append(
_call(
hooks,
"summary_line",
record,
"- Game `%s`, combo `%s`, build %s, session `%s`" % _where(record)
)
)
for entity: Dictionary in record.get("selected", []):
facts.append(
_call(hooks, "entity_line", entity, "- Selected %s `%s` (%s) at %s" % _entity(entity))
)
for shape: Dictionary in record.get("shapes", []):
if shape["tool"] == "text":
facts.append('- Label at %s: "%s"' % [shape["a"], shape["text"]])
return facts
## The host's line when it gave a hook for `name`, else `fallback`.
static func _call(hooks: Dictionary, name: String, arg: Dictionary, fallback: String) -> String:
var hook: Callable = hooks.get(name, Callable())
return str(hook.call(arg)) if hook.is_valid() else fallback
static func _where(record: Dictionary) -> Array:
var build: Dictionary = record.get("build", {})
return [
record.get("game", "-"),
record.get("combo", ""),
build.get("id", "?"),
record.get("session", "")
]
static func _entity(entity: Dictionary) -> Array:
return [
entity.get("kind", "?"),
entity.get("id", "?"),
entity.get("state", "-"),
entity.get("position", entity.get("at", [])),
]
static func _task(record: Dictionary) -> String:
var count := (record.get("shapes", []) as Array).size()
return (
"Task: Read the annotated screenshot (%d marks), match the marks and selected" % count
+ " objects to `snapshot.json` and the code, and find what is wrong. Write a red"
+ " test first, fix it, and show kuhy before and after."
)

View File

@ -0,0 +1 @@
uid://bk46jtnty2he3

View File

@ -0,0 +1,90 @@
extends RefCounted
## Writes one feedback as a bundle FOLDER:
## screenshot.png the frozen frame as it was
## annotated.png the same frame with the red marks burned in
## report.json the record (marks in annotated.png pixels, note, game,
## variant, player pose, settings, build, session id, files)
## game.log the tail of the run's dev.log
## snapshot.json the play state (every item and slot, judged)
## `dir` is injected, so tests use a temp dir and never the real feedback
## folder (R11). No class_name (dev files reach each other with preload).
## A file name base (local time, `YYYY-MM-DDTHH-MM-SS-mmm`) for the unix time
## `unix_time` (seconds, fractional); a negative value means now.
static func stamp(unix_time: float = -1.0) -> String:
return _stamp_ms(_unix_ms(unix_time))
## A bundle folder under `root` that does not exist yet. A clash moves to the
## next free millisecond, so the name keeps the form feedback_inbox accepts.
static func bundle_dir(root: String, unix_time: float = -1.0) -> String:
var total_ms := _unix_ms(unix_time)
var dir := root.path_join(_stamp_ms(total_ms))
while DirAccess.dir_exists_absolute(dir):
total_ms += 1
dir = root.path_join(_stamp_ms(total_ms))
return dir
static func _unix_ms(unix_time: float) -> int:
if unix_time < 0.0:
unix_time = Time.get_unix_time_from_system()
return int(floor(unix_time * 1000.0))
static func _stamp_ms(total_ms: int) -> String:
var local_secs := total_ms / 1000 + int(Time.get_time_zone_from_system()["bias"]) * 60
var text := Time.get_datetime_string_from_unix_time(local_secs).replace(":", "-")
return "%s-%03d" % [text, total_ms % 1000]
## Writes the bundle into `dir` (either image may be null). Returns the record
## with its `files` (absolute paths of what was written) filled in.
static func save(
dir: String,
record: Dictionary,
annotated: Image,
raw: Image,
game_log: String,
snapshot: Dictionary
) -> Dictionary:
DirAccess.make_dir_recursive_absolute(dir)
var files := {}
if annotated != null and annotated.save_png(dir.path_join("annotated.png")) == OK:
files["annotated"] = dir.path_join("annotated.png")
record["image"] = [annotated.get_width(), annotated.get_height()]
if raw != null and raw.save_png(dir.path_join("screenshot.png")) == OK:
files["screenshot"] = dir.path_join("screenshot.png")
if _write(dir.path_join("game.log"), game_log):
files["game_log"] = dir.path_join("game.log")
if _write(dir.path_join("snapshot.json"), JSON.stringify(snapshot, "\t")):
files["snapshot"] = dir.path_join("snapshot.json")
files["report"] = dir.path_join("report.json")
record["files"] = files
if not _write(files["report"], JSON.stringify(record, "\t")):
push_warning("feedback: cannot write %s" % files["report"])
files.erase("report")
return record
## The feedback.jsonl line of one saved bundle (the recorder stamps it on the
## video as an "annotation" moment).
static func log_entry(dir: String, record: Dictionary, marks: int) -> Dictionary:
var files: Dictionary = record.get("files", {})
return {
"event": "annotation",
"bundle": dir,
"image": files.get("annotated", ""),
"report": files.get("report", ""),
"marks": marks,
}
static func _write(path: String, text: String) -> bool:
var file := FileAccess.open(path, FileAccess.WRITE)
if file == null:
return false
file.store_string(text)
file.close()
return true

View File

@ -0,0 +1 @@
uid://b85x0cq4e46ua

View File

@ -0,0 +1,48 @@
extends Texture2D
## A vector glyph that any Texture2D slot can show (TextureRect, Button.icon,
## draw_texture_rect): it draws the vector shapes at the size asked for, so it
## never blurs when the screen is bigger than the layout.
## No class_name (the addon's scripts reach each other with relative preload).
const DevVectorGlyph = preload("vector_glyph.gd")
var glyph: DevVectorGlyph
## Natural size in pixels (what a theme slot lays out with).
var px: int = int(DevVectorGlyph.UNITS)
## Colour baked in for slots that cannot tint; white = tint on draw.
var tint: Color = Color.WHITE
static func of(p_glyph: DevVectorGlyph, p_px := int(DevVectorGlyph.UNITS)) -> Texture2D:
var tex := new()
tex.glyph = p_glyph
tex.px = p_px
return tex
func _get_width() -> int:
return px
func _get_height() -> int:
return px
func _has_alpha() -> bool:
return true
func _draw(to_canvas_item: RID, pos: Vector2, modulate: Color, _transpose: bool) -> void:
glyph.draw_rid(to_canvas_item, Rect2(pos, Vector2.ONE * px), modulate * tint)
func _draw_rect(
to_canvas_item: RID, rect: Rect2, _tile: bool, modulate: Color, _transpose: bool
) -> void:
glyph.draw_rid(to_canvas_item, rect, modulate * tint)
func _draw_rect_region(
to_canvas_item: RID, rect: Rect2, _src: Rect2, modulate: Color, _transpose: bool, _clip_uv: bool
) -> void:
glyph.draw_rid(to_canvas_item, rect, modulate * tint)

View File

@ -0,0 +1 @@
uid://cto1t7osy5akw

View File

@ -0,0 +1,63 @@
extends RefCounted
## The session's structured log: one JSON line per moment in
## <feedback dir>/feedback.jsonl. The addon writes the session start and end,
## the exact clock pair a recorder syncs on, and every engine error; the game
## adds its own moments (screens, buys, orders, outcomes...) through `entry`,
## from its host's attach_telemetry (dev_host.gd).
## No class_name (the addon's scripts reach each other with relative preload).
const DevLogger = preload("dev_logger.gd")
const SESSION_ARG := "--session-id="
var dev_log: RefCounted
var logger: Logger
var session_id := ""
var _start_ms := 0
var _done := false
## Starts the run: lets the host connect its moments, writes session_start +
## recording_sync and begins listening for engine errors.
func attach(p_log: RefCounted, host: RefCounted) -> void:
dev_log = p_log
var args := OS.get_cmdline_user_args()
session_id = dev_log.arg_value(args, SESSION_ARG)
if session_id == "":
session_id = "%d-%04x" % [Time.get_unix_time_from_system(), randi() & 0xffff]
dev_log.session = session_id
_start_ms = Time.get_ticks_msec()
logger = DevLogger.new()
OS.add_logger(logger)
host.attach_telemetry(self)
entry("session_start", {"args": Array(args), "godot": Engine.get_version_info()["string"]})
# One exact (unix time, ms) pair: an external recorder places every entry on
# its timeline with it.
entry("recording_sync", {"unix_us": int(Time.get_unix_time_from_system() * 1_000_000.0)})
## Once per frame: engine errors caught since the last frame become entries.
func tick() -> void:
if logger == null:
return
for error: Dictionary in logger.drain():
entry("engine_error", error)
## Ends the session once (window close, quit, tree exit).
func shutdown(reason: String) -> void:
if _done or dev_log == null:
return
_done = true
tick()
var elapsed := (Time.get_ticks_msec() - _start_ms) / 1000.0
entry("session_end", {"reason": reason, "elapsed_s": snappedf(elapsed, 0.001)})
OS.remove_logger(logger)
logger = null
## One moment of the run: `event` names it, `fields` is its data.
func entry(event: String, fields: Dictionary) -> void:
var row := fields.duplicate(true)
row["event"] = event
dev_log.entry(row)

View File

@ -0,0 +1 @@
uid://o0co2s5kf7ck

View File

@ -0,0 +1,200 @@
extends RefCounted
## A vector icon: shapes recorded in a 128-unit square (rect, polygon, line,
## frame, ring; `erase` punches a shape out of what is there), resolved once into
## simple, hole-free, non-overlapping polygons. They are drawn at any size
## (CanvasItem or a Texture2D, see glyph_texture.gd), so an icon is as sharp at
## 3840x2160 as at 1280x800. White-on-nothing: tint on draw. No class_name (the
## addon's scripts reach each other with relative preload).
const UNITS := 128.0
const CIRCLE_SEGMENTS := 96
const REACH := 4096.0
## Hole-free pieces in glyph units; they never overlap (an alpha tint stays even).
var pieces: Array[PackedVector2Array] = []
var _points := PackedVector2Array()
var _indices := PackedInt32Array()
## Fills a polygon; erase=true punches it out of what is already there.
func polygon(points: PackedVector2Array, erase := false) -> void:
var shape := _upright(points)
_subtract(shape)
if not erase:
pieces.append(shape)
_points = PackedVector2Array()
func rect(x: float, y: float, w: float, h: float, erase := false) -> void:
polygon(
PackedVector2Array(
[Vector2(x, y), Vector2(x + w, y), Vector2(x + w, y + h), Vector2(x, y + h)]
),
erase
)
## Thick segment between two points (flat ends).
func line(a: Vector2, b: Vector2, width: float, erase := false) -> void:
var n := (b - a).normalized().orthogonal() * width / 2.0
polygon(PackedVector2Array([a + n, b + n, b - n, a - n]), erase)
## Outline of a rectangle, `t` thick.
func frame(x: float, y: float, w: float, h: float, t: float) -> void:
rect(x, y, w, h)
rect(x + t, y + t, w - 2.0 * t, h - 2.0 * t, true)
## Disc or ring (inner > 0); with erase=true it removes that disc or ring.
func ring(center: Vector2, outer: float, inner := 0.0, erase := false) -> void:
var disc := _circle(center, outer)
if inner <= 0.0:
polygon(disc, erase)
return
var hole := _circle(center, inner)
if erase:
var kept := _intersect_all(hole)
_subtract(disc)
pieces.append_array(kept)
else:
_subtract(disc)
pieces.append_array(_difference(disc, hole))
_points = PackedVector2Array()
func area() -> float:
var total := 0.0
for piece in pieces:
total += piece_area(piece)
return total
func piece_area(piece: PackedVector2Array) -> float:
var sum := 0.0
for i in piece.size():
sum += piece[i].cross(piece[(i + 1) % piece.size()])
return absf(sum) / 2.0
## Draws the glyph into `box` of `canvas` (call from its _draw), tinted.
func draw(canvas: CanvasItem, box: Rect2, tint: Color) -> void:
draw_rid(canvas.get_canvas_item(), box, tint)
## Same, onto a canvas item RID (what a Texture2D is handed to draw on).
func draw_rid(item: RID, box: Rect2, tint: Color) -> void:
_triangulate()
var xform := Transform2D(
Vector2(box.size.x / UNITS, 0), Vector2(0, box.size.y / UNITS), box.position
)
RenderingServer.canvas_item_add_set_transform(item, xform)
RenderingServer.canvas_item_add_triangle_array(
item, _indices, _points, PackedColorArray([tint])
)
RenderingServer.canvas_item_add_set_transform(item, Transform2D.IDENTITY)
func _triangulate() -> void:
if not _points.is_empty():
return
_indices = PackedInt32Array()
for piece in pieces:
var base := _points.size()
_points.append_array(piece)
for index in Geometry2D.triangulate_polygon(piece):
_indices.append(base + index)
## Removes `cutter` from every piece, splitting a piece wherever the cutter
## would leave a hole in it.
func _subtract(cutter: PackedVector2Array) -> void:
var next: Array[PackedVector2Array] = []
for piece in pieces:
next.append_array(_difference(piece, cutter))
pieces = next
## piece minus cutter, as hole-free polygons.
func _difference(
piece: PackedVector2Array, cutter: PackedVector2Array, depth := 0
) -> Array[PackedVector2Array]:
var out: Array[PackedVector2Array] = []
var result := Geometry2D.clip_polygons(piece, cutter)
if not _has_hole(result) or depth > 4:
for part in result:
if depth > 4 and Geometry2D.is_polygon_clockwise(part) != _outer_clockwise(result):
continue
out.append(_upright(part))
return out
# The cutter sits inside the piece: cut the piece along a line through the
# cutter first, so the cutter only ever notches an edge.
var y := _bounds(cutter).get_center().y
for half in [
Rect2(-REACH, -REACH, 2.0 * REACH, REACH + y), Rect2(-REACH, y, 2.0 * REACH, REACH)
]:
for part in Geometry2D.intersect_polygons(piece, _rect_points(half)):
out.append_array(_difference(_upright(part), cutter, depth + 1))
return out
func _intersect_all(shape: PackedVector2Array) -> Array[PackedVector2Array]:
var out: Array[PackedVector2Array] = []
for piece in pieces:
for part in Geometry2D.intersect_polygons(piece, shape):
out.append(_upright(part))
return out
func _has_hole(polygons: Array[PackedVector2Array]) -> bool:
if polygons.size() < 2:
return false
var outer := _outer_clockwise(polygons)
for part in polygons:
if Geometry2D.is_polygon_clockwise(part) != outer:
return true
return false
## Winding of the biggest polygon (an outline; holes wind the other way).
func _outer_clockwise(polygons: Array[PackedVector2Array]) -> bool:
var biggest := polygons[0]
for part in polygons:
if piece_area(part) > piece_area(biggest):
biggest = part
return Geometry2D.is_polygon_clockwise(biggest)
## The same polygon wound one fixed way.
func _upright(points: PackedVector2Array) -> PackedVector2Array:
if not Geometry2D.is_polygon_clockwise(points):
return points
var flipped := points.duplicate()
flipped.reverse()
return flipped
func _circle(center: Vector2, radius: float) -> PackedVector2Array:
var points := PackedVector2Array()
for i in CIRCLE_SEGMENTS:
points.append(center + Vector2.from_angle(TAU * i / CIRCLE_SEGMENTS) * radius)
return points
func _bounds(points: PackedVector2Array) -> Rect2:
var box := Rect2(points[0], Vector2.ZERO)
for p in points:
box = box.expand(p)
return box
func _rect_points(box: Rect2) -> PackedVector2Array:
return PackedVector2Array(
[
box.position,
Vector2(box.end.x, box.position.y),
box.end,
Vector2(box.position.x, box.end.y)
]
)

View File

@ -0,0 +1 @@
uid://by2hb3qdikqcb

31
godot_dev_tools/lint.sh Executable file
View File

@ -0,0 +1,31 @@
#!/bin/bash
# ============================================================================
# Lint of the dev_tools addon and its tests: gdlint (.gdlintrc, every check on)
# and gdformat --check. gdtoolkit is pinned in requirements-dev.txt
# (pip install -r godot_dev_tools/requirements-dev.txt, or uv tool install).
# ============================================================================
set -euo pipefail
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly HERE
main() {
local tool files=()
for tool in gdlint gdformat; do
command -v "$tool" >/dev/null || {
echo "Error: $tool not found (pip install -r $HERE/requirements-dev.txt)" >&2
exit 1
}
done
mapfile -t files < <(find "$HERE/addons/dev_tools" "$HERE/tests" -name '*.gd' -type f | sort)
(cd "$HERE" && printf '%s\0' "${files[@]}" | xargs -0 -n 12 -P 4 gdlint >/dev/null)
printf '%s\0' "${files[@]}" | xargs -0 -n 12 -P 4 gdformat --check >/dev/null 2>&1 || {
gdformat --check "${files[@]}" 2>&1 | grep -v 'left unchanged' >&2 || true
exit 1
}
echo "godot_dev_tools lint: ${#files[@]} files ok"
}
main "$@"

View File

@ -0,0 +1,19 @@
; The stub host project of the dev_tools addon: it exists only so GUT can load
; addons/dev_tools headless. A game mounts the addon folder, not this project.
config_version=5
[application]
config/name="dev_tools_test_host"
config/features=PackedStringArray("4.7", "GL Compatibility")
[display]
window/size/viewport_width=640
window/size/viewport_height=360
[rendering]
renderer/rendering_method="gl_compatibility"
renderer/rendering_method.mobile="gl_compatibility"

View File

@ -0,0 +1 @@
gdtoolkit==4.5.0

98
godot_dev_tools/test.sh Executable file
View File

@ -0,0 +1,98 @@
#!/bin/bash
# ============================================================================
# GUT tests of the dev_tools addon against the stub host project in this
# folder, headless and muted, one run under 60 s.
# godot_dev_tools/test.sh the whole suite
# godot_dev_tools/test.sh -gselect=test_annotator one file
# GUT is fetched at the pinned tag into addons/gut (gitignored): no third-party
# code is committed. user:// and the feedback dir point at a throwaway folder,
# so no test ever writes where a real game saves.
# Fail closed: green only with exit 0, no SCRIPT ERROR, no failing test, at
# least one test and tests == passing + pending. Prints one summary line.
# ============================================================================
set -euo pipefail
readonly GUT_TAG="v9.7.1"
readonly RUN_TIMEOUT=50
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly HERE
TMP=""
cleanup() {
[[ -z "$TMP" ]] || rm -rf "$TMP"
}
# Fetches GUT at GUT_TAG into addons/gut unless that version is already there.
ensure_gut() {
local gut_dir="$HERE/addons/gut" tmp
if [[ -f "$gut_dir/plugin.cfg" ]] && grep -q "\"${GUT_TAG#v}\"" "$gut_dir/plugin.cfg"; then
return
fi
tmp="$(mktemp -d)"
git -c advice.detachedHead=false clone -q --depth 1 --branch "$GUT_TAG" \
https://github.com/bitwes/Gut "$tmp/gut"
rm -rf "$gut_dir"
mv "$tmp/gut/addons/gut" "$gut_dir"
rm -rf "$tmp"
}
# Value of a GUT totals row ("Tests 59", "Passing Tests 59"...), 0 when absent.
total_of() {
local row="$1" out="$2"
awk -v row="$row" 'index($0, row) == 1 { v = $NF } END { print v + 0 }' <<<"$out"
}
# Runs godot under the resource cap kuhy's machine has, else plainly.
run_capped() {
local capped="$HOME/.claude/scripts/capped.sh"
if [[ -x "$capped" ]]; then
"$capped" "$@"
else
"$@"
fi
}
main() {
command -v godot >/dev/null || {
echo "Error: godot 4.7.2 not on PATH" >&2
exit 1
}
ensure_gut
TMP="$(mktemp -d)"
trap cleanup EXIT
export XDG_DATA_HOME="$TMP/xdg"
export DEV_FEEDBACK_DIR="$TMP/feedback"
mkdir -p "$XDG_DATA_HOME" "$DEV_FEEDBACK_DIR"
# GUT's own class_names need a class cache before a script run.
run_capped timeout 40 godot --headless --path "$HERE" --import >/dev/null 2>&1 || true
local out code=0 start="$SECONDS"
out="$(run_capped timeout -k 3 "$RUN_TIMEOUT" godot --headless --audio-driver Dummy \
--path "$HERE" -s addons/gut/gut_cmdln.gd -gexit "$@" 2>&1)" || code=$?
local tests passing failing pending why=""
tests="$(total_of Tests "$out")"
passing="$(total_of "Passing Tests" "$out")"
failing="$(total_of "Failing Tests" "$out")"
pending="$(total_of "Risky/Pending" "$out")"
if [[ "$code" -eq 124 || "$code" -eq 137 || "$code" -eq 143 ]]; then
why="timed out or killed after ${RUN_TIMEOUT}s (exit $code)"
elif grep -qE 'SCRIPT ERROR|Failing Tests' <<<"$out" || ((failing > 0)); then
why="failing tests or a script error"
elif ((code != 0)); then
why="exit code $code"
elif ((tests == 0)); then
why="no tests ran"
elif ((tests != passing + pending)); then
why="tests $tests != passing $passing + pending $pending"
fi
local line="$tests tests, $passing pass, $failing fail, $pending pending, $((SECONDS - start))s"
if [[ -n "$why" ]]; then
echo "$out" | tail -60 >&2
echo "godot_dev_tools: FAILED ($why; $line)" >&2
exit 1
fi
echo "godot_dev_tools: green ($line)"
}
main "$@"

View File

@ -0,0 +1,48 @@
extends RefCounted
## A minimal host for the dev_tools addon: what a game would hand in, with a
## fixed answer for everything, and a record of what the addon asked of it.
## No class_name (tests load it by path).
var game := "stub-game"
var feedback_env := "STUB_FEEDBACK_DIR"
var colors := {"mark": Color(0.0, 1.0, 0.0)}
var menu: Array = []
var menu_closed := 0
var resets := 0
var telemetry: RefCounted = null
func debug_state() -> Dictionary:
return {"screen": "hub", "items": [{"id": "thing"}]}
func pick_at(at: Vector2) -> Dictionary:
if at.x < 100.0:
return {"kind": "stub", "id": "thing", "state": "idle", "position": [at.x, at.y]}
return {}
func context(state: Dictionary) -> Dictionary:
return {"screen": state["screen"], "mode": "stub", "variant": {"seed": 7}}
func reset_progress() -> int:
resets += 1
return 3
func add_menu_entry(id: String, icon: Texture2D, spoken: String, on_press: Callable) -> void:
menu.append({"id": id, "icon": icon, "spoken": spoken, "press": on_press})
func close_menu() -> void:
menu_closed += 1
func attach_telemetry(p_telemetry: RefCounted) -> void:
telemetry = p_telemetry
telemetry.entry("host_attached", {"game": game})
func summary_line(record: Dictionary) -> String:
return "- Stub screen `%s`" % record.get("screen", "-")

View File

@ -0,0 +1 @@
uid://bkm3tholykmke

View File

@ -0,0 +1,177 @@
extends GutTest
## The annotator: red rectangles, arrows, circles and pen strokes, undo, the
## note, and the PNG + JSON it saves. Everything writes into a temp dir.
const Annotator = preload("res://addons/dev_tools/annotator.gd")
const DevHost = preload("res://addons/dev_tools/dev_host.gd")
const DevLog = preload("res://addons/dev_tools/dev_log.gd")
const FeedbackContext = preload("res://addons/dev_tools/feedback_context.gd")
const Glyph = preload("res://addons/dev_tools/dev_glyphs.gd")
const Hint = preload("res://addons/dev_tools/dev_hint.gd")
const StubHost = preload("res://tests/stub_host.gd")
const TmpDir = preload("res://tests/tmp_dir.gd")
var log: RefCounted
var annotator: Control
var _temp := TmpDir.path("annotator")
func before_each() -> void:
log = DevLog.new()
log.dir = _temp.path_join("fb")
log.session = "test-session-1"
annotator = Annotator.new()
add_child_autofree(annotator)
var frame := Image.create(400, 200, false, Image.FORMAT_RGBA8)
frame.fill(Color(0.2, 0.3, 0.4))
var host := DevHost.new(StubHost.new())
annotator.open(frame, log, FeedbackContext.capture(host, get_tree(), log, false))
annotator.size = Vector2(200, 100) # after open: a bare Node parent gives no layout
func after_each() -> void:
TmpDir.remove_tree(_temp)
func _v(pair: Array) -> Vector2:
return Vector2(pair[0], pair[1])
func _mouse(pressed: bool, at: Vector2) -> InputEventMouseButton:
var event := InputEventMouseButton.new()
event.button_index = MOUSE_BUTTON_LEFT
event.pressed = pressed
event.position = at
return event
func _motion(at: Vector2) -> InputEventMouseMotion:
var event := InputEventMouseMotion.new()
event.position = at
return event
func test_a_rect_and_an_arrow_are_shapes_with_their_tool() -> void:
assert_true(annotator.add_shape("rect", Vector2(10, 10), Vector2(80, 60)))
assert_true(annotator.add_shape("arrow", Vector2(100, 20), Vector2(150, 70)))
assert_eq(annotator.shapes.size(), 2)
assert_eq(annotator.shapes[0]["tool"], "rect")
assert_eq(annotator.shapes[1]["tool"], "arrow")
assert_eq(annotator.shapes[1]["b"], Vector2(150, 70), "an arrow points at b")
func test_a_too_short_drag_adds_nothing() -> void:
assert_false(annotator.add_shape("rect", Vector2(10, 10), Vector2(11, 11)))
assert_false(annotator.add_stroke(PackedVector2Array([Vector2(5, 5)])))
assert_true(annotator.shapes.is_empty())
func test_a_mouse_drag_draws_the_shape_of_the_tool() -> void:
annotator.set_tool("arrow")
annotator._gui_input(_mouse(true, Vector2(10, 10)))
annotator._gui_input(_motion(Vector2(60, 40)))
annotator._gui_input(_mouse(false, Vector2(120, 80)))
assert_eq(annotator.shapes.size(), 1)
assert_eq(annotator.shapes[0]["tool"], "arrow")
assert_eq(annotator.shapes[0]["b"], Vector2(120, 80))
func test_a_pen_stroke_follows_the_mouse() -> void:
annotator.set_tool("pen")
annotator._gui_input(_mouse(true, Vector2(10, 10)))
for x in range(20, 100, 10):
annotator._gui_input(_motion(Vector2(x, 10 + x / 2.0)))
annotator._gui_input(_mouse(false, Vector2(100, 60)))
assert_eq(annotator.shapes.size(), 1)
assert_gt((annotator.shapes[0]["points"] as PackedVector2Array).size(), 5)
func test_tool_buttons_and_keys_pick_the_tool() -> void:
for id in ["rect", "arrow", "circle", "pen", "text", "select"]:
assert_true(annotator.tool_buttons.has(id), id)
annotator.tool_buttons["circle"].pressed.emit()
assert_eq(annotator.drawing_tool, "circle")
var key := InputEventKey.new()
key.keycode = KEY_P
key.pressed = true
annotator._unhandled_key_input(key)
assert_eq(annotator.drawing_tool, "pen")
func test_every_icon_only_control_has_an_accessibility_name() -> void:
for id: String in annotator.tool_buttons:
assert_ne(annotator.tool_buttons[id].accessibility_name, "", id)
for id: String in annotator.action_buttons:
assert_ne(annotator.action_buttons[id].accessibility_name, "", id)
var hint := Hint.new()
add_child_autofree(hint)
assert_ne(hint.accessibility_name, "")
func test_undo_removes_the_last_shape_and_is_safe_when_empty() -> void:
annotator.undo()
annotator.add_shape("rect", Vector2(10, 10), Vector2(80, 60))
annotator.add_shape("circle", Vector2(20, 20), Vector2(90, 70))
annotator.undo()
assert_eq(annotator.shapes.size(), 1)
assert_eq(annotator.shapes[0]["tool"], "rect")
func test_saving_writes_the_bundle_with_every_field() -> void:
annotator.add_shape("rect", Vector2(10, 10), Vector2(80, 60))
annotator.add_shape("arrow", Vector2(100, 20), Vector2(150, 70))
annotator.note.text = "the frame is crooked"
var base := _temp.path_join("fb/one")
annotator.save_path = base
annotator.write(Image.create(400, 200, false, Image.FORMAT_RGBA8))
for file_name in ["annotated.png", "screenshot.png", "report.json"]:
assert_true(FileAccess.file_exists(base.path_join(file_name)), file_name)
var saved: Dictionary = JSON.parse_string(
FileAccess.get_file_as_string(base.path_join("report.json"))
)
for field in ["session", "build", "godot", "game", "mode", "window", "canvas"]:
assert_true(saved.has(field), field)
assert_eq(saved["session"], "test-session-1")
assert_eq(saved["game"], "stub-game")
assert_eq(saved["mode"], "stub", "the host's own fields are in the report")
assert_eq(saved["note"], "the frame is crooked")
assert_eq(_v(saved["image"]), Vector2(400, 200))
assert_eq(saved["files"]["annotated"], base.path_join("annotated.png"))
assert_eq(saved["shapes"].size(), 2)
assert_eq(_v(saved["shapes"][0]["a"]), Vector2(20, 20))
assert_eq(_v(saved["shapes"][0]["b"]), Vector2(160, 120))
assert_eq(_v(saved["shapes"][1]["b"]), Vector2(300, 140), "shapes are in the PNG's pixels")
var entry := FileAccess.get_file_as_string(log.dir.path_join("feedback.jsonl"))
assert_true(entry.contains("one/report.json"))
func test_the_default_save_goes_under_the_injected_dir() -> void:
watch_signals(annotator)
annotator.write(Image.create(400, 200, false, Image.FORMAT_RGBA8))
assert_signal_emitted(annotator, "closed")
assert_eq(DirAccess.get_directories_at(log.dir).size(), 1, "one bundle folder")
func test_the_hint_glyph_emits_pressed_on_a_click() -> void:
var hint := Hint.new()
add_child_autofree(hint)
watch_signals(hint)
hint._gui_input(_mouse(true, Vector2(5, 5)))
assert_signal_emitted(hint, "pressed")
func test_the_hint_sits_inside_the_top_right_corner() -> void:
var layer := CanvasLayer.new()
add_child_autofree(layer)
var hint := Hint.new()
layer.add_child(hint)
var view := get_tree().root.get_visible_rect().size
assert_almost_eq(hint.position.x + hint.size.x, view.x - Hint.MARGIN_PX, 0.5)
assert_almost_eq(hint.position.y, float(Hint.MARGIN_PX), 0.5)
func test_every_dev_glyph_draws_something() -> void:
var kinds := "rect arrow circle pen undo save cancel note camera text select clear"
for kind in kinds.split(" "):
assert_gt(Glyph.texture(kind).glyph.pieces.size(), 0, kind)
assert_gt(Glyph.texture(kind).glyph.area(), 100.0, kind)

View File

@ -0,0 +1 @@
uid://yc2260o50sag

View File

@ -0,0 +1,249 @@
extends GutTest
## The annotator's second half: text labels, entity select, clear + undo, the
## unsaved-changes guard, and the bundle folder with its Markdown entry (the
## on-disk contract utils feedback_inbox reads).
const Annotator = preload("res://addons/dev_tools/annotator.gd")
const DevHost = preload("res://addons/dev_tools/dev_host.gd")
const DevLog = preload("res://addons/dev_tools/dev_log.gd")
const FeedbackContext = preload("res://addons/dev_tools/feedback_context.gd")
const StubHost = preload("res://tests/stub_host.gd")
const TmpDir = preload("res://tests/tmp_dir.gd")
const FILES := ["screenshot.png", "annotated.png", "report.json", "game.log", "snapshot.json"]
## Every top-level field of report.json: the generic ones plus the stub host's.
const REPORT_FIELDS := (
"kind time note session build godot game screen mode variant"
+ " paused scene window canvas shapes selected image files"
)
const ITEM := {
"kind": "entity",
"id": "entity_3",
"team": "army",
"count": 10,
"state": "move",
"position": [120.0, 80.5],
}
var log: RefCounted
var annotator: Control
var _host := DevHost.new(StubHost.new())
var _temp := TmpDir.path("annotator_bundle")
func before_each() -> void:
log = DevLog.new()
log.dir = _temp.path_join("fb")
log.session = "test-session-2"
annotator = Annotator.new()
add_child_autofree(annotator)
var frame := Image.create(400, 200, false, Image.FORMAT_RGBA8)
frame.fill(Color(0.2, 0.3, 0.4))
var context := FeedbackContext.capture(_host, get_tree(), log, false)
annotator.open(frame, log, context, {"items": []})
annotator.size = Vector2(200, 100)
annotator.picker = func(_at: Vector2) -> Dictionary: return ITEM.duplicate()
func after_each() -> void:
TmpDir.remove_tree(_temp)
func _click(at: Vector2) -> void:
for pressed in [true, false]:
var event := InputEventMouseButton.new()
event.button_index = MOUSE_BUTTON_LEFT
event.pressed = pressed
event.position = at
annotator._gui_input(event)
func _bundles() -> Array:
return Array(DirAccess.get_directories_at(log.dir))
func _json(path: String) -> Variant:
return JSON.parse_string(FileAccess.get_file_as_string(path))
func _save() -> String:
annotator.write(Image.create(400, 200, false, Image.FORMAT_RGBA8))
var dirs := _bundles()
dirs.sort()
return log.dir.path_join(dirs[dirs.size() - 1])
func test_a_text_label_keeps_its_words_and_empty_text_makes_none() -> void:
assert_true(annotator.add_text(Vector2(20, 30), "wrong place"))
assert_false(annotator.add_text(Vector2(20, 30), " "))
assert_eq(annotator.shapes.size(), 1)
assert_eq(annotator.shapes[0]["tool"], "text")
assert_eq(annotator.shapes[0]["text"], "wrong place")
var mark: Dictionary = annotator.record()["shapes"][0]
assert_eq(mark["text"], "wrong place")
assert_eq(mark["a"], [40, 60], "in PNG pixels")
func test_the_text_tool_asks_for_the_words_where_you_click() -> void:
annotator.set_tool("text")
_click(Vector2(50, 40))
assert_true(annotator.text_field != null and annotator.text_field.visible)
assert_true(annotator.shapes.is_empty(), "nothing yet")
annotator.text_field.text = "here"
annotator.text_field.text_submitted.emit("here")
assert_eq(annotator.shapes.size(), 1)
assert_eq(annotator.shapes[0]["text"], "here")
assert_eq(annotator.shapes[0]["a"], Vector2(50, 40))
assert_false(annotator.text_field.visible)
func test_select_attaches_the_entity_under_the_cursor() -> void:
assert_true(annotator.select_at(Vector2(60, 40)))
assert_eq(annotator.shapes[0]["tool"], "select")
var record: Dictionary = annotator.record()
assert_eq(record["selected"].size(), 1)
var entity: Dictionary = record["selected"][0]
assert_eq(entity["id"], "entity_3")
assert_eq(entity["state"], "move")
assert_eq(entity["position"], [120.0, 80.5])
assert_eq(entity["at"], [120, 80], "where you clicked, in PNG pixels")
func test_select_on_nothing_makes_no_mark() -> void:
annotator.picker = func(_at: Vector2) -> Dictionary: return {}
assert_false(annotator.select_at(Vector2(60, 40)))
assert_true(annotator.shapes.is_empty())
func test_the_select_tool_picks_on_a_click() -> void:
annotator.set_tool("select")
_click(Vector2(60, 40))
assert_eq(annotator.shapes.size(), 1)
assert_eq(annotator.shapes[0]["entity"]["id"], "entity_3")
func test_clear_empties_the_marks_and_undo_brings_them_back() -> void:
annotator.add_shape("rect", Vector2(10, 10), Vector2(80, 60))
annotator.add_text(Vector2(20, 30), "x")
annotator.clear()
assert_true(annotator.shapes.is_empty())
annotator.undo()
assert_eq(annotator.shapes.size(), 2, "clear is one undo step")
annotator.undo()
assert_eq(annotator.shapes.size(), 1)
func test_clear_with_nothing_to_clear_leaves_no_undo_step() -> void:
annotator.add_shape("rect", Vector2(10, 10), Vector2(80, 60))
annotator.clear()
annotator.clear()
annotator.undo()
assert_eq(annotator.shapes.size(), 1)
func test_cancel_with_nothing_drawn_closes_at_once() -> void:
watch_signals(annotator)
annotator.cancel()
assert_signal_emitted(annotator, "closed")
func test_cancel_with_marks_asks_first_and_the_second_press_closes() -> void:
annotator.add_shape("rect", Vector2(10, 10), Vector2(80, 60))
watch_signals(annotator)
annotator.cancel()
assert_signal_not_emitted(annotator, "closed")
assert_true(annotator.cancel_pending)
annotator.cancel()
assert_signal_emitted(annotator, "closed")
func test_a_note_counts_as_unsaved_and_a_new_mark_disarms_the_ask() -> void:
annotator.note.text = "typed"
annotator.cancel()
assert_true(annotator.cancel_pending, "a note counts as unsaved work")
annotator.add_shape("rect", Vector2(10, 10), Vector2(80, 60))
assert_false(annotator.cancel_pending)
func test_save_writes_the_bundle_folder_with_every_file() -> void:
annotator.add_shape("rect", Vector2(10, 10), Vector2(80, 60))
annotator.select_at(Vector2(60, 40))
annotator.note.text = "this squad stands still"
log.write("hello-from-the-test")
var bundle := _save()
assert_eq(_bundles().size(), 1)
for file_name in FILES:
assert_true(FileAccess.file_exists(bundle.path_join(file_name)), file_name)
var game_log := FileAccess.get_file_as_string(bundle.path_join("game.log"))
assert_true(game_log.contains("hello-from-the-test"))
assert_eq(_json(bundle.path_join("snapshot.json")), {"items": []})
func test_report_json_has_the_fields_a_later_session_needs() -> void:
annotator.add_shape("rect", Vector2(10, 10), Vector2(80, 60))
annotator.select_at(Vector2(60, 40))
annotator.note.text = "n"
var report: Dictionary = _json(_save().path_join("report.json"))
for field in REPORT_FIELDS.split(" "):
assert_true(report.has(field), field)
assert_eq(report["game"], "stub-game")
assert_eq(report["kind"], "annotation")
assert_eq(report["session"], "test-session-2")
assert_eq(report["note"], "n")
assert_eq(report["image"], [400.0, 200.0])
assert_eq(report["shapes"].size(), 2)
assert_eq(report["selected"][0]["id"], "entity_3")
for field: String in ["id", "version", "debug"]:
assert_true(report["build"].has(field), "build." + field)
for file_key: String in ["annotated", "screenshot", "game_log", "snapshot", "report"]:
assert_true(FileAccess.file_exists(report["files"][file_key]), file_key)
assert_eq(String(report["files"]["annotated"]).get_file(), "annotated.png")
func test_two_saves_in_one_millisecond_get_two_folders() -> void:
annotator.write(Image.create(400, 200, false, Image.FORMAT_RGBA8))
annotator.write(Image.create(400, 200, false, Image.FORMAT_RGBA8))
assert_eq(_bundles().size(), 2)
func test_each_save_appends_a_prompt_ready_markdown_entry() -> void:
annotator.note.text = "the third card is cut off"
var bundle := _save()
annotator.note.text = "second thought"
_save()
var md_files := Array(DirAccess.get_files_at(log.dir)).filter(
func(f: String) -> bool: return f.ends_with(".md")
)
assert_eq(md_files.size(), 1, "one Markdown file per day")
assert_true(String(md_files[0]).begins_with("feedback-"))
var md := FileAccess.get_file_as_string(log.dir.path_join(md_files[0]))
assert_true(md.begins_with("## "))
assert_eq(md.count("\n## "), 1, "two entries")
assert_true(md.contains("the third card is cut off"))
assert_true(md.contains(bundle.path_join("annotated.png")))
assert_true(md.contains(bundle.path_join("report.json")))
assert_true(md.contains("Task:"), "ends with what the next session should do")
func test_the_default_entry_has_the_line_the_inbox_parses() -> void:
var md := FileAccess.get_file_as_string(_md_after_save())
var line := RegEx.create_from_string("- Game `([^`]*)`, combo `([^`]*)`")
assert_not_null(line.search(md), "feedback_inbox matches Game `..`, combo `..`")
assert_string_contains(md, "- Game `stub-game`, combo ``")
func test_host_hooks_replace_the_summary_and_the_selected_lines() -> void:
annotator.markdown_hooks = _host.markdown_hooks()
annotator.select_at(Vector2(60, 40))
var md := FileAccess.get_file_as_string(_md_after_save())
assert_string_contains(md, "- Stub screen `hub`")
assert_false(md.contains("- Game `"))
assert_string_contains(md, "- Selected entity `entity_3` (move) at [120.0, 80.5]")
func _md_after_save() -> String:
_save()
var md_files := Array(DirAccess.get_files_at(log.dir)).filter(
func(f: String) -> bool: return f.ends_with(".md")
)
return log.dir.path_join(md_files[0])

View File

@ -0,0 +1 @@
uid://bvjhtx78stju5

View File

@ -0,0 +1,61 @@
extends GutTest
## The host wrapper: a game hands in any object, the addon fills every gap with
## a default, and the colours a host names replace the defaults.
const DevHost = preload("res://addons/dev_tools/dev_host.gd")
const Style = preload("res://addons/dev_tools/dev_style.gd")
const StubHost = preload("res://tests/stub_host.gd")
class MethodsOnly:
extends RefCounted
func game() -> String:
return "from-a-method"
func feedback_env() -> String:
return "METHOD_ENV"
func after_each() -> void:
Style.apply({})
func test_a_missing_host_answers_with_defaults() -> void:
var host := DevHost.new()
assert_eq(host.game(), "game")
assert_eq(host.feedback_env(), "DEV_FEEDBACK_DIR")
assert_eq(host.colors(), {})
assert_eq(host.debug_state(), {})
assert_eq(host.pick_at(Vector2.ONE), {})
assert_eq(host.context({"a": 1}), {})
assert_false(host.can_reset())
assert_eq(host.markdown_hooks(), {})
host.close_menu()
host.add_menu_entry("x", null, "x", func() -> void: pass)
host.attach_telemetry(null)
func test_a_value_may_be_a_property_or_a_method() -> void:
assert_eq(DevHost.new(StubHost.new()).game(), "stub-game")
assert_eq(DevHost.new(StubHost.new()).feedback_env(), "STUB_FEEDBACK_DIR")
assert_eq(DevHost.new(MethodsOnly.new()).game(), "from-a-method")
assert_eq(DevHost.new(MethodsOnly.new()).feedback_env(), "METHOD_ENV")
func test_the_host_answers_what_it_has() -> void:
var host := DevHost.new(StubHost.new())
assert_true(host.can_reset())
assert_eq(host.pick_at(Vector2(5, 5))["id"], "thing")
assert_eq(host.pick_at(Vector2(500, 5)), {})
assert_eq(host.context(host.debug_state())["mode"], "stub")
assert_eq(host.markdown_hooks().keys(), ["summary_line"], "only the hooks the game has")
func test_host_colours_replace_the_defaults_and_apply_resets_them() -> void:
Style.apply({"mark": Color.BLUE, "ink": Color.RED})
assert_eq(Style.mark, Color.BLUE)
assert_eq(Style.ink, Color.RED)
assert_eq(Style.panel, Style.DEFAULT_PANEL, "a key the host leaves out keeps the default")
Style.apply({})
assert_eq(Style.mark, Style.DEFAULT_MARK)

View File

@ -0,0 +1 @@
uid://cek7couaerifq

View File

@ -0,0 +1,246 @@
extends GutTest
## The dev tools node and its parts: where the logs go, the session's structured
## log, the node joining a game through its host, F9 and F12, and the rules the
## addon keeps (no class_name, no game class, relative preload only).
const ADDON := "res://addons/dev_tools"
const DevHost = preload("res://addons/dev_tools/dev_host.gd")
const DevLog = preload("res://addons/dev_tools/dev_log.gd")
const DevTools = preload("res://addons/dev_tools/dev_tools.gd")
const Style = preload("res://addons/dev_tools/dev_style.gd")
const StubHost = preload("res://tests/stub_host.gd")
const Telemetry = preload("res://addons/dev_tools/telemetry.gd")
const TmpDir = preload("res://tests/tmp_dir.gd")
var host: RefCounted
var log: RefCounted
var _dir := TmpDir.path("dev_tools")
func before_each() -> void:
host = StubHost.new()
log = DevLog.new()
log.dir = _dir
func after_each() -> void:
get_tree().paused = false
Style.apply({})
TmpDir.remove_tree(_dir)
func _rows() -> Array:
var rows := []
for line in FileAccess.get_file_as_string(_dir.path_join("feedback.jsonl")).split("\n", false):
rows.append(JSON.parse_string(line))
return rows
func _events() -> Array:
return _rows().map(func(row: Dictionary) -> String: return row.get("event", ""))
func _tools() -> Node:
var tools: Node = DevTools.new()
tools.setup(host)
tools.dev_log.dir = _dir
add_child_autofree(tools)
return tools
## Waits for process frames (a paused tree stops GUT's own wait_until), 300 at most.
func _until(done: Callable) -> void:
for _i in 300:
if done.call():
return
await get_tree().process_frame
fail_test("never happened")
func _key(code: Key) -> InputEventKey:
var press := InputEventKey.new()
press.keycode = code
press.pressed = true
return press
func test_the_log_folder_follows_the_arguments_and_the_game() -> void:
assert_eq(DevLog.default_dir(["--feedback-dir=/x/fb", "--save-dir=/y"]), "/x/fb")
assert_eq(DevLog.default_dir(["--save-dir=/y/save"]), "/y/save/dev", "a bot logs in its save")
assert_eq(DevLog.arg_value(["--dev-tag=v03"], "--dev-tag="), "v03")
assert_eq(DevLog.arg_value([], "--dev-tag="), "")
assert_eq(
DevLog.new("g", "NO_SUCH_VAR_X").dir, "user://dev", "no env, no --dev: the user folder"
)
func test_the_env_variable_of_the_host_names_the_folder() -> void:
OS.set_environment("STUB_FEEDBACK_DIR", "/env/fb")
assert_eq(DevLog.default_dir([], "stub-game", "STUB_FEEDBACK_DIR"), "/env/fb")
assert_eq(_tools_dir(), "/env/fb", "the node asks the host for the variable name")
OS.unset_environment("STUB_FEEDBACK_DIR")
func _tools_dir() -> String:
var tools: Node = DevTools.new()
tools.setup(host)
var dir: String = tools.dev_log.dir
tools.free()
return dir
func test_log_lines_and_entries_land_in_the_injected_folder() -> void:
log.session = "s-1"
log.write("first line")
log.write("second line")
assert_eq(log.tail(1), "%s\n" % log.tail(5).strip_edges().split("\n")[1])
assert_string_contains(log.tail(5), "first line")
log.entry({"event": "probe"})
log.entry({"event": "probe"})
var rows := _rows()
assert_eq(rows.size(), 2)
assert_eq(rows[1]["seq"], 2.0)
assert_eq(rows[1]["session"], "s-1")
for field: String in ["time", "ms", "frame"]:
assert_true(rows[1].has(field), field)
func test_a_session_starts_with_the_host_moments_and_an_exact_clock_pair() -> void:
var telemetry := Telemetry.new()
telemetry.attach(log, DevHost.new(host))
assert_eq(_events(), ["host_attached", "session_start", "recording_sync"])
var sync: Dictionary = _rows()[2]
assert_almost_eq(sync["unix_us"] / 1000000.0, Time.get_unix_time_from_system(), 5.0)
assert_ne(telemetry.session_id, "")
assert_eq(sync["session"], telemetry.session_id)
telemetry.shutdown("test")
telemetry.shutdown("again")
assert_eq(_events().count("session_end"), 1, "a session ends once")
func test_engine_errors_become_entries() -> void:
var telemetry := Telemetry.new()
telemetry.attach(log, DevHost.new(host))
push_error("boom from the test")
telemetry.tick()
telemetry.shutdown("test")
assert_push_error("boom from the test")
var errors := _rows().filter(
func(row: Dictionary) -> bool: return row["event"] == "engine_error"
)
assert_eq(errors.size(), 1)
assert_string_contains(str(errors[0]), "boom from the test")
func test_the_node_joins_the_game_through_its_host() -> void:
var tools := _tools()
assert_eq(host.menu.size(), 1, "the pause menu gets a camera")
assert_eq(host.menu[0]["id"], "annotate")
assert_not_null(host.menu[0]["icon"])
assert_not_null(tools.hint)
assert_has(_events(), "session_start")
assert_has(_events(), "host_attached")
assert_eq(Style.mark, Color(0.0, 1.0, 0.0), "the host's colours restyle the tools")
assert_ne(tools.first_pickable(), Vector2.INF, "the stub has something at the left")
assert_string_contains(tools.dev_log.tail(50), "dev tools on")
func test_a_bare_host_still_works() -> void:
var tools: Node = DevTools.new()
tools.setup(null)
tools.dev_log.dir = _dir
add_child_autofree(tools)
assert_eq(tools.first_pickable(), Vector2.INF, "no pick_at: nothing to select")
tools._input(_key(KEY_F9))
assert_does_not_have(_events(), "reset_progress")
assert_eq(Style.mark, Style.DEFAULT_MARK)
func test_f9_resets_through_the_host_and_logs_it() -> void:
var tools := _tools()
tools._input(_key(KEY_F9))
assert_eq(host.resets, 1)
var rows := _rows()
var reset: Dictionary = rows[_events().find("reset_progress")]
assert_eq(reset["files"], 3.0)
func test_f12_freezes_the_game_and_the_marks_save_a_bundle() -> void:
var tools := _tools()
tools.annotate()
await _until(func() -> bool: return tools.annotator != null)
assert_true(get_tree().paused, "the frame is frozen")
assert_true(tools.annotator.is_in_group(&"annotator"))
assert_true(tools.annotator.add_shape("rect", Vector2(10, 10), Vector2(80, 60)))
tools.annotator.note.text = "from the f12 test"
tools.annotator.save()
await _until(func() -> bool: return tools.annotator == null)
assert_false(get_tree().paused, "the game runs again")
assert_eq(DirAccess.get_directories_at(_dir).size(), 1, "one bundle")
assert_eq(host.menu_closed, 0)
var report: Dictionary = JSON.parse_string(
FileAccess.get_file_as_string(
_dir.path_join(DirAccess.get_directories_at(_dir)[0]).path_join("report.json")
)
)
assert_eq(report["game"], "stub-game")
assert_eq(report["screen"], "hub")
func test_the_pause_menu_entry_closes_the_menu_first() -> void:
var tools := _tools()
host.menu[0]["press"].call()
await _until(func() -> bool: return tools.annotator != null)
assert_eq(host.menu_closed, 1)
tools.annotator.cancel()
await _until(func() -> bool: return tools.annotator == null)
func test_no_addon_file_declares_a_class_name() -> void:
for source in _sources():
assert_false(source.contains("\nclass_name "))
assert_false(source.begins_with("class_name "))
func test_the_addon_names_no_game_class_and_no_mount_path() -> void:
for source in _sources():
assert_false(source.contains('load("res://'), "scripts reach siblings by relative preload")
assert_false(source.contains("Palette"), "no game palette")
assert_false(source.contains("SaveStore"), "no game save")
func test_every_preload_alias_is_prefixed_so_no_game_class_can_shadow_it() -> void:
var alias := RegEx.create_from_string("(?m)^const (\\w+) = preload")
var seen := 0
for source in _sources():
for found in alias.search_all(source):
seen += 1
assert_true(found.get_string(1).begins_with("Dev"), found.get_string(1))
assert_gt(seen, 20)
func test_the_addon_loads_from_any_folder() -> void:
var copy := TmpDir.path("mounted_elsewhere")
for file_name in DirAccess.get_files_at(ADDON):
if file_name.ends_with(".gd"):
var text := FileAccess.get_file_as_string(ADDON.path_join(file_name))
var out := FileAccess.open(copy.path_join(file_name), FileAccess.WRITE)
out.store_string(text)
out.close()
var script := ResourceLoader.load(
copy.path_join("dev_tools.gd"), "", ResourceLoader.CACHE_MODE_IGNORE
)
assert_not_null(script, "a copy at another path still parses and preloads its siblings")
var tools: Node = script.new()
assert_not_null(tools.get("telemetry"))
tools.free()
TmpDir.remove_tree(copy)
func _sources() -> Array[String]:
var out: Array[String] = []
for file_name in DirAccess.get_files_at(ADDON):
if file_name.ends_with(".gd"):
out.append(FileAccess.get_file_as_string(ADDON.path_join(file_name)))
assert_gt(out.size(), 10)
return out

View File

@ -0,0 +1 @@
uid://djdtnm0k7ifd8

View File

@ -0,0 +1,27 @@
extends GutTest
## Bundle folder names must stay importable by utils feedback_inbox, even when
## two saves land in the same millisecond.
const FeedbackSaver = preload("res://addons/dev_tools/feedback_saver.gd")
const TmpDir = preload("res://tests/tmp_dir.gd")
## Copied from feedback_inbox/feedback_inbox/_bundle.py (_STAMP): the only
## folder names the inbox imports.
const INBOX_STAMP := "^\\d{4}-\\d{2}-\\d{2}T\\d{2}-\\d{2}-\\d{2}-\\d{3}$"
var _root := TmpDir.path("feedback_saver")
func after_each() -> void:
TmpDir.remove_tree(_root)
func test_same_millisecond_gives_two_inbox_names() -> void:
var pattern := RegEx.create_from_string(INBOX_STAMP)
var unix := 1760000000.123
var first := FeedbackSaver.bundle_dir(_root, unix)
DirAccess.make_dir_recursive_absolute(first)
var second := FeedbackSaver.bundle_dir(_root, unix)
assert_ne(first, second, "a clash must pick another folder")
assert_not_null(pattern.search(first.get_file()), first)
assert_not_null(pattern.search(second.get_file()), second)

View File

@ -0,0 +1 @@
uid://doeql0nkwvuib

View File

@ -0,0 +1,26 @@
extends RefCounted
## One throwaway folder per test run under user:// (test.sh points user:// at a
## temporary XDG_DATA_HOME, so nothing lands in a real game's saves).
## No class_name (tests load it by path).
const META := "dev_tools_test_run_dir"
## A subfolder of this run's folder, made.
static func path(name: String) -> String:
if not Engine.has_meta(META):
Engine.set_meta(META, "user://dev_tools_test_%d_%d" % [OS.get_process_id(), randi()])
var dir: String = Engine.get_meta(META).path_join(name)
DirAccess.make_dir_recursive_absolute(dir)
return dir
## Deletes `dir` with everything in it.
static func remove_tree(dir: String) -> void:
if not DirAccess.dir_exists_absolute(dir):
return
for file_name in DirAccess.get_files_at(dir):
DirAccess.remove_absolute(dir.path_join(file_name))
for sub in DirAccess.get_directories_at(dir):
remove_tree(dir.path_join(sub))
DirAccess.remove_absolute(dir)

View File

@ -0,0 +1 @@
uid://ddgx6u6ewtyul