scad-gltf 0.4.0 → 0.5.1

package/README.md

@@ -16,6 +16,7 @@ The C++ source code for this custom OpenSCAD version is included directly in thi
 - **Extended PBR Material Support:** Native extensions to the OpenSCAD `color()` module supporting `metalness`, `roughness`, `transmission` (glass), `thickness`, `ior`, `attenuationColor`, `attenuationDistance`, `clearcoat`, `sheen`, `emissive`, `specular`, and `iridescence`, plus a `$asa` special variable for auto smooth shading.
 - **Hierarchical Node Animation:** Define articulated, rigid-body hierarchies and keyframe animations using `armature()` and `bone()` modules. Exports proper glTF node transform tracks (rigid parenting rather than vertex-weighted skinning—ideal for robots, mechanical parts, vehicles, and articulated components).
 - **Texture Baking:** Automatically generate UVs and bake high-poly details (colors, normals, ORM) onto low-poly meshes using the new `bake()` module.
+- **Scene Lighting:** Spawn precise light sources within your hierarchy (point, directional, spot) using the `light()` module, exporting directly to glTF.
 - **Web Editor & Real-time Viewer (Scadify):** In-browser IDE with live WebAssembly compilation, GPU path tracing, animation timeline scrubbing, video/image export, URL sharing, and `.scad` / `.hdr` drag-and-drop.
 - **LLM Friendly:** Includes a built-in modular prompt generator (`prompt.js` and Web UI) to help AI models (like Gemini, Claude, or ChatGPT) write compatible OpenSCAD scripts utilizing the new features.
 - **Local API Server & Editor:** Bundled `scad-gltf serve` CLI utility to manage local `.scad` files remotely via REST API with automatic `include`/`use` dependency resolution.
@@ -260,7 +261,7 @@ Instead of generating code blindly, the AI can compile its script, render the 3D
 
 **Exposed MCP Tools:**
 
-- `get_scad_prompt`: Injects the custom OpenSCAD syntax rules (PBR, animations, baking) into the AI's context.
+- `get_project_prompt`: Generates the specialized system prompt and user input request for creating full procedural 3D projects (Godot, Web, Rust, or pure SCAD).
 - `render_scad_model`: Compiles the generated `.scad` code to GLB and returns base64 images from requested camera angles (front, back, left, right, top, bottom, isometric) and specific animation keyframes.
 - `compile_rust_project` / `test_godot_project`: Tests the generated game projects for compilation and runtime errors.
 
@@ -283,18 +284,6 @@ If you installed the package globally, you can configure your MCP client to use
 
 ---
 
-## 🎮 Godot Engine Integration
-
-This repository includes an official **Godot 4.x Importer Addon** located in the [`/godot`](./godot) directory.
-
-The addon allows you to drag-and-drop `.scad` files directly into your Godot project. It uses this WASM compiler under the hood to transform scripts into 3D scenes automatically.
-
-- **Features:** Supports PBR Materials and Hierarchical Node Animations inside the Godot Editor.
-- **License:** The Godot Addon is licensed under **MIT**.
-- **Setup:** Simply copy the `addons/scad_importer` folder to your project and enable it in Project Settings.
-
----
-
 ## Automated AI Generation (`scad-gltf gen`)
 
 By default, the `scad-gltf gen` utility copies a heavily engineered system prompt to your clipboard to paste into an LLM. However, if you provide a **Base URL** (and optional **API Key**), the CLI will fully automate this process. It will automatically spin up the `scad-gltf mcp` server in the background, connect it to your LLM, and allow the AI to _visually evaluate and fix_ its code in real-time before saving the final `generate_project.js` script to your disk.
