summer-engine 3.0.0 → 3.2.0

package/dist/core/capabilities/replace-node.js

@@ -0,0 +1,423 @@
+/**
+ * replace-node — ONE implementation of `summer_replace_node` for both faces
+ * (src/mcp/tools/scene-tools.ts and tool-dispatch.ts), built from ops whose
+ * results persist, and verified against the SAVED scene file.
+ *
+ * Why not the engine's ReplaceNode op for scenes: SceneOps::replace_node
+ * (engine modules/1summer_engine/editor/ops/scene_ops.cpp, scene branch and
+ * the async _finish_replace_node) instantiates the new PackedScene and hands
+ * it to SceneTreeDock::replace_node — the editor's "Change Type" path — which
+ * ends in Node::replace_by (scene/main/node.cpp). replace_by finishes with
+ * `p_node->set_scene_file_path(get_scene_file_path())`: the new instance is
+ * stamped with the OLD node's scene path. The editor draws the new subtree,
+ * the receipt says ok, and SaveScene packs the node as
+ * `instance=ExtResource(<old scene>)` with a fresh unique_id — the change is
+ * gone on reload. A plain
+ * node replaced by a scene loses the other way (scene_file_path cleared, the
+ * instance's children owned by the instance root and dropped on save), and a
+ * type change of an instanced node stays an instance of the old scene.
+ *
+ * So the scene branch (and a type change of an instanced node) runs as:
+ *   0. SaveScene, so the file on disk is exactly the editor state;
+ *   1. read + parse the saved .tscn (which children the scene added under the
+ *      node, which properties it overrides, its sibling index);
+ *   2. InstantiateScene / AddNode at the same parent under a temporary name;
+ *   3. SetProp every copyable property override (transform, visibility, ...);
+ *   4. ReparentNode each scene-added child onto the new node (local
+ *      transforms kept), then re-parent each deeper scene-added descendant in
+ *      place — the engine's ReparentNode re-owns only the node it moves, and
+ *      remove_child clears the owner of everything below it;
+ *   5. MoveNode to the old sibling index, RemoveNode the old node, SetProp
+ *      name back to the original name;
+ *   6. SaveScene, read the file back and check it: the node at the path
+ *      instances the new scene (or has the new type), the parent and every
+ *      scene-added descendant are there. persisted:false is reported as a
+ *      failure, never as success.
+ * A type change of a plain node keeps the engine's ReplaceNode (it persists:
+ * replace_by copies an empty scene path) and gets the same read-back check.
+ */
+import { z } from "zod";
+import { resolveSingleOnlyOps, missingEngineOpResult } from "../capability-skew.js";
+import { ToolInputError } from "../tool-errors.js";
+import { asRecord } from "../util/json.js";
+import { executeOpsChunked, safeProjectPath, sceneMutationOps } from "./engine-ops.js";
+import { extractOpError } from "./engine-receipt.js";
+import { REPLACE_NODE_FALLBACK } from "./engine-fallbacks.js";
+import { reownInPlaceOps } from "./scene-batch.js";
+import { isReadbackFailure, readSavedScene as readSceneFile, readbackFailure } from "./scene-readback.js";
+import { decodeGodotString, extResourceId, findTscnNode, isAtOrBelow, isSceneCreatedNode, joinNodePath, normalizeNodePath, normalizeResPath, quotedLiteral, } from "./tscn.js";
+// Mirrors library/tools/replace-node/resource.yaml input_schema (parity-tested).
+export const replaceNodeInputShape = {
+    scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
+    path: z.string().describe("Node path to replace, e.g. './House3/Front/G_f2_door'"),
+    type: z.string().optional().describe("New node type, e.g. 'RigidBody3D'. Give exactly one of type or scene."),
+    scene: z
+        .string()
+        .optional()
+        .describe("Scene or model to replace with, e.g. 'res://kit/wall_door_02.tscn'. Give exactly one of type or scene."),
+};
+export const replaceNodeInputSchema = z.object(replaceNodeInputShape).strict();
+const failure = readbackFailure;
+const isFailure = isReadbackFailure;
+const TOO_LARGE_HINT = "Replace by hand: summer_remove_node, then summer_instantiate_scene with the same parent and name, then summer_set_prop for the transform.";
+const readSavedScene = (client, scenePath) => readSceneFile(client, scenePath, TOO_LARGE_HINT);
+/** Per-op results of a (possibly chunked) receipt. */
+function opResults(receipt) {
+    const results = asRecord(receipt)?.results;
+    return Array.isArray(results) ? results.filter((r) => asRecord(r)) : [];
+}
+/** Live child names of `nodePath`, in tree order, from a targeted scene read
+ *  rooted at that node; null when the engine cannot answer (an older build
+ *  ignores `root` and answers the scene root instead — detected by path). */
+async function readLiveChildren(client, scenePath, nodePath) {
+    try {
+        const state = asRecord(await client.getSceneState(scenePath, { root: nodePath, depth: 1, limit: 100_000 }));
+        if (!state || state.ok === false)
+            return null;
+        const data = asRecord(state.data);
+        if (!data || normalizeNodePath(String(data.path ?? "")) !== nodePath)
+            return null;
+        if (!Array.isArray(data.children))
+            return null;
+        return data.children.map((child) => String(asRecord(child)?.name ?? ""));
+    }
+    catch {
+        return null;
+    }
+}
+/** A property override as a SetProp value, or why it cannot be copied. */
+export function propSetValue(prop, parsed) {
+    const raw = prop.value.trim();
+    if (/\bSubResource\(/.test(raw)) {
+        return { reason: "scene-local sub_resource: it cannot be copied by reference; set it again on the new node" };
+    }
+    const ext = extResourceId(raw);
+    if (ext !== undefined) {
+        const path = parsed.extResources.get(ext)?.path;
+        return path ? { value: path } : { reason: `ext_resource ${ext} is not listed in the scene file` };
+    }
+    if (/\bExtResource\(/.test(raw))
+        return { reason: "the value embeds resource references; set it again on the new node" };
+    if (raw === "true")
+        return { value: true };
+    if (raw === "false")
+        return { value: false };
+    if (/^-?\d+(?:\.\d+)?(?:e[-+]?\d+)?$/i.test(raw))
+        return { value: Number(raw) };
+    const text = quotedLiteral(raw);
+    if (text !== undefined)
+        return { value: text };
+    const nodePath = /^NodePath\("((?:[^"\\]|\\.)*)"\)$/.exec(raw);
+    if (nodePath)
+        return { value: decodeGodotString(nodePath[1]) };
+    // Godot literal text (Transform3D(...), Vector3(...), Color(...), arrays,
+    // dictionaries): SetProp parses it with str_to_var.
+    return { value: raw };
+}
+function tempName(base, taken) {
+    const stem = `${base}_SummerReplace`;
+    let name = stem;
+    for (let i = 2; taken.has(name); i++)
+        name = `${stem}${i}`;
+    return name;
+}
+function siblingIndexInFile(parsed, node) {
+    return parsed.nodes.filter((n) => n.parent === node.parent && n.order < node.order).length;
+}
+function describeNode(node) {
+    if (node.instancePath)
+        return node.instancePath;
+    if (node.instance)
+        return `ExtResource("${node.instance}")`;
+    return `type ${node.type ?? "?"}`;
+}
+function verifyAgainstSaved(after, plan) {
+    const problems = [];
+    const warnings = [];
+    const node = findTscnNode(after, plan.target);
+    const saved = { read_back: plan.scenePath };
+    if (!node) {
+        problems.push(`the saved file has no node at ${plan.target}`);
+    }
+    else {
+        saved.node = describeNode(node);
+        saved.parent = node.parent;
+        if (plan.scene !== undefined) {
+            if (!node.instance) {
+                problems.push(`the saved node is a plain ${node.type ?? "node"}, not an instance of ${plan.scene}`);
+            }
+            else if (normalizeResPath(node.instancePath ?? "") !== normalizeResPath(plan.scene)) {
+                problems.push(`the saved node still instances ${describeNode(node)}, not ${plan.scene}`);
+            }
+        }
+        else if (node.instance) {
+            problems.push(`the saved node is still an instance of ${describeNode(node)}`);
+        }
+        else if (node.type !== plan.type) {
+            problems.push(`the saved node has type ${node.type ?? "?"}, not ${plan.type}`);
+        }
+        if (node.parent !== plan.parent) {
+            problems.push(`the saved node's parent is ${node.parent ?? "(none)"}, not ${plan.parent ?? "(none)"}`);
+        }
+        const index = siblingIndexInFile(after, node);
+        saved.index = index;
+        if (index !== plan.fileIndex) {
+            warnings.push(`sibling order changed: index ${index} among the saved siblings, was ${plan.fileIndex}`);
+        }
+        if (plan.oldTransform !== undefined) {
+            const now = node.props.find((p) => p.key === "transform")?.value;
+            const squash = (s) => s.replace(/\s+/g, "");
+            if (now === undefined) {
+                warnings.push("the saved node lists no transform override (it now uses the new scene's own root transform); check its placement");
+            }
+            else if (squash(now) !== squash(plan.oldTransform)) {
+                warnings.push(`the saved transform differs from the old one: ${now} (was ${plan.oldTransform})`);
+            }
+        }
+    }
+    const missing = plan.keptNodes
+        .filter((kept) => !after.nodes.some((n) => n.path === kept.path && isSceneCreatedNode(n)))
+        .map((kept) => kept.path);
+    if (missing.length > 0)
+        problems.push(`children missing from the saved file: ${missing.join(", ")}`);
+    return { persisted: problems.length === 0, problems, warnings, saved };
+}
+function notPersistedFailure(plan, verification, extra) {
+    return failure("not_persisted", `summer_replace_node did NOT persist (persisted:false): ${verification.problems.join("; ")}. ` +
+        `The editor may show the change, but ${plan.scenePath} on disk does not, so it reverts on reload. Do not report it as done: ` +
+        "inspect the saved file (summer_read_file), then redo it with summer_remove_node + summer_instantiate_scene (same parent and name) + summer_set_prop transform.", { persisted: false, verified: false, scenePath: plan.scenePath, path: plan.target, verification: { ...verification.saved, problems: verification.problems, warnings: verification.warnings }, ...extra });
+}
+/** summer_batch guard (both faces): a raw ReplaceNode with `scene` is the op
+ *  that saves the OLD scene reference. Refuse it before anything is sent and
+ *  point at the tool that persists. Null when the ops are fine. */
+export function rawSceneReplaceRefusal(ops) {
+    const raw = ops.find((op) => op.op === "ReplaceNode" && typeof op.scene === "string" && op.scene.trim() !== "");
+    if (!raw)
+        return null;
+    return ("summer_batch does not send a raw ReplaceNode with scene: on current engines it shows the new scene in the editor but saves the OLD scene reference, " +
+        "so the change reverts on reload. Nothing was sent. Use summer_replace_node (it verifies the saved file), or RemoveNode + InstantiateScene.");
+}
+/**
+ * Replace the node at `path` in `scenePath` with `scene` (or a node of
+ * `type`) and prove the saved file holds the result.
+ */
+export async function replaceNodePersisted(client, args) {
+    const scenePath = safeProjectPath(args.scenePath);
+    if (!scenePath.endsWith(".tscn")) {
+        throw new ToolInputError("summer_replace_node verifies the result in the saved text scene, so scenePath must be a .tscn file. For a binary .scn use summer_remove_node + summer_instantiate_scene.");
+    }
+    const type = args.type?.trim() || undefined;
+    const scene = args.scene?.trim() ? safeProjectPath(args.scene) : undefined;
+    if ((type === undefined) === (scene === undefined)) {
+        throw new ToolInputError("Give exactly one of type (a node class) or scene (a res:// scene or model path).");
+    }
+    if (type !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(type)) {
+        throw new ToolInputError(`Invalid type "${type}": pass a plain node class name such as 'RigidBody3D'.`);
+    }
+    const target = normalizeNodePath(args.path);
+    const singleOnly = resolveSingleOnlyOps(client);
+    const send = (ops, options = {}) => executeOpsChunked((chunk) => client.executeIdentityBoundOps(chunk, { groupUndo: true, ...options, scenePath }), ops, singleOnly);
+    // 0. Save first: the plan is read from the file, so the file must be the editor state.
+    const preSave = await send([{ op: "SaveScene" }]);
+    if (extractOpError(preSave))
+        return asRecord(preSave) ?? { ok: false, error: "SaveScene failed" };
+    // 1. Read the scene as saved.
+    const before = await readSavedScene(client, scenePath);
+    if (isFailure(before))
+        return before;
+    const node = findTscnNode(before.parsed, target);
+    if (!node) {
+        return failure("node_not_found", `No node at "${target}" in ${scenePath} (paths are relative to the scene root, e.g. "World/Door"). Nothing was replaced; read the hierarchy with summer_get_scene_tree.`);
+    }
+    const keptNodes = before.parsed.nodes.filter((n) => n !== node && isAtOrBelow(n.path, target) && isSceneCreatedNode(n));
+    const plan = {
+        scenePath,
+        target,
+        parent: node.parent,
+        ...(scene !== undefined ? { scene } : {}),
+        ...(type !== undefined ? { type } : {}),
+        keptNodes,
+        fileIndex: siblingIndexInFile(before.parsed, node),
+    };
+    const from = describeNode(node);
+    // A type change of a plain node: the engine op persists. Verify it anyway.
+    if (type !== undefined && !node.instance && !node.instancePlaceholder) {
+        const receipt = await send(sceneMutationOps([{ op: "ReplaceNode", path: args.path, type }]));
+        if (extractOpError(receipt))
+            return asRecord(receipt) ?? { ok: false, error: "ReplaceNode failed" };
+        const after = await readSavedScene(client, scenePath);
+        if (isFailure(after))
+            return { ...after, applied: true, note: "ReplaceNode and SaveScene reported success, but the saved file could not be read back to verify it." };
+        const verification = verifyAgainstSaved(after.parsed, plan);
+        const extra = { method: "engine_replace_node", replaced: { from, to: `type ${type}` } };
+        if (!verification.persisted)
+            return notPersistedFailure(plan, verification, extra);
+        return {
+            ok: true,
+            persisted: true,
+            verified: true,
+            scenePath,
+            path: target,
+            ...extra,
+            verification: { ...verification.saved, ...(verification.warnings.length ? { warnings: verification.warnings } : {}) },
+        };
+    }
+    if (node.parent === null) {
+        return failure("root_not_supported", `"${target}" is the scene root. Replacing the root with ${scene ?? `type ${type}`} cannot be expressed as instantiate-and-remove; ` +
+            "create a new scene instead (summer_create_scene), or change the root's own properties.");
+    }
+    const parent = node.parent;
+    // Capability pre-flight for every op this path sends.
+    for (const op of [scene !== undefined ? "InstantiateScene" : "AddNode", "SetProp", "ReparentNode", "MoveNode", "RemoveNode"]) {
+        const missing = missingEngineOpResult(client, op, REPLACE_NODE_FALLBACK);
+        if (missing)
+            return { ...missing };
+    }
+    // What the new node takes over, and what cannot travel.
+    const props = [];
+    const notCopied = [];
+    for (const prop of node.props) {
+        const converted = propSetValue(prop, before.parsed);
+        if ("value" in converted)
+            props.push({ key: prop.key, value: converted.value });
+        else
+            notCopied.push({ key: prop.key, reason: converted.reason });
+    }
+    const oldTransform = node.props.find((p) => p.key === "transform")?.value;
+    if (oldTransform !== undefined)
+        plan.oldTransform = oldTransform;
+    const directChildren = keptNodes.filter((n) => n.parent === target);
+    const deeper = keptNodes
+        .filter((n) => n.parent !== target)
+        .sort((a, b) => a.order - b.order)
+        .map((n) => n.path);
+    // Overrides of nodes the OLD instance creates (no type/instance, nearest
+    // scene-created ancestor is the old node) belong to the old scene and go.
+    const droppedOverrides = before.parsed.nodes
+        .filter((n) => !isSceneCreatedNode(n) && isAtOrBelow(n.path, target) && n !== node)
+        .filter((n) => !keptNodes.some((k) => n.path.startsWith(`${k.path}/`)))
+        .map((n) => n.path);
+    const editableDropped = before.parsed.editable.includes(target);
+    const connections = before.parsed.connections.filter((c) => c.from === target || c.to === target);
+    const notCarriedOver = {
+        ...(notCopied.length ? { props: notCopied } : {}),
+        ...(node.groups.length ? { groups: node.groups } : {}),
+        ...(connections.length
+            ? { connections: connections.map((c) => `${c.from}:${c.signal} -> ${c.to}:${c.method}`) }
+            : {}),
+        ...(droppedOverrides.length ? { overrides_of_old_scene_nodes: droppedOverrides } : {}),
+        ...(editableDropped ? { editable_children: true } : {}),
+    };
+    // 2. Create the replacement next to the old node under a temporary name.
+    const siblingNames = new Set(before.parsed.nodes.filter((n) => n.parent === parent).map((n) => n.name));
+    const liveSiblings = await readLiveChildren(client, scenePath, parent);
+    for (const name of liveSiblings ?? [])
+        siblingNames.add(name);
+    const tmp = tempName(node.name, siblingNames);
+    const createOp = scene !== undefined
+        ? { op: "InstantiateScene", parent, scene, name: tmp }
+        : { op: "AddNode", parent, type: type, name: tmp };
+    const created = await send([createOp]);
+    if (extractOpError(created)) {
+        return { ...(asRecord(created) ?? {}), ok: false, note: `Nothing was replaced: creating the new node failed. ${scenePath} is unchanged.` };
+    }
+    const createdMeta = asRecord(opResults(created)[0]?.meta);
+    const newPath = normalizeNodePath(typeof createdMeta?.nodePath === "string" && createdMeta.nodePath ? createdMeta.nodePath : joinNodePath(parent, tmp));
+    // Remove the temporary node again (nothing else was changed yet).
+    const rollbackNew = async (reason, message) => {
+        const undo = await send([{ op: "RemoveNode", path: newPath }]);
+        const rolledBack = !extractOpError(undo);
+        return failure(reason, rolledBack
+            ? `${message} The temporary node was removed again; the old node is untouched and ${scenePath} on disk is unchanged.`
+            : `${message} Removing the temporary node ${newPath} also failed: remove it with summer_remove_node. ${scenePath} on disk is unchanged (not saved).`, { persisted: false, rolled_back: rolledBack });
+    };
+    // Children of the new scene that would collide with the moved children.
+    const newChildren = await readLiveChildren(client, scenePath, newPath);
+    if (newChildren) {
+        const clashes = directChildren.filter((c) => newChildren.includes(c.name)).map((c) => c.name);
+        if (clashes.length > 0) {
+            return rollbackNew("child_name_collision", `The new ${scene ?? `type ${type}`} already has children named ${clashes.join(", ")}, the same names as children added under ${target}; ` +
+                "moving them would rename them. Rename those children first (summer_set_prop name), then retry.");
+        }
+    }
+    // Live sibling index of the old node (an instanced or inherited parent has
+    // children the file does not list).
+    const liveIndex = liveSiblings ? liveSiblings.indexOf(node.name) : -1;
+    const oldIndex = liveIndex >= 0 ? liveIndex : plan.fileIndex;
+    // 3. Property overrides (each attempted; a failure is reported, not fatal).
+    const propsCopied = [];
+    if (props.length > 0) {
+        const receipt = await send(props.map((p) => ({ op: "SetProp", path: newPath, key: p.key, value: p.value })), { stopOnError: false });
+        const results = opResults(receipt);
+        props.forEach((p, i) => {
+            const r = results[i];
+            if (r && r.ok !== false)
+                propsCopied.push(p.key);
+            else
+                notCopied.push({ key: p.key, reason: String(r?.error ?? "SetProp failed") });
+        });
+        if (notCopied.length)
+            notCarriedOver.props = notCopied;
+    }
+    // 4 + 5. Move children, restore ownership below them, take the old slot, drop the old node, take its name.
+    const rebase = (path) => (path === target ? newPath : `${newPath}${path.slice(target.length)}`);
+    const structure = [
+        ...directChildren.map((c) => ({ op: "ReparentNode", path: c.path, new_parent_path: newPath, keep_global_transform: false })),
+        ...reownInPlaceOps(deeper, rebase),
+        { op: "MoveNode", path: newPath, new_index: oldIndex },
+        { op: "RemoveNode", path: target },
+        { op: "SetProp", path: newPath, key: "name", value: node.name },
+    ];
+    const moved = await send(structure);
+    if (extractOpError(moved)) {
+        const results = opResults(moved);
+        const applied = results.filter((r) => r.ok !== false).length;
+        const removedOld = results.some((r, i) => r.ok !== false && structure[i]?.op === "RemoveNode");
+        if (applied === 0) {
+            return rollbackNew("replace_failed", `Replacement stopped before anything moved: ${extractOpError(moved)}.`);
+        }
+        return failure("replace_partially_applied", `summer_replace_node stopped after ${applied} of ${structure.length} steps: ${extractOpError(moved)}. ` +
+            `Applied in the editor only, NOT saved (${scenePath} on disk still holds the original node). ` +
+            (removedOld
+                ? `The old node is gone and the new one is at ${newPath}: rename it with summer_set_prop name "${node.name}", then summer_save_scene.`
+                : `The new node is at ${newPath} next to the old one: undo with Ctrl+Z in the editor, or move the children back and remove ${newPath}.`), { persisted: false, applied_steps: structure.slice(0, applied).map((op) => String(op.op)) });
+    }
+    // 6. Save, then read the file back and check it.
+    const saved = await send([{ op: "SaveScene" }]);
+    if (extractOpError(saved)) {
+        return {
+            ...(asRecord(saved) ?? {}),
+            ok: false,
+            persisted: false,
+            note: `The replacement is applied in the editor but SaveScene failed, so ${scenePath} on disk still holds the original node. Fix the save error, then call summer_save_scene.`,
+        };
+    }
+    const after = await readSavedScene(client, scenePath);
+    if (isFailure(after))
+        return { ...after, persisted: false, note: "The replacement was applied and saved, but the file could not be read back to verify it." };
+    const verification = verifyAgainstSaved(after.parsed, plan);
+    const extra = {
+        method: "instantiate_move_remove",
+        replaced: { from, to: scene ?? `type ${type}` },
+        ...(directChildren.length ? { moved_children: directChildren.map((c) => c.name) } : {}),
+        ...(propsCopied.length ? { props_copied: propsCopied } : {}),
+        ...(Object.keys(notCarriedOver).length ? { not_carried_over: notCarriedOver } : {}),
+    };
+    if (!verification.persisted)
+        return notPersistedFailure(plan, verification, extra);
+    const warnings = [...verification.warnings];
+    if (Object.keys(notCarriedOver).length) {
+        warnings.push("Some state of the old node did not carry over (see not_carried_over): re-apply what is still wanted.");
+    }
+    return {
+        ok: true,
+        persisted: true,
+        verified: true,
+        scenePath,
+        path: target,
+        ...extra,
+        verification: verification.saved,
+        ...(warnings.length ? { warnings } : {}),
+        undo: "Sent as separate engine requests: undoing it in the editor takes one Ctrl+Z per step (create, properties, move/remove).",
+    };
+}

