scad-gltf 0.1.3 → 0.2.1

package/README.md

@@ -22,7 +22,8 @@ The C++ source code for this custom OpenSCAD version is included directly in thi
 - **CLI Converter:** Bundled `scad-convert` CLI utility for single file and batch compiling `.scad` files with smart dependency hashing.
 - **MCP Server for AI Agents:** Bundled `scad-mcp` server enables MCP clients to iteratively design, compile, and **visually inspect** 3D models via multi-angle headless rendering and animation frame evaluation.
 - **AI Studio Extension:** Chrome extension to natively preview, prompt, take chat snapshots, open in Scadify, and locally save AI-generated 3D models directly inside Google AI Studio.
-- **Godot 4 Integration & Web Demos:** Native Godot 4 importer addon for procedural `.scad` assets and prebuilt AI-generated [web game examples](https://iliagrigorevdev.github.io/scad-godot/).
+- **Godot 4, Rust Bevy & Web Integration:** Native Godot 4 importer addon, Rust Bevy compile-time `build.rs` integration, and prebuilt AI-generated game examples for Godot and Bevy.
+- **Automated AI Generation:** Pass an OpenAI-compatible base URL (and optional API key) to the `scad-godot`, `scad-bevy`, or `scad-web` CLI to automatically spawn a local MCP server, query the LLM via standard endpoints, allow it to visually iterate, and output a ready-to-run project generator script.
 
 ---
 
@@ -219,6 +220,7 @@ When asking an LLM (like Gemini) to generate OpenSCAD code, the extension automa
 - **Instant 3D Preview:** Injects a **"Preview 3D"** button on any OpenSCAD code block to compile and render the model in an embedded 3D viewer with grid, wireframe, and full-screen support.
 - **Visual Chat Feedback (📷):** Click the snapshot button inside the 3D preview window to capture a PNG snapshot of the model and **automatically paste it into the AI Studio chat input**, allowing Gemini to visually evaluate and fix geometry.
 - **Smart Prompt Injection:** Click the floating **"✨ SCAD"** button to open the configuration modal. Select your desired engine feature set (PBR, auto-smooth, animations, baking) to automatically generate and inject the prompt rules into your chat input.
+- **Local Model Refinement:** Connect to your local `scad-serve` workspace directly from the prompt modal. Select an existing `.scad` file to automatically append its source code to your prompt as a reference, enabling seamless AI iteration and refinement of your existing local designs.
 - **Open in Scadify:** Click **"Edit"** in the preview window to immediately transfer the current script into the full standalone Scadify editor via compressed URL hash.
 - **Local Workspace Saving:** Directly save and overwrite models to your local directory when running `scad-serve`.
 
@@ -259,6 +261,7 @@ Instead of generating code blindly, the AI can compile its script, render the 3D
 
 - `get_scad_prompt`: Injects the custom OpenSCAD syntax rules (PBR, animations, baking) into the AI's context.
 - `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_bevy_project` / `test_godot_project`: Tests the generated game projects for compilation and runtime errors.
 
 ### Setup
 
@@ -294,6 +297,53 @@ Try prebuilt AI-generated Godot games directly in your browser: [https://iliagri
 
 ---
 
+### Automated AI Generation (OpenAI-Compatible API)
+
+By default, `scad-godot`, `scad-bevy`, and `scad-web` copy 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-mcp` server in the background, connect it to your LLM, and allow the AI to _visually evaluate and fix_ its 3D models in real-time before saving the final `generate_project.js` script to your disk.
+
+**Option 1: Using OpenAI (GPT-4o)**
+
+```bash
+export OPENAI_BASE_URL="https://api.openai.com/v1"
+export OPENAI_API_KEY="sk-..."
+export OPENAI_MODEL="gpt-4o"
+scad-bevy "A 3D spaceship shooter game"
+```
+
+**Option 2: Using Google Gemini (via OpenAI compatibility)**
+Because Gemini provides an official OpenAI-compatible endpoint, you can configure it using standard OpenAI variables:
+
+```bash
+export OPENAI_API_KEY="AIzaSy..."
+export OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
+export OPENAI_MODEL="gemini-3.8-flash"
+scad-godot "A fast-paced 3D hovercraft racing game"
+```
+
+**Option 3: Using Local Server**
+You can use completely local, uncensored, or fine-tuned vision models by overriding the OpenAI Base URL to point to a local inference server (like `llama.cpp`'s API server).
+
+```bash
+export OPENAI_BASE_URL="http://127.0.0.1:8080/v1"
+export OPENAI_MODEL="llama-3" # Or whatever model name you've loaded
+scad-web "A 3D configurator app"
+```
+
+**Passing Parameters via JSON**
+You can also pass credentials inline as a JSON string argument instead of modifying environment variables:
+
+```bash
+scad-godot "A futuristic tank game" '{"openaiBaseUrl": "http://127.0.0.1:8080/v1", "openaiModel": "llama-3"}'
+```
+
+_Once the automated process completes, simply run the generated Node.js script to assemble your complete Godot, Bevy, or Vite project structure with all assets and code!_
+
+```bash
+node generate_godot_project.js
+```
+
+---
+
 ## Extended OpenSCAD Syntax
 
 This custom fork introduces new syntax not found in standard OpenSCAD.
@@ -420,8 +470,6 @@ const promptContext = generatePrompt(description, {
 console.log(promptContext);
 ```
 
----
-
 ### Workflow
 
 Once connected, an AI assistant can use the server to execute the following loop:
@@ -490,7 +538,3 @@ This repository includes a custom fork of OpenSCAD in the `openscad/` subfolder
 - **Path Tracing:** The web editor utilizes [three-gpu-pathtracer](https://github.com/gkjohnson/three-gpu-pathtracer) for high-quality rendering.
 - **Environment Map (HDR)**: [Aristea Wreck Puresky](https://polyhaven.com/a/aristea_wreck_puresky) by **Jarod Guest** via [Poly Haven](https://polyhaven.com/). Licensed under [CC0](https://polyhaven.com/license).
 - **License:** See the `LICENSE` file (GPL-2.0 or later, inheriting from standard OpenSCAD).
-
-```
-
-```

package/bin/scad-bevy.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+import { runCliApp } from "../src/cli-utils.js";
+
+async function main() {
+  await runCliApp({
+    projectType: "bevy",
+    buildSystemPrompt: (
+      promptRules,
+    ) => `You are an expert Rust Bevy engine game developer and procedural 3D technical artist.
+
+NAMING CONVENTION REQUIREMENT:
+- All generated files, directories, models, scripts, and root folders MUST strictly use snake_case (lowercase with underscores, e.g. \`player_character.rs\`, \`enemy_walker.scad\`).
+- NEVER use hyphens/minus signs (\`-\`) or spaces in any file or folder names.
+
+What to generate:
+1. 3D Game Assets (.scad):
+   - Generate procedural 3D models for the game using OpenSCAD.
+   - CRITICAL: The SCAD to glTF converter automatically converts OpenSCAD's Z-up coordinate system to the standard glTF Y-up coordinate system. Design your models naturally in OpenSCAD.
+   - CRITICAL: You must use the custom OpenSCAD glTF extensions for PBR materials (e.g., \`roughness\`, \`metalness\`, \`emissive\`) and Hierarchical Node Animations (\`armature()\`, \`bone()\`). The rules and syntax for these features are provided below:
+
+=== OPENSCAD SYNTAX RULES ===
+${promptRules}
+=============================
+
+2. Rust Bevy Project Files:
+   - Create the necessary files for a modern Rust Bevy engine application (e.g., \`Cargo.toml\`, \`build.rs\`, \`src/main.rs\`).
+   - In \`Cargo.toml\`, include \`bevy\` as a dependency.
+   - You MUST include this EXACT \`build.rs\` script at the root of the project to automatically compile the \`.scad\` files into \`.glb\` format inside the \`assets/models\` folder before running the game via Cargo:
+     \`\`\`rust
+     use std::process::Command;
+
+     fn main() {
+         // Tell Cargo to re-run this script only if the 'scad' directory changes
+         println!("cargo::rerun-if-changed=scad");
+
+         // Ensure cross-platform compatibility for npm global binaries
+         let cmd = if cfg!(target_os = "windows") {
+             "scad-convert.cmd"
+         } else {
+             "scad-convert"
+         };
+
+         let status = Command::new(cmd)
+             .args(["./scad", "./assets/models", "--cache"])
+             .status()
+             .expect("Failed to execute scad-convert. Is scad-gltf installed globally?");
+
+         if !status.success() {
+             panic!("scad-convert failed with status: {}", status);
+         }
+     }
+     \`\`\`
+   - Write the core application logic in \`src/main.rs\` to load and display the converted \`.glb\` files interactively. Provide standard Bevy game systems (camera, lights, movement, etc.).
+
+3. Delivery Format (Single Node.js Script):
+   - Output exactly ONE self-contained Node.js script. Do not output manual setup instructions.
+   - CRITICAL: The generated Node.js script MUST first create a root project folder (named using a slugified version of the project name) and output all files and folders inside this newly created project folder.
+   - When executed, this script must programmatically create the entire project directory structure and write all the files to disk using the \`fs\` module.
+   - The script must embed and write:
+     - Your generated \`.scad\` 3D assets.
+     - Your generated Rust Bevy project files (\`Cargo.toml\`, \`build.rs\`, \`src/main.rs\`).
+   - Ensure all string file contents inside the Node.js script are properly escaped.`,
+    buildInputRequest: (task) =>
+      `Design and implement a Rust Bevy engine game for the following concept: "${task}"`,
+    allowedTools: ["render_scad_model", "compile_bevy_project"],
+  });
+}
+
+// Execute and handle unhandled runtime errors
+main().catch((err) => {
+  console.error("An unexpected error occurred:", err);
+  process.exit(1);
+});

package/bin/scad-gen.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { runCliApp } from "../src/cli-utils.js";
+
+async function main() {
+  await runCliApp({
+    projectType: "gen",
+    buildSystemPrompt: () =>
+      `You are an expert procedural 3D technical artist and OpenSCAD developer.
+Your goal is to generate a single OpenSCAD (.scad) file based on the user's request.
+
+CRITICAL WORKFLOW:
+1. Write the OpenSCAD code using the custom syntax rules provided in the request.
+2. Call the \`render_scad_model\` tool with your code to visually verify your design.
+3. If the model looks incorrect, adjust your code and re-render. Iterate until perfect.
+4. Provide your final OpenSCAD code in a standard markdown block (\`\`\`openscad).`,
+    allowedTools: ["render_scad_model"],
+  });
+}
+
+// Execute and handle unhandled runtime errors
+main().catch((err) => {
+  console.error("An unexpected error occurred:", err);
+  process.exit(1);
+});

package/bin/scad-godot.js

@@ -3,143 +3,20 @@
 import fs from "node:fs";
 import path from "node:path";
 import url from "node:url";
-import readline from "node:readline";
+import { runCliApp } from "../src/cli-utils.js";
 
-// Safely resolve symlinks to find the actual package directory
-const __filename = fs.realpathSync(url.fileURLToPath(import.meta.url));
+const __filename = url.fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const DIR = path.resolve(__dirname, "..");
 
-// Safely detect if actual data is being piped into the script via STDIN
-function hasStdinData() {
-  try {
-    const stat = fs.fstatSync(0); // 0 is the file descriptor for STDIN
-    // isFIFO means piped (echo "foo" | script)
-    // isFile means redirected (script < foo.txt)
-    return stat.isFIFO() || stat.isFile();
-  } catch (e) {
-    return false;
-  }
-}
-
-// Writes text to system clipboard
-async function writeToClipboard(text) {
-  const clipboardy = (await import("clipboardy")).default;
-  await clipboardy.write(text);
-}
-
-function waitForEnter(message) {
-  return new Promise((resolve) => {
-    // If standard input was piped/redirected, we need to bypass it and read from the actual terminal
-    if (!process.stdin.isTTY) {
-      try {
-        const tty = process.platform === "win32" ? "CONIN$" : "/dev/tty";
-        const fd = fs.openSync(tty, "rs");
-        process.stdout.write(message);
-        const buf = Buffer.alloc(1);
-        fs.readSync(fd, buf, 0, 1, null);
-        fs.closeSync(fd);
-        console.log();
-        resolve();
-        return;
-      } catch (e) {
-        console.log(
-          message +
-            " (Auto-continuing due to non-interactive terminal environment)",
-        );
-        resolve();
-        return;
-      }
-    }
-
-    // For standard TTY terminals
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-    rl.question(message, () => {
-      rl.close();
-      resolve();
-    });
-  });
-}
-
 async function main() {
-  let task = "";
-  let optionsStr = "{}";
-
-  // 1. Read TASK and OPTIONS
-  if (hasStdinData()) {
-    try {
-      task = fs.readFileSync(0, "utf-8").trim();
-    } catch (e) {
-      console.error("Error reading from STDIN:", e);
-    }
-    if (process.argv[2]) optionsStr = process.argv[2];
-  } else {
-    if (process.argv[2]) task = process.argv[2];
-    if (process.argv[3]) optionsStr = process.argv[3];
-  }
-
-  if (!task) {
-    console.error("Error: Task parameter is required.");
-    console.error(
-      'Usage: scad-godot "<description of the game to generate>" [options_json]',
-    );
-    console.error('   or: echo "<description>" | scad-godot [options_json]');
-    console.error("");
-    console.error("Example with JSON options:");
-    console.error(
-      '  scad-godot "Game description" \'{"animation": false, "bakeColors": true}\'',
-    );
-    process.exit(1);
-  }
-
-  // 2. Parse Options JSON
-  // Disable heavy PBR features by default
-  let options = {
-    transmission: false,
-    clearcoat: false,
-    sheen: false,
-    iridescence: false,
-  };
-
-  if (optionsStr) {
-    try {
-      const parsed = JSON.parse(optionsStr);
-      options = { ...options, ...parsed }; // User provided options override defaults
-    } catch (e) {
-      console.error(`Invalid JSON options: ${optionsStr}`);
-      process.exit(1);
-    }
-  }
-
-  // Disable the modelName instructions specifically for the Godot wrapper context
-  options.modelName = false;
+  await runCliApp({
+    projectType: "godot",
+    buildSystemPrompt: (promptRules, options) => {
+      const hasUserScadFiles =
+        Array.isArray(options.scadFiles) && options.scadFiles.length > 0;
 
-  // 3. Dynamically import and generate prompt rules from src/prompt.js
-  let generatePrompt;
-  try {
-    const promptJsPath = path.join(DIR, "src", "prompt.js");
-    const promptModuleUrl = url.pathToFileURL(promptJsPath).href;
-    const m = await import(promptModuleUrl);
-    generatePrompt = m.generatePrompt;
-  } catch (e) {
-    console.error(`Error loading ${path.join("src", "prompt.js")}:`, e);
-    process.exit(1);
-  }
-
-  let promptRules = "";
-  try {
-    promptRules = generatePrompt("the 3D assets for the game", options);
-  } catch (e) {
-    console.error("Error generating prompt rules from prompt.js:");
-    console.error(e);
-    process.exit(1);
-  }
-
-  // 4. Construct the Main Godot Prompt System Text (System Instructions)
-  const systemPrompt = `You are an expert Godot 4 game developer and procedural 3D technical artist.
+      const systemPrompt = `You are an expert Godot 4 game developer and procedural 3D technical artist.
 
 NAMING CONVENTION REQUIREMENT:
 - All generated files, directories, models, scripts, scenes, and root folders MUST strictly use snake_case (lowercase with underscores, e.g. \`player_character.gd\`, \`main_scene.tscn\`, \`enemy_walker.scad\`).
@@ -185,83 +62,75 @@ ${promptRules}
    - The script must embed and write:
      - Your generated \`.scad\` game assets.
      - Your generated Godot project files.
-     - The exact source code of the provided \`addons/scad_importer/*\` files, placed in their correct respective paths.
-   - Ensure all string file contents inside the Node.js script are properly escaped.`;
-
-  // 5. Gather Addon Files content
-  const addonDir = path.join(DIR, "godot", "addons", "scad_importer");
-  let addonFiles = [];
-  try {
-    if (fs.existsSync(addonDir)) {
-      const files = fs.readdirSync(addonDir);
-      for (const file of files) {
-        const fullPath = path.join(addonDir, file);
-        // Ensure we only read text files to prevent binary/hidden files
-        // from introducing control characters that crash browser UIs.
-        if (
-          fs.statSync(fullPath).isFile() &&
-          (file.endsWith(".gd") || file.endsWith(".cfg"))
-        ) {
-          addonFiles.push(fullPath);
+     - The exact source code of the provided \`addons/scad_importer/*\` files, placed in their correct respective paths.${
+       hasUserScadFiles
+         ? "\n     - The exact source code of the provided user `.scad` files, placed in the appropriate project folders."
+         : ""
+     }
+   - Ensure all string file contents inside the Node.js script are properly escaped.
+   - TESTING CAPABILITY: You have access to the \`test_godot_project\` tool. If you want to verify your code before outputting your final response, you can pass your complete generated Node.js script as the \`nodejs_script\` parameter. The server will execute it in a temporary folder and run the Godot tests automatically.`;
+
+      // Gather Addon Files content
+      const addonDir = path.join(DIR, "godot", "addons", "scad_importer");
+      let addonFiles = [];
+      try {
+        if (fs.existsSync(addonDir)) {
+          const files = fs.readdirSync(addonDir);
+          for (const file of files) {
+            const fullPath = path.join(addonDir, file);
+            if (
+              fs.statSync(fullPath).isFile() &&
+              (file.endsWith(".gd") || file.endsWith(".cfg"))
+            ) {
+              addonFiles.push(fullPath);
+            }
+          }
         }
+      } catch (e) {
+        console.error("Warning: Could not read addon directory.", e);
       }
-    }
-  } catch (e) {
-    console.error("Warning: Could not read addon directory.", e);
-  }
-
-  // 6. Format the unified system instructions clipboard output
-  let systemClipboardOutput = `${systemPrompt}\n\n`;
-
-  for (const file of addonFiles) {
-    try {
-      // Normalize line endings to avoid mixed line-ending layout loops in web editors
-      const content = fs.readFileSync(file, "utf-8").replace(/\r\n/g, "\n");
-      // Format to use relative paths and force forward slashes for LLM clarity
-      const relativePath = path.relative(DIR, file).replace(/\\/g, "/");
-
-      // Add explicit language tags to prevent catastrophic regex backtracking
-      // during the Markdown parser's language auto-detection step.
-      const lang = file.endsWith(".gd") ? "gdscript" : "text";
-      systemClipboardOutput += `### ${relativePath}\n---\n\`\`\`${lang}\n${content}\n\`\`\`\n\n`;
-    } catch (e) {
-      console.error(`Warning: Skipping '${file}'. It is not a readable file.`);
-    }
-  }
 
-  systemClipboardOutput = systemClipboardOutput.trimEnd() + "\n";
-
-  // 7. Format the input request output
-  const inputRequestOutput = `Design and implement a Godot 4 project for the following game concept: "${task}"`;
-
-  // 8. Write to System Clipboard (Part 1: System Instructions)
-  try {
-    await writeToClipboard(systemClipboardOutput);
-    console.log("✔️  System instructions have been copied to the clipboard.");
-  } catch (err) {
-    console.error(
-      "Error: Failed to copy system instructions to the clipboard.",
-    );
-    console.error(err.message);
-    process.exit(1);
-  }
+      let systemClipboardOutput = `${systemPrompt}\n\n`;
+
+      for (const file of addonFiles) {
+        try {
+          const content = fs.readFileSync(file, "utf-8").replace(/\r\n/g, "\n");
+          const relativePath = path.relative(DIR, file).replace(/\\/g, "/");
+          const lang = file.endsWith(".gd") ? "gdscript" : "text";
+          systemClipboardOutput += `### ${relativePath}\n---\n\`\`\`${lang}\n${content}\n\`\`\`\n\n`;
+        } catch (e) {
+          console.error(
+            `Warning: Skipping '${file}'. It is not a readable file.`,
+          );
+        }
+      }
 
-  // 9. Await user confirmation
-  await waitForEnter(
-    "Please paste the system instructions into your LLM, then press ENTER to copy your input request...",
-  );
+      if (hasUserScadFiles) {
+        systemClipboardOutput += `=== USER PROVIDED OPENSCAD FILES ===\n`;
+        systemClipboardOutput += `The following .scad files are provided as reference or base assets. You MUST embed and write them into the generated project, modifying them if necessary to fit the game logic.\n\n`;
+        for (const file of options.scadFiles) {
+          try {
+            const content = fs
+              .readFileSync(file, "utf-8")
+              .replace(/\r\n/g, "\n");
+            const relativePath = path.isAbsolute(file)
+              ? path.relative(process.cwd(), file).replace(/\\/g, "/")
+              : file.replace(/\\/g, "/");
+            systemClipboardOutput += `### ${relativePath}\n---\n\`\`\`openscad\n${content}\n\`\`\`\n\n`;
+          } catch (e) {
+            console.error(
+              `Warning: Skipping user SCAD file '${file}'. It is not a readable file.`,
+            );
+          }
+        }
+      }
 
-  // 10. Write to System Clipboard (Part 2: Input Request)
-  try {
-    await writeToClipboard(inputRequestOutput);
-    console.log(
-      "✔️  Input request has been copied to the clipboard. You can now paste it into your LLM.",
-    );
-  } catch (err) {
-    console.error("Error: Failed to copy input request to the clipboard.");
-    console.error(err.message);
-    process.exit(1);
-  }
+      return systemClipboardOutput.trimEnd() + "\n";
+    },
+    buildInputRequest: (task) =>
+      `Design and implement a Godot 4 project for the following game concept: "${task}"`,
+    allowedTools: ["render_scad_model", "test_godot_project"],
+  });
 }
 
 // Execute and handle unhandled runtime errors