@v12-engine/create 0.1.0 → 0.4.0

package/starters/examples/src/examples/post/passes.ts

@@ -0,0 +1,213 @@
+/**
+ * Passes of our own over the finished picture: each a fragment shader, made into a `PostProcess` and put on with
+ * `client.picture.addPass`, which keeps it in its place in the camera's chain whatever else comes and goes. A pass reads
+ * the picture as `textureSampler` at `vUV` and writes the colour shown. Each is written twice, as the client's own are:
+ * in WGSL for WebGPU and in GLSL for WebGL (Babylon does not turn one into the other in the page)
+ */
+import { ShaderLanguage } from '@babylonjs/core/Materials/shaderLanguage.js'
+import { ShaderStore } from '@babylonjs/core/Engines/shaderStore.js'
+import { PostProcess } from '@babylonjs/core/PostProcesses/postProcess.js'
+import type { GameClientApi, PicturePass } from '@v12-engine/client'
+
+/** What every pass is given in GLSL: the picture, where on it, its size in pixels, the time, and a strength of 0 to 1 */
+const GLSL_HEAD = /* glsl */ `
+precision highp float;
+varying vec2 vUV;
+uniform sampler2D textureSampler;
+uniform vec2 screen;
+uniform float time;
+uniform float amount;
+vec3 picture(vec2 uv) { return texture2D(textureSampler, uv).rgb; }
+`
+
+/** The same in WGSL: the uniforms are read as `uniforms.*`, the picture sampled the same way everywhere (`picture`) */
+const WGSL_HEAD = /* wgsl */ `
+varying vUV: vec2f;
+var textureSamplerSampler: sampler;
+var textureSampler: texture_2d<f32>;
+uniform screen: vec2f;
+uniform time: f32;
+uniform amount: f32;
+fn picture(uv: vec2f) -> vec3f { return textureSampleLevel(textureSampler, textureSamplerSampler, uv, 0.0).rgb; }
+`
+
+/** A pass in both languages: the body after the head, its colour `gl_FragColor` in GLSL and `fragmentOutputs.color` in WGSL */
+interface Shader {
+	glsl: string
+	wgsl: string
+}
+
+/** The passes, by name */
+export const SHADERS = {
+	// big square pixels and few colours: an old console's
+	Pixels: {
+		glsl: `
+void main(void) {
+	float size = mix(2.0, 9.0, amount);
+	vec2 cell = floor(vUV * screen / size) * size + size * 0.5;
+	float levels = mix(24.0, 5.0, amount);
+	gl_FragColor = vec4(floor(picture(cell / screen) * levels + 0.5) / levels, 1.0);
+}`,
+		wgsl: `
+@fragment
+fn main(input: FragmentInputs) -> FragmentOutputs {
+	let size = mix(2.0, 9.0, uniforms.amount);
+	let cell = floor(input.vUV * uniforms.screen / size) * size + size * 0.5;
+	let levels = mix(24.0, 5.0, uniforms.amount);
+	fragmentOutputs.color = vec4f(floor(picture(cell / uniforms.screen) * levels + 0.5) / levels, 1.0);
+}`
+	},
+	// a curved tube's screen: lines across, the picture bent at its edges, red, green and blue in stripes
+	CRT: {
+		glsl: `
+void main(void) {
+	vec2 centred = vUV * 2.0 - 1.0;
+	vec2 uv = centred * (1.0 + dot(centred.yx, centred.yx) * 0.08 * amount) * 0.5 + 0.5;
+	float inside = step(0.0, uv.x) * step(uv.x, 1.0) * step(0.0, uv.y) * step(uv.y, 1.0);
+	vec3 color = picture(clamp(uv, 0.0, 1.0));
+	float line = 0.75 + 0.25 * sin(uv.y * screen.y * 3.14159);
+	float column = mod(floor(uv.x * screen.x), 3.0);
+	vec3 mask = column < 1.0 ? vec3(1.0, 0.75, 0.75) : column < 2.0 ? vec3(0.75, 1.0, 0.75) : vec3(0.75, 0.75, 1.0);
+	color *= mix(vec3(1.0), mask * line * 1.25, amount);
+	color *= 1.0 - dot(centred, centred) * 0.25 * amount;
+	gl_FragColor = vec4(color * inside, 1.0);
+}`,
+		wgsl: `
+@fragment
+fn main(input: FragmentInputs) -> FragmentOutputs {
+	let centred = input.vUV * 2.0 - 1.0;
+	let uv = centred * (1.0 + dot(centred.yx, centred.yx) * 0.08 * uniforms.amount) * 0.5 + 0.5;
+	let inside = step(0.0, uv.x) * step(uv.x, 1.0) * step(0.0, uv.y) * step(uv.y, 1.0);
+	var color = picture(clamp(uv, vec2f(0.0), vec2f(1.0)));
+	let line = 0.75 + 0.25 * sin(uv.y * uniforms.screen.y * 3.14159);
+	let column = floor(uv.x * uniforms.screen.x) % 3.0;
+	var mask = vec3f(0.75, 0.75, 1.0);
+	if (column < 1.0) { mask = vec3f(1.0, 0.75, 0.75); } else if (column < 2.0) { mask = vec3f(0.75, 1.0, 0.75); }
+	color = color * mix(vec3f(1.0), mask * line * 1.25, uniforms.amount);
+	color = color * (1.0 - dot(centred, centred) * 0.25 * uniforms.amount);
+	fragmentOutputs.color = vec4f(color * inside, 1.0);
+}`
+	},
+	// under water: the picture wavers, green-blue, light dancing over it
+	'Under water': {
+		glsl: `
+void main(void) {
+	vec2 uv = vUV + vec2(sin(vUV.y * 24.0 + time * 1.7), cos(vUV.x * 20.0 + time * 1.3)) * 0.004 * amount;
+	vec3 color = picture(uv);
+	float caustic = pow(abs(sin(uv.x * 40.0 + time) * sin(uv.y * 34.0 - time * 1.2)), 6.0);
+	vec3 water = color * vec3(0.45, 0.8, 0.95) + vec3(0.0, 0.05, 0.1) + caustic * 0.25;
+	gl_FragColor = vec4(mix(color, water, amount), 1.0);
+}`,
+		wgsl: `
+@fragment
+fn main(input: FragmentInputs) -> FragmentOutputs {
+	let t = uniforms.time;
+	let uv = input.vUV + vec2f(sin(input.vUV.y * 24.0 + t * 1.7), cos(input.vUV.x * 20.0 + t * 1.3)) * 0.004 * uniforms.amount;
+	let color = picture(uv);
+	let caustic = pow(abs(sin(uv.x * 40.0 + t) * sin(uv.y * 34.0 - t * 1.2)), 6.0);
+	let water = color * vec3f(0.45, 0.8, 0.95) + vec3f(0.0, 0.05, 0.1) + caustic * 0.25;
+	fragmentOutputs.color = vec4f(mix(color, water, uniforms.amount), 1.0);
+}`
+	},
+	// a pencil drawing: the edges of what is drawn in grey lines on paper, the darks hatched
+	Sketch: {
+		glsl: `
+float lum(vec2 uv) { return dot(picture(uv), vec3(0.299, 0.587, 0.114)); }
+void main(void) {
+	vec2 p = 1.0 / screen;
+	float gx = lum(vUV + vec2(p.x, 0.0)) - lum(vUV - vec2(p.x, 0.0));
+	float gy = lum(vUV + vec2(0.0, p.y)) - lum(vUV - vec2(0.0, p.y));
+	float edge = clamp(length(vec2(gx, gy)) * 6.0, 0.0, 1.0);
+	float hatch = step(0.5, fract((vUV.x + vUV.y) * screen.y * 0.18)) * step(lum(vUV), 0.35) * 0.25;
+	vec3 paper = vec3(0.96, 0.94, 0.88) * (1.0 - edge * 0.85 - hatch);
+	gl_FragColor = vec4(mix(picture(vUV), paper, amount), 1.0);
+}`,
+		wgsl: `
+fn lum(uv: vec2f) -> f32 { return dot(picture(uv), vec3f(0.299, 0.587, 0.114)); }
+@fragment
+fn main(input: FragmentInputs) -> FragmentOutputs {
+	let uv = input.vUV;
+	let p = 1.0 / uniforms.screen;
+	let gx = lum(uv + vec2f(p.x, 0.0)) - lum(uv - vec2f(p.x, 0.0));
+	let gy = lum(uv + vec2f(0.0, p.y)) - lum(uv - vec2f(0.0, p.y));
+	let edge = clamp(length(vec2f(gx, gy)) * 6.0, 0.0, 1.0);
+	let hatch = step(0.5, fract((uv.x + uv.y) * uniforms.screen.y * 0.18)) * step(lum(uv), 0.35) * 0.25;
+	let paper = vec3f(0.96, 0.94, 0.88) * (1.0 - edge * 0.85 - hatch);
+	fragmentOutputs.color = vec4f(mix(picture(uv), paper, uniforms.amount), 1.0);
+}`
+	},
+	// a heat camera's: how bright as a colour, cold blue to white hot
+	'Heat vision': {
+		glsl: `
+vec3 heat(float t) {
+	return clamp(vec3(1.5 * t - 0.25, 1.8 * t * t - 0.4, 0.8 - 1.6 * abs(t - 0.3)) + vec3(0.0, 0.0, 0.2) * (1.0 - t), 0.0, 1.0);
+}
+void main(void) {
+	vec3 color = picture(vUV);
+	gl_FragColor = vec4(mix(color, heat(dot(color, vec3(0.299, 0.587, 0.114))), amount), 1.0);
+}`,
+		wgsl: `
+fn heat(t: f32) -> vec3f {
+	return clamp(vec3f(1.5 * t - 0.25, 1.8 * t * t - 0.4, 0.8 - 1.6 * abs(t - 0.3)) + vec3f(0.0, 0.0, 0.2) * (1.0 - t), vec3f(0.0), vec3f(1.0));
+}
+@fragment
+fn main(input: FragmentInputs) -> FragmentOutputs {
+	let color = picture(input.vUV);
+	fragmentOutputs.color = vec4f(mix(color, heat(dot(color, vec3f(0.299, 0.587, 0.114))), uniforms.amount), 1.0);
+}`
+	}
+} satisfies Record<string, Shader>
+
+/** A pass's name */
+export type ShaderName = keyof typeof SHADERS
+
+/** A pass of our own put on, and how strongly it is drawn (0 to 1) */
+export interface OwnPass {
+	pass: PicturePass
+	amount: number
+}
+
+/**
+ * Puts a pass of ours on the picture, after it is finished (`before: 'screen'`, the default): its shader stored once
+ * under its name in the language the engine draws with, its strength read every frame from what is given back.
+ * `remove()` on its `pass` takes it off
+ */
+export function addShader(client: GameClientApi, name: ShaderName, amount = 1): OwnPass {
+	const id = `examplesPost${name.replace(/[^a-z]/gi, '')}`
+	ShaderStore.ShadersStore[`${id}PixelShader`] ??= GLSL_HEAD + SHADERS[name].glsl
+	ShaderStore.ShadersStoreWGSL[`${id}PixelShader`] ??= WGSL_HEAD + SHADERS[name].wgsl
+	const started = performance.now()
+	const own: OwnPass = { amount, pass: undefined as unknown as PicturePass }
+	own.pass = client.picture.addPass(
+		({ engine }) => {
+			const language = engine.isWebGPU ? ShaderLanguage.WGSL : ShaderLanguage.GLSL
+			// (name, shader, uniforms, samplers, ratio, camera, sampling, engine, reusable, defines, texture type, vertex, index uniforms, block compilation, format, language)
+			const pass = new PostProcess(
+				name,
+				id,
+				['screen', 'time', 'amount'],
+				null,
+				1,
+				null,
+				undefined,
+				engine,
+				false,
+				undefined,
+				undefined,
+				undefined,
+				undefined,
+				undefined,
+				undefined,
+				language
+			)
+			pass.onApply = (effect) => {
+				effect.setFloat2('screen', pass.width, pass.height)
+				effect.setFloat('time', (performance.now() - started) / 1000)
+				effect.setFloat('amount', own.amount)
+			}
+			return pass
+		},
+		{ name }
+	)
+	return own
+}

