summer-engine 3.4.1 → 3.5.1

package/dist/core/capabilities/capture-gameplay.js

@@ -1,4 +1,5 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, openSync, readdirSync, readFileSync, readSync, closeSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { platform } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
@@ -15,8 +16,22 @@ const DEFAULT_RESOLUTION = "1920x1080";
 const MAX_FRAMES = 10;
 /** The engine clamps --summer-verify-max to 240 (main.cpp SUMMER_VERIFY_MAX_SECONDS). */
 const ENGINE_MAX_SECONDS = 240;
+/** Offscreen runs draw uncapped (~130 fps) while the verify backstop counts 60 frames a second; cap the frame rate so seconds stay seconds. */
+const CAPTURE_MAX_FPS = 60;
+/** Files the engine imports; a new or changed one means the .godot/ caches are stale. */
+const IMPORTED_EXTENSIONS = new Set([
+    ".png", ".jpg", ".jpeg", ".webp", ".svg", ".tga", ".bmp", ".exr", ".hdr", ".ktx", ".dds",
+    ".glb", ".gltf", ".fbx", ".obj", ".blend", ".dae",
+    ".wav", ".ogg", ".mp3",
+    ".ttf", ".otf", ".woff", ".woff2", ".fnt", ".csv",
+]);
+const SKIPPED_DIRS = new Set([".godot", ".git", ".summer", ".import", "node_modules", "build", "exports"]);
+const MAX_SCANNED_FILES = 50_000;
 const IMPORT_TIMEOUT_MS = 5 * 60_000;
 const PROBE_FILE = "capture_probe.gd";
+const MAX_STEPS = 50;
+const MAX_ARGS = 32;
+const STEP_KINDS = ["press", "key", "action", "click", "drag", "wait", "shot"];
 function invalid(message, recovery) {
     return new BuildToolError("capture_args_invalid", message, recovery);
 }
@@ -54,6 +69,169 @@ function checkScene(project, scene) {
     }
     return value;
 }
