@v12-engine/create 0.1.1 → 0.4.0

package/starters/examples/src/examples/cinematics/tour.json

@@ -0,0 +1,43 @@
+{
+	"id": "cinematics.tour",
+	"name": "A tour of Elmbrook",
+	"length": 18,
+	"lanes": [
+		{
+			"id": "camera",
+			"kind": "camera",
+			"items": [
+				{ "at": 0, "value": { "x": 24, "z": 6, "distance": 40, "yaw": 0, "pitch": 0.8 } },
+				{ "at": 6, "value": { "x": 24, "z": 22, "distance": 20, "yaw": 0.6, "pitch": 0.5 }, "path": "smooth", "ease": "inOutCubic" },
+				{ "at": 12, "value": { "x": 24, "z": 30, "distance": 18, "yaw": 2.8, "pitch": 0.45 }, "path": "smooth", "ease": "inOutSine" },
+				{ "at": 16, "value": { "x": 24, "z": 26, "distance": 42, "yaw": 3.6, "pitch": 0.9 }, "ease": "inOutSine" }
+			]
+		},
+		{
+			"id": "screen",
+			"kind": "screen",
+			"items": [
+				{ "at": 0, "for": 18, "letterbox": 2.39, "vignette": 0.3, "in": 0.6, "out": 0.8 },
+				{ "at": 0, "for": 1.5, "fade": 1, "in": 0, "out": 1.5 }
+			]
+		},
+		{
+			"id": "ui",
+			"kind": "ui",
+			"items": [{ "at": 0.5, "for": 4, "ui": "title", "title": "Elmbrook", "subtitle": "made in a file", "in": 0.6, "out": 0.8 }]
+		},
+		{
+			"id": "dialog",
+			"kind": "dialog",
+			"items": [
+				{ "at": 1.5, "for": 4.5, "speaker": "cinematics.narrator", "text": "In the north there is a village where the road ends." },
+				{ "at": 7.5, "for": 4.5, "speaker": "cinematics.narrator", "text": "Its people keep the fire lit, and the bell rung." }
+			]
+		}
+	],
+	"markers": [
+		{ "at": 0, "name": "road", "kind": "section" },
+		{ "at": 6, "name": "square", "kind": "section" },
+		{ "at": 12, "name": "bell", "kind": "section" }
+	]
+}

package/starters/examples/src/examples/cinematics/village.ts