package/starters/examples/src/examples/rts/ai.ts

@@ -0,0 +1,49 @@
+/**
+ * A computer opponent: the engine's melee brain seated at the red player (`world.computers.seat`). It sees only what
+ * its side sees, and plays as a player does: it puts its peasants to work, builds farms and a barracks, trains an army
+ * and, once it has a wave, comes for your base. Yours has a barracks, a tower and a few footmen to meet it
+ */
+import { defineCommand, type World } from '@v12-engine/engine'
+import { meleeBrain } from '@v12-engine/engine/ai'
+import { ENEMY, PLAYER } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+import { base, clear, purse, startWork } from './base'
+import { RTS } from './data'
+
+/** The two bases, at opposite corners of the field */
+export const HOME = { x: 18, z: 16 }
+export const THEIRS = { x: 50, z: 48 }
+
+/** Both bases, their peasants at work; yours with a barracks, a farm, a tower and four footmen; the computer seated at theirs */
+function layOut(world: World): void {
+	clear(world)
+	purse(world, PLAYER, 600, 300)
+	purse(world, ENEMY, 800, 400)
+	base(world, PLAYER, HOME)
+	startWork(world, PLAYER, 3)
+	world.spawn(RTS.barracks, { at: { x: 24.5, z: 22.5 }, owner: PLAYER })
+	world.spawn(RTS.farm, { at: { x: 15, z: 10 }, owner: PLAYER })
+	world.spawn(RTS.tower, { at: { x: 26, z: 27 }, owner: PLAYER })
+	for (let i = 0; i < 4; i++) world.spawn(RTS.footman, { at: { x: 22 + i * 1.4, z: 26 }, owner: PLAYER, facing: 0.8 })
+	base(world, ENEMY, THEIRS)
+	startWork(world, ENEMY, 3)
+	// the engine's melee brain, handed over itself: its first wave of four after a minute and a half, then every minute
+	world.computers.seat(ENEMY, { brain: meleeBrain, enemyBases: [HOME], settings: { army: { firstAttack: 90, waveSize: 4, attackEvery: 60 } } })
+}
+
+/** Tells the computer to attack now, with what it has (a mission's script talks to its brain the same way) */
+export const attackNow = defineCommand('rts.attackNow', {}, (world) => void world.computers.tell(ENEMY, 'attack', { at: HOME }))
+
+export const resetAi = defineCommand('rts.resetAi', {}, (world) => layOut(world))
+
+export const ai: ExampleDef = {
+	id: 'rts-ai',
+	category: 'rts',
+	title: 'A computer opponent',
+	summary:
+		'The red player is the computer: the engine’s melee brain gathers, builds, trains and sends waves at your base, seeing only what its side sees. Defend with what you have, train more, or look in on its base.',
+	tags: ['ai', 'computer', 'opponent', 'brain', 'bot', 'enemy', 'waves', 'skirmish', 'melee'],
+	map: () => exampleField({ name: 'Skirmish', size: 64, players: 2 }),
+	start: (world) => layOut(world),
+	source: ['examples/rts/ai.ts', 'examples/rts/base.ts', 'examples/rts/data.ts', 'examples/rts/looks.ts']
+}

