@v12-engine/create 0.1.0 → 0.4.0

package/starters/examples/src/examples/showcase/looks.ts

@@ -0,0 +1,238 @@
+/**
+ * The showcases on the client's side: the looks of their own units (the boss and its dead, the towers, the raiders and
+ * the keep), the effects their rules play, and cards that read how each scene stands from what the rules tell every
+ * screen (a component replicated on an entity: `EntityState.components`)
+ */
+import type { EntityView, GameClientApi, GameView, UnitLook } from '@v12-engine/client'
+import { presetFx } from '@v12-engine/client'
+import { button, type CategoryLooks, readout, select, toggle } from '../../shell/look'
+import { character, hold, person, TWO_HANDED } from '../common/looks'
+import { ENEMY, PLAYER } from '../common/units'
+import {
+	bossCharge,
+	bossReset,
+	buildTower,
+	callWave,
+	defenseReset,
+	generalsReset,
+	halt,
+	marchAs,
+	rewind,
+	rewindFight,
+	rewindReset,
+	SHOW,
+	TOWER_COST
+} from './index'
+
+/** The effects the showcases' rules play (`world.fx`), taken into the game's look */
+const EFFECTS = ['dust', 'shockwave', 'explosion', 'ground-crack', 'impact-ring'] as const
+
+const looks: Record<string, UnitLook> = {
+	[SHOW.showcaseBoss]: {
+		height: 4.4,
+		model: character('skeleton_warrior', 1.9, { hold: [hold('sword_2handed_color')] }),
+		attacks: [TWO_HANDED],
+		// red with rage in its last phase: the buff it carries
+		tintFor: (entity: EntityView) => (entity.state.buffs?.includes('showcase.enraged') ? [1, 0.45, 0.4] : undefined),
+		death: { clip: 'Skeletons_Death', fx: 'explosion', corpse: { lie: 6, sink: 3 } },
+		shapes: person(4.4)
+	},
+	[SHOW.showcaseRisen]: {
+		height: 1.6,
+		model: character('skeleton_minion', 0.65, { animations: { idle: 'Skeletons_Idle', walk: 'Skeletons_Walking' } }),
+		death: { shatter: 10 },
+		shapes: person(1.6)
+	},
+	[SHOW.showcaseTower]: {
+		height: 3.2,
+		model: { src: 'rts/small_watch_tower.glb', scale: 1.15 },
+		shot: { color: [0.9, 0.8, 0.55], size: 0.2 },
+		shapes: [{ shape: 'cylinder', size: [1.2, 3, 1.2], offset: [0, 1.5, 0], color: [0.6, 0.5, 0.4] }]
+	},
+	[SHOW.showcaseRaider]: {
+		height: 1.6,
+		model: character('skeleton_rogue', 0.62, { hold: [hold('dagger')], animations: { walk: 'Skeletons_Walking' } }),
+		death: { shatter: 8 },
+		shapes: person(1.6)
+	},
+	[SHOW.showcaseBrute]: {
+		height: 2.2,
+		model: character('skeleton_warrior', 0.95, { hold: [hold('axe_1handed'), hold('shield_spikes', 'l')] }),
+		death: { shatter: 14, fx: 'dust' },
+		shapes: person(2.2)
+	},
+	[SHOW.showcaseKeep]: {
+		height: 4,
+		model: { src: 'rts/castle.glb', scale: 0.75 },
+		shapes: [{ shape: 'box', size: [4, 3, 4], offset: [0, 1.5, 0], color: [0.6, 0.6, 0.65] }]
+	}
+}
+
+/** The first unit of a type the client knows, alive */
+const first = (client: GameClientApi, type: string) => [...client.state.entities.values()].find((each) => each.def.id === type && each.health > 0)
+/** How many of a side are alive */
+const count = (client: GameClientApi, owner: number) =>
+	[...client.state.entities.values()].filter((each) => each.owner === owner && each.health > 0).length
+/** A component the rules tell every screen, on a unit of a type: what the snapshot carries of it */
+function told<T>(client: GameClientApi, type: string, component: string): T | undefined {
+	const entity = client.session.snapshot().entities.find((each) => each.type === type && each.health > 0)
+	return entity?.components?.[component] as T | undefined
+}
+
+/** Puts the camera at a point, `distance` back and as steep as `pitch`, letting it go that far and a half again */
+const stage = (client: GameClientApi, x: number, z: number, distance: number, pitch: number, yaw = 0) => {
+	client.camera.setLimits({ max: Math.max(distance * 1.5, 60) })
+	client.camera.setPose({ x, z, distance, yaw, pitch })
+}
+
+export const category: CategoryLooks = {
+	view: (view: GameView<any>) => ({
+		...view,
+		units: { ...view.units, looks: { ...view.units.looks, ...looks } },
+		fx: { ...view.fx, defs: { ...presetFx([...EFFECTS]), ...view.fx?.defs } }
+	}),
+	looks: {
+		'showcase-boss': {
+			controls: [
+				button('Charge!', (client) => client.session.send(bossCharge.make({})), 'Sends the party at the Bone King, fighting whatever is in the way'),
+				button(
+					'Start the fight again',
+					(client) => client.session.send(bossReset.make({})),
+					'The party and the Bone King back where they started, whole, his dead gone'
+				),
+				readout(
+					'The Bone King',
+					(client) => {
+						const boss = first(client, SHOW.showcaseBoss)
+						if (!boss) return 'fallen!'
+						const fight = told<{ phase: number }>(client, SHOW.showcaseBoss, 'showcase.bossFight')
+						const phase = ['', 'phase 1', 'phase 2: the dead rise', 'phase 3: enraged'][fight?.phase ?? 1]
+						return `${Math.round((boss.health / boss.maxHealth) * 100)}% · ${phase}`
+					},
+					'His health left, and his phase: at two thirds the dead rise, at a third he is enraged'
+				),
+				readout(
+					'Party · his dead',
+					(client) => {
+						const dead = [...client.state.entities.values()].filter((each) => each.def.id === SHOW.showcaseRisen && each.health > 0).length
+						return `${count(client, PLAYER)} · ${dead}`
+					},
+					'Your party left alive, and the risen dead fighting for him'
+				)
+			],
+			ready: (client) => stage(client, 24, 23, 28, 0.8)
+		},
+		'showcase-defense': {
+			controls: [
+				button(
+					`Build a tower (${TOWER_COST} gold)`,
+					(client) => client.session.send(buildTower.make({})),
+					'A tower on the next free spot by the road, if you have the gold: it shoots raiders as they pass'
+				),
+				button(
+					'Call the next wave now',
+					(client) => client.session.send(callWave.make({})),
+					'The next wave comes at once rather than in a few seconds, and you get fifteen gold for not waiting'
+				),
+				button(
+					'Start again',
+					(client) => client.session.send(defenseReset.make({})),
+					'Takes everything away and holds the road again from the first wave'
+				),
+				readout(
+					'Wave · lives · gold',
+					(client) => {
+						const defense = told<{ wave: number; lives: number; gold: number }>(client, SHOW.showcaseKeep, 'showcase.defense')
+						return defense ? `${defense.wave} · ${defense.lives} · ${defense.gold}` : '…'
+					},
+					'The wave it is, the lives the keep has left (a raider at the keep takes one, a brute three), and your gold'
+				),
+				readout(
+					'Raiders on the road · towers',
+					(client) => {
+						const all = [...client.state.entities.values()].filter((each) => each.health > 0)
+						const raiders = all.filter((each) => each.def.id === SHOW.showcaseRaider || each.def.id === SHOW.showcaseBrute).length
+						return `${raiders} · ${all.filter((each) => each.def.id === SHOW.showcaseTower).length}`
+					},
+					'Raiders alive on the road now, and your towers'
+				)
+			],
+			ready: (client) => stage(client, 24, 20, 46, 0.95)
+		},
+		'showcase-generals': {
+			controls: [
+				button(
+					'Lay them out again',
+					(client) => client.session.send(generalsReset.make({})),
+					'Both armies whole and back in place: the two computer generals fight it out again'
+				),
+				readout('Blue · red', (client) => `${count(client, PLAYER)} · ${count(client, ENEMY)}`, 'Units each side has left alive')
+			],
+			ready: (client) => stage(client, 32, 28, 36, 0.8)
+		},
+		'showcase-rewind': {
+			controls: [
+				button(
+					'Fight',
+					(client) => client.session.send(rewindFight.make({})),
+					'Sends both sides at each other: let them fight a while before turning back'
+				),
+				button(
+					'Back 3 seconds',
+					(client) => client.session.send(rewind.make({ seconds: 3 })),
+					'Every unit back where it stood and as hurt as it was 3 seconds ago, the fallen up again: the fight goes on from there'
+				),
+				button('Back 10 seconds', (client) => client.session.send(rewind.make({ seconds: 10 })), 'The same, 10 seconds back'),
+				button(
+					'From the start',
+					(client) => client.session.send(rewindReset.make({})),
+					'The battle laid out as it began, the record of it started over'
+				),
+				readout(
+					'Blue · red',
+					(client) => `${count(client, PLAYER)} · ${count(client, ENEMY)}`,
+					'Units each side has left alive: turn back and the fallen count again'
+				)
+			],
+			ready: (client) => stage(client, 24, 21, 24, 0.75)
+		},
+		'showcase-march': {
+			controls: [
+				select(
+					'Formation',
+					['rows', 'square', 'circle'],
+					'rows',
+					(client, shape) => client.session.send(marchAs.make({ shape: shape as 'rows' })),
+					'The shape each of the three companies takes behind the knight: they change it as they march'
+				),
+				toggle(
+					'Halt',
+					false,
+					(client, halted) => client.session.send(halt.make({ halted })),
+					'On, the knight and the companies stop where they are; off, they march on'
+				),
+				button(
+					'Follow the knight',
+					(client) => {
+						const knight = [...client.state.entities.values()].find((each) => each.def.id === 'knight' && each.health > 0)
+						if (knight) client.follow(knight.id)
+					},
+					'The camera follows the knight at the head of the march'
+				),
+				button(
+					'Look over the field',
+					(client) => {
+						client.follow(null)
+						stage(client, 32, 28, 60, 0.95)
+					},
+					'The camera stops following and looks down on the whole road'
+				),
+				readout('Marching', (client) => `${count(client, PLAYER)} in three companies`, 'Everyone on the march, the knight too')
+			],
+			ready: (client) => {
+				client.camera.setLimits({ max: 90 })
+				stage(client, 32, 28, 60, 0.95)
+			}
+		}
+	}
+}