package/dist/core/capabilities/runtime-control.d.ts

@@ -186,18 +186,18 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
     instance?: string | undefined;
     name?: string | undefined;
     value?: string | number | boolean | undefined;
+    cmd?: "pause" | "play" | "stop" | "state" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
+    space?: "local" | "global" | "both" | undefined;
     blend?: number | undefined;
     state?: string | undefined;
     position?: number | undefined;
     speed?: number | undefined;
     bones?: string[] | undefined;
-    cmd?: "pause" | "play" | "stop" | "state" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     from_end?: boolean | undefined;
     update?: boolean | undefined;
     reset?: boolean | undefined;
     param?: string | undefined;
     playback_path?: string | undefined;
-    space?: "local" | "global" | "both" | undefined;
     include_rest?: boolean | undefined;
 }, {
     path: string;
@@ -205,18 +205,18 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
     instance?: string | undefined;
     name?: string | undefined;
     value?: string | number | boolean | undefined;
+    cmd?: "pause" | "play" | "stop" | "state" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
+    space?: "local" | "global" | "both" | undefined;
     blend?: number | undefined;
     state?: string | undefined;
     position?: number | undefined;
     speed?: number | undefined;
     bones?: string[] | undefined;
-    cmd?: "pause" | "play" | "stop" | "state" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     from_end?: boolean | undefined;
     update?: boolean | undefined;
     reset?: boolean | undefined;
     param?: string | undefined;
     playback_path?: string | undefined;
-    space?: "local" | "global" | "both" | undefined;
     include_rest?: boolean | undefined;
 }>;
 export type RuntimeAnimateArgs = z.infer<typeof runtimeAnimateArgsSchema>;
