dewctl 0.5.4 → 0.6.0

package/examples/AGENTS.md

@@ -0,0 +1,132 @@
+# Working on this game
+
+This is a three.js game for Dewdrop. Dewdrop draws each frame from the scene, in the style the game describes.
+The docs are at https://alpha.dewdrop.world/docs, and each rule below links the page with the details.
+
+## 1. Agree the look with the user first
+
+Before you build or restyle anything, ask the user for a specific look:
+- the style or medium, such as clay, paper, ink sketch, watercolor or voxel;
+- the setting and the time of day;
+- the palette and the mood;
+- the camera: first or third person, and how close.
+
+If the answer is vague ("make it look nice"), offer three or four of these looks from the
+[style recipes](https://alpha.dewdrop.world/docs/recipes), the nearest to what the user wants, and let them choose:
+- **Clay:** matte plasticine with thumbprints, chunky rounded shapes, saturated colors, a tabletop set.
+- **Knitted wool:** chunky knitted yarn and soft felt, visible stitches, plump rounded forms, a cozy craft diorama.
+- **Paper:** folded and cut colored paper and card, sharp creases, white cut edges.
+- **Voxel:** everything built from small cubes, in flat saturated colors.
+- **Cartoon / anime:** cel-shaded with clean dark outlines, a bright summer afternoon.
+- **Ink sketch:** thin black ink outlines on white paper, no shading, no color.
+- **Watercolor:** soft washes fading into bare white paper, no outlines.
+- **Picture book:** crisp ink outlines and loose watercolor washes on warm cream paper.
+- **Colored pencil:** pencil hatching on textured cream paper, warm earthy colors with saturated accents.
+- **Stained glass:** jewel-colored glass panes in dark lead, glowing like a lit window at night.
+- **Neon cyberpunk:** a city at night in the rain, magenta and cyan tubes, wet black ground.
+- **Noir:** black and white, hard light, razor-sharp black shadows, a wet street at night.
+- **Horror:** a candlelit house at night, pitch-black beyond the candlelight, cold blue moonlight.
+- **Winter:** deep midwinter, thick fresh snow, bare trees, warm lamplight in the windows.
+- **Golden hour:** gouache countryside under a low warm sun, gold highlights, cool blue-green shade.
+- **Underwater:** murky teal water, god rays from the surface, caustic light on the sea floor.
+
+So you never stall:
+- If `renderer.prompt` already starts with `style:`, the look is chosen. Keep it and don't ask.
+- If nobody can answer, pick the nearest recipe, say which in your first message, and keep the look in one place.
+
+Write the agreed look where the prompt lives: `src/look.js` in a starter game, `renderer.prompt` in `src/main.js`
+in the Blank game. Ask again before you change the style.
+
+## 2. How Dewdrop makes a frame
+
+Dewdrop renders the game from what is in the three.js scene ([renderer](https://alpha.dewdrop.world/docs/renderer)):
+- `renderer.prompt`: the style of the whole game. It starts with `style:` and the style, then describes the scene:
+  `'style: claymation. A handmade plasticine miniature on a dark blue studio backdrop.'`
+- `scene.background`, a `THREE.Color`, and `renderer.backgroundDescription`, the sky in words.
+- Each mesh's shape, its base color (its material's `color`) and its `userData.description`.
+
+Textures, vertex colors, emissive colors, lights, shadows, fog, custom shaders, points, lines and sprites don't
+show on Dewdrop. The prompt is at most 4 KiB, the background description and each description at most 1 KiB. A
+scene draws at most 65,536 objects: each mesh counts once, and so does each instance.
+The view is 16:9 ([limits](https://alpha.dewdrop.world/docs/limits#the-look)).
+
+## 3. The rules that matter most
+
+The controls, strongest first: colors, descriptions, shapes, light and shadow, then the prompt and the background.
+A new look usually means changing the first three together.
+
+- **Color carries the most.** A mesh comes out at its base color, whatever the words say. Very dark colors for
+  night, close to white for a drawing on paper. Set a color on every mesh: colors don't pass down the scene graph.
+- **Dark means very dark.** Dewdrop lifts dark colors. For black, stay under about `#12` in each channel and say
+  "black". For deep darkness, use `#02` to `#06` and words such as "in deep shadow"
+  ([colors](https://alpha.dewdrop.world/docs/renderer#colors)).
+- **Describe what the camera sees, in the style's words:** "the back of an owl's head" behind a character,
+  "a plasticine tree". Use one description for each kind of object.
+- **Keep color words in step with the colors.** "Terracotta" on a pale roof came out red, and "pale cream wall"
+  came out white on a dark wall. Name the material without its lightness
+  ([descriptions](https://alpha.dewdrop.world/docs/renderer#descriptions)).
+- A group's description reaches every mesh under it that has none of its own; `null` gives none, and a mesh's
+  `name` is never used ([scene graph](https://alpha.dewdrop.world/docs/descriptions)).
+- **Don't name objects in the prompt.** Describe them on their meshes. The prompt can't override the colors.
+- **Dewdrop keeps your shapes.** A style made of shapes needs them: cubes for voxel, folded flat faces for paper,
+  rounded lumpy forms for clay. A realistic look needs realistic shapes. A face needs eye and nose meshes. Build the
+  letters you want read ([shapes](https://alpha.dewdrop.world/docs/renderer#shapes)).
+- **A light is a mesh.** Three.js lights don't show on Dewdrop. Give a lamp or candle a bright mesh described as
+  glowing. Night is every surface at about a fifth of its daylight color, with the lights in view. Words don't light
+  a surface; warmth comes from color. A shadow is a thin dark mesh on the ground
+  ([light and shadow](https://alpha.dewdrop.world/docs/renderer#light-and-shadow)).
+- **The sky is the background.** Describe it in `renderer.backgroundDescription`, not the prompt, with a matching
+  `scene.background` color. A gradient and the sun come from the words; a sun disc mesh shows as a flat coin. Big
+  clouds are stacked white spheres about 1 km or more away. Flat bands or panels in the sky become a wall
+  ([background](https://alpha.dewdrop.world/docs/renderer#style-prompt-and-background)).
+- Mist, rain and god rays come from the words. `scene.fog` doesn't show; to fade distance, or for pools of light
+  and sunlight, bake them into colors ([baked light](https://alpha.dewdrop.world/docs/baked-light)).
+- **Keep the camera clear.** A mesh very close to the camera becomes a big smooth blob. Keep scenery and moving
+  parts a few meters from anywhere the camera goes. In first person, hold items 0.6 to 0.7 m from the camera, as
+  its children ([camera](https://alpha.dewdrop.world/docs/camera)).
+- **Small moving things smear.** Make what matters large in frame. Fish, flocks and sparks: muted, about 0.6 m long
+  or more, 8 m or more from the camera. Smoke and steam can't be built. Turn flat things to face the camera
+  ([what to watch for](https://alpha.dewdrop.world/docs/renderer#what-to-watch-for)).
+- To find which mesh became a blob, give the suspects a loud color such as magenta for a moment, and check again.
+
+The code ([limits](https://alpha.dewdrop.world/docs/limits)):
+- The frame rate on Dewdrop is often far lower than a browser's own three.js, and varies. Move by the real time
+  that passed, don't cap a frame's time below about 0.25 s, and step in small fixed steps.
+- `index.html`'s own scripts don't run. Leave `html` and `body` without a background, and don't set
+  `color-scheme: dark`. Put what the page shows under `public/ui/`, or import it.
+- `fetch` reads only the game's own files. WebSocket, WebRTC and workers aren't available. Sound plays through
+  Web Audio; `<audio>` and `<video>` make no sound.
+- Keep `three` at 0.185.1, which Dewdrop provides ([project](https://alpha.dewdrop.world/docs/project)).
+
+## 4. The working loop
+
+Follow the [development flow](https://alpha.dewdrop.world/docs/development-flow). The game runs on Dewdrop alone,
+in its dev version; there is no local preview.
+1. **Shapes:** build the scene and the game from simple shapes, and play it until it works.
+   Check that the player and the roads show. Seed any random layout.
+2. **Colors:** give every mesh its base color.
+3. **Descriptions:** say what each thing is and what it's made of, in the style's words.
+4. **Style prompt:** set the prompt for the whole game, and the sky.
+
+After each step, upload. While the user runs `npm run dev`, every save uploads by itself and the page reloads;
+otherwise `npx dewctl dev` builds the game, uploads it and prints the link to play it on Dewdrop. Don't run both at
+once: they build into the same folder. Judge the look there, in motion, not from a still frame. The first second is
+plain and grey.
+
+You can't see Dewdrop's frames. Ask the user specific questions ("Does the lantern glow?", "What does the sky look
+like?"), or ask for a screenshot. In the dev version, `dewdrop.evaluate` runs code in the game from the browser
+console or a script driving the browser, to read the game's state or change it
+([run code](https://alpha.dewdrop.world/docs/development-flow#run-code-in-your-dev-version)). Change one thing
+at a time, so you know what each change did.
+
+## 5. The project
+
+- `dewdrop.json` connects the folder to the game: its name, the build command, the folder the build writes, and
+  the thumbnail ([dewdrop.json](https://alpha.dewdrop.world/docs/dewdrop-json)).
+- `npm run dev` plays the dev version on Dewdrop and uploads it again on every save; `npx dewctl dev` uploads it
+  once. `npx dewctl status` shows both versions. Run `npx dewctl publish` only when the user asks: it puts the game
+  in front of players ([commands](https://alpha.dewdrop.world/docs/cli)).
+- In a starter game, README.md says how the game works and why its look works. Read it first.
+- `thumbnail.jpg` is the image players see for the game. A starter's shows the starter, so once the look has
+  changed, ask the user for a screenshot of the game on Dewdrop to replace it before publishing (a PNG, JPEG or WebP
+  of at most 1 MB, at 16:9).

package/examples/starter/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "my-game",
+  "private": true,
+  "type": "module",
+  "scripts": { "dev": "dewctl dev --watch", "build": "vite build" },
+  "dependencies": { "three": "0.185.1" },
+  "devDependencies": { "vite": "^8" }
+}

package/examples/starter/{main.js → src/main.js}

@@ -1,4 +1,4 @@
-// Your game. Save a change while `dewctl dev --watch` runs and the game on Dewdrop updates.
+// Your game. Save a change while `npm run dev` runs and the game on Dewdrop updates.
 import * as THREE from 'three';
 
 const scene=new THREE.Scene();
@@ -14,10 +14,6 @@ const cube=new THREE.Mesh(new THREE.BoxGeometry(1.5,1.5,1.5),new THREE.MeshStand
 // …and what this mesh is.
 cube.userData.description='A polished turquoise cube';
 scene.add(cube);
-scene.add(new THREE.AmbientLight(0xffffff,1));
-const light=new THREE.DirectionalLight(0xffffff,2);
-light.position.set(3,4,5);
-scene.add(light);
 const heading=document.createElement('h1');
 heading.textContent='Hello from your Dewdrop game';
 heading.style.cssText='position:absolute;top:20px;left:24px;color:white;font:24px sans-serif;';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dewctl",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Build and publish three.js games on Dewdrop.",
   "license": "MIT",
   "type": "module",

package/src/client.js

@@ -48,6 +48,7 @@ export class Client {
   game(game,signal){return this.api(`/v1/games/${game}`,{signal});}
   releases(game){return this.api(`/v1/games/${game}/releases`);}
   deleteRelease(game,release){return this.api(`/v1/games/${game}/releases/${release}`,{method:'DELETE'});}
+  deleteGame(game){return this.api(`/v1/games/${game}`,{method:'DELETE'});}
   // Makes the game this developer's if it is new, and confirms it is theirs if not: asked before anything is built, so
   // a name someone else has, or a sign-in that has ended, is known at once.
   async claim(game,signal) {

package/src/command.js

@@ -1,2 +1,3 @@
-// How the developer runs this CLI, for the commands its messages suggest: through npx when npx started it, else by name.
-export const RUN=process.env.npm_command==='exec'?'npx dewctl':'dewctl';
+// How the developer runs this CLI, for the commands its messages suggest: through npx when npx or an npm script
+// (`npm run dev`, which runs `dewctl dev --watch`) started it, else by name.
+export const RUN=['exec','run','run-script'].includes(process.env.npm_command)?'npx dewctl':'dewctl';

package/src/main.js

@@ -2,7 +2,7 @@
 // Dewdrop's developer commands: sign in, connect a directory to a game, then run, publish, share and inspect it.
 import {spawn} from 'node:child_process';
 import {readFileSync} from 'node:fs';
-import {readProject,platformOrigin,initProject,DEWDROP} from './project.js';
+import {readProject,platformOrigin,initProject,chooseTemplate,DEWDROP} from './project.js';
 import {Credentials} from './credentials.js';
 import {Client} from './client.js';
 import {deploy,watch,size} from './watch.js';
@@ -13,8 +13,11 @@ import {syncThumbnail} from './thumbnail.js';
 
 const HELP=`${RUN} — make three.js games on Dewdrop
 
-  init [--game NAME]                       Connect this folder to a game; an empty folder gets the starter game.
-                                           The game is named after the folder unless --game names it
+  init [--game NAME] [--template NAME]     Connect this folder to a game. An empty folder gets a new game from
+                                           a template: blank, golden-glide, ember-wyrm, woolly-farm,
+                                           turtle-tide or hollow-manor. Without --template, init asks which at a terminal
+                                           (Enter for Blank), and starts Blank in a script. The game is named
+                                           after the folder unless --game names it
   login                                    Sign in: prints a link to open in your browser and approve
   logout                                   Sign this computer out
   dev [--watch] [--release ID]             Build, upload and play the dev version; --watch repeats this on every
@@ -26,18 +29,22 @@ const HELP=`${RUN} — make three.js games on Dewdrop
   share EMAIL                              Let another developer play and update the dev version
   unshare EMAIL                            Take that back
   status                                   Show the dev and published versions and where to play them
-  releases                                 List the uploads Dewdrop keeps: every published version, the dev version
-                                           and each member's latest upload; any id, or its first 8 characters,
-                                           feeds --release and delete
-  delete ID                                Delete a published version nothing runs, freeing its space (owner only)
+  releases                                 List the uploads Dewdrop keeps: every published version, the dev version,
+                                           each member's latest upload, and every other dev build for two weeks;
+                                           any id, or its first 8 characters, feeds --release and delete
+  delete ID                                Delete an upload nothing runs, freeing its space (owner only)
+  delete-game NAME                         Delete this game, its name typed again to confirm: both versions stop
+                                           now, and it is removed with its uploads and its players' saves. This
+                                           can't be undone (owner only)
   --version                                Show this CLI's version
 
   Run the commands in your game's folder: they read the game from its dewdrop.json.
   Docs: ${DEWDROP}/docs
 `;
-// Each command's flags; share and unshare also take one address, and delete one release. Anything else on the line is refused.
-const COMMANDS={init:['--game'],login:[],logout:[],dev:['--watch','--release'],stop:[],publish:['--release'],unpublish:[],share:[],unshare:[],status:[],releases:[],delete:[]};
-const VALUED=['--game','--release'];
+// Each command's flags; share and unshare also take one address, delete one release and delete-game the game's name.
+// Anything else on the line is refused.
+const COMMANDS={init:['--game','--template'],login:[],logout:[],dev:['--watch','--release'],stop:[],publish:['--release'],unpublish:[],share:[],unshare:[],status:[],releases:[],delete:[],'delete-game':[]};
+const VALUED=['--game','--template','--release'];
 function options(command,args) {
   const out={};
   for(let i=0;i<args.length;i++) {
@@ -48,6 +55,7 @@ function options(command,args) {
       else out[key.slice(2)]=args[++i];
     } else if(['share','unshare'].includes(command)&&!key.startsWith('-')&&out.email===undefined)out.email=key;
     else if(command==='delete'&&!key.startsWith('-')&&out.release===undefined)out.release=key;
+    else if(command==='delete-game'&&!key.startsWith('-')&&out.name===undefined)out.name=key;
     else throw new Error(`${command} doesn't take ${key}. Run ${RUN} --help to see what it takes.`);
   }
   if(out.release!==undefined&&!/^[a-f0-9]{8,64}$/.test(out.release))throw new Error(`${command==='delete'?'delete':'--release'} takes a release id, or its first 8 or more characters, from ${RUN} releases.`);
@@ -87,23 +95,25 @@ async function main() {
   if(!Object.hasOwn(COMMANDS,command))throw new Error(`There's no ${command} command. Run ${RUN} --help to see them.`);
   const flags=options(command,args);
   if(command==='init') {
-    const config=initProject(process.cwd(),flags.game);
+    const config=await initProject(process.cwd(),flags.game,flags.template,process.stdin.isTTY&&process.stdout.isTTY?chooseTemplate:undefined);
     const run=RUN;
-    if(config.starter)console.log(`Set up ${config.game} here. Next:\n  npm install\n  ${run} login\n  ${run} dev --watch\nThe game is created on Dewdrop the first time you run dev. To try it here without Dewdrop, run npm run dev.`);
-    else console.log(`Created dewdrop.json for ${config.game}. Next: ${run} login, then ${run} dev --watch.`);
-    if(config.buildScript==='build')console.log('Using your build script (npm run build) to build for Dewdrop. It must build with the Dewdrop plugin (vite build --mode dew); if it doesn\'t, add a build:dew script that does and set "build" in dewdrop.json to ["npm","run","build:dew"].');
-    if(!config.starter&&!config.buildScript)console.log('No build:dew or build script is in package.json, so dewdrop.json builds with npm run build:dew. Add that script, building with the Dewdrop plugin (vite build --mode dew), or set "build" in dewdrop.json to your own command.');
+    if(config.starter)console.log(`Set up ${config.game} here. Next:\n  npm install\n  ${run} login\n  npm run dev\nnpm run dev builds the game, uploads it to Dewdrop and prints a link to play it, then uploads again on every save; the game is created on Dewdrop the first time.${config.template==='blank'?'':'\nRead README.md: how the game works and why its look works.'}\nAGENTS.md tells coding agents how to work on the game, starting with agreeing its look with you.`);
+    else console.log(`Created dewdrop.json for ${config.game}. Next: ${run} login, then ${run} dev --watch. To make npm run dev play it on Dewdrop, set package.json's dev script to dewctl dev --watch.`);
+    if(!config.starter&&config.buildScript)console.log(`Building for Dewdrop with npm run ${config.buildScript}, which must run vite build with the Dewdrop plugin in vite.config.js.`);
+    if(!config.starter&&!config.buildScript)console.log('No build script is in package.json, so dewdrop.json builds with npm run build. Add one that runs vite build with the Dewdrop plugin in vite.config.js, or set "build" in dewdrop.json to your own command.');
     return;
   }
   // Every command but init reads the game from the project's dewdrop.json.
   const project=readProject(process.cwd());
   const origin=platformOrigin();
   const credentials=new Credentials(origin),client=new Client(origin,credentials);
-  // The commands that wait on Dewdrop stop waiting at Ctrl-C; the rest end the ordinary way.
+  // The commands that wait on Dewdrop stop waiting at Ctrl-C; the rest end the ordinary way. Every signal is taken,
+  // not the first alone: under `npm run dev`, npm passes the terminal's Ctrl-C on to the CLI, which has had it already,
+  // and a second signal must not end the CLI before it has said what it stopped.
   const controller=new AbortController(),{signal}=controller;
   if(['login','stop','unpublish','publish','dev'].includes(command)) {
-    process.once('SIGINT',()=>controller.abort(new Error('Stopped.')));
-    process.once('SIGTERM',()=>controller.abort(new Error('Stopped.')));
+    process.on('SIGINT',()=>controller.abort(new Error('Stopped.')));
+    process.on('SIGTERM',()=>controller.abort(new Error('Stopped.')));
   }
   // login makes a sign-in token and prints the link that approves it; the token is kept once Dewdrop says whose it is.
   if(command==='login') {
@@ -141,8 +151,8 @@ async function main() {
   if(command==='releases'){
     const [{releases},state]=await Promise.all([client.releases(game),client.game(game)]);
     if(!releases.length){console.log(`No uploads of ${game} yet. Run ${RUN} dev to make one.`);return;}
-    // What each release is to the game, the reason Dewdrop keeps it.
-    const status=release=>[release.sha256===state.dev.release&&'dev',release.sha256===state.live.release&&'published'].filter(Boolean).join(', ')||(release.published?'published before':'latest upload');
+    // What each release is to the game, the reason Dewdrop keeps it, and for an old dev build when it goes.
+    const status=release=>[release.sha256===state.dev.release&&'dev',release.sha256===state.live.release&&'published'].filter(Boolean).join(', ')||(release.published?'published before':release.expires?`dev build until ${new Date(release.expires).toISOString().slice(0,10)}`:'latest upload');
     console.log(columns([['RELEASE','UPLOADED (UTC)','SIZE','STATUS','BY'],...releases.map(release=>[release.sha256.slice(0,12),new Date(release.created).toISOString().slice(0,16).replace('T',' '),size(release.bytes),status(release),release.email])]));
     return;
   }
@@ -152,6 +162,11 @@ async function main() {
     await client.deleteRelease(game,release);
     console.log(`Deleted ${release.slice(0,12)} from ${game}.`);return;
   }
+  if(command==='delete-game'){
+    if(flags.name!==game)throw new Error(`delete-game takes the game's name to confirm. Run ${RUN} delete-game ${game} to delete ${game}.`);
+    await client.deleteGame(game);
+    console.log(`Deleted ${game}. Both versions are stopped, players can no longer open it, and it is removed with its uploads and its players' saves.`);return;
+  }
   if(['share','unshare'].includes(command)) {
     if(!flags.email)throw new Error(`${command} needs the developer's email address.`);
     await client.member(game,flags.email,command==='share');

package/src/project.js

@@ -3,7 +3,10 @@ import {readFileSync, writeFileSync, existsSync, lstatSync, readdirSync, openSyn
 import {resolve, relative, join, isAbsolute, basename, dirname} from 'node:path';
 import {createHash,randomBytes} from 'node:crypto';
 import {spawn} from 'node:child_process';
-import {packTar} from './tar.js';
+import {fileURLToPath} from 'node:url';
+import {gunzipSync} from 'node:zlib';
+import {createInterface} from 'node:readline';
+import {packTar,readTar} from './tar.js';
 import {RUN} from './command.js';
 
 const MAX_BYTES = 1024 * 1024 * 1024;
@@ -37,7 +40,7 @@ export function readProject(root = process.cwd()) {
   if (!GAME_NAME.test(config.game ?? '')) throw new Error("Set game in dewdrop.json to the game's name (for example my-game).");
   projectPath(root,config.bundle);
   if (config.thumbnail !== undefined) projectPath(root,config.thumbnail);
-  if (config.build !== undefined && (!Array.isArray(config.build) || !config.build.length || config.build.some(v=>typeof v !== 'string' || !v || v.includes('\0')))) throw new Error('build must be an argument array, such as ["npm","run","build:dew"].');
+  if (config.build !== undefined && (!Array.isArray(config.build) || !config.build.length || config.build.some(v=>typeof v !== 'string' || !v || v.includes('\0')))) throw new Error('build must be an argument array, such as ["npm","run","build"].');
   return {...config,root};
 }
 
@@ -101,7 +104,7 @@ export function fingerprint(project) {
 export function snapshot(project) {
   const directory=projectPath(project.root,project.bundle);
   if (!existsSync(directory)) throw new Error(project.build
-    ? `The build wrote no ${project.bundle} folder. Set "bundle" in dewdrop.json to the folder your Dewdrop build (vite build --mode dew) writes.`
+    ? `The build wrote no ${project.bundle} folder. Set "bundle" in dewdrop.json to the folder your build (vite build) writes.`
     : `There's no ${project.bundle} folder to upload. Build the game first, or set "build" in dewdrop.json so ${RUN} dev builds it.`);
   const root=realpathSync(directory);
   if (root!==directory) throw new Error(`The ${project.bundle} folder can't be a symlink.`);
@@ -112,7 +115,7 @@ export function snapshot(project) {
     const nested=[...files.keys()].filter(path=>path.endsWith('/main.js')).sort((a,b)=>a.split('/').length-b.split('/').length)[0];
     throw new Error(nested
       ? `There's no main.js at the top of ${project.bundle}, but there is ${project.bundle}/${nested}. Set "bundle": "${project.bundle}/${dirname(nested)}" in dewdrop.json.`
-      : `There's no main.js in ${project.bundle}. Build with the Dewdrop plugin (vite build --mode dew), and set "bundle" in dewdrop.json to the folder that build writes.`);
+      : `There's no main.js in ${project.bundle}. Build with the Dewdrop plugin in vite.config.js (vite build), and set "bundle" in dewdrop.json to the folder that build writes.`);
   }
   let bytes=0;
   const entries=[...files].map(([path,{file,size}])=>{
@@ -152,56 +155,101 @@ export async function build(project, signal) {
     if(signal?.aborted)cancel();
   });
 }
-// The one project shape: a Vite project with the SDK's plugin, which previews locally with `npm run dev` and
-// builds for Dewdrop with `npm run build:dew`. A directory holding none of the starter's files gets the
-// starter game, depending on the SDK and this CLI from npm; one holding any of them has a game of its own and gets
-// dewdrop.json alone, so nothing of it is touched and no starter is left half written.
+// The one project shape: a Vite project with the SDK's plugin, which builds for Dewdrop with `npm run build`
+// and plays there with `npm run dev`, which runs `dewctl dev --watch`. A directory holding none of the starter's
+// files gets a new game, depending on the SDK and this CLI from npm; one holding any of them has a game of its own
+// and gets dewdrop.json alone, so nothing of it is touched and no new game is left half written.
 const STARTER_FILES=['package.json','src','index.html','vite.config.js'];
 // The SDK a new game depends on — the range moves with the SDK's minor, since a caret on 0.x stays within one —
 // and this CLI, at its own version.
-const SDK_RANGE='^0.5.1';
+const SDK_RANGE='^0.6.0';
 const CLI_RANGE=`^${JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version}`;
+// The games a new one can start from: Blank, which ships with this CLI, and the starter games in the public
+// starter-templates repository, a folder each, at the commit this release pins.
+const STARTERS={repo:'DewdropLabs/starter-templates',commit:'4247a60d29f5477b94b498fcd31a4c3c0e873cc0'};
+const TEMPLATES={
+  blank:['Blank','a cube and a style prompt, the smallest game'],
+  'golden-glide':['Golden Glide','flight over golden-hour countryside, in gouache'],
+  'ember-wyrm':['Ember Wyrm','a third-person dragon fight, in colored pencil'],
+  'woolly-farm':['Woolly Farm','cozy farming, third person, in knitted wool'],
+  'turtle-tide':['Turtle Tide','a sea turtle swimming through kelp, in stained glass'],
+  'hollow-manor':['Hollow Manor','first-person horror by candlelight'],
+};
+const EXAMPLES=fileURLToPath(new URL('../examples/',import.meta.url)),BLANK=join(EXAMPLES,'starter');
+// Asks at a terminal which game a new one starts from. Enter is Blank, and any answer but a listed number asks again.
+export async function chooseTemplate(input=process.stdin, output=process.stdout) {
+  const ids=Object.keys(TEMPLATES),ask=`Choose 1–${ids.length} [1]: `;
+  output.write(`Start from:\n${ids.map((id,i)=>`  ${i+1}  ${TEMPLATES[id][0].padEnd(14)}${TEMPLATES[id][1]}`).join('\n')}\n${ask}`);
+  for await (const line of createInterface({input})) {
+    const answer=line.trim()||'1',id=/^\d$/.test(answer)&&ids[answer-1];
+    if(id)return id;
+    output.write(ask);
+  }
+  throw new Error('No game was chosen to start from.');
+}
+// A starter game's files, from the repository's tarball at the pinned commit (or the one DEWDROP_STARTERS names, for
+// tests): the regular files under the game's folder, by their paths in it, leaving out names starting with a dot.
+async function download(template) {
+  const name=TEMPLATES[template][0];
+  let response,files;
+  try { response=await fetch(process.env.DEWDROP_STARTERS??`https://codeload.github.com/${STARTERS.repo}/tar.gz/${STARTERS.commit}`,{signal:AbortSignal.timeout(120000)}); }
+  catch(error) { throw new Error(`Couldn't download the ${name} game (${error.cause?.message??error.message}). Nothing was written; check your connection and run init again.`); }
+  try {
+    if(!response.ok)throw new Error(`the download answered ${response.status}`);
+    files=readTar(gunzipSync(await response.bytes()));
+  } catch(error) { throw new Error(`Couldn't read the ${name} game (${error.message}). Nothing was written.`); }
+  files=files.filter(({path})=>path.startsWith(`${template}/`)&&!path.split('/').some(part=>part.startsWith('.'))).map(({path,data})=>({path:path.slice(template.length+1),data}));
+  if(!files.length)throw new Error(`The ${name} game is missing from the download. Nothing was written.`);
+  return files;
+}
 // A game name from the project directory, or a random one when the directory name yields nothing usable.
 function gameNameFrom(root) {
   const slug=basename(resolve(root)).toLowerCase().replace(/[^a-z0-9]+/g,'-').replace(/^[^a-z]+/,'').replace(/-+$/,'').slice(0,48).replace(/-+$/,'');
   return GAME_NAME.test(slug)?slug:`game-${randomBytes(4).toString('hex')}`;
 }
-// The build command for a project of its own: its build:dew or build npm script when it has one, named so init can
-// say which it chose, else the default with no script, so init can tell the developer to add one.
+// The build command for a project of its own: its build:dew npm script when it has one — a project set up before
+// dewdrop-sdk 0.6, whose SDK init leaves as it is, builds for Dewdrop through that script alone — else its build
+// script, named so init can say which it chose, else the default with no script, so init can tell the developer to
+// add one.
 function buildCommandFor(root) {
   try {
     const scripts=JSON.parse(readFileSync(join(root,'package.json'),'utf8')).scripts;
     for(const name of ['build:dew','build'])if(scripts&&typeof scripts[name]==='string')return {build:['npm','run',name],script:name};
   } catch {}
-  return {build:['npm','run','build:dew'],script:null};
+  return {build:['npm','run','build'],script:null};
 }
-export function initProject(root, game) {
-  const path=join(root,'dewdrop.json');
-  if(existsSync(path))throw new Error('This folder already has a dewdrop.json.');
+// Connects `root` to `game`. A new game starts from `template`, else from the one `choose` answers, else Blank, and
+// gets its name, this CLI's ranges and the agent instructions; a project of its own gets dewdrop.json alone.
+export async function initProject(root, game, template, choose) {
+  if(existsSync(join(root,'dewdrop.json')))throw new Error('This folder already has a dewdrop.json.');
   const starter=!STARTER_FILES.some(file=>existsSync(join(root,file)));
   game??=gameNameFrom(root);
   if(!GAME_NAME.test(game))throw new Error('A game name is 1–48 lowercase letters, digits or dashes, starting with a letter.');
-  const {build,script}=starter?{build:['npm','run','build:dew'],script:'build:dew'}:buildCommandFor(root);
-  const config={version:1,game,bundle:'dist',build};
+  if(template!==undefined&&!Object.hasOwn(TEMPLATES,template))throw new Error(`--template takes ${Object.keys(TEMPLATES).join(', ')}.`);
+  if(template&&!starter)throw new Error('This folder has a project of its own, so init only connects it to a game. Start from a template in an empty folder.');
+  if(starter)template??=choose?await choose():'blank';
+  const files=!starter?[]:template==='blank'?readdirSync(BLANK,{recursive:true}).filter(path=>lstatSync(join(BLANK,path)).isFile()).map(path=>({path,data:readFileSync(join(BLANK,path))})):await download(template);
+  const {build,script}=starter?{build:['npm','run','build'],script:'build'}:buildCommandFor(root);
+  const config={version:1,game,bundle:'dist',build,...files.some(({path})=>path==='thumbnail.jpg')&&{thumbnail:'thumbnail.jpg'}};
+  // The game's package and page take its name, and the package this CLI's ranges of the SDK and itself.
+  const edits=new Map([
+    ['package.json',text=>{const pkg=JSON.parse(text);pkg.name=game;pkg.devDependencies={...pkg.devDependencies,'dewdrop-sdk':SDK_RANGE,dewctl:CLI_RANGE};return JSON.stringify(pkg,null,2)+'\n';}],
+    ['index.html',text=>text.replace(/<title>[^<]*<\/title>/,`<title>${game}</title>`)],
+  ]);
   // Everything init writes, so a failure part-way removes it again and a retry starts from the same empty folder.
+  const taken=files.find(({path})=>existsSync(join(root,path)));
+  if(taken)throw new Error(`${taken.path} is already in this folder, and the game has one of its own. Move it out, or start in an empty folder.`);
   const made=[];
-  const write=(file,data)=>{writeFileSync(file,data,{flag:'wx'});made.push(file);};
-  const folder=dir=>{if(!existsSync(dir)){mkdirSync(dir,{recursive:true});made.push(dir);}};
+  const write=(path,data)=>{const file=join(root,path),dir=mkdirSync(dirname(file),{recursive:true});if(dir)made.push(dir);writeFileSync(file,data,{flag:'wx'});made.push(file);};
   try {
-    if(starter) {
-      folder(join(root,'src'));
-      const template=name=>readFileSync(new URL(`../examples/starter/${name}`,import.meta.url),'utf8');
-      write(join(root,'src/main.js'),template('main.js'));
-      write(join(root,'index.html'),template('index.html').replace('<title>My game</title>',`<title>${game}</title>`));
-      write(join(root,'vite.config.js'),template('vite.config.js'));
-      const devDependencies={'dewdrop-sdk':SDK_RANGE,dewctl:CLI_RANGE,vite:'^8'};
-      write(join(root,'package.json'),JSON.stringify({name:game,private:true,type:'module',scripts:{dev:'vite','build:dew':'vite build --mode dew'},dependencies:{three:'0.185.1'},devDependencies},null,2)+'\n');
-      if(!existsSync(join(root,'.gitignore')))write(join(root,'.gitignore'),'dist/\nnode_modules/\n.env*\n');
-    }
-    write(path,JSON.stringify(config,null,2)+'\n');
+    for(const {path,data} of files)write(path,edits.get(path)?.(data.toString())??data);
+    // The files every new game gets beside its own, each left as it is when the folder has one already: AGENTS.md
+    // guides coding agents, which read it by that name.
+    if(starter)for(const [name,data] of Object.entries({'.gitignore':'dist/\nnode_modules/\n','AGENTS.md':readFileSync(join(EXAMPLES,'AGENTS.md'))}))if(!existsSync(join(root,name)))write(name,data);
+    write('dewdrop.json',JSON.stringify(config,null,2)+'\n');
   } catch(error) {
     for(const file of made.reverse())rmSync(file,{recursive:true,force:true});
     throw error;
   }
-  return {...config,starter,buildScript:script};
+  return {...config,starter,template,buildScript:script};
 }

package/src/tar.js

@@ -46,3 +46,28 @@ export function packTar(entries) {
   }
   return out;
 }
+
+// The regular files of a ustar archive, such as a GitHub tarball, as `{path, data}` with the archive's one top-level
+// folder taken off each path. Folders and pax headers are passed over, but for the path a pax header gives the file
+// after it; any other kind of entry, a path that could leave the folder, or an archive cut short is refused.
+export function readTar(archive) {
+  const files=[];
+  let top,long;
+  for(let offset=0;offset+BLOCK<=archive.length;) {
+    const block=archive.subarray(offset,offset+BLOCK);
+    if(!block.some(byte=>byte))return files;
+    const text=(start,length)=>{const raw=block.subarray(start,start+length),end=raw.indexOf(0);return raw.subarray(0,end<0?length:end).toString();};
+    const size=text(124,12).trim(),type=text(156,1)||'0',start=offset+BLOCK,end=start+parseInt(size,8);
+    if(text(257,5)!=='ustar'||!/^[0-7]+$/.test(size)||end>archive.length)throw new Error(end>archive.length?'the archive is cut short':'the archive is damaged');
+    const data=archive.subarray(start,end);
+    offset=start+padded(end-start);
+    if(type==='x'){long=/(?:^|\n)\d+ path=([^\n]*)/.exec(data.toString())?.[1];continue;}
+    const path=long??[text(345,155),text(0,100)].filter(Boolean).join('/'),parts=path.split('/');
+    long=undefined;
+    if(type==='5'||type==='g')continue;
+    if(type!=='0')throw new Error(`the archive holds ${path}, which isn't a regular file`);
+    if(parts.length<2||parts.some(part=>!part||part==='.'||part==='..')||parts[0]!==(top??=parts[0]))throw new Error(`the archive holds a file outside its folder: ${path}`);
+    files.push({path:parts.slice(1).join('/'),data});
+  }
+  throw new Error('the archive is cut short');
+}