summer-engine 3.1.0 → 3.2.0

package/dist/core/capabilities/inspect-node.d.ts

@@ -0,0 +1,56 @@
+/**
+ * inspect-node — ONE implementation of `summer_inspect_node` for both faces
+ * (src/mcp/tools/scene-tools.ts and tool-dispatch.ts).
+ *
+ * The engine's state:inspector returns every editor-visible property of a
+ * node (StateProvider::inspector_state) — about 5 KB to read one transform.
+ * `fields` keeps only the named properties (globs allowed) and adds a few
+ * derived fields the inspector cannot give:
+ *   transform        local position / rotation_degrees / scale (+ Transform3D
+ *                    literal for 3D nodes);
+ *   global_transform world origin/basis composed down the ancestor chain from
+ *                    the world snapshot's local pos/rot_deg/scale;
+ *   scene_file_path  the res:// scene the node instances (world snapshot);
+ *   aabb             the node's world AABB (world snapshot);
+ *   warnings         the node's configuration warnings.
+ * The world snapshot is read only when one of its fields is asked for.
+ */
+import { z } from "zod";
+import { type CapabilityAdvertisingClient } from "../capability-skew.js";
+import { type JsonRecord } from "../util/json.js";
+import { basisFromEulerScale, parseVec3, type Vec3 } from "./math3d.js";
+export { basisFromEulerScale, parseVec3 };
+export declare const INSPECT_NODE_DERIVED_FIELDS: readonly string[];
+export declare const inspectNodeInputShape: {
+    path: z.ZodString;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+};
+export declare const inspectNodeInputSchema: z.ZodObject<{
+    path: z.ZodString;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    path: string;
+    fields?: string[] | undefined;
+}, {
+    path: string;
+    fields?: string[] | undefined;
+}>;
+export type InspectNodeArgs = z.infer<typeof inspectNodeInputSchema>;
+export interface InspectNodeClient extends CapabilityAdvertisingClient {
+    inspectNode(path: string): Promise<unknown>;
+    executeOps(ops: Record<string, unknown>[], options?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+}
+export interface SnapshotNode {
+    pos?: Vec3;
+    rot?: Vec3;
+    scale?: Vec3;
+    entry: JsonRecord;
+}
+/** World transform of a Node3D: its local transform composed with every
+ *  Node3D directly above it. A Node3D's parent space ends at the first
+ *  ancestor that is not a Node3D (a plain Node or a CanvasItem — the snapshot
+ *  lists CanvasItems only with include_2d), as in Godot. */
+export declare function globalTransform(index: Map<string, SnapshotNode>, path: string): JsonRecord | {
+    error: string;
+};
+export declare function inspectNodeFields(client: InspectNodeClient, args: InspectNodeArgs): Promise<unknown>;

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

@@ -0,0 +1,225 @@
+/**
+ * inspect-node — ONE implementation of `summer_inspect_node` for both faces
+ * (src/mcp/tools/scene-tools.ts and tool-dispatch.ts).
+ *
+ * The engine's state:inspector returns every editor-visible property of a
+ * node (StateProvider::inspector_state) — about 5 KB to read one transform.
+ * `fields` keeps only the named properties (globs allowed) and adds a few
+ * derived fields the inspector cannot give:
+ *   transform        local position / rotation_degrees / scale (+ Transform3D
+ *                    literal for 3D nodes);
+ *   global_transform world origin/basis composed down the ancestor chain from
+ *                    the world snapshot's local pos/rot_deg/scale;
+ *   scene_file_path  the res:// scene the node instances (world snapshot);
+ *   aabb             the node's world AABB (world snapshot);
+ *   warnings         the node's configuration warnings.
+ * The world snapshot is read only when one of its fields is asked for.
+ */
+import { z } from "zod";
+import { missingEngineOpResult } from "../capability-skew.js";
+import { asRecord } from "../util/json.js";
+import { annotateVariantTypes } from "./variant-types.js";
+import { extractOpError } from "./engine-receipt.js";
+import { WORLD_SNAPSHOT_FALLBACK } from "./engine-fallbacks.js";
+import { normalizeNodePath, parentNodePath } from "./tscn.js";
+import { applyMat3 as apply, basisFromEulerScale, IDENTITY3, mulMat3 as mul, parseVec3, transformLiteral, vec3Literal, } from "./math3d.js";
+export { basisFromEulerScale, parseVec3 };
+export const INSPECT_NODE_DERIVED_FIELDS = [
+    "transform",
+    "global_transform",
+    "scene_file_path",
+    "aabb",
+    "warnings",
+];
+const SNAPSHOT_FIELDS = new Set(["global_transform", "scene_file_path", "aabb"]);
+// Mirrors library/tools/inspect-node/resource.yaml input_schema (parity-tested).
+export const inspectNodeInputShape = {
+    path: z.string().describe("Node path from scene tree, e.g. 'Player', 'World/Enemies/Boss', 'DirectionalLight3D'"),
+    fields: z
+        .array(z.string())
+        .max(48)
+        .optional()
+        .describe("Only these fields: property names or globs (e.g. 'position', 'surface_material_override/*') and the derived fields transform, global_transform, scene_file_path, aabb, warnings. Omit for every property."),
+};
+export const inspectNodeInputSchema = z.object(inspectNodeInputShape).strict();
+// ---------------------------------------------------------------------------
+function propsOf(payload) {
+    const data = asRecord(asRecord(payload)?.data);
+    const props = data?.props;
+    return Array.isArray(props) ? props.filter((p) => asRecord(p)) : [];
+}
+function globMatcher(pattern) {
+    if (!/[*?]/.test(pattern))
+        return (name) => name === pattern;
+    const regex = new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+    return (name) => regex.test(name);
+}
+function localTransformFromProps(props) {
+    const value = (name) => props.find((p) => p.name === name)?.value;
+    const position = parseVec3(value("position"));
+    const rotation = parseVec3(value("rotation"));
+    const scale = parseVec3(value("scale"));
+    if (position && rotation && scale) {
+        const rotDeg = rotation.map((r) => (r * 180) / Math.PI);
+        const out = {
+            position: vec3Literal(position),
+            rotation_degrees: vec3Literal(rotDeg),
+            scale: vec3Literal(scale),
+            source: "inspector (rotation read in radians at 3 decimals)",
+        };
+        const order = value("rotation_order");
+        if (order === undefined || order === 2)
+            out.transform = transformLiteral(basisFromEulerScale(rotDeg, scale), position);
+        else
+            out.rotation_order = order;
+        return out;
+    }
+    // 2D / Control: report what the inspector has.
+    const out = {};
+    for (const name of ["position", "rotation", "scale", "skew", "size"]) {
+        const v = value(name);
+        if (v !== undefined)
+            out[name] = v;
+    }
+    return Object.keys(out).length > 0 ? { ...out, source: "inspector" } : null;
+}
+async function snapshotIndex(client) {
+    const missing = missingEngineOpResult(client, "GetWorldSnapshot", WORLD_SNAPSHOT_FALLBACK);
+    if (missing)
+        return { error: missing.error };
+    let result;
+    try {
+        result = await client.executeOps([{ op: "GetWorldSnapshot" }]);
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    const failure = extractOpError(result);
+    if (failure)
+        return { error: failure };
+    const root = asRecord(result);
+    const payload = Array.isArray(root?.nodes)
+        ? root
+        : asRecord((Array.isArray(root?.results) ? root.results : []).find((r) => asRecord(r)?.op === "GetWorldSnapshot"));
+    const nodes = Array.isArray(payload?.nodes) ? payload.nodes : null;
+    if (!nodes)
+        return { error: "the world snapshot returned no node list" };
+    const index = new Map();
+    for (const raw of nodes) {
+        const entry = asRecord(raw);
+        if (!entry || typeof entry.path !== "string")
+            continue;
+        index.set(normalizeNodePath(entry.path), {
+            pos: parseVec3(entry.pos) ?? undefined,
+            rot: parseVec3(entry.rot_deg) ?? undefined,
+            scale: parseVec3(entry.scale) ?? undefined,
+            entry,
+        });
+    }
+    return index;
+}
+function hasTransform(node) {
+    return !!node && !!node.pos && !!node.rot && !!node.scale;
+}
+/** World transform of a Node3D: its local transform composed with every
+ *  Node3D directly above it. A Node3D's parent space ends at the first
+ *  ancestor that is not a Node3D (a plain Node or a CanvasItem — the snapshot
+ *  lists CanvasItems only with include_2d), as in Godot. */
+export function globalTransform(index, path) {
+    const target = index.get(path);
+    if (!target)
+        return { error: `the world snapshot does not list ${path} (a 2D node, or the scene is larger than the snapshot cap)` };
+    if (!hasTransform(target))
+        return { error: `${path} is not a 3D node` };
+    const chain = [target];
+    for (let p = parentNodePath(path); p !== null; p = parentNodePath(p)) {
+        const node = index.get(p);
+        if (!hasTransform(node))
+            break;
+        chain.unshift(node);
+    }
+    let basis = IDENTITY3;
+    let origin = [0, 0, 0];
+    for (const node of chain) {
+        const local = basisFromEulerScale(node.rot, node.scale);
+        const moved = apply(basis, node.pos);
+        origin = [moved[0] + origin[0], moved[1] + origin[1], moved[2] + origin[2]];
+        basis = mul(basis, local);
+    }
+    return {
+        origin: vec3Literal(origin),
+        transform: transformLiteral(basis, origin),
+        source: "composed from the world snapshot's local pos/rot_deg/scale down the parent chain (YXZ Euler; top_level nodes not detected)",
+    };
+}
+export async function inspectNodeFields(client, args) {
+    const payload = annotateVariantTypes(await client.inspectNode(args.path));
+    if (!args.fields || args.fields.length === 0)
+        return payload;
+    if (extractOpError(payload))
+        return payload;
+    const root = asRecord(payload);
+    const data = asRecord(root?.data);
+    if (!root || !data)
+        return payload;
+    const props = propsOf(payload);
+    const requested = args.fields;
+    const derived = requested.filter((f) => INSPECT_NODE_DERIVED_FIELDS.includes(f));
+    const propPatterns = requested.filter((f) => !INSPECT_NODE_DERIVED_FIELDS.includes(f)).map(globMatcher);
+    const keptProps = props.filter((p) => propPatterns.some((match) => match(String(p.name ?? ""))));
+    const missing = requested
+        .filter((f) => !INSPECT_NODE_DERIVED_FIELDS.includes(f))
+        .filter((f) => !props.some((p) => globMatcher(f)(String(p.name ?? ""))));
+    const out = {
+        node_path: data.node_path,
+        node_type: data.node_type,
+        node_name: data.node_name,
+        ...(keptProps.length > 0 ? { props: keptProps } : {}),
+    };
+    const unavailable = {};
+    if (derived.includes("transform")) {
+        const local = localTransformFromProps(props);
+        if (local)
+            out.transform = local;
+        else
+            unavailable.transform = "this node has no position/rotation/scale (not a Node3D, Node2D or Control)";
+    }
+    if (derived.includes("warnings"))
+        out.warnings = Array.isArray(data.warnings) ? data.warnings : [];
+    if (derived.some((f) => SNAPSHOT_FIELDS.has(f))) {
+        const nodePath = normalizeNodePath(String(data.node_path ?? args.path));
+        const index = await snapshotIndex(client);
+        if (!(index instanceof Map)) {
+            for (const f of derived.filter((d) => SNAPSHOT_FIELDS.has(d)))
+                unavailable[f] = `world snapshot unavailable: ${index.error}`;
+        }
+        else {
+            const map = index;
+            const node = map.get(nodePath);
+            if (derived.includes("scene_file_path")) {
+                if (node)
+                    out.scene_file_path = typeof node.entry.scene_file === "string" ? node.entry.scene_file : null;
+                else
+                    unavailable.scene_file_path = `the world snapshot does not list ${nodePath}`;
+            }
+            if (derived.includes("aabb")) {
+                if (node?.entry.aabb)
+                    out.aabb = node.entry.aabb;
+                else
+                    unavailable.aabb = node ? "the node has no visual bounds" : `the world snapshot does not list ${nodePath}`;
+            }
+            if (derived.includes("global_transform")) {
+                const global = globalTransform(map, nodePath);
+                if ("error" in global && typeof global.error === "string")
+                    unavailable.global_transform = global.error;
+                else
+                    out.global_transform = global;
+            }
+        }
+    }
+    if (missing.length > 0)
+        out.missing_fields = missing;
+    if (Object.keys(unavailable).length > 0)
+        out.unavailable = unavailable;
+    return { ...root, data: out };
+}

package/dist/core/capabilities/inspect-resource.d.ts

@@ -0,0 +1,61 @@
+/**
+ * inspect-resource — ONE implementation of `summer_inspect_resource` for both
+ * faces (src/mcp/tools/scene-tools.ts and tool-dispatch.ts).
+ *
+ * The engine's state:resource (StateProvider::resource_properties_state)
+ * reads a resource a NODE holds: it takes nodePath + property and answers
+ * "missing nodePath or property" to anything else. The tool used to send it
+ * only `path`, so every call failed, on a mesh .res or a .glb alike. Two forms
+ * now:
+ *
+ *   path               a resource FILE, loaded in the editor by a read-only
+ *                      RunSceneScript probe (undo none, no checkpoint; the
+ *                      path travels as base64 data, never as source):
+ *                        Mesh         AABB, surfaces (primitive, vertex and
+ *                                     index counts, attributes, triangles,
+ *                                     material), materials, blend shapes
+ *                        PackedScene  node count, the first nodes with their
+ *                                     types, instanced scenes and meshes, and
+ *                                     a pointer to summer_inspect_asset
+ *                        Texture2D    size
+ *                        every other  editor properties that differ from the
+ *                                     class default (defaults are counted)
+ *   nodePath+property  the engine endpoint, for a resource a node of the
+ *                      active scene holds (e.g. Floor + mesh).
+ */
+import { z } from "zod";
+import { type CapabilityAdvertisingClient } from "../capability-skew.js";
+import { type JsonRecord } from "../util/json.js";
+export declare const INSPECT_RESOURCE_ARGS_TOKEN = "__SUMMER_RESOURCE_ARGS__";
+export declare const INSPECT_RESOURCE_FALLBACK = "read a text resource (.tres/.tscn) with summer_read_file, or pass nodePath + property for a resource a node of the open scene holds";
+export declare const inspectResourceInputShape: {
+    path: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    nodePath: z.ZodOptional<z.ZodString>;
+    property: z.ZodOptional<z.ZodString>;
+};
+export declare const inspectResourceInputSchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    nodePath: z.ZodOptional<z.ZodString>;
+    property: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    path?: string | undefined;
+    nodePath?: string | undefined;
+    property?: string | undefined;
+}, {
+    path?: string | undefined;
+    nodePath?: string | undefined;
+    property?: string | undefined;
+}>;
+export type InspectResourceArgs = z.output<typeof inspectResourceInputSchema>;
+export interface InspectResourceClient extends CapabilityAdvertisingClient {
+    executeIdentityBoundOps(ops: Record<string, unknown>[], options?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    inspectNodeResource(nodePath: string, property: string): Promise<unknown>;
+}
+export declare function inspectResource(client: InspectResourceClient, args: InspectResourceArgs): Promise<unknown>;
+/** Load a resource file read-only in the editor and describe it compactly. */
+export declare function inspectResourceFile(client: InspectResourceClient, path: string): Promise<JsonRecord>;
+export declare function buildInspectResourceScript(args: {
+    path: string;
+}): string;
+/** The probe source with its placeholder, for tests. */
+export declare function inspectResourceProbeTemplate(): string;