@v12-engine/create 0.1.0 → 0.4.0

package/starters/examples/src/examples/custom-fx/ribbons.look.ts

@@ -0,0 +1,151 @@
+/**
+ * Ribbons and orbits, on the client's side: effects whose parts go round where the effect is (`orbit`: how far out,
+ * turns a second, how high, a lean, a figure, a climb) or along a way of their own (`path`), each leaving a ribbon
+ * (`trail`) and sparkles. They are played on the mage and follow him
+ */
+import type { FxDef, FxHandle, FxPart, GameClientApi, ParticleDef } from '@v12-engine/client'
+import { button, type ExampleLook, select } from '../../shell/look'
+import { UNIT } from '../common/units'
+import { aim, idsOf } from '../fx/stage'
+import { RIBBONS_AT } from './ribbons'
+
+/** Sparkles left by a part as it goes: a few soft dots, drifting a little */
+const sparkles = (color: string): ParticleDef => ({
+	rate: 40,
+	lifetime: [0.4, 0.9],
+	speed: [0, 0.3],
+	size: [0.18, 0],
+	color: [color, '#ffffff'],
+	texture: 'flare'
+})
+
+/** A braid: three strands in a figure of eight, a third of a turn apart, climbing from the feet over the head and again */
+const braid: FxDef = {
+	length: 6,
+	parts: ['#6ff2ff', '#c48bff', '#ff8fd8'].flatMap((color, i): FxPart[] => {
+		const orbit = { radius: 0.7, figure: 2, depth: 0.45, phase: i / 3, turns: 1.1, climb: 1.6, height: [0.1, 2.3] as const }
+		return [
+			{ orbit, trail: { color, width: 0.22, soft: true, blend: 'add', time: 1.2, gap: 0.9, linger: 0.8 } },
+			{ orbit, particles: sparkles(color) }
+		]
+	})
+}
+
+/** A spiral: two strands climbing round and round, closing in as they rise */
+const spiral: FxDef = {
+	length: 4,
+	parts: ['#ffd76a', '#ff7a2a'].flatMap((color, i): FxPart[] => {
+		const orbit = {
+			radius: [
+				[0, 1.3],
+				[1, 0.2]
+			] as const,
+			turns: 1.4,
+			phase: i / 2,
+			height: [
+				[0, 0.1],
+				[1, 3]
+			] as const
+		}
+		return [
+			{ orbit, trail: { color, width: 0.3, soft: true, blend: 'add', time: 0.8, strength: [1, 0] } },
+			{ orbit, particles: sparkles(color) }
+		]
+	})
+}
+
+/** A figure of eight lying flat round the feet, turning as a whole */
+const eight: FxDef = {
+	length: 5,
+	parts: [
+		{
+			orbit: { radius: 1.6, figure: 2, depth: 0.6, turns: 0.7, spin: 0.3, height: 0.4 },
+			trail: { color: '#7dff9a', width: 0.35, soft: true, blend: 'add', time: 1.4 }
+		},
+		{
+			orbit: { radius: 1.6, figure: 2, depth: 0.6, turns: 0.7, spin: 0.3, height: 0.4, phase: 0.5 },
+			trail: { color: '#d8ffe0', width: 0.15, soft: true, blend: 'add', time: 1.4 }
+		}
+	]
+}
+
+/** A halo: six motes round the head, leaning, bobbing, each with its ribbon */
+const halo: FxDef = {
+	length: 5,
+	parts: Array.from({ length: 6 }, (_, i): FxPart => ({
+		orbit: { radius: 0.55, turns: 0.9, phase: i / 6, height: 2.2, wobble: 0.25, bob: 0.08, bobs: 3 },
+		trail: { color: '#fff2b0', width: 0.08, blend: 'add', soft: true, time: 0.5 }
+	}))
+}
+
+/** Comets on a way of their own (`path`): out from the chest, over in an arc, down at a point ahead, four of them in turn */
+const comets: FxDef = {
+	length: 3.5,
+	parts: [0, 1, 2, 3].map((i): FxPart => ({
+		at: i * 0.35,
+		for: 1.6,
+		path: (age, life) => {
+			const t = Math.min(age / life, 1)
+			const side = (i % 2 ? 1 : -1) * (1 + i * 0.4)
+			// up and over in an arc to a spot five cells ahead, swinging out to one side
+			return [Math.sin(t * Math.PI) * side, 1.3 + Math.sin(t * Math.PI) * 2.5 - t * 1.2, t * 5]
+		},
+		trail: { color: ['#ff9a3a', '#ffd23c', '#ff5aa0', '#8fd8ff'][i], width: 0.28, blend: 'add', soft: true, time: 0.6, taper: true },
+		particles: { rate: 60, lifetime: [0.3, 0.6], size: [0.25, 0], speed: [0.2, 0.8], color: ['#ffffff', '#ffb050'], texture: 'spark' }
+	}))
+}
+
+/** The ribbons of this example, taken into the game's view */
+export const ribbonsFx: Record<string, FxDef> = {
+	'customFx.braid': braid,
+	'customFx.spiral': spiral,
+	'customFx.eight': eight,
+	'customFx.halo': halo,
+	'customFx.comets': comets
+}
+
+const NAMES: Record<string, string> = {
+	'A braid': 'customFx.braid',
+	'A spiral': 'customFx.spiral',
+	'A figure of eight': 'customFx.eight',
+	'A halo': 'customFx.halo',
+	'Comets on a path': 'customFx.comets'
+}
+
+let chosen = 'customFx.braid'
+let playing: FxHandle | undefined
+
+/** Plays the chosen ribbons on the mage, the last let finish */
+function play(client: GameClientApi): void {
+	const [mage] = idsOf(client, UNIT.mage)
+	if (mage === undefined) return
+	playing?.stop()
+	playing = client.fx.play(chosen, { on: mage })
+}
+
+export const ribbonsLook: ExampleLook = {
+	controls: [
+		select(
+			'Ribbons',
+			Object.keys(NAMES),
+			'A braid',
+			(client, name) => {
+				chosen = NAMES[name] ?? chosen
+				play(client)
+			},
+			'Which ribbons play round the mage: each a few lines of data'
+		),
+		button('Play', (client) => play(client), 'Plays the chosen ribbons on the mage again')
+	],
+	ready: (client) => {
+		chosen = 'customFx.braid'
+		aim(client, { x: RIBBONS_AT.x, z: RIBBONS_AT.z + 1 }, 14, 0.5)
+		const first = window.setTimeout(() => play(client), 300)
+		const again = window.setInterval(() => playing?.alive || play(client), 1000)
+		return () => {
+			window.clearTimeout(first)
+			window.clearInterval(again)
+			playing?.stop({ mode: 'at-once' })
+		}
+	}
+}

