@v12-engine/create 0.1.0 → 0.4.0

package/starters/examples/src/examples/mechanics/highGround.ts

@@ -0,0 +1,82 @@
+/**
+ * Sight, fog of war and high ground: each side sees only what its units see (`sight`), the rest of the map dark. And
+ * nobody sees up a cliff: archers on a plateau shoot down at units below that cannot see them, until those climb the
+ * ramp. The map is played with `reveal: false`, so the player sees through their own units' eyes alone
+ */
+import { createMap, defineCommand, type GameMap, type World } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, tiles } from '../define'
+
+/** The size of the field, and the plateau on its east side: its cells, from and to */
+const SIZE = 40
+const PLATEAU = { x0: 22, x1: 36, z0: 10, z1: 30 }
+/** The ramp up its west face: four cells wide, two below and two on top */
+const RAMP = { x0: 20, x1: 24, z0: 18, z1: 22 }
+/** Where the player's party waits below, and the top of the ramp */
+const BELOW = { x: 12, z: 20 }
+const TOP = { x: 26, z: 20 }
+
+/** A field of grass with a rocky plateau of one level up, and a ramp to it */
+function highGroundMap(): GameMap {
+	const map = createMap({ name: 'High ground', width: SIZE, depth: SIZE, players: 2, game: 'examples', tileset: tiles.map((each) => each.id) })
+	const grass = map.tileset.indexOf('grass') + 1
+	const rock = map.tileset.indexOf('rock') + 1
+	const dirt = map.tileset.indexOf('dirt') + 1
+	map.tiles.fill(grass)
+	for (let z = PLATEAU.z0; z < PLATEAU.z1; z++)
+		for (let x = PLATEAU.x0; x < PLATEAU.x1; x++) {
+			map.levels[z * SIZE + x] = 1
+			map.tiles[z * SIZE + x] = rock
+		}
+	for (let z = RAMP.z0; z < RAMP.z1; z++)
+		for (let x = RAMP.x0; x < RAMP.x1; x++) {
+			map.ramps[z * SIZE + x] = 1
+			map.tiles[z * SIZE + x] = dirt
+		}
+	map.players[0].start = BELOW
+	map.players[1].start = { x: 30, z: 20 }
+	return map
+}
+
+/** The player's party below the cliff, and the enemy's archers on the plateau above it, all taken away first */
+function layOut(world: World): void {
+	for (const unit of [...world.units.values()]) if (unit.alive) world.kill(unit, undefined, false, 'removed')
+	;[UNIT.footman, UNIT.footman, UNIT.knight, UNIT.archer].forEach((type, i) =>
+		world.spawn(type, { at: { x: BELOW.x + 1, z: BELOW.z - 1.5 + i }, owner: PLAYER })
+	)
+	// they hold their ground (`hold`): they shoot what comes in reach, but never walk down after it
+	for (let i = 0; i < 3; i++) world.spawn(UNIT.archer, { at: { x: 24.5, z: 16 + i * 4 }, owner: ENEMY }).order('hold')
+	// one more archer deeper on the plateau, out of the reach of anything below: seen only from the top of it
+	world.spawn(UNIT.archer, { at: { x: 32, z: 20 }, owner: ENEMY }).order('hold')
+}
+
+/** The party walks up the ramp to the top: they see the plateau, and the archers on it, as they get there */
+export const climb = defineCommand('mechanics.climb', {}, (world, player) => {
+	const ids = [...world.units.values()].filter((unit) => unit.alive && unit.owner === player).map((unit) => unit.id)
+	world.issue({ type: 'order', player, entities: ids, order: { type: 'attackMove', point: TOP } })
+})
+
+/**
+ * The party walks to the foot of the cliff, by the archers' feet, and holds there (`hold`, queued after the move):
+ * shot at from the dark, it cannot see whom to hit back, and holding it does not go looking
+ */
+export const underCliff = defineCommand('mechanics.underCliff', {}, (world, player) => {
+	const ids = [...world.units.values()].filter((unit) => unit.alive && unit.owner === player).map((unit) => unit.id)
+	world.issue({ type: 'order', player, entities: ids, order: { type: 'move', point: { x: 19, z: 14 } } })
+	world.issue({ type: 'order', player, entities: ids, order: { type: 'hold' }, queue: true })
+})
+
+export const resetHighGround = defineCommand('mechanics.resetHighGround', {}, (world) => layOut(world))
+
+export const highGround: ExampleDef = {
+	id: 'mechanics-high-ground',
+	category: 'mechanics',
+	title: 'Fog of war and high ground',
+	summary:
+		'You see only what your units see, and nobody sees up a cliff. Walk under the cliff and arrows come from the dark; climb the ramp and the archers on the plateau are seen, and fought.',
+	tags: ['fog', 'fog of war', 'sight', 'vision', 'cliff', 'high ground', 'ramp', 'reveal'],
+	map: highGroundMap,
+	reveal: false,
+	start: (world) => layOut(world),
+	source: ['examples/mechanics/highGround.ts', 'examples/mechanics/looks.ts']
+}

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

