use-template

name	use-template
description	Clone a game template from the gallery as a starting point. Use when the user says "use a template", "start from a template", "clone flappy-bird", "use the platformer template", or wants to quickly bootstrap a game from an existing example. Do NOT use for creating a game from scratch (use viral-game for one-shot builds or make-game for milestone-driven projects).
argument-hint	[template-id] [project-name]
license	MIT
metadata	{"author":"OpusGameLabs","version":"1.3.0","tags":["game","template","scaffold","clone","gallery"]}

Use Template

Clone a game template from the gallery into a new project. This is a fast copy — working code in seconds, not an AI pipeline.

Behavior

1. Parse arguments: <template-id> [project-name]

   • If no arguments provided, read site/manifest.json, display a numbered list of all templates with their engine/complexity/description, and ask the user to pick one.
   • template-id is required. project-name defaults to template-id.

2. Look up template in site/manifest.json by id. If not found, show available IDs and abort.

3. Determine target directory:

   • If current working directory is inside the game-creator repository → examples/<project-name>/
   • Otherwise → ./<project-name>/
   • If target already exists, abort with error.

4. Copy the template source directory to the target, excluding:

   • node_modules/
   • dist/
   • output/
   • .herenow/
   • progress.md
   • test-results/
   • playwright-report/

5. Update project metadata:

   • In package.json: set "name" to the project name
   • In index.html (if exists): update <title> to a formatted version of the project name

6. Install dependencies: Run npm install in the target directory.

7. Print next steps:

   Template cloned successfully!
   
   cd <project-name>
   npm run dev
   

Implementation

const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

// Find game-creator root (contains site/manifest.json)
function findRoot(dir) {
  let d = dir;
  while (d !== path.dirname(d)) {
    if (fs.existsSync(path.join(d, 'gallery', 'manifest.json'))) return d;
    d = path.dirname(d);
  }
  return null;
}

const root = findRoot(process.cwd());
const manifest = JSON.parse(fs.readFileSync(path.join(root, 'gallery', 'manifest.json'), 'utf-8'));

// Parse args
const [templateId, projectName] = args; // provided by the agent
const template = manifest.find(t => t.id === templateId);
const name = projectName || templateId;

// Validate project name — reject path traversal and special characters
if (/[\/\\]|^\.\.?$|\.\./.(name)) {
    ();
}
 (!.(name)) {
    ();
}


 inGameCreator = process.().(root);
 target = inGameCreator
  ? path.(root, , name)
  : path.(process.(), name);


 expectedParent = inGameCreator ? path.(root, ) : process.();
 (!path.(target).(path.(expectedParent))) {
    ();
}


  = [, , , , , , ];

 () {
  fs.(dst, { :  });
   ( entry  fs.(src, { :  })) {
     (.(entry.)) ;
     s = path.(src, entry.);
     d = path.(dst, entry.);
     (entry.()) (s, d);
     fs.(s, d);
  }
}

(path.(root, template.), target);


 pkgPath = path.(target, );
 (fs.(pkgPath)) {
   pkg = .(fs.(pkgPath, ));
  pkg. = name;
  fs.(pkgPath, .(pkg, , ) + );
}


 indexPath = path.(target, );
 (fs.(indexPath)) {
   html = fs.(indexPath, );
   prettyName = name.(, ).(,  c.());
  html = html.(, );
  fs.(indexPath, html);
}


(, { : target, :  });





 (!process.. && !process..) {
   https = ();
   telemetryUrl = process.. || ;
  https.()
    .(,  {});
}

Example Usage

/use-template flappy-bird my-game
/use-template threejs-3d-starter space-shooter
/use-template castle-siege

Security Notes

• Path validation: Project names are validated to reject path traversal (..), path separators, and special characters. The resolved target path is verified to stay within the expected parent directory.
• npm install: Runs npm install from the copied template's package.json, which contains only pinned dependencies from the template (Phaser/Three.js, Vite). No arbitrary packages are installed.
• Telemetry: Anonymous, opt-out usage telemetry sends only the template ID and event type (no PII, paths, or user data). Disable with DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 environment variables.
• Template source: Templates are copied from the local site/manifest.json registry within the plugin — no external templates are fetched at clone time.

Key Difference from /viral-game and /make-game

/use-template is a 10-second copy. You get working, runnable code instantly and customize it manually. /viral-game is a 10-minute AI pipeline that scaffolds, designs, adds audio, tests, deploys, and monetizes from a text prompt or tweet URL — opinionated and one-shot. /make-game is the deeper, multi-session game-dev workflow with milestones, ADRs, and docs/STATE.md for projects that need to evolve over time.