@@ -0,0 +1,88 @@
+/**
+ * A village to stage scenes in: a field with houses round a bonfire, a well, a market, carts and hay, a dirt road in
+ * from the south and woods round the edge. Scenery only (`MapDoodad`): the rules never see it. The cinematics and the
+ * dialogue examples play here, each with its own name for the map (`world.map.name`), which their rules check to know
+ * the example is theirs
+ */
+import { exactMath, type GameMap, type MapDoodad } from '@v12-engine/engine'
+import { exampleField } from '../define'
+
+/** The middle of the village: the bonfire */
+export const SQUARE = { x: 24, z: 26 }
+/** Where the road comes in, at the south edge */
+export const ROAD_END = { x: 24, z: 4 }
+
+/** A few houses, the well, the market and what lies about, round the square: [model, x, z, facing] */
+const BUILDINGS: [string, number, number, number][] = [
+	['village/bonfire.glb', SQUARE.x, SQUARE.z, 0],
+	['village/fantasy_house.glb', 15, 33, 2.4],
+	['village/fantasy_house_2.glb', 33, 34, -2.4],
+	['village/fantasy_inn.glb', 14, 21, 1.6],
+	['village/fantasy_house_3.glb', 34, 20, -1.6],
+	['village/well.glb', 29.5, 28.5, 0],
+	['village/market_stand.glb', 19.5, 27, 1.2],
+	['village/cart.glb', 28.5, 22, 0.4],
+	['village/hay.glb', 31, 25.5, 0],
+	['village/barrel.glb', 20, 31, 0],
+	['village/crate.glb', 21, 30.2, 0.5],
+	['village/bench.glb', 25.5, 29.5, 0],
+	['village/fence.glb', 21, 14, 0],
+	['village/fence.glb', 27, 14, 0],
+	['village/bell_tower.glb', 24, 40, Math.PI],
+	// the old stones north of the fire, in a ring
+	...[0, 1, 2, 3, 4, 5].map((i): [string, number, number, number] => [
+		'village/rocks.glb',
+		24 + exactMath.cos(i * 1.047) * 2.6,
+		33 + exactMath.sin(i * 1.047) * 2.6,
+		i * 1.3
+	])
+]
+
+/** The woods round the edge: trees in a ring, a little off from even, the same on every map made */
+function woods(): MapDoodad[] {
+	const trees: MapDoodad[] = []
+	const models = ['trees/oak_1.glb', 'trees/oak_2.glb', 'trees/columnar_1.glb', 'trees/columnar_3.glb']
+	for (let i = 0; i < 44; i++) {
+		const angle = (i / 44) * Math.PI * 2
+		// a gap where the road comes in
+		if (Math.abs(angle - Math.PI * 1.5) < 0.22) continue
+		const away = 19 + ((i * 7) % 5)
+		const x = 24 + exactMath.cos(angle) * away
+		const z = 24 + exactMath.sin(angle) * away
+		const size = 0.9 + ((i * 13) % 7) / 14
+		trees.push({ id: 100 + i, model: models[i % models.length], x, z, yaw: i * 1.7, scale: [size, size, size] })
+	}
+	return trees
+}
+
+/** The village, called `name` (what the example's rules know it by), with `players` players */
+export function villageMap(name: string, players = 2): GameMap {
+	const map = exampleField({ name, players })
+	const dirt = map.tileset.indexOf('dirt') + 1
+	const darkGrass = map.tileset.indexOf('darkGrass') + 1
+	// the road in from the south, and the trodden square round the bonfire
+	for (let z = 0; z < map.depth; z++)
+		for (let x = 0; x < map.width; x++) {
+			const square = exactMath.hypot(x + 0.5 - SQUARE.x, z + 0.5 - SQUARE.z)
+			const road = Math.abs(x + 0.5 - 24) < 1.6 && z < SQUARE.z
+			if (square < 5.5 || road) map.tiles[z * map.width + x] = dirt
+			else if (square > 17) map.tiles[z * map.width + x] = darkGrass
+		}
+	map.doodads = [...BUILDINGS.map(([model, x, z, yaw], i): MapDoodad => ({ id: i + 1, model, x, z, yaw, scale: [1, 1, 1] })), ...woods()]
+	// the road as a line the cinematics can run the camera along (`cut.rail('road')`)
+	map.paths = [
+		{
+			id: 1,
+			name: 'road',
+			width: 3,
+			points: [
+				{ x: 24, z: 2 },
+				{ x: 24, z: 14 },
+				{ x: 20, z: 22 },
+				{ x: 24, z: 31 },
+				{ x: 30, z: 27 }
+			]
+		}
+	]
+	return map
+}

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

