create-threejs-game 1.0.0

package/template/prompts/04-execution-plan.md

@@ -0,0 +1,89 @@
+# Execution Plan Generation Prompt
+
+## Tool
+LLM with Three.js skills enabled (Claude Code, Cursor, etc.)
+
+**IMPORTANT:** Start a NEW CHAT with clear context
+
+## Files to Attach
+- `docs/prd.md` - Product requirements
+- `docs/tdd.md` - Technical design
+- `public/assets/{game_name}/assets.json` - Asset index
+
+## Prompt Template
+
+```
+Implement the game defined in docs/prd.md adhering to the technical design 
+in docs/tdd.md.
+
+Note the assets index in public/assets/{game_name}/assets.json.
+
+Use the Three.js skills for implementation patterns.
+
+Create an execution plan that:
+
+## Overview
+- Target file(s) to create
+- Key references to PRD and TDD sections
+- Asset path format
+
+## Implementation Phases
+For each phase, specify:
+- Phase name and priority (Critical/Important/Polish)
+- What to implement
+- Key code sections from TDD to use
+- Verification steps
+
+Suggested phases:
+1. Core Engine (Critical) - Scene, camera, lighting, ground
+2. Asset Loading (Critical) - GLTF loader, fallbacks
+3. ECS Architecture (Critical) - Entities, components, manager
+4. Selection System (Critical) - Click/box select, visuals
+5. Command System (Critical) - Move, attack commands
+6. Movement System (Critical) - Unit movement, collision
+7. Combat System (Critical) - Damage, death
+8. Economy/Resource System (Important) - If applicable
+9. AI System (Important) - Enemy behavior
+10. UI & Game States (Important) - Menus, HUD
+11. Effects (Polish) - Juice, particles
+12. Mobile/Polish (Polish) - Touch controls, onboarding
+
+## HTML File Structure
+Show the expected structure:
+- DOCTYPE, head, meta tags
+- Style block organization
+- Import map for Three.js
+- Script module organization
+
+## Map Setup
+- Initial entity positions
+- Resource placement
+- Obstacle placement
+
+## Verification Checklist
+From PRD success criteria, list what must work:
+- [ ] Game loads without errors
+- [ ] [Other criteria...]
+
+## Estimated Scope
+- Approximate lines of code
+- Expected complexity
+```
+
+## Output
+Save to: `plans/{descriptive-name}.md`
+
+**Naming convention:** Use a memorable name like:
+- `plans/initial-implementation.md`
+- `plans/core-gameplay.md`
+- Or use a random word generator for unique names
+
+## Next Step
+After saving the plan, proceed to implementation:
+
+```
+Please proceed with implementing the game based on the plan in 
+plans/{plan-name}.md
+
+Use the Three.js skills for reference.
+```

package/template/prompts/05-implementation.md

@@ -0,0 +1,61 @@
+# Implementation Prompt
+
+## Tool
+Claude Code / Cursor with Three.js skills enabled
+
+## Files to Attach
+- `plans/{plan-name}.md` - The execution plan
+
+## Prompt Template
+
+```
+Please proceed with implementing the game based on the plan in 
+plans/{plan-name}.md
+
+Use the Three.js skills for reference.
+```
+
+## What to Expect
+The AI will:
+1. Read the plan and understand the phased approach
+2. Create the HTML file structure
+3. Implement each phase sequentially
+4. Test and verify as it goes
+
+## During Implementation
+You may need to:
+- Answer clarifying questions
+- Approve file creations
+- Test the game in browser and report issues
+- Request adjustments to specific features
+
+## Common Follow-up Prompts
+
+**If something doesn't work:**
+```
+The [feature] isn't working correctly. When I [action], it [actual behavior] 
+instead of [expected behavior]. Can you fix this?
+```
+
+**To add a feature:**
+```
+Can you add [feature] to the game? It should [description of behavior].
+```
+
+**To improve performance:**
+```
+The game is running slowly. Can you optimize [specific system/area]?
+```
+
+**To adjust visuals:**
+```
+Can you adjust the [visual element] to be more [description]?
+```
+
+**To test specific functionality:**
+```
+Can you verify that [specific feature] works by [test steps]?
+```
+
+## Verification
+After implementation, test all items in the plan's verification checklist.

package/template/scripts/config.example.json

@@ -0,0 +1,12 @@
+{
+  "google_ai_studio": {
+    "api_key": "YOUR_GOOGLE_AI_STUDIO_API_KEY"
+  },
+  "anthropic": {
+    "api_key": "YOUR_ANTHROPIC_API_KEY"
+  },
+  "game": {
+    "name": "your_game_name",
+    "description": "A 3D real-time strategy game set in a medieval fantasy world where players gather resources, build bases, and destroy the enemy."
+  }
+}