package/starters/examples/src/examples/custom-fx/ribbons.ts

@@ -0,0 +1,22 @@
+/**
+ * Ribbons and orbits, on the rules' side: a mage to wind them round. The ribbons are the view's effects
+ * (`./ribbons.look.ts`)
+ */
+import { PLAYER, UNIT } from '../common/units'
+import type { ExampleDef } from '../define'
+
+export const RIBBONS_AT = { x: 24, z: 24 }
+
+export const ribbons: ExampleDef = {
+	id: 'custom-fx-ribbons',
+	category: 'custom-fx',
+	title: 'Ribbons and orbits',
+	summary:
+		'Parts that go round where the effect is (`orbit`) leave a ribbon behind them (`trail`): a braid of three strands, a spiral climbing, a figure of eight, a halo, comets on their own path. Pick one; each is a few lines of data.',
+	tags: ['trail', 'ribbon', 'orbit', 'path', 'FxTrail', 'FxOrbit', 'spiral', 'braid'],
+	environment: 'dusk',
+	start: (world) => {
+		world.spawn(UNIT.mage, { at: RIBBONS_AT, owner: PLAYER })
+	},
+	source: ['examples/custom-fx/ribbons.ts', 'examples/custom-fx/ribbons.look.ts']
+}

package/starters/examples/src/examples/custom-fx/shader.ts