@@ -0,0 +1,44 @@
+/**
+ * The core mechanics' examples on the rules' side: their list entries, maps and starts, and what they add to the game
+ * (`ExampleCategory`). Each example is a file of its own here: its units, its commands and its start
+ */
+import type { Game } from '@v12-engine/engine'
+import type { ExampleCategory } from '../define'
+import { battle, charge, resetBattle } from './battle'
+import { damage, fire, plated, resetDamage, sorceress, warded } from './damage'
+import { cross, crossbowman, flyIn, flying, gryphon, resetFlying } from './flying'
+import { formations, march, scatter } from './formations'
+import { climb, highGround, resetHighGround, underCliff } from './highGround'
+import { crate, maze, newMaze, run } from './maze'
+import { ordersExample, raid, resetOrders, resume, stopAll } from './orders'
+import { selection } from './selection'
+
+export { ranks } from './battle'
+
+export const category: ExampleCategory = {
+	rules: (game: Game<any>) => {
+		for (const unit of [crate, plated, warded, sorceress, gryphon, crossbowman]) game.unit(unit)
+		for (const command of [
+			charge,
+			resetBattle,
+			march,
+			scatter,
+			run,
+			newMaze,
+			climb,
+			underCliff,
+			resetHighGround,
+			raid,
+			stopAll,
+			resume,
+			resetOrders,
+			fire,
+			resetDamage,
+			cross,
+			flyIn,
+			resetFlying
+		])
+			game.command(command)
+	},
+	examples: [battle, selection, formations, maze, ordersExample, highGround, damage, flying]
+}

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