package/starters/examples/src/game.ts

@@ -0,0 +1,17 @@
+/**
+ * The game whole: its rules (`src/rules.ts`) and its look (`src/view.ts`), fetched as the page first plays it. What the
+ * page, the server and the tests take; a server or a test never fetches the look
+ */
+import { game } from './rules'
+
+// @if !desktop
+game.view(() => import('./view'))
+// @end
+// @if desktop
+// its look with what the desktop app adds to it: a Windowed setting, Quit on the pause menu
+game.view(() => Promise.all([import('./view'), import('./desktop')]).then(([{ view }, { desktopView }]) => desktopView(view)))
+// @end
+
+export { game } from './rules'
+export { examples, exampleNamed } from './examples/catalog'
+export { ENEMY, PLAYER, UNIT } from './examples/common/units'

package/starters/examples/src/main.ts

@@ -0,0 +1,82 @@
+/**
+ * The page: the examples' list first (`src/shell/scenes.ts`), each example a scene of an app of scenes (`startApp`,
+ * `@v12-engine/client/app`), one shown at a time. `appScenes` makes the usual ones beside them: the start screen,
+ * the game on its field, and the settings.
+// @if editor
+ * The map editor too, set up in `src/editor.ts`.
+// @end
+// @if server
+ * A seat at the game's server too (`npm run server`).
+// @end
+ * The address opens straight into a scene by its id: `/?fx-fireball`, an example; `/?home`, the start screen; the
+ * examples' list otherwise. The debug panel (🐞 on the top bar, Alt+Shift+D) and its cheats are in the game while
+ * developing (`npm run dev`), not in a built page
+ */
+// @if !desktop
+import { appScenes, sceneAsked, sceneRef, startApp } from '@v12-engine/client/app'
+// @end
+// @if desktop
+import { appScenes, exitButton, sceneAsked, sceneRef, startApp } from '@v12-engine/client/app'
+// @end
+import '@v12-engine/client/styles.css'
+// the theme's typefaces come with the client: the page's own font stays what it was
+import '@v12-engine/client/fonts.css'
+// @if editor
+import { editor } from './editor'
+// @end
+import { game } from './game'
+import { EXAMPLES, exampleScenes, examplesIndex } from './shell/scenes'
+// @if desktop
+// what the desktop app adds: its shell's stores, the game saved as the window closes, an error log, updates, Exit
+import { desktop } from './desktop'
+// @end
+
+// @if desktop
+const shell = desktop()
+
+// @end
+const scenes = appScenes({
+	// the game (`src/game.ts`): its look (and the client that draws it) is fetched as a scene first plays it, so that the
+	// list shows at once
+	game,
+	// @if editor
+	editor,
+	// @end
+	// @if single
+	server: true,
+	// @end
+	// @if rooms
+	server: { rooms: true },
+	// @end
+	// the examples' list first on the start screen, and every example among the scenes
+	home: {
+		buttons: [{ label: 'Examples', scene: sceneRef(EXAMPLES) }],
+		// @if desktop
+		// Exit, last on the start screen: in the shell alone, as a page cannot close its tab
+		after: [exitButton(shell)]
+		// @end
+	},
+	extra: [examplesIndex, ...exampleScenes()],
+	menu: { description: 'What V12 can do, a small scene each.' },
+	// the Credits on the start screen (`creditsScene`): who made the game, by parts, scrolling
+	credits: {
+		sections: [
+			{ title: 'Made by', names: ['You'] },
+			{ title: 'Made with', names: ['V12'] }
+		]
+	}
+})
+
+/** The ground's textures made in a worker of the page's (`src/ground.worker.ts`), made at the first texture: the page goes on while they are made */
+const groundWorker = () => new Worker(new URL('./ground.worker.ts', import.meta.url), { type: 'module' })
+/** The navigations of its worlds built in another (`src/navigation.worker.ts`), made at the first build */
+const navigationWorker = () => new Worker(new URL('./navigation.worker.ts', import.meta.url), { type: 'module' })
+
+// @if !desktop
+const app = startApp({ target: '#game', game, scenes, start: sceneAsked(scenes, EXAMPLES), groundWorker, navigationWorker })
+// @end
+// @if desktop
+const app = startApp({ target: '#game', game, scenes, start: sceneAsked(scenes, EXAMPLES), groundWorker, navigationWorker, ...shell.options })
+shell.started(app)
+// @end
+Object.assign(window, { app })