package/starters/examples/src/examples/rts/airlift.ts

@@ -0,0 +1,43 @@
+/**
+ * A zeppelin over a cliff wall: a squad below the wall cannot walk up it (it has no ramp), so they board a zeppelin,
+ * which flies up over the cliff and lets them out on the plateau. A flying transport is a unit type with `flying` and
+ * `transport`: its passengers walk under it to get in, and get out on the ground nearest it
+ */
+import { defineCommand, type World } from '@v12-engine/engine'
+import { PLAYER, UNIT } from '../common/units'
+import type { ExampleDef } from '../define'
+import { clear } from './base'
+import { CARRY, route } from './carry'
+import { RTS } from './data'
+import { edgeAt, plateauMap } from './waterside'
+
+/** Where the zeppelin waits over the squad, where it flies to over the plateau, and where it lets them out up there */
+const MOOR = { x: 15, z: 20 }
+const ACROSS = { x: edgeAt(20) + 7, z: 20 }
+const LAND = { x: edgeAt(20) + 8, z: 20 }
+
+/** The squad below the wall, the zeppelin hanging over them, and a gold mine up on the plateau out of their reach */
+export function layOutAirlift(world: World): void {
+	clear(world)
+	world.setState(route, { moor: MOOR, across: ACROSS, land: LAND })
+	world.spawn(CARRY.zeppelin, { at: MOOR, owner: PLAYER, facing: Math.PI / 2 })
+	const squad = [UNIT.footman, UNIT.footman, UNIT.footman, UNIT.archer, UNIT.archer, UNIT.mage]
+	squad.forEach((type, i) =>
+		world.spawn(type, { at: { x: 9.5 + Math.floor(i / 3) * 1.8, z: 18.2 + (i % 3) * 1.8 }, owner: PLAYER, facing: Math.PI / 2 })
+	)
+	world.spawn(RTS.goldmine, { at: { x: edgeAt(20) + 13, z: 26 }, owner: 0 })
+}
+
+export const resetAirlift = defineCommand('rts.resetAirlift', {}, (world) => layOutAirlift(world))
+
+export const airlift: ExampleDef = {
+	id: 'rts-zeppelin',
+	category: 'rts',
+	title: 'A zeppelin over a cliff',
+	summary:
+		'Nothing on foot gets up the cliff wall. Board the squad onto the zeppelin, fly it over the wall and unload on the plateau, or by hand: right-click the zeppelin with your units, then select it and right-click up top.',
+	tags: ['transport', 'zeppelin', 'airship', 'flying', 'air', 'board', 'load', 'unload', 'cargo', 'cliff', 'plateau', 'drop'],
+	map: plateauMap,
+	start: (world) => layOutAirlift(world),
+	source: ['examples/rts/airlift.ts', 'examples/rts/carry.ts', 'examples/rts/waterside.ts', 'examples/rts/looks.ts']
+}

