summer-engine 2.8.2 → 3.1.0

package/assets/autopilot/README.md

@@ -2,7 +2,7 @@
 
 A starting point for proving your game actually works — not that it compiles, that it *works*.
 
-`autopilot.gd` boots your game in an invisible instance, presses your real input actions to walk the player through a list of waypoints, saves a rendered frame at each one, records what it found, and exits. It is ordinary GDScript against your real running game. There is no test framework here to learn.
+`autopilot.gd` boots your game in an invisible instance, finds the player, presses your real input actions to walk it through a list of waypoints, saves a rendered frame at each one, records what it found, and exits. It is ordinary GDScript against your real running game. There is no test framework here to learn.
 
 ## Run it
 
@@ -10,14 +10,20 @@ A starting point for proving your game actually works — not that it compiles,
 bash tests/autopilot/run.sh
 ```
 
-No editor needed. Exit code is 0 when the probe finished cleanly and the engine logged no errors.
+No editor needed. Two things happen:
+
+1. **First run only: asset import.** A never-opened checkout has no `.godot/` caches, so the engine's standard editor import runs once, headless, to build them (imported textures/fonts/audio/models, `uid_cache.bin`, `global_script_class_cache.cfg`). Without this the game boots into hundreds of `Unable to open file …ctex` / `invalid UID` / `Could not find type` errors that are not bugs in your game. Output goes to `tests/autopilot/out/import.log`; the pass is skipped once `.godot/global_script_class_cache.cfg` exists; `bash tests/autopilot/run.sh --reimport` forces it. Bounded by `IMPORT_MAX_SECONDS` (default 300).
+2. **The verify run.** The probe runs in the engine's offscreen verify instance and `run.sh` reads `results.json`.
+
+Exit code is 0 when the probe finished, every configured waypoint was reached, and the engine logged no `ERROR` / `SCRIPT ERROR`. Engine `WARNING`s are printed and counted but do not fail the run. The last line is the verdict: `PASSED: …` or `FAILED: …`.
 
 Results land in `tests/autopilot/out/`:
 
 ```
 results.json     reports, frame list, errors_seen, duration_ms, finished
-00_start.jpg     a real rendered frame, one per waypoint
-engine.log       full engine output if something went wrong
+00_start.jpg     a real rendered frame, one per step
+engine.log       full engine output of the verify run
+import.log       the asset import, when it ran
 ```
 
 An agent can also run the same probe through MCP without touching your editor:
@@ -28,9 +34,15 @@ summer_batch ops:[{"op": "RunVerification",
                    "max_seconds": 40}]
 ```
 
+## What the shipped probe does
+
+Out of the box `WAYPOINTS` is empty, so the run is a **smoke test**: boot, find the player, let the game run for a second, save two frames, pass when the engine logged no errors (`reports.smoke: true`). That already catches a project that does not boot, a main scene that fails to load, and every script that fails to parse.
+
+The player is `PLAYER_PATH` when that path exists under the current scene; otherwise the probe auto-detects it — the first `CharacterBody2D`/`3D`, then the first `RigidBody2D`/`3D`, then any `Node2D`/`Node3D` whose name contains "player" — and reports `player_found_by` and the exact `player_path` it used, so the next edit to CONFIG is a paste. A workspace scene with no player still passes the smoke test (`player_found_by: "none"`); it only fails when waypoints are configured and there is nothing to drive.
+
 ## Make it yours
 
-Open `autopilot.gd` and edit the `CONFIG` block at the top: the player's node path, your Input Map action names, and the waypoints to walk. Then put your real assertions in `_check_at_waypoint()` and `_check_at_end()` — the shipped version walks and looks, but asserts nothing about *your* game, and a test that asserts nothing always passes.
+Open `autopilot.gd` and edit the `CONFIG` block at the top: the player's node path, your Input Map action names, and the waypoints to walk (2D in pixels, 3D in metres on x/z). Then put your real assertions in `_check_at_waypoint()` and `_check_at_end()` — the shipped version boots, walks and looks, but asserts nothing about *your* game, and a test that asserts nothing always passes.
 
 Leave `ACT_UP` / `ACT_DOWN` empty for a side-on platformer. The autopilot then measures arrival on X alone, because in a side-scroller Y is gravity, not a destination.
 
@@ -44,7 +56,9 @@ Leave `ACT_UP` / `ACT_DOWN` empty for a side-on platformer. The autopilot then m
 
 **`finished: false` is a failure.** It means the probe hit `--summer-verify-max` before calling `finish()`. `run.sh` exits non-zero on it; do not read the partial reports as a pass.
 
