@v12-engine/create 0.1.1 → 0.4.0

package/starters/examples/src/examples/gui/plates.ts

@@ -0,0 +1,87 @@
+/**
+ * The plates over units' heads, set while the game runs (`client.unitHud`): a plate is a column of widgets (bars,
+ * words, a face, a badge, a ring) and a def picks one for whom and when (`UnitHudDef`). Each design below is set on
+ * every unit type of the camp (`client.unitHud.defs.set`); how they are drawn is the defaults' (`client.unitHud.look`):
+ * on the canvas over the picture, as HTML elements, or with Babylon's GUI
+ */
+import type { GameClientApi, UnitHudDef } from '@v12-engine/client'
+import { UNIT } from '../common/units'
+
+/** The camp's unit types, which the designs are set on */
+const TYPES = [UNIT.footman, UNIT.archer, UNIT.mage, UNIT.knight]
+
+/** A unit's name as its plate says it: the knights by their own */
+const nameOf = (unit: { def: { name: string }; state: { name?: string } }) =>
+	unit.state.name === 'hero' ? 'Sir Aldwin' : unit.state.name === 'warlord' ? 'The Warlord' : unit.def.name
+
+/** The designs to pick from, by their names in the example's select */
+export const DESIGNS: Record<string, UnitHudDef> = {
+	// a thin bar, only while hurt (and while selected or hovered), as most RTS games do
+	'Bars when hurt': {
+		plates: [
+			{ when: { selected: true }, show: 'always', items: [{ bar: 'health', width: 46, height: 5, ghost: { seconds: 0.5 } }] },
+			{ show: 'hurt', items: [{ bar: 'health', width: 46, height: 5, ghost: { seconds: 0.5 } }] }
+		]
+	},
+	// a name over a bar with ticks every 100 points, always
+	'Name and bar': {
+		plates: [
+			{
+				show: 'always',
+				items: [
+					{ text: nameOf, size: 11, color: 'owner', bold: true },
+					{ bar: 'health', width: 64, height: 7, ticks: 100, ghost: { seconds: 0.6 } }
+				]
+			}
+		]
+	},
+	// the full card: a face, the name, the level, health with its points and mana; enemies get a plain bar
+	'Hero card': {
+		plates: [
+			{
+				when: { relation: ['self', 'ally'] },
+				show: 'always',
+				items: [
+					{
+						row: [
+							{ portrait: true, size: 28, border: 'owner', shape: 'circle' },
+							{
+								column: [
+									{ text: nameOf, size: 12, color: 'owner', bold: true },
+									{ bar: 'health', width: 86, height: 8, label: 'value', ghost: { seconds: 0.6 } },
+									{ bar: 'mana', width: 86, height: 3 }
+								]
+							},
+							{ badge: (unit) => unit.level ?? 1, size: 16 }
+						],
+						gap: 4
+					}
+				]
+			},
+			{
+				show: 'always',
+				items: [
+					{ text: nameOf, size: 11, color: 'owner' },
+					{ bar: 'health', width: 64, height: 6 }
+				]
+			}
+		]
+	},
+	// a ring round a dot, filling as health is lost: small and clean
+	Rings: { plates: [{ show: 'always', items: [{ ring: 'health', size: 18, width: 3 }] }] },
+	// names alone, no bars at all
+	'Names only': { plates: [{ show: 'always', items: [{ text: nameOf, size: 12, color: 'owner', bold: true }] }] }
+}
+
+/** Sets a design on every type of the camp */
+export function setDesign(client: GameClientApi, name: string): void {
+	const def = DESIGNS[name]
+	if (!def) return
+	for (const type of TYPES) client.unitHud.defs.set(type, def)
+}
+
+/** The plates as the types' own again, drawn on the canvas */
+export function restorePlates(client: GameClientApi): void {
+	for (const type of TYPES) client.unitHud.defs.set(type, undefined)
+	client.unitHud.look.render = 'canvas'
+}

package/starters/examples/src/examples/gui/radial.ts