+function checkArgs(args) {
+    if (args === undefined)
+        return [];
+    if (!Array.isArray(args) || args.length > MAX_ARGS || args.some((arg) => typeof arg !== "string" || arg.length > 200 || /[\u0000\n\r]/.test(arg))) {
+        throw invalid(`args must be at most ${MAX_ARGS} single-line strings.`, 'Recovery: pass the game\'s own flags, e.g. ["--autostart", "--solo"].');
+    }
+    return args;
+}
+function point(value, where) {
+    if (!Array.isArray(value) || value.length !== 2 || !value.every((n) => typeof n === "number" && Number.isFinite(n) && n >= 0 && n <= 7680)) {
+        throw invalid(`${where} must be [x, y] in frame pixels.`, "Recovery: pass two numbers from 0 to 7680, e.g. [960, 540] for the middle of a 1920x1080 frame.");
+    }
+    return [value[0], value[1]];
+}
+/** Validate the steps and turn them into the probe's one shape. */
+export function probeSteps(steps) {
+    if (steps === undefined)
+        return [];
+    if (!Array.isArray(steps) || steps.length > MAX_STEPS) {
+        throw invalid(`steps must be a list of at most ${MAX_STEPS} steps.`, 'Recovery: pass e.g. [{"press":"Play"},{"wait":2000},{"shot":true}].');
+    }
+    const out = steps.map((raw, index) => {
+        const where = `steps[${index}]`;
+        const step = (raw && typeof raw === "object" ? raw : {});
+        const kinds = STEP_KINDS.filter((kind) => kind in step);
+        if (kinds.length !== 1) {
+            throw invalid(`${where} must have exactly one of ${STEP_KINDS.join(", ")}.`, 'Recovery: one step per object, e.g. {"press":"Play"} or {"key":"Space"}.');
+        }
+        const hold = boundedNumber(step.holdMs, 100, 0, 10_000, `${where}.holdMs`);
+        const name = (key) => {
+            const value = step[key];
+            if (typeof value !== "string" || !value.trim() || value.length > 100) {
+                throw invalid(`${where}.${key} must be a non-empty name.`, 'Recovery: e.g. {"press":"Play"}, {"key":"Space"}, {"action":"jump"}.');
+            }
+            return value.trim();
+        };
+        switch (kinds[0]) {
+            case "press":
+                return { type: "press", text: name("press"), timeout: boundedNumber(step.timeoutSeconds, 10, 0, 60, `${where}.timeoutSeconds`) };
+            case "key":
+                return { type: "key", text: name("key"), hold_ms: hold };
+            case "action":
+                return { type: "action", text: name("action"), hold_ms: hold };
+            case "click":
+                return { type: "click", at: point(step.click, `${where}.click`) };
+            case "drag": {
+                const drag = (step.drag && typeof step.drag === "object" ? step.drag : {});
+                return {
+                    type: "drag",
+                    at: point(drag.from, `${where}.drag.from`),
+                    to: point(drag.to, `${where}.drag.to`),
+                    ms: boundedNumber(drag.ms, 300, 0, 10_000, `${where}.drag.ms`),
+                };
+            }
+            case "wait":
+                return { type: "wait", ms: boundedNumber(step.wait, 0, 0, 60_000, `${where}.wait`) };
+            default:
+                if (step.shot !== true)
+                    throw invalid(`${where}.shot must be true.`, 'Recovery: {"shot":true} saves a frame at that point.');
+                return { type: "shot" };
+        }
+    });
+    if (out.filter((step) => step.type === "shot").length > MAX_FRAMES) {
+        throw invalid(`at most ${MAX_FRAMES} shot steps.`, "Recovery: capture again for more frames.");
+    }
+    return out;
+}
+/** Seconds the steps can take at most (press waits for its button). */
+function stepSeconds(steps) {
+    return steps.reduce((sum, step) => sum + (step.timeout ?? 0) + ((step.hold_ms ?? 0) + (step.ms ?? 0)) / 1000 + 0.5, 0);
+}
+/**
+ * Why one imported file needs importing again, or null when its import is
+ * current. Like the editor: the .import sidecar names the cached result, whose
+ * .md5 records the source's hash; the hash is only computed when the source is
+ * newer than that record.
+ */
+function staleImport(project, path) {
+    const relative = path.slice(project.length + 1);
+    let sidecar;
+    try {
+        sidecar = readFileSync(`${path}.import`, "utf8");
+    }
+    catch {
+        return `${relative} has not been imported`;
+    }
+    const dest = /^path(?:\.[a-z0-9_]+)?="res:\/\/\.godot\/imported\/([^"]+)"/m.exec(sidecar)?.[1];
+    // importer "keep" or "skip": nothing is cached.
+    if (!dest)
+        return null;
+    const record = join(project, ".godot", "imported", dest.replace(/\.[^.]+$/, ".md5"));
+    let recorded;
+    try {
+        recorded = { text: readFileSync(record, "utf8"), mtimeMs: statSync(record).mtimeMs };
+    }
+    catch {
+        return `${relative} has no import cache`;
+    }
+    if (statSync(path).mtimeMs <= recorded.mtimeMs)
+        return null;
+    const sourceMd5 = /source_md5="([0-9a-f]+)"/.exec(recorded.text)?.[1];
+    return sourceMd5 === createHash("md5").update(readFileSync(path)).digest("hex") ? null : `${relative} changed after the last import`;
+}
+function isLfsPointer(path) {
+    try {
+        if (statSync(path).size > 1024)
+            return false;
+        const fd = openSync(path, "r");
+        const buffer = Buffer.alloc(64);
+        readSync(fd, buffer, 0, 64, 0);
+        closeSync(fd);
+        return buffer.toString("utf8").startsWith("version https://git-lfs");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether the project's import caches are stale: an imported file (texture,
+ * model, sound, font) that has no .import sidecar or cache yet, or whose
+ * content changed since it was imported (a pull, or LFS files fetched after
+ * the first import). Also names files that are still Git LFS pointers, which no
+ * import can fix.
+ */
+export function importState(project) {
+    if (!existsSync(join(project, ".godot")))
+        return { needed: true, reason: "the project was never imported", lfsPointers: [] };
+    const lfsPointers = [];
+    let reason;
+    let scanned = 0;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (scanned >= MAX_SCANNED_FILES)
+                return;
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIPPED_DIRS.has(entry.name) && !existsSync(join(path, ".gdignore")))
+                    walk(path);
+                continue;
+            }
+            const dot = entry.name.lastIndexOf(".");
+            if (!entry.isFile() || dot < 0 || !IMPORTED_EXTENSIONS.has(entry.name.slice(dot).toLowerCase()))
+                continue;
+            scanned++;
+            if (isLfsPointer(path)) {
+                if (lfsPointers.length < 10)
+                    lfsPointers.push(path.slice(project.length + 1));
+                continue;
+            }
+            if (!reason)
+                reason = staleImport(project, path) ?? undefined;
+        }
+    };
+    walk(project);
+    return { needed: reason !== undefined, ...(reason ? { reason } : {}), lfsPointers };
+}
 function stamp(date) {
     return date.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z").replace("T", "-");
 }