-**Never add `--headless` to this.** Headless has no renderer: `save_frame()` gets a null image, and `draw_calls` reads 0.0 forever. The verify instance is windowed but positioned off-screen, which is why it can produce real frames and stay invisible.
+**Warnings are still worth reading.** An `invalid UID … using text path instead` warning means a scene's `uid://` does not match the resource's `.import`/`.uid` file; the load still works, and one day it will not.
+
+**Never add `--headless` to the verify run.** Headless has no renderer: `save_frame()` gets a null image, and `draw_calls` reads 0.0 forever. The verify instance is windowed but positioned off-screen, which is why it can produce real frames and stay invisible. (The import pre-pass is headless on purpose: it needs no pixels.)
 
 ## Frames are the point
 

package/assets/autopilot/autopilot.gd

@@ -1,9 +1,10 @@
-# Autopilot — drives the player through a list of waypoints, saves a frame at each,
-# asserts what it saw, and exits.
+# Autopilot — boots your game offscreen, finds the player, optionally drives it through
+# a list of waypoints, saves a frame at each step, asserts what it saw, and exits.
 #
 # This is a starting point, not a finished test. Edit CONFIG below to match your game,
-# then add your own assertions in _check_at_waypoint(). Everything here is ordinary
-# GDScript against your real running game — there is no test framework to learn.
+# then add your own assertions in _check_at_waypoint() / _check_at_end(). Everything
+# here is ordinary GDScript against your real running game — there is no test
+# framework to learn.
 #
 # Run it:
 #   bash tests/autopilot/run.sh
@@ -13,7 +14,10 @@ extends "res://tests/autopilot/probe_base.gd"
 
 # ── CONFIG — edit this ────────────────────────────────────────────────────────────
 
-# Node path to the player, from the current scene root.
+# Node path to the player, from the current scene root. If nothing is at this path the
+# probe looks for the first CharacterBody2D/3D, then the first RigidBody2D/3D, then any
+# Node2D/Node3D whose name contains "player", and reports what it picked and how in
+# reports.player_found_by / reports.player_path. Paste that path here once you know it.
 const PLAYER_PATH := "Player"
 
 # Input action names from your project's Input Map. Leave an entry empty to skip it.
@@ -25,10 +29,13 @@ const ACT_JUMP  := "jump"
 
 # Where to walk. 2D games use x/y in pixels; 3D games use x/z in metres (y ignored).
 # Positions are WORLD positions, not offsets.
-const WAYPOINTS := [
-    Vector3(300, 0, 0),
-    Vector3(600, 0, 0),
-]
+#
+# EMPTY means a smoke test: boot the game, let it run, save frames, and pass when the
+# engine logged no errors. Add waypoints once you know your level — they are what
+# turns "it boots" into "the player can get from here to there":
+#   const WAYPOINTS: Array = [Vector3(300, 0, 0), Vector3(600, 0, 0)]   # 2D, pixels
+#   const WAYPOINTS: Array = [Vector3(5, 0, 0), Vector3(5, 0, -8)]      # 3D, metres
+const WAYPOINTS: Array = []
 
 # How close counts as arrived, and how long to allow per leg before giving up.
 const ARRIVE_EPSILON := 40.0
@@ -48,17 +55,40 @@ func _ready() -> void:
     for _i in 30:
         await get_tree().physics_frame
 
-    if not _bind_player():
+    var scene := get_tree().current_scene
+    if scene == null:
+        report("error", "no current scene — is run/main_scene set in project.godot?")
         finish()
         return
 
-    report("player_path", PLAYER_PATH)
-    report("player_class", _player.get_class())
-    report("mode", "3D" if _is_3d else "2D")
-    report("start_pos", str(_pos()))
+    var bound := _bind_player(scene)
+    if bound:
+        report("player_path", str(scene.get_path_to(_player)))
+        report("player_class", _player.get_class())
+        report("mode", "3D" if _is_3d else "2D")
+        report("start_pos", str(_pos()))
+    else:
+        report("mode", "3D" if scene is Node3D else ("2D" if scene is Node2D else "unknown"))
     dump_tree()
+    await settle()
     save_frame("00_start")
 