@@ -0,0 +1,289 @@
+/** The core mechanics' examples on the client's side: their looks and controls, by id (`CategoryLooks`) */
+import { type GameClientApi, presetPings, type UnitLook } from '@v12-engine/client'
+import { button, readout, select, type CategoryLooks } from '../../shell/look'
+import { character, hold, person } from '../common/looks'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { charge, resetBattle } from './battle'
+import { fire, plated, resetDamage, sorceress, TARGETS, warded } from './damage'
+import { cross, crossbowman, flyIn, gryphon, resetFlying } from './flying'
+import { FORMATIONS, march, scatter } from './formations'
+import { climb, resetHighGround, underCliff } from './highGround'
+import { crate, newMaze, run } from './maze'
+import { raid, resetOrders, resume, stopAll } from './orders'
+
+const STEEL: [number, number, number] = [0.62, 0.65, 0.7]
+const WOOD: [number, number, number] = [0.45, 0.31, 0.18]
+
+/**
+ * A post to shoot at: the shared art's training dummy in a tint, plated grey or warded violet. The parts (a pole and a
+ * body in a colour, a band of `band` round it) show until it has loaded
+ */
+const post = (body: [number, number, number], band: [number, number, number], tint: [number, number, number]): UnitLook => ({
+	height: 1.9,
+	blood: false,
+	model: { src: 'props/dummy.glb', scale: 1, tint },
+	shapes: [
+		{ shape: 'cylinder', size: [0.16, 1.1, 0.16], offset: [0, 0.55, 0], color: WOOD },
+		{ shape: 'cylinder', size: [0.75, 1, 0.6], offset: [0, 1.25, 0], color: body },
+		{ shape: 'cylinder', size: [0.8, 0.14, 0.65], offset: [0, 1.4, 0], color: band },
+		{ shape: 'sphere', size: [0.5, 0.5, 0.5], offset: [0, 1.95, 0], color: body }
+	]
+})
+
+/** The looks of the units the examples here add */
+const looks: Record<string, UnitLook> = {
+	[crate.id]: {
+		height: 1,
+		blood: false,
+		model: { src: 'dungeon-kit/crate.glb', scale: 0.95 },
+		shapes: [{ shape: 'box', size: [0.95, 0.95, 0.95], offset: [0, 0.48, 0], color: WOOD }]
+	},
+	[plated.id]: post(STEEL, [0.35, 0.37, 0.42], [0.7, 0.75, 0.85]),
+	[warded.id]: post([0.42, 0.3, 0.62], [0.55, 0.85, 1], [0.75, 0.55, 1]),
+	[sorceress.id]: {
+		height: 1.8,
+		model: character('mage', 0.72, { hold: [hold('staff')] }),
+		shot: { color: [0.75, 0.4, 1], size: 0.35 },
+		shapes: person(1.8)
+	},
+	[crossbowman.id]: {
+		height: 1.7,
+		model: character('ranger', 0.68, { hold: [hold('crossbow_2handed')], animations: { attack: 'Ranged_2H_Shoot' } }),
+		shot: { color: [0.5, 0.45, 0.4], size: 0.2 },
+		shapes: person(1.7)
+	},
+	// a gryphon and its rider, drawn as parts: its body, head and beak, wings, tail and the rider in the side's colour. The
+	// shared art has no beast that flies, so the parts are its look
+	[gryphon.id]: {
+		height: 1.9,
+		altitude: 3.2,
+		shot: { color: [0.55, 0.8, 1], size: 0.3 },
+		shapes: [
+			{ shape: 'sphere', size: [0.8, 0.7, 1.5], offset: [0, 0.7, 0], color: [0.72, 0.58, 0.36] },
+			{ shape: 'sphere', size: [0.5, 0.5, 0.6], offset: [0, 1.05, 0.85], color: [0.93, 0.91, 0.84] },
+			{ shape: 'cone', size: [0.2, 0.4, 0.2], offset: [0, 0.98, 1.25], color: [1, 0.8, 0.2], tilt: Math.PI / 2 },
+			{ shape: 'box', size: [1.7, 0.08, 0.8], offset: [1.1, 0.95, 0], color: [0.6, 0.47, 0.28], turn: 0.25 },
+			{ shape: 'box', size: [1.7, 0.08, 0.8], offset: [-1.1, 0.95, 0], color: [0.6, 0.47, 0.28], turn: -0.25 },
+			{ shape: 'cone', size: [0.5, 0.9, 0.5], offset: [0, 0.65, -1], color: [0.6, 0.47, 0.28], tilt: -Math.PI / 2 },
+			{ shape: 'box', size: [0.45, 0.7, 0.35], offset: [0, 1.35, -0.1], color: 'team' },
+			{ shape: 'sphere', size: [0.34, 0.34, 0.34], offset: [0, 1.85, -0.1], color: STEEL }
+		]
+	}
+}
+
+/** The live units of the player's, or of `owner`, as the screen knows them */
+const unitsOf = (client: GameClientApi, owner = PLAYER) =>
+	client.session.snapshot().entities.filter((each) => each.owner === owner && each.health > 0)
+/** How many of `owner`'s are alive */
+const count = (client: GameClientApi, owner: number) => unitsOf(client, owner).length
+/** Selects the player's units of a type, as a click on each would */
+const selectType = (client: GameClientApi, type: string) =>
+	client.controller.select(
+		unitsOf(client)
+			.filter((each) => each.type === type)
+			.map((each) => each.id)
+	)
+
+/** Looks down at a square of the field `size` cells across round a point: from far enough to see all of it */
+const view = (client: GameClientApi, x: number, z: number, size: number) =>
+	client.camera.frame({ minX: x - size / 2, minZ: z - size / 2, maxX: x + size / 2, maxZ: z + size / 2 })
+
+/** The formation chosen on the card, which March sends */
+let formation: (typeof FORMATIONS)[number] = 'rows'
+/** The seed of the maze stacked last */
+let seed = 1
+
+export const category: CategoryLooks = {
+	view: (view) => ({ ...view, units: { ...view.units, looks: { ...view.units?.looks, ...looks } } }),
+	looks: {
+		'mechanics-battle': {
+			controls: [
+				button(
+					'Charge',
+					(client) => client.session.send(charge.make({})),
+					'Sends both armies at each other; each unit fights whatever it meets on the way'
+				),
+				button(
+					'Lay it out again',
+					(client) => client.session.send(resetBattle.make({})),
+					'Takes every unit away and lines both armies up again, whole'
+				),
+				readout('Yours · theirs', (client) => `${count(client, PLAYER)} · ${count(client, ENEMY)}`, 'How many units each side has left alive')
+			]
+		},
+		'mechanics-selection': {
+			// the ready-made pings' looks: a kind with none is sent and drawn nowhere
+			view: (view) => ({ ...view, pings: { ...view.pings, kinds: view.pings?.kinds ?? presetPings() } }),
+			ready: (client) => view(client, 24, 23, 18),
+			controls: [
+				button('Footmen', (client) => selectType(client, UNIT.footman), 'Selects every footman of yours, as a double-click on one would'),
+				button('Archers', (client) => selectType(client, UNIT.archer), 'Selects every archer of yours'),
+				button('The whole army', (client) => client.controller.selectArmy(), 'Selects every unit of yours that fights, as F2 does in the HUD'),
+				button('Keep as group 1', (client) => client.controller.assignGroup(1), 'Keeps what is selected as group 1, as Ctrl+1 does'),
+				button('Take group 1', (client) => client.controller.recallGroup(1), 'Selects group 1 again, as pressing 1 does'),
+				button(
+					'Ping the enemy',
+					(client) => {
+						const [enemy] = unitsOf(client, ENEMY)
+						if (enemy) client.controller.ping({ x: enemy.x, z: enemy.z }, 'danger')
+					},
+					'Pings the first enemy unit on the map and the minimap, for your allies and you'
+				),
+				readout(
+					'Selected',
+					(client) => {
+						const ids = new Set(client.controller.selected)
+						const types = new Map<string, number>()
+						for (const each of client.session.snapshot().entities) if (ids.has(each.id)) types.set(each.type, (types.get(each.type) ?? 0) + 1)
+						return [...types].map(([type, n]) => `${n} ${type}`).join(', ') || 'nothing'
+					},
+					'What is selected now, by type: the buttons above change it, and so do your clicks'
+				)
+			]
+		},
+		'mechanics-formations': {
+			ready: (client) => {
+				client.controller.setFormation(formation)
+				view(client, 24, 24, 19)
+				// the player's own orders back to the game's formation as the example is left
+				return () => client.controller.setFormation(undefined)
+			},
+			controls: [
+				select(
+					'Formation',
+					FORMATIONS,
+					formation,
+					(client, value) => {
+						formation = value as typeof formation
+						client.controller.setFormation(formation)
+					},
+					'The shape the group takes where it is sent: by March, and by your own right-clicks'
+				),
+				button(
+					'March',
+					(client) => client.session.send(march.make({ formation })),
+					'Sends all thirty to the other end of the field in the formation chosen above'
+				),
+				button('Scatter them', (client) => client.session.send(scatter.make({})), 'Puts the thirty back in a loose crowd at the near end')
+			]
+		},
+		'mechanics-maze': {
+			ready: (client) => view(client, 16, 13, 25),
+			controls: [
+				button(
+					'Run',
+					(client) => {
+						// the runners selected, so that their paths are drawn
+						client.controller.select(unitsOf(client).map((each) => each.id))
+						client.session.send(run.make({}))
+					},
+					'Selects the three runners, so that their paths are drawn, and sends them to the far corner of the maze (or back)'
+				),
+				button(
+					'New maze',
+					(client) => client.session.send(newMaze.make({ seed: ++seed })),
+					'Stacks a different maze of crates and puts the runners back in its first corner'
+				)
+			]
+		},
+		'mechanics-orders': {
+			ready: (client) => view(client, 24, 24, 24),
+			controls: [
+				button(
+					'Send raiders',
+					(client) => client.session.send(raid.make({})),
+					'Three enemy raiders come down the field: watch who fights them, who only shoots, and who walks past'
+				),
+				button('Stop everyone', (client) => client.session.send(stopAll.make({})), 'Drops every order: they fight what comes near where they stand'),
+				button(
+					'Back to their orders',
+					(client) => client.session.send(resume.make({})),
+					'Gives each group its order again: the footmen patrol, the archers hold, the knight walks up and down'
+				),
+				button(
+					'Lay it out again',
+					(client) => client.session.send(resetOrders.make({})),
+					'Puts your three groups back where they started, on their orders, and takes the raiders away'
+				),
+				readout(
+					'Footmen · archers · knight',
+					(client) => {
+						const mine = unitsOf(client)
+						const order = (type: string) => mine.find((each) => each.type === type)?.own?.order ?? 'idle'
+						return `${order(UNIT.footman)} · ${order(UNIT.archer)} · ${order(UNIT.knight)}`
+					},
+					'The order each group is on now, as the game tells the screen'
+				)
+			]
+		},
+		'mechanics-high-ground': {
+			ready: (client) => view(client, 21, 19, 20),
+			controls: [
+				button(
+					'Walk under the cliff',
+					(client) => client.session.send(underCliff.make({})),
+					'Your party walks to the foot of the cliff and holds there: arrows come down from archers it cannot see'
+				),
+				button(
+					'Climb the ramp',
+					(client) => client.session.send(climb.make({})),
+					'Your party walks up the ramp: at the top the archers on the plateau come out of the dark, and are fought'
+				),
+				button(
+					'Lay it out again',
+					(client) => client.session.send(resetHighGround.make({})),
+					'Your party back below the cliff and the archers back on the plateau, all whole'
+				),
+				// what the screen is told of the enemy's: only what the player's side sees
+				readout(
+					'Enemy archers seen',
+					(client) => `${client.session.snapshot().entities.filter((each) => each.owner === ENEMY && each.visible).length} of 4`,
+					'How many of the enemy archers in reach of the ramp your side can see now'
+				),
+				readout('Yours left', (client) => `${count(client, PLAYER)}`, 'Your party members still alive')
+			]
+		},
+		'mechanics-damage': {
+			ready: (client) => view(client, 24, 22, 17),
+			controls: [
+				button('Fire', (client) => client.session.send(fire.make({})), 'Each pair of shooters attacks the post in front of it'),
+				button(
+					'Whole again',
+					(client) => client.session.send(resetDamage.make({})),
+					'The posts whole again and the shooters back in place, holding fire'
+				),
+				...TARGETS.map((target) =>
+					readout(
+						target.name,
+						(client) => {
+							const post = client.session.snapshot().entities.find((each) => each.name === target.name)
+							return post ? `${Math.round((post.maxHealth ?? 4000) - post.health)} lost` : '—'
+						},
+						'Health this post has lost: armor lessens arrows, magic resist lessens bolts'
+					)
+				)
+			]
+		},
+		'mechanics-flying': {
+			ready: (client) => view(client, 20, 20, 28),
+			controls: [
+				button(
+					'Cross the ridge',
+					(client) => client.session.send(cross.make({})),
+					'Sends your three to the other side: the gryphon flies straight over, the two on foot go round by the gap'
+				),
+				button(
+					'Enemy flyers',
+					(client) => client.session.send(flyIn.make({})),
+					'Two enemy gryphons fly at your units: the footman cannot reach them, the crossbowman and your gryphon can'
+				),
+				button(
+					'Lay it out again',
+					(client) => client.session.send(resetFlying.make({})),
+					'Your three back on the west side, the enemy flyers taken away'
+				),
+				readout('Enemy flyers', (client) => `${count(client, ENEMY)}`, 'Enemy gryphons still in the air')
+			]
+		}
+	}
+}