package/starters/examples/src/rules.ts

@@ -0,0 +1,31 @@
+/**
+ * The rules: one game (`createGame`) that every example plays, each with a map and a start of its own. What the
+ * examples share is here (the ground's tiles, the shared units: `src/examples/common/units.ts`); what each category
+ * adds (its units, abilities, commands) is its folder's `index.ts`, registered below. The engine alone
+ * (`@v12-engine/engine`), so the page, the server and the tests play the same game
+ */
+import { createGame, hotGame } from '@v12-engine/engine'
+import { categories } from './examples/catalog'
+import { sharedUnits } from './examples/common/units'
+import { exampleField, tiles } from './examples/define'
+
+export const game = createGame({
+	// the maps of this game say they are its own by this id
+	id: 'examples',
+	name: 'Examples',
+	// a view that names what the rules do not have (a look for no unit type) stops the page, saying what was meant
+	checkView: 'throw',
+	tiles,
+	// nobody wins or loses: an example plays until it is left
+	victory: null
+})
+
+sharedUnits(game)
+// each category's units, abilities and commands
+for (const category of Object.values(categories)) category.rules?.(game)
+
+// the game's one map of its own, what a server plays and the editor opens: each example says its own (`ExampleDef.map`)
+game.maps({ field: exampleField() })
+
+// saved while it runs (npm run dev): the game and the editor open take the new version, with no new page
+if (import.meta.hot) import.meta.hot.accept((module) => hotGame(import.meta.hot, game, module?.game))