@@ -0,0 +1,42 @@
+/**
+ * A shader material of your own, for either renderer: Babylon's `ShaderMaterial` with its vertex and fragment shaders
+ * written twice, in GLSL for WebGL and in WGSL for WebGPU, the one the engine draws with taken. Client code: only looks
+ * files import it
+ */
+import { ShaderStore } from '@babylonjs/core/Engines/shaderStore.js'
+import { ShaderLanguage } from '@babylonjs/core/Materials/shaderLanguage.js'
+import { ShaderMaterial } from '@babylonjs/core/Materials/shaderMaterial.js'
+import type { Scene } from '@babylonjs/core/scene.js'
+
+/** A shader in both languages: its vertex and fragment code in each */
+export interface TwoShaders {
+	glsl: { vertex: string; fragment: string }
+	wgsl: { vertex: string; fragment: string }
+}
+
+/**
+ * A material drawn by the shaders of `name`, kept in Babylon's store the first time: `uniforms` are what the code
+ * sets (`setFloat`, `setVector3`...) besides the matrices Babylon sets itself (`world`, `worldViewProjection`)
+ */
+export function shaderMaterial(
+	name: string,
+	scene: Scene,
+	shaders: TwoShaders,
+	uniforms: readonly string[],
+	attributes = ['position', 'normal', 'uv']
+): ShaderMaterial {
+	const webgpu = scene.getEngine().isWebGPU
+	const language = webgpu ? ShaderLanguage.WGSL : ShaderLanguage.GLSL
+	const store = ShaderStore.GetShadersStore(language)
+	const code = webgpu ? shaders.wgsl : shaders.glsl
+	if (!store[`${name}VertexShader`]) {
+		store[`${name}VertexShader`] = code.vertex
+		store[`${name}FragmentShader`] = code.fragment
+	}
+	return new ShaderMaterial(
+		name,
+		scene,
+		{ vertex: name, fragment: name },
+		{ attributes, uniforms: ['world', 'worldViewProjection', ...uniforms], needAlphaBlending: true, shaderLanguage: language }
+	)
+}

package/starters/examples/src/examples/custom-fx/shield.look.ts