+    if WAYPOINTS.is_empty():
+        # Smoke test: nothing configured to walk to. Let the game run for a second and
+        # take a second frame so the flipbook shows it running, not just booted.
+        report("smoke", true)
+        for _i in 60:
+            await get_tree().physics_frame
+        save_frame("01_running")
+        _check_at_end()
+        finish()
+        return
+
+    if not bound:
+        report("error", "waypoints are configured but no player was found at '%s' (or by auto-detect)" % PLAYER_PATH)
+        finish()
+        return
+
     for i in WAYPOINTS.size():
         var target: Vector3 = WAYPOINTS[i]
         var arrived := await _walk_to(target)
@@ -87,32 +117,56 @@ func _check_at_waypoint(index: int) -> void:
     pass
 
 
-# Called once after the last waypoint.
+# Called once at the end of the run (after the last waypoint, or after the smoke run).
 func _check_at_end() -> void:
-    #   report("player_alive", _player.has_method("is_alive") and _player.is_alive())
+    #   report("player_alive", _player != null and _player.has_method("is_alive") and _player.is_alive())
     pass
 
 
 # ── Machinery — you should not need to edit below this line ───────────────────────
 
-func _bind_player() -> bool:
-    var scene := get_tree().current_scene
-    if scene == null:
-        report("error", "no current scene — is run/main_scene set in project.godot?")
-        return false
+# Resolve the player: CONFIG path first, then auto-detect. Records how it was found
+# (reports.player_found_by) so the next edit to CONFIG is a paste, not a guess.
+func _bind_player(scene: Node) -> bool:
+    var found_by := "config PLAYER_PATH"
     _player = scene.get_node_or_null(PLAYER_PATH)
+    if _player != null and not _is_spatial(_player):
+        report("player_config_note", "'%s' is a %s, not a Node2D/Node3D — ignored" % [PLAYER_PATH, _player.get_class()])
+        _player = null
+    if _player == null:
+        _player = _find_first(scene, func(n: Node) -> bool: return n is CharacterBody2D or n is CharacterBody3D)
+        found_by = "first CharacterBody2D/3D"
+    if _player == null:
+        _player = _find_first(scene, func(n: Node) -> bool: return n is RigidBody2D or n is RigidBody3D)
+        found_by = "first RigidBody2D/3D"
+    if _player == null:
+        _player = _find_first(scene, func(n: Node) -> bool: return _is_spatial(n) and n.name.to_lower().contains("player"))
+        found_by = "name contains 'player'"
     if _player == null:
-        report("error", "player not found at '%s'" % PLAYER_PATH)
+        report("player_found_by", "none")
         report("scene_children", _child_names(scene))
-        dump_tree()
         return false
+    report("player_found_by", found_by)
     _is_3d = _player is Node3D
-    if not (_is_3d or _player is Node2D):
-        report("error", "player at '%s' is neither Node2D nor Node3D" % PLAYER_PATH)
-        return false
     return true
 
 
+func _is_spatial(n: Node) -> bool:
+    return n is Node2D or n is Node3D
+
+
+# Depth-first search below `root` (root itself excluded) for the first node `pred`
+# accepts. Returns null when nothing matches.
+func _find_first(root: Node, pred: Callable) -> Node:
+    for c in root.get_children():
+        if pred.call(c):
+            return c
+        var deeper := _find_first(c, pred)
+        if deeper != null:
+            return deeper
+    return null
+
+
 func _child_names(n: Node) -> Array:
     var names := []
     for c in n.get_children():

package/assets/autopilot/run.sh

@@ -3,15 +3,36 @@
 #
 #   bash tests/autopilot/run.sh                    # runs autopilot.gd
 #   bash tests/autopilot/run.sh my_probe.gd        # runs a different probe
+#   bash tests/autopilot/run.sh --reimport         # rebuild the .godot/ caches first
 #
-# No editor required. This spawns the engine's offscreen verify instance, which
-# has a REAL renderer — unlike --headless, which produces no pixels at all.
+# First run on a fresh checkout: the engine's standard editor import runs once,
+# headless, to build the .godot/ caches a never-opened project does not have —
+# imported textures/fonts/audio/models, uid_cache.bin, global_script_class_cache.cfg.
+# Without them the game boots into "Unable to open file ...ctex", "invalid UID" and
+# "Could not find type" errors that are not bugs in your game. The pass is skipped
+# once .godot/global_script_class_cache.cfg exists; --reimport forces it.
+#
+# The verify run itself needs no editor. It spawns the engine's offscreen verify
+# instance, which has a REAL renderer — unlike --headless, which produces no pixels
+# at all (fine for importing, useless for frames).
+#
+# Exit code: 0 when the probe finished, every configured waypoint was reached and the
+# engine logged no ERROR / SCRIPT ERROR. WARNINGs are printed and counted, not failed.
 set -euo pipefail
 
 PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-PROBE="${1:-$PROJECT_DIR/tests/autopilot/autopilot.gd}"