package/template/scripts/generate-assets-json.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+/**
+ * Asset Index Generator
+ * 
+ * Generates an assets.json file that indexes all assets in a game's asset folder.
+ * 
+ * Usage:
+ *   node generate-assets-json.js <game_name>
+ * 
+ * Example:
+ *   node generate-assets-json.js medieval
+ * 
+ * This will scan public/assets/medieval/ and create public/assets/medieval/assets.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Get game name from command line argument
+const gameName = process.argv[2];
+
+if (!gameName) {
+  console.error('Usage: node generate-assets-json.js <game_name>');
+  console.error('Example: node generate-assets-json.js medieval');
+  process.exit(1);
+}
+
+// Paths
+const scriptDir = __dirname;
+const projectRoot = path.join(scriptDir, '..');
+const assetsDir = path.join(projectRoot, 'public', 'assets', gameName);
+const outputPath = path.join(assetsDir, 'assets.json');
+
+// Check if assets directory exists
+if (!fs.existsSync(assetsDir)) {
+  console.error(`Error: Assets directory not found: ${assetsDir}`);
+  console.error(`Please create the directory and add your assets first.`);
+  process.exit(1);
+}
+
+// File extensions to index
+const SUPPORTED_EXTENSIONS = {
+  '3d': ['.gltf', '.glb', '.obj', '.fbx'],
+  'images': ['.png', '.jpg', '.jpeg', '.webp', '.gif'],
+  'audio': ['.mp3', '.wav', '.ogg'],
+  'other': ['.json', '.txt']
+};
+
+// Get category from extension
+function getCategory(ext) {
+  ext = ext.toLowerCase();
+  
+  if (SUPPORTED_EXTENSIONS['3d'].includes(ext)) {
+    return ext === '.gltf' || ext === '.glb' ? 'glTF' : '3D';
+  }
+  if (SUPPORTED_EXTENSIONS.images.includes(ext)) {
+    return 'PNG'; // Keep as PNG for consistency with existing format
+  }
+  if (SUPPORTED_EXTENSIONS.audio.includes(ext)) {
+    return 'Audio';
+  }
+  return 'Other';
+}
+
+// Recursively scan directory for assets
+function scanDirectory(dir, relativeTo) {
+  const assets = [];
+  
+  if (!fs.existsSync(dir)) {
+    return assets;
+  }
+  
+  const items = fs.readdirSync(dir, { withFileTypes: true });
+  
+  for (const item of items) {
+    const fullPath = path.join(dir, item.name);
+    
+    if (item.isDirectory()) {
+      // Recursively scan subdirectories
+      assets.push(...scanDirectory(fullPath, relativeTo));
+    } else if (item.isFile()) {
+      const ext = path.extname(item.name).toLowerCase();
+      
+      // Skip if not a supported extension or is the output file itself
+      if (item.name === 'assets.json') continue;
+      
+      const allExtensions = [
+        ...SUPPORTED_EXTENSIONS['3d'],
+        ...SUPPORTED_EXTENSIONS.images,
+        ...SUPPORTED_EXTENSIONS.audio
+      ];
+      
+      if (!allExtensions.includes(ext)) continue;
+      
+      const relativePath = path.relative(relativeTo, fullPath);
+      const category = getCategory(ext);
+      
+      assets.push({
+        name: item.name,
+        path: `public/assets/${gameName}/${relativePath.replace(/\\/g, '/')}`,
+        relativePath: relativePath.replace(/\\/g, '/'),
+        category: category,
+        extension: ext,
+        focusGlTF: ext === '.gltf' || ext === '.glb'
+      });
+    }
+  }
+  
+  return assets;
+}
+
+// Main execution
+console.log(`Scanning assets in: ${assetsDir}`);
+
+const assets = scanDirectory(assetsDir, assetsDir);
+
+// Sort assets by name
+assets.sort((a, b) => a.name.localeCompare(b.name));
+
+// Count by category
+const categoryCounts = {};
+for (const asset of assets) {
+  categoryCounts[asset.category] = (categoryCounts[asset.category] || 0) + 1;
+}
+
+// Count glTF assets
+const glTFCount = assets.filter(a => a.focusGlTF).length;
+
+// Build output
+const output = {
+  metadata: {
+    generatedAt: new Date().toISOString(),
+    root: `public/assets/${gameName}`,
+    totalAssets: assets.length,
+    glTFAssetCount: glTFCount,
+    categories: categoryCounts
+  },
+  assets: assets
+};
+
+// Write output
+fs.writeFileSync(outputPath, JSON.stringify(output, null, 2));
+
+console.log(`\nGenerated: ${outputPath}`);
+console.log(`\nSummary:`);
+console.log(`  Total assets: ${assets.length}`);
+console.log(`  glTF/GLB models: ${glTFCount}`);
+console.log(`  Categories:`, categoryCounts);

package/template/scripts/generate-mockup.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+/**
+ * Mockup Generation Script
+ * 
+ * Uses Google AI Studio (Gemini) to generate a game concept mockup
+ * based on the asset preview and description.
+ * 
+ * Usage:
+ *   node generate-mockup.js
+ * 
+ * Requires:
+ *   - config.json with google_ai_studio.api_key and game settings
+ *   - public/assets/{game_name}/Preview.jpg
+ *   - public/assets/{game_name}/assets.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+// Load config
+const scriptDir = __dirname;
+const projectRoot = path.join(scriptDir, '..');
+const configPath = path.join(scriptDir, 'config.json');
+
+if (!fs.existsSync(configPath)) {
+  console.error('Error: config.json not found');
+  console.error('Copy config.example.json to config.json and add your API keys');
+  process.exit(1);
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+const { google_ai_studio, game } = config;
+
+// Check config first, then env vars
+const apiKey = (google_ai_studio?.api_key && !google_ai_studio.api_key.includes('YOUR_'))
+  ? google_ai_studio.api_key
+  : process.env.GOOGLE_API_KEY || process.env.GOOGLE_AI_STUDIO_API_KEY;
+
+if (!apiKey) {
+  console.error('Error: Google AI Studio API key not found');
+  console.error('Set GOOGLE_API_KEY env var or configure scripts/config.json');
+  process.exit(1);
+}
+
+// Use resolved key
+google_ai_studio.api_key = apiKey;
+
+// Paths
+const assetsDir = path.join(projectRoot, 'public', 'assets', game.name);
+const previewPath = path.join(assetsDir, 'Preview.jpg');
+const assetsJsonPath = path.join(assetsDir, 'assets.json');
+const outputDir = path.join(projectRoot, 'public', game.name);
+const outputPath = path.join(outputDir, 'concept.jpg');
+
+// Check required files
+if (!fs.existsSync(previewPath)) {
+  console.error(`Error: Preview image not found: ${previewPath}`);
+  process.exit(1);
+}
+
+if (!fs.existsSync(assetsJsonPath)) {
+  console.error(`Error: assets.json not found: ${assetsJsonPath}`);
+  console.error('Run: node generate-assets-json.js ' + game.name);
+  process.exit(1);
+}
+
+// Read files
+const previewImage = fs.readFileSync(previewPath);
+const previewBase64 = previewImage.toString('base64');
+const assetsJson = JSON.parse(fs.readFileSync(assetsJsonPath, 'utf-8'));
+
+// Build asset summary (just glTF names for brevity)
+const assetNames = assetsJson.assets
+  .filter(a => a.focusGlTF)
+  .map(a => a.name.replace('.gltf', ''))
+  .join(', ');
+
+// Build prompt
+const prompt = `You are a game concept artist. Based on the attached preview image showing available 3D assets and the following game description, create a detailed mockup image showing how this game would look during gameplay.
+
+GAME DESCRIPTION:
+${game.description}
+
+AVAILABLE ASSETS (3D models):
+${assetNames}
+
+The mockup should show:
+1. An actual gameplay scene (not a title screen)
+2. Multiple game elements arranged naturally (buildings, units, terrain, resources)
+3. Appropriate UI elements for this game type (health bars, resource counters, minimap, etc.)
+4. The camera perspective that best suits this game type
+5. The visual style matching the provided assets
+
+Create a polished, professional game screenshot mockup that shows the core gameplay loop in action.`;
+
+console.log('Generating mockup with Google AI Studio...');
+console.log('Game:', game.name);
+console.log('Description:', game.description);
+
+// Gemini API request
+const requestBody = JSON.stringify({
+  contents: [{
+    parts: [
+      {
+        text: prompt
+      },
+      {
+        inline_data: {
+          mime_type: 'image/jpeg',
+          data: previewBase64
+        }
+      }
+    ]
+  }],
+  generationConfig: {
+    responseModalities: ['image', 'text'],
+    responseMimeType: 'image/jpeg'
+  }
+});
+
+const options = {
+  hostname: 'generativelanguage.googleapis.com',
+  port: 443,
+  path: `/v1beta/models/gemini-2.0-flash-exp:generateContent?key=${google_ai_studio.api_key}`,
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(requestBody)
+  }
+};
+
+const req = https.request(options, (res) => {
+  let data = '';
+  
+  res.on('data', (chunk) => {
+    data += chunk;
+  });
+  
+  res.on('end', () => {
+    try {
+      const response = JSON.parse(data);
+      
+      if (response.error) {
+        console.error('API Error:', response.error.message);
+        process.exit(1);
+      }
+      
+      // Find image in response
+      const candidates = response.candidates || [];
+      let imageData = null;
+      
+      for (const candidate of candidates) {
+        const parts = candidate.content?.parts || [];
+        for (const part of parts) {
+          if (part.inline_data?.mime_type?.startsWith('image/')) {
+            imageData = part.inline_data.data;
+            break;
+          }
+        }
+        if (imageData) break;
+      }
+      
+      if (!imageData) {
+        console.error('No image generated in response');
+        console.error('Response:', JSON.stringify(response, null, 2));
+        process.exit(1);
+      }
+      
+      // Ensure output directory exists
+      if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+      }
+      
+      // Save image
+      const imageBuffer = Buffer.from(imageData, 'base64');
+      fs.writeFileSync(outputPath, imageBuffer);
+      
+      console.log('\nMockup generated successfully!');
+      console.log('Output:', outputPath);
+      
+    } catch (err) {
+      console.error('Error parsing response:', err.message);
+      console.error('Raw response:', data.substring(0, 500));
+      process.exit(1);
+    }
+  });
+});
+
+req.on('error', (err) => {
+  console.error('Request error:', err.message);
+  process.exit(1);
+});
+
+req.write(requestBody);
+req.end();