package/starters/examples/src/examples/rts/base.ts

@@ -0,0 +1,129 @@
+/**
+ * What the RTS examples share on the rules' side: a base laid out (a hall, its gold mine, a wood behind it, workers),
+ * a player's purse set, and commands the cards send to train, build and gather as a player's clicks would
+ */
+import { defineCommand, defineTimer, type Entity, string, type Vec2, type World, exactMath } from '@v12-engine/engine'
+import { RTS } from './data'
+
+/**
+ * A player's live entities, of a type or all. Of every entity (`world.entities`): what is no player's and only
+ * stands there (a mine, a tree, a shop) is scenery, kept out of `world.units`, the entities that act
+ */
+export const ownedOf = (world: World, player: number, type?: string): Entity[] =>
+	[...world.entities.values()].filter((each) => each.alive && each.owner === player && (type === undefined || each.def.id === type))
+
+/** Takes everything away but the trees: what an example laid out again starts from */
+export function clear(world: World): void {
+	for (const entity of [...world.entities.values()]) if (entity.alive && entity.def.id !== RTS.tree) world.kill(entity, undefined, false, 'removed')
+}
+
+/** Sets what a player has of each resource */
+export function purse(world: World, player: number, gold: number, lumber: number): void {
+	const resources = world.player(player).resources
+	resources.gold = gold
+	resources.lumber = lumber
+}
+
+/** Where a base's parts stand round its hall: the mine to the west, the wood to the north */
+export interface Base {
+	hall: Entity
+	mine: Entity
+	workers: Entity[]
+}
+
+/**
+ * A base at `at`: a town hall (or a keep), a gold mine 9 cells west of it, a wood of trees north of the two, and
+ * `workers` peasants by the hall, of `player`'s. The trees and the mine are the neutral player's: anyone may gather them
+ */
+export function base(world: World, player: number, at: Vec2, options: { workers?: number; hall?: string; wood?: boolean } = {}): Base {
+	const { workers = 5, hall: hallType = RTS.townhall, wood = true } = options
+	const hall = world.spawn(hallType, { at, owner: player })
+	const mine = world.spawn(RTS.goldmine, { at: { x: at.x - 9, z: at.z }, owner: 0 })
+	if (wood) forest(world, { x: at.x - 10, z: at.z + 6 }, 16, 3)
+	const peasants = Array.from({ length: workers }, (_, i) =>
+		world.spawn(RTS.peasant, { at: { x: at.x - 3 + (i % 3) * 1.2, z: at.z - 3 - Math.floor(i / 3) * 1.2 }, owner: player })
+	)
+	return { hall, mine, workers: peasants }
+}
+
+/** A wood: `width` by `depth` trees from `from`, a cell apart, some left out at random so its edge is ragged */
+export function forest(world: World, from: Vec2, width: number, depth: number): void {
+	for (let z = 0; z < depth; z++)
+		for (let x = 0; x < width; x++) {
+			const at = { x: Math.floor(from.x) + x + 0.5, z: Math.floor(from.z) + z + 0.5 }
+			if (z === depth - 1 && world.rng.next() < 0.4) continue
+			// a tree there already (a wood laid out again keeps its trees): left as it is
+			if (
+				world.spatial
+					.queryStatic(at.x, at.z, 0.1)
+					.some((each) => each.def.id === RTS.tree && Math.abs(each.pos.x - at.x) + Math.abs(each.pos.z - at.z) < 0.1)
+			)
+				continue
+			world.spawn(RTS.tree, { at, owner: 0 })
+		}
+}
+
+/** Sends workers to gather: the first `toGold` to the mine, the rest to the nearest tree each */
+export function gather(world: World, workers: Entity[], mine: Entity, toGold: number): void {
+	const trees = ownedOf(world, 0, RTS.tree)
+	workers.forEach((worker, i) => {
+		if (i < toGold) return worker.order('harvest', mine)
+		const nearest = trees.reduce<Entity | undefined>(
+			(best, tree) =>
+				!best ||
+				exactMath.hypot(tree.pos.x - worker.pos.x, tree.pos.z - worker.pos.z) < exactMath.hypot(best.pos.x - worker.pos.x, best.pos.z - worker.pos.z)
+					? tree
+					: best,
+			undefined
+		)
+		if (nearest) worker.order('harvest', nearest)
+	})
+}
+
+/**
+ * Puts a player's idle peasants to work, `count` of them at most: `toGold` on the gold of the mine nearest them, the
+ * rest in the wood
+ */
+export function putToWork(world: World, player: number, toGold: number, count = Infinity): void {
+	const idle = ownedOf(world, player, RTS.peasant)
+		.filter((each) => !each.orders.length)
+		.slice(0, count)
+	const [first] = idle
+	if (!first) return
+	const away = (each: Entity) => exactMath.hypot(each.pos.x - first.pos.x, each.pos.z - first.pos.z)
+	const [mine] = ownedOf(world, 0, RTS.goldmine).sort((a, b) => away(a) - away(b))
+	if (mine) gather(world, idle, mine, toGold)
+}
+
+/**
+ * `putToWork` a moment after the world starts. Not at once: an order on a mine or a tree is refused while its side
+ * has not seen it yet, and the world works out what each side sees as its first tick ends
+ */
+export const toWork = defineTimer<{ player: number; toGold: number; count: number }>({
+	id: 'rts.toWork',
+	run: (world, { player, toGold, count }) => putToWork(world, player, toGold, count)
+})
+
+/** Puts the player's peasants to work shortly: see `toWork` */
+export const startWork = (world: World, player: number, toGold: number, count = 99): void =>
+	void world.timers.after(0.2, toWork, { player, toGold, count })
+
+/**
+ * Queues a unit type at the player's least busy building that trains it, as the train button of its card does (the
+ * engine's `train` command): paid for as it is queued, refused when the player is short of it or of supply
+ */
+export const train = defineCommand('rts.train', { unitType: string }, (world, player, { unitType }) => {
+	const buildings = ownedOf(world, player).filter((each) => each.def.trains?.includes(unitType))
+	if (buildings.length) world.issue({ type: 'train', player, buildings: buildings.map((each) => each.id), unitType })
+})
+
+/** Researches an upgrade at the player's building that researches it, as its card's button does */
+export const research = defineCommand('rts.research', { upgrade: string }, (world, player, { upgrade }) => {
+	const buildings = ownedOf(world, player).filter((each) => each.def.researches?.includes(upgrade))
+	if (buildings.length) world.issue({ type: 'research', player, buildings: buildings.map((each) => each.id), upgrade })
+})
+
+/** Every idle worker of the player's back to work: half to the gold, half to the wood */
+export const backToWork = defineCommand('rts.backToWork', {}, (world, player) => {
+	putToWork(world, player, Math.ceil(ownedOf(world, player, RTS.peasant).filter((each) => !each.orders.length).length / 2))
+})

