@v12-engine/create 0.1.0 → 0.4.0

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

@@ -0,0 +1,217 @@
+/**
+ * The cinematics examples on the rules' side: their list entries, maps and starts, and the little the rules do for them.
+ * A cinematic is the screen's (`src/examples/cinematics/looks.ts` plays them): it reads the game and changes it only by
+ * commands, like the player. So the rules here are the commands a scene sends (walk there, fight), the units the
+ * scenes need, and one cinematic the rules play themselves, as a unit walks into a ring (`playCinematic`)
+ */
+import {
+	defineCommand,
+	defineComponent,
+	defineIds,
+	exactMath,
+	type Game,
+	id,
+	playCinematic,
+	point,
+	type UnitTypeDef,
+	type World
+} from '@v12-engine/engine'
+import { PLAYER, ENEMY, UNIT } from '../common/units'
+import type { ExampleCategory } from '../define'
+import { ROAD_END, SQUARE, villageMap } from './village'
+
+/** The cinematics examples' own unit types */
+export const CINE = defineIds('cinematics.raider', 'cinematics.villager')
+
+const units: UnitTypeDef[] = [
+	{
+		// a raider of the scene: quick to fall, so that the fight is over in a few blows
+		id: CINE['cinematics.raider'],
+		name: 'Raider',
+		kind: 'unit',
+		radius: 0.45,
+		stats: { health: 110, attackDamage: 8, attackSpeed: 1.2, attackRange: 0.5, armor: 2, moveSpeed: 3.8 },
+		sight: 9,
+		attacks: [{ damagePoint: 0.45, acquisitionRange: 3 }]
+	},
+	{
+		// someone of the village, standing about: what a flythrough flies over
+		id: CINE['cinematics.villager'],
+		name: 'Villager',
+		kind: 'unit',
+		radius: 0.4,
+		stats: { health: 150, moveSpeed: 2.6 },
+		sight: 8
+	}
+]
+
+/** What each example's map is called: its rules tell their own world by it (`world.map.name`) */
+export const MAPS = { flythrough: 'Village', scene: 'Raid', screen: 'Square', trigger: 'Shrine', files: 'Tour', control: 'Transport' } as const
+
+/** The ring of stones the trigger example's cinematic plays at, and the cinematic's id (the view's, `cinematics.defs`) */
+export const SHRINE = { x: 24, z: 33, radius: 2.5 }
+export const SHRINE_CINEMATIC = 'cinematics.shrine'
+
+/** Villagers about the square, some at the fire, some at the market and the well */
+function villagers(world: World): void {
+	const spots = [
+		[22, 24.5, 0.8],
+		[26, 24.6, -0.8],
+		[24, 28.3, Math.PI],
+		[20.5, 28.8, 2.2],
+		[28.3, 29.5, -1.2],
+		[29.6, 23.4, -0.6]
+	]
+	for (const [x, z, facing] of spots) world.spawn(CINE['cinematics.villager'], { at: { x, z }, owner: PLAYER, facing })
+}
+
+/** The raid's units: the knight at the end of the road, three raiders at the bonfire, the villagers fled */
+function raid(world: World): void {
+	world.spawn(UNIT.knight, { at: { x: ROAD_END.x, z: ROAD_END.z + 4 }, owner: PLAYER, facing: 0, name: 'hero' })
+	const raiders = [
+		[SQUARE.x - 2, SQUARE.z - 3],
+		[SQUARE.x + 2, SQUARE.z - 3.4],
+		[SQUARE.x, SQUARE.z - 1.6]
+	]
+	raiders.forEach(([x, z], i) => world.spawn(CINE['cinematics.raider'], { at: { x, z }, owner: ENEMY, facing: Math.PI, name: `raider${i + 1}` }))
+}
+
+/** Takes every unit away */
+function clear(world: World): void {
+	for (const unit of [...world.units.values()]) if (unit.alive) world.kill(unit, undefined, false, 'removed')
+}
+
+/** A scene's walk: a unit sent to a spot, whoever's it is (a cinematic directs everyone) */
+export const walk = defineCommand('cinematics.walk', { unit: id, to: point }, (world, _player, command) => {
+	world.get(command.unit)?.order('move', command.to)
+})
+
+/** The raid's fight: the knight and the raiders at each other */
+export const fight = defineCommand('cinematics.fight', {}, (world) => {
+	const hero = world.named('hero')
+	if (!hero?.alive) return
+	for (const unit of world.units.values()) {
+		if (!unit.alive || unit.def.id !== CINE['cinematics.raider']) continue
+		unit.order('attack', hero)
+	}
+	const first = [...world.units.values()].find((unit) => unit.alive && unit.def.id === CINE['cinematics.raider'])
+	if (first) hero.order('attack', first)
+})
+
+/** Lays the raid out again, as at the start */
+export const resetRaid = defineCommand('cinematics.resetRaid', {}, (world) => {
+	clear(world)
+	raid(world)
+})
+
+/** Whether the shrine's cinematic has played since the knight last stood back on the road */
+const shrineSeen = defineComponent<{ seen: boolean }>({ id: 'cinematics.shrineSeen', default: () => ({ seen: false }) })
+
+/**
+ * The trigger: the first time the knight walks into the ring of stones, the rules play the shrine's cinematic for
+ * its owner, the game held while it plays. Every map plays this game, so it checks the map is the trigger example's.
+ * (A region of a map can say the same with no code: `MapRegion.cinematic`)
+ */
+const shrineTrigger = {
+	name: 'cinematics.shrineTrigger',
+	every: 3,
+	update(world: World) {
+		if (world.map.name !== MAPS.trigger || world.state(shrineSeen).seen) return
+		const hero = world.named('hero')
+		if (!hero?.alive || exactMath.hypot(hero.pos.x - SHRINE.x, hero.pos.z - SHRINE.z) > SHRINE.radius) return
+		world.setState(shrineSeen, { seen: true })
+		hero.order('stop')
+		playCinematic(world, SHRINE_CINEMATIC, { to: hero.owner, hold: true, params: { hero: hero.id } })
+	}
+}
+
+/** The knight back on the road, the shrine ready to play again */
+export const resetShrine = defineCommand('cinematics.resetShrine', {}, (world) => {
+	world.setState(shrineSeen, { seen: false })
+	const hero = world.named('hero')
+	if (!hero?.alive) return
+	hero.order('stop')
+	hero.moveTo(ROAD_END.x, ROAD_END.z + 6)
+})
+
+export const category: ExampleCategory = {
+	rules: (game: Game<any>) => {
+		for (const unit of units) game.unit(unit)
+		game.component(shrineSeen)
+		game.system(shrineTrigger)
+		game.command(walk)
+		game.command(fight)
+		game.command(resetRaid)
+		game.command(resetShrine)
+	},
+	examples: [
+		{
+			id: 'cinematics-flythrough',
+			category: 'cinematics',
+			title: 'A flythrough',
+			summary:
+				'The camera flies over the village in one smooth move through a few shots, along the road on a rail, or round the bonfire. Press a button to fly; Esc skips.',
+			tags: ['camera', 'shot', 'rail', 'path', 'orbit', 'flyover', 'cut.shot', 'cut.rail', 'cut.orbit'],
+			map: () => villageMap(MAPS.flythrough, 1),
+			start: (world) => villagers(world),
+			source: ['examples/cinematics/index.ts', 'examples/cinematics/looks.ts', 'examples/cinematics/village.ts']
+		},
+		{
+			id: 'cinematics-scene',
+			category: 'cinematics',
+			title: 'A scene with actors',
+			summary:
+				'A knight walks up the road, raiders at the bonfire taunt him, he answers, and they fight: units given orders by the cinematic, lines said, and the camera cutting between them.',
+			tags: ['timeline', 'actors', 'walk', 'fight', 'talk', 'camera cuts', 'follow', 'say', 'commands'],
+			map: () => villageMap(MAPS.scene),
+			start: (world) => raid(world),
+			source: ['examples/cinematics/index.ts', 'examples/cinematics/looks.ts']
+		},
+		{
+			id: 'cinematics-screen',
+			category: 'cinematics',
+			title: 'Bars, fades and titles',
+			summary:
+				'What a cinematic does to the frame: letterbox bars, a fade to black, a title card, a vignette, a cold grade, slow motion and transitions between shots. Each button plays a short one.',
+			tags: ['letterbox', 'fade', 'title card', 'vignette', 'grade', 'transition', 'iris', 'wipe', 'dissolve', 'slow motion', 'screen'],
+			map: () => villageMap(MAPS.screen, 1),
+			start: (world) => villagers(world),
+			source: ['examples/cinematics/index.ts', 'examples/cinematics/looks.ts']
+		},
+		{
+			id: 'cinematics-trigger',
+			category: 'cinematics',
+			title: 'Walk in, watch, play on',
+			summary:
+				'Walk the knight (selected) into the ring of stones north of the fire: the rules play a cinematic, the game held, and give the player the knight back after. Again puts him on the road.',
+			tags: ['trigger', 'region', 'playCinematic', 'hold', 'gameplay', 'return control', 'area'],
+			map: () => villageMap(MAPS.trigger, 1),
+			start: (world) => {
+				world.spawn(UNIT.knight, { at: { x: ROAD_END.x, z: ROAD_END.z + 6 }, owner: PLAYER, facing: 0, name: 'hero' })
+				villagers(world)
+			},
+			source: ['examples/cinematics/index.ts', 'examples/cinematics/looks.ts']
+		},
+		{
+			id: 'cinematics-files',
+			category: 'cinematics',
+			title: 'From a file, or in code',
+			summary:
+				'One tour of the village made twice: as data, a file the editor’s Cinematic panel writes (lanes of keys and clips), and as a script, an async function given a cut. Play either; they look alike.',
+			tags: ['json', 'file', 'readCinematic', 'CinematicDef', 'lanes', 'script', 'code', 'editor'],
+			map: () => villageMap(MAPS.files, 1),
+			start: (world) => villagers(world),
+			source: ['examples/cinematics/index.ts', 'examples/cinematics/looks.ts', 'examples/cinematics/tour.json']
+		},
+		{
+			id: 'cinematics-control',
+			category: 'cinematics',
+			title: 'Pause, seek, skip',
+			summary: 'A cinematic on its own clock: pause it, jump to a moment, slow it down, skip it (or make it unskippable), and read how it ended.',
+			tags: ['skip', 'pause', 'seek', 'rate', 'clock', 'Playing', 'outcome', 'skippable', 'Esc'],
+			map: () => villageMap(MAPS.control, 1),
+			start: (world) => villagers(world),
+			source: ['examples/cinematics/index.ts', 'examples/cinematics/looks.ts']
+		}
+	]
+}

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

@@ -0,0 +1,476 @@
+/**
+ * The cinematics examples on the client's side: the scripts they play, their controls, and the looks of their units.
+ * A cinematic here is mostly code: an `async` function given a cut (`Cinematic`), played with `client.play` or
+ * `client.cinematics.play` (which gives back a `Playing` to pause, seek and skip). One is a file (`./tour.json`), as the
+ * editor's Cinematic panel writes them, read with `readCinematic`. The rules play one themselves (the shrine's), by
+ * its id in the view (`cinematics.defs`)
+ */
+import { type Cinematic, type Cut, type GameClientApi, type GameView, mountTitleCard, type Playing, readCinematic } from '@v12-engine/client'
+import { button, type CategoryLooks, readout, slider, toggle } from '../../shell/look'
+import { character, hold, ONE_HANDED, person } from '../common/looks'
+import { CINE, fight, resetRaid, resetShrine, SHRINE, SHRINE_CINEMATIC, walk } from './index'
+import { ROAD_END, SQUARE } from './village'
+import tourFile from './tour.json'
+
+/** Who speaks in the scenes: their names, colours and faces (`GameView.cinematics.speakers`) */
+const SPEAKERS = {
+	'cinematics.knight': { name: 'Sir Aldwin', color: '#9cc4ff', portrait: { type: 'knight' } },
+	'cinematics.raider': { name: 'Raider chief', color: '#ff8a65', portrait: { type: CINE['cinematics.raider'] } },
+	'cinematics.narrator': { name: 'Narrator', color: '#e8d9a8' }
+}
+
+/** The tour of the village as data: a file of lanes, the editor's (`readCinematic` checks it and says what is wrong) */
+const tour = readCinematic(tourFile)
+
+/** A title card over the picture for `seconds`, on the cut's clock (it pauses and slows with it) */
+function titleCard(cut: Cut, title: string, subtitle: string, seconds = 3.5, style = 'title'): void {
+	cut.ui.mount({ mount: (element) => mountTitleCard(element, { title, subtitle, style, for: seconds, in: 0.6, out: 0.8 }, cut.timers) })
+}
+
+/** A pose of the camera: looking at a spot of the map from `distance`, turned `yaw` round it, `pitch` down to it */
+const view = (x: number, z: number, distance: number, yaw: number, pitch: number, fov?: number) => ({
+	at: { x, z },
+	distance,
+	yaw,
+	pitch,
+	...(fov && { fov })
+})
+
+// ---- A flythrough
+
+/**
+ * In one move through five shots: in over the woods, down to the square, round the well, up and away. The move's time
+ * is shared out by how far apart the shots' spots on the ground are, so no two of them look at the same spot
+ */
+const flythrough: Cinematic = async (cut) => {
+	await cut.camera(view(24, 14, 44, 0, 0.8), 0)
+	titleCard(cut, 'Elmbrook', 'a village of the north road', 4)
+	await cut.shot(
+		[
+			view(24, 17, 30, 0.1, 0.6),
+			view(24, 25, 14, 0.25, 0.38, 50),
+			view(27, 28, 12, 1.4, 0.32, 50),
+			view(23, 25, 24, 3.2, 0.55),
+			view(25, 20, 48, 4.4, 0.95)
+		],
+		{ seconds: 16, ease: 'inOutSine' }
+	)
+}
+
+/** Along the road on a rail (the map's path `road`), the camera turned the way it goes */
+const rail: Cinematic = async (cut) => {
+	await cut.camera(view(24, 2, 14, 0, 0.45), 0)
+	await cut.rail('road', { seconds: 12, distance: 14, pitch: 0.45, yaw: 'along', smooth: 4, ease: 'inOutSine' })
+}
+
+/** Round the bonfire, a full turn, the lens long */
+const orbit: Cinematic = async (cut) => {
+	await cut.camera(view(SQUARE.x, SQUARE.z, 18, 0, 0.42, 45), 0.8)
+	await cut.orbit(SQUARE, { radians: Math.PI * 2, seconds: 12 })
+}
+
+// ---- A scene with actors
+
+/**
+ * The raid: the knight walks up the road (an order, sent as a command), the camera following; the raiders' chief
+ * taunts him, a cut to each face; then the fight, the camera framing them all. The cinematic directs both sides with
+ * the example's own commands (`./index.ts`): a game with the director pack (`directorPack`) can use the units lane's
+ */
+const raidScene =
+	(client: GameClientApi): Cinematic =>
+	async (cut) => {
+		const hero = cut.entity('hero')
+		const chief = cut.entity('raider3')
+		if (hero === undefined || chief === undefined) return
+		// the establishing shot: the raiders at the fire, from over the road
+		await cut.camera(view(SQUARE.x, SQUARE.z - 4, 22, 0.3, 0.5), 0)
+		titleCard(cut, 'The Raid', 'Elmbrook, at dusk', 3, 'chapter')
+		await cut.shot(view(SQUARE.x, SQUARE.z - 2, 15, 0.1, 0.42), { seconds: 3, ease: 'inOutCubic' })
+		// a cut to the road: the knight walks in, the camera following him
+		await cut.shot(view(ROAD_END.x, ROAD_END.z + 6, 10, 2.8, 0.35), { transition: 'dissolve' })
+		client.session.send(walk.make({ unit: hero, to: { x: SQUARE.x, z: SQUARE.z - 9 } }))
+		cut.follow(hero, { distance: 11, pitch: 0.35, lag: 0.4 })
+		await cut.say('cinematics.knight', 'Smoke over Elmbrook. I should have come sooner.', 3.5)
+		await cut.until(() => {
+			const at = cut.where(hero)
+			return !!at && at.z > SQUARE.z - 9.5
+		}, 8)
+		// he stands his ground while they talk: on hold, he swings at what comes within reach but chases nothing
+		client.session.send({ type: 'order', entities: [hero], order: { type: 'hold' } })
+		// the chief, close: a long lens over the knight's shoulder
+		await cut.shot({ at: { entity: chief }, distance: 7, yaw: 0.25, pitch: 0.18, fov: 40, height: 1.4 }, { seconds: 0.6 })
+		await cut.say('cinematics.raider', 'One knight? Turn round, tin man, and we let you keep your horse.', 4)
+		await cut.shot({ at: { entity: hero }, distance: 6, yaw: Math.PI - 0.25, pitch: 0.15, fov: 40, height: 1.6 })
+		await cut.say('cinematics.knight', 'I have no horse.', 2.5)
+		// the fight: every one of them in the picture, the camera shaking with the first blows
+		client.session.send(fight.make({}))
+		await cut.fit(['hero', 'raider1', 'raider2', 'raider3'], { seconds: 0.8 })
+		cut.follow(['hero', 'raider1', 'raider2', 'raider3'], { fit: { padding: 5 }, pitch: 0.55, lag: 0.5 })
+		await cut.wait(1.2)
+		cut.shake(0.4)
+		await cut.until(() => [1, 2, 3].every((n) => cut.entity(`raider${n}`) === undefined), 14)
+		await cut.shot({ at: { entity: hero }, distance: 9, yaw: 0.6, pitch: 0.3 }, { seconds: 1.2, ease: 'inOutCubic' })
+		await cut.say('cinematics.knight', 'Elmbrook is free. Ring the bell.', 3)
+	}
+
+// ---- Bars, fades and titles
+
+/** Each a short cinematic of one thing the frame does, over the same shot of the square */
+const SQUARE_SHOT = view(SQUARE.x, SQUARE.z, 20, 0.5, 0.5)
+const screenCuts: Record<string, Cinematic> = {
+	letterbox: async (cut) => {
+		await cut.camera(SQUARE_SHOT, 0)
+		await cut.screen.letterbox(2.39, 0.8)
+		await cut.shot(view(SQUARE.x, SQUARE.z, 16, 1.1, 0.4), { seconds: 4 })
+		await cut.screen.letterbox(false, 0.8)
+	},
+	fade: async (cut) => {
+		await cut.camera(SQUARE_SHOT, 0)
+		await cut.wait(0.6)
+		await cut.screen.fade('#000', 1, 1.2)
+		await cut.camera(view(29, 28.5, 9, 2.4, 0.35), 0)
+		await cut.wait(0.6)
+		await cut.screen.fade('#000', 0, 1.2)
+		await cut.wait(1.5)
+	},
+	title: async (cut) => {
+		await cut.camera(SQUARE_SHOT, 0)
+		await cut.screen.vignette(0.6, 0.5, 0.6)
+		titleCard(cut, 'Chapter One', 'The North Road', 4, 'chapter')
+		await cut.wait(4.3)
+		titleCard(cut, 'Elmbrook', 'three days from the capital', 3.5, 'lower-third')
+		await cut.wait(3.8)
+	},
+	grade: async (cut) => {
+		await cut.camera(SQUARE_SHOT, 0)
+		await cut.picture.grade({ saturation: 0.35, contrast: 1.15, tint: [0.55, 0.7, 1], tintAmount: 0.35 }, 1.5)
+		await cut.screen.vignette(0.7, 0.5, 1)
+		await cut.shot(view(SQUARE.x, SQUARE.z, 14, 1.4, 0.35), { seconds: 3 })
+		await cut.picture.reset(1)
+	},
+	slow: async (cut) => {
+		await cut.camera(view(SQUARE.x, SQUARE.z, 11, 0.4, 0.3, 45), 0)
+		await cut.screen.letterbox(2.39, 0.4)
+		await cut.speed.slow(0.2, 0.6)
+		await cut.screen.tint('#ffd9a0', 0.15, 0.6)
+		await cut.shot(view(SQUARE.x, SQUARE.z, 9, 1.3, 0.25, 45), { seconds: 4 })
+		cut.speed.reset()
+	},
+	transitions: async (cut) => {
+		const shots = [
+			view(24, 20, 20, 0.3, 0.5),
+			view(15, 33, 14, 2.4, 0.35),
+			view(29, 28.5, 9, 2.4, 0.35),
+			view(34, 20, 16, 4.5, 0.4),
+			view(24, 40, 18, 3.1, 0.3)
+		]
+		const ways = ['dissolve', 'wipe', 'iris', 'push', 'zoom']
+		await cut.camera(SQUARE_SHOT, 0)
+		for (let i = 0; i < shots.length; i++) {
+			await cut.wait(0.9)
+			titleCard(cut, ways[i], '', 1.6, 'lower-third')
+			await cut.shot(shots[i], { transition: { id: ways[i], seconds: 0.8 } })
+		}
+		await cut.wait(1.4)
+	}
+}
+
+// ---- Walk in, watch, play on
+
+/**
+ * The shrine's cinematic, played by the rules as the knight walks into the ring (`playCinematic`, handed his id): the
+ * camera round him, a voice from the stones, and the bars away. Then the player has him back, where he stood
+ */
+const shrine: Cinematic = async (cut, params) => {
+	const hero = Number(params?.hero)
+	await cut.shot({ at: SHRINE, distance: 12, yaw: 0.4, pitch: 0.35 }, { seconds: 1.2, ease: 'inOutCubic' })
+	cut.fx('spark-burst', { at: SHRINE })
+	await cut.screen.flash('#fff6d0', 0.4)
+	await cut.say('cinematics.narrator', 'The stones hum. Something old is awake beneath Elmbrook.', 3.5)
+	await cut.orbit({ entity: hero }, { radians: Math.PI * 0.8, seconds: 4 })
+	await cut.say('cinematics.knight', 'Then I will be ready for it.', 2.5)
+}
+
+// ---- Pause, seek, skip
+
+/** What the transport example is playing, and how the last one ended */
+const transport: { playing?: Playing; outcome?: string; skippable: boolean; rate: number } = { skippable: true, rate: 1 }
+
+/** Plays the tour (the file), keeping hold of it for the controls */
+function playTour(client: GameClientApi): void {
+	transport.playing?.stop()
+	transport.outcome = undefined
+	const playing = client.cinematics.play(tour, { skippable: transport.skippable, rate: transport.rate })
+	transport.playing = playing
+	void playing.done.then((outcome) => {
+		transport.outcome = outcome
+		if (transport.playing === playing) transport.playing = undefined
+	})
+}
+
+/** The tour in code, the same shots and lines as the file: what the file's lanes do, said as steps */
+const tourInCode: Cinematic = async (cut) => {
+	await cut.screen.letterbox(2.39, 0.6)
+	await cut.camera(view(24, 6, 40, 0, 0.8), 0)
+	cut.screen.fade('#000', 0, 1.5)
+	titleCard(cut, 'Elmbrook', 'made in code', 4)
+	void cut.say('cinematics.narrator', 'In the north there is a village where the road ends.', 4.5)
+	await cut.shot(view(24, 22, 20, 0.6, 0.5), { seconds: 6, ease: 'inOutCubic' })
+	void cut.say('cinematics.narrator', 'Its people keep the fire lit, and the bell rung.', 4.5)
+	await cut.shot(view(24, 30, 18, 2.8, 0.45), { seconds: 6, ease: 'inOutSine' })
+	await cut.shot(view(24, 26, 42, 3.6, 0.9), { seconds: 4, ease: 'inOutSine' })
+}
+
+/** The player's camera over a spot, `distance` away, turned and tilted as it is: where an example starts */
+export function aim(client: GameClientApi, at: { x: number; z: number }, distance: number): void {
+	const { yaw, pitch } = client.camera.pose()
+	client.camera.setPose({ x: at.x, z: at.z, distance, yaw, pitch })
+}
+
+/** The village alive: the bonfire burning, smoke from two chimneys. Gives back what puts them out */
+export function villageFx(client: GameClientApi): () => void {
+	const lit = [
+		client.fx.play('campfire', { at: SQUARE }),
+		client.fx.play('chimney', { at: { x: 15.6, y: 6, z: 34.2 } }),
+		client.fx.play('chimney', { at: { x: 13.6, y: 6.5, z: 20.4 } })
+	]
+	return () => lit.forEach((each) => each.stop({ clear: true }))
+}
+
+/**
+ * Plays a cinematic in the place of any playing now (`replaced`): what the example's buttons all do. The screen is made
+ * clear first: one replaced half way through its fade to black leaves the fade where it got to (a cinematic's fade
+ * stays after it, for a game that ends on black), and the next would play in the dark
+ */
+const play = (client: GameClientApi, what: Cinematic) =>
+	void client.play(async (cut, params) => {
+		await cut.screen.reset(0)
+		await what(cut, params)
+	})
+
+export const category: CategoryLooks = {
+	// the units of the scenes, and who speaks in them
+	view: (view: GameView) => ({
+		...view,
+		units: {
+			...view.units,
+			looks: {
+				...view.units.looks,
+				[CINE['cinematics.raider']]: {
+					height: 1.8,
+					model: character('barbarian', 0.7, { hold: [hold('axe_1handed'), hold('shield_round_barbarian', 'l')] }),
+					attacks: [ONE_HANDED],
+					shapes: person(1.8)
+				},
+				[CINE['cinematics.villager']]: { height: 1.7, model: character('rogue_hooded', 0.66), shapes: person(1.7, [0.55, 0.45, 0.35]) }
+			}
+		},
+		cinematics: {
+			...view.cinematics,
+			// the one the rules play by its id (`playCinematic`)
+			defs: { ...view.cinematics?.defs, [SHRINE_CINEMATIC]: { play: shrine, back: true } },
+			speakers: { ...view.cinematics?.speakers, ...SPEAKERS }
+		}
+	}),
+	looks: {
+		'cinematics-flythrough': {
+			controls: [
+				button(
+					'Fly through the village',
+					(client) => play(client, flythrough),
+					'Plays a fly-through of the village: five camera shots joined in one smooth move (cut.shot), the bars in at the edges.'
+				),
+				button(
+					'Down the road on a rail',
+					(client) => play(client, rail),
+					'The camera glides down the village road along a path drawn on the map, “road”, turned the way it goes (cut.rail).'
+				),
+				button(
+					'Round the fire',
+					(client) => play(client, orbit),
+					'The camera makes a full slow turn round the bonfire with a long lens (cut.orbit).'
+				),
+				button('Skip', (client) => client.skipCinematic(), 'Ends the cinematic playing now, as Esc does: the camera is the player’s again.')
+			],
+			ready: (client) => {
+				aim(client, SQUARE, 34)
+				const out = villageFx(client)
+				const timer = setTimeout(() => play(client, flythrough), 600)
+				return () => {
+					clearTimeout(timer)
+					out()
+				}
+			}
+		},
+		'cinematics-scene': {
+			controls: [
+				button(
+					'Play the scene',
+					(client) => {
+						client.session.send(resetRaid.make({}))
+						// the units laid out again land at the next tick: the scene starts after them
+						setTimeout(() => play(client, raidScene(client)), 150)
+					},
+					'Lays the raiders and the knight out again and plays the scene: he walks in, the chief taunts him with a cut to each face, then the fight.'
+				),
+				button('Skip', (client) => client.skipCinematic(), 'Ends the scene now, as Esc does: the units stay where the scene left them.')
+			],
+			ready: (client) => {
+				aim(client, { x: SQUARE.x, z: SQUARE.z - 6 }, 30)
+				const out = villageFx(client)
+				const timer = setTimeout(() => play(client, raidScene(client)), 600)
+				return () => {
+					clearTimeout(timer)
+					out()
+				}
+			}
+		},
+		'cinematics-screen': {
+			controls: [
+				button(
+					'Letterbox',
+					(client) => play(client, screenCuts.letterbox),
+					'Black bars slide in to a 2.39:1 frame, then out again (cut.screen.letterbox).'
+				),
+				button(
+					'Fade to black',
+					(client) => play(client, screenCuts.fade),
+					'The picture fades out to black, the camera cuts in the dark, and it fades back in (cut.screen.fade).'
+				),
+				button(
+					'Title cards',
+					(client) => play(client, screenCuts.title),
+					'A chapter title over the picture, then a smaller name in the lower third (mountTitleCard).'
+				),
+				button(
+					'Cold grade',
+					(client) => play(client, screenCuts.grade),
+					'The picture’s colour drained and cooled to blue for a few seconds, then back (cut.picture.grade).'
+				),
+				button(
+					'Slow motion',
+					(client) => play(client, screenCuts.slow),
+					'The whole world slows to a fifth of its speed, the fire and smoke with it, then back (cut.speed.slow).'
+				),
+				button(
+					'Transitions',
+					(client) => play(client, screenCuts.transitions),
+					'Five cuts between two shots, each a different transition: dissolve, wipe, iris, push and zoom.'
+				)
+			],
+			ready: (client) => {
+				aim(client, SQUARE, 26)
+				return villageFx(client)
+			}
+		},
+		'cinematics-trigger': {
+			controls: [
+				button(
+					'Walk him in',
+					(client) => {
+						const hero = client.session.snapshot().entities.find((each) => each.name === 'hero')
+						if (hero) client.session.send(walk.make({ unit: hero.id, to: SHRINE }))
+					},
+					'Walks the knight into the ring of stones: the rules see him arrive and play the shrine’s cinematic. You can also order him there yourself.'
+				),
+				button(
+					'Again',
+					(client) => client.session.send(resetShrine.make({})),
+					'Puts the knight back on the road and resets the stones, so walking in plays the cinematic again.'
+				),
+				readout(
+					'Playing',
+					(client) => (client.cinematics.current ? `${client.cinematics.current.id ?? 'a cinematic'}` : 'the game'),
+					'The cinematic playing now, by its id, or “the game” when the player has the camera.'
+				)
+			],
+			ready: (client) => {
+				aim(client, { x: 24, z: 20 }, 32)
+				const hero = client.session.snapshot().entities.find((each) => each.name === 'hero')
+				if (hero) client.controller.select([hero.id])
+				// the ring to walk into: a label over the stones, pinned to the world
+				const label = document.createElement('div')
+				label.textContent = '◈ The old stones'
+				label.style.cssText =
+					'font:600 13px Georgia,serif;color:#ffe9a8;padding:3px 9px;border-radius:12px;background:rgba(20,14,6,.7);border:1px solid #c9a35a;white-space:nowrap'
+				const pin = client.attach(label, { x: SHRINE.x, z: SHRINE.z, height: 1 })
+				const glow = client.fx.play('glow', { at: SHRINE })
+				const out = villageFx(client)
+				return () => {
+					pin.remove()
+					glow.stop({ clear: true })
+					out()
+				}
+			}
+		},
+		'cinematics-files': {
+			controls: [
+				button(
+					'Play the file',
+					(client) => void client.play(tour),
+					'Plays tour.json, a cinematic made as data (as the editor saves it): lanes of camera keys, the bars, spoken lines and a title.'
+				),
+				button(
+					'Play the code',
+					(client) => play(client, tourInCode),
+					'Plays the same tour written as code, step after step: compare it with the file.'
+				),
+				button('Skip', (client) => client.skipCinematic(), 'Ends the tour now, as Esc does.')
+			],
+			ready: (client) => {
+				aim(client, SQUARE, 30)
+				return villageFx(client)
+			}
+		},
+		'cinematics-control': {
+			controls: [
+				button('Play', (client) => playTour(client), 'Plays the village tour from the start, at the speed and skippable as set below.'),
+				button('Pause', () => transport.playing?.pause(), 'Holds the tour where it is: the camera, the lines and the clock stop.'),
+				button('Resume', () => transport.playing?.resume(), 'Goes on with the tour from where it was paused.'),
+				button(
+					'Jump to 9 s',
+					() => transport.playing?.seek(9),
+					'Jumps the tour to 9 seconds in: the camera, the bars and the lines are as they are at that moment.'
+				),
+				slider(
+					'Speed',
+					{ min: 0.25, max: 2, step: 0.25, value: 1 },
+					(_client, value) => {
+						transport.rate = value
+						transport.playing?.rate(value)
+					},
+					'How fast the tour plays, from a quarter to twice: the camera moves and the lines follow its clock.'
+				),
+				toggle(
+					'Skippable',
+					true,
+					(_client, on) => (transport.skippable = on),
+					'Whether Esc and Skip may end the tour: off, they do nothing, from the next Play on.'
+				),
+				button(
+					'Skip',
+					(client) => client.skipCinematic(),
+					'Ends the tour now, as Esc does (in code, playing.stop()): does nothing while Skippable is off.'
+				),
+				readout(
+					'Clock',
+					() => {
+						const { playing } = transport
+						if (playing) return `${playing.cut.time.toFixed(1)} s${playing.paused ? ', paused' : ''}`
+						return transport.outcome ? `over: ${transport.outcome}` : 'not playing'
+					},
+					'Where the tour is on its own clock, and how the last one ended: ended, skipped, stopped or replaced.'
+				)
+			],
+			ready: (client) => {
+				aim(client, SQUARE, 30)
+				const out = villageFx(client)
+				return () => {
+					transport.playing = undefined
+					transport.outcome = undefined
+					out()
+				}
+			}
+		}
+	}
+}