+PROBE="$PROJECT_DIR/tests/autopilot/autopilot.gd"
+REIMPORT=0
+for arg in "$@"; do
+  case "$arg" in
+    --reimport) REIMPORT=1 ;;
+    -h|--help) sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) PROBE="$arg" ;;
+  esac
+done
 OUT="$PROJECT_DIR/tests/autopilot/out"
 MAX_SECONDS="${MAX_SECONDS:-40}"
+IMPORT_MAX_SECONDS="${IMPORT_MAX_SECONDS:-300}"
 
 # Find the engine. Override with SUMMER_BIN=/path/to/engine if it lives elsewhere.
 # There is no `godot` binary on a Summer install — do not substitute one.
@@ -30,6 +51,55 @@ fi
 rm -rf "$OUT"
 mkdir -p "$OUT"
 
+# ── Import pre-pass ───────────────────────────────────────────────────────────────
+# `--import` is Godot's own "start the editor, import everything, quit" mode; Summer
+# is an editor build, so it is available. --headless keeps it off your screen. It
+# reads and writes only this project (.godot/, and any missing *.import files),
+# needs no network, and is bounded by IMPORT_MAX_SECONDS. While it runs, the engine
+# registers itself in ~/.summer/instances/ like any instance (publishesGlobal:false,
+# so it never hijacks a running editor) and removes that entry on exit. Only a
+# watchdog kill can leave the entry behind; the next engine start reaps it.
+CLASS_CACHE="$PROJECT_DIR/.godot/global_script_class_cache.cfg"
+if [[ "$REIMPORT" == 1 || ! -f "$CLASS_CACHE" ]]; then
+  if [[ "$REIMPORT" == 1 ]]; then
+    echo "Importing assets (--reimport) ..."
+  else
+    echo "Importing assets (first run on this checkout: building .godot/ caches) ..."
+  fi
+  import_started=$SECONDS
+  "$ENGINE" --headless --import --disable-crash-handler --path "$PROJECT_DIR" \
+    >"$OUT/import.log" 2>&1 &
+  import_pid=$!
+  import_timed_out=0
+  while kill -0 "$import_pid" 2>/dev/null; do
+    if (( SECONDS - import_started >= IMPORT_MAX_SECONDS )); then
+      kill "$import_pid" 2>/dev/null || true
+      sleep 2
+      kill -9 "$import_pid" 2>/dev/null || true
+      import_timed_out=1
+      break
+    fi
+    sleep 1
+  done
+  import_rc=0
+  wait "$import_pid" || import_rc=$?
+  if [[ "$import_timed_out" == 1 ]]; then
+    echo "FAILED: asset import did not finish within ${IMPORT_MAX_SECONDS}s (raise IMPORT_MAX_SECONDS). Log: $OUT/import.log" >&2
+    tail -20 "$OUT/import.log" >&2
+    exit 1
+  fi
+  if [[ ! -f "$CLASS_CACHE" ]]; then
+    echo "FAILED: asset import exited $import_rc without writing .godot/global_script_class_cache.cfg. Log: $OUT/import.log" >&2
+    tail -20 "$OUT/import.log" >&2
+    exit 1
+  fi
+  imported_files=$(find "$PROJECT_DIR/.godot/imported" -type f 2>/dev/null | wc -l | tr -d ' ')
+  echo "Imported: ${imported_files} files under .godot/imported in $((SECONDS - import_started))s (exit ${import_rc}; log: tests/autopilot/out/import.log)"
+else
+  echo "Import: skipped, .godot/ caches present (pass --reimport to rebuild them)"
+fi
+
+# ── Verify run ────────────────────────────────────────────────────────────────────
 # --disable-crash-handler: Summer's handler popen()s atos from inside a signal
 # handler, which turns a clean failure into a hang. Never arm it on an
 # agent-driven run. Note there is deliberately no --headless here: headless has
@@ -52,18 +122,43 @@ cat "$OUT/results.json"
 echo
 echo "Frames and full log: $OUT"
 
