@v12-engine/create 0.1.1 → 0.4.0

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

@@ -0,0 +1,714 @@
+/**
+ * The showcases on the rules' side (`ExampleCategory`): larger scenes, each made of several parts of the engine at once.
+ * A boss fight in phases (a system that watches its health, a buff, a slam, the dead raised), a tower defense (waves on
+ * a timer, a road, lives and gold kept on the keep), two computer generals against each other (`defineBrain`), and a
+ * battle that turns back time (the world's state recorded, then laid out again as it was)
+ */
+import {
+	applyBuff,
+	bool,
+	type BuffDef,
+	defineCommand,
+	defineComponent,
+	defineIds,
+	type Entity,
+	entityDied,
+	type Game,
+	number,
+	oneOf,
+	type PlayerId,
+	type UnitTypeDef,
+	type Vec2,
+	type World,
+	exactMath
+} from '@v12-engine/engine'
+import { type AiModule, defineBrain } from '@v12-engine/engine/ai'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleCategory, exampleField, tiles } from '../define'
+
+/** The showcases' own units */
+export const SHOW = defineIds('showcaseBoss', 'showcaseRisen', 'showcaseTower', 'showcaseRaider', 'showcaseBrute', 'showcaseKeep')
+
+const units: UnitTypeDef[] = [
+	{
+		id: SHOW.showcaseBoss,
+		name: 'The Bone King',
+		kind: 'unit',
+		radius: 1.1,
+		stats: { health: 6000, armor: 15, attackDamage: 55, attackSpeed: 0.75, attackRange: 1.4, moveSpeed: 3 },
+		sight: 12,
+		attacks: [{ damagePoint: 0.5, acquisitionRange: 12 }]
+	},
+	{
+		id: SHOW.showcaseRisen,
+		name: 'Risen dead',
+		kind: 'unit',
+		radius: 0.4,
+		stats: { health: 160, attackDamage: 9, attackSpeed: 1.1, attackRange: 0.5, moveSpeed: 3.6 },
+		sight: 10,
+		attacks: [{ damagePoint: 0.4, acquisitionRange: 10 }]
+	},
+	{
+		id: SHOW.showcaseTower,
+		name: 'Arrow tower',
+		kind: 'unit',
+		radius: 0.9,
+		stats: { health: 1500, attackDamage: 24, attackSpeed: 1.3, attackRange: 7.5, moveSpeed: 0, armor: 20 },
+		sight: 9,
+		attacks: [{ damagePoint: 0.2, acquisitionRange: 7.5, projectileSpeed: 26 }]
+	},
+	// the raiders walk the road and fight nothing: they only want to get through
+	{ id: SHOW.showcaseRaider, name: 'Raider', kind: 'unit', radius: 0.4, stats: { health: 110, moveSpeed: 2.8 }, sight: 4 },
+	{ id: SHOW.showcaseBrute, name: 'Brute', kind: 'unit', radius: 0.55, stats: { health: 520, armor: 20, moveSpeed: 1.9 }, sight: 4 },
+	{ id: SHOW.showcaseKeep, name: 'Keep', kind: 'unit', radius: 2, stats: { health: 5000, moveSpeed: 0 }, sight: 8 }
+]
+
+/** Every unit of the world taken away */
+const clearAll = (world: World) => {
+	for (const unit of [...world.units.values()]) if (unit.alive) world.kill(unit, undefined, false, 'removed')
+}
+/** The alive units of the world a test says yes to */
+const alive = (world: World, test: (unit: Entity) => boolean) => [...world.units.values()].filter((unit) => unit.alive && test(unit))
+/** One order to many, the way a player gives it */
+const orderAll = (world: World, player: PlayerId, units: readonly Entity[], order: { type: string; point?: Vec2; target?: number }) => {
+	if (units.length) world.issue({ type: 'order', player, entities: units.map((unit) => unit.id), order: { ...order, formation: 'none' } as never })
+}
+
+// ---- the boss: phases by its health
+
+/** Where the boss fight stands, kept on the boss and told to every screen: its phase, and when it slams next */
+export const bossState = defineComponent<{ phase: 1 | 2 | 3; slamAt: number }>({
+	id: 'showcase.bossFight',
+	default: () => ({ phase: 1, slamAt: 0 }),
+	replicate: 'everyone'
+})
+
+/** The fury of the boss's last phase: faster blows, faster feet */
+const enraged: BuffDef = { id: 'showcase.enraged', name: 'Enraged', percent: { attackSpeed: 0.7, moveSpeed: 0.35, attackDamage: 0.25 } }
+
+/** The party: a knight, footmen, archers and a mage, south of the boss */
+function party(world: World): void {
+	world.spawn(UNIT.knight, { at: { x: 24, z: 15 }, owner: PLAYER, facing: 0 })
+	for (let i = 0; i < 5; i++) world.spawn(UNIT.footman, { at: { x: 20 + i * 2, z: 16.5 }, owner: PLAYER, facing: 0 })
+	for (let i = 0; i < 4; i++) world.spawn(UNIT.archer, { at: { x: 20.5 + i * 2.3, z: 12.5 }, owner: PLAYER, facing: 0 })
+	for (let i = 0; i < 2; i++) world.spawn(UNIT.mage, { at: { x: 22 + i * 4, z: 11 }, owner: PLAYER, facing: 0 })
+}
+
+/** The boss fight laid out: the party to the south, the boss on its dais to the north */
+function bossArena(world: World): void {
+	party(world)
+	const boss = world.spawn(SHOW.showcaseBoss, { at: { x: 24, z: 31 }, owner: ENEMY, facing: Math.PI })
+	boss.set(bossState, { phase: 1, slamAt: 0 })
+}
+
+/** Raises the dead round the boss: `count` of them out of the ground, in a ring */
+function raiseDead(world: World, at: Vec2, count: number): void {
+	for (let i = 0; i < count; i++) {
+		const angle = (i / count) * Math.PI * 2
+		const point = { x: at.x + exactMath.cos(angle) * 3, z: at.z + exactMath.sin(angle) * 3 }
+		world.spawn(SHOW.showcaseRisen, { at: point, owner: ENEMY, facing: angle })
+		world.fx('dust', { at: point })
+	}
+}
+
+/**
+ * The boss's phases, watched a few times a second: at two thirds of its health it roars and raises the dead; at a
+ * third it is enraged (`enraged`), raises more, and slams the ground every few seconds, hurting all round it
+ */
+const bossPhases = {
+	name: 'showcase.bossPhases',
+	every: 3,
+	update: (world: World) => {
+		for (const boss of world.units.values()) {
+			if (!boss.alive || boss.def.id !== SHOW.showcaseBoss) continue
+			const fight = boss.get(bossState) ?? { phase: 1, slamAt: 0 }
+			const share = boss.health / boss.maxHealth
+			if (fight.phase === 1 && share < 2 / 3) {
+				boss.set(bossState, { ...fight, phase: 2 })
+				world.fx('shockwave', { at: boss.pos, params: { size: 2 } })
+				raiseDead(world, boss.pos, 6)
+				world.hint(PLAYER, 'The Bone King calls up his dead!')
+			} else if (fight.phase === 2 && share < 1 / 3) {
+				boss.set(bossState, { phase: 3, slamAt: world.time + 2 })
+				world.fx('explosion', { at: boss.pos, params: { size: 1.4 } })
+				applyBuff(world, boss, enraged.id, 600, boss)
+				raiseDead(world, boss.pos, 5)
+				world.hint(PLAYER, 'The Bone King is enraged!')
+			} else if (fight.phase === 3 && world.time >= fight.slamAt) {
+				boss.set(bossState, { ...fight, slamAt: world.time + 5 })
+				// the slam: all of the other side within 4 of it hurt, more the nearer they stand
+				world.fx('ground-crack', { at: boss.pos, params: { size: 1.6 } })
+				world.fx('shockwave', { at: boss.pos, params: { size: 1.5 } })
+				for (const unit of world.units.values()) {
+					if (!unit.alive || unit.owner !== PLAYER) continue
+					const away = exactMath.hypot(unit.pos.x - boss.pos.x, unit.pos.z - boss.pos.z)
+					if (away < 4) world.damage(unit, 90 * (1 - away / 5), boss)
+				}
+			}
+		}
+	}
+}
+/** The fight again from the start */
+export const bossReset = defineCommand('showcase.bossReset', {}, (world) => {
+	clearAll(world)
+	bossArena(world)
+})
+/** The party sent at the boss, fighting what is in the way */
+export const bossCharge = defineCommand('showcase.bossCharge', {}, (world) => {
+	orderAll(
+		world,
+		PLAYER,
+		alive(world, (unit) => unit.owner === PLAYER),
+		{ type: 'attackMove', point: { x: 24, z: 33 } }
+	)
+})
+
+// ---- the tower defense: a road, waves, towers, lives and gold
+
+/** The road the raiders walk, from the west to the keep in the east */
+export const ROAD: Vec2[] = [
+	{ x: 1, z: 38 },
+	{ x: 14, z: 38 },
+	{ x: 14, z: 22 },
+	{ x: 32, z: 22 },
+	{ x: 32, z: 10 },
+	{ x: 42, z: 10 }
+]
+/** Where towers may stand, along the road, in the order they are built */
+const SPOTS: Vec2[] = [
+	{ x: 17.5, z: 30 },
+	{ x: 10.5, z: 30 },
+	{ x: 23, z: 25.5 },
+	{ x: 23, z: 18.5 },
+	{ x: 28.5, z: 15 },
+	{ x: 35.5, z: 15 },
+	{ x: 8, z: 41.5 },
+	{ x: 17.5, z: 41.5 },
+	{ x: 35.5, z: 6.5 },
+	{ x: 28.5, z: 6.5 }
+]
+/** A time that never comes: a wave not yet beaten has its next one here (the state is sent as plain data, which has no Infinity) */
+const NEVER = 1e9
+/** What a tower costs, and what a raider and a brute are worth */
+export const TOWER_COST = 60
+const BOUNTY = { [SHOW.showcaseRaider]: 6, [SHOW.showcaseBrute]: 20 } as Record<string, number>
+
+/** How the defense stands, kept on the keep and told to every screen */
+interface Defense {
+	wave: number
+	lives: number
+	gold: number
+	/** Raiders still to come out this wave, and when the next does */
+	toCome: number
+	nextAt: number
+	/** When the next wave starts, once this one is beaten */
+	waveAt: number
+}
+export const defenseState = defineComponent<Defense>({
+	id: 'showcase.defense',
+	default: () => ({ wave: 0, lives: 20, gold: 120, toCome: 0, nextAt: 0, waveAt: 3 }),
+	replicate: 'everyone'
+})
+
+/** The keep, where the defense is kept */
+const keepOf = (world: World) => alive(world, (unit) => unit.def.id === SHOW.showcaseKeep)[0]
+
+/** The map of the tower defense: the field with the road painted on it */
+function defenseMap() {
+	const map = exampleField({ name: 'Hold the road', players: 2 })
+	const road = tiles.findIndex((tile) => tile.id === 'road') + 1 || tiles.findIndex((tile) => tile.id === 'dirt') + 1
+	for (let i = 0; i + 1 < ROAD.length; i++) {
+		const a = ROAD[i]!
+		const b = ROAD[i + 1]!
+		for (let x = Math.min(a.x, b.x) - 1; x <= Math.max(a.x, b.x) + 1; x++)
+			for (let z = Math.min(a.z, b.z) - 1; z <= Math.max(a.z, b.z) + 1; z++)
+				if (x >= 0 && z >= 0 && x < map.width && z < map.depth) map.tiles[Math.floor(z) * map.width + Math.floor(x)] = road
+	}
+	return map
+}
+
+/** How far along the road a point is, as the leg it is on (0 the first), to send it on to the next corner */
+function legOf(point: Vec2): number {
+	let best = 0
+	let nearest = Infinity
+	for (let i = 0; i + 1 < ROAD.length; i++) {
+		const a = ROAD[i]!
+		const b = ROAD[i + 1]!
+		const dx = b.x - a.x
+		const dz = b.z - a.z
+		const t = Math.max(0, Math.min(1, ((point.x - a.x) * dx + (point.z - a.z) * dz) / (dx * dx + dz * dz)))
+		const away = exactMath.hypot(a.x + dx * t - point.x, a.z + dz * t - point.z)
+		if (away < nearest - 0.01) {
+			nearest = away
+			best = i
+		}
+	}
+	return best
+}
+
+/** The defense laid out: the keep at the road's end, two towers to start with */
+function defenseStart(world: World): void {
+	const keep = world.spawn(SHOW.showcaseKeep, { at: { x: 44.5, z: 10 }, owner: PLAYER, facing: -Math.PI / 2 })
+	keep.set(defenseState, { wave: 0, lives: 20, gold: 120, toCome: 0, nextAt: 0, waveAt: world.time + 4 })
+	for (const spot of SPOTS.slice(0, 2)) world.spawn(SHOW.showcaseTower, { at: spot, owner: PLAYER })
+}
+
+/**
+ * The waves, ten times a second: a raider out every so often while the wave has some to come; the next wave a few
+ * seconds after the last is beaten, bigger, every third with brutes. Each raider is sent on to the next corner of the
+ * road; one that gets to the keep is taken away, and a life with it
+ */
+const waves = {
+	name: 'showcase.waves',
+	every: 3,
+	update: (world: World) => {
+		const keep = keepOf(world)
+		const defense = keep?.get(defenseState)
+		if (!keep || !defense) return
+		const raiders = alive(world, (unit) => unit.owner === ENEMY && (unit.def.id === SHOW.showcaseRaider || unit.def.id === SHOW.showcaseBrute))
+		const now = { ...defense }
+		if (now.lives > 0 && now.toCome > 0 && world.time >= now.nextAt) {
+			const brute = now.wave % 3 === 0 && now.toCome % 3 === 0
+			world.spawn(brute ? SHOW.showcaseBrute : SHOW.showcaseRaider, { at: ROAD[0]!, owner: ENEMY, facing: Math.PI / 2 })
+			now.toCome--
+			now.nextAt = world.time + (brute ? 1.6 : 0.8)
+		} else if (now.lives > 0 && !now.toCome && !raiders.length && world.time >= now.waveAt) {
+			now.wave++
+			now.toCome = 6 + now.wave * 3
+			now.nextAt = world.time
+			now.waveAt = NEVER
+			world.hint(PLAYER, `Wave ${now.wave}`)
+		} else if (!now.toCome && !raiders.length && now.waveAt === NEVER) now.waveAt = world.time + 5
+		const end = ROAD[ROAD.length - 1]!
+		for (const raider of raiders) {
+			if (exactMath.hypot(raider.pos.x - end.x, raider.pos.z - end.z) < 1.5) {
+				world.kill(raider, undefined, false, 'removed')
+				world.fx('impact-ring', { at: end })
+				now.lives = Math.max(0, now.lives - (raider.def.id === SHOW.showcaseBrute ? 3 : 1))
+				if (!now.lives) world.hint(PLAYER, 'The keep has fallen. Start again to hold the road anew.')
+				continue
+			}
+			const next = ROAD[legOf(raider.pos) + 1]!
+			const going = raider.orders[0]?.init.point as Vec2 | undefined
+			if (!going || going.x !== next.x || going.z !== next.z) raider.order('move', next)
+		}
+		keep.set(defenseState, now)
+	}
+}
+
+/** A tower built at the next free spot, if the gold is there */
+export const buildTower = defineCommand('showcase.buildTower', {}, (world, player) => {
+	const keep = keepOf(world)
+	const defense = keep?.get(defenseState)
+	if (!keep || !defense) return
+	if (defense.gold < TOWER_COST) return world.message(player, 'Not enough gold')
+	const towers = alive(world, (unit) => unit.def.id === SHOW.showcaseTower)
+	const spot = SPOTS.find((each) => !towers.some((tower) => exactMath.hypot(tower.pos.x - each.x, tower.pos.z - each.z) < 1))
+	if (!spot) return world.message(player, 'Every spot has a tower')
+	world.spawn(SHOW.showcaseTower, { at: spot, owner: player })
+	world.fx('dust', { at: spot })
+	keep.set(defenseState, { ...defense, gold: defense.gold - TOWER_COST })
+})
+/** The road held again from the first wave */
+export const defenseReset = defineCommand('showcase.defenseReset', {}, (world) => {
+	clearAll(world)
+	defenseStart(world)
+})
+/** The next wave now, for gold */
+export const callWave = defineCommand('showcase.callWave', {}, (world) => {
+	const keep = keepOf(world)
+	const defense = keep?.get(defenseState)
+	if (keep && defense && defense.waveAt !== NEVER) keep.set(defenseState, { ...defense, waveAt: world.time, gold: defense.gold + 15 })
+})
+
+// ---- two generals: a computer on each side, with tactics of its own
+
+/** The first of a set a test likes best, by a score: the lowest wins */
+const best = <T>(list: readonly T[], score: (each: T) => number): T | undefined => {
+	let found: T | undefined
+	let low = Infinity
+	for (const each of list) {
+		const s = score(each)
+		if (s < low) {
+			low = s
+			found = each
+		}
+	}
+	return found
+}
+
+/**
+ * A general's tactics, a module of a computer's brain (`AiModule`): it reads the game as its seat sees it (`ai.view`)
+ * and orders its army as a player would (`ai.send`). Footmen hit the weakest foe near the front together, and fall
+ * back to the archers when badly hurt; archers keep out of a blade's reach and shoot the weakest in range; the knight
+ * goes round the side for the archers. An order is given again only when it changes, so swings are not cut off
+ */
+const tactics = (): AiModule => {
+	const given = new Map<number, string>()
+	return {
+		id: 'showcase.tactics',
+		think(ai) {
+			const mine = ai.view.mine.units().filter((each) => each.health > 0)
+			const foes = ai.view.enemies.units().filter((each) => each.health > 0 && each.visible)
+			const order = (id: number, key: string, command: { type: string; point?: Vec2; target?: number }) => {
+				if (given.get(id) === key) return
+				given.set(id, key)
+				ai.send({ type: 'order', entities: [id], order: command } as never)
+			}
+			/** The foe a unit was set on last, while it lives and is still within `reach`: kept, so a swing is never cut off for another */
+			const still = (unit: { id: number; x: number; z: number }, reach: number) => {
+				const was = Number(given.get(unit.id)?.replace(/^\D+/, ''))
+				const foe = foes.find((each) => each.id === was)
+				return foe && exactMath.hypot(foe.x - unit.x, foe.z - unit.z) < reach ? foe : undefined
+			}
+			const front = ai.view.enemies.centre() ?? { x: 32, z: 32 }
+			const home = ai.view.mine.centre() ?? front
+			const archers = mine.filter((each) => each.type === UNIT.archer)
+			const rear = archers.length
+				? { x: archers.reduce((s, a) => s + a.x, 0) / archers.length, z: archers.reduce((s, a) => s + a.z, 0) / archers.length }
+				: home
+			for (const unit of mine) {
+				const hurt = unit.health / (unit.maxHealth ?? unit.health) < 0.3
+				const near = best(foes, (foe) => exactMath.hypot(foe.x - unit.x, foe.z - unit.z))
+				const nearAway = near ? exactMath.hypot(near.x - unit.x, near.z - unit.z) : Infinity
+				if (unit.type === UNIT.archer) {
+					// a blade too near: step back, away from it
+					if (near && nearAway < 3 && near.type !== UNIT.archer) {
+						const dx = unit.x - near.x
+						const dz = unit.z - near.z
+						const k = 4 / (exactMath.hypot(dx, dz) || 1)
+						order(unit.id, `back${Math.round(unit.x)},${Math.round(unit.z)}`, { type: 'move', point: { x: unit.x + dx * k, z: unit.z + dz * k } })
+						continue
+					}
+					const target =
+						still(unit, 8) ??
+						best(
+							foes.filter((foe) => exactMath.hypot(foe.x - unit.x, foe.z - unit.z) < 8),
+							(foe) => foe.health
+						)
+					if (target) order(unit.id, `shoot${target.id}`, { type: 'attack', target: target.id })
+					else order(unit.id, 'advance', { type: 'attackMove', point: front })
+					continue
+				}
+				if (unit.type === UNIT.knight) {
+					const hunted = still(unit, 30)
+					const prey =
+						(hunted?.type === UNIT.archer ? hunted : undefined) ??
+						best(
+							foes.filter((foe) => foe.type === UNIT.archer),
+							(foe) => exactMath.hypot(foe.x - unit.x, foe.z - unit.z)
+						)
+					if (prey) order(unit.id, `hunt${prey.id}`, { type: 'attack', target: prey.id })
+					else order(unit.id, 'advance', { type: 'attackMove', point: front })
+					continue
+				}
+				if (hurt && nearAway < 6) {
+					order(unit.id, 'fall back', { type: 'move', point: rear })
+					continue
+				}
+				// the footmen together on the weakest foe near them
+				const target =
+					still(unit, 7) ??
+					best(
+						foes.filter((foe) => exactMath.hypot(foe.x - unit.x, foe.z - unit.z) < 7),
+						(foe) => foe.health + exactMath.hypot(foe.x - unit.x, foe.z - unit.z) * 10
+					)
+				if (target) order(unit.id, `hit${target.id}`, { type: 'attack', target: target.id })
+				else order(unit.id, 'advance', { type: 'attackMove', point: front })
+			}
+		}
+	}
+}
+
+/** The general: a brain of one module, thinking twice a second */
+export const general = defineBrain({ id: 'showcase.general', modules: [tactics], every: 0.5 })
+
+/** The two armies of the generals: footmen in front, archers behind, a knight on a wing */
+function generalsArmies(world: World): void {
+	for (const [owner, z, back] of [
+		[PLAYER, 18, -1],
+		[ENEMY, 46, 1]
+	] as const) {
+		for (let i = 0; i < 14; i++)
+			world.spawn(UNIT.footman, { at: { x: 23 + (i % 7) * 1.5, z: z + Math.floor(i / 7) * 1.4 * back }, owner, facing: back < 0 ? 0 : Math.PI })
+		for (let i = 0; i < 8; i++)
+			world.spawn(UNIT.archer, {
+				at: { x: 24.5 + (i % 4) * 2.2, z: z + (3.6 + Math.floor(i / 4) * 1.4) * back },
+				owner,
+				facing: back < 0 ? 0 : Math.PI
+			})
+		world.spawn(UNIT.knight, { at: { x: owner === PLAYER ? 18 : 46, z: z + 1.5 * back }, owner, facing: back < 0 ? 0 : Math.PI })
+	}
+}
+
+/** Both generals seated, each playing its side */
+function seatGenerals(world: World): void {
+	world.computers.seat(PLAYER, { brain: general })
+	world.computers.seat(ENEMY, { brain: general })
+}
+
+/** Both armies laid out again, and the generals at them */
+export const generalsReset = defineCommand('showcase.generalsReset', {}, (world) => {
+	clearAll(world)
+	generalsArmies(world)
+	seatGenerals(world)
+})
+
+// ---- a battle that turns back time: the world recorded, and laid out again as it was
+
+/** One unit as it was at a moment: enough to make it again */
+interface Kept {
+	type: string
+	owner: PlayerId
+	x: number
+	z: number
+	facing: number
+	health: number
+}
+/** What the world looked like, twice a second for the last fifteen seconds: kept in the world's state, so a save has it */
+const historyState = defineComponent<{ frames: { time: number; units: Kept[] }[] }>({ id: 'showcase.history', default: () => ({ frames: [] }) })
+
+/** The armies of the rewind battle */
+function rewindArmies(world: World): void {
+	for (const [owner, z, back] of [
+		[PLAYER, 18, -1],
+		[ENEMY, 30, 1]
+	] as const) {
+		for (let i = 0; i < 12; i++)
+			world.spawn(UNIT.footman, { at: { x: 20 + (i % 6) * 1.6, z: z + Math.floor(i / 6) * 1.4 * back }, owner, facing: back < 0 ? 0 : Math.PI })
+		for (let i = 0; i < 6; i++) world.spawn(UNIT.archer, { at: { x: 21 + (i % 6) * 1.4, z: z + 4 * back }, owner, facing: back < 0 ? 0 : Math.PI })
+	}
+}
+
+/** Both sides at each other */
+function fight(world: World): void {
+	for (const owner of [PLAYER, ENEMY])
+		orderAll(
+			world,
+			owner,
+			alive(world, (unit) => unit.owner === owner),
+			{ type: 'attackMove', point: { x: 24, z: owner === PLAYER ? 36 : 12 } }
+		)
+}
+
+/** The world recorded twice a second, on the rewind example's field alone */
+const recording = {
+	name: 'showcase.recording',
+	every: 15,
+	update: (world: World) => {
+		if (world.map?.name !== 'Turn back time') return
+		const history = world.state(historyState)
+		const units = alive(world, () => true).map((unit) => ({
+			type: unit.def.id,
+			owner: unit.owner,
+			x: unit.pos.x,
+			z: unit.pos.z,
+			facing: unit.facing,
+			health: unit.health
+		}))
+		world.setState(historyState, { frames: [...history.frames.slice(-29), { time: world.time, units }] })
+	}
+}
+
+/**
+ * Time turned back `seconds`: every unit taken away and laid out again as the record of that moment has it, where it
+ * stood, as hurt as it was, the fallen of since standing again; then the fight goes on from there
+ */
+export const rewind = defineCommand('showcase.rewind', { seconds: number }, (world, _player, { seconds }) => {
+	const { frames } = world.state(historyState)
+	const then = best(frames, (frame) => Math.abs(frame.time - (world.time - seconds)))
+	if (!then) return
+	clearAll(world)
+	for (const kept of then.units) {
+		const unit = world.spawn(kept.type, { at: { x: kept.x, z: kept.z }, owner: kept.owner, facing: kept.facing })
+		unit.health = Math.min(kept.health, unit.maxHealth)
+	}
+	world.setState(historyState, { frames: frames.filter((frame) => frame.time <= then.time) })
+	world.fx('shockwave', { at: { x: 24, z: 24 }, params: { size: 3, color: '#9fd6ff' } })
+	fight(world)
+})
+/** The battle from the start */
+export const rewindReset = defineCommand('showcase.rewindReset', {}, (world) => {
+	clearAll(world)
+	world.setState(historyState, { frames: [] })
+	rewindArmies(world)
+})
+/** The two sides sent at each other */
+export const rewindFight = defineCommand('showcase.rewindFight', {}, (world) => fight(world))
+
+// ---- a march: companies in formation behind a leader who walks a road round the field
+
+/** The leader's road: round the field and back, for ever */
+export const MARCH: Vec2[] = [
+	{ x: 16, z: 16 },
+	{ x: 48, z: 16 },
+	{ x: 52, z: 32 },
+	{ x: 48, z: 48 },
+	{ x: 16, z: 48 },
+	{ x: 12, z: 32 }
+]
+/** How the companies march, kept in the world's state: their shape, and whether they march or stand */
+export const marching = defineComponent<{ shape: 'rows' | 'square' | 'circle'; halted: boolean }>({
+	id: 'showcase.marching',
+	default: () => ({ shape: 'rows', halted: false })
+})
+
+/** The companies, by what they are, and how far behind the leader each marches */
+const COMPANIES = [
+	{ type: UNIT.footman, count: 36, behind: 5 },
+	{ type: UNIT.archer, count: 24, behind: 12 },
+	{ type: UNIT.mage, count: 12, behind: 18 }
+]
+
+/** The leader, and the companies in ranks behind it */
+function column(world: World): void {
+	world.spawn(UNIT.knight, { at: MARCH[0]!, owner: PLAYER, facing: Math.PI / 2 })
+	for (const company of COMPANIES)
+		for (let i = 0; i < company.count; i++)
+			world.spawn(company.type, {
+				at: { x: MARCH[0]!.x - company.behind - Math.floor(i / 6) * 1.4, z: MARCH[0]!.z - 3.5 + (i % 6) * 1.4 },
+				owner: PLAYER,
+				facing: Math.PI / 2
+			})
+}
+
+/**
+ * The march, every two seconds: the leader walks on to the next point of its road; each company is sent, in one order and in
+ * the formation chosen, to a place behind the leader on the way it goes, facing that way (`OrderInit.facing`). The
+ * formation lays each company out anew round its place; the units find their spots in it as they walk
+ */
+const march = {
+	name: 'showcase.march',
+	every: 60,
+	update: (world: World) => {
+		if (world.map?.name !== 'March') return
+		const leader = alive(world, (unit) => unit.def.id === UNIT.knight)[0]
+		if (!leader) return
+		const how = world.state(marching)
+		if (how.halted) return
+		const goal = leader.orders[0]?.init.point as Vec2 | undefined
+		if (!goal || exactMath.hypot(goal.x - leader.pos.x, goal.z - leader.pos.z) < 3) {
+			const near = MARCH.reduce(
+				(best, each, i) =>
+					exactMath.hypot(each.x - leader.pos.x, each.z - leader.pos.z) <
+					exactMath.hypot(MARCH[best]!.x - leader.pos.x, MARCH[best]!.z - leader.pos.z)
+						? i
+						: best,
+				0
+			)
+			leader.order('move', MARCH[(near + 1) % MARCH.length]!)
+		}
+		const to = (leader.orders[0]?.init.point as Vec2 | undefined) ?? leader.pos
+		const away = exactMath.hypot(to.x - leader.pos.x, to.z - leader.pos.z) || 1
+		const forward = { x: (to.x - leader.pos.x) / away, z: (to.z - leader.pos.z) / away }
+		const facing = exactMath.atan2(forward.x, forward.z)
+		for (const company of COMPANIES) {
+			const units = alive(world, (unit) => unit.def.id === company.type)
+			const place = { x: leader.pos.x - forward.x * company.behind, z: leader.pos.z - forward.z * company.behind }
+			if (units.length)
+				world.issue({
+					type: 'order',
+					player: PLAYER,
+					entities: units.map((unit) => unit.id),
+					order: { type: 'move', point: place, formation: how.shape, facing } as never
+				})
+		}
+	}
+}
+
+/** The companies' shape, or a halt and on again */
+export const marchAs = defineCommand('showcase.marchAs', { shape: oneOf('rows', 'square', 'circle') }, (world, _player, { shape }) => {
+	world.setState(marching, { ...world.state(marching), shape })
+})
+export const halt = defineCommand('showcase.halt', { halted: bool }, (world, player, { halted }) => {
+	world.setState(marching, { ...world.state(marching), halted })
+	if (halted)
+		orderAll(
+			world,
+			player,
+			alive(world, (unit) => unit.owner === player),
+			{ type: 'stop' }
+		)
+})
+
+export const category: ExampleCategory = {
+	rules: (game: Game<any>) => {
+		for (const unit of units) game.unit(unit)
+		for (const component of [bossState, defenseState, historyState, marching]) game.component(component)
+		game.buff(enraged)
+		game.brain(general)
+		game.system(bossPhases)
+		game.system(waves)
+		game.system(recording)
+		game.system(march)
+		for (const command of [bossReset, bossCharge, buildTower, defenseReset, callWave, generalsReset, rewind, rewindReset, rewindFight, marchAs, halt])
+			game.command(command)
+		// a raider's bounty, to the keep's gold
+		game.on(entityDied, (world, { entity, reason }) => {
+			const bounty = BOUNTY[entity.def.id]
+			const keep = bounty && reason !== 'removed' ? keepOf(world) : undefined
+			const defense = keep?.get(defenseState)
+			if (keep && defense) keep.set(defenseState, { ...defense, gold: defense.gold + bounty! })
+		})
+	},
+	examples: [
+		{
+			id: 'showcase-boss',
+			category: 'showcase',
+			title: 'The Bone King: a boss in phases',
+			summary:
+				'A party against a boss that changes as it is hurt: at two thirds it raises the dead, at a third it is enraged and slams the ground. Charge, or lead the party yourself (select, right-click).',
+			tags: ['boss', 'phases', 'raid', 'adds', 'enrage', 'system', 'buff', 'fight'],
+			map: () => exampleField({ name: 'Bone King', players: 2 }),
+			start: (world) => bossArena(world),
+			source: ['examples/showcase/index.ts', 'examples/showcase/looks.ts']
+		},
+		{
+			id: 'showcase-defense',
+			category: 'showcase',
+			title: 'Hold the road: a tower defense',
+			summary:
+				'Raiders come down the road in waves, bigger each time, brutes every third; towers shoot them as they pass. Build towers with the gold they bring, and keep them from the keep.',
+			tags: ['tower defense', 'waves', 'road', 'lives', 'gold', 'towers', 'td'],
+			map: () => defenseMap(),
+			start: (world) => defenseStart(world),
+			source: ['examples/showcase/index.ts', 'examples/showcase/looks.ts']
+		},
+		{
+			id: 'showcase-generals',
+			category: 'showcase',
+			title: 'Two computer generals',
+			summary:
+				'Both sides played by a computer with tactics of its own: footmen gang up on the weakest and fall back hurt, archers keep their distance, the knight hunts the archers. Sit back and watch, then lay them out again.',
+			tags: ['ai', 'computer player', 'brain', 'defineBrain', 'tactics', 'kiting', 'focus fire'],
+			map: () => exampleField({ name: 'Generals', size: 64, players: 2 }),
+			start: (world) => {
+				generalsArmies(world)
+				seatGenerals(world)
+			},
+			source: ['examples/showcase/index.ts', 'examples/showcase/looks.ts']
+		},
+		{
+			id: 'showcase-rewind',
+			category: 'showcase',
+			title: 'Turn back time',
+			summary:
+				'A battle the world records twice a second. Let them fight, then turn back time: every unit stands where it stood, as hurt as it was, the fallen up again, and the fight goes on from there.',
+			tags: ['rewind', 'time', 'record', 'state', 'save', 'replay', 'component'],
+			map: () => exampleField({ name: 'Turn back time', players: 2 }),
+			start: (world) => rewindArmies(world),
+			source: ['examples/showcase/index.ts', 'examples/showcase/looks.ts']
+		},
+		{
+			id: 'showcase-march',
+			category: 'showcase',
+			title: 'Companies on the march',
+			summary:
+				'A knight walks a road round the field, and seventy-two behind him follow in three companies, each in formation and facing the way they go. Change their shape as they march, or halt them.',
+			tags: ['formation', 'march', 'follow', 'leader', 'column', 'army', 'maneuver'],
+			map: () => exampleField({ name: 'March', size: 64 }),
+			start: (world) => column(world),
+			source: ['examples/showcase/index.ts', 'examples/showcase/looks.ts']
+		}
+	]
+}