@@ -0,0 +1,65 @@
+/**
+ * How the shared units look (`./units.ts`): the shared art's adventurers with their clips and their gear in hand,
+ * drawn as their parts while the model loads. A category's own units' looks go in its `looks.ts`
+ */
+import type { AttackLook, ModelDef, UnitLook } from '@v12-engine/client'
+
+/** A character of the shared art, `scale` times its size, with what it holds in its hands */
+export const character = (name: string, scale: number, own: Partial<ModelDef> = {}): ModelDef => ({ src: `characters/${name}.glb`, scale, ...own })
+/** A piece of the adventurers' gear in a hand: the right one when not said */
+export const hold = (name: string, hand: 'l' | 'r' = 'r') => ({ src: `gear/${name}.glb`, at: `handslot.${hand}` })
+
+const SKIN: [number, number, number] = [0.87, 0.68, 0.53]
+
+/** A person, as parts: a body in a colour and a head */
+export const person = (height: number, body: [number, number, number] | 'team' = 'team'): UnitLook['shapes'] => [
+	{ shape: 'cylinder', size: [0.5, height * 0.6, 0.5], offset: [0, height * 0.3, 0], color: body },
+	{ shape: 'sphere', size: [0.4, 0.4, 0.4], offset: [0, height * 0.75, 0], color: SKIN }
+]
+
+/** A one-handed weapon's swings, in turn at random, a big slice on a critical strike */
+export const ONE_HANDED: AttackLook = {
+	clip: ['Melee_1H_Attack_Chop', 'Melee_1H_Attack_Slice_Diagonal', 'Melee_1H_Attack_Stab'],
+	order: 'random',
+	crit: 'Melee_2H_Attack_Slice'
+}
+/** A two-handed weapon's: a chop and a slice */
+export const TWO_HANDED: AttackLook = { clip: ['Melee_2H_Attack_Chop', 'Melee_2H_Attack_Slice'], crit: 'Melee_2H_Attack_Chop' }
+
+/** The shared units' looks, by id */
+export const sharedLooks: Record<string, UnitLook> = {
+	footman: {
+		height: 1.8,
+		model: character('knight', 0.7, { hold: [hold('sword_1handed'), hold('shield_round', 'l')] }),
+		attacks: [ONE_HANDED],
+		shapes: person(1.8)
+	},
+	archer: {
+		height: 1.7,
+		model: character('ranger', 0.68, { hold: [hold('bow')], animations: { attack: 'Ranged_2H_Shoot' } }),
+		shot: { color: [0.85, 0.75, 0.55], size: 0.2 },
+		shapes: person(1.7)
+	},
+	mage: {
+		height: 1.8,
+		model: character('mage', 0.72, { hold: [hold('staff')] }),
+		shot: { color: [0.4, 0.6, 1], size: 0.3 },
+		shapes: person(1.8)
+	},
+	knight: {
+		height: 2.2,
+		model: character('knight', 0.9, { hold: [hold('sword_2handed')], animations: { attack: 'Melee_2H_Attack_Chop' } }),
+		attacks: [TWO_HANDED],
+		shapes: person(2.2)
+	},
+	dummy: {
+		height: 1.9,
+		// the shared art's training dummy, 1.86 high as it is; the parts below show until it has loaded
+		model: { src: 'props/dummy.glb', scale: 1 },
+		shapes: [
+			{ shape: 'cylinder', size: [0.15, 1.9, 0.15], offset: [0, 0.95, 0], color: [0.45, 0.31, 0.18] },
+			{ shape: 'cylinder', size: [0.7, 0.9, 0.7], offset: [0, 1.2, 0], color: [0.78, 0.68, 0.45] },
+			{ shape: 'sphere', size: [0.45, 0.45, 0.45], offset: [0, 1.85, 0], color: [0.78, 0.68, 0.45] }
+		]
+	}
+}

package/starters/examples/src/examples/common/units.ts

