summer-engine 1.1.0 → 1.2.1

package/dist/mcp/tools/project-tools.js

@@ -1,18 +1,83 @@
 import { z } from "zod";
 import { withEngine } from "./with-engine.js";
-import { readFile } from "fs/promises";
-import { join } from "path";
-async function readMainSceneFromProject(projectPath) {
-    if (!projectPath)
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringFrom(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function pickString(record, keys) {
+    if (!record)
         return null;
-    try {
-        const text = await readFile(join(projectPath, "project.godot"), "utf-8");
-        const match = text.match(/run\/main_scene="([^"]+)"/);
-        return match?.[1] ?? null;
+    for (const key of keys) {
+        const value = stringFrom(record[key]);
+        if (value)
+            return value;
     }
-    catch {
+    return null;
+}
+function getProjectData(projectState) {
+    return asRecord(asRecord(projectState)?.data);
+}
+function getProjectSetting(projectState, keys) {
+    const data = getProjectData(projectState);
+    const entries = data?.entries;
+    if (!Array.isArray(entries))
         return null;
+    for (const entry of entries) {
+        const item = asRecord(entry);
+        const key = stringFrom(item?.key);
+        if (key && keys.includes(key)) {
+            return stringFrom(item?.value);
+        }
     }
+    return null;
+}
+function getProjectPath(projectState) {
+    const root = asRecord(projectState);
+    const data = getProjectData(projectState);
+    return (pickString(data, [
+        "projectPath",
+        "project_path",
+        "projectRoot",
+        "project_root",
+        "rootPath",
+        "root_path",
+    ]) ??
+        pickString(root, ["projectPath", "project_path", "projectRoot", "project_root"]) ??
+        null);
+}
+function getProjectName(projectState) {
+    const root = asRecord(projectState);
+    const data = getProjectData(projectState);
+    return (pickString(data, ["projectName", "project_name", "name"]) ??
+        pickString(root, ["projectName", "project_name", "name"]) ??
+        getProjectSetting(projectState, ["application/config/name", "config/name"]));
+}
+function getMainScene(projectState) {
+    const root = asRecord(projectState);
+    const data = getProjectData(projectState);
+    return (pickString(data, ["mainScene", "main_scene", "mainScenePath", "main_scene_path"]) ??
+        pickString(root, ["mainScene", "main_scene", "mainScenePath", "main_scene_path"]) ??
+        getProjectSetting(projectState, [
+            "application/run/main_scene",
+            "run/main_scene",
+        ]));
+}
+function getCurrentScene(projectState, sceneState) {
+    const sceneRoot = asRecord(sceneState);
+    const sceneData = asRecord(sceneRoot?.data);
+    const sceneProvenance = asRecord(sceneRoot?.provenance);
+    const projectRoot = asRecord(projectState);
+    const projectData = getProjectData(projectState);
+    const projectProvenance = asRecord(projectRoot?.provenance);
+    return (pickString(sceneProvenance, ["scenePath", "scene_path"]) ??
+        pickString(sceneData, ["scenePath", "scene_path", "currentScene", "current_scene"]) ??
+        pickString(projectData, ["currentScene", "current_scene", "scenePath", "scene_path"]) ??
+        pickString(projectProvenance, ["scenePath", "scene_path"]) ??
+        null);
 }
 export function registerProjectTools(server) {
     server.tool("summer_get_agent_playbook", `AI-first operating guide for Summer Engine MCP.
@@ -25,7 +90,8 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                 text: JSON.stringify({
                     startupChecklist: [
                         "Decide first: file edit or engine operation.",
-                        "For normal code/content edits (.gd/.tscn/.tres/.ts), use host file-edit tools directly.",
+                        "Write .gd/.cs/.json/docs/simple config with host file-edit tools directly.",
+                        "Use Summer MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, screenshots/verification.",
                         "Call summer_get_project_context first.",
                         "If no scene is open, call summer_open_main_scene.",
                         "Call summer_get_scene_tree before structural edits.",
@@ -33,15 +99,16 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                     ],
                     safeDefaults: [
                         "Never guess scene filenames (main.tscn/Main.tscn).",
-                        "Do not route ordinary code edits through MCP when direct file tools are available.",
+                        "Do not route ordinary script, JSON, docs, or simple config edits through MCP when direct file tools are available.",
                         "Never remove multiple top-level nodes unless user explicitly requests destructive edits.",
-                        "Never write .tscn/.scn with file write tools; use scene ops.",
+                        "Use MCP for scene-tree mutations and inspector-visible values instead of hand-editing live scene state.",
                     ],
                     preferredFlow: [
                         "summer_get_project_context",
                         "summer_open_main_scene (if needed)",
                         "summer_get_scene_tree",
                         "edit via summer_add_node / summer_set_prop / summer_set_resource_property",
+                        "write scripts/data/docs/simple config directly with host file-edit tools",
                         "summer_save_scene",
                         "summer_get_diagnostics",
                     ],
@@ -56,35 +123,45 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
     }));
     server.tool("summer_get_project_context", `Get essential project context before editing. Returns:
 - engine health/status
-- project name and path
+- project name and project path when exposed by project state
 - current scene path (if available)
-- main scene path from project.godot
+- main scene path from project settings
 
 Use this first in every fresh chat to avoid guessing scene filenames or editing the wrong scene.`, {}, async () => withEngine(async (client) => {
-        const [health, projectState] = await Promise.all([
+        const [health, projectState, sceneState] = await Promise.all([
             client.health(),
             client.getProjectState(),
+            client.getSceneState().catch((err) => ({
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            })),
         ]);
-        const healthObj = (health ?? {});
-        const mainScene = await readMainSceneFromProject(typeof healthObj.project_path === "string" ? healthObj.project_path : undefined);
+        const projectPath = getProjectPath(projectState);
+        const projectName = getProjectName(projectState);
+        const mainScene = getMainScene(projectState);
+        const currentScene = getCurrentScene(projectState, sceneState);
         return {
             health,
             project: projectState,
+            scene: sceneState,
+            projectName,
+            projectPath,
+            currentScene,
             mainScene,
             guidance: mainScene
                 ? "Use `summer_open_scene` with `mainScene` if no scene is open."
-                : "Main scene not found in project.godot. Open a known scene path explicitly.",
+                : "Main scene not found in project state. Open a known scene path explicitly.",
+            fileEditingGuidance: "Write .gd/.cs/.json/docs/simple config directly with host file tools. Use MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, and visual verification.",
         };
     }));
-    server.tool("summer_open_main_scene", `Open the project's configured main scene from project.godot.
+    server.tool("summer_open_main_scene", `Open the project's configured main scene from project settings.
 
 Safer than guessing scene names like main.tscn/Main.tscn.
 Call this when you get "no scene open".`, {}, async () => withEngine(async (client) => {
-        const health = (await client.health());
-        const projectPath = typeof health.project_path === "string" ? health.project_path : undefined;
-        const mainScene = await readMainSceneFromProject(projectPath);
+        const projectState = await client.getProjectState();
+        const mainScene = getMainScene(projectState);
         if (!mainScene) {
-            throw new Error("Could not resolve application/run/main_scene from project.godot. Call `summer_get_project_context` and open a scene explicitly.");
+            throw new Error("Could not resolve application/run/main_scene from project state. Call `summer_get_project_context` and open a scene explicitly.");
         }
         return client.executeOps([{ op: "OpenScene", path: mainScene }]);
     }));

package/dist/mcp/tools/with-engine.js

@@ -1,10 +1,10 @@
 import { getClient, resetClient } from "../server.js";
-import { getAuthToken } from "../../lib/auth.js";
-const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
 function extractOpError(result) {
     if (!result || typeof result !== "object")
         return null;
     const op = result;
+    if (op.ok === false && op.error)
+        return op.error;
     if (op.status === "error" && op.error)
         return op.error;
     const firstFailed = op.results?.find((r) => r.ok === false && r.error);
@@ -19,62 +19,12 @@ function buildActionHint(message) {
         return "Scene path could not be opened. Call `summer_get_project_context` to get `mainScene`, then open that exact path. Avoid guessing scene filenames.";
     }
     if (normalized.includes("writefile cannot edit .tscn/.scn")) {
-        return "This MCP operation cannot write .tscn/.scn directly. If your host AI has normal file-edit tools, edit .gd/.tscn files there; use Summer MCP for engine/state/scene-tree operations.";
+        return "Write .gd/.cs/.json/docs/simple config files with normal file-edit tools. Use Summer MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, and visual verification.";
     }
     return null;
 }
-async function checkMcpQuota() {
-    const token = await getAuthToken();
-    if (!token) {
-        return {
-            allowed: false,
-            message: "Not signed in. The user needs to run this in their terminal:\n  npx summer-engine login\nOr open: https://www.summerengine.com/login\nMCP tools require a Summer Engine account (free to create).",
-        };
-    }
-    try {
-        const res = await fetch(`${GATEWAY_URL}/api/mcp/log-local-call`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${token}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({}),
-            signal: AbortSignal.timeout(10000),
-        });
-        const data = (await res.json().catch(() => ({})));
-        // Hard enforcement errors should block tool execution.
-        if ([401, 402, 403, 429].includes(res.status)) {
-            return {
-                allowed: false,
-                message: data.message || "Quota check failed. Try again.",
-            };
-        }
-        // Soft-fail on service/gateway issues so local tools keep working.
-        if (!res.ok) {
-            return { allowed: true };
-        }
-        if (data.allowed === false) {
-            return {
-                allowed: false,
-                message: data.message || "MCP call limit reached. Upgrade at https://summerengine.com/pricing",
-            };
-        }
-        return { allowed: true };
-    }
-    catch (err) {
-        // Network/transient errors should not brick local MCP usage.
-        return { allowed: true };
-    }
-}
 export async function withEngine(fn) {
     try {
-        const quota = await checkMcpQuota();
-        if (!quota.allowed) {
-            return {
-                content: [{ type: "text", text: quota.message || "Quota exceeded" }],
-                isError: true,
-            };
-        }
         const client = await getClient();
         const result = await fn(client);
         const opError = extractOpError(result);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
   "keywords": [
     "game-engine",
@@ -31,6 +31,8 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "summer": "node dist/bin/summer.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "engines": {
@@ -48,6 +50,7 @@
   "devDependencies": {
     "@types/diff": "^7.0.0",
     "@types/node": "^20.0.0",
-    "typescript": "^5.5.0"
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.4"
   }
 }

package/skills/asset-strategy/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: asset-strategy
+description: Decision guide for how to create different game asset types. Use when deciding whether to generate 3D models, textures, or use primitives. Includes prompt templates for AI image-to-3D pipeline.
+license: MIT
+compatibility:
+  - Cursor
+  - Claude Code
+  - Windsurf
+---
+
+# Asset Strategy for Summer Engine
+
+How to create different types of game assets. Pick the right pipeline for each asset type.
+
+---
+
+## Decision Tree
+
+| Asset type | Pipeline | Why |
+|-----------|----------|-----|
+| Props (sword, barrel, chair, crate) | Image-to-3D | Best quality for isolated objects |
+| Characters (player, NPC, enemy) | Image-to-3D (mannequin ref) | T-pose reference preserves proportions |
+| Organic (trees, rocks, mushrooms) | Image-to-3D | Handles complex shapes well |
+| Vehicles (car, spaceship, boat) | Image-to-3D | Good for hard-surface objects |
+| Walls / floors / ceilings | Texture + BoxMesh/CSGBox | Tiled textures on simple geometry |
+| Terrain / ground | Texture + PlaneMesh | Tileable ground textures |
+| Buildings / structures | Texture + CSG or modular kit | Combine primitive shapes with textures |
+| UI elements / icons / HUD | 2D image only | No 3D conversion needed |
+| Sprites (2D games) | 2D image only | Direct use as Sprite2D texture |
+| Skyboxes / backgrounds | Panoramic image gen | Environment, not mesh |
+| Particles / VFX | Built in engine | GPUParticles3D, no generation |
+| Audio / music / SFX | summer_generate_audio | Separate pipeline |
+
+---
+
+## Pipeline 1: Image-to-3D (Props, Characters, Organic)
+
+### How it works
+
+1. A reference template image (mannequin on white bg) is stored server-side
+2. nano-banana-2 img2img replaces the mannequin with the desired asset
+3. The result is a clean, 3D-ready reference image
+4. That image feeds into Hunyuan 3D (default) or Trellis 2 for 3D conversion
+5. You get a 3D model back
+
+Available 3D models:
+- **hunyuan** (default) — Hunyuan 3D v3.1 Pro, highest quality
+- **trellis** — Trellis 2, fast and detailed
+- **meshy** — Legacy option
+
+From the CLI, the reference image step is invisible. Just call:
+
+```
+summer_generate_3d(prompt="a treasure chest with gold coins")
+```
+
+The server generates the reference image and feeds it to 3D automatically.
+
+To pick a specific model:
+
+```
+summer_generate_3d(prompt="a treasure chest", model="trellis")
+```
+
+For manual control (you want to see/approve the reference image first):
+
+```
+summer_generate_image(prompt="a treasure chest with gold coins, game asset, white background, stylized, not ultra realistic")
+# Review the image with Read tool
+summer_generate_3d(kind="image-to-3d", imageUrl="<fileUrl from above>")
+```
+
+### Prompt template for 3D reference images
+
+When generating images intended for 3D conversion, use this suffix:
+
+```
+[your asset description]. Game asset, centered in frame, 3D model render style, 
+stylized game art, not ultra realistic, clean white background, soft studio 
+lighting. Isolated object ready for 3D mesh generation.
+```
+
+Examples:
+
+**Weapon:**
+```
+A medieval broadsword with ornate crossguard and leather-wrapped grip. Game asset, 
+centered in frame, 3D model render style, stylized game art, not ultra realistic, 
+clean white background, soft studio lighting. Isolated object ready for 3D mesh 
+generation.
+```
+
+**Character:**
+```
+A fantasy knight in full plate armor, red cape, detailed pauldrons. T-pose, 
+front-facing. Game character asset, 3D model render style, stylized game art, 
+not ultra realistic, clean white background, soft studio lighting. Ready for 
+3D mesh generation.
+```
+
+**Organic prop:**
+```
+Cluster of bioluminescent mushrooms growing from a small mossy rock base. Pale 
+green glow, translucent caps, alien organic shapes. Game asset, centered in frame, 
+3D model render style, stylized game art, not ultra realistic, clean white 
+background, soft studio lighting. Isolated object ready for 3D mesh generation.
+```
+
+**Vehicle:**
+```
+A rusted sci-fi hover bike with exposed engine parts and worn paint. Game asset, 
+centered in frame, 3D model render style, stylized game art, not ultra realistic, 
+clean white background, soft studio lighting. Isolated vehicle ready for 3D mesh 
+generation.
+```
+
+### What makes a BAD 3D reference
+
+Avoid these in prompts:
+- Scene context ("sword lying on a table") -- the table becomes part of the mesh
+- Strong directional shadows -- baked into the mesh as geometry
+- Ultra-realistic rendering -- too much detail for game-ready meshes
+- Flat 2D angles (pure front/side view) -- 3D gen needs depth cues
+- Multiple objects ("a sword and a shield") -- generates as one fused mesh
+- Busy backgrounds -- bleeds into the model
+
+### Polycount guidance
+
+Pass in options when quality matters:
+
+```
+summer_generate_3d(prompt="...", options={ target_polycount: 5000 })
+```
+
+Rough targets:
+- Mobile games: 1k-3k tris
+- Indie/stylized PC: 3k-10k tris
+- Detailed hero assets: 10k-30k tris
+- Cinematics/showcase: 30k-100k tris
+
+Default if not specified: provider decides (usually 10k-30k range).
+
+---
+
+## Pipeline 2: Textures + Geometry (Walls, Floors, Structures)
+
+For flat surfaces and repeating structures, don't generate 3D models. Generate textures and apply them to simple geometry.
+
+### Walls
+
+```
+summer_generate_image(prompt="seamless brick wall texture, tileable, game texture, diffuse map")
+summer_import_from_url(url="<fileUrl>", path="res://assets/textures/brick_wall.png")
+```
+
+Then in the scene:
+```
+summer_add_node(parent="./Level", type="CSGBox3D", name="Wall")
+summer_set_prop(path="./Level/Wall", key="size", value="Vector3(10, 3, 0.3)")
+summer_set_prop(path="./Level/Wall", key="position", value="Vector3(0, 1.5, -5)")
+```
+
+Attach material with texture via script or manual setup.
+
+### Floors / ground
+
+```
+summer_generate_image(prompt="seamless grass ground texture, top-down, tileable, game texture")
+```
+
+Apply to PlaneMesh or CSGBox3D scaled flat.
+
+### Modular building kit
+
+For buildings, combine CSG shapes:
+- CSGBox3D for walls
+- CSGBox3D for floors/ceilings
+- CSGCylinder3D for pillars
+- CSGPolygon3D for custom shapes
+
+Generate different textures for each material:
+- Wall texture (brick, stone, wood)
+- Floor texture (tile, wood planks, concrete)
+- Roof texture (shingles, metal)
+
+### Texture prompt tips
+
+For tileable textures, always include:
+```
+[material description], seamless, tileable, game texture, diffuse map, 
+top-down view, uniform lighting, no perspective
+```
+
+---
+
+## Pipeline 3: 2D Only (UI, Sprites, Icons)
+
+For 2D game assets and UI elements:
+
+```
+summer_generate_image(prompt="pixel art heart icon, 64x64, red, game UI element", 
+  style="pixel")
+```
+
+For sprite sheets, consider the sprite animation tools (separate from this pipeline).
+
+### UI prompt tips
+
+```
+[element description], flat design, clean edges, game UI style, 
+transparent background preferred, [size]px
+```
+
+---
+
+## Pipeline 4: Audio
+
+Separate from visual assets. See summer_generate_audio tool:
+
+```
+summer_generate_audio(capability="sound_effects", text="metal sword clash impact")
+summer_generate_audio(capability="music", prompt="ambient fantasy forest theme", durationSeconds=60)
+summer_generate_audio(capability="text_to_speech", text="You shall not pass!", voiceId="<id>")
+```
+
+---
+
+## Edge Cases (add to this list as they come up)
+
+- **Transparent/glass objects**: Add "translucent material, see-through" to prompt. 3D gen may struggle -- consider using engine materials instead.
+- **Animated objects**: Generate static mesh first, animate in engine with AnimationPlayer.
+- **Multi-part objects**: Generate each part separately, assemble in scene tree.
+- **Extremely thin objects** (paper, cloth, flags): 3D gen produces thick meshes. Better to use MeshInstance3D with a plane + texture + shader.
+- **Emissive/glowing objects**: Generate the mesh, add emissive material in engine. Don't rely on the glow being in the mesh.
+- **LOD (Level of Detail)**: Generate one version. If perf needs LOD, use Godot's LOD system or generate a second low-poly version.

package/skills/gdscript-patterns/SKILL.md

@@ -89,8 +89,8 @@ var siblings = get_parent().get_children()
 
 For health systems, input handling, and state machines, see [reference.md](reference.md).
 
-## MCP Integration
+## Scene Integration
 
-When the AI adds a script via `summer_add_node` and attaches a script, the script path is set via `summer_set_prop(path, "script", "res://path/to/script.gd")`. The script file must exist—use `summer_write_file` to create it first.
+When the AI adds a node with Summer MCP tools and attaches a script, the script path is set via `summer_set_prop(path, "script", "res://path/to/script.gd")`. The script file must exist first. Create or edit `.gd` files with the host agent's normal file-editing tools, then use Summer MCP only to attach the script and connect scene signals.
 
 For signal connections, the receiver must have the handler method. Create the script with the method stub before calling `summer_connect_signal`.