summer-engine 1.1.0 → 1.2.0

package/dist/mcp/server.js

@@ -6,6 +6,7 @@ import { registerSceneTools } from "./tools/scene-tools.js";
 import { registerDebugTools } from "./tools/debug-tools.js";
 import { registerProjectTools } from "./tools/project-tools.js";
 import { registerAssetTools } from "./tools/asset-tools.js";
+import { registerGenerateTools } from "./tools/generate-tools.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
 let cachedClient = null;
@@ -34,6 +35,7 @@ export async function startMcpServer() {
     registerDebugTools(server);
     registerProjectTools(server);
     registerAssetTools(server);
+    registerGenerateTools(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     process.stderr.write(`[summer-mcp] MCP server running v${version}.\n`);

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

@@ -56,6 +56,9 @@ async function searchAssetsApi(params) {
     if (params.limit) {
         searchParams.set("limit", String(params.limit));
     }
+    if (params.source) {
+        searchParams.set("source", params.source);
+    }
     const res = await fetch(`${GATEWAY_URL}/api/mcp/assets?${searchParams}`, {
         headers: { Authorization: `Bearer ${token}` },
         signal: AbortSignal.timeout(15000),
@@ -85,17 +88,23 @@ async function searchAssetsApi(params) {
     return data;
 }
 export function registerAssetTools(server) {
-    server.tool("summer_search_assets", `Search the Summer Engine asset library (25k+ game assets) by description.
+    server.tool("summer_search_assets", `Search for game assets in the Summer Engine ecosystem.
+
+Sources:
+  - "library" (default) — Public asset library (25k+ community assets). Requires Pro plan.
+  - "my_assets" — Your own generated/uploaded assets. Free for all users. Query is optional.
+  - "all" — Search both library and your assets.
 
 Uses hybrid search: keywords + semantic similarity. Finds assets by name AND by meaning.
 Returns asset names, types, preview URLs, and import-ready file URLs.
 
-Requires authentication. If the user gets an auth error, they need to run 'npx summer-engine login' in their terminal first.`, {
-        query: z.string().describe("Natural language search, e.g. 'low-poly tree', 'sci-fi weapon', 'wooden crate'"),
+Requires authentication: run 'npx summer-engine login' first.`, {
+        query: z.string().describe("Natural language search, e.g. 'low-poly tree', 'sci-fi weapon'. For my_assets, can be empty to list recent."),
         assetType: z.enum(["2d_image", "animation", "3d_model", "audio", "music", "all"]).default("all").describe("Filter by asset type"),
         limit: z.number().default(10).describe("Max results (1-20)"),
-    }, async ({ query, assetType, limit }) => {
-        const result = await searchAssetsApi({ query, assetType, limit: Math.min(limit, 20) });
+        source: z.enum(["library", "my_assets", "all"]).default("library").describe("Where to search: library (public 25k+), my_assets (your generated assets), all"),
+    }, async ({ query, assetType, limit, source }) => {
+        const result = await searchAssetsApi({ query, assetType, limit: Math.min(limit, 20), source });
         if (result.error) {
             return {
                 content: [

package/dist/mcp/tools/generate-tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGenerateTools(server: McpServer): void;

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.1.0",
+  "version": "1.2.0",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
   "keywords": [
     "game-engine",

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/make-game/SKILL.md

@@ -0,0 +1,441 @@
+---
+name: make-game
+description: End-to-end game creation workflow. Use when the user wants to build a complete game, start a new project, or says "make me a game". Orchestrates project setup, asset creation, scene building, scripting, and testing.
+license: MIT
+compatibility:
+  - Cursor
+  - Claude Code
+  - Windsurf
+---
+
+# Make a Game with Summer Engine
+
+Step-by-step workflow for building a complete game. Follow phases 0-6 in order. Each phase must complete before moving to the next.
+
+**Rule**: Scene operations (.tscn) use MCP tools. Script files (.gd) use host file-edit tools (Write/Edit). Never cross the streams.
+
+---
+
+## Phase 0: Gather Requirements
+
+Before touching any tools, ask the user:
+1. **What kind of game?** (platformer, FPS, top-down, puzzle, racing, etc.)
+2. **2D or 3D?**
+3. **Art style?** (realistic, low-poly, cartoon, pixel art)
+4. **Core mechanic?** One sentence. ("player jumps between platforms collecting coins")
+5. **Scope?** (1 level prototype, or multi-level)
+
+Use this decision matrix:
+
+| Genre | Root Type | Camera | Player Body | Dimension |
+|-------|-----------|--------|-------------|-----------|
+| FPS | Node3D | Camera3D on player | CharacterBody3D | 3D |
+| Platformer 2D | Node2D | Camera2D following | CharacterBody2D | 2D |
+| Platformer 3D | Node3D | Camera3D following | CharacterBody3D | 3D |
+| Top-down | Node2D | Camera2D | CharacterBody2D | 2D |
+| Puzzle | Node2D or Control | Camera2D or none | varies | 2D |
+| Racing | Node3D | Camera3D behind car | VehicleBody3D | 3D |
+
+---
+
+## Phase 1: Project Bootstrap
+
+### 1a. Get context
+
+```
+summer_get_agent_playbook()
+summer_get_project_context()
+```
+
+If a scene is open: `summer_get_scene_tree()` to see what exists.
+
+### 1b. Configure project
+
+```
+summer_project_setting(key="application/config/name", value="<game name>")
+summer_project_setting(key="display/window/size/viewport_width", value=1280)
+summer_project_setting(key="display/window/size/viewport_height", value=720)
+summer_project_setting(key="application/run/main_scene", value="res://scenes/main_level.tscn")
+```
+
+For 2D pixel art, add:
+```
+summer_project_setting(key="rendering/textures/canvas_textures/default_texture_filter", value=0)
+```
+
+### 1c. Create scenes
+
+```
+summer_create_scene(path="res://scenes/main_level.tscn", rootName="World", allow_temporary_scene_mutation=true)
+summer_create_scene(path="res://scenes/player.tscn", rootName="Player", allow_temporary_scene_mutation=true)
+```
+
+### 1d. Folder conventions
+
+- `res://scenes/` -- .tscn files
+- `res://scripts/` -- .gd files
+- `res://assets/models/` -- 3D models
+- `res://assets/textures/` -- images, sprites
+- `res://assets/audio/` -- sounds, music
+
+---
+
+## Phase 2: Asset Pipeline
+
+Pick the right strategy per asset. Prefer this order: Library > Generate > Primitives.
+
+### Strategy A: Asset Library (fastest, 25k+ free models)
+
+For environment props, furniture, nature, vehicles:
+
+```
+summer_search_assets(query="low-poly tree", assetType="3d_model", limit=5)
+summer_import_asset(query="wooden barrel", parent="./World/Props", assetType="3d_model")
+```
+
+### Strategy B: AI Generation (custom assets)
+
+**Images** (textures, sprites, UI art) -- sync, returns immediately:
+```
+summer_generate_image(prompt="top-down grass tileset, seamless, 512x512", style="cartoon")
+```
+Returns `localPath` -- use Read tool to show the user for approval.
+Then import:
+```
+summer_import_from_url(url="<asset.fileUrl>", path="res://assets/textures/grass.png")
+```
+
+**3D models** -- async, waits up to 5 min by default:
+```
+summer_generate_3d(prompt="low-poly treasure chest with gold coins", kind="text-to-3d")
+```
+Returns completed result directly. Then import the model URL.
+
+**Image-to-3D** -- generate concept art first, then convert:
+```
+summer_generate_image(prompt="medieval sword, ornate handle, game asset, white background")
+# Show to user, get approval
+summer_generate_3d(kind="image-to-3d", imageUrl="<asset.fileUrl>")
+```
+
+**Audio** -- sync:
+```
+summer_generate_audio(capability="sound_effects", text="sword swing whoosh")
+summer_generate_audio(capability="music", prompt="upbeat adventure theme", durationSeconds=30)
+summer_generate_audio(capability="text_to_speech", text="Welcome, adventurer!", voiceId="<id>")
+```
+
+**Parallel generation**: Start multiple 3D jobs with `wait=false`, work on scene setup, then check later:
+```
+summer_generate_3d(prompt="...", wait=false)  -> jobId: "abc"
+summer_generate_3d(prompt="...", wait=false)  -> jobId: "def"
+# ... do scene work ...
+summer_check_job(jobId="abc")
+summer_check_job(jobId="def")
+```
+
+### Strategy C: Primitive Meshes (instant, offline)
+
+For prototyping or blocking out levels:
+```
+summer_add_node(parent="./World", type="MeshInstance3D", name="Floor")
+summer_set_prop(path="./World/Floor", key="mesh", value="BoxMesh")
+summer_set_resource_property(nodePath="./World/Floor", resourceProperty="mesh", subProperty="size", value="Vector3(20, 0.2, 20)")
+```
+
+---
+
+## Phase 3: Scene Construction
+
+### 3a. Build environment with batch
+
+Use `summer_batch` for multi-step setup in one undo step:
+
+```
+summer_batch(ops=[
+  {"op":"AddNode","parent":"./","type":"Node3D","name":"Level"},
+  {"op":"AddNode","parent":"./Level","type":"MeshInstance3D","name":"Ground"},
+  {"op":"SetProp","path":"./Level/Ground","key":"mesh","value":"PlaneMesh"},
+  {"op":"SetResourceProperty","nodePath":"./Level/Ground","resourceProperty":"mesh","subProperty":"size","value":"Vector2(50,50)"},
+  {"op":"AddNode","parent":"./","type":"DirectionalLight3D","name":"Sun"},
+  {"op":"SetProp","path":"./Sun","key":"rotation_degrees","value":"Vector3(-45,30,0)"},
+  {"op":"SetProp","path":"./Sun","key":"shadow_enabled","value":"true"},
+  {"op":"AddNode","parent":"./","type":"WorldEnvironment","name":"Env"}
+])
+```
+
+### 3b. Build player
+
+**3D FPS/Third-person:**
+```
+summer_open_scene(path="res://scenes/player.tscn")
+summer_batch(ops=[
+  {"op":"AddNode","parent":"./","type":"CollisionShape3D","name":"Collision"},
+  {"op":"SetProp","path":"./Collision","key":"shape","value":"CapsuleShape3D"},
+  {"op":"AddNode","parent":"./","type":"Camera3D","name":"Camera"},
+  {"op":"SetProp","path":"./Camera","key":"position","value":"Vector3(0,1.6,0)"}
+])
+```
+
+**2D Platformer:**
+```
+summer_open_scene(path="res://scenes/player.tscn")
+summer_batch(ops=[
+  {"op":"AddNode","parent":"./","type":"CollisionShape2D","name":"Collision"},
+  {"op":"SetProp","path":"./Collision","key":"shape","value":"RectangleShape2D"},
+  {"op":"AddNode","parent":"./","type":"Sprite2D","name":"Sprite"},
+  {"op":"AddNode","parent":"./","type":"Camera2D","name":"Camera"}
+])
+```
+
+### 3c. Input bindings
+
+```
+summer_input_map_bind(name="move_forward", events=[{"type":"key","key":"W"}])
+summer_input_map_bind(name="move_back", events=[{"type":"key","key":"S"}])
+summer_input_map_bind(name="move_left", events=[{"type":"key","key":"A"}])
+summer_input_map_bind(name="move_right", events=[{"type":"key","key":"D"}])
+summer_input_map_bind(name="jump", events=[{"type":"key","key":"Space"}])
+summer_input_map_bind(name="interact", events=[{"type":"key","key":"E"}])
+```
+
+### 3d. Place assets in scene
+
+```
+summer_open_scene(path="res://scenes/main_level.tscn")
+summer_instantiate_scene(parent="./Level", scene="res://scenes/player.tscn", name="Player")
+summer_instantiate_scene(parent="./Level", scene="res://assets/models/tree.glb", name="Tree1")
+summer_set_prop(path="./Level/Tree1", key="position", value="Vector3(5, 0, 3)")
+```
+
+### 3e. Save
+
+```
+summer_save_scene()
+```
+
+---
+
+## Phase 4: Scripting
+
+**Write .gd files with host file-edit tools (Write/Edit). Attach via MCP.**
+
+Workflow:
+1. Write the script file to disk
+2. Attach: `summer_set_prop(path="./Player", key="script", value="res://scripts/player.gd")`
+3. Check: `summer_get_script_errors(path="res://scripts/player.gd")`
+4. Wire signals: `summer_connect_signal(emitter="./Coin", signal="body_entered", receiver="./Coin", method="_on_body_entered")`
+
+### 3D Player Controller (FPS)
+
+Write to `res://scripts/player.gd`:
+
+```gdscript
+extends CharacterBody3D
+
+@export var speed: float = 5.0
+@export var jump_velocity: float = 4.5
+@export var mouse_sensitivity: float = 0.002
+
+var gravity: float = ProjectSettings.get_setting("physics/3d/default_gravity")
+
+func _ready() -> void:
+    Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
+
+func _unhandled_input(event: InputEvent) -> void:
+    if event is InputEventMouseMotion:
+        rotate_y(-event.relative.x * mouse_sensitivity)
+        $Camera.rotate_x(-event.relative.y * mouse_sensitivity)
+        $Camera.rotation.x = clampf($Camera.rotation.x, -PI/2, PI/2)
+    if event.is_action_pressed("ui_cancel"):
+        Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
+
+func _physics_process(delta: float) -> void:
+    if not is_on_floor():
+        velocity.y -= gravity * delta
+
+    if Input.is_action_just_pressed("jump") and is_on_floor():
+        velocity.y = jump_velocity
+
+    var input_dir := Input.get_vector("move_left", "move_right", "move_forward", "move_back")
+    var direction := (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized()
+
+    if direction:
+        velocity.x = direction.x * speed
+        velocity.z = direction.z * speed
+    else:
+        velocity.x = move_toward(velocity.x, 0, speed)
+        velocity.z = move_toward(velocity.z, 0, speed)
+
+    move_and_slide()
+```
+
+### 2D Platformer Controller
+
+Write to `res://scripts/player.gd`:
+
+```gdscript
+extends CharacterBody2D
+
+@export var speed: float = 200.0
+@export var jump_velocity: float = -350.0
+
+var gravity: float = ProjectSettings.get_setting("physics/2d/default_gravity")
+
+func _physics_process(delta: float) -> void:
+    if not is_on_floor():
+        velocity.y += gravity * delta
+
+    if Input.is_action_just_pressed("jump") and is_on_floor():
+        velocity.y = jump_velocity
+
+    var direction := Input.get_axis("move_left", "move_right")
+    velocity.x = direction * speed if direction else move_toward(velocity.x, 0, speed)
+
+    move_and_slide()
+```
+
+### Collectible Pickup
+
+Write to `res://scripts/collectible.gd`:
+
+```gdscript
+extends Area3D
+
+signal collected
+
+func _ready() -> void:
+    body_entered.connect(_on_body_entered)
+
+func _on_body_entered(body: Node3D) -> void:
+    if body.is_in_group("player"):
+        collected.emit()
+        queue_free()
+```
+
+### Simple Enemy Patrol
+
+Write to `res://scripts/enemy_patrol.gd`:
+
+```gdscript
+extends CharacterBody3D
+
+@export var speed: float = 2.0
+@export var patrol_distance: float = 5.0
+
+var start_pos: Vector3
+var direction: float = 1.0
+var gravity: float = ProjectSettings.get_setting("physics/3d/default_gravity")
+
+func _ready() -> void:
+    start_pos = global_position
+
+func _physics_process(delta: float) -> void:
+    if not is_on_floor():
+        velocity.y -= gravity * delta
+
+    velocity.x = direction * speed
+    move_and_slide()
+
+    if global_position.distance_to(start_pos) > patrol_distance:
+        direction *= -1
+```
+
+---
+
+## Phase 5: Test and Debug
+
+```
+summer_clear_console()
+summer_play()
+```
+
+After a few seconds:
+```
+summer_get_diagnostics()
+```
+
+If errors:
+```
+summer_get_console(type="error")
+summer_get_script_errors(path="res://scripts/player.gd")
+```
+
+Fix, then:
+```
+summer_stop()
+# apply fix
+summer_play()
+```
+
+### Common errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "Node not found" | Bad $NodePath | Check path with `summer_get_scene_tree()` |
+| "Invalid call" on move_and_slide | Wrong base class | Script must extend CharacterBody3D/2D |
+| Falling through floor | No collision | Add StaticBody3D + CollisionShape3D to ground |
+| "No main scene" | Not configured | `summer_project_setting(key="application/run/main_scene", ...)` |
+| Mouse not captured | Missing in _ready | Add `Input.mouse_mode = Input.MOUSE_MODE_CAPTURED` |
+
+---
+
+## Phase 6: Iterate
+
+After first playable, ask the user what to improve. Common next steps:
+
+- **More levels**: Create new .tscn, instantiate player, add to scene list
+- **Enemies**: New scene + patrol script + spawn in level
+- **UI/HUD**: Add CanvasLayer + Control nodes (see ui-basics skill)
+- **Sound**: Generate with `summer_generate_audio`, attach AudioStreamPlayer3D
+- **Lighting**: Set up WorldEnvironment + lights (see 3d-lighting skill)
+- **Game states**: Main menu > gameplay > game over flow via SceneTree.change_scene_to_file()
+
+---
+
+## Anti-Patterns
+
+- Never write .tscn files with host file tools -- always use MCP scene tools
+- Never guess node paths -- call `summer_get_scene_tree()` first
+- Never edit scenes while game is running -- call `summer_stop()` first
+- Never skip `summer_save_scene()` -- unsaved changes are editor-only
+- Script .gd files must exist on disk BEFORE attaching via `summer_set_prop`
+- `summer_create_scene` requires `allow_temporary_scene_mutation=true`
+- Node paths use `./` prefix. File paths use `res://` prefix. Never mix them.
+
+---
+
+## Tool Quick Reference
+
+| Category | Tool | Purpose |
+|----------|------|---------|
+| Setup | `summer_get_agent_playbook` | Safe workflow guide |
+| Setup | `summer_get_project_context` | Project name, paths, status |
+| Setup | `summer_project_setting` | Set project.godot values |
+| Scene | `summer_create_scene` | New scene file |
+| Scene | `summer_open_scene` | Switch to scene |
+| Scene | `summer_get_scene_tree` | Read scene structure |
+| Scene | `summer_save_scene` | Save to disk |
+| Nodes | `summer_add_node` | Add node |
+| Nodes | `summer_set_prop` | Set property |
+| Nodes | `summer_set_resource_property` | Set sub-resource prop |
+| Nodes | `summer_remove_node` | Delete node |
+| Nodes | `summer_instantiate_scene` | Place .tscn/.glb |
+| Nodes | `summer_batch` | Multi-op, one undo |
+| Nodes | `summer_connect_signal` | Wire signals |
+| Nodes | `summer_inspect_node` | Read node details |
+| Input | `summer_input_map_bind` | Bind keys to actions |
+| Assets | `summer_search_assets` | Search 25k+ library |
+| Assets | `summer_import_asset` | Search + import + place |
+| Assets | `summer_import_from_url` | Import from URL |
+| Generate | `summer_generate_image` | AI image gen |
+| Generate | `summer_generate_audio` | AI audio/SFX/music |
+| Generate | `summer_generate_3d` | AI 3D model gen |
+| Generate | `summer_generate_video` | AI video gen |
+| Generate | `summer_check_job` | Poll async jobs |
+| Debug | `summer_play` | Run game |
+| Debug | `summer_stop` | Stop game |
+| Debug | `summer_get_diagnostics` | Error overview |
+| Debug | `summer_get_console` | Read output |
+| Debug | `summer_get_script_errors` | Check .gd compile |
+| Debug | `summer_clear_console` | Clear output |