package/starters/examples/src/examples/rts/build.ts

@@ -0,0 +1,65 @@
+/**
+ * Building: a worker `builds` building types. Told to build one at a spot, it walks there, the site is laid out and
+ * paid for, and it hammers it up over the building's `buildTime`, the building rising as it goes. Placing one yourself
+ * is the worker's card: select a peasant, pick a building, click the ground (green where it fits, red where it does not)
+ */
+import { defineCommand, oneOf, type World } from '@v12-engine/engine'
+import { PLAYER } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+import { base, clear, ownedOf, purse, startWork } from './base'
+import { RTS } from './data'
+
+/** What the card's buttons build, and the spots each goes on in turn: a row of farms, a barracks, towers either side */
+const SPOTS = {
+	[RTS.farm]: [
+		{ x: 20, z: 16 },
+		{ x: 23, z: 16 },
+		{ x: 26, z: 16 },
+		{ x: 29, z: 16 }
+	],
+	[RTS.barracks]: [
+		{ x: 34.5, z: 22.5 },
+		{ x: 34.5, z: 27.5 }
+	],
+	[RTS.tower]: [
+		{ x: 22, z: 11 },
+		{ x: 30, z: 11 }
+	]
+} as const
+
+/** The base with three peasants, two of them at work, and enough to build all the card has */
+function layOut(world: World): void {
+	clear(world)
+	purse(world, PLAYER, 1500, 800)
+	// four peasants: two at work, one on the gold and one in the wood, and two idle by the hall, the builders
+	base(world, PLAYER, { x: 26, z: 24 }, { workers: 4 })
+	startWork(world, PLAYER, 1, 2)
+}
+
+/**
+ * A peasant told to build `unitType` on its next spot: the one nearest, idle ones first. A barracks must stand before a
+ * tower can (`requires`); short of gold or lumber, nothing is laid out and the player is told why
+ */
+export const build = defineCommand('rts.build', { unitType: oneOf(RTS.farm, RTS.barracks, RTS.tower) }, (world, player, { unitType }) => {
+	const spots = SPOTS[unitType]
+	const spot = spots[ownedOf(world, player, unitType).length]
+	// the builders: the two that do not gather, a barracks for the one and the rest for the other. What it is told
+	// while it builds waits its turn (`queue`)
+	const builders = ownedOf(world, player, RTS.peasant).filter((each) => each.orders[0]?.type !== 'harvest')
+	const builder = builders[unitType === RTS.barracks ? 1 : 0] ?? builders[0]
+	if (spot && builder) builder.order('build', { unitType, point: spot }, { queue: true })
+})
+
+export const resetBuild = defineCommand('rts.resetBuild', {}, (world) => layOut(world))
+
+export const building: ExampleDef = {
+	id: 'rts-build',
+	category: 'rts',
+	title: 'Building a base',
+	summary:
+		'Peasants walk to a spot, lay out a building and hammer it up as it rises. Press a button to build a farm, a barracks or a tower, or select a peasant and place one yourself from its card.',
+	tags: ['build', 'construction', 'placement', 'worker', 'base', 'farm', 'barracks', 'tower'],
+	map: () => exampleField({ name: 'Building site', size: 44 }),
+	start: (world) => layOut(world),
+	source: ['examples/rts/build.ts', 'examples/rts/base.ts', 'examples/rts/data.ts', 'examples/rts/looks.ts']
+}