@@ -77,14 +255,42 @@ export function pngSize(bytes) {
         return null;
     return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
 }
+/** A GDScript string literal (JSON escapes are valid GDScript escapes). */
+const gdString = (text) => JSON.stringify(text);
+const gdFloat = (value) => (Number.isInteger(value) ? `${value}.0` : String(value));
+const gdVector = (point) => `Vector2(${gdFloat(point[0])}, ${gdFloat(point[1])})`;
+/** One step as a typed GDScript call: no Variant reads, so strict projects load it. */
+function stepLine(step, index) {
+    switch (step.type) {
+        case "press":
+            return `await _press(${index}, ${gdString(step.text)}, ${gdFloat(step.timeout)})`;
+        case "key":
+            return `await _key_named(${index}, ${gdString(step.text)}, ${step.hold_ms})`;
+        case "action":
+            return `await _action_named(${index}, ${gdString(step.text)}, ${step.hold_ms})`;
+        case "click":
+            return `await _click(${gdVector(step.at)})`;
+        case "drag":
+            return `await _drag(${gdVector(step.at)}, ${gdVector(step.to)}, ${step.ms})`;
+        case "wait":
+            return `await get_tree().create_timer(${gdFloat(step.ms / 1000)}, true).timeout`;
+        default:
+            return "await _shot()";
+    }
+}
 /**
  * The stock probe. Self-contained (extends Node, no base class to copy into the
  * project); follows the verify-instance contract of assets/autopilot/probe_base.gd:
  * the engine sets summer_out_dir and summer_max_seconds before _ready(), the
  * first frames are empty until the scene has drawn twice, results.json is
- * always written.
+ * always written. The steps are generated as typed calls, and nothing reads a
+ * Variant, so projects that treat every GDScript warning as an error
+ * (untyped_declaration, unsafe_call_argument, unsafe_cast, integer_division)
+ * still load it.
  */