@@ -0,0 +1,70 @@
+/**
+ * The units the examples share: a footman, an archer, a mage, a knight who is a hero, and a dummy to hit. Each is
+ * data (`UnitTypeDef`); how each looks is `./looks.ts`. A category with units of its own registers them in its
+ * `index.ts`, its ids starting with the category's (`fx.target`)
+ */
+import { defineIds, type Game, type IdOf, type UnitTypeDef } from '@v12-engine/engine'
+
+/** The shared units' ids: `UNIT.footman` everywhere else */
+export const UNIT = defineIds('footman', 'archer', 'mage', 'knight', 'dummy')
+export type SharedUnit = IdOf<typeof UNIT>
+
+/** The two sides an example sets against each other: the player, and the one it fights */
+export const PLAYER = 1
+export const ENEMY = 2
+
+const units: UnitTypeDef[] = [
+	{
+		id: UNIT.footman,
+		name: 'Footman',
+		kind: 'unit',
+		radius: 0.45,
+		stats: { health: 420, attackDamage: 14, attackSpeed: 1.1, attackRange: 0.5, armor: 12, moveSpeed: 4 },
+		sight: 10,
+		attacks: [{ damagePoint: 0.45, acquisitionRange: 8 }]
+	},
+	{
+		id: UNIT.archer,
+		name: 'Archer',
+		kind: 'unit',
+		radius: 0.42,
+		stats: { health: 260, attackDamage: 18, attackSpeed: 1, attackRange: 7, moveSpeed: 4.2 },
+		sight: 11,
+		attacks: [{ damagePoint: 0.5, acquisitionRange: 8, projectileSpeed: 26 }]
+	},
+	{
+		id: UNIT.mage,
+		name: 'Mage',
+		kind: 'unit',
+		radius: 0.42,
+		stats: { health: 300, mana: 400, manaRegen: 4, attackDamage: 16, attackSpeed: 0.9, attackRange: 6, moveSpeed: 4 },
+		sight: 11,
+		attacks: [{ damagePoint: 0.5, acquisitionRange: 7, projectileSpeed: 18 }]
+	},
+	{
+		id: UNIT.knight,
+		name: 'Knight',
+		kind: 'unit',
+		radius: 0.5,
+		stats: { health: 900, healthRegen: 2, mana: 500, manaRegen: 5, attackDamage: 42, attackSpeed: 0.8, attackRange: 0.6, armor: 30, moveSpeed: 4.4 },
+		sight: 12,
+		attacks: [{ damagePoint: 0.4, acquisitionRange: 8 }],
+		hero: { learns: [], growth: { stats: { health: 80, mana: 30, attackDamage: 3, armor: 3 } }, maxLevel: 10 },
+		inventory: 6,
+		level: 1
+	},
+	{
+		// stands where it is put and takes what it is given: what an effect or an ability is tried on
+		id: UNIT.dummy,
+		name: 'Training dummy',
+		kind: 'unit',
+		radius: 0.5,
+		stats: { health: 5000, healthRegen: 50, moveSpeed: 0 },
+		sight: 4
+	}
+]
+
+/** Registers the shared units on the game */
+export function sharedUnits(game: Game<any>): void {
+	for (const unit of units) game.unit(unit)
+}

package/starters/examples/src/examples/construction/index.ts

@@ -0,0 +1,329 @@
+/**
+ * The construction examples on the rules' side: workers who build, buildings that go up as they work (`construction:
+ * 'builder'`), a speed for all of it, sites paused, called off and repaired, a hall upgraded where it stands, a town
+ * laid out and built. How each building looks as it rises (grows, rises, fades in, is revealed, stands in scaffolding)
+ * is its look's `construction` (`./looks.ts`)
+ */
+import {
+	cancelConstructionCommand,
+	defineCommand,
+	defineComponent,
+	defineTimer,
+	type Entity,
+	type Game,
+	number,
+	text,
+	underConstruction,
+	type UnitTypeDef,
+	upgradeBuildingCommand,
+	type Vec2,
+	type World
+} from '@v12-engine/engine'
+import { PLAYER } from '../common/units'
+import { type ExampleCategory, type ExampleDef, exampleField } from '../define'
+
+/** The construction examples' own unit types */
+export const C = {
+	worker: 'constructionWorker',
+	hall: 'constructionHall',
+	keep: 'constructionKeep',
+	castle: 'constructionCastle',
+	barracks: 'constructionBarracks',
+	tower: 'constructionTower',
+	house: 'constructionHouse',
+	temple: 'constructionTemple',
+	farm: 'constructionFarm',
+	mill: 'constructionMill',
+	fortress: 'constructionFortress'
+} as const
+
+/** How fast everything goes up, 1 as its `buildTime` says: what the Build speed slider sets */
+const speed = defineComponent<{ factor: number }>({ id: 'construction.speed', default: () => ({ factor: 1 }) })
+
+/** How fast a site goes up with so many builders: the first counts whole, every other one half, times the example's speed */
+const rate = (builders: number, world: World) => (builders > 0 ? 1 + (builders - 1) * 0.5 : 0) * world.state(speed).factor
+
+const building = (id: string, name: string, size: number, buildTime: number, health: number, own: Partial<UnitTypeDef> = {}): UnitTypeDef => ({
+	id,
+	name,
+	kind: 'building',
+	radius: size / 2,
+	footprint: { w: size, d: size },
+	sight: 6,
+	stats: { health, armor: 3 },
+	// a worker stays and works on it; more workers, faster
+	construction: 'builder',
+	buildTime,
+	buildRate: rate,
+	...own
+})
+
+const types: UnitTypeDef[] = [
+	{
+		id: C.worker,
+		name: 'Worker',
+		kind: 'unit',
+		radius: 0.4,
+		sight: 8,
+		stats: { health: 220, moveSpeed: 4.5 },
+		// what it puts down: every building here. A unit that builds can repair too
+		builds: [C.hall, C.barracks, C.tower, C.house, C.temple, C.farm, C.mill, C.fortress]
+	},
+	building(C.hall, 'Town hall', 4, 30, 2000, { upgradesTo: C.keep }),
+	building(C.keep, 'Keep', 4, 10, 2600, { upgradesTo: C.castle }),
+	building(C.castle, 'Castle', 4, 12, 3400),
+	building(C.barracks, 'Barracks', 3, 18, 1200),
+	building(C.tower, 'Watch tower', 2, 14, 700),
+	building(C.house, 'House', 2, 10, 500),
+	building(C.temple, 'Temple', 3, 24, 1400),
+	building(C.farm, 'Farm', 3, 12, 600),
+	building(C.mill, 'Windmill', 3, 16, 800),
+	building(C.fortress, 'Fortress', 4, 28, 2400)
+]
+
+// ---- helpers the examples share
+
+/** A worker of the player's, put down beside a point */
+const worker = (world: World, at: Vec2): Entity => world.spawn(C.worker, { at, owner: PLAYER })
+
+/** A site of the player's, put down at a point: at `progress` of the way already, nobody working on it yet */
+function site(world: World, type: string, at: Vec2, progress = 0): Entity {
+	const made = world.spawn(type, { at, owner: PLAYER, underConstruction: true })
+	if (progress > 0) setProgress(world, made, progress)
+	return made
+}
+
+/** Puts a site at a share of the way, and its health with it: what it would be had it been built so far */
+function setProgress(world: World, entity: Entity, progress: number): void {
+	const state = underConstruction(entity)
+	if (!state) return
+	state.progress = Math.min(0.999, Math.max(0, progress))
+	const start = world.settings.production.constructionHealth
+	entity.health = Math.max(1, entity.maxHealth * (start + (1 - start) * state.progress))
+}
+
+/** The sites still going up, left to right */
+const sites = (world: World) =>
+	world
+		.query({ kinds: ['building'], owner: PLAYER })
+		.filter((each) => underConstruction(each))
+		.sort((a, b) => a.pos.x - b.pos.x)
+
+/** Takes away everything an example put down */
+function clear(world: World): void {
+	for (const each of [...world.entities.values()]) if (each.alive) world.kill(each, undefined, false, 'removed')
+}
+
+// ---- the examples' layouts
+
+/** Five sites in a row, each going up its own way, a worker at each */
+function row(world: World): void {
+	const kinds = [C.barracks, C.tower, C.house, C.temple, C.fortress]
+	kinds.forEach((type, i) => {
+		const x = 8 + i * 8
+		const made = site(world, type, { x, z: 24 })
+		worker(world, { x: x - 1, z: 20.5 }).order('construct', made)
+	})
+}
+
+/** A hall to be, and six workers waiting by it */
+function yard(world: World): void {
+	site(world, C.fortress, { x: 24, z: 26 })
+	for (let i = 0; i < 6; i++) worker(world, { x: 19 + i * 2, z: 17 })
+}
+
+/** The same building six times, each further along: 0, a fifth, two fifths… and one finished */
+function stages(world: World): void {
+	for (let i = 0; i < 6; i++) {
+		const at = { x: 6 + i * 7.2, z: 24 }
+		if (i === 5) world.spawn(C.fortress, { at, owner: PLAYER })
+		else site(world, C.fortress, at, i * 0.2)
+	}
+}
+
+/** A barracks that is burning, and three workers to mend it */
+function burning(world: World): void {
+	world.spawn(C.barracks, { at: { x: 24.5, z: 26.5 }, owner: PLAYER })
+	for (let i = 0; i < 3; i++) worker(world, { x: 21 + i * 3, z: 19 })
+	// set alight a moment after it stands: the screen has drawn it by then, to put the fire on
+	world.timers.after(1.5, alight)
+}
+
+/** Every building of the player's hurt to an eighth of its health, with a blast on it */
+const alight = defineTimer({ id: 'construction.alight', run: (world) => hurtTo(world, 0.12) })
+
+function hurtTo(world: World, share: number): void {
+	for (const each of world.query({ kinds: ['building'], owner: PLAYER })) {
+		each.health = Math.max(1, Math.min(each.health, each.maxHealth * share))
+		world.fx('explosion', { at: each.pos, params: { size: 0.6, scorch: false } })
+	}
+}
+
+/** A town hall, standing, to upgrade into a keep and then a castle */
+function hall(world: World): void {
+	world.spawn(C.hall, { at: { x: 24, z: 26 }, owner: PLAYER })
+	for (let i = 0; i < 2; i++) worker(world, { x: 22 + i * 3, z: 20 })
+}
+
+/** Where the town's buildings go, in the order they are built: a hall in the middle, the rest round it */
+const TOWN: [string, number, number][] = [
+	[C.hall, 24, 24],
+	[C.house, 18, 19],
+	[C.house, 30, 19],
+	[C.farm, 15.5, 27.5],
+	[C.farm, 32.5, 27.5],
+	[C.barracks, 18.5, 32.5],
+	[C.house, 24, 33],
+	[C.temple, 29.5, 33.5],
+	[C.tower, 13, 18],
+	[C.tower, 35, 18],
+	[C.mill, 10.5, 32.5],
+	[C.house, 36, 24],
+	[C.house, 12, 24],
+	[C.tower, 13, 38],
+	[C.tower, 35, 38],
+	[C.fortress, 37, 33]
+]
+
+/** Workers in the middle of an empty field, a town to be laid out round them */
+function town(world: World): void {
+	for (let i = 0; i < 10; i++) worker(world, { x: 20 + (i % 5) * 2, z: 12 + Math.floor(i / 5) * 1.6 })
+}
+
+/** Each example's layout, by its id */
+const LAYOUTS: Record<string, (world: World) => void> = {
+	'construction-motions': row,
+	'construction-workers': yard,
+	'construction-stages': stages,
+	'construction-repair': burning,
+	'construction-upgrade': hall,
+	'construction-town': town
+}
+
+// ---- commands, sent by the examples' buttons
+
+/** How fast everything goes up, from a quarter to eight times */
+export const setSpeed = defineCommand('construction.speed', { factor: number }, (world, _player, { factor }) => {
+	world.setState(speed, { factor: Math.min(8, Math.max(0.1, factor)) })
+})
+
+/** Workers sent to the first site still going up: `count` more of those idle, or all (0) */
+export const sendWorkers = defineCommand('construction.send', { count: number }, (world, _player, { count }) => {
+	const target = sites(world)[0]
+	if (!target) return
+	const idle = world.query({ type: C.worker, owner: PLAYER, sort: 'nearest', near: target }).filter((each) => each.currentOrder?.type !== 'construct')
+	for (const each of count > 0 ? idle.slice(0, count) : idle) each.order('construct', target)
+})
+
+/** Every worker stops: the sites stand where they got to */
+export const stopWork = defineCommand('construction.stop', {}, (world) => {
+	for (const each of world.query({ type: C.worker, owner: PLAYER })) each.order('stop')
+})
+
+/** The first site called off, as its Cancel button would (the engine's `cancelConstruction`): it folds into the ground */
+export const callOff = defineCommand('construction.cancel', {}, (world, player) => {
+	const target = sites(world)[0]
+	if (target) cancelConstructionCommand.execute(world, player, { building: target.id })
+})
+
+/** Every site put at a share of the way (the Progress slider) */
+export const progressAll = defineCommand('construction.progress', { share: number }, (world, _player, { share }) => {
+	for (const each of sites(world)) setProgress(world, each, share)
+})
+
+/** The workers told to mend every hurt building of the player's */
+export const repairAll = defineCommand('construction.repair', {}, (world) => {
+	const hurt = world.query({ kinds: ['building'], owner: PLAYER }).filter((each) => !underConstruction(each) && each.health < each.maxHealth)
+	if (!hurt.length) return
+	for (const each of world.query({ type: C.worker, owner: PLAYER })) each.order('repair', hurt[0])
+})
+
+/** Every building of the player's hurt down to a share of its health */
+export const hurtAll = defineCommand('construction.hurt', { share: number }, (world, _player, { share }) => hurtTo(world, share))
+
+/** The hall upgraded into a keep, the keep into a castle, as its card's button would (the engine's `upgradeBuilding`) */
+export const upgrade = defineCommand('construction.upgrade', {}, (world, player) => {
+	const standing = world.query({ type: [C.hall, C.keep], owner: PLAYER, limit: 1 })[0]
+	if (standing) upgradeBuildingCommand.execute(world, player, { building: standing.id, into: undefined })
+})
+
+/** The town laid out: each worker given its share of the plan, one after another (queued `build` orders) */
+export const buildTown = defineCommand('construction.town', {}, (world) => {
+	const workers = world.query({ type: C.worker, owner: PLAYER })
+	if (!workers.length) return
+	// each its share of the plan, in turn: the first the hall, the others a house, a farm… and on to the next
+	TOWN.forEach(([type, x, z], i) => {
+		const builder = workers[i % workers.length]
+		builder.order('build', { unitType: type, point: { x, z } }, { queue: true })
+	})
+})
+
+/** Takes everything away and lays the example out again */
+export const relay = defineCommand('construction.relay', { example: text }, (world, _player, { example }) => {
+	const layout = LAYOUTS[example]
+	if (!layout) return
+	clear(world)
+	layout(world)
+})
+
+const example = (id: string, title: string, summary: string, tags: string[]): ExampleDef => ({
+	id,
+	category: 'construction',
+	title,
+	summary,
+	tags,
+	map: () => exampleField({ name: title }),
+	start: (world) => {
+		world.setState(speed, { factor: 1 })
+		LAYOUTS[id]?.(world)
+	},
+	source: ['examples/construction/index.ts', 'examples/construction/looks.ts']
+})
+
+export const category: ExampleCategory = {
+	rules: (game: Game<any>) => {
+		for (const type of types) game.unit(type)
+		game.component(speed)
+		game.timer(alight)
+		for (const command of [setSpeed, sendWorkers, stopWork, callOff, progressAll, repairAll, hurtAll, upgrade, buildTown, relay])
+			game.command(command)
+	},
+	examples: [
+		example(
+			'construction-motions',
+			'Five ways to go up',
+			'Five buildings going up side by side, a worker hammering at each: one grows out of the ground, one rises, one fades in, one is revealed by a glowing cut, and one stands in scaffolding until it is done.',
+			['construction', 'build', 'grow', 'rise', 'fade', 'reveal', 'scaffold', 'stages', 'speed']
+		),
+		example(
+			'construction-workers',
+			'Workers at a site',
+			'A fortress to be built and six workers. Send them one at a time and watch it go faster with each; stop them and it waits where it got to; cancel it and it folds back into the ground.',
+			['construction', 'workers', 'builders', 'pause', 'cancel', 'refund']
+		),
+		example(
+			'construction-stages',
+			'Every stage at once',
+			'The same fortress six times, each further along: dug earth, low scaffolding, high scaffolding, the building rising inside it, and finished. Drag Progress to move them all.',
+			['construction', 'stages', 'scaffold', 'progress']
+		),
+		example(
+			'construction-repair',
+			'Repair a burning barracks',
+			'A barracks is burning down. Send the workers to repair it: its health comes back as they hammer, the fire goes out under a quarter and the smoke over a half.',
+			['repair', 'damaged', 'fire', 'smoke', 'workers']
+		),
+		example(
+			'construction-upgrade',
+			'Hall, keep, castle',
+			'A town hall upgraded where it stands: scaffolding goes up round it, and it comes out a keep; upgrade again for a castle. It keeps working all the while.',
+			['upgrade', 'morph', 'hall', 'keep', 'castle', 'scaffold']
+		),
+		example(
+			'construction-town',
+			'A whole town',
+			'Ten workers lay out a town: a hall first, then houses, farms, a barracks, a temple, towers and a mill, each worker going from one to the next. Speed it up to watch it all rise.',
+			['town', 'build order', 'workers', 'queue', 'city', 'construction']
+		)
+	]
+}