@@ -0,0 +1,226 @@
+/**
+ * An energy shield, on the client's side: a renderer of the game's own (`GameView.renderers`, a `RendererFactory`),
+ * given the render kit: it puts a sphere on every warden, drawn by a shader of its own (`./shader.ts`), places it where
+ * the warden is drawn every frame (`kit.drawn`), and hears every blow the screen is told of (`sync`, its `events`): a
+ * blow on a warden starts a ripple on the bubble, from the side it came from
+ */
+import { Constants } from '@babylonjs/core/Engines/constants.js'
+import type { ShaderMaterial } from '@babylonjs/core/Materials/shaderMaterial.js'
+import { Color3 } from '@babylonjs/core/Maths/math.color.js'
+import { Vector3, Vector4 } from '@babylonjs/core/Maths/math.vector.js'
+import { CreateSphere } from '@babylonjs/core/Meshes/Builders/sphereBuilder.js'
+import type { Mesh } from '@babylonjs/core/Meshes/mesh.js'
+import type { RendererFactory, UnitLook } from '@v12-engine/client'
+import { type ExampleLook, select } from '../../shell/look'
+import { character, hold, person } from '../common/looks'
+import { aim } from '../fx/stage'
+import { type TwoShaders, shaderMaterial } from './shader'
+import { WARDEN, WARDEN_AT } from './shield'
+
+/** The warden: the knight, shield and sword */
+export const wardenLook: UnitLook = {
+	height: 2,
+	model: character('knight', 0.8, { hold: [hold('sword_1handed'), hold('shield_badge_color', 'l')] }),
+	shapes: person(2, [0.4, 0.6, 1])
+}
+
+/** How many ripples at once: the oldest gives way */
+const RIPPLES = 4
+
+/**
+ * The bubble's shaders. Bright where it is seen edge on (a fresnel), a grid of lines crawling up it, and up to four
+ * ripples: each a ring spreading from where a blow struck (a direction from the middle, `xyz`), as old as `w` (0 to 1,
+ * none below 0)
+ */
+const SHIELD: TwoShaders = {
+	glsl: {
+		vertex: `precision highp float;
+attribute vec3 position;
+attribute vec3 normal;
+uniform mat4 world;
+uniform mat4 worldViewProjection;
+varying vec3 vPositionW;
+varying vec3 vNormalW;
+varying vec3 vLocal;
+void main() {
+	vec4 p = vec4(position, 1.0);
+	gl_Position = worldViewProjection * p;
+	vPositionW = (world * p).xyz;
+	vNormalW = normalize((world * vec4(normal, 0.0)).xyz);
+	vLocal = normalize(position);
+}`,
+		fragment: `precision highp float;
+uniform vec3 eye;
+uniform vec3 color;
+uniform float time;
+uniform vec4 hit0;
+uniform vec4 hit1;
+uniform vec4 hit2;
+uniform vec4 hit3;
+varying vec3 vPositionW;
+varying vec3 vNormalW;
+varying vec3 vLocal;
+float ripple(vec4 hit, vec3 at) {
+	if (hit.w < 0.0) return 0.0;
+	float away = acos(clamp(dot(at, hit.xyz), -1.0, 1.0));
+	float ring = away - hit.w * 2.6;
+	return exp(-ring * ring * 60.0) * (1.0 - hit.w) * 1.6 + exp(-away * away * 12.0) * (1.0 - hit.w) * 0.8 * step(hit.w, 0.25);
+}
+void main() {
+	vec3 toEye = normalize(eye - vPositionW);
+	float rim = pow(1.0 - abs(dot(normalize(vNormalW), toEye)), 2.4);
+	float around = atan(vLocal.z, vLocal.x);
+	float up = vLocal.y;
+	float grid = max(step(0.93, abs(sin(around * 9.0))), step(0.9, abs(sin(up * 12.0 - time * 1.5))));
+	float waves = ripple(hit0, vLocal) + ripple(hit1, vLocal) + ripple(hit2, vLocal) + ripple(hit3, vLocal);
+	float shine = 0.05 + rim * 0.85 + grid * (0.08 + rim * 0.25) + waves;
+	vec3 lit = color * shine + vec3(1.0) * waves * 0.5;
+	gl_FragColor = vec4(lit, clamp(shine, 0.0, 1.0));
+}`
+	},
+	wgsl: {
+		vertex: `attribute position: vec3f;
+attribute normal: vec3f;
+uniform world: mat4x4f;
+uniform worldViewProjection: mat4x4f;
+varying vPositionW: vec3f;
+varying vNormalW: vec3f;
+varying vLocal: vec3f;
+@vertex
+fn main(input: VertexInputs) -> FragmentInputs {
+	let p = vec4f(vertexInputs.position, 1.0);
+	vertexOutputs.position = uniforms.worldViewProjection * p;
+	vertexOutputs.vPositionW = (uniforms.world * p).xyz;
+	vertexOutputs.vNormalW = normalize((uniforms.world * vec4f(vertexInputs.normal, 0.0)).xyz);
+	vertexOutputs.vLocal = normalize(vertexInputs.position);
+}`,
+		fragment: `uniform eye: vec3f;
+uniform color: vec3f;
+uniform time: f32;
+uniform hit0: vec4f;
+uniform hit1: vec4f;
+uniform hit2: vec4f;
+uniform hit3: vec4f;
+varying vPositionW: vec3f;
+varying vNormalW: vec3f;
+varying vLocal: vec3f;
+fn ripple(hit: vec4f, at: vec3f) -> f32 {
+	if (hit.w < 0.0) { return 0.0; }
+	let away = acos(clamp(dot(at, hit.xyz), -1.0, 1.0));
+	let ring = away - hit.w * 2.6;
+	return exp(-ring * ring * 60.0) * (1.0 - hit.w) * 1.6 + exp(-away * away * 12.0) * (1.0 - hit.w) * 0.8 * step(hit.w, 0.25);
+}
+@fragment
+fn main(input: FragmentInputs) -> FragmentOutputs {
+	let toEye = normalize(uniforms.eye - fragmentInputs.vPositionW);
+	let rim = pow(1.0 - abs(dot(normalize(fragmentInputs.vNormalW), toEye)), 2.4);
+	let local = fragmentInputs.vLocal;
+	let around = atan2(local.z, local.x);
+	let grid = max(step(0.93, abs(sin(around * 9.0))), step(0.9, abs(sin(local.y * 12.0 - uniforms.time * 1.5))));
+	let waves = ripple(uniforms.hit0, local) + ripple(uniforms.hit1, local) + ripple(uniforms.hit2, local) + ripple(uniforms.hit3, local);
+	let shine = 0.05 + rim * 0.85 + grid * (0.08 + rim * 0.25) + waves;
+	let lit = uniforms.color * shine + vec3f(1.0) * waves * 0.5;
+	fragmentOutputs.color = vec4f(lit, clamp(shine, 0.0, 1.0));
+}`
+	}
+}
+
+/** The bubble's colour, as the card sets it */
+const shieldColor = new Color3(0.35, 0.75, 1)
+
+/** The renderer: a bubble on each warden, its ripples, told of every blow */
+const shieldRenderer: RendererFactory = (kit) => {
+	const bubbles = new Map<number, { mesh: Mesh; material: ShaderMaterial; hits: Vector4[]; next: number }>()
+	let time = 0
+	const bubbleOf = (id: number) => {
+		let bubble = bubbles.get(id)
+		if (bubble) return bubble
+		const mesh = CreateSphere('customFx.shield', { diameter: 2.6, segments: 48 }, kit.scene)
+		const material = shaderMaterial(
+			'customFxShield',
+			kit.scene,
+			SHIELD,
+			['eye', 'color', 'time', 'hit0', 'hit1', 'hit2', 'hit3'],
+			['position', 'normal']
+		)
+		// light added, not painted: what is behind shows through
+		material.alphaMode = Constants.ALPHA_ADD
+		material.backFaceCulling = false
+		mesh.material = material
+		mesh.isPickable = false
+		bubble = { mesh, material, hits: Array.from({ length: RIPPLES }, () => new Vector4(0, 1, 0, -1)), next: 0 }
+		bubbles.set(id, bubble)
+		return bubble
+	}
+	return {
+		sync(changes) {
+			for (const event of changes.events) {
+				if (event.type !== 'damage') continue
+				const bubble = bubbles.get(event.id)
+				const struck = kit.drawn(event.id)
+				const from = event.source !== undefined ? kit.drawn(event.source) : undefined
+				if (!bubble || !struck) continue
+				// the side the blow came from, from the bubble's middle; straight at the front where the shooter is not seen
+				const way = from ? from.position.subtract(struck.position).addInPlaceFromFloats(0, 0.6, 0) : new Vector3(0, 0.3, 1)
+				way.normalize()
+				bubble.hits[bubble.next]!.set(way.x, way.y, way.z, 0)
+				bubble.next = (bubble.next + 1) % RIPPLES
+			}
+		},
+		frame(_alpha, dt) {
+			time += dt
+			for (const entity of kit.state.entities.values()) if (entity.def.id === WARDEN && entity.health > 0) bubbleOf(entity.id)
+			const eye = kit.scene.activeCamera?.globalPosition ?? Vector3.Zero()
+			for (const [id, bubble] of bubbles) {
+				const drawn = kit.drawn(id)
+				if (!drawn || !kit.state.entities.has(id)) {
+					bubble.mesh.dispose()
+					bubble.material.dispose()
+					bubbles.delete(id)
+					continue
+				}
+				bubble.mesh.setEnabled(drawn.visible)
+				bubble.mesh.position.set(drawn.position.x, drawn.position.y + 1, drawn.position.z)
+				const { material, hits } = bubble
+				for (const hit of hits) if (hit.w >= 0) hit.w = hit.w + dt / 0.9 > 1 ? -1 : hit.w + dt / 0.9
+				material.setVector3('eye', eye)
+				material.setColor3('color', shieldColor)
+				material.setFloat('time', time)
+				hits.forEach((hit, i) => material.setVector4(`hit${i}`, hit))
+			}
+		},
+		dispose() {
+			for (const bubble of bubbles.values()) {
+				bubble.mesh.dispose()
+				bubble.material.dispose()
+			}
+			bubbles.clear()
+		}
+	}
+}
+
+const COLORS: Record<string, [number, number, number]> = {
+	Azure: [0.35, 0.75, 1],
+	Gold: [1, 0.75, 0.25],
+	Venom: [0.4, 1, 0.35],
+	Void: [0.75, 0.3, 1],
+	Blood: [1, 0.2, 0.25]
+}
+
+export const shieldLook: ExampleLook = {
+	// the renderer is this example's alone: laid over the game's renderers as it opens
+	view: (view) => ({ ...view, renderers: [...(view.renderers ?? []), shieldRenderer] }),
+	controls: [
+		select(
+			'Colour',
+			Object.keys(COLORS),
+			'Azure',
+			(_client, name) => shieldColor.set(...(COLORS[name] ?? COLORS.Azure!)),
+			'The colour of the bubble round the warden: the shader is handed it every frame'
+		)
+	],
+	ready: (client) => {
+		shieldColor.set(...COLORS.Azure!)
+		aim(client, WARDEN_AT, 19, 0.7)
+	}
+}