package/starters/examples/src/examples/rts/camps.ts

@@ -0,0 +1,36 @@
+/**
+ * Neutral camps the RTS examples share: creeps that guard a spot (with the heroes pack), for the hero to hunt and the
+ * army to clear. They are the map's (`GameMap.camps`): a map with camps has the creeps' player, and its world puts them
+ * down as it is made. Laid out again, a camp is brought back where it was (`respawnCamp`)
+ */
+import { campsOf, type GameMap, MAP_CREEPS, respawnCamp, spawnCamp, type Vec2, type World } from '@v12-engine/engine'
+
+/** A camp: its name, where it stands and who is in it */
+export interface CampSpot {
+	name: string
+	at: Vec2
+	types: string[]
+}
+
+/** The map with the camps on it, by name */
+export function withCamps(map: GameMap, spots: readonly CampSpot[]): GameMap {
+	map.camps.push(...spots.map((spot, i) => ({ id: i + 1, name: spot.name, x: spot.at.x, z: spot.at.z, units: [...spot.types] })))
+	return map
+}
+
+/** The camps, each where it was: new ones the first time, the same brought back afterwards (what stood there taken away first) */
+export function camps(world: World, spots: readonly CampSpot[]): void {
+	const all = campsOf(world)
+	for (const spot of spots) {
+		const camp = all.find((each) => each.name === spot.name)
+		if (!camp) {
+			spawnCamp(world, MAP_CREEPS, spot.at, spot.types).name = spot.name
+			continue
+		}
+		for (const id of camp.members) {
+			const creep = world.get(id)
+			if (creep?.alive) world.kill(creep, undefined, false, 'removed')
+		}
+		respawnCamp(world, camp)
+	}
+}