@@ -0,0 +1,104 @@
+/**
+ * A radial menu of orders, the game's own: a right-click on the ground with units selected opens a ring of buttons
+ * where the click was (an element pinned to that spot of the world, `client.attach`), in place of the smart order
+ * (`GameView.input.onRightClick` says it is the game's). Each button sends an order for the selected units, as the
+ * HUD's card would: a command (`{ type: 'order', entities, order }`), or one of the game's own (`gather`)
+ */
+import type { GameClientApi, GameView, Pin } from '@v12-engine/client'
+import type { Vec2 } from '@v12-engine/engine'
+import { gather } from './index'
+
+/** What a right-click on the map is given (the client's `ClickContext`: the spot, what is under it, what is selected) */
+type ClickContext = Parameters<NonNullable<NonNullable<GameView['input']>['onRightClick']>>[0]
+
+/** The ring's buttons: a glyph, a word, and the order sent for the selected units at the spot */
+const ORDERS: { glyph: string; label: string; order: (ids: number[], at: Vec2, client: GameClientApi) => void }[] = [
+	{
+		glyph: '➜',
+		label: 'Move',
+		order: (ids, at, client) => client.session.send({ type: 'order', entities: ids, order: { type: 'move', point: at } })
+	},
+	{
+		glyph: '⚔',
+		label: 'Attack',
+		order: (ids, at, client) => client.session.send({ type: 'order', entities: ids, order: { type: 'attackMove', point: at } })
+	},
+	{ glyph: '⛨', label: 'Hold', order: (ids, _at, client) => client.session.send({ type: 'order', entities: ids, order: { type: 'hold' } }) },
+	{ glyph: '■', label: 'Stop', order: (ids, _at, client) => client.session.send({ type: 'order', entities: ids, order: { type: 'stop' } }) },
+	{ glyph: '✺', label: 'Gather', order: (_ids, at, client) => client.session.send(gather.make({ at })) }
+]
+
+const STYLE = `
+.gui-radial { position: relative; width: 190px; height: 190px; pointer-events: none; animation: guiRadialIn .14s ease-out }
+.gui-radial::before { content: ''; position: absolute; inset: 52px; border-radius: 50%; border: 2px dashed rgba(242, 213, 138, .55) }
+.gui-radial button { pointer-events: auto; position: absolute; width: 58px; height: 58px; margin: -29px; border-radius: 50%; cursor: pointer;
+	border: 2px solid #c9a35a; background: radial-gradient(circle at 35% 30%, #3b3326, #15120c); color: #f6e3ae;
+	display: grid; place-items: center; font: 20px/1 system-ui; box-shadow: 0 4px 12px rgba(0,0,0,.6); transition: transform .08s }
+.gui-radial button span { position: absolute; bottom: -17px; font: 600 11px system-ui, sans-serif; color: #fff; text-shadow: 0 1px 3px #000 }
+.gui-radial button:hover { transform: scale(1.14); border-color: #fff2c4; background: radial-gradient(circle at 35% 30%, #5a4a2a, #241c0e) }
+@keyframes guiRadialIn { from { transform: scale(.5); opacity: 0 } to { transform: scale(1); opacity: 1 } }
+`
+
+/** The ring open now, and what closes it */
+let open: { pin: Pin; close: () => void } | undefined
+
+/** Closes the ring, if one is open */
+export function closeRadial(): void {
+	open?.close()
+}
+
+/** Opens the ring at a spot of the world, for the units selected now */
+function openRadial(client: GameClientApi, at: Vec2, ids: number[]): void {
+	closeRadial()
+	const ring = document.createElement('div')
+	ring.className = 'gui-radial'
+	const style = document.createElement('style')
+	style.textContent = STYLE
+	ring.append(style)
+	ORDERS.forEach((each, i) => {
+		const angle = -Math.PI / 2 + (i / ORDERS.length) * Math.PI * 2
+		const button = document.createElement('button')
+		button.type = 'button'
+		button.style.left = `${95 + Math.cos(angle) * 70}px`
+		button.style.top = `${95 + Math.sin(angle) * 70}px`
+		button.innerHTML = `${each.glyph}<span>${each.label}</span>`
+		button.onpointerdown = (event) => {
+			event.stopPropagation()
+			each.order(ids, at, client)
+			client.ping(at.x, at.z, [1, 0.85, 0.3])
+			closeRadial()
+		}
+		ring.append(button)
+	})
+	const pin = client.attach(ring, at, { anchor: 'center' })
+	// a click anywhere else, or Esc, closes it
+	const away = (event: Event) => {
+		if (event instanceof KeyboardEvent && event.key !== 'Escape') return
+		if (event instanceof PointerEvent && ring.contains(event.target as Node)) return
+		closeRadial()
+	}
+	setTimeout(() => {
+		window.addEventListener('pointerdown', away, true)
+		window.addEventListener('keydown', away, true)
+	})
+	open = {
+		pin,
+		close: () => {
+			window.removeEventListener('pointerdown', away, true)
+			window.removeEventListener('keydown', away, true)
+			pin.remove()
+			open = undefined
+		}
+	}
+}
+
+/**
+ * What the view does with a right-click (`GameView.input.onRightClick`): with the player's own units selected, opens
+ * the ring at the spot and says the click is the game's (true), so no smart order goes
+ */
+export function radialRightClick(click: ClickContext): boolean {
+	const mine = click.selected.filter((unit) => unit.owner === click.client.session.playerId).map((unit) => unit.id)
+	if (!mine.length) return false
+	openRadial(click.client, click.point, mine)
+	return true
+}