package/starters/examples/src/examples/custom-fx/shield.ts

@@ -0,0 +1,43 @@
+/**
+ * An energy shield, on the rules' side: a warden who takes the blows and heals them as fast, archers round him who
+ * shoot at him of themselves. The shield is the screen's: a renderer of the game's own that draws it with a shader of
+ * its own and is told of every blow (`./shield.look.ts`)
+ */
+import { exactMath } from '@v12-engine/engine'
+import type { Game } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+
+export const WARDEN = 'customFxWarden'
+export const WARDEN_AT = { x: 24, z: 24 }
+
+export const shield: ExampleDef = {
+	id: 'custom-fx-shield',
+	category: 'custom-fx',
+	title: 'An energy shield (a shader)',
+	summary:
+		"A bubble drawn by a shader of your own, GLSL and WGSL: bright at its rim, a grid crawling over it, and a ripple spreading from every arrow that strikes it. A renderer of the game's own places it on the warden and hears each blow. Change its colour; walk him about.",
+	tags: ['shader', 'ShaderMaterial', 'GLSL', 'WGSL', 'renderer', 'RendererFactory', 'shield', 'fresnel', 'ripple'],
+	environment: 'dusk',
+	map: () => exampleField({ name: 'Ring', players: 2 }),
+	start: (world) => {
+		world.spawn(WARDEN, { at: WARDEN_AT, owner: PLAYER })
+		for (let i = 0; i < 4; i++) {
+			const angle = (i / 4) * Math.PI * 2 + 0.4
+			world.spawn(UNIT.archer, { at: { x: WARDEN_AT.x + exactMath.cos(angle) * 6.5, z: WARDEN_AT.z + exactMath.sin(angle) * 6.5 }, owner: ENEMY })
+		}
+	},
+	source: ['examples/custom-fx/shield.ts', 'examples/custom-fx/shield.look.ts', 'examples/custom-fx/shader.ts']
+}
+
+/** Registers the warden: he cannot fall, nor strike back */
+export function shieldRules(game: Game<any>): void {
+	game.unit({
+		id: WARDEN,
+		name: 'Warden',
+		kind: 'unit',
+		radius: 0.5,
+		stats: { health: 3000, healthRegen: 200, armor: 40, moveSpeed: 3.5 },
+		sight: 12
+	})
+}