-# finished:false means the probe hit its time ceiling before calling finish().
-# That is a failure, not a pass — exit non-zero so CI notices.
+# ── Verdict ───────────────────────────────────────────────────────────────────────
+# Every errors_seen entry is one line the engine's SummerVerifyLogger::log_error wrote
+# (modules/1summer_engine/verify/summer_verify_logger.cpp), shaped exactly
+#
+#     LEVEL|file:line|function|code|rationale
+#
+# where LEVEL is core/io/logger.h error_type_string(): ERROR, WARNING, SCRIPT ERROR
+# or SHADER ERROR. The logger records every level, so a run can be "red" on nothing
+# but warnings; only WARNING is downgraded here. Anything else — including a level
+# this script has never seen — fails the run.
+#
+# finished:false means the probe hit its time ceiling before calling finish(). That
+# is a failure, not a pass. So is any configured waypoint the autopilot missed.
 if command -v python3 >/dev/null 2>&1; then
   python3 - "$OUT/results.json" <<'PY'
 import json, sys
 d = json.load(open(sys.argv[1]))
 reports = d.get("reports", {})
+errors, warnings = [], []
+for line in d.get("errors_seen", []):
+    (warnings if line.split("|", 1)[0] == "WARNING" else errors).append(line)
+
+def show(lines, limit=10):
+    for l in lines[:limit]:
+        print(f"  {l}", file=sys.stderr)
+    if len(lines) > limit:
+        print(f"  ... {len(lines) - limit} more in results.json", file=sys.stderr)
+
+if warnings:
+    print(f"WARNINGS: {len(warnings)} engine warning(s) during the run (not failures):", file=sys.stderr)
+    show(warnings)
 if not d.get("finished", False):
     print("FAILED: probe did not finish (hit --summer-verify-max)", file=sys.stderr)
     sys.exit(1)
-if d.get("errors_seen"):
-    print(f"FAILED: {len(d['errors_seen'])} engine error(s) during the run", file=sys.stderr)
+if errors:
+    print(f"FAILED: {len(errors)} engine error(s) during the run:", file=sys.stderr)
+    show(errors)
     sys.exit(1)
 if reports.get("error"):
     print(f"FAILED: {reports['error']}", file=sys.stderr)
@@ -74,5 +169,35 @@ missed = [k for k, v in reports.items() if k.endswith("_reached") and v is False
 if missed:
     print(f"FAILED: waypoints not reached: {', '.join(sorted(missed))}", file=sys.stderr)
     sys.exit(1)
+reached = sum(1 for k, v in reports.items() if k.endswith("_reached") and v is True)
+what = "smoke test: booted and ran" if reports.get("smoke") else f"{reached} waypoint(s) reached"
+print(f"PASSED: {what}, {len(d.get('frames', []))} frame(s), 0 errors, {len(warnings)} warning(s)")
 PY
+else
+  # No python3 (Git Bash on Windows, minimal containers). Coarse line-based reading
+  # of the same file: Godot pretty-prints results.json one array element / key per
+  # line, so the LEVEL prefix and the report keys are greppable. Fail closed.
+  echo "python3 not found: using a coarse shell reading of results.json"
+  n_err=$(grep -cE '^[[:space:]]*"(ERROR|SCRIPT ERROR|SHADER ERROR)\|' "$OUT/results.json" || true)
+  n_warn=$(grep -cE '^[[:space:]]*"WARNING\|' "$OUT/results.json" || true)
+  if (( n_warn > 0 )); then
+    echo "WARNINGS: ${n_warn} engine warning(s) during the run (not failures)" >&2
+  fi
+  if ! grep -qE '^[[:space:]]*"finished": true' "$OUT/results.json"; then
+    echo "FAILED: probe did not finish (hit --summer-verify-max)" >&2
+    exit 1
+  fi
+  if (( n_err > 0 )); then
+    echo "FAILED: ${n_err} engine error(s) during the run" >&2
+    exit 1
+  fi
+  if grep -qE '^[[:space:]]*"error": ' "$OUT/results.json"; then
+    echo "FAILED: probe reported an error (reports.error). Edit the CONFIG block at the top of tests/autopilot/autopilot.gd." >&2
+    exit 1
+  fi
+  if grep -qE '_reached": false' "$OUT/results.json"; then
+    echo "FAILED: waypoints not reached" >&2
+    exit 1
+  fi
+  echo "PASSED: 0 errors, ${n_warn} warning(s)"
 fi