package/starters/examples/src/examples/gui/solidPart.ts

@@ -0,0 +1,107 @@
+/**
+ * A part of the HUD written in Solid: a component, given to the HUD as a widget (`HudWidgetDef.component`). No JSX:
+ * a project made from this starter has no Solid compiler in its build, so the markup is Solid's tagged template
+ * (`solid-js/html`), which is the same components and signals with nothing to compile. It is built from the client's
+ * kit (`@v12-engine/client/kit`: `Panel`, `Meter`, `Button`), so it takes the HUD's theme, and from the HUD's own
+ * signals (`client.ui.selection()`), so it changes as they do
+ */
+import { Button, Meter, Panel } from '@v12-engine/client/kit'
+import type { GameClientApi, HudWidgetDef } from '@v12-engine/client'
+import { createSignal, For, Index, onCleanup, Show } from 'solid-js'
+import html from 'solid-js/html'
+import { ENEMY, PLAYER } from '../common/units'
+import { charge, resetCamp } from './index'
+
+/** A side as the part shows it: how many stand, their health and the most they had */
+interface Side {
+	name: string
+	owner: number
+	alive: number
+	health: number
+	most: number
+}
+
+/** Each side's strength now, from the snapshot the screen was sent last */
+function sides(client: GameClientApi, most: Map<number, number>): Side[] {
+	const { entities } = client.session.snapshot()
+	return [
+		{ name: 'Yours', owner: PLAYER },
+		{ name: 'Theirs', owner: ENEMY }
+	].map(({ name, owner }) => {
+		const units = entities.filter((each) => each.owner === owner && each.health > 0)
+		const health = units.reduce((sum, each) => sum + each.health, 0)
+		// the most a side had since it was last laid out: what its meter is full at
+		const full = units.reduce((sum, each) => sum + (each.maxHealth ?? each.health), 0)
+		most.set(owner, Math.max(most.get(owner) ?? 0, full))
+		if (units.length && health >= (most.get(owner) ?? 0)) most.set(owner, full)
+		return { name, owner, alive: units.length, health, most: most.get(owner) || 1 }
+	})
+}
+
+/**
+ * The army's part: each side's strength as a meter, what is selected counted by type (a button for each selects just
+ * those), and the two orders of the camp. Solid runs it once; what it reads of signals (`client.ui.selection()`,
+ * `strength()`) it keeps up to date by itself
+ */
+function ArmyPart(props: { client: GameClientApi }) {
+	const { client } = props
+	const most = new Map<number, number>()
+	const [strength, setStrength] = createSignal(sides(client, most))
+	const timer = setInterval(() => setStrength(sides(client, most)), 250)
+	onCleanup(() => clearInterval(timer))
+
+	/** What is selected, by type: its name, how many, and their ids */
+	const picked = () => {
+		const groups = new Map<string, { name: string; ids: number[] }>()
+		for (const item of client.ui.selection()) {
+			const group = groups.get(item.typeId) ?? { name: item.name, ids: [] }
+			group.ids.push(item.id)
+			groups.set(item.typeId, group)
+		}
+		return [...groups.values()]
+	}
+
+	// styled with the theme's variables (`--vg-accent`, `--vg-muted-foreground`): it follows the HUD's theme as the kit does
+	return html`
+		<${Panel} padding="md" style="width:260px;pointer-events:auto;display:flex;flex-direction:column;gap:8px">
+			<div style="font-family:var(--vg-typeface-display);color:var(--vg-accent);font-size:17px;letter-spacing:.04em">The army</div>
+			<div style="font-size:11px;color:var(--vg-muted-foreground);margin-top:-4px">A Solid component, in the HUD's place on the left</div>
+			<${Index} each=${strength}>
+				${(side: () => Side) => html`
+					<div style="display:flex;flex-direction:column;gap:4px">
+						<div style="display:flex;justify-content:space-between;font-size:13px">
+							<span>${() => side().name}</span>
+							<span style="color:var(--vg-muted-foreground)">${() => side().alive} standing</span>
+						</div>
+						<${Meter} value=${() => side().health} max=${() => side().most} kind=${() => (side().owner === PLAYER ? 'health' : 'health-low')} />
+					</div>
+				`}
+			<//>
+			<div style="font-size:12px;color:var(--vg-muted-foreground);margin-top:4px">Selected</div>
+			<${Show}
+				when=${() => picked().length > 0}
+				fallback=${html`<div style="font-size:12px;color:var(--vg-faint-foreground)">nothing: drag a box round some</div>`}
+			>
+				<div style="display:flex;flex-wrap:wrap;gap:4px">
+					<${For} each=${picked}>
+						${(group: { name: string; ids: number[] }) =>
+							html`<${Button} size="sm" onClick=${() => client.controller.select(group.ids)} tip="Select just these"
+								>${group.ids.length} × ${group.name}<//
+							>`}
+					<//>
+				</div>
+			<//>
+			<div style="display:flex;gap:8px;margin-top:4px">
+				<${Button} variant="primary" onClick=${() => client.session.send(charge.make({}))}>Charge<//>
+				<${Button} onClick=${() => client.session.send(resetCamp.make({}))}>Lay out again<//>
+			</div>
+		<//>
+	`
+}
+
+/** The part as the HUD takes it: on the left over the map, drawn by the component above */
+export const armyPart = (client: GameClientApi): HudWidgetDef => ({
+	id: 'gui.army',
+	place: 'left',
+	component: () => ArmyPart({ client }) as ReturnType<NonNullable<HudWidgetDef['component']>>
+})

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