package/starters/examples/src/examples/mechanics/maze.ts

@@ -0,0 +1,119 @@
+/**
+ * Finding the way: crates stacked into a maze, and units sent from its one corner to the other.
+ * Each crate is a building of one cell, so it shuts its cell to walkers; the engine finds a path round them all, and
+ * cuts the ground's paths anew where crates are taken away or put down while the game runs
+ */
+import { defineCommand, number, type UnitTypeDef, type World } from '@v12-engine/engine'
+import { PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+
+/** A crate: a building of one cell that nobody fights, and that cannot be hurt. A maze is made of them */
+export const crate: UnitTypeDef = {
+	id: 'mechanicsCrate',
+	name: 'Crate',
+	kind: 'building',
+	radius: 0.5,
+	footprint: { w: 1, d: 1 },
+	stats: { health: 100 },
+	sight: 0,
+	invulnerable: true,
+	ignored: true
+}
+
+/** Rooms of the maze a side, each two cells wide with a cell of wall between: wide enough to walk at full speed */
+const ROOMS = 7
+/** The cell the maze starts at, both ways: the field is 32 a side and the maze 22 */
+const AT = 5
+/** Cells of the maze a side, its outer wall too: shut all round, so that the only way is through */
+const SIDE = ROOMS * 3 + 1
+/** Where the runners start, in the first room of the maze (its south-west corner), and where they go, the last room */
+const FROM = { x: AT + 2, z: AT + 2 }
+const TO = { x: AT + SIDE - 2, z: AT + SIDE - 2 }
+
+/**
+ * The walls of a maze of `ROOMS` by `ROOMS` rooms, a passage dug from each room to one it had not reached yet (a
+ * depth-first walk), drawn from `seed`: true for a cell that is wall. The same seed is the same maze
+ */
+export function mazeWalls(seed: number): boolean[] {
+	let state = (seed * 2654435761) >>> 0 || 1
+	const random = () => (state = (state * 1664525 + 1013904223) >>> 0) / 4294967296
+	const wall = new Array<boolean>(SIDE * SIDE).fill(true)
+	const dig = (x: number, z: number) => {
+		wall[z * SIDE + x] = false
+		wall[z * SIDE + x + 1] = false
+		wall[(z + 1) * SIDE + x] = false
+		wall[(z + 1) * SIDE + x + 1] = false
+	}
+	const seen = new Set<number>()
+	const stack = [0]
+	seen.add(0)
+	dig(1, 1)
+	while (stack.length) {
+		const room = stack[stack.length - 1]
+		const rx = room % ROOMS
+		const rz = Math.floor(room / ROOMS)
+		const next = [
+			[rx + 1, rz],
+			[rx - 1, rz],
+			[rx, rz + 1],
+			[rx, rz - 1]
+		].filter(([x, z]) => x >= 0 && z >= 0 && x < ROOMS && z < ROOMS && !seen.has(z * ROOMS + x))
+		if (!next.length) {
+			stack.pop()
+			continue
+		}
+		const [nx, nz] = next[Math.floor(random() * next.length)]
+		// the room, and the wall between the two: two cells from the nearer room's inner half into the wall
+		dig(nx * 3 + 1, nz * 3 + 1)
+		if (nx !== rx) dig(Math.min(rx, nx) * 3 + 2, rz * 3 + 1)
+		else dig(rx * 3 + 1, Math.min(rz, nz) * 3 + 2)
+		seen.add(nz * ROOMS + nx)
+		stack.push(nz * ROOMS + nx)
+	}
+	return wall
+}
+
+/** Takes every crate away and stacks a maze of `seed` */
+function buildMaze(world: World, seed: number): void {
+	// of every entity: a crate is no player's and only stands there, scenery, which `world.units` (the entities that act) leaves out
+	for (const entity of [...world.entities.values()]) if (entity.alive && entity.def.id === crate.id) world.kill(entity, undefined, false, 'removed')
+	const walls = mazeWalls(seed)
+	for (let z = 0; z < SIDE; z++)
+		for (let x = 0; x < SIDE; x++) if (walls[z * SIDE + x]) world.spawn(crate.id, { at: { x: AT + x + 0.5, z: AT + z + 0.5 }, owner: 0 })
+}
+
+/** The three runners in the first room: a footman, an archer and the knight, each finding its own way */
+function runners(world: World): void {
+	for (const unit of [...world.units.values()]) if (unit.owner === PLAYER) world.kill(unit, undefined, false, 'removed')
+	;[UNIT.footman, UNIT.archer, UNIT.knight].forEach((type, i) =>
+		world.spawn(type, { at: { x: FROM.x + (i % 2) * 0.9 - 0.45, z: FROM.z + (i - 1) * 0.7 }, owner: PLAYER })
+	)
+}
+
+/** Sends the runners through: to the far corner, or back to the first when they stand past the middle */
+export const run = defineCommand('mechanics.run', {}, (world, player) => {
+	const units = [...world.units.values()].filter((unit) => unit.alive && unit.owner === player)
+	const past = units.some((unit) => unit.pos.x > AT + SIDE / 2)
+	world.issue({ type: 'order', player, entities: units.map((unit) => unit.id), order: { type: 'move', point: past ? FROM : TO } })
+})
+
+/** A new maze of the seed, the runners back in the first room */
+export const newMaze = defineCommand('mechanics.maze', { seed: number }, (world, _player, { seed }) => {
+	buildMaze(world, seed)
+	runners(world)
+})
+
+export const maze: ExampleDef = {
+	id: 'mechanics-maze',
+	category: 'mechanics',
+	title: 'Paths through a maze',
+	summary:
+		'A maze of crates, and three units in its corner that find their own way to the far one. Press Run, or right-click anywhere in it; New maze stacks another, and the paths are cut again at once.',
+	tags: ['pathfinding', 'path', 'navigation', 'maze', 'obstacles', 'walls'],
+	map: () => exampleField({ name: 'Maze', size: 32, tile: 'dirt' }),
+	start: (world) => {
+		buildMaze(world, 1)
+		runners(world)
+	},
+	source: ['examples/mechanics/maze.ts', 'examples/mechanics/looks.ts']
+}

package/starters/examples/src/examples/mechanics/orders.ts

@@ -0,0 +1,68 @@
+/**
+ * Orders: what a unit is told to do, and what it does about enemies on the way. Footmen patrol between two flags and
+ * fight what they meet, then walk on; archers hold their position and shoot what comes in reach, but never chase; a
+ * knight on a plain move walks past every enemy. Raiders cross the field to show each of them
+ */
+import { defineCommand, type World } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+
+/** The patrol's two flags, and the archers' post between them */
+const WEST = { x: 12, z: 24 }
+const EAST = { x: 36, z: 24 }
+const POST = { x: 24, z: 28 }
+
+/** Each group of the player's on its order: the patrol, the post held, and the knight walking up and down */
+function orders(world: World): void {
+	for (const unit of world.units.values()) {
+		if (!unit.alive || unit.owner !== PLAYER) continue
+		if (unit.def.id === UNIT.footman) unit.order('patrol', unit.pos.x < 24 ? EAST : WEST)
+		else if (unit.def.id === UNIT.archer) unit.order('hold')
+		else if (unit.def.id === UNIT.knight) {
+			// moves one after another (`queue`): across the field and back, three times
+			const far = unit.pos.x < 24 ? 40 : 8
+			for (let leg = 0; leg < 6; leg++) unit.order('move', { x: leg % 2 ? 48 - far : far, z: 18 }, { queue: leg > 0 })
+		}
+	}
+}
+
+/** The player's three groups, the enemy's taken away */
+function layOut(world: World): void {
+	for (const unit of [...world.units.values()]) if (unit.alive) world.kill(unit, undefined, false, 'removed')
+	for (let i = 0; i < 3; i++) world.spawn(UNIT.footman, { at: { x: WEST.x, z: WEST.z - 1.4 + i * 1.4 }, owner: PLAYER })
+	for (let i = 0; i < 4; i++) world.spawn(UNIT.archer, { at: { x: POST.x - 2.1 + i * 1.4, z: POST.z }, owner: PLAYER })
+	world.spawn(UNIT.knight, { at: { x: 8, z: 18 }, owner: PLAYER })
+	orders(world)
+}
+
+/** Three raiders come down the field from the north, fighting what they meet on the way to its south edge */
+export const raid = defineCommand('mechanics.raid', {}, (world) => {
+	const x = 16 + world.rng.next() * 16
+	for (let i = 0; i < 3; i++) {
+		const raider = world.spawn(UNIT.footman, { at: { x: x + i * 1.4, z: 44 }, owner: ENEMY })
+		raider.order('attackMove', { x: x + i * 1.4, z: 4 })
+	}
+})
+
+/** Every unit of the player's stops: what it was told is dropped, and it fights what comes near where it stands */
+export const stopAll = defineCommand('mechanics.stop', {}, (world, player) => {
+	const ids = [...world.units.values()].filter((unit) => unit.alive && unit.owner === player).map((unit) => unit.id)
+	world.issue({ type: 'stop', player, entities: ids })
+})
+
+/** Each group back on its order */
+export const resume = defineCommand('mechanics.resume', {}, (world) => orders(world))
+
+export const resetOrders = defineCommand('mechanics.resetOrders', {}, (world) => layOut(world))
+
+export const ordersExample: ExampleDef = {
+	id: 'mechanics-orders',
+	category: 'mechanics',
+	title: 'Patrol, hold and move',
+	summary:
+		'Footmen patrol between two points, archers hold their post, a knight walks up and down on a plain move. Send raiders and see who fights, who chases and who walks on; Stop drops every order.',
+	tags: ['orders', 'patrol', 'hold position', 'stop', 'attack move', 'move'],
+	map: () => exampleField({ name: 'Orders', players: 2 }),
+	start: (world) => layOut(world),
+	source: ['examples/mechanics/orders.ts', 'examples/mechanics/looks.ts']
+}

package/starters/examples/src/examples/mechanics/selection.ts

@@ -0,0 +1,30 @@
+/**
+ * Selection and control groups, the player's hands: all of it is the client's (`client.controller`), the rules only
+ * lay the army out. Click a unit, drag a box, double-click for every one of its type on the screen; Ctrl and a number
+ * keeps the selection as a group, the number alone takes it back, twice looks at it. The card does the same from code
+ */
+import type { World } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+import { ranks } from './battle'
+
+/** The player's army in three blocks, and a few of the enemy's across the field to send them at */
+function army(world: World): void {
+	ranks(world, UNIT.footman, PLAYER, { x: 18, z: 18 }, 8, 4)
+	ranks(world, UNIT.archer, PLAYER, { x: 30, z: 18 }, 6, 3)
+	world.spawn(UNIT.knight, { at: { x: 24, z: 16 }, owner: PLAYER })
+	world.spawn(UNIT.mage, { at: { x: 24, z: 19 }, owner: PLAYER })
+	ranks(world, UNIT.footman, ENEMY, { x: 24, z: 34 }, 6, 3)
+}
+
+export const selection: ExampleDef = {
+	id: 'mechanics-selection',
+	category: 'mechanics',
+	title: 'Selection and control groups',
+	summary:
+		'Click, drag a box, double-click for all of a kind, Shift to add. Ctrl+1 keeps a selection as group 1 and 1 takes it back. The card selects by type, makes groups and pings the map from code.',
+	tags: ['selection', 'select', 'control group', 'hotkeys', 'box', 'ping', 'minimap'],
+	map: () => exampleField({ name: 'Selection', players: 2 }),
+	start: (world) => army(world),
+	source: ['examples/mechanics/selection.ts', 'examples/mechanics/looks.ts']
+}