package/starters/examples/src/shell/look.ts

@@ -0,0 +1,79 @@
+/**
+ * What an example is on the client's side (`ExampleLook`): how it changes the game's look, the controls listed beside
+ * it, and what it does once its game is drawn. A category's `looks.ts` gives them by the example's id. Types alone of
+ * the client here: this file is part of the list's page, which carries none of the client's code
+ */
+import type { GameClientApi, GameView } from '@v12-engine/client'
+
+/**
+ * A control beside an example: a button, an on and off, a slider or a choice. Each runs with the example's client, and
+ * says what it does (`hint`): shown under the controls while the pointer is over it, and as its tooltip
+ */
+export type ExampleControl =
+	| { kind: 'button'; label: string; hint: string; run: (client: GameClientApi) => void }
+	| { kind: 'toggle'; label: string; hint: string; value: boolean; set: (client: GameClientApi, on: boolean) => void }
+	| {
+			kind: 'slider'
+			label: string
+			hint: string
+			min: number
+			max: number
+			step?: number
+			value: number
+			set: (client: GameClientApi, value: number) => void
+	  }
+	| { kind: 'select'; label: string; hint: string; options: readonly string[]; value: string; set: (client: GameClientApi, value: string) => void }
+	| { kind: 'text'; label: string; hint?: string; text: (client: GameClientApi) => string }
+
+/** An example's own on the client's side */
+export interface ExampleLook {
+	/** The game's look for this example: units, abilities, the HUD, renderers of its own over the game's */
+	view?: (view: GameView<any>) => GameView<any>
+	/** Its controls, listed under its summary */
+	controls?: readonly ExampleControl[]
+	/**
+	 * Called once its game is drawn, with the client: the camera put where it should look, a unit selected, a light
+	 * added. Returns what undoes it as the example is left, when anything needs to be
+	 */
+	ready?: (client: GameClientApi) => void | (() => void)
+}
+
+/** What a category's `looks.ts` gives: its examples' looks by id, and what its examples all need of the game's look */
+export interface CategoryLooks {
+	looks?: Readonly<Record<string, ExampleLook>>
+	/** Laid over the whole game's look once (its units', abilities' and effects' looks), before any example's own */
+	view?: (view: GameView<any>) => GameView<any>
+}
+
+/** A button, and what pressing it does */
+export const button = (label: string, run: (client: GameClientApi) => void, hint: string): ExampleControl => ({ kind: 'button', label, run, hint })
+/** An on and off, `value` at first, and what it turns on */
+export const toggle = (label: string, value: boolean, set: (client: GameClientApi, on: boolean) => void, hint: string): ExampleControl => ({
+	kind: 'toggle',
+	label,
+	value,
+	set,
+	hint
+})
+/** A slider from `min` to `max`, `value` at first */
+export const slider = (
+	label: string,
+	range: { min: number; max: number; step?: number; value: number },
+	set: (client: GameClientApi, value: number) => void,
+	hint: string
+): ExampleControl => ({ kind: 'slider', label, ...range, set, hint })
+/** A choice of `options`, `value` at first */
+export const select = (
+	label: string,
+	options: readonly string[],
+	value: string,
+	set: (client: GameClientApi, value: string) => void,
+	hint: string
+): ExampleControl => ({ kind: 'select', label, options, value, set, hint })
+/** A line of text kept up to date (twice a second), and what it counts when that is not plain from its label */
+export const readout = (label: string, text: (client: GameClientApi) => string, hint?: string): ExampleControl => ({
+	kind: 'text',
+	label,
+	text,
+	...(hint && { hint })
+})