@@ -0,0 +1,45 @@
+/**
+ * Every example on the client's side: their looks and controls by id, and what each category adds to the game's look.
+ * Fetched with the game's look (`src/view.ts`), never with the list's page
+ */
+import type { CategoryLooks } from '../shell/look'
+import { category as mechanics } from './mechanics/looks'
+import { category as abilities } from './abilities/looks'
+import { category as moba } from './moba/looks'
+import { category as rts } from './rts/looks'
+import { category as fx } from './fx/looks'
+import { category as customFx } from './custom-fx/looks'
+import { category as animation } from './animation/looks'
+import { category as customAnimation } from './custom-animation/looks'
+import { category as destruction } from './destruction/looks'
+import { category as construction } from './construction/looks'
+import { category as nature } from './nature/looks'
+import { category as post } from './post/looks'
+import { category as dynamicMap } from './dynamic-map/looks'
+import { category as cinematics } from './cinematics/looks'
+import { category as dialogs } from './dialogs/looks'
+import { category as gui } from './gui/looks'
+import { category as showcase } from './showcase/looks'
+import { category as performance } from './performance/looks'
+
+/** The categories' looks, in the list's order */
+export const categoryLooks: readonly CategoryLooks[] = [
+	mechanics,
+	abilities,
+	moba,
+	rts,
+	fx,
+	customFx,
+	animation,
+	customAnimation,
+	destruction,
+	construction,
+	nature,
+	post,
+	dynamicMap,
+	cinematics,
+	dialogs,
+	gui,
+	showcase,
+	performance
+]

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