-export function captureProbeSource(frames, waitSeconds, intervalSeconds) {
+export function captureProbeSource(frames, waitSeconds, intervalSeconds, steps = []) {
+    const shotSteps = steps.some((step) => step.type === "shot");
+    const body = steps.length ? steps.map((step, index) => `\t${stepLine(step, index)}`).join("\n") : "\tpass";
     return `# Written by summer_capture_gameplay. Safe to delete.
 # Fully typed: projects that treat GDScript warnings as errors must still load it.
 extends Node
@@ -95,11 +301,13 @@ var summer_max_seconds: int = 20
 const FRAMES: int = ${frames}
 const WAIT_SECONDS: float = ${waitSeconds.toFixed(3)}
 const INTERVAL_SECONDS: float = ${intervalSeconds.toFixed(3)}
+const SHOT_STEPS: bool = ${shotSteps}
 
-var _shots: Array = []
-var _warnings: Array = []
+var _shots: Array[Dictionary] = []
+var _warnings: Array[String] = []
 var _start_ms: int = 0
 var _done: bool = false
+var _pressed_seen: bool = false
 
 func _ready() -> void:
 \tprocess_mode = Node.PROCESS_MODE_ALWAYS
@@ -121,23 +329,159 @@ func _run() -> void:
 \t\t_finish(true)
 \t\treturn
 \tawait get_tree().create_timer(WAIT_SECONDS, true).timeout
-\tfor i: int in range(FRAMES):
-\t\tif i > 0:
-\t\t\tawait get_tree().create_timer(INTERVAL_SECONDS, true).timeout
-\t\tawait RenderingServer.frame_post_draw
-\t\tvar img: Image = get_viewport().get_texture().get_image()
-\t\tvar file_name: String = "shot-%02d.png" % (i + 1)
-\t\tif img == null:
-\t\t\t_warnings.append("%s: the viewport returned no image." % file_name)
-\t\t\tcontinue
-\t\tif img.save_png(summer_out_dir.path_join(file_name)) == OK:
-\t\t\t_shots.append({"file": file_name, "width": img.get_width(), "height": img.get_height()})
-\t\telse:
-\t\t\t_warnings.append("%s: could not write the PNG." % file_name)
+\tawait _steps()
+\tif not SHOT_STEPS:
+\t\tfor i: int in range(FRAMES):
+\t\t\tif i > 0:
+\t\t\t\tawait get_tree().create_timer(INTERVAL_SECONDS, true).timeout
+\t\t\tawait _shot()
 \t_finish(true)
 
-func _errors() -> Array:
-\tvar errors: Array = []
+func _steps() -> void:
+${body}
+
+func _shot() -> void:
+\tawait RenderingServer.frame_post_draw
+\tvar img: Image = get_viewport().get_texture().get_image()
+\tvar file_name: String = "shot-%02d.png" % (_shots.size() + 1)
+\tif img == null:
+\t\t_warnings.append("%s: the viewport returned no image." % file_name)
+\t\treturn
+\tif img.save_png(summer_out_dir.path_join(file_name)) == OK:
+\t\t_shots.append({"file": file_name, "width": img.get_width(), "height": img.get_height()})
+\telse:
+\t\t_warnings.append("%s: could not write the PNG." % file_name)
+
+# Clicks and drags take frame pixels: the saved PNG's own coordinates. The frame
+# is the root viewport; the final transform maps it to the window, where input
+# events land, so a stretched canvas still gets the click where the frame shows it.
+func _to_window(frame_pos: Vector2) -> Vector2:
+\treturn get_viewport().get_final_transform() * frame_pos
+
+func _mouse_button(frame_pos: Vector2, pressed: bool) -> void:
+\tvar ev: InputEventMouseButton = InputEventMouseButton.new()
+\tev.button_index = MOUSE_BUTTON_LEFT
+\tev.pressed = pressed
+\tev.button_mask = MOUSE_BUTTON_MASK_LEFT if pressed else 0
+\tev.position = _to_window(frame_pos)
+\tev.global_position = ev.position
+\tInput.parse_input_event(ev)
+
+func _mouse_move(frame_pos: Vector2, relative: Vector2, held: bool) -> void:
+\tvar ev: InputEventMouseMotion = InputEventMouseMotion.new()
+\tev.position = _to_window(frame_pos)
+\tev.global_position = ev.position
+\tev.relative = relative
+\tev.button_mask = MOUSE_BUTTON_MASK_LEFT if held else 0
+\tInput.parse_input_event(ev)
+
+func _click(frame_pos: Vector2) -> void:
+\t_mouse_move(frame_pos, Vector2.ZERO, false)
+\tawait get_tree().process_frame
+\t_mouse_button(frame_pos, true)
+\tawait get_tree().create_timer(0.05, true).timeout
+\t_mouse_button(frame_pos, false)
+\tawait get_tree().process_frame
+
+func _drag(from: Vector2, to: Vector2, ms: int) -> void:
+\t_mouse_move(from, Vector2.ZERO, false)
+\t_mouse_button(from, true)
+\tvar moves: int = maxi(2, roundi(ms / 16.0))
+\tvar last: Vector2 = from
+\tfor j: int in range(1, moves + 1):
+\t\tawait get_tree().create_timer(ms / 1000.0 / moves, true).timeout
+\t\tvar here: Vector2 = from.lerp(to, float(j) / moves)
+\t\t_mouse_move(here, here - last, true)
+\t\tlast = here
+\t_mouse_button(to, false)
+\tawait get_tree().process_frame
+
+func _key_named(index: int, key_name: String, hold_ms: int) -> void:
+\tvar keycode: Key = OS.find_keycode_from_string(key_name)
+\tif keycode == KEY_NONE:
+\t\t_warnings.append('steps[%d]: no key is named "%s" (use names like Space, Enter, Escape, A, Up).' % [index, key_name])
+\t\treturn
+\tvar ev: InputEventKey = InputEventKey.new()
+\tev.keycode = keycode
+\tev.physical_keycode = keycode
+\tev.pressed = true
+\tInput.parse_input_event(ev)
+\tawait get_tree().create_timer(hold_ms / 1000.0, true).timeout
+\tvar up: InputEventKey = InputEventKey.new()
+\tup.keycode = keycode
+\tup.physical_keycode = keycode
+\tup.pressed = false
+\tInput.parse_input_event(up)
+\tawait get_tree().process_frame
+
+func _action_named(index: int, action: String, hold_ms: int) -> void:
+\tif not InputMap.has_action(StringName(action)):
+\t\t_warnings.append('steps[%d]: the project has no input action "%s".' % [index, action])
+\t\treturn
+\tvar ev: InputEventAction = InputEventAction.new()
+\tev.action = StringName(action)
+\tev.pressed = true
+\tInput.parse_input_event(ev)
+\tawait get_tree().create_timer(hold_ms / 1000.0, true).timeout
+\tvar up: InputEventAction = InputEventAction.new()
+\tup.action = StringName(action)
+\tup.pressed = false
+\tInput.parse_input_event(up)
+\tawait get_tree().process_frame
+
+# A visible, enabled button: exact text, then node name, then partial text, then partial name.
+func _find_button(label: String) -> BaseButton:
+\tvar want: String = label.strip_edges().to_lower()
+\tvar best: BaseButton = null
+\tvar best_rank: int = 99
+\tfor node: Node in get_tree().root.find_children("*", "BaseButton", true, false):
+\t\tvar button: BaseButton = node as BaseButton
+\t\tif button == null or button.disabled or not button.is_visible_in_tree():
+\t\t\tcontinue
+\t\tvar text: String = ""
+\t\tvar as_button: Button = button as Button
+\t\tif as_button != null:
+\t\t\ttext = tr(as_button.text).strip_edges().to_lower()
+\t\tvar node_name: String = String(button.name).to_lower()
+\t\tvar rank: int = 99
+\t\tif text == want:
+\t\t\trank = 0
+\t\telif node_name == want:
+\t\t\trank = 1
+\t\telif text.contains(want):
+\t\t\trank = 2
+\t\telif node_name.contains(want):
+\t\t\trank = 3
+\t\tif rank < best_rank:
+\t\t\tbest = button
+\t\t\tbest_rank = rank
+\treturn best
+
+func _on_pressed_seen() -> void:
+\t_pressed_seen = true
+
+# Click the button's centre like a player; emit pressed when the click did not reach it.
+func _press(index: int, label: String, timeout: float) -> void:
+\tvar button: BaseButton = _find_button(label)
+\tvar deadline: int = Time.get_ticks_msec() + roundi(timeout * 1000.0)
+\twhile button == null and Time.get_ticks_msec() < deadline:
+\t\tawait get_tree().create_timer(0.1, true).timeout
+\t\tbutton = _find_button(label)
+\tif button == null:
+\t\t_warnings.append('steps[%d]: no visible, enabled button "%s" within %.1f s.' % [index, label, timeout])
+\t\treturn
+\t_pressed_seen = false
+\tbutton.pressed.connect(_on_pressed_seen, CONNECT_ONE_SHOT)
+\tvar centre: Vector2 = button.get_global_transform_with_canvas() * (button.size / 2.0)
+\tawait _click(centre)
+\tif not _pressed_seen and is_instance_valid(button):
+\t\tif button.pressed.is_connected(_on_pressed_seen):
+\t\t\tbutton.pressed.disconnect(_on_pressed_seen)
+\t\tbutton.pressed.emit()
+\tawait get_tree().process_frame
+
+func _errors() -> Array[String]:
+\tvar errors: Array[String] = []
 \tvar path: String = summer_out_dir.path_join("errors.log")
 \tif FileAccess.file_exists(path):
 \t\tvar f: FileAccess = FileAccess.open(path, FileAccess.READ)
@@ -171,6 +515,8 @@ export async function captureGameplay(input, overrides = {}) {
     const waitSeconds = boundedNumber(input.waitSeconds, 3, 0, 120, "waitSeconds");
     const intervalSeconds = boundedNumber(input.intervalSeconds, 1, 0.1, 60, "intervalSeconds");
     const scene = checkScene(project, input.scene);
+    const userArgs = checkArgs(input.args);
+    const steps = probeSteps(input.steps);
     const started = deps.now();
     const binary = deps.findBinary();
     if (!binary) {
@@ -185,19 +531,25 @@ export async function captureGameplay(input, overrides = {}) {
     }
     await mkdir(out, { recursive: true });
     await rm(join(out, "results.json"), { force: true });
-    // A never-opened checkout has no .godot/ caches; the game would boot into
-    // missing-import errors. Build them once, headless (same as tests/autopilot).
+    // A never-opened checkout has no .godot/ caches, and a pull (or LFS files
+    // fetched later) leaves them stale; the game would boot into missing or old
+    // imports. Import headless first (same as tests/autopilot).
     let imported = false;
-    if (!existsSync(join(project, ".godot"))) {
+    const importCheck = importState(project);
+    if (importCheck.needed) {
         const run = await deps.run(binary, ["--headless", "--import", "--disable-crash-handler", "--path", project], IMPORT_TIMEOUT_MS);
         if (run.timedOut || !existsSync(join(project, ".godot"))) {
             throw new BuildToolError("import_failed", "Summer Engine could not import the project's assets before the capture.", "Recovery: open the project once in Summer Engine (or run the engine with --headless --import), then capture again.", undefined, { output: outputTail(run.output) });
         }
         imported = true;
     }
+    const importReason = importCheck.reason;
     const probe = join(out, PROBE_FILE);
-    await writeFile(probe, captureProbeSource(frames, waitSeconds, intervalSeconds));
-    const maxSeconds = Math.min(ENGINE_MAX_SECONDS, Math.ceil(waitSeconds + (frames - 1) * intervalSeconds + 30));
+    await writeFile(probe, captureProbeSource(frames, waitSeconds, intervalSeconds, steps));
+    // The engine's verify backstop counts frames, not seconds; with the frame rate
+    // capped at 60 twice the planned run leaves room for slow loads.
+    const plannedSeconds = waitSeconds + (frames - 1) * intervalSeconds + stepSeconds(steps) + 15;
+    const maxSeconds = Math.min(ENGINE_MAX_SECONDS, Math.ceil(2 * plannedSeconds));
     const args = [
         "--disable-crash-handler",
         // No local HTTP API or ~/.summer discovery files for this throwaway run.
@@ -206,13 +558,18 @@ export async function captureGameplay(input, overrides = {}) {
         project,
         "--resolution",
         resolution.text,
+        "--max-fps",
+        String(CAPTURE_MAX_FPS),
         ...(scene ? ["--scene", scene] : []),
+        // The verify instance is offscreen already; the posture flag says so explicitly.
+        "--summer-offscreen",
         "--summer-verify",
         probe,
         "--summer-verify-out",
         out,
         "--summer-verify-max",
         String(maxSeconds),
+        ...(userArgs.length ? ["--", ...userArgs] : []),
     ];
     let run;
     try {
@@ -259,6 +616,9 @@ export async function captureGameplay(input, overrides = {}) {
         captured.push({ path, ...size });
     }
     const warnings = [...(results.frame_warnings ?? [])];
+    if (importCheck.lfsPointers.length) {
+        warnings.push(`These files are Git LFS pointers, not the real files, so the game shows them missing: ${importCheck.lfsPointers.join(", ")}. Run "git lfs pull" in the project, then capture again.`);
+    }
     if (results.finished === false)
         warnings.push("The game hit its time limit before every frame was saved.");
     const off = captured.filter((frame) => frame.width !== resolution.width || frame.height !== resolution.height);
@@ -276,6 +636,7 @@ export async function captureGameplay(input, overrides = {}) {
         out,
         engine: binary,
         imported,
+        ...(imported && importReason ? { importReason } : {}),
         durationMs: deps.now().getTime() - started.getTime(),
         ...(warnings.length ? { warnings } : {}),
         next: "Look at each frame before using it. For the store: upload with summer_upload_image_begin/complete and set them as desktop.screenshots or mobile.screenshots (summer_store_set_art). The game's own HUD may show; add no captions, logos or overlays.",

package/dist/core/capabilities/export-engine-version.d.ts

@@ -4,6 +4,13 @@
  * summer_export_game writes and fails after a full engine start.
  */
 export declare const EXPORT_MIN_ENGINE_VERSION = "0.7.0";
+/** Bundle targets that need a newer engine than EXPORT_MIN_ENGINE_VERSION. */
+export declare const TARGET_MIN_ENGINE_VERSION: Readonly<Record<string, string>>;
+/** The requested targets this engine version cannot export; an unreadable version skips none. */
+export declare function targetsNeedingNewerEngine(targets: readonly string[], version: string | null): Array<{
+    target: string;
+    needs: string;
+}>;
 export declare const ENGINE_UPDATE_HOW = "run \"summer install --yes\" (or download it from summerengine.com/download)";
 /** Installed Summer version of an engine binary, or null when this system cannot read it. */
 export declare function installedEngineVersion(binary: string): string | null;

package/dist/core/capabilities/export-engine-version.js

@@ -7,6 +7,15 @@ import { BuildToolError } from "./summer-bundle.js";
  * summer_export_game writes and fails after a full engine start.
  */
 export const EXPORT_MIN_ENGINE_VERSION = "0.7.0";
+/** Bundle targets that need a newer engine than EXPORT_MIN_ENGINE_VERSION. */
+export const TARGET_MIN_ENGINE_VERSION = { android: "0.7.1" };
+/** The requested targets this engine version cannot export; an unreadable version skips none. */
+export function targetsNeedingNewerEngine(targets, version) {
+    return targets.flatMap((target) => {
+        const needs = TARGET_MIN_ENGINE_VERSION[target];
+        return needs && isVersionAtLeast(version, needs) === false ? [{ target, needs }] : [];
+    });
+}
 export const ENGINE_UPDATE_HOW = 'run "summer install --yes" (or download it from summerengine.com/download)';
 /** Installed Summer version of an engine binary, or null when this system cannot read it. */
 export function installedEngineVersion(binary) {

package/dist/core/capabilities/export-game.d.ts

@@ -34,6 +34,8 @@ export interface ExportGameInput {
     out?: string;
     /** Export with debug enabled (--export-debug). */
     debug?: boolean;
+    /** Bundle with targets: set summer.build.json targetPlatforms to the targets first, so the store takes the declaration. */
+    alignDeclaration?: boolean;
     /** Export preset name; the engine's own is "summer.games". Bundle format without targets only. */
     preset?: string;
     /** Store platforms: macos, windows, ios, android, web. */
@@ -52,6 +54,8 @@ export interface ExportGameResult {
     preset: string;
     /** The targets asked for, when any were. */
     targets?: StoreTarget[];
+    /** Asked-for targets left out of the bundle (an engine too old for them); warnings say why. */
+    skippedTargets?: StoreTarget[];
     /** What happened to export_presets.cfg for the preset this export used. */
     presetChange?: EnsuredPreset["change"];
     debug: boolean;

package/dist/core/capabilities/export-game.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { platform } from "node:os";
 import { engineSelectionFromEnv } from "../engine.js";
@@ -7,10 +7,10 @@ import { findEngineBinary } from "../engine-install.js";
 import { readStoreJson, writeStoreJson } from "../store.js";
 import { writeZip } from "../util/zip-write.js";
 import { engineErrorLines, runEngine } from "./engine-run.js";
-import { assertExportEngine, installedEngineVersion } from "./export-engine-version.js";
+import { assertExportEngine, ENGINE_UPDATE_HOW, installedEngineVersion, targetsNeedingNewerEngine } from "./export-engine-version.js";
 import { BUNDLE_TARGETS, DOWNLOAD_TARGETS, SUMMER_GAMES_PRESET, bundlePresetSpec, ensurePreset, normalizeTargets, variantString, } from "./export-presets.js";
 import { engineTemplateInfo, findInstalledTemplate, templateFileFor } from "./export-templates.js";
-import { BuildToolError, hashFile, readSummerBundle } from "./summer-bundle.js";
+import { BuildToolError, declarationMismatch, hashFile, readSummerBundle, samePlatforms } from "./summer-bundle.js";
 export { runEngine, SUMMER_GAMES_PRESET };
 /**
  * summer_export_game: run the installed Summer Engine headless and return the
@@ -272,10 +272,27 @@ async function runExport(deps, binary, project, preset, out, debug, timeoutMs, n
         throw new BuildToolError("export_failed", `Summer Engine did not export the game (exit ${run.code ?? run.signal})${named.length ? `: ${named.join(" | ")}` : "."}`, [exportFailureRecovery(errors, preset), ...notes].join(" "), undefined, { errors, output: outputTail(run.output) });
     }
 }
+/** Set the project's summer.build.json targetPlatforms to the export targets (a hosted game's Build declaration). */
+async function alignBuildDeclaration(project, targets) {
+    const path = join(project, "summer.build.json");
+    if (!existsSync(path))
+        return;
+    let build;
+    try {
+        build = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        throw new BuildToolError("build_declaration_invalid", "summer.build.json is not valid JSON.", "Recovery: fix summer.build.json, then export again.");
+    }
+    if (Array.isArray(build.targetPlatforms) && samePlatforms(build.targetPlatforms.map(String), targets))
+        return;
+    build.targetPlatforms = [...targets];
+    await writeFile(path, `${JSON.stringify(build, null, 2)}\n`);
+}
 export async function exportGame(input, overrides = {}) {
     const deps = { ...defaultDependencies, ...overrides };
     const project = resolveExportProject(input.project);
-    const targets = input.targets?.length ? normalizeTargets(input.targets) : undefined;
+    let targets = input.targets?.length ? normalizeTargets(input.targets) : undefined;
     const format = resolveFormat(input, targets);
     const debug = input.debug === true;
     const started = deps.now();
@@ -293,13 +310,26 @@ export async function exportGame(input, overrides = {}) {
         throw new BuildToolError("engine_not_installed", "Summer Engine is not installed on this machine.", 'Recovery: run "summer install", or set SUMMER_BIN to the engine executable, then export again.');
     }
     // Before any preset is written: an old engine cannot read them.
-    assertExportEngine(binary, deps.engineVersion(binary));
+    const engineVersion = deps.engineVersion(binary);
+    assertExportEngine(binary, engineVersion);
+    // A target this engine cannot build is left out, not the whole export.
+    const skipped = format === "bundle" && targets ? targetsNeedingNewerEngine(targets, engineVersion) : [];
+    const skippedWarnings = skipped.map(({ target, needs }) => `${target} was not exported: it needs Summer Engine ${needs} or newer, and ${engineVersion} is installed. Update (${ENGINE_UPDATE_HOW}) and export ${target} again.`);
+    if (skipped.length) {
+        const left = targets.filter((target) => !skipped.some((entry) => entry.target === target));
+        if (!left.length) {
+            throw new BuildToolError("export_target_unsupported", `Summer Engine ${engineVersion} cannot export ${skipped.map((entry) => entry.target).join(", ")}.`, `Recovery: ${skippedWarnings.join(" ")}`, undefined, { engineVersion, skippedTargets: skipped });
+        }
+        targets = left;
+    }
     if (format === "download") {
         return exportDownload(deps, binary, project, targets[0], out, debug, timeoutMs, started);
     }
     out ??= join(await defaultExportDir(project), `${basename(project)}-${stamp(started)}.zip`);
     const before = existsSync(out) ? statSync(out).mtimeMs : null;
     const projectBefore = await snapshotProjectFiles(project);
+    if (targets && input.alignDeclaration === true)
+        await alignBuildDeclaration(project, targets);
     const ensured = targets ? await ensurePreset(project, bundlePresetSpec(targets)) : undefined;
     const preset = ensured?.name ?? (input.preset?.trim() || SUMMER_GAMES_PRESET);
     const notes = (targets ?? []).flatMap((target) => TARGET_ENGINE_NOTE[target] ?? []);
@@ -310,10 +340,20 @@ export async function exportGame(input, overrides = {}) {
     }
     const bundle = await readSummerBundle(out);
     const missing = (targets ?? []).filter((target) => !bundle.targetPlatforms.includes(target));
-    if (missing.length) {
+    // Some targets made it: keep the bundle and say which did not.
+    const partial = missing.length > 0 && missing.length < (targets ?? []).length;
+    if (missing.length && !partial) {
         throw new BuildToolError("export_target_unsupported", `This Summer Engine exported the bundle without ${missing.join(", ")}: its summer.games preset has no such platform.`, ["Recovery: update Summer Engine and export again, or export without those targets.", ...missing.flatMap((target) => TARGET_ENGINE_NOTE[target] ?? [])].join(" "), undefined, { exportedPlatforms: bundle.targetPlatforms, path: out });
     }
-    const warnings = projectChangeWarnings(projectChanges);
+    const warnings = [...skippedWarnings, ...projectChangeWarnings(projectChanges)];
+    const mismatch = declarationMismatch(bundle);
+    if (mismatch) {
+        warnings.unshift(`summer_publish_build will refuse this export (declaration_mismatch): ${mismatch}. Export again with alignDeclaration:true to set summer.build.json targetPlatforms to [${bundle.targetPlatforms.join(", ")}], or with targets equal to what it declares.`);
+    }
+    if (partial) {
+        warnings.push(`This Summer Engine exported the bundle without ${missing.join(", ")}: its summer.games preset has no such platform. ` +
+            ["Update Summer Engine and export them again.", ...missing.flatMap((target) => TARGET_ENGINE_NOTE[target] ?? [])].join(" "));
+    }
     const desktopOnly = bundle.hosted ? [] : bundle.targetPlatforms.filter((target) => !STANDALONE_TARGETS.includes(target));
     if (desktopOnly.length) {
         warnings.push(`This game has no server, and the store runs games without a server on iPhone and Android only: summer_publish_build will refuse ${desktopOnly.join(", ")}. ` +
@@ -332,6 +372,9 @@ export async function exportGame(input, overrides = {}) {
         project,
         preset,
         ...(targets ? { targets, presetChange: ensured.change } : {}),
+        ...(skipped.length || partial
+            ? { skippedTargets: [...skipped.map((entry) => entry.target), ...(partial ? missing : [])] }
+            : {}),
         debug,
         engine: binary,
         durationMs: deps.now().getTime() - started.getTime(),