@@ -467,6 +456,17 @@ bake(uvs=true) {
 }
 ```
 
+### 4. Scene Lighting
+
+Add glTF lights directly into your model hierarchy:
+
+```openscad
+// A spot light pointing down at an angle
+translate([0, 0, 50]) rotate([0, 30, 0])
+  light(type="spot", color=[1, 0.8, 0.8], intensity=5.0, innerConeAngle=15.0, outerConeAngle=30.0)
+    color("gray") cylinder(h=2, r=1, center=true); // A visual representation of the light fixture
+```
+
 ---
 
 ## AI Integration (`prompt.js`)
@@ -490,6 +490,7 @@ const promptContext = generatePrompt(description, {
   iridescence: true, // Thin-film interference
   autoSmoothAngle: true, // $asa rules
   animation: true, // Armature & bone syntax
+  lights: false, // Light rules
   bakeColors: false, // Texture baking flags
   bakeNormals: false,
   bakeOrm: false,
@@ -505,7 +506,7 @@ console.log(promptContext);
 
 Once connected, an AI assistant can use the server to execute the following loop:
 
-1. **Retrieve Syntax Rules:** The assistant calls the `get_scad_prompt` tool to get the extended syntax rules for PBR materials, hierarchical node animations, and texture baking.
+1. **Retrieve Syntax Rules:** The assistant calls the `get_project_prompt` tool to get the extended syntax rules and project structure guidelines.
 2. **Generate Code:** The assistant writes the `.scad` script based on your design request.
 3. **Compile & Visually Inspect:** The assistant calls the `render_scad_model` tool to inspect rendered multi-angle frames and keyframes, fixing any errors before final export.
 

package/bin/mcp.js

@@ -13,7 +13,9 @@ import {
 import puppeteer from "puppeteer";
 import { convertScadToGltf } from "../src/convert.js";
 import { generatePrompt } from "../src/prompt.js";
+import { getProjectPrompts } from "../src/project-prompts.js";
 import { runGodotAsync } from "../src/godot-utils.js";
+import { generateScadPreviewUrl } from "../src/cli-utils.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -55,15 +57,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
     tools: [
       {
-        name: "get_scad_prompt",
+        name: "get_project_prompt",
         description:
-          "Generates the specialized instruction prompt containing the required syntax rules for PBR, Animations, and Texture Baking in this custom OpenSCAD environment.",
+          "Generates the specialized system prompt and user input request for creating full procedural 3D projects (Godot, Web, Rust, or pure SCAD). This provides the syntax rules and structure required to generate the project.",
         inputSchema: {
           type: "object",
           properties: {
+            project_type: {
+              type: "string",
+              enum: ["scad", "bevy", "wgpu", "web", "godot"],
+              description:
+                "The target framework or output type for the project.",
+            },
             description: {
               type: "string",
-              description: "The description of the object you want to design.",
+              description:
+                "The description of the project or object you want to design.",
             },
             options: {
               type: "object",
@@ -78,17 +87,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 transmission: {
                   type: "boolean",
                   description:
-                    "Include rules for transparent/glass volumes: transmission, thickness, ior, attenuationColor, and attenuationDistance. (Default: true)",
+                    "Include rules for transparent/glass volumes. (Default: false)",
                 },
                 clearcoat: {
                   type: "boolean",
                   description:
-                    "Include rules for clearcoat and clearcoatRoughness. (Default: true)",
+                    "Include rules for clearcoat and clearcoatRoughness. (Default: false)",
                 },
                 sheen: {
                   type: "boolean",
                   description:
-                    "Include rules for cloth/velvet sheen: sheen, sheenColor, and sheenRoughness. (Default: true)",
+                    "Include rules for cloth/velvet sheen. (Default: false)",
                 },
                 emissive: {
                   type: "boolean",
@@ -98,12 +107,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 specular: {
                   type: "boolean",
                   description:
-                    "Include rules for specular reflections: specularColor and specularIntensity. (Default: true)",
+                    "Include rules for specular reflections. (Default: true)",
                 },
                 iridescence: {
                   type: "boolean",
                   description:
-                    "Include rules for thin-film interference: iridescence and iridescenceIOR. (Default: true)",
+                    "Include rules for thin-film interference. (Default: false)",
                 },
                 autoSmoothAngle: {
                   type: "boolean",
@@ -140,21 +149,27 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                   description:
                     "Include rules for the lazy-union compiler optimization. (Default: false)",
                 },
-                modelName: {
+                lights: {
                   type: "boolean",
                   description:
-                    "Include output instructions requiring the '/* Model Name: ... */' header comment. (Default: true)",
+                    "Include rules for adding scene lights. (Default: false)",
+                },
+                scadFiles: {
+                  type: "array",
+                  items: { type: "string" },
+                  description:
+                    "Array of file paths to existing .scad files to embed as context.",
                 },
               },
             },
           },
-          required: ["description"],
+          required: ["project_type", "description"],
         },
       },
       {
         name: "render_scad_model",
         description:
-          "Converts OpenSCAD code to GLTF and uses a 3D renderer to capture images from requested camera angles. Analyze these returned images to verify your design, including specific frames of your animations.",
+          "Converts OpenSCAD code to GLTF and uses a 3D renderer to capture images from requested camera angles. Analyze these returned images to verify your design. The tool response will also include a GitHub-hosted Live Editor Preview URL—you MUST share this URL with the user so they can view the model interactively.",
         inputSchema: {
           type: "object",
           properties: {
@@ -257,23 +272,54 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
 
   // ------------------------------------------
-  // TOOL 1: get_scad_prompt
+  // TOOL 1: get_project_prompt
   // ------------------------------------------
-  if (name === "get_scad_prompt") {
+  if (name === "get_project_prompt") {
     try {
-      const promptText = generatePrompt(args.description, args.options || {});
+      const pType = args.project_type;
+      const desc = args.description;
+      const opts = {
+        transmission: false,
+        clearcoat: false,
+        sheen: false,
+        iridescence: false,
+        ...(args.options || {}),
+      };
+
+      if (!["scad", "bevy", "wgpu", "web", "godot"].includes(pType)) {
+        throw new Error(`Invalid project type: ${pType}`);
+      }
+
+      if (pType !== "scad") {
+        opts.modelName = false;
+      }
+
+      const promptRules = generatePrompt(
+        pType === "scad" ? desc : "the 3D assets for the project",
+        opts,
+      );
+
+      const prompts = getProjectPrompts(pType);
+      const systemPrompt = prompts.buildSystemPrompt(promptRules, opts);
+      const userRequest = prompts.buildInputRequest
+        ? prompts.buildInputRequest(desc, promptRules)
+        : promptRules;
+
       return {
         content: [
           {
             type: "text",
-            text: promptText,
+            text: `=== SYSTEM PROMPT ===\n${systemPrompt}\n\n=== USER REQUEST ===\n${userRequest}`,
           },
         ],
       };
     } catch (error) {
       return {
         content: [
-          { type: "text", text: `Error generating prompt: ${error.message}` },
+          {
+            type: "text",
+            text: `Error generating project prompt: ${error.message}`,
+          },
         ],
         isError: true,
       };
@@ -295,7 +341,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const animIndex = args.animation_index || 0;
       const returnImages = args.return_images !== false;
 
-      // 1. Convert SCAD to GLB ArrayBuffer
+      // 1. Generate the public GitHub Scadify URL
+      const previewUrl =
+        generateScadPreviewUrl(
+          scadCode,
+          "https://iliagrigorevdev.github.io/scad-gltf",
+        ) || "Failed to generate URL";
+
+      // 2. Convert SCAD to GLB ArrayBuffer
       const glbDataArray = await convertScadToGltf(scadCode, {
         wasmUrl: `file://${wasmPath}`,
       });
