summer-engine 1.0.1 → 1.2.0

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

@@ -0,0 +1,422 @@
+import { z } from "zod";
+import { writeFile, mkdir } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { getAuthToken } from "../../lib/auth.js";
+const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
+    const token = await getAuthToken();
+    if (!token) {
+        return {
+            error: "Not signed in. Run in your terminal:\n  npx summer-engine login\nOr open: https://www.summerengine.com/login",
+            status: 401,
+        };
+    }
+    const res = await fetch(`${GATEWAY_URL}${endpoint}`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        let message = data.message || data.error || "Request failed";
+        if (res.status === 402) {
+            message =
+                (data.message || "Insufficient credits.") +
+                    "\nTop up at: https://www.summerengine.com/dashboard\nOr upgrade your plan at: https://www.summerengine.com/pricing";
+        }
+        if (res.status === 401) {
+            message =
+                (data.message || "Auth token expired.") +
+                    "\nRe-authenticate:\n  npx summer-engine login";
+        }
+        return { error: message, data, status: res.status };
+    }
+    return { data, status: res.status };
+}
+/**
+ * Download an image URL to a temp file so the AI can Read it and show the user.
+ */
+async function downloadToTemp(url, prefix, ext = "png") {
+    try {
+        const dir = join(tmpdir(), "summer-gen");
+        await mkdir(dir, { recursive: true });
+        const filename = `${prefix}-${Date.now()}.${ext}`;
+        const filepath = join(dir, filename);
+        const res = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+        if (!res.ok)
+            return null;
+        const buffer = Buffer.from(await res.arrayBuffer());
+        await writeFile(filepath, buffer);
+        return filepath;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Poll a job until completed, failed, or timeout.
+ * Returns the final job status object.
+ */
+async function pollJob(jobId, maxWaitMs = 300_000, intervalMs = 5_000) {
+    const token = await getAuthToken();
+    if (!token)
+        return { error: "Not signed in" };
+    const deadline = Date.now() + maxWaitMs;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(`${GATEWAY_URL}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
+                headers: { Authorization: `Bearer ${token}` },
+                signal: AbortSignal.timeout(15_000),
+            });
+            const data = await res.json();
+            if (!res.ok)
+                return { error: data.message || "Poll failed", data };
+            if (data.status === "completed")
+                return { data };
+            if (data.status === "failed")
+                return { error: data.error || "Job failed", data };
+            // Still running — wait and retry
+            await new Promise((r) => setTimeout(r, intervalMs));
+            // Back off slightly after 30s
+            if (Date.now() - (deadline - maxWaitMs) > 30_000) {
+                intervalMs = Math.min(intervalMs * 1.2, 15_000);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { error: `Poll error: ${msg}` };
+        }
+    }
+    return { error: `Timed out after ${maxWaitMs / 1000}s. Use summer_check_job({ jobId: "${jobId}" }) to check later.` };
+}
+function errorResult(message, extra) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error: true, message, ...extra }, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+function successResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+export function registerGenerateTools(server) {
+    // ========================================================================
+    // summer_generate_image
+    // ========================================================================
+    server.tool("summer_generate_image", `Generate an image using AI models via Summer Engine Studio.
+
+Known models:
+  - "nano-banana-2" (default) — High quality, supports txt2img and img2img
+  - "gemini-flash" — Google Gemini 2.5 Flash, fast
+  - "flux-2" — FLUX.2, good for specific styles
+  - Any fal-ai model ID works as a passthrough
+
+Two modes:
+  - txt2img (default): just pass prompt
+  - img2img (edit): pass prompt + referenceImageUrl to edit/transform an existing image
+
+Style presets: "realistic" (default), "cartoon", "anime", "none"
+
+The 'options' object is passed directly to the AI provider for full control.
+
+Returns the asset with fileUrl (hosted) and localPath (temp file on disk).
+Use the Read tool on localPath to show the image to the user for approval.
+
+Requires authentication: run 'npx summer-engine login' first.`, {
+        prompt: z.string().describe("Description of the image to generate"),
+        model: z
+            .string()
+            .default("nano-banana-2")
+            .describe("Model name or full provider ID"),
+        style: z
+            .string()
+            .default("realistic")
+            .describe("Style preset: realistic, cartoon, anime, or 'none' to skip"),
+        referenceImageUrl: z
+            .string()
+            .optional()
+            .describe("Source image URL for img2img / edit mode. The prompt describes how to transform this image."),
+        options: z
+            .record(z.any())
+            .optional()
+            .describe("Provider-specific params (guidance_scale, seed, image_size, negative_prompt, etc.)"),
+    }, async ({ prompt, model, style, referenceImageUrl, options }) => {
+        const result = await mcpGenerate("/api/mcp/generate/image", {
+            prompt,
+            model,
+            style,
+            referenceImageUrl,
+            options,
+        });
+        if (result.error) {
+            return errorResult(result.error, result.data);
+        }
+        // Download to temp so the AI can Read and show the image
+        const imageUrl = result.data?.asset?.fileUrl || result.data?.asset?.thumbnailUrl;
+        let localPath = null;
+        if (imageUrl) {
+            localPath = await downloadToTemp(imageUrl, "img");
+        }
+        return successResult({
+            ...result.data,
+            localPath,
+            hint: localPath
+                ? `Image saved to ${localPath}. Use the Read tool on this path to show it to the user.`
+                : undefined,
+        });
+    });
+    // ========================================================================
+    // summer_generate_audio
+    // ========================================================================
+    server.tool("summer_generate_audio", `Generate audio using AI providers via Summer Engine Studio.
+
+Capabilities:
+  - "text_to_speech" — Convert text to spoken audio. Requires 'text'. Optional 'voiceId'.
+  - "sound_effects" — Generate sound effects from description. Requires 'text'. Optional 'durationSeconds'.
+  - "music" — Generate background music. Requires 'prompt'. Optional 'durationSeconds'.
+  - "text_to_dialogue" — Multi-voice dialogue. Requires 'inputs' array of {text, voiceId} objects.
+
+The 'options' object is passed directly to ElevenLabs, so you can set any
+provider-specific parameter: stability, similarity_boost, style, speed, etc.
+
+Returns the generated audio URL and asset metadata.
+Requires authentication: run 'npx summer-engine login' first.`, {
+        capability: z
+            .string()
+            .describe("Type of audio: text_to_speech, sound_effects, music, text_to_dialogue"),
+        text: z
+            .string()
+            .optional()
+            .describe("Text for TTS, or description for sound effects"),
+        prompt: z
+            .string()
+            .optional()
+            .describe("Music description (for 'music' capability)"),
+        voiceId: z
+            .string()
+            .optional()
+            .describe("ElevenLabs voice ID for TTS"),
+        modelId: z
+            .string()
+            .optional()
+            .describe("ElevenLabs model ID (e.g. 'eleven_multilingual_v2')"),
+        durationSeconds: z
+            .number()
+            .optional()
+            .describe("Duration in seconds for SFX or music"),
+        inputs: z
+            .array(z.object({ text: z.string(), voiceId: z.string() }))
+            .optional()
+            .describe("Dialogue lines for text_to_dialogue"),
+        options: z
+            .record(z.any())
+            .optional()
+            .describe("Provider-specific params (stability, similarity_boost, style, speed, etc.)"),
+    }, async ({ capability, text, prompt, voiceId, modelId, durationSeconds, inputs, options }) => {
+        const body = { capability };
+        if (text)
+            body.text = text;
+        if (prompt)
+            body.prompt = prompt;
+        if (voiceId)
+            body.voiceId = voiceId;
+        if (modelId)
+            body.modelId = modelId;
+        if (durationSeconds)
+            body.durationSeconds = durationSeconds;
+        if (inputs)
+            body.inputs = inputs;
+        if (options)
+            body.options = options;
+        const result = await mcpGenerate("/api/mcp/generate/audio", body);
+        if (result.error) {
+            return errorResult(result.error, result.data);
+        }
+        return successResult(result.data);
+    });
+    // ========================================================================
+    // summer_generate_3d
+    // ========================================================================
+    server.tool("summer_generate_3d", `Generate a 3D model via Summer Engine Studio.
+
+Available models:
+  - "hunyuan" (default) — Hunyuan 3D v3.1 Pro, high quality
+  - "trellis" — Trellis 2, fast and detailed
+  - "meshy" — Meshy, legacy option
+  - Any fal-ai model ID works as a passthrough
+
+Available kinds:
+  - "text-to-3d" (default) — From text description. Requires 'prompt'.
+    Internally generates a 3D-optimized reference image first, then converts to 3D.
+  - "image-to-3d" — From your own image. Requires 'imageUrl'.
+  - "texture" — Generate textures for a model. Requires 'imageUrl'.
+
+By default, waits for completion (up to 5 min) and returns the result directly.
+Set wait=false to get the jobId immediately and poll manually with summer_check_job.
+
+Requires authentication: run 'npx summer-engine login' first.`, {
+        prompt: z
+            .string()
+            .optional()
+            .describe("Description of the 3D model, e.g. 'a low-poly treasure chest'"),
+        kind: z
+            .string()
+            .default("text-to-3d")
+            .describe("Generation type: text-to-3d, image-to-3d, texture"),
+        model: z
+            .string()
+            .default("hunyuan")
+            .describe("Model: hunyuan (default), trellis, meshy, or any fal-ai model ID"),
+        imageUrl: z
+            .string()
+            .optional()
+            .describe("Source image URL for image-to-3d or texture"),
+        wait: z
+            .boolean()
+            .default(true)
+            .describe("Wait for completion (default true, up to 5 min). Set false to get jobId immediately."),
+        options: z
+            .record(z.any())
+            .optional()
+            .describe("Provider-specific params (target_polycount, topology, art_style, etc.)"),
+    }, async ({ prompt, kind, model, imageUrl, wait, options }) => {
+        const result = await mcpGenerate("/api/mcp/generate/3d", {
+            prompt,
+            kind,
+            model,
+            imageUrl,
+            options,
+        });
+        if (result.error) {
+            return errorResult(result.error, result.data);
+        }
+        const jobId = result.data?.jobId;
+        // If not waiting or no jobId, return immediately
+        if (!wait || !jobId) {
+            return successResult(result.data);
+        }
+        // Auto-poll until done
+        const pollResult = await pollJob(jobId);
+        if (pollResult.error) {
+            return errorResult(pollResult.error, { ...pollResult.data, jobId });
+        }
+        return successResult({
+            ...pollResult.data,
+            jobId,
+            message: "3D generation complete.",
+        });
+    });
+    // ========================================================================
+    // summer_generate_video
+    // ========================================================================
+    server.tool("summer_generate_video", `Generate a video using AI models via Summer Engine Studio.
+
+Known models (text-to-video):
+  - "ltx" (default) — LTX Video, fast (~$0.10)
+  - "kling" — Kling 2 Master, high quality (~$0.50)
+  - "kling-turbo" — Kling 2.5 Turbo Pro (~$0.30)
+  - "minimax" — MiniMax (~$0.25)
+  - "veo3" — Google Veo 3, premium (~$1.00)
+
+Known models (image-to-video, when imageUrl provided):
+  - "ltx" (default), "kling", "minimax"
+
+If imageUrl is provided, switches to image-to-video mode.
+Pass provider-specific params in 'options' (negative_prompt, num_frames, etc.).
+
+Returns the generated video URL and asset metadata.
+Requires authentication: run 'npx summer-engine login' first.`, {
+        prompt: z
+            .string()
+            .describe("Description of the video content"),
+        model: z
+            .string()
+            .default("ltx")
+            .describe("Model name: ltx, kling, kling-turbo, minimax, veo3 (or any new model)"),
+        imageUrl: z
+            .string()
+            .optional()
+            .describe("Source image URL — if provided, uses image-to-video mode"),
+        duration: z
+            .number()
+            .default(5)
+            .describe("Duration in seconds (5 or 10)"),
+        aspectRatio: z
+            .string()
+            .default("16:9")
+            .describe("Aspect ratio: 16:9, 9:16, 1:1, 4:3"),
+        options: z
+            .record(z.any())
+            .optional()
+            .describe("Provider-specific params (negative_prompt, num_frames, guidance_scale, etc.)"),
+    }, async ({ prompt, model, imageUrl, duration, aspectRatio, options }) => {
+        const result = await mcpGenerate("/api/mcp/generate/video", {
+            prompt,
+            model,
+            imageUrl,
+            duration,
+            aspectRatio,
+            options,
+        });
+        if (result.error) {
+            return errorResult(result.error, result.data);
+        }
+        return successResult(result.data);
+    });
+    // ========================================================================
+    // summer_check_job
+    // ========================================================================
+    server.tool("summer_check_job", `Check the status of an async generation job.
+
+Use this when you called summer_generate_3d with wait=false, or need to re-check
+a job that timed out. Most of the time you won't need this — summer_generate_3d
+waits automatically.
+
+Status values: waiting, active, completed, failed, delayed, unknown.
+
+Requires authentication: run 'npx summer-engine login' first.`, {
+        jobId: z.string().describe("The job ID returned by an async generation tool"),
+    }, async ({ jobId }) => {
+        const token = await getAuthToken();
+        if (!token) {
+            return errorResult("Not signed in. Run: npx summer-engine login");
+        }
+        try {
+            const res = await fetch(`${GATEWAY_URL}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
+                headers: { Authorization: `Bearer ${token}` },
+                signal: AbortSignal.timeout(15_000),
+            });
+            const data = await res.json();
+            if (!res.ok) {
+                return errorResult(data.message || data.error || "Failed to check job status", data);
+            }
+            return successResult(data);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return errorResult(`Job status check failed: ${msg}`);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
   "keywords": [
     "game-engine",
@@ -37,12 +37,16 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "ai": "^6.0.0",
     "commander": "^12.0.0",
+    "diff": "^7.0.0",
     "open": "^10.0.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@types/diff": "^7.0.0",
     "@types/node": "^20.0.0",
     "typescript": "^5.5.0"
   }

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.