package/starters/examples/src/shell/registry.ts

@@ -0,0 +1,7 @@
+/**
+ * Where the examples' looks are kept once the game's look is fetched (`src/view.ts` fills it): what an example's scene
+ * reads as it opens. Nothing of the client's code here, so the list's page can name it
+ */
+import type { ExampleLook } from './look'
+
+export const registry: { looks: Readonly<Record<string, ExampleLook>> } = { looks: {} }

package/starters/examples/src/shell/scenes.ts

@@ -0,0 +1,178 @@
+/**
+ * The examples as scenes of the app: the list's own page (`examples`, a card of each example by category) and a game
+ * scene for each example, its id its scene's (`/?fx-fireball` opens it straight). Each is drawn in the frame
+ * (`./shell.ts`): the list down the left, the example on the right with its card. The client's code is fetched as an
+ * example first opens, not with the list
+ */
+import { gameScene, type Scene, type SceneOpenContext, sceneRef } from '@v12-engine/client/app'
+import type { GameClientApi, GameView, LoadProgress } from '@v12-engine/client'
+import { errorFields } from '@v12-engine/engine'
+import { game } from '../game'
+import { examples } from '../examples/catalog'
+import { CATEGORIES, exampleField, type ExampleDef } from '../examples/define'
+import type { ExampleLook } from './look'
+import { registry } from './registry'
+import { mountShell, type Shell } from './shell'
+
+/** The list's page's id: where an example's leave button goes */
+export const EXAMPLES = 'examples'
+
+/** The categories whose examples show what a player has (gold, lumber, supply) on the HUD's top */
+const RESOURCES_SHOWN: readonly string[] = ['rts', 'moba']
+
+/** Opens an example by its id, or the list's page for none */
+const opener = (context: SceneOpenContext<any>) => (id: string) => context.goTo(sceneRef(id || EXAMPLES))
+
+/** Fetches an example ahead of its opening: its code and the files it starts with (models, textures), once */
+const warmer = (context: SceneOpenContext<any>) => (id: string) => void context.warm?.(id)
+
+/** What the frame is told by a scene: how to open another, warm it, and go to the start screen */
+const shellOptions = (context: SceneOpenContext<any>) => ({
+	open: opener(context),
+	warm: warmer(context),
+	home: () => context.goTo(sceneRef('home'))
+})
+
+/** The list's own page: every example as a card, by category */
+export const examplesIndex: Scene = {
+	id: EXAMPLES,
+	name: 'Examples',
+	names: [sceneRef('home')],
+	open(element, context) {
+		const shell = mountShell(element, shellOptions(context))
+		const page = document.createElement('div')
+		page.className = 'vx-index'
+		page.innerHTML = `<h1>Examples</h1><p>What the engine can do, a small scene each. Pick one on the left or below: it plays at
+			once, with its controls on a card over it. Each is a few dozen lines in <code>src/examples/</code>, its rules in its
+			category's <code>index.ts</code> and its look and controls in its <code>looks.ts</code>: read one, copy it, change it.</p>`
+		for (const category of CATEGORIES) {
+			const own = examples.filter((each) => each.category === category.id)
+			if (!own.length) continue
+			const title = document.createElement('h2')
+			title.textContent = category.title
+			const about = document.createElement('p')
+			about.textContent = category.summary
+			const grid = document.createElement('div')
+			grid.className = 'vx-grid'
+			for (const def of own) {
+				const tile = document.createElement('a')
+				tile.className = 'vx-tile'
+				tile.href = `?${def.id}`
+				tile.innerHTML = '<strong></strong><span></span>'
+				tile.querySelector('strong')!.textContent = def.title
+				tile.querySelector('span')!.textContent = def.summary
+				tile.onclick = (event) => {
+					if (event.metaKey || event.ctrlKey || event.shiftKey) return
+					event.preventDefault()
+					context.goTo(sceneRef(def.id))
+				}
+				tile.onpointerenter = () => void context.warm?.(def.id)
+				grid.append(tile)
+			}
+			page.append(title, about, grid)
+		}
+		shell.content.append(page)
+		return () => shell.dispose()
+	}
+}
+
+/** An example's scene: its game in the frame, its look laid over the game's, its controls on its card once it is drawn */
+export function exampleScene(def: ExampleDef): Scene {
+	// the frame of the scene open now, which the view's frame phase tells once the game is drawn
+	const open: { shell?: Shell } = {}
+	const scene = gameScene({
+		id: def.id,
+		name: def.title,
+		game,
+		map: def.map ?? (() => exampleField()),
+		// the example's own start, or none: the game's (a scout) is for the field alone
+		onStart: def.start ?? (() => {}),
+		...(def.environment && { environment: def.environment }),
+		reveal: def.reveal ?? true,
+		exit: { label: 'Examples', scene: sceneRef(EXAMPLES) },
+		view: (view) => withExample(view, def, registry.looks[def.id], (client, look) => open.shell?.controls(look, client)),
+		// shown at once, the list beside it, with how far its files are: not the scene before it held until it is ready
+		loading: { mount: (element, progress) => loadingScreen(element, def.title, progress) }
+	})
+	return {
+		...scene,
+		names: [sceneRef(EXAMPLES), sceneRef('home')],
+		open(element, context) {
+			const shell = mountShell(element, { current: def, ...shellOptions(context) })
+			open.shell = shell
+			const drawn = document.createElement('div')
+			drawn.className = 'vx-game'
+			shell.content.prepend(drawn)
+			const stop = scene.open(drawn, context)
+			return () => {
+				stop()
+				shell.dispose()
+				if (open.shell === shell) open.shell = undefined
+			}
+		}
+	}
+}
+
+/**
+ * The game's look with an example's over it, and a phase of the frame that, at the first frame, hands the example's
+ * `ready` the client (what it returns run as the game stops) and tells the card its controls can run
+ */
+function withExample(
+	view: GameView,
+	def: ExampleDef,
+	look: ExampleLook | undefined,
+	drawn: (client: GameClientApi, look: ExampleLook | undefined) => void
+): GameView {
+	const own = look?.view ? look.view(view) : view
+	let told = false
+	return {
+		...own,
+		// the gold and lumber the RTS and MOBA examples play with are the one game's: shown in theirs alone
+		...(!RESOURCES_SHOWN.includes(def.category) && {
+			hud: { ...own.hud, widgets: [...(own.hud?.widgets ?? []), { id: 'resources', when: () => false }] }
+		}),
+		framePhases: [
+			...(own.framePhases ?? []),
+			{
+				name: 'examples.ready',
+				run: (_frame, client) => {
+					if (told) return
+					told = true
+					try {
+						const undo = look?.ready?.(client)
+						if (typeof undo === 'function') client.onStop(() => undo())
+					} catch (error) {
+						client.log.error('examples', 'The example failed as it was made ready', errorFields(error))
+					}
+					drawn(client, look)
+				}
+			}
+		]
+	}
+}
+
+/** The loading screen in the example's place: its name, a spinner, and a bar of how far its files are */
+function loadingScreen(element: HTMLElement, title: string, progress: () => LoadProgress): () => void {
+	const screen = document.createElement('div')
+	screen.className = 'vx-loading'
+	screen.innerHTML = '<div class="vx-spinner"></div><strong></strong><div class="vx-bar"><div></div></div><span></span>'
+	screen.querySelector('strong')!.textContent = title
+	const bar = screen.querySelector<HTMLElement>('.vx-bar > div')!
+	const count = screen.querySelector('span')!
+	let frame = 0
+	const update = () => {
+		const { done, total } = progress()
+		bar.style.width = `${total ? Math.round((done / total) * 100) : 0}%`
+		count.textContent = total ? `${done} of ${total} files` : 'Starting…'
+		frame = requestAnimationFrame(update)
+	}
+	update()
+	element.append(screen)
+	return () => {
+		cancelAnimationFrame(frame)
+		screen.remove()
+	}
+}
+
+/** Every example's scene */
+export const exampleScenes = (): Scene[] => examples.map(exampleScene)