create-threejs-game 1.0.5 → 1.1.0

package/README.md

@@ -7,15 +7,24 @@ Scaffold a Three.js game project with AI-assisted design documents.
 Before running the CLI, have these ready:
 
 ### 1. 3D Assets (Required)
-Download a GLTF asset pack from:
+Download GLTF asset packs from:
 - [itch.io](https://itch.io/game-assets/tag-3d)
 - [Kenney.nl](https://kenney.nl/assets)
 - [Quaternius](https://quaternius.com/)
 
 The CLI will ask for the path to your downloaded assets folder and validate it contains `.gltf` or `.glb` files.
 
-### 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.
+**Multi-Pack Support:** You can combine multiple asset packs by organizing them in subdirectories:
+```
+my-assets/
+├── characters/      # Asset pack 1 (with Preview.jpg)
+├── buildings/       # Asset pack 2 (with Preview.jpg)
+└── environment/     # Asset pack 3 (with Preview.jpg)
+```
+The CLI auto-detects this structure and combines all preview images into a single grid.
+
+### 2. Preview Image (Auto-generated for multi-packs)
+Most asset packs include a `Preview.jpg`. For multi-pack directories, the CLI automatically combines all subdirectory previews into one image. For single packs without a preview, take a screenshot of your assets.
 
 ### 3. API Keys (Required for automation)
 Set these as environment variables for the smoothest experience:
@@ -74,6 +83,8 @@ my-game/
 ├── plans/               # Generated implementation plans
 ├── prompts/             # Prompt templates (fallback/reference)
 ├── public/
+│   ├── {game}/
+│   │   └── concept.jpg  # Generated mockup
 │   └── assets/{game}/   # Your 3D assets (copied by CLI)
 ├── scripts/
 │   ├── config.json      # API keys and game config

package/bin/cli.js

@@ -16,6 +16,14 @@ const path = require('path');
 const readline = require('readline');
 const { execSync, spawn } = require('child_process');
 
+// Sharp for image processing (optional, for combining previews)
+let sharp;
+try {
+  sharp = require('sharp');
+} catch (e) {
+  // Sharp not available - preview combining will be skipped
+}
+
 // Colors for terminal output
 const colors = {
   reset: '\x1b[0m',
@@ -91,6 +99,118 @@ function copyDir(src, dest, exclude = []) {
   }
 }
 
+// Find preview image in a directory
+function findPreview(dir) {
+  const previewNames = ['Preview.jpg', 'Preview.png', 'preview.jpg', 'preview.png', 
+                        'Preview.jpeg', 'preview.jpeg'];
+  for (const name of previewNames) {
+    const previewPath = path.join(dir, name);
+    if (fs.existsSync(previewPath)) {
+      return previewPath;
+    }
+  }
+  return null;
+}
+
+// Detect if directory is a multi-pack (has subdirs with previews)
+function detectMultiPack(sourceDir) {
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+  const subdirs = entries.filter(e => e.isDirectory());
+  
+  if (subdirs.length === 0) return null;
+  
+  const packsWithPreviews = [];
+  
+  for (const subdir of subdirs) {
+    const subdirPath = path.join(sourceDir, subdir.name);
+    const preview = findPreview(subdirPath);
+    if (preview) {
+      packsWithPreviews.push({
+        name: subdir.name,
+        path: subdirPath,
+        preview: preview
+      });
+    }
+  }
+  
+  // Consider it a multi-pack if at least 2 subdirs have previews
+  if (packsWithPreviews.length >= 2) {
+    return packsWithPreviews;
+  }
+  
+  return null;
+}
+
+// Combine preview images into a grid
+async function combinePreviews(packs, outputPath) {
+  if (!sharp) {
+    console.log(c('yellow', '  ⚠ sharp not available - skipping preview combination'));
+    return null;
+  }
+  
+  const cellWidth = 512;
+  const cellHeight = 512;
+  const padding = 10;
+  const backgroundColor = { r: 30, g: 30, b: 30, alpha: 1 };
+  
+  const cols = Math.ceil(Math.sqrt(packs.length));
+  const rows = Math.ceil(packs.length / cols);
+  const totalWidth = cols * cellWidth + (cols + 1) * padding;
+  const totalHeight = rows * cellHeight + (rows + 1) * padding;
+  
+  console.log(c('dim', `  Creating ${cols}x${rows} combined preview...`));
+  
+  const composites = [];
+  
+  for (let i = 0; i < packs.length; i++) {
+    const pack = packs[i];
+    const col = i % cols;
+    const row = Math.floor(i / cols);
+    
+    const x = padding + col * (cellWidth + padding);
+    const y = padding + row * (cellHeight + padding);
+    
+    try {
+      const resized = await sharp(pack.preview)
+        .resize(cellWidth, cellHeight, {
+          fit: 'contain',
+          background: backgroundColor
+        })
+        .toBuffer();
+      
+      composites.push({
+        input: resized,
+        left: x,
+        top: y
+      });
+    } catch (err) {
+      console.log(c('yellow', `  ⚠ Failed to process ${pack.name}: ${err.message}`));
+    }
+  }
+  
+  if (composites.length === 0) return null;
+  
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  
+  await sharp({
+    create: {
+      width: totalWidth,
+      height: totalHeight,
+      channels: 4,
+      background: backgroundColor
+    }
+  })
+    .composite(composites)
+    .jpeg({ quality: 90 })
+    .toFile(outputPath);
+  
+  return outputPath;
+}
+
 // Run a script
 function runScript(scriptPath, args = [], cwd) {
   return new Promise((resolve, reject) => {
@@ -307,7 +427,21 @@ async function main() {
   fs.mkdirSync(assetsDir, { recursive: true });
   
   // Copy assets if path was provided
+  let isMultiPack = false;
+  let multiPackInfo = null;
+  
   if (assetsSourcePath) {
+    // Check if this is a multi-pack directory
+    multiPackInfo = detectMultiPack(assetsSourcePath);
+    isMultiPack = multiPackInfo !== null;
+    
+    if (isMultiPack) {
+      console.log(c('cyan', `  Detected multi-pack with ${multiPackInfo.length} asset packs:`));
+      for (const pack of multiPackInfo) {
+        console.log(c('dim', `    - ${pack.name}`));
+      }
+    }
+    
     console.log(c('dim', '  Copying assets...'));
     copyDir(assetsSourcePath, assetsDir, ['node_modules', '.git', '.DS_Store']);
     
@@ -326,6 +460,17 @@ async function main() {
     };
     const fileCount = countFiles(assetsDir);
     console.log(c('green', '  ✓ ') + `public/assets/${gameName}/ (${fileCount} files copied)`);
+    
+    // Combine previews if multi-pack
+    if (isMultiPack && sharp) {
+      try {
+        const combinedPreviewPath = path.join(assetsDir, 'Preview.jpg');
+        await combinePreviews(multiPackInfo, combinedPreviewPath);
+        console.log(c('green', '  ✓ ') + 'Combined preview image generated');
+      } catch (err) {
+        console.log(c('yellow', `  ⚠ Could not combine previews: ${err.message}`));
+      }
+    }
   } else {
     fs.writeFileSync(path.join(assetsDir, '.gitkeep'), '');
     console.log(c('green', '  ✓ ') + `public/assets/${gameName}/`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-threejs-game",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Scaffold a Three.js game project with AI-assisted design documents",
   "bin": {
     "create-threejs-game": "./bin/cli.js"
@@ -25,5 +25,8 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "sharp": "^0.33.0"
   }
 }

package/template/scripts/combine-previews.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+/**
+ * Combine Preview Images
+ * 
+ * Scans a directory for subdirectories containing Preview.jpg/png files
+ * and combines them into a single grid image.
+ * 
+ * Usage: node combine-previews.js <source-dir> <output-path>
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// We'll use sharp for image processing - it's fast and handles this well
+let sharp;
+try {
+  sharp = require('sharp');
+} catch (e) {
+  console.error('Error: sharp module not found.');
+  console.error('Install it with: npm install sharp');
+  process.exit(1);
+}
+
+/**
+ * Find all preview images in subdirectories
+ */
+function findPreviews(sourceDir) {
+  const previews = [];
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+  
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    
+    const subdir = path.join(sourceDir, entry.name);
+    const previewNames = ['Preview.jpg', 'Preview.png', 'preview.jpg', 'preview.png', 
+                          'Preview.jpeg', 'preview.jpeg'];
+    
+    for (const name of previewNames) {
+      const previewPath = path.join(subdir, name);
+      if (fs.existsSync(previewPath)) {
+        previews.push({
+          path: previewPath,
+          name: entry.name
+        });
+        break;
+      }
+    }
+  }
+  
+  return previews;
+}
+
+/**
+ * Calculate grid dimensions for N images
+ */
+function calculateGrid(count) {
+  const cols = Math.ceil(Math.sqrt(count));
+  const rows = Math.ceil(count / cols);
+  return { cols, rows };
+}
+
+/**
+ * Combine images into a grid
+ */
+async function combineImages(previews, outputPath, options = {}) {
+  const {
+    cellWidth = 512,
+    cellHeight = 512,
+    padding = 10,
+    backgroundColor = { r: 30, g: 30, b: 30, alpha: 1 }
+  } = options;
+  
+  if (previews.length === 0) {
+    console.log('No preview images found.');
+    return null;
+  }
+  
+  if (previews.length === 1) {
+    // Just copy the single preview
+    fs.copyFileSync(previews[0].path, outputPath);
+    console.log(`Copied single preview: ${previews[0].name}`);
+    return outputPath;
+  }
+  
+  const { cols, rows } = calculateGrid(previews.length);
+  const totalWidth = cols * cellWidth + (cols + 1) * padding;
+  const totalHeight = rows * cellHeight + (rows + 1) * padding;
+  
+  console.log(`Creating ${cols}x${rows} grid (${totalWidth}x${totalHeight}px) for ${previews.length} previews...`);
+  
+  // Prepare each image
+  const composites = [];
+  
+  for (let i = 0; i < previews.length; i++) {
+    const preview = previews[i];
+    const col = i % cols;
+    const row = Math.floor(i / cols);
+    
+    const x = padding + col * (cellWidth + padding);
+    const y = padding + row * (cellHeight + padding);
+    
+    try {
+      // Resize image to fit cell while maintaining aspect ratio
+      const resized = await sharp(preview.path)
+        .resize(cellWidth, cellHeight, {
+          fit: 'contain',
+          background: backgroundColor
+        })
+        .toBuffer();
+      
+      composites.push({
+        input: resized,
+        left: x,
+        top: y
+      });
+      
+      console.log(`  [${i + 1}/${previews.length}] ${preview.name}`);
+    } catch (err) {
+      console.error(`  Failed to process ${preview.name}: ${err.message}`);
+    }
+  }
+  
+  // Create the combined image
+  const combined = sharp({
+    create: {
+      width: totalWidth,
+      height: totalHeight,
+      channels: 4,
+      background: backgroundColor
+    }
+  });
+  
+  await combined
+    .composite(composites)
+    .jpeg({ quality: 90 })
+    .toFile(outputPath);
+  
+  console.log(`\nCombined preview saved to: ${outputPath}`);
+  return outputPath;
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.length < 2) {
+    console.log('Usage: node combine-previews.js <source-dir> <output-path>');
+    console.log('');
+    console.log('Scans source-dir for subdirectories with Preview.jpg/png');
+    console.log('and combines them into a single grid image.');
+    process.exit(1);
+  }
+  
+  const sourceDir = args[0];
+  const outputPath = args[1];
+  
+  if (!fs.existsSync(sourceDir)) {
+    console.error(`Error: Source directory not found: ${sourceDir}`);
+    process.exit(1);
+  }
+  
+  const previews = findPreviews(sourceDir);
+  
+  if (previews.length === 0) {
+    console.log('No subdirectories with preview images found.');
+    console.log('Looking for: Preview.jpg, Preview.png, preview.jpg, preview.png');
+    process.exit(0);
+  }
+  
+  console.log(`Found ${previews.length} preview images:\n`);
+  
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  
+  await combineImages(previews, outputPath);
+}
+
+// Export for use as module
+module.exports = { findPreviews, combineImages, calculateGrid };
+
+// Run if called directly
+if (require.main === module) {
+  main().catch(err => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
+}