@@ -305,7 +358,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           content: [
             {
               type: "text",
-              text: `Successfully compiled SCAD without syntax errors. (Visual rendering skipped because return_images is false).`,
+              text: `Successfully compiled SCAD without syntax errors. (Visual rendering skipped because return_images is false).\n\nLive Editor Preview URL: ${previewUrl}`,
             },
           ],
         };
@@ -330,8 +383,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           <script type="importmap">
             {
               "imports": {
-                "three": "https://unpkg.com/three@0.160.0/build/three.module.js",
-                "three/addons/": "https://unpkg.com/three@0.160.0/examples/jsm/"
+                "three": "https://unpkg.com/three@0.186.1/build/three.module.js",
+                "three/addons/": "https://unpkg.com/three@0.186.1/examples/jsm/"
               }
             }
           </script>
@@ -416,6 +469,58 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           const gltf = await loader.loadAsync(dataUrl);
           scene.add(gltf.scene);
 
+          // Detect scene lights to match editor behavior
+          let sceneHasLights = false;
+          let maxDir = 0;
+          let maxPt = 0;
+
+          gltf.scene.traverse((child) => {
+            if (child.isMesh) {
+              child.frustumCulled = false;
+            }
+            if (child.isLight) {
+              sceneHasLights = true;
+              child.castShadow = true;
+              if (child.isDirectionalLight) {
+                maxDir = Math.max(maxDir, child.intensity);
+              } else {
+                maxPt = Math.max(maxPt, child.intensity);
+              }
+            }
+          });
+
+          if (sceneHasLights) {
+            renderer.shadowMap.enabled = true;
+            renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+
+            gltf.scene.traverse((child) => {
+              if (child.isMesh) {
+                child.castShadow = true;
+                child.receiveShadow = true;
+              }
+            });
+
+            let optimalExposure = 1.0;
+            const expDir = maxDir > 0 ? 3.0 / maxDir : 1.0;
+            const expPt = maxPt > 0 ? 3000.0 / maxPt : 1.0;
+
+            if (maxDir > 0 && maxPt > 0)
+              optimalExposure = Math.min(expDir, expPt);
+            else if (maxDir > 0) optimalExposure = expDir;
+            else if (maxPt > 0) optimalExposure = expPt;
+
+            optimalExposure = Math.max(0.00001, Math.min(optimalExposure, 5.0));
+
+            renderer.toneMappingExposure = optimalExposure;
+            scene.environmentIntensity = 0.0;
+
+            ambientLight.visible = false;
+            hemiLight.visible = false;
+            keyLight.visible = false;
+            fillLight.visible = false;
+            rimLight.visible = false;
+          }
+
           // --- Apply Animation State if requested ---
           let appliedAnim = false;
           if (gltf.animations && gltf.animations.length > 0) {
@@ -477,6 +582,35 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             vertices.push(center.x, center.y, center.z);
           }
 