package/starters/examples/src/examples/define.ts

@@ -0,0 +1,86 @@
+/**
+ * What an example is, on the rules' side: its place in the list, its words, its map and what it starts on it. The engine
+ * alone (`@v12-engine/engine`), so the page, the server, a worker and the tests read it with nothing of the client. How
+ * an example looks and the controls beside it are its category's `looks.ts` (`ExampleLook`, `src/shell/look.ts`),
+ * fetched with the game's look
+ */
+import { createMap, exactMath, type Game, type GameMap, type GameStart, type MapEnvironment, presetTiles } from '@v12-engine/engine'
+
+/** The categories of the list, in its order: an example names one by its id */
+export const CATEGORIES = [
+	{ id: 'mechanics', title: 'Core mechanics', summary: 'Selection, orders, paths, combat, sight and fog: what every game here is made of' },
+	{ id: 'abilities', title: 'Abilities', summary: "The engine's own abilities and effects, each cast on something to see what it does" },
+	{ id: 'moba', title: 'Like a MOBA', summary: 'Heroes, skillshots, lanes, a shop and items, as a game like League of Legends has them' },
+	{ id: 'rts', title: 'Like an RTS', summary: 'Bases, workers, building and training, armies and heroes, as a game like Warcraft III has them' },
+	{ id: 'fx', title: 'Effects', summary: 'Every effect the client draws: missiles, impacts, auras, beams, fields and more' },
+	{ id: 'custom-fx', title: 'Your own effects', summary: 'Effects made in code: particles, meshes, shaders and lights of your own' },
+	{ id: 'animation', title: 'Animation', summary: "Models' clips: walking, attacking, blending, timed to what happens" },
+	{ id: 'custom-animation', title: 'Your own animation', summary: 'Moves made in code: poses, springs, tweens and bones driven by hand' },
+	{ id: 'destruction', title: 'Destruction', summary: 'Buildings, trees, rocks and grass broken apart, split into pieces that fall' },
+	{ id: 'construction', title: 'Construction', summary: 'Buildings rising as they are built, stage by stage' },
+	{ id: 'nature', title: 'Nature and weather', summary: 'Trees, grass, water and waterfalls, clouds, mist, rain and snow, the time of day, fire' },
+	{ id: 'post', title: 'Post-processing', summary: 'The picture after it is drawn: bloom, colour, depth of field, outlines and more' },
+	{ id: 'dynamic-map', title: 'A changing map', summary: 'Ground raised, dug, painted and made while the game runs' },
+	{ id: 'cinematics', title: 'Cinematics', summary: 'Cameras, timelines, letterboxing and scenes played in the game' },
+	{ id: 'dialogs', title: 'Dialogue', summary: 'Characters talking, choices, portraits and messages' },
+	{ id: 'gui', title: 'Interfaces', summary: "The HUD's parts, and interfaces of your own in Babylon GUI, Solid and plain HTML" },
+	{ id: 'showcase', title: 'Showcase', summary: 'Larger scenes that put many parts together' },
+	{ id: 'performance', title: 'Performance', summary: 'Thousands of units, crowds, and what the engine keeps fast' }
+] as const
+
+/** A category's id */
+export type CategoryId = (typeof CATEGORIES)[number]['id']
+
+/**
+ * An example on the rules' side: what the list shows of it, and the world it plays. Its scene's id is its `id`, so the
+ * page's address opens it straight (`/?fx-fireball`)
+ */
+export interface ExampleDef {
+	/** Its id, unique among them all, starting with its category's (`fx-fireball`): the scene's id and the address */
+	id: string
+	/** Which category it is listed under */
+	category: CategoryId
+	/** Its name in the list */
+	title: string
+	/** One or two sentences: what it shows, and what to do to see it */
+	summary: string
+	/** Words the list's search finds it by besides its name and summary */
+	tags?: readonly string[]
+	/** The map it plays: a flat field of 48 cells a side with one player when left out (`exampleField`) */
+	map?: () => GameMap | Promise<GameMap>
+	/** What it puts in the world once it is made, before anyone plays: units, buildings, scenery, a timer */
+	start?: GameStart
+	/** A look of the world over the map's own: sky, light, mist, weather. One of the view's by name, or given whole */
+	environment?: string | MapEnvironment
+	/** Whether the player sees the whole map, no fog of war: yes when left out */
+	reveal?: boolean
+	/** The files of the rules' side that make it, shown in the list's Source (paths in `src/`) */
+	source?: readonly string[]
+}
+
+/** What a category's `index.ts` gives: its examples, and what it adds to the game's rules (units, abilities, commands) */
+export interface ExampleCategory {
+	examples: readonly ExampleDef[]
+	/** Registers what its examples need on the game: called once, as the rules are put together (`src/rules.ts`) */
+	rules?: (game: Game) => void
+}
+
+/** The ids of the tiles, the engine's of an RTS (grass, dark grass, dirt, road, sand, rock, snow) */
+export const tiles = [...presetTiles]
+
+/**
+ * A field to play an example on: flat, of `size` cells a side, `players` players with a start each (the first in the
+ * middle, the others round it), painted grass. What an example plays when it says no map
+ */
+export function exampleField(options: { name?: string; size?: number; players?: number; tile?: string } = {}): GameMap {
+	const { name = 'Field', size = 48, players = 1, tile = 'grass' } = options
+	const map = createMap({ name, width: size, depth: size, players, game: 'examples', tileset: tiles.map((each) => each.id) })
+	const paint = map.tileset.indexOf(tile) + 1
+	if (paint > 0) map.tiles.fill(paint)
+	map.players.forEach((player, index) => {
+		const angle = (index / Math.max(1, players)) * Math.PI * 2
+		const away = index === 0 ? 0 : size / 3
+		player.start = { x: size / 2 + exactMath.cos(angle) * away, z: size / 2 + exactMath.sin(angle) * away }
+	})
+	return map
+}