create-threejs-game 1.0.0 → 1.0.5

package/README.md

@@ -2,70 +2,67 @@
 
 Scaffold a Three.js game project with AI-assisted design documents.
 
-## Quick Start
-
-```bash
-npx create-threejs-game my-game
-cd my-game
-# Add assets to public/assets/my_game/
-node scripts/pipeline.js
-```
+## Prerequisites
 
-## What it does
+Before running the CLI, have these ready:
 
-This CLI creates a Three.js game project with:
+### 1. 3D Assets (Required)
+Download a GLTF asset pack from:
+- [itch.io](https://itch.io/game-assets/tag-3d)
+- [Kenney.nl](https://kenney.nl/assets)
+- [Quaternius](https://quaternius.com/)
 
-- **Three.js skills** for Claude/Codex AI assistance
-- **Automation scripts** to generate:
-  - Asset index (assets.json)
-  - Concept mockup (via Google AI Studio)
-  - Product Requirements Document (PRD)
-  - Technical Design Document (TDD)
-  - Implementation plan
-- **Prompt templates** for each generation step
+The CLI will ask for the path to your downloaded assets folder and validate it contains `.gltf` or `.glb` files.
 
-## Interactive Setup
+### 2. Preview Image (Recommended)
+Most asset packs include a `Preview.jpg`. If not, take a screenshot of your assets. This is used by the AI to generate concept mockups.
 
-Run without arguments for interactive mode:
+### 3. API Keys (Required for automation)
+Set these as environment variables for the smoothest experience:
 
 ```bash
-npx create-threejs-game
+export GOOGLE_API_KEY="your-key"      # or GOOGLE_AI_STUDIO_API_KEY
+export ANTHROPIC_API_KEY="your-key"
 ```
 
-You'll be asked for:
-1. Project name
-2. Game description (1-3 sentences)
-3. API keys (only if not found in environment)
-
-**Supported environment variables:**
-- `GOOGLE_API_KEY` or `GOOGLE_AI_STUDIO_API_KEY`
-- `ANTHROPIC_API_KEY`
-
-## Manual Steps
+Get keys from:
+- [Google AI Studio](https://aistudio.google.com/) - free tier available
+- [Anthropic Console](https://console.anthropic.com/)
 
-After scaffolding, you'll need to:
+If not set, the CLI will prompt for them.
 
-1. **Add your 3D assets** to `public/assets/{game_name}/`
-   - Download from itch.io, Kenney.nl, Quaternius, etc.
-   - GLTF format preferred
-
-2. **Add Preview.jpg** to the assets folder
-   - Most asset packs include one
-   - Or screenshot your assets
+## Quick Start
 
-3. **Configure API keys** in `scripts/config.json`:
-   - Google AI Studio: for mockup generation
-   - Anthropic: for PRD/TDD/plan generation
+```bash
+npx create-threejs-game
+```
 
-## Automated Pipeline
+The CLI will:
+1. Ask for your **project name**
+2. Ask for a **game description** (1-3 sentences describing your game)
+3. Check for **API keys** (from env vars, or prompt if missing)
+4. Ask for **path to your assets folder** (required for automation)
+5. Validate everything and tell you if anything is missing
+6. Create your project with assets copied in
 
-Once configured, run:
+Then run the automation:
 
 ```bash
+cd my-game
 node scripts/pipeline.js
 ```
 
-This generates all design documents automatically, leaving you with an implementation plan to follow in Claude Code or Cursor.
+## What Gets Generated
+
+The automation pipeline creates:
+
+| Step | Output | AI Service |
+|------|--------|------------|
+| Asset Index | `public/assets/{game}/assets.json` | Local script |
+| Concept Mockup | `public/{game}/concept.jpg` | Google AI Studio |
+| PRD | `docs/prd.md` | Claude (Anthropic) |
+| TDD | `docs/tdd.md` | Claude (Anthropic) |
+| Execution Plan | `plans/plan.md` | Claude (Anthropic) |
 
 ## Project Structure
 
@@ -75,22 +72,29 @@ my-game/
 ├── .codex/skills/       # Three.js skills for Codex
 ├── docs/                # Generated PRD and TDD
 ├── plans/               # Generated implementation plans
-├── prompts/             # Manual prompt templates (fallback)
+├── prompts/             # Prompt templates (fallback/reference)
 ├── public/
-│   └── assets/{game}/   # Your 3D assets go here
+│   └── assets/{game}/   # Your 3D assets (copied by CLI)
 ├── scripts/
-│   ├── config.json      # Your configuration
+│   ├── config.json      # API keys and game config
 │   ├── pipeline.js      # Run full automation
 │   └── generate-*.js    # Individual generators
-└── README.md            # Detailed workflow guide
+└── README.md
+```
+
+## Final Step
+
+After the pipeline completes, open your project in Claude Code or Cursor and follow the generated execution plan:
+
+```
+Please proceed with implementing based on the plan in plans/plan.md
 ```
 
 ## Requirements
 
 - Node.js 18+
-- API keys (for automation):
-  - [Google AI Studio](https://aistudio.google.com/) - free tier available
-  - [Anthropic](https://console.anthropic.com/) - API access required
+- API keys (see Prerequisites)
+- 3D assets in GLTF format
 
 ## License
 

package/bin/cli.js

@@ -194,6 +194,67 @@ async function main() {
     console.log('');
   }
   
+  // Ask for assets location (required for automation)
+  console.log(c('bright', '📁 3D Assets (Required)'));
+  console.log(c('dim', '─'.repeat(50)));
+  console.log(c('dim', 'The automation pipeline needs 3D assets to generate mockups and docs.'));
+  console.log(c('dim', 'Download a GLTF asset pack from itch.io, Kenney.nl, etc. first.\n'));
+  
+  let assetsSourcePath = '';
+  
+  while (!assetsSourcePath) {
+    let inputPath = await ask(c('bright', 'Path to assets folder'));
+    
+    if (!inputPath) {
+      const skipAnyway = await confirm(
+        c('yellow', 'Without assets, the automation pipeline cannot run. Skip anyway?'),
+        false
+      );
+      if (skipAnyway) {
+        console.log(c('yellow', '\n  ⚠ No assets provided. You\'ll need to add them manually before running the pipeline.\n'));
+        break;
+      }
+      continue;
+    }
+    
+    // Expand ~ to home directory
+    if (inputPath.startsWith('~')) {
+      inputPath = path.join(process.env.HOME || process.env.USERPROFILE, inputPath.slice(1));
+    }
+    
+    // Resolve relative paths
+    if (!path.isAbsolute(inputPath)) {
+      inputPath = path.resolve(process.cwd(), inputPath);
+    }
+    
+    // Validate path
+    if (!fs.existsSync(inputPath)) {
+      console.log(c('red', `  ✗ Path not found: ${inputPath}`));
+      console.log(c('dim', '  Please check the path and try again.\n'));
+      continue;
+    }
+    
+    const stat = fs.statSync(inputPath);
+    if (!stat.isDirectory()) {
+      console.log(c('red', '  ✗ Path is not a directory.'));
+      console.log(c('dim', '  Please provide a folder path.\n'));
+      continue;
+    }
+    
+    // Check if it has any gltf/glb files
+    const hasModels = fs.readdirSync(inputPath, { recursive: true })
+      .some(f => f.endsWith('.gltf') || f.endsWith('.glb'));
+    
+    if (!hasModels) {
+      console.log(c('yellow', '  ⚠ No .gltf or .glb files found in this folder.'));
+      const useAnyway = await confirm('Use this folder anyway?', false);
+      if (!useAnyway) continue;
+    }
+    
+    assetsSourcePath = inputPath;
+    console.log(c('green', '  ✓ ') + 'Assets folder validated\n');
+  }
+  
   // Copy template
   console.log(c('bright', '📦 Creating project...'));
   console.log(c('dim', '─'.repeat(50)));
@@ -244,8 +305,31 @@ async function main() {
   // Create assets directory
   const assetsDir = path.join(projectPath, 'public', 'assets', gameName);
   fs.mkdirSync(assetsDir, { recursive: true });
-  fs.writeFileSync(path.join(assetsDir, '.gitkeep'), '');
-  console.log(c('green', '  ✓ ') + `public/assets/${gameName}/`);
+  
+  // Copy assets if path was provided
+  if (assetsSourcePath) {
+    console.log(c('dim', '  Copying assets...'));
+    copyDir(assetsSourcePath, assetsDir, ['node_modules', '.git', '.DS_Store']);
+    
+    // Count copied files
+    const countFiles = (dir) => {
+      let count = 0;
+      const items = fs.readdirSync(dir, { withFileTypes: true });
+      for (const item of items) {
+        if (item.isDirectory()) {
+          count += countFiles(path.join(dir, item.name));
+        } else {
+          count++;
+        }
+      }
+      return count;
+    };
+    const fileCount = countFiles(assetsDir);
+    console.log(c('green', '  ✓ ') + `public/assets/${gameName}/ (${fileCount} files copied)`);
+  } else {
+    fs.writeFileSync(path.join(assetsDir, '.gitkeep'), '');
+    console.log(c('green', '  ✓ ') + `public/assets/${gameName}/`);
+  }
   
   console.log('');
   console.log(c('green', `✅ Project created at: ${projectPath}`));
@@ -264,21 +348,34 @@ async function main() {
   const steps = [];
   let stepNum = 1;
   
-  // Step: Add assets
-  steps.push({
-    num: stepNum++,
-    manual: true,
-    text: `Add your 3D assets to ${c('cyan', `public/assets/${gameName}/`)}`,
-    detail: 'Download a GLTF asset pack from itch.io, Kenney.nl, or similar'
-  });
+  // Check if assets were copied and if Preview exists
+  const hasAssets = assetsSourcePath && fs.existsSync(assetsDir);
+  const previewExists = hasAssets && (
+    fs.existsSync(path.join(assetsDir, 'Preview.jpg')) ||
+    fs.existsSync(path.join(assetsDir, 'Preview.png')) ||
+    fs.existsSync(path.join(assetsDir, 'preview.jpg')) ||
+    fs.existsSync(path.join(assetsDir, 'preview.png'))
+  );
+  
+  // Step: Add assets (only if not already copied)
+  if (!hasAssets) {
+    steps.push({
+      num: stepNum++,
+      manual: true,
+      text: `Add your 3D assets to ${c('cyan', `public/assets/${gameName}/`)}`,
+      detail: 'Download a GLTF asset pack from itch.io, Kenney.nl, or similar'
+    });
+  }
   
-  // Step: Add preview
-  steps.push({
-    num: stepNum++,
-    manual: true,
-    text: `Ensure ${c('cyan', 'Preview.jpg')} exists in the assets folder`,
-    detail: 'Most asset packs include one, or take a screenshot of your assets'
-  });
+  // Step: Add preview (only if not found)
+  if (!previewExists) {
+    steps.push({
+      num: stepNum++,
+      manual: true,
+      text: `Ensure ${c('cyan', 'Preview.jpg')} exists in the assets folder`,
+      detail: 'Most asset packs include one, or take a screenshot of your assets'
+    });
+  }
   
   // Step: API keys
   if (!hasGoogleKey || !hasAnthropicKey) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-threejs-game",
-  "version": "1.0.0",
+  "version": "1.0.5",
   "description": "Scaffold a Three.js game project with AI-assisted design documents",
   "bin": {
     "create-threejs-game": "./bin/cli.js"