@@ -0,0 +1,51 @@
+/**
+ * Two armies, footmen in front and archers behind, facing each other across the field. Charge sends both at each
+ * other on attack-moves: each unit fights what it meets on the way (`attackMove`), the footmen close in and surround,
+ * the archers shoot from behind them
+ */
+import { defineCommand, type World } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+
+/** Ranks of a unit type round a point, `across` wide, 1.4 apart, facing `facing` (radians) */
+export function ranks(world: World, type: string, owner: number, at: { x: number; z: number }, count: number, across = 5): void {
+	for (let i = 0; i < count; i++) {
+		const row = Math.floor(i / across)
+		const column = i % across
+		world.spawn(type, { at: { x: at.x + (column - (across - 1) / 2) * 1.4, z: at.z + row * 1.4 }, owner })
+	}
+}
+
+/** The two armies of the battle example, facing each other across the field */
+function battleArmies(world: World): void {
+	ranks(world, UNIT.footman, PLAYER, { x: 24, z: 14 }, 10)
+	ranks(world, UNIT.archer, PLAYER, { x: 24, z: 10 }, 5)
+	ranks(world, UNIT.footman, ENEMY, { x: 24, z: 32 }, 10)
+	ranks(world, UNIT.archer, ENEMY, { x: 24, z: 36 }, 5)
+}
+
+/** Sends both sides of the battle at each other, fighting what they meet (`attackMove`) */
+export const charge = defineCommand('mechanics.charge', {}, (world) => {
+	for (const unit of world.units.values()) {
+		if (!unit.alive || (unit.owner !== PLAYER && unit.owner !== ENEMY)) continue
+		unit.order('attackMove', { x: unit.pos.x, z: unit.owner === PLAYER ? 40 : 6 })
+	}
+})
+
+/** Takes every unit away and lays the battle out again */
+export const resetBattle = defineCommand('mechanics.reset', {}, (world) => {
+	for (const unit of [...world.units.values()]) if (unit.alive) world.kill(unit, undefined, false, 'removed')
+	battleArmies(world)
+})
+
+export const battle: ExampleDef = {
+	id: 'mechanics-battle',
+	category: 'mechanics',
+	title: 'Two armies',
+	summary:
+		'Footmen and archers against footmen and archers. Charge sends both sides at each other; select yours (click or drag) and right-click to lead them yourself.',
+	tags: ['combat', 'fight', 'attack', 'selection', 'orders'],
+	map: () => exampleField({ name: 'Battle', players: 2 }),
+	start: (world) => battleArmies(world),
+	source: ['examples/mechanics/battle.ts', 'examples/mechanics/looks.ts']
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Damage types, armor and magic resist. An attack deals `physical` damage unless it says `magic` (or `true`, which
+ * nothing lessens); armor lessens what is physical and magic resist what is magic, 100 of either halving it. Four
+ * targets in a square: two plated (armor 100), two warded (magic resist 100), each shot by archers or by sorceresses
+ */
+import { defineCommand, type UnitTypeDef, type World } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+
+/** A post in plate: armor 100, no magic resist. Ignored by everyone but who is told to hit it (`ignored`), and it never dies (`undying`) */
+export const plated: UnitTypeDef = {
+	id: 'mechanicsPlated',
+	name: 'Plated post',
+	kind: 'unit',
+	radius: 0.5,
+	stats: { health: 4000, armor: 100, moveSpeed: 0 },
+	sight: 2,
+	ignored: true,
+	undying: true
+}
+
+/** A post with a ward: magic resist 100, no armor */
+export const warded: UnitTypeDef = { ...plated, id: 'mechanicsWarded', name: 'Warded post', stats: { health: 4000, magicResist: 100, moveSpeed: 0 } }
+
+/** A sorceress: she shoots bolts of magic (`damageType: 'magic'`), as hard as an archer's arrows */
+export const sorceress: UnitTypeDef = {
+	id: 'mechanicsSorceress',
+	name: 'Sorceress',
+	kind: 'unit',
+	radius: 0.42,
+	stats: { health: 260, attackDamage: 18, attackSpeed: 1, attackRange: 7, moveSpeed: 4 },
+	sight: 11,
+	attacks: [{ damageType: 'magic', damagePoint: 0.5, acquisitionRange: 8, projectileSpeed: 18 }]
+}
+
+/** The four targets, by where they stand: what shoots each, and what it is */
+export const TARGETS = [
+	{ name: 'plated · arrows', type: plated.id, shooter: UNIT.archer, at: { x: 18, z: 28 } },
+	{ name: 'plated · magic', type: plated.id, shooter: sorceress.id, at: { x: 30, z: 28 } },
+	{ name: 'warded · arrows', type: warded.id, shooter: UNIT.archer, at: { x: 18, z: 18 } },
+	{ name: 'warded · magic', type: warded.id, shooter: sorceress.id, at: { x: 30, z: 18 } }
+] as const
+
+/** The targets, whole, each with two shooters in front of it, standing still (`hold`) */
+function layOut(world: World): void {
+	for (const unit of [...world.units.values()]) if (unit.alive) world.kill(unit, undefined, false, 'removed')
+	for (const each of TARGETS) {
+		// the enemy's, which nobody goes for unless told to (`ignored`)
+		world.spawn(each.type, { at: each.at, owner: ENEMY, name: each.name })
+		for (const side of [-1, 1])
+			world.spawn(each.shooter, { at: { x: each.at.x + side * 1.2, z: each.at.z - 5 }, owner: PLAYER, facing: 0 }).order('hold')
+	}
+}
+
+/** Each pair of shooters fires at its own target */
+export const fire = defineCommand('mechanics.fire', {}, (world, player) => {
+	for (const each of TARGETS) {
+		const target = world.named(each.name)
+		if (!target) continue
+		// the two that stand in front of it, 5 cells off
+		const shooters = [...world.units.values()].filter(
+			(unit) => unit.alive && unit.owner === player && Math.abs(unit.pos.x - each.at.x) < 3 && Math.abs(unit.pos.z - (each.at.z - 5)) < 2
+		)
+		world.issue({ type: 'order', player, entities: shooters.map((unit) => unit.id), order: { type: 'attack', target: target.id } })
+	}
+})
+
+export const resetDamage = defineCommand('mechanics.resetDamage', {}, (world) => layOut(world))
+
+export const damage: ExampleDef = {
+	id: 'mechanics-damage',
+	category: 'mechanics',
+	title: 'Armor and damage types',
+	summary:
+		'Arrows deal physical damage, which armor lessens; a sorceress’s bolts deal magic, which magic resist lessens. Press Fire and watch what each post loses: the plated one shrugs off arrows, the warded one bolts.',
+	tags: ['armor', 'magic resist', 'damage type', 'physical', 'magic', 'mitigation', 'combat'],
+	map: () => exampleField({ name: 'Range', players: 2 }),
+	start: (world) => layOut(world),
+	source: ['examples/mechanics/damage.ts', 'examples/mechanics/looks.ts']
+}

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

@@ -0,0 +1,93 @@
+/**
+ * Flying units: a unit type with `flying: true` goes straight over cliffs, trees and buildings, and is hit only by
+ * attacks that name the air in their `targets`. A ridge cuts the field in two, with one gap at its far end: walkers go
+ * round by the gap, the gryphon flies over. A footman's sword cannot reach a flyer; a crossbow can
+ */
+import { createMap, defineCommand, type GameMap, type UnitTypeDef, type World } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, tiles } from '../define'
+
+/** A gryphon rider: it flies, and its bolts hit the ground and the air */
+export const gryphon: UnitTypeDef = {
+	id: 'mechanicsGryphon',
+	name: 'Gryphon Rider',
+	kind: 'unit',
+	radius: 0.6,
+	flying: true,
+	stats: { health: 500, attackDamage: 22, attackSpeed: 0.8, attackRange: 4.5, armor: 10, moveSpeed: 5 },
+	sight: 12,
+	turnRate: 6,
+	attacks: [{ damagePoint: 0.5, acquisitionRange: 8, projectileSpeed: 14, targets: ['ground', 'air'] }]
+}
+
+/** A crossbowman: an archer whose bolts reach the air as well as the ground. The shared archer's reach the ground alone */
+export const crossbowman: UnitTypeDef = {
+	id: 'mechanicsCrossbowman',
+	name: 'Crossbowman',
+	kind: 'unit',
+	radius: 0.42,
+	stats: { health: 300, attackDamage: 16, attackSpeed: 1, attackRange: 7, moveSpeed: 4.2 },
+	sight: 11,
+	attacks: [{ damagePoint: 0.5, acquisitionRange: 8, projectileSpeed: 26, targets: ['ground', 'air'] }]
+}
+
+const SIZE = 40
+/** The ridge: the cells between these, all the way down the field but for the gap at its far end */
+const RIDGE = { x0: 18, x1: 22, gapZ0: 33, gapZ1: 37 }
+const WEST = { x: 8, z: 10 }
+const EAST = { x: 32, z: 10 }
+
+/** A field cut by a rocky ridge one level up, its faces cliffs, with a gap through it at the far end */
+function ridgeMap(): GameMap {
+	const map = createMap({ name: 'Ridge', width: SIZE, depth: SIZE, players: 2, game: 'examples', tileset: tiles.map((each) => each.id) })
+	map.tiles.fill(map.tileset.indexOf('grass') + 1)
+	const rock = map.tileset.indexOf('rock') + 1
+	for (let z = 0; z < SIZE; z++) {
+		if (z >= RIDGE.gapZ0 && z < RIDGE.gapZ1) continue
+		for (let x = RIDGE.x0; x < RIDGE.x1; x++) {
+			map.levels[z * SIZE + x] = 1
+			map.tiles[z * SIZE + x] = rock
+		}
+	}
+	map.players[0].start = { x: 20, z: 14 }
+	map.players[1].start = EAST
+	return map
+}
+
+/** The player's three on the west side, 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')
+	world.spawn(UNIT.footman, { at: { x: WEST.x, z: WEST.z - 1.5 }, owner: PLAYER })
+	world.spawn(crossbowman.id, { at: { x: WEST.x, z: WEST.z }, owner: PLAYER })
+	world.spawn(gryphon.id, { at: { x: WEST.x, z: WEST.z + 1.5 }, owner: PLAYER })
+}
+
+/** All three go to the other side of the ridge, or back: each by its own way */
+export const cross = defineCommand('mechanics.cross', {}, (world, player) => {
+	for (const unit of world.units.values()) {
+		if (!unit.alive || unit.owner !== player) continue
+		const to = unit.pos.x < SIZE / 2 ? EAST : WEST
+		unit.order('move', { x: to.x, z: to.z + (unit.def.id === UNIT.footman ? -1.5 : unit.def.id === gryphon.id ? 1.5 : 0) })
+	}
+})
+
+/** Two enemy gryphons fly in at the player's units: the footman can only watch them */
+export const flyIn = defineCommand('mechanics.flyIn', {}, (world, player) => {
+	const mine = [...world.units.values()].find((unit) => unit.alive && unit.owner === player)
+	const at = mine?.pos ?? WEST
+	for (let i = 0; i < 2; i++) world.spawn(gryphon.id, { at: { x: at.x + 10, z: at.z + 14 + i * 2 }, owner: ENEMY }).order('attackMove', at)
+})
+
+export const resetFlying = defineCommand('mechanics.resetFlying', {}, (world) => layOut(world))
+
+export const flying: ExampleDef = {
+	id: 'mechanics-flying',
+	category: 'mechanics',
+	title: 'Flying units',
+	summary:
+		'A gryphon flies straight over the ridge while the footman and the crossbowman walk round by its gap. Send enemy flyers: the footman cannot hit them, the crossbowman and the gryphon can.',
+	tags: ['flying', 'air', 'flyer', 'anti-air', 'cliff', 'targets'],
+	map: ridgeMap,
+	start: (world) => layOut(world),
+	source: ['examples/mechanics/flying.ts', 'examples/mechanics/looks.ts']
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Formations: a group sent to a point lays itself out as rows, a ring, a filled square or a crowd on the point. The
+ * order says which (`formation` of a `move`); the engine gives each unit its place and fits them to their places with
+ * the fewest crossings, and those of a formation trade places on the way rather than jostle
+ */
+import { defineCommand, oneOf, type World, exactMath } from '@v12-engine/engine'
+import { PLAYER, UNIT } from '../common/units'
+import type { ExampleDef } from '../define'
+
+/** The engine's formations, by id: what the card offers */
+export const FORMATIONS = ['rows', 'circle', 'square', 'none'] as const
+
+/** The two points the group goes between, across the field */
+const ENDS = [
+	{ x: 24, z: 14 },
+	{ x: 24, z: 34 }
+]
+
+/** Twenty footmen and ten archers, scattered round the first point */
+function army(world: World): void {
+	for (let i = 0; i < 30; i++) {
+		const angle = i * 2.4
+		const away = 1.5 + (i % 7) * 0.9
+		world.spawn(i < 20 ? UNIT.footman : UNIT.archer, {
+			at: { x: ENDS[0].x + exactMath.cos(angle) * away, z: ENDS[0].z + exactMath.sin(angle) * away },
+			owner: PLAYER
+		})
+	}
+}
+
+/**
+ * Sends the player's units to the far end of the two in a formation: the end that is further from where most of them
+ * stand. Through the order command, as a right click would (`world.issue`), so that it is the same order a player gives
+ */
+export const march = defineCommand('mechanics.march', { formation: oneOf(...FORMATIONS) }, (world, player, { formation }) => {
+	const units = [...world.units.values()].filter((unit) => unit.alive && unit.owner === player && unit.isUnit)
+	if (!units.length) return
+	const middle = units.reduce((sum, unit) => sum + unit.pos.z, 0) / units.length
+	const to = Math.abs(middle - ENDS[0].z) < Math.abs(middle - ENDS[1].z) ? ENDS[1] : ENDS[0]
+	world.issue({ type: 'order', player, entities: units.map((unit) => unit.id), order: { type: 'move', point: to, formation } })
+})
+
+/** Scatters the group again round the first point */
+export const scatter = defineCommand('mechanics.scatter', {}, (world) => {
+	for (const unit of [...world.units.values()]) if (unit.alive && unit.owner === PLAYER) world.kill(unit, undefined, false, 'removed')
+	army(world)
+})
+
+export const formations: ExampleDef = {
+	id: 'mechanics-formations',
+	category: 'mechanics',
+	title: 'Formations',
+	summary:
+		'Thirty units sent across the field in rows, a ring, a filled square or no formation at all. Pick one and press March; your own right-clicks take it too, and a right-click drag turns it.',
+	tags: ['formation', 'move', 'group', 'rows', 'circle', 'square', 'order'],
+	start: (world) => army(world),
+	source: ['examples/mechanics/formations.ts', 'examples/mechanics/looks.ts']
+}