@v12-engine/create 0.0.0-stage → 0.1.1

package/index.mjs

@@ -0,0 +1,286 @@
+/**
+ * A project to start from (S60): `npm create @v12-engine my-game` puts one together in `my-game` from layers (create
+ * N2), each a folder of files laid over the ones before:
+ *
+ * 1. `base/`: what every project has: its page, its `package.json`, its TypeScript config
+ * 2. `layers/<option>/`: what an option on adds (the editor, a server, the tests), in `LAYERS`'s order
+ * 3. `starters/<starter>/`: the game, its rules, look and maps, and its README
+ * 4. `starters/<starter>/layers/<option>/`: what the starter adds with an option on (its tests)
+ *
+ * A `package.json` of a layer is merged into the one before (scripts, dependencies), not laid over it. A line of
+ * `// @if <option>`, `<!-- @if <option> -->` or `# @if <option>` keeps what follows, to its `@end`, only with the option on (`!<option>`
+ * with it off, `a|b` with either on); the marker lines are left out. The command line (`cli.mjs`) asks or is told how, and the install test
+ * makes its project with this too (`scripts/install-test/run.mjs`), so what is made is what is tested
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { DEFAULT_STARTER, starterNamed } from './starters.mjs'
+
+export { DEFAULT_STARTER, starterNamed, starters } from './starters.mjs'
+
+const here = fileURLToPath(new URL('.', import.meta.url))
+/** What the packages of the library are installed as: the version of this one, as the three are versioned together */
+const own = JSON.parse(await readFile(fileURLToPath(new URL('./package.json', import.meta.url)), 'utf8'))
+
+/** What a package may be called (npm's rules): lower case, no spaces, nothing that leads out of a folder */
+export function packageName(folder) {
+	const name = basename(resolve(folder))
+		.toLowerCase()
+		.replace(/[^a-z0-9._~-]+/g, '-')
+		.replace(/^[._-]+|-+$/g, '')
+	return name || 'my-game'
+}
+
+/**
+ * What a game is called where it is shown, from its folder's name: `orc-wars`, Orc wars; `Orc Wars`, Orc Wars. My game
+ * where the folder's name makes no name
+ */
+export function titleOf(folder) {
+	const words = basename(resolve(folder))
+		.replace(/[-_.~\s]+/g, ' ')
+		.trim()
+	const title = words ? words[0].toUpperCase() + words.slice(1) : ''
+	return title && !titleProblem(title) ? title : 'My game'
+}
+
+/**
+ * Why a game cannot be called this, or nothing: the title is written into its code, its page and its README as it is,
+ * so it has no quotes, backslashes or angle brackets, and fits on a line
+ */
+export function titleProblem(title) {
+	if (!title.trim()) return 'A game needs a name'
+	if (title.length > 60) return 'A name of 60 letters at most'
+	if (/["'`\\<>\n\r]/.test(title)) return 'A name without quotes, backslashes or angle brackets'
+	return undefined
+}
+
+/**
+ * The options that are layers, in the order they are laid: each may have a folder in `layers/` and in a starter's
+ * `layers/`, and is a name its files' `@if` lines may ask about
+ */
+export const LAYERS = ['editor', 'server', 'rooms', 'tests', 'assets', 'source']
+
+/**
+ * What a file's `@if` lines may ask about: the layers, and what changes a few lines and has no files of its own
+ * (`ratings`; `single`, a server of one game at a time, where `server` is any server and `rooms` one of rooms;
+ * `generator`, the starter's, not the command line's: its random map made in a worker, `starters`)
+ */
+export const OPTIONS = ['editor', 'server', 'single', 'rooms', 'ratings', 'tests', 'assets', 'source', 'generator']
+
+/** What a server of the game is: one game at a time (`single`), many games in rooms that players find and make (`rooms`), or none */
+export const SERVERS = ['single', 'rooms', 'none']
+
+/** What may install and run a project: its words for that are `commandsOf`'s */
+export const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun']
+
+/** A package manager's words: what installs, and what runs a script of the project */
+export function commandsOf(packageManager = 'npm') {
+	if (!PACKAGE_MANAGERS.includes(packageManager))
+		throw new Error(`There is no package manager "${packageManager}": they are ${PACKAGE_MANAGERS.join(', ')}`)
+	const install = packageManager === 'yarn' ? 'yarn' : `${packageManager} install`
+	const run = (script) =>
+		packageManager === 'npm'
+			? script === 'test'
+				? 'npm test'
+				: `npm run ${script}`
+			: packageManager === 'bun'
+				? `bun run ${script}`
+				: `${packageManager} ${script}`
+	return { install, run }
+}
+
+/** The files whose words may be the game's name and may have `@if` lines: its code, its page, its README, its maps */
+const TEXT = new Set(['.ts', '.mjs', '.html', '.md', '.json', '.css'])
+const isText = (path) => TEXT.has(extname(path)) || basename(path) === '_gitignore'
+
+/** The order of a project's scripts, as one reads them: the rest after, as they came */
+const SCRIPTS = ['dev', 'build', 'preview', 'server', 'test', 'typecheck']
+
+/**
+ * Makes a project in `folder`, which is to be empty or not there:
+ *
+ * - `starter`: the game it starts from (`starters`), `DEFAULT_STARTER` (`empty`) when left out, as on the command line
+ * - `title`: what the game is called where it is shown, made from the folder's name when left out (`orc-wars`, Orc wars)
+ * - `editor`: its map editor (`/?editor`, `src/editor.ts`, the dev server's plugin); on when left out
+ * - `server`: a server of the game: `single`, one game at a time (`server.ts`, `/?server`); `rooms`, a room for each
+ *   map, games players make and matchmaking (`/?find-game`, Find a game); or `none`. `single` when left out
+ * - `ratings`: the server keeps a rating for each player (`ratings.json`); off when left out, and with no server
+ * - `tests`: a test of its rules (`tests/`, Vitest); on when left out
+ * - `assets`: the shared art (`@v12-engine/assets`: models only: adventurers with their clips, buildings, trees and rocks, props, weapons), served by the dev server and
+ *   copied into a build as the game uses it (`assetsPackage`); on when left out, and always for a starter that plays
+ *   with it (`needs`)
+ * - `packageManager`: what installs and runs it (`PACKAGE_MANAGERS`): its README and comments say its words; `npm`
+ *   when left out
+ * - `source`: the library read as it is written, for a project inside the library's own repository (`apps/`): its
+ *   configs name the condition the packages' `exports` give their source under, with the plugins the source needs,
+ *   and `{{root}}` in the layer's files is the way to the repository's root from the project. Off when left out
+ * - `dependencies`: written over the template's (the install test's packed packages, `file:./…`); the library's are
+ *   `^` this package's version otherwise
+ *
+ * Nothing is written until the whole project is put together. Gives the project's name, its title, where it is, and
+ * the options it was made with
+ */
+export async function createProject(folder, options = {}) {
+	const {
+		starter = DEFAULT_STARTER,
+		editor = true,
+		server = 'single',
+		tests = true,
+		source = false,
+		packageManager = 'npm',
+		dependencies = {}
+	} = options
+	const ratings = !!options.ratings && server !== 'none'
+	const words = commandsOf(packageManager)
+	const needs = starterNamed(starter).needs ?? []
+	if (options.assets === false && needs.includes('assets'))
+		throw new Error(`The ${starter} starter plays with the shared art (@v12-engine/assets): it cannot be left out`)
+	const assets = options.assets ?? true
+	if (!SERVERS.includes(server)) throw new Error(`There is no server "${server}": a server is ${SERVERS.join(', ')}`)
+	const where = resolve(folder)
+	if (notEmpty(where)) throw new Error(`${where} is not empty: a project is made in an empty folder, or a new one`)
+	const name = packageName(where)
+	const title = options.title ?? titleOf(where)
+	const problem = titleProblem(title)
+	if (problem) throw new Error(`"${title}": ${problem}`)
+	const generator = !!starterNamed(starter).generator
+	const on = { editor, server: server !== 'none', single: server === 'single', rooms: server === 'rooms', ratings, tests, assets, source, generator }
+	// the way from the project to the repository's root (`{{root}}` in the source layer): this package is `packages/create` of it
+	const root = relative(where, resolve(here, '../..')).split(sep).join('/') || '.'
+	const files = await putTogether(starter, on)
+	const project = JSON.parse(files.get('package.json'))
+	project.name = name
+	// the map editor's package only in a project with the editor: one without it installs none of it
+	for (const library of [
+		'@v12-engine/engine',
+		'@v12-engine/client',
+		...(editor ? ['@v12-engine/editor'] : []),
+		...(assets ? ['@v12-engine/assets'] : [])
+	])
+		project.dependencies[library] = `^${own.version}`
+	// the `v12` command's package too, a dev dependency of a project with the editor: the five are versioned as one
+	if (project.devDependencies?.['@v12-engine/create']) project.devDependencies['@v12-engine/create'] = `^${own.version}`
+	// what is given for the library's packages stands in for those the project has (the install test's packed ones),
+	// a dev dependency (the `v12` command's package) among them
+	for (const [dependency, version] of Object.entries(dependencies)) {
+		if (project.devDependencies && dependency in project.devDependencies) project.devDependencies[dependency] = version
+		else if (!dependency.startsWith('@v12-engine/') || dependency in project.dependencies) project.dependencies[dependency] = version
+	}
+	files.set('package.json', `${JSON.stringify(project, null, '\t')}\n`)
+	for (const [path, content] of files) {
+		const file = join(where, path === '_gitignore' ? '.gitignore' : path)
+		await mkdir(dirname(file), { recursive: true })
+		await writeFile(
+			file,
+			typeof content === 'string'
+				? said(
+						named(content, name, title).replaceAll('{{root}}', () => root),
+						words,
+						path
+					)
+				: content
+		)
+	}
+	return { name, title, where, starter, editor, server, ratings, tests, assets, source, packageManager }
+}
+
+/**
+ * The files of a project of `starter` with the options `on` (by name, true or false), by their path in it: text with
+ * its `@if` lines kept or left out, the rest as bytes. Throws for a marker it cannot read, wherever it is
+ */
+export async function putTogether(starter, on) {
+	const folders = [
+		join(here, 'base'),
+		...LAYERS.filter((layer) => on[layer]).map((layer) => join(here, 'layers', layer)),
+		join(here, 'starters', starter),
+		...LAYERS.filter((layer) => on[layer]).map((layer) => join(here, 'starters', starter, 'layers', layer))
+	]
+	const files = new Map()
+	for (const folder of folders) {
+		if (!existsSync(folder)) continue
+		for (const entry of await readdir(folder, { recursive: true, withFileTypes: true })) {
+			if (!entry.isFile()) continue
+			const path = relative(folder, join(entry.parentPath, entry.name)).split('\\').join('/')
+			// a starter's own layers are laid after it, each when its option is on; its list of the files its page asks
+			// for (`files.txt`, which the tests read) is no part of a game
+			if (folder.endsWith(join('starters', starter)) && (path.startsWith('layers/') || path === 'files.txt')) continue
+			const bytes = await readFile(join(entry.parentPath, entry.name))
+			if (!isText(path)) {
+				files.set(path, bytes)
+				continue
+			}
+			const text = kept(bytes.toString('utf8'), on, path)
+			// a file all of whose lines are for options off is not there: the Vite config of a project with neither the
+			// editor nor the shared art
+			if (!text.trim()) {
+				files.delete(path)
+				continue
+			}
+			files.set(path, basename(path) === 'package.json' && files.has(path) ? merged(files.get(path), text) : text)
+		}
+	}
+	return files
+}
+
+/** `text` with what its `@if` lines keep for the options `on`, without them; `path` is for what an error says */
+export function kept(text, on, path = 'a file') {
+	const marker = /^\s*(?:\/\/|<!--|#)\s*@(if|end)\b\s*(!?)([\w|-]*)\s*(?:-->)?\s*$/
+	const open = []
+	const lines = []
+	text.split('\n').forEach((line, index) => {
+		const found = marker.exec(line)
+		if (!found) {
+			if (open.every(Boolean)) lines.push(line)
+			return
+		}
+		const [, word, not, asked] = found
+		if (word === 'end') {
+			if (!open.length) throw new Error(`${path}:${index + 1}: an @end with no @if`)
+			open.pop()
+			return
+		}
+		// `@if editor|server`: any of them on
+		const options = asked.split('|')
+		for (const option of options) {
+			if (!(option in on)) throw new Error(`${path}:${index + 1}: @if ${option}, an option there is not (${Object.keys(on).join(', ')})`)
+		}
+		const any = options.some((option) => on[option])
+		open.push(not ? !any : any)
+	})
+	if (open.length) throw new Error(`${path}: an @if with no @end`)
+	return lines.join('\n')
+}
+
+/** A layer's `package.json` merged into the one before: its scripts and dependencies added, in the order one reads them */
+function merged(before, layer) {
+	const project = JSON.parse(before)
+	for (const [key, value] of Object.entries(JSON.parse(layer))) {
+		project[key] = value && typeof value === 'object' && !Array.isArray(value) ? { ...project[key], ...value } : value
+	}
+	const order = (key) => (SCRIPTS.includes(key) ? SCRIPTS.indexOf(key) : SCRIPTS.length)
+	if (project.scripts) project.scripts = Object.fromEntries(Object.entries(project.scripts).sort(([a], [b]) => order(a) - order(b)))
+	for (const key of ['dependencies', 'devDependencies']) {
+		if (project[key]) project[key] = Object.fromEntries(Object.entries(project[key]).sort(([a], [b]) => a.localeCompare(b)))
+	}
+	return `${JSON.stringify(project, null, '\t')}\n`
+}
+
+/** The starters' game is `my-game`, My game: the project's is its own, in its code, its page, its README and its maps */
+const named = (text, name, title) => text.replaceAll('my-game', () => name).replaceAll('My game', () => title)
+
+/** Folders git or the system leaves in a folder that is still new: a project is made beside them */
+const LEFT_BY_TOOLS = new Set(['.git', '.DS_Store', 'Thumbs.db'])
+
+/** Whether there is something in a folder: a project is made in an empty one (a fresh `git init` is empty) */
+export const notEmpty = (where) => existsSync(where) && readdirSync(where).some((entry) => !LEFT_BY_TOOLS.has(entry))
+
+/** The starters say npm's words (`npm run dev`, `npm test`): the project says its package manager's, but in its `package.json` */
+const said = (text, words, path) =>
+	basename(path) === 'package.json'
+		? text
+		: text
+				.replace(/\bnpm run ([\w:-]+)/g, (_, script) => words.run(script))
+				.replace(/\bnpm test\b/g, words.run('test'))
+				.replace(/\bnpm install\b/g, words.install)

package/layers/assets/package.json

@@ -0,0 +1,5 @@
+{
+	"dependencies": {
+		"@v12-engine/assets": "^0.0.0"
+	}
+}

package/layers/editor/package.json

@@ -0,0 +1,8 @@
+{
+	"scripts": {
+		"map": "v12 map"
+	},
+	"devDependencies": {
+		"@v12-engine/create": "^0.0.0"
+	}
+}

package/layers/editor/src/editor.ts

@@ -0,0 +1,13 @@
+/**
+ * The map editor of the game, a scene of the app (Map editor on the start screen, or `/?editor`) that `appScenes` makes
+ * (`src/main.ts`) with the editor's `editorScene`: it opens on the game's first map, as a file of the project that Save
+ * writes back, and Play here tries it in the page's own game. What is set here is the editor's own: what a game adds to
+ * it (`extensions`, made with `defineEditorExtension` of `@v12-engine/editor`), another map to open on (`startMap`,
+ * `startFile`)
+ */
+import type { AppEditorScene } from '@v12-engine/client/app'
+import '@v12-engine/editor/styles.css'
+
+// what the app's scenes say of it (its id, the game, the map it starts on, Play here's scene), and the game's own after.
+// The editor fetched as it first opens: the start screen carries none of it
+export const editor = (scene: AppEditorScene) => import('@v12-engine/editor').then(({ editorScene }) => editorScene({ ...scene }))

package/layers/rooms/server.ts

@@ -0,0 +1,69 @@
+/**
+ * A server of many games of the game (`npm run server`), in rooms that share its port. The page finds them at
+ * `/?find-game` (`npm run dev` beside it): the games to join or watch, a New game of any map, and Play now to be matched
+ * with someone. `PORT` is the port, 8787 when not said
+ */
+import { GameRooms, generatedMode, mapMode, type GameMode, type RoomKind } from '@v12-engine/engine/server'
+// @if ratings
+import { createRatings } from '@v12-engine/engine/server'
+// @end
+import { DEFAULT_MAP, mapNamed, maps } from './src/maps'
+import { rules, start } from './src/rules'
+
+/** A game on one of the game's maps, each world started as the page starts it */
+const onMap = (name: string): GameMode => mapMode(rules, mapNamed(name), { start })
+
+/**
+ * A game on a map the game's generator makes (`rules.generator`): another for each game made, of 128 cells a side for
+ * two, turned half about the middle so it is fair; the seed a New game asks for (`settings.seed`) where it says one
+ */
+const random: Record<string, RoomKind> = rules.generator
+	? {
+			random: {
+				name: 'A random map',
+				room: (settings) => ({
+					mode: generatedMode(rules, rules.generator!, {
+						width: 128,
+						depth: 128,
+						players: 2,
+						symmetry: 'half',
+						...(Number(settings.seed) > 0 && { seed: Number(settings.seed) }),
+						start
+					})
+				})
+			}
+		}
+	: {}
+
+// @if ratings
+// a rating for each player, moved by every game that ends with a winner, kept in a file (`ratings.json`)
+const ratings = createRatings({ file: 'ratings.json' })
+// a file that cannot be read stops the server here, rather than being written over
+await ratings.ready
+// @end
+// the seats the computer plays in the room to try the game alone in: every player of the first map but the first
+const computer = mapNamed()
+	.players.slice(1)
+	.map((player) => player.id)
+const rooms = await GameRooms.start({
+	port: Number(process.env.PORT ?? 8787),
+	rooms: {
+		// a room for each map, for people: ws://host:8787/<map>. Its game starts once every seat is taken
+		...Object.fromEntries(Object.keys(maps).map((name) => [name, { mode: onMap(name) }])),
+		// and one to try the game alone in
+		practice: { mode: onMap(DEFAULT_MAP), ai: computer }
+	},
+	// what players make games of (New game), each closed once nobody has been in it for a minute; and are matched for
+	// (Play now), once as many wait as it has seats
+	kinds: { ...Object.fromEntries(Object.entries(maps).map(([name, map]) => [name, { name: map.name, room: { mode: onMap(name) } }])), ...random },
+	// @if ratings
+	ratings,
+	// @end
+	log: (line) => console.log(line)
+})
+console.log(`The game's server is at ws://localhost:${rooms.port}: open the page at /?find-game to find a game on it`)
+
+// stopped (Ctrl+C, or SIGTERM where it is hosted): no new games, and those running have 30 seconds to end
+const stop = () => void rooms.close({ drain: 30 }).then(() => process.exit(0))
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)

package/layers/server/package.json

@@ -0,0 +1,8 @@
+{
+	"scripts": {
+		"server": "tsx server.ts"
+	},
+	"devDependencies": {
+		"tsx": "^4.23.15"
+	}
+}

package/layers/server/server.ts

@@ -0,0 +1,34 @@
+/**
+ * A server of the game (`npm run server`): each game on the first map, the first player's seat for whoever joins and
+ * the rest played by the computer. The page joins it at `/?server` (`npm run dev` beside it). `PORT` is the port,
+ * 8787 when not said
+ */
+import { startServer } from '@v12-engine/engine/server'
+// @if ratings
+import { createRatings } from '@v12-engine/engine/server'
+// @end
+import { mapNamed } from './src/maps'
+import { rules, start } from './src/rules'
+
+const map = mapNamed()
+// @if ratings
+// a rating for each player, moved by every game that ends with a winner, kept in a file (`ratings.json`)
+const ratings = createRatings({ file: 'ratings.json' })
+// a file that cannot be read stops the server here, rather than being written over
+await ratings.ready
+// @end
+const server = await startServer({
+	game: rules,
+	map,
+	start,
+	// the seats the computer plays: leave it out for a game of people alone, which starts once every seat is taken
+	ai: map.players.slice(1).map((player) => player.id),
+	// @if ratings
+	ratings,
+	// @end
+	port: Number(process.env.PORT ?? 8787)
+})
+console.log(`The game's server is at ws://localhost:${server.port}: open the page at /?server to play on it`)
+
+// stopped (Ctrl+C), it closes its connections first
+process.once('SIGINT', () => void server.close().then(() => process.exit(0)))

package/layers/source/package.json

@@ -0,0 +1,12 @@
+{
+	"scripts": {
+		// @if server
+		"server": "tsx --conditions=@v12-engine/source server.ts"
+		// @end
+	},
+	"devDependencies": {
+		"@tailwindcss/vite": "^4.3.3",
+		"tailwindcss": "^4.3.3",
+		"vite-plugin-solid": "^2.11.14"
+	}
+}

package/layers/source/tsconfig.json

@@ -0,0 +1,5 @@
+{
+	"extends": "{{root}}/tsconfig.base.json",
+	"compilerOptions": { "types": ["vite/client", "node"], "resolveJsonModule": true },
+	"include": ["src", "tests", "server.ts", "vite.config.ts"]
+}

package/layers/source/vite.config.ts

@@ -0,0 +1,45 @@
+import solid from 'vite-plugin-solid'
+import tailwindcss from '@tailwindcss/vite'
+import { defineConfig } from 'vite'
+// @if tests
+// the `test` key of the config
+import type {} from 'vitest/config'
+// @end
+// what every config of the library's repository says alike: its packages read as they are written
+import { sourceLibrary } from '{{root}}/config/vite.ts'
+// @if editor
+// the editor's plugin as it is written, not as it is built (`@v12-engine/editor/vite`): nothing of the library is built here
+import { editorFiles } from '{{root}}/packages/editor/plugin/editorFiles.ts'
+// @end
+// @if assets
+import { assetsPackage } from '{{root}}/packages/client/plugin/assetsPackage.ts'
+// @end
+
+// The library as it is written: a change to the engine or the client shows here at once, and nothing is built. Solid's
+// plugin and Tailwind's are here because the client's source is read (its components, its stylesheet): a project that
+// installs the packages needs neither.
+// @if assets
+// The shared art (@v12-engine/assets) is served where the game's shared files are (/models/…),
+// behind public/: a file of yours at the same path is the one served. A build copies what the game uses of it
+// @end
+// @if editor
+// The map editor keeps the game's maps in the project through the dev server: Save writes them into `src/maps`. Only
+// in `npm run dev`; a built page keeps maps in the browser
+// @end
+export default defineConfig({
+	plugins: [
+		!process.env.VITEST && solid(),
+		tailwindcss(),
+		// @if assets
+		assetsPackage(),
+		// @end
+		// @if editor
+		editorFiles({ gameFolder: () => 'src' })
+		// @end
+	],
+	// the packages' source on the page, on the dev server's own side and in the tests (the library's `config/vite.ts`)
+	...sourceLibrary(),
+	// @if tests
+	test: { environment: 'node' }
+	// @end
+})

package/layers/tests/package.json

@@ -0,0 +1,8 @@
+{
+	"scripts": {
+		"test": "vitest run"
+	},
+	"devDependencies": {
+		"vitest": "^5.0.5"
+	}
+}

package/package.json

@@ -1,6 +1,47 @@
 {
-  "name": "@v12-engine/create",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@v12-engine/create",
+	"version": "0.1.1",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/DoronTorangy/V12.git",
+		"directory": "packages/create"
+	},
+	"type": "module",
+	"description": "A project to start a game from: npm create @v12-engine my-game",
+	"bin": {
+		"create": "./bin.mjs",
+		"create-v12": "./bin.mjs",
+		"v12": "./v12.mjs"
+	},
+	"exports": {
+		".": "./index.mjs"
+	},
+	"files": [
+		"bin.mjs",
+		"v12.mjs",
+		"cli.mjs",
+		"index.mjs",
+		"starters.mjs",
+		"base",
+		"layers",
+		"starters"
+	],
+	"engines": {
+		"node": ">=22.12"
+	},
+	"scripts": {
+		"test": "vitest run --dir tests",
+		"typecheck": "tsc --noEmit && node scripts/typecheckStarters.mjs"
+	},
+	"devDependencies": {
+		"vitest": "^5.0.5"
+	},
+	"dependencies": {
+		"@clack/prompts": "^1.8.1",
+		"commander": "^15.0.0"
+	}
+}

package/starters/campaign/README.md

@@ -0,0 +1,61 @@
+# My game
+
+A campaign made with V12: three missions on the long road home, a hero carried from one to the next. Burn the Red Hand's camp, hold the fort through a night of waves, and climb the pass to Varga's hold.
+
+| To      | Run                                                                  |
+| ------- | -------------------------------------------------------------------- |
+| Play it | `npm run dev`, and open the page it says: its start screen, Campaign |
+<!-- @if editor -->
+| Make maps | `npm run dev`, and open `/?editor`: Save writes them into `src/maps`, with a names file each |
+| Check the maps | `npm run map check`: every map in `src/maps` against the game's rules |
+<!-- @end -->
+<!-- @if server -->
+<!-- @if !rooms -->
+| Play it on a server | `npm run server`, beside `npm run dev`, and open `/?server` |
+<!-- @end -->
+<!-- @if rooms -->
+| Play it online | `npm run server`, beside `npm run dev`, and open `/?find-game` |
+<!-- @end -->
+<!-- @end -->
+<!-- @if tests -->
+| Test the rules | `npm test` |
+<!-- @end -->
+| Check the types | `npm run typecheck` |
+| Build the page to host | `npm run build`, into `dist/` |
+
+## What is where
+
+- `src/campaign/`: the game. `index.ts` puts the rules together and gives each map its mission; `ids.ts` names everything once; `units.ts` the units, buildings, the hero, his abilities and the items; `missions/` a file a mission: `homecoming.ts` (objectives, a prefab, areas, a brain that holds and raids), `siege.ts` (the waves, the gate, effects fired from the rules), `warlord.ts` (the hero carried in, a shop, the talk at the gate and its choice, the prisoners); `waves.ts` the waves, as `waves.json` says them; `view/` how it looks and sounds, with the cinematic of the talk in code; `cinematics/` the intro and the outro, made in the editor's Cinematic panel; `prefabs/` what the editor's Save as a prefab wrote; `campaign.json` the campaign's chapters and missions (their maps, words, briefings, debriefs), what the editor's Campaign panel writes, and `scenes.ts` what of them is code, for the page (`defineCampaign`); `data.json`, `looks.json`, `fx.json` and `waves.json` what the editor's Data, model, Effects and Waves panels write
+- `src/rules.ts`, `src/game.ts`, `src/maps.ts`: the game by the names the page, the server and the tests know it by
+- `src/maps/`: the missions' maps, made in the editor. Each has the names its mission's rules look for (`hall`, `hero`, `camp`, `warcamp`, `gate`, `cells`…): a names file beside each says which
+- `src/main.ts`: the page: the start screen, the campaign's menu and its missions, free play, the settings
+
+<!-- @if editor -->
+
+- `src/editor.ts`: the map editor, with what `src/campaign-editor.ts` adds as one extension: the Waves panel (`src/waves-panel.ts`: the waves listed, found, changed and undone, where they come out drawn in the scene) and the search's entries. Saved while the editor is open, they change in it
+<!-- @end -->
+<!-- @if server -->
+<!-- @if !rooms -->
+
+- `server.ts`: a server of the game, one game at a time, `startServer`: the first mission's map, the computer at the Red Hand's seat
+<!-- @end -->
+<!-- @if rooms -->
+
+- `server.ts`: a server of many games, `GameRooms`: a room for each map, games players make (New game) and are matched for (Play now). The page's `/?find-game` is the client's Find a game
+<!-- @end -->
+<!-- @end -->
+<!-- @if tests -->
+
+- `tests/`: the missions tested with no page: the maps checked, each mission won and lost as it says, the waves, the carried hero, the choice at the gate, the computer playing a minute (`simulate`)
+<!-- @end -->
+- `public/games/campaign/`: the game's own folder of files: what the editor's Assets panel takes in (models, sounds, pictures), with an `assets.json` saying what is there
+- `@v12-engine/assets`: the shared art every unit and building is drawn with (adventurers with their clips and their gear, buildings, trees), served where `public/`'s files are by `assetsPackage()` in `vite.config.ts`, and copied into a build as the game uses it. Whose each file is: its group's `CREDITS.md` in `node_modules/@v12-engine/assets/groups/`
+
+## Where to go from here
+
+The tutorial that ends in this project, chapter by chapter, is the docs' Let's make a basic campaign. Then:
+
+1. **A fourth mission.** A map in the editor (names for what the rules look for), a file in `src/campaign/missions/`, the mission in the Campaign panel (`campaign.json`), its `start` in `scenes.ts` and a line in `index.ts`'s `MISSIONS`.
+2. **A second ability of the hero's own.** `defineEffect` in `units.ts` for what the engine's effects do not do, and a line in `hero.learns`. The docs' Let's add a hero with abilities and items walks through it.
+3. **More for the waves.** `waves.json` in the editor's Waves panel; a new kind of raider in `units.ts` and in `WAVE_UNITS`.
+4. **Your own art.** Drop a glTF on the editor's Assets panel: Set up as a unit writes `looks.json`, which the view lays over its code.