package/starters/examples/src/examples/rts/carry.ts

@@ -0,0 +1,103 @@
+/**
+ * What carries others (`UnitTypeDef.transport`): a ship on the water, a zeppelin in the air, a tower soldiers go into.
+ * Units of its side get in when told to (a right-click on it: the `board` order), are out of the world while inside, and
+ * get out on the land nearest it (the `unload` order, the card's Unload button). What a ship or a zeppelin carries dies
+ * with it; what a building holds comes out when it falls. The examples' cards send `carry`, as a player's clicks would
+ */
+import { defineCommand, defineComponent, type Entity, oneOf, type UnitTypeDef, type Vec2, type World } from '@v12-engine/engine'
+import { UNIT } from '../common/units'
+import { ownedOf } from './base'
+
+/** The transports' ids */
+export const CARRY = { ship: 'rtsTransportShip', zeppelin: 'rtsZeppelin', tower: 'rtsGarrisonTower' } as const
+
+/** Who rides: the shared units that walk */
+const riders: readonly string[] = [UNIT.footman, UNIT.archer, UNIT.mage, UNIT.knight]
+
+/** A transport ship: it goes on deep water and nowhere else (`naval`), and takes eight on board */
+export const ship: UnitTypeDef = {
+	id: CARRY.ship,
+	name: 'Transport Ship',
+	kind: 'unit',
+	radius: 1.6,
+	naval: true,
+	transport: { capacity: 8, takes: (unit) => riders.includes(unit.id) },
+	stats: { health: 900, armor: 10, moveSpeed: 4.5 },
+	sight: 11,
+	// a ship comes about slowly
+	turnRate: 2.2
+}
+
+/** A zeppelin: it flies (`flying`), over cliffs and water alike, and takes eight up with it */
+export const zeppelin: UnitTypeDef = {
+	id: CARRY.zeppelin,
+	name: 'Zeppelin',
+	kind: 'unit',
+	radius: 1.5,
+	flying: true,
+	transport: { capacity: 8, takes: (unit) => riders.includes(unit.id) },
+	stats: { health: 600, armor: 5, moveSpeed: 4.2 },
+	sight: 12,
+	turnRate: 1.8
+}
+
+/**
+ * A tower soldiers go into: four of them, out of reach inside. It shoots only while someone is in it, and each one
+ * inside adds 12 to its arrows (`transport.armed`)
+ */
+export const garrisonTower: UnitTypeDef = {
+	id: CARRY.tower,
+	name: 'Garrison Tower',
+	kind: 'building',
+	radius: 1,
+	footprint: { w: 2, d: 2 },
+	transport: { capacity: 4, takes: (unit) => riders.includes(unit.id), armed: 12 },
+	stats: { health: 1800, attackDamage: 4, attackSpeed: 1.1, attackRange: 9, armor: 30 },
+	sight: 13,
+	attacks: [{ damagePoint: 0.3, acquisitionRange: 9, projectileSpeed: 26, targets: ['ground', 'air'] }]
+}
+
+export const carryUnits: UnitTypeDef[] = [ship, zeppelin, garrisonTower]
+
+/**
+ * Where an example's transport goes, kept in the world (a component of its state) as each example lays itself out:
+ * where it waits for its passengers, where it goes across to, and where it lets them out over there
+ */
+export interface Route {
+	/** Where it waits by the passengers' side: on the water by the near bank, in the air over them */
+	moor: Vec2
+	/** Where it goes across to */
+	across: Vec2
+	/** Where it lets them out on the far side */
+	land: Vec2
+}
+
+export const route = defineComponent<Route>({
+	id: 'rts.route',
+	default: () => ({ moor: { x: 0, z: 0 }, across: { x: 0, z: 0 }, land: { x: 0, z: 0 } })
+})
+
+/** The player's transport: their ship, zeppelin or tower */
+export const transportOf = (world: World, player: number): Entity | undefined =>
+	ownedOf(world, player).find((each) => each.def.transport && !each.hidden)
+
+/** The player's units that could get in: what walks and is not inside already */
+export const ridersOf = (world: World, player: number): Entity[] =>
+	ownedOf(world, player).filter((each) => !each.hidden && riders.includes(each.def.id))
+
+/**
+ * What the cards send: everyone gets in (`board`), the transport goes across or back (`move`), lets them out on the
+ * far side (`unload` at a point: it goes there first) or where it is, or it is sunk (killed, and its passengers with it)
+ */
+export const carry = defineCommand('rts.carry', { step: oneOf('board', 'across', 'unload', 'back', 'sink') }, (world, player, { step }) => {
+	const transport = transportOf(world, player)
+	if (!transport) return
+	const { across, land, moor } = world.state(route)
+	const order = (entities: Entity[], init: Record<string, unknown>) =>
+		world.issue({ type: 'order', player, entities: entities.map((each) => each.id), order: init as never })
+	if (step === 'board') order(ridersOf(world, player), { type: 'board', target: transport.id })
+	else if (step === 'across') order([transport], { type: 'move', point: across })
+	else if (step === 'back') order([transport], { type: 'move', point: moor })
+	else if (step === 'unload') order([transport], transport.isStructure ? { type: 'unload' } : { type: 'unload', point: land })
+	else world.kill(transport)
+})