@@ -473,6 +473,9 @@ export declare const playGameExtensionSchema: {
     fixed_fps: z.ZodOptional<z.ZodNumber>;
     time_scale: z.ZodOptional<z.ZodNumber>;
     speed: z.ZodOptional<z.ZodNumber>;
+    players: z.ZodOptional<z.ZodNumber>;
+    spectators: z.ZodOptional<z.ZodNumber>;
+    queue: z.ZodOptional<z.ZodString>;
     focus: z.ZodOptional<z.ZodBoolean>;
 };
 export interface PlayGameArgs {
@@ -486,7 +489,13 @@ export interface PlayGameArgs {
     speed?: number;
     /** true = today's toolbar-style launch (Game tab + focus). Absent/false = quiet. */
     focus?: boolean;
+    /** Local Play: headless authority + this many clients (0 = one ordinary run). */
+    players?: number;
+    spectators?: number;
+    queue?: string;
 }
+/** True when the caller asked for Local Play parameters at all. */
+export declare function playRequestsLocalPlay(args: PlayGameArgs): boolean;
 /**
  * Quiet is the default whenever an agent drives play — both faces of this tool
  * (MCP and `summer tool`) ARE agent faces, so the only way to a focus-stealing
@@ -510,6 +519,13 @@ export declare function buildStopGameOp(instance: string): BuiltRuntimeOp;
  * believe a parallel instance is up.
  */
 export declare function withPlayInstanceEcho(result: unknown, args: PlayGameArgs): unknown;
+export declare const PLAY_LOCAL_PLAY_NOT_SUPPORTED = "This Summer Engine build did not echo `local_play` in its PlayGame result \u2014 it predates Local Play and started ONE ordinary client, not a local authority plus the requested players. Update to an engine with Local Play (SummerEngine main after PR #415; restart it after updating).";
+/**
+ * Local Play was requested with players > 0: an engine with Local Play echoes
+ * `local_play` (applied, or applied:false with a reason). No echo means an
+ * engine that ignored the keys and ran one client — say so.
+ */
+export declare function withLocalPlayEcho(result: unknown, args: PlayGameArgs): unknown;
 export declare const PLAY_QUIET_NOT_SUPPORTED = "This Summer Engine build did not echo `agent_quiet` in its PlayGame result \u2014 it predates quiet play and has most likely switched the editor to the Game tab and taken focus. Update Summer Engine (restart it after updating) for launches that leave the user's screen alone.";
 /**
  * Quiet was requested: the engine echoes `agent_quiet` when it understood the

package/dist/core/capabilities/runtime-control.js

@@ -853,11 +853,32 @@ export const playGameExtensionSchema = {
         .number()
         .optional()
         .describe("User time scale applied on session start, (0, 100] — e.g. 0.5 for half speed."),
+    players: z
+        .number()
+        .int()
+        .min(0)
+        .max(64)
+        .optional()
+        .describe("Local Play for a Summer multiplayer game (engine with Local Play): start the game's authority headless plus this many clients on this machine, each joining through the game's own Summer.client.join. The scenes and queue come from the project's summer.build.json WorldDefinition; no account, Docker or game flags are needed. Omit it and pass queue to start the queue's minPlayers from summer.build.json; 0 forces one ordinary run. The result's local_play block lists every process and persona, plus warnings when the roster is outside the queue's minPlayers..maxPlayers."),
+    spectators: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Local Play: also start this many spectator clients (only with players)."),
+    queue: z
+        .string()
+        .optional()
+        .describe("Local Play: the summer.build.json queue the local World stands in for (default: the first declared queue)."),
     focus: z
         .boolean()
         .optional()
         .describe("Default false = QUIET play (PlayGame agent:true): the editor does not switch to the Game tab or grab focus for the embedded game, so the user keeps working. Pass true to launch the way the toolbar Play button does (Game tab + focus) — only when the user is watching and asked to see it."),
 };
+/** True when the caller asked for Local Play parameters at all. */
+export function playRequestsLocalPlay(args) {
+    return args.players !== undefined || args.spectators !== undefined || args.queue !== undefined;
+}
 /**
  * Quiet is the default whenever an agent drives play — both faces of this tool
  * (MCP and `summer tool`) ARE agent faces, so the only way to a focus-stealing
@@ -881,7 +902,8 @@ export function playNeedsOp(args) {
         args.seed !== undefined ||
         args.fixed_fps !== undefined ||
         args.time_scale !== undefined ||
-        args.speed !== undefined);
+        args.speed !== undefined ||
+        playRequestsLocalPlay(args));
 }
 /** True when the call addresses a non-main instance or an offscreen mode —
  *  the part of PlayGame that only a runtime-control engine understands. */
@@ -914,6 +936,26 @@ export function buildPlayGameOp(args) {
     if (args.speed !== undefined && (typeof args.speed !== "number" || !Number.isFinite(args.speed) || args.speed <= 0 || args.speed > 100)) {
         throw new ToolInputError("speed must be a number in (0, 100].");
     }
+    if (playRequestsLocalPlay(args)) {
+        if (args.players !== undefined && (!isInt(args.players) || args.players < 0 || args.players > 64)) {
+            throw new ToolInputError("players must be an integer 0..64 (0 forces one ordinary run).");
+        }
+        if (args.spectators !== undefined && (!isInt(args.spectators) || args.spectators < 0)) {
+            throw new ToolInputError("spectators must be an integer >= 0.");
+        }
+        if ((args.players ?? 0) + (args.spectators ?? 0) > 64) {
+            throw new ToolInputError("players + spectators must be at most 64.");
+        }
+        if (args.spectators !== undefined && args.spectators > 0 && args.players === 0) {
+            throw new ToolInputError("spectators need players > 0.");
+        }
+        if (args.queue !== undefined && (typeof args.queue !== "string" || args.queue.trim().length === 0)) {
+            throw new ToolInputError("queue must be a queue name declared in summer.build.json.");
+        }
+        if (instance.length > 0 && instance !== "main") {
+            throw new ToolInputError("Local Play (players/spectators/queue) runs the editor's main game; it does not combine with an offscreen instance.");
+        }
+    }
     const op = { op: "PlayGame" };
     if (typeof args.scene === "string" && args.scene.trim().length > 0)
         op.scene = args.scene.trim();
@@ -935,6 +977,12 @@ export function buildPlayGameOp(args) {
         op.time_scale = args.time_scale;
     if (args.speed !== undefined)
         op.speed = args.speed;
+    if (args.players !== undefined)
+        op.players = args.players;
+    if (args.spectators !== undefined)
+        op.spectators = args.spectators;
+    if (args.queue !== undefined)
+        op.queue = args.queue.trim();
     return { kind: "PlayGame", op, timeoutMs: PLAY_INSTANCE_TIMEOUT_MS };
 }
 export function buildStopGameOp(instance) {
@@ -963,6 +1011,23 @@ export function withPlayInstanceEcho(result, args) {
         warning: `This Summer Engine build did not echo \`instance\` in its PlayGame result — it predates instance-aware play and has most likely started the MAIN embedded game, ignoring instance:'${args.instance ?? ""}' / mode:'${args.mode ?? "embedded"}'. Verify with summer_is_running or summer_game_control action:'instances' before addressing that instance, and update Summer Engine for parallel instances.`,
     };
 }
+export const PLAY_LOCAL_PLAY_NOT_SUPPORTED = "This Summer Engine build did not echo `local_play` in its PlayGame result — it predates Local Play and started ONE ordinary client, not a local authority plus the requested players. Update to an engine with Local Play (SummerEngine main after PR #415; restart it after updating).";
+/**
+ * Local Play was requested with players > 0: an engine with Local Play echoes
+ * `local_play` (applied, or applied:false with a reason). No echo means an
+ * engine that ignored the keys and ran one client — say so.
+ */
+export function withLocalPlayEcho(result, args) {
+    if (!playRequestsLocalPlay(args) || args.players === 0 || !result || typeof result !== "object")
+        return result;
+    if (extractOpError(result))
+        return result;
+    const envelope = result;
+    const payload = envelope.results?.[0] ?? envelope;
+    if (payload.local_play && typeof payload.local_play === "object")
+        return result;
+    return { ...envelope, local_play_note: PLAY_LOCAL_PLAY_NOT_SUPPORTED };
+}
 export const PLAY_QUIET_NOT_SUPPORTED = "This Summer Engine build did not echo `agent_quiet` in its PlayGame result — it predates quiet play and has most likely switched the editor to the Game tab and taken focus. Update Summer Engine (restart it after updating) for launches that leave the user's screen alone.";
 /**
  * Quiet was requested: the engine echoes `agent_quiet` when it understood the
@@ -1007,5 +1072,5 @@ export async function playGame(client, args) {
             return missing;
     }
     const result = await client.executeOps([op], undefined, timeoutMs);
-    return withPlayPostureEcho(withPlayInstanceEcho(withRuntimeFailureHints(withOldEngineHint(result, "PlayGame", PLAY_INSTANCE_FALLBACK)), args), args);
+    return withLocalPlayEcho(withPlayPostureEcho(withPlayInstanceEcho(withRuntimeFailureHints(withOldEngineHint(result, "PlayGame", PLAY_INSTANCE_FALLBACK)), args), args), args);
 }