+          // Dynamically scale shadow biases and camera bounds based on actual model size
+          const shadowCamSize = initialDim * 1.5;
+          const shadowScale = initialDim / 10.0;
+
+          if (sceneHasLights) {
+            gltf.scene.traverse((child) => {
+              if (child.isLight && child.shadow) {
+                child.shadow.bias = -0.0005 * shadowScale;
+                child.shadow.normalBias = 0.02 * shadowScale;
+
+                if (child.isDirectionalLight) {
+                  child.shadow.camera.left = -shadowCamSize;
+                  child.shadow.camera.right = shadowCamSize;
+                  child.shadow.camera.top = shadowCamSize;
+                  child.shadow.camera.bottom = -shadowCamSize;
+                  child.shadow.camera.near = Math.max(0.01, initialDim * 0.01);
+                  child.shadow.camera.far = shadowCamSize * 4;
+                  child.shadow.camera.updateProjectionMatrix();
+                  child.shadow.mapSize.width = 2048;
+                  child.shadow.mapSize.height = 2048;
+                } else if (child.isPointLight || child.isSpotLight) {
+                  child.shadow.camera.near = Math.max(0.01, initialDim * 0.01);
+                  child.shadow.camera.far = shadowCamSize * 4;
+                  child.shadow.camera.updateProjectionMatrix();
+                }
+              }
+            });
+          }
+
           const fovY = (camera.fov * Math.PI) / 180;
           const tanY = Math.tan(fovY / 2);
           const tanX = tanY * camera.aspect;
@@ -611,7 +745,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const content = [
         {
           type: "text",
-          text: `Successfully compiled SCAD and rendered ${snapshots.length} camera angle(s)${appliedAnimStr}. Please analyze these visual results to determine your next adjustments.`,
+          text: `Successfully compiled SCAD and rendered ${snapshots.length} camera angle(s)${appliedAnimStr}. Please analyze these visual results to determine your next adjustments.\n\nLive Editor Preview URL: ${previewUrl}`,
         },
       ];
 
@@ -746,16 +880,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const originalProjectGodot = fs.readFileSync(projectGodotPath, "utf8");
       let playResult;
 
+      // 1.5 Prepare MCP Runner Autoload Script (ALWAYS inject to ensure a clean exit)
+      const snapTime = Math.max(0.5, runTime - 0.5);
+
+      let runnerScript = `extends Node\nfunc _ready():\n\tprint("[MCP] Autoload ready. Waiting ${snapTime} seconds...")\n\tawait get_tree().create_timer(${snapTime}).timeout\n`;
+
+      // If returning images, inject the screenshot capture logic
       if (returnImages) {
-        // 1.5 Prepare Screenshot Autoload Script
-        const snapTime = Math.max(0.5, runTime - 0.5);
-
-        const screenshotScript = `extends Node
-func _ready():
-\tprint("[ScreenshotMCP] Autoload ready. Waiting ${snapTime} seconds...")
-\tawait get_tree().create_timer(${snapTime}).timeout
-\tvar ds = DisplayServer.get_name()
-\tprint("[ScreenshotMCP] DisplayServer is: ", ds)
+        runnerScript += `\tvar ds = DisplayServer.get_name()
+\tprint("[MCP] DisplayServer is: ", ds)
 \tif ds != "headless":
 \t\tawait RenderingServer.frame_post_draw
 \t\tvar tex = get_viewport().get_texture()
@@ -770,34 +903,37 @@ func _ready():
 \t\t\t\tvar cropped = img.get_region(Rect2i(x, y, size, size))
 \t\t\t\tvar path = ProjectSettings.globalize_path("res://screenshot_mcp.png")
 \t\t\t\tvar err = cropped.save_png(path)
-\t\t\t\tprint("[ScreenshotMCP] Save PNG to ", path, " returned error code: ", err)
+\t\t\t\tprint("[MCP] Save PNG to ", path, " returned error code: ", err)
 \t\t\telse:
-\t\t\t\tprint("[ScreenshotMCP] Error: Image is null or empty.")
+\t\t\t\tprint("[MCP] Error: Image is null or empty.")
 \t\telse:
-\t\t\tprint("[ScreenshotMCP] Error: Viewport texture is null.")
-\tget_tree().quit()
-`;
-        fs.writeFileSync(
-          path.join(projectDir, "screenshot_mcp.gd"),
-          screenshotScript,
+\t\t\tprint("[MCP] Error: Viewport texture is null.")\n`;
+      }
+
+      // Always force Godot to quit gracefully from the inside
+      runnerScript += `\tget_tree().quit()\n`;
+
+      fs.writeFileSync(path.join(projectDir, "mcp_runner.gd"), runnerScript);
+
+      let tempProjectGodot = originalProjectGodot;
+      if (tempProjectGodot.includes("[autoload]")) {
+        tempProjectGodot = tempProjectGodot.replace(
+          "[autoload]",
+          '[autoload]\nMCPRunner="*res://mcp_runner.gd"',
         );
+      } else {
+        tempProjectGodot += `\n[autoload]\nMCPRunner="*res://mcp_runner.gd"\n`;
+      }
+      fs.writeFileSync(projectGodotPath, tempProjectGodot, "utf8");
 
-        let tempProjectGodot = originalProjectGodot;
-        if (tempProjectGodot.includes("[autoload]")) {
-          tempProjectGodot = tempProjectGodot.replace(
-            "[autoload]",
-            '[autoload]\nScreenshotMCP="*res://screenshot_mcp.gd"',
-          );
-        } else {
-          tempProjectGodot += `\n[autoload]\nScreenshotMCP="*res://screenshot_mcp.gd"\n`;
-        }
-        fs.writeFileSync(projectGodotPath, tempProjectGodot, "utf8");
+      // 2. Run Project Step
+      // Give the Node wrapper a +5000ms buffer so the internal Godot timer always finishes first
+      const safeNodeTimeout = runTime * 1000 + 5000;
 
-        // 2. Run Project Step
-        // Always try windowed first to get the screenshot.
-        // If the environment lacks a display server, we'll catch the error and fallback.
+      if (returnImages) {
+        // Windowed first to get the screenshot
         let playArgs = [
-          "--windowed", // Use windowed instead of headless to ensure rendering works for screenshot
+          "--windowed",
           "--resolution",
           "512x512",
           "--audio-driver",
@@ -806,13 +942,7 @@ func _ready():
           projectDir,
         ];
 
-        playResult = await runGodotAsync(
-          playArgs,
-          projectDir,
-          // Give Godot extra buffer time to boot, take the shot, and quit gracefully
-          runTime * 1000 + 5000,
-        );
-
+        playResult = await runGodotAsync(playArgs, projectDir, safeNodeTimeout);
         let windowedOutput = playResult.output;
 
         // Fallback if windowed mode fails due to display server issues
@@ -824,30 +954,29 @@ func _ready():
           playResult = await runGodotAsync(
             ["--headless", "--audio-driver", "Dummy", "--path", projectDir],
             projectDir,
-            runTime * 1000,
+            safeNodeTimeout,
           );
-          // Explicitly inject the display error into the final output so we aren't flying blind!
           playResult.output =
             "--- WINDOWED LAUNCH FAILED (Display Error) ---\n" +
             windowedOutput.trim() +
             "\n\n--- FALLBACK HEADLESS LAUNCH ---\n" +
             playResult.output;
         }
-
-        // 3. Cleanup Autoloads
-        fs.writeFileSync(projectGodotPath, originalProjectGodot, "utf8");
-        if (fs.existsSync(path.join(projectDir, "screenshot_mcp.gd"))) {
-          fs.unlinkSync(path.join(projectDir, "screenshot_mcp.gd"));
-        }
       } else {
         // Text-only mode: Run headless immediately
         playResult = await runGodotAsync(
           ["--headless", "--audio-driver", "Dummy", "--path", projectDir],
           projectDir,
-          runTime * 1000,
+          safeNodeTimeout,
         );
       }
 
+      // 3. Cleanup Autoloads
+      fs.writeFileSync(projectGodotPath, originalProjectGodot, "utf8");
+      if (fs.existsSync(path.join(projectDir, "mcp_runner.gd"))) {
+        fs.unlinkSync(path.join(projectDir, "mcp_runner.gd"));
+      }
+
       // 4. Read Screenshot
       let screenshotBase64 = null;
       if (returnImages) {