@v12-engine/create 0.1.0 → 0.4.0

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

@@ -0,0 +1,372 @@
+/**
+ * The performance examples on the client's side: their units drawn as baked crowds, the cards' sliders that ask for
+ * thousands, and a meter on every card (`./meter.ts`) that says how fast the picture is made. Numbers to watch, not
+ * to trust to the last frame: they are this machine's, with whatever else it runs
+ */
+import type { GameClientApi, GameView, UnitLook } from '@v12-engine/client'
+import { presetFx } from '@v12-engine/client'
+import type { MapDoodad } from '@v12-engine/engine'
+import { button, type CategoryLooks, readout, select, slider, toggle } from '../../shell/look'
+import { character, hold, ONE_HANDED, person } from '../common/looks'
+import { army, battle, charge, flow, march, PERF, volley } from './index'
+import { countUnits, metered, meterReadouts, startMeter } from './meter'
+
+/** The category's units' looks. `baked: true`: each drawn as a copy of one mesh, its clips baked into a texture */
+const looks: Record<string, UnitLook> = {
+	[PERF.performanceFootman]: {
+		height: 1.8,
+		model: character('knight', 0.7, { hold: [hold('sword_1handed'), hold('shield_round', 'l')] }),
+		attacks: [ONE_HANDED],
+		baked: true,
+		shapes: person(1.8)
+	},
+	[PERF.performanceArcher]: {
+		height: 1.7,
+		model: character('ranger', 0.68, { hold: [hold('bow')], animations: { attack: 'Ranged_2H_Shoot' } }),
+		shot: { color: [0.85, 0.75, 0.55], size: 0.2 },
+		baked: true,
+		shapes: person(1.7)
+	},
+	// the shared art's training dummy; its parts show while it loads
+	[PERF.performanceTarget]: {
+		height: 1.6,
+		model: { src: 'props/dummy.glb', scale: 0.86 },
+		shapes: [
+			{ shape: 'cylinder', size: [0.12, 1.6, 0.12], offset: [0, 0.8, 0], color: [0.45, 0.31, 0.18] },
+			{ shape: 'cylinder', size: [1, 0.12, 1], offset: [0, 1.3, 0], tilt: Math.PI / 2, color: [0.85, 0.2, 0.15] }
+		]
+	}
+}
+
+/** The effects the effects example plays: the ready-made ones, taken into the game's look */
+const EFFECTS = ['fire', 'campfire', 'explosion', 'sparkle', 'spark-burst', 'smoke', 'glow', 'aura'] as const
+
+/**
+ * Calls `send` once the slider has stood still a moment: a slider tells every step it is dragged through, and an army
+ * of thousands laid out at each would be thousands laid out many times over
+ */
+function settled(send: (client: GameClientApi, value: number) => void, ms = 250): (client: GameClientApi, value: number) => void {
+	let timer: ReturnType<typeof setTimeout> | undefined
+	return (client, value) => {
+		clearTimeout(timer)
+		timer = setTimeout(() => send(client, value), ms)
+	}
+}
+
+/** Puts the camera over the middle of a field `size` cells a side, `distance` back, and lets it go as far as `far` */
+function overlook(client: GameClientApi, size: number, distance: number, far = distance * 1.6, pitch = 0.9): void {
+	client.camera.setLimits({ max: far })
+	client.camera.setPose({ x: size / 2, z: size / 2, distance, yaw: 0, pitch })
+}
+
+/** The sides of the examples' fields, in cells, as their maps say (`./index.ts`) */
+const SIZE = { army: 128, battle: 128, volley: 96, flow: 112, forest: 192, effects: 96 }
+
+/** Sends a command of the game's from the card */
+const send = (client: GameClientApi, command: ReturnType<(typeof army)['make']>) => client.session.send(command)
+
+// ---- the forest: trees as scenery, laid out in code and handed to the client's scenery whole
+
+const TREES = [
+	'trees/pine_1.glb',
+	'trees/pine_2.glb',
+	'trees/pine_3.glb',
+	'trees/pine_4.glb',
+	'trees/oak_1.glb',
+	'trees/oak_2.glb',
+	'trees/oak_5.glb',
+	'trees/columnar_2.glb'
+]
+
+/** `count` trees over the field, in clumps with clearings, the same every time for the same count (a seeded random) */
+function forest(count: number, size: number): MapDoodad[] {
+	let seed = 12345
+	const random = () => (seed = (seed * 1103515245 + 12345) & 0x7fffffff) / 0x7fffffff
+	const trees: MapDoodad[] = []
+	// clumps of woods: each tree near one, so the forest has glades between
+	const clumps = Array.from({ length: 60 }, () => ({ x: 8 + random() * (size - 16), z: 8 + random() * (size - 16), r: 8 + random() * 22 }))
+	for (let id = 1; trees.length < count && id < count * 4; id++) {
+		const clump = clumps[Math.floor(random() * clumps.length)]!
+		const angle = random() * Math.PI * 2
+		const away = Math.sqrt(random()) * clump.r
+		const x = clump.x + Math.cos(angle) * away
+		const z = clump.z + Math.sin(angle) * away
+		if (x < 2 || z < 2 || x > size - 2 || z > size - 2) continue
+		const scale = 0.7 + random() * 0.6
+		trees.push({
+			id: 100000 + id,
+			model: TREES[Math.floor(random() * TREES.length)]!,
+			x,
+			z,
+			yaw: random() * Math.PI * 2,
+			scale: [scale, scale, scale]
+		})
+	}
+	return trees
+}
+
+// ---- the effects: many playing at once, the bursts played again as they end
+
+/** How many of the effects example's give light */
+const LIT = 12
+
+/** What the effects example plays now, to stop it as another count or kind is chosen */
+const playing = new WeakMap<GameClientApi, { count: number; kind: string; stop: () => void }>()
+
+/** Plays `count` effects of a kind over the field, in a grid round the middle: bursts again and again, the rest held on */
+function playEffects(client: GameClientApi, count: number, kind: string): void {
+	playing.get(client)?.stop()
+	const x = SIZE.effects / 2
+	const z = SIZE.effects / 2
+	const side = Math.ceil(Math.sqrt(count))
+	const places = Array.from({ length: count }, (_, i) => ({
+		x: x + ((i % side) - (side - 1) / 2) * 2.6,
+		z: z + (Math.floor(i / side) - (side - 1) / 2) * 2.6
+	}))
+	const kinds = kind === 'mixed' ? EFFECTS : [kind]
+	const handles = new Set<ReturnType<GameClientApi['fx']['play']>>()
+	let stopped = false
+	const play = (i: number) => {
+		if (stopped) return
+		const name = kinds[i % kinds.length]!
+		// a light of its own for the first few alone: lights are dear (each lights everything near it), and the scene
+		// has room for a few dozen at once; the rest glow by their particles
+		const handle = client.fx.play(name, { at: places[i]!, ...(i >= LIT && { params: { light: 0 } }) })
+		handles.add(handle)
+		// one that ends by itself (a blast, a burst of sparks) is played again a moment after, at the same place
+		void handle.done.then(() => {
+			handles.delete(handle)
+			if (!stopped) setTimeout(() => play(i), 200 + ((i * 37) % 600))
+		})
+	}
+	for (let i = 0; i < count; i++) setTimeout(() => play(i), (i * 7) % 800)
+	playing.set(client, {
+		count,
+		kind,
+		stop: () => {
+			stopped = true
+			for (const handle of handles) handle.stop()
+			handles.clear()
+		}
+	})
+}
+
+export const category: CategoryLooks = {
+	view: (view: GameView<any>) => ({
+		...view,
+		units: { ...view.units, looks: { ...view.units.looks, ...looks } },
+		fx: { ...view.fx, defs: { ...presetFx([...EFFECTS]), ...view.fx?.defs } }
+	}),
+	looks: {
+		'performance-army': {
+			view: metered,
+			controls: [
+				slider(
+					'Footmen',
+					{ min: 100, max: 5000, step: 100, value: 400 },
+					settled((client, count) => send(client, army.make({ count }))),
+					'How many footmen stand in the block in the middle: let go and the army is laid out anew'
+				),
+				select(
+					'Formation',
+					['square', 'circle', 'rows'],
+					'square',
+					(client, value) => formation.set(client, value as Formation),
+					'The shape the army takes where the buttons below send it: it shows as they march'
+				),
+				button(
+					'March north',
+					(client) => send(client, march.make({ to: 'north', formation: formation.get(client) ?? 'square' })),
+					'One order for the whole army to the north of the field, in the formation chosen'
+				),
+				button(
+					'March south',
+					(client) => send(client, march.make({ to: 'south', formation: formation.get(client) ?? 'square' })),
+					'The whole army to the south of the field'
+				),
+				button(
+					'Back to the middle',
+					(client) => send(client, march.make({ to: 'middle', formation: formation.get(client) ?? 'square' })),
+					'The whole army back to the middle'
+				),
+				toggle(
+					'Baked crowd',
+					true,
+					(client, on) => {
+						// the look the same but for its baking: each footman drawn again as a copy, or with a skeleton of its own
+						const look = client.looks.get(PERF.performanceFootman)
+						if (look) void client.looks.set(PERF.performanceFootman, { ...look, baked: on })
+					},
+					'On, the footmen are drawn as copies of a few baked clips; off, every footman has a skeleton of its own, as a hero has: much slower past a few hundred'
+				),
+				readout('Footmen', (client) => countUnits(client).toLocaleString(), 'Footmen on the field now'),
+				...meterReadouts()
+			],
+			ready: (client) => {
+				overlook(client, SIZE.army, 75, 140)
+				return startMeter(client)
+			}
+		},
+		'performance-battle': {
+			view: metered,
+			controls: [
+				slider(
+					'Footmen a side',
+					{ min: 100, max: 2500, step: 100, value: 150 },
+					settled((client, count) => {
+						lastBattle.set(client, count)
+						send(client, battle.make({ count }))
+					}),
+					'How many footmen each side has: let go and both armies are laid out anew'
+				),
+				button(
+					'Charge',
+					(client) => send(client, charge.make({})),
+					'Both armies at each other, fighting what they meet: the costly part is the melee'
+				),
+				button(
+					'Lay them out again',
+					(client) => send(client, battle.make({ count: lastBattle.get(client) ?? 150 })),
+					'Both armies whole again and facing each other, as many as the slider says'
+				),
+				readout('Blue · red', sides, 'Footmen each side has left alive'),
+				...meterReadouts()
+			],
+			ready: (client) => {
+				overlook(client, SIZE.battle, 60, 140, 0.75)
+				return startMeter(client)
+			}
+		},
+		'performance-volley': {
+			view: metered,
+			controls: [
+				slider(
+					'Archers',
+					{ min: 50, max: 2000, step: 50, value: 120 },
+					settled((client, count) => send(client, volley.make({ count }))),
+					'How many archers shoot at the targets: let go and they are laid out anew, a target for every eight'
+				),
+				readout(
+					'Archers · arrows in the air',
+					(client) => {
+						const { projectiles } = client.session.snapshot()
+						return `${countUnits(client, (type) => type === PERF.performanceArcher)} · ${projectiles.length}`
+					},
+					'Archers on the field, and the arrows flying now: each a missile the rules move'
+				),
+				...meterReadouts()
+			],
+			ready: (client) => {
+				overlook(client, SIZE.volley, 45, 120, 0.7)
+				return startMeter(client)
+			}
+		},
+		'performance-flow': {
+			view: metered,
+			controls: [
+				slider(
+					'Footmen a crowd',
+					{ min: 50, max: 1000, step: 50, value: 100 },
+					settled((client, count) => send(client, flow.make({ count }))),
+					'How many footmen in each of the two crowds that cross the field through each other'
+				),
+				readout('Footmen', (client) => countUnits(client).toLocaleString(), 'Footmen on the field now, both crowds'),
+				...meterReadouts()
+			],
+			ready: (client) => {
+				overlook(client, SIZE.flow, 70, 140, 0.95)
+				return startMeter(client)
+			}
+		},
+		'performance-forest': {
+			view: metered,
+			controls: [
+				slider(
+					'Trees',
+					{ min: 1000, max: 40000, step: 1000, value: 8000 },
+					settled((client, count) => client.doodads.set(forest(count, SIZE.forest)), 400),
+					'How many trees stand in the forest: let go and it is planted anew'
+				),
+				button(
+					'Fly across',
+					(client) => {
+						const x = SIZE.forest / 2
+						const z = SIZE.forest / 2
+						client.camera.setPose({ x: x - 60, z: z - 60, distance: 30, yaw: Math.PI / 4, pitch: 0.55 })
+						client.camera.panTo({ x: x + 60, z: z + 60 }, 12, 'linear')
+					},
+					'The camera low over the trees, flying corner to corner for twelve seconds'
+				),
+				button('Look over it all', (client) => overlook(client, SIZE.forest, 150, 220, 0.75), 'The camera high, the whole forest in view'),
+				readout(
+					'Trees · drawn as',
+					(client) => {
+						const stats = client.doodads.stats
+						return `${stats.doodads.toLocaleString()} · ${stats.copies.toLocaleString()} copies, ${stats.merged.toLocaleString()} merged, ${stats.own} own`
+					},
+					'Trees, and how they are drawn: as copies of one mesh, merged into big meshes, or each a mesh of its own'
+				),
+				...meterReadouts()
+			],
+			ready: (client) => {
+				client.doodads.set(forest(8000, SIZE.forest))
+				overlook(client, SIZE.forest, 90, 220, 0.7)
+				return startMeter(client)
+			}
+		},
+		'performance-effects': {
+			view: metered,
+			controls: [
+				slider(
+					'Effects',
+					{ min: 25, max: 300, step: 25, value: 150 },
+					settled((client, count) => playEffects(client, count, playing.get(client)?.kind ?? 'mixed')),
+					'How many effects play at once in a grid over the field, the first twelve with a light'
+				),
+				select(
+					'Kind',
+					['mixed', ...EFFECTS],
+					'mixed',
+					(client, kind) => playEffects(client, playing.get(client)?.count ?? 150, kind),
+					'Which effect plays in every place, or a mix of all of them'
+				),
+				readout(
+					'Effects · particles · lights',
+					(client) => {
+						const stats = client.fx.stats()
+						return `${stats.effects} · ${stats.particles.toLocaleString()} · ${stats.lights}`
+					},
+					'Effects playing, the particles they hold, and the lights they give'
+				),
+				...meterReadouts()
+			],
+			ready: (client) => {
+				overlook(client, SIZE.effects, 50, 120, 0.8)
+				playEffects(client, 150, 'mixed')
+				const stop = startMeter(client)
+				return () => {
+					playing.get(client)?.stop()
+					stop()
+				}
+			}
+		}
+	}
+}
+
+type Formation = 'square' | 'circle' | 'rows'
+/** The formation chosen on the army example's card, by client */
+const formation = new WeakMap<GameClientApi, Formation>()
+/** The size of the battle last laid out, by client */
+const lastBattle = new WeakMap<GameClientApi, number>()
+
+/** The two sides of the battle, alive: blue's and red's */
+function sides(client: GameClientApi): string {
+	let blue = 0
+	let red = 0
+	for (const each of client.session.snapshot().entities) {
+		if (each.health <= 0) continue
+		if (each.owner === 1) blue++
+		else if (each.owner === 2) red++
+	}
+	return `${blue.toLocaleString()} · ${red.toLocaleString()}`
+}

package/starters/examples/src/examples/performance/meter.ts

@@ -0,0 +1,158 @@
+/**
+ * A meter of how fast the game is made, for the performance examples' cards: frames a second and the milliseconds
+ * from one frame to the next (the slowest of the last half second too), the CPU's work of a frame and the
+ * simulation's part of it, and the draws a frame takes. The CPU's work is timed by phases of the frame of our own
+ * (`GameView.framePhases`), one before the client's first phase and one after its last, and two round `simulate`; the
+ * draws are counted by Babylon (`SceneInstrumentation`). `metered` adds the phases to an example's look; `startMeter`,
+ * in its `ready`, starts adding up; the card's readouts (`meterReadouts`) say what it found
+ */
+import { SceneInstrumentation } from '@babylonjs/core/Instrumentation/sceneInstrumentation.js'
+import type { GameClientApi, GameView } from '@v12-engine/client'
+import { type ExampleControl, readout } from '../../shell/look'
+
+/** What the meter has measured over the last half second */
+export interface Measured {
+	/** Frames drawn a second */
+	fps: number
+	/** Milliseconds from one frame to the next, on average */
+	frameMs: number
+	/** The slowest frame of the last half second, in milliseconds */
+	worstMs: number
+	/** Milliseconds of the CPU's work a frame: every phase of the client's, the picture's draw calls with them */
+	cpuMs: number
+	/** Of it, the simulation's: the world stepped and its snapshot taken (`simulate`) */
+	simMs: number
+	/** Draws a frame: the view and every shadow pass */
+	draws: number
+}
+
+/** The sums of the half second under way, and what they last came to */
+interface Meter {
+	measured: Measured
+	frameAt: number
+	simAt: number
+	cpu: number
+	sim: number
+	stop(): void
+}
+
+/** The meter of each client playing an example now */
+const meters = new WeakMap<GameClientApi, Meter>()
+
+/** An example's look with the meter's phases of the frame: what times the CPU's work and the simulation's */
+export function metered(view: GameView<any>): GameView<any> {
+	const now = () => performance.now()
+	return {
+		...view,
+		framePhases: [
+			...(view.framePhases ?? []),
+			{
+				name: 'performance.frameStart',
+				before: 'measure',
+				run: (_frame, client) => void (meters.get(client) && (meters.get(client)!.frameAt = now()))
+			},
+			{ name: 'performance.simStart', before: 'simulate', run: (_frame, client) => void (meters.get(client) && (meters.get(client)!.simAt = now())) },
+			{
+				name: 'performance.simEnd',
+				after: 'simulate',
+				run: (_frame, client) => {
+					const meter = meters.get(client)
+					if (meter) meter.sim += now() - meter.simAt
+				}
+			},
+			{
+				name: 'performance.frameEnd',
+				after: 'hud',
+				run: (_frame, client) => {
+					const meter = meters.get(client)
+					if (meter) meter.cpu += now() - meter.frameAt
+				}
+			}
+		]
+	}
+}
+
+/** Starts adding up the client's frames; what it gives back stops it */
+export function startMeter(client: GameClientApi): () => void {
+	meters.get(client)?.stop()
+	const instruments = new SceneInstrumentation(client.scene)
+	const measured: Measured = { fps: 0, frameMs: 0, worstMs: 0, cpuMs: 0, simMs: 0, draws: 0 }
+	let last = performance.now()
+	let since = last
+	let frames = 0
+	let gaps = 0
+	let worst = 0
+	let draws = 0
+	const observer = client.scene.onAfterRenderObservable.add(() => {
+		const now = performance.now()
+		const gap = now - last
+		last = now
+		frames++
+		gaps += gap
+		worst = Math.max(worst, gap)
+		draws += instruments.drawCallsCounter.current
+		if (now - since < 500) return
+		measured.fps = (frames * 1000) / (now - since)
+		measured.frameMs = gaps / frames
+		measured.worstMs = worst
+		measured.cpuMs = meter.cpu / frames
+		measured.simMs = meter.sim / frames
+		measured.draws = Math.round(draws / frames)
+		since = now
+		frames = gaps = worst = draws = meter.cpu = meter.sim = 0
+	})
+	const meter: Meter = {
+		measured,
+		frameAt: last,
+		simAt: last,
+		cpu: 0,
+		sim: 0,
+		stop: () => {
+			client.scene.onAfterRenderObservable.remove(observer)
+			instruments.dispose()
+			if (meters.get(client) === meter) meters.delete(client)
+		}
+	}
+	meters.set(client, meter)
+	return meter.stop
+}
+
+/** What the client's meter has measured, if it is measuring */
+export const meterOf = (client: GameClientApi): Measured | undefined => meters.get(client)?.measured
+
+/** The meter's lines on a card: frames a second and frame time, the CPU's work and the simulation's, draws */
+export function meterReadouts(): ExampleControl[] {
+	return [
+		readout(
+			'Frames a second',
+			(client) => {
+				const m = meterOf(client)
+				return m ? `${m.fps.toFixed(0)} fps · ${m.frameMs.toFixed(1)} ms (worst ${m.worstMs.toFixed(0)})` : '…'
+			},
+			'Frames drawn a second, the time between them, and the slowest frame of late'
+		),
+		readout(
+			'CPU a frame · of it the simulation',
+			(client) => {
+				const m = meterOf(client)
+				return m ? `${m.cpuMs.toFixed(1)} ms · ${m.simMs.toFixed(1)} ms` : '…'
+			},
+			'What the page’s own work takes a frame, and how much of that is the game’s rules (the rest is drawing)'
+		),
+		readout(
+			'Draws a frame',
+			(client) => {
+				const m = meterOf(client)
+				return m ? String(m.draws) : '…'
+			},
+			'Draw calls the graphics card is sent a frame: fewer is cheaper, and a baked crowd is a handful'
+		)
+	]
+}
+
+/** How many of the world's units are alive, by what they are (a type's id, or any of them), as the player sees them */
+export function countUnits(client: GameClientApi, test: (type: string) => boolean = () => true): number {
+	let count = 0
+	for (const each of client.session.snapshot().entities) if (each.health > 0 && test(each.type)) count++
+	return count
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Colour grades made in code: look-up tables (`.3dl`, a colour in for every colour out) written as text from a
+ * function of a colour, and handed to the picture as files of their own. A grade is usually a file a colourist made
+ * (`MapPictureLook.grade: 'grades/film.3dl'` in the game's `textures/`); here the picture's `resolve` is taught where
+ * these are, so the same field takes them
+ */
+import type { GameClientApi } from '@v12-engine/client'
+
+type Rgb = [number, number, number]
+
+/** How many steps of each colour the tables have: 17 is what colourists' tools write */
+const SIZE = 17
+
+const clamp = (v: number) => Math.min(1, Math.max(0, v))
+const luma = ([r, g, b]: Rgb) => r * 0.2126 + g * 0.7152 + b * 0.0722
+const mix = (a: Rgb, b: Rgb, t: number): Rgb => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t]
+/** More apart from the middle grey, by `amount` (1 as it is) */
+const contrast = (v: number, amount: number) => clamp(0.5 + (v - 0.5) * amount)
+/** An S curve: darks darker, lights lighter, by `amount` (0 as it is) */
+const curve = (v: number, amount: number) => clamp(v + (v - v * v) * (v - 0.5) * amount * 4)
+
+/** The grades, by name: what each does to a colour */
+export const GRADES: Record<string, (color: Rgb) => Rgb> = {
+	// the blockbuster's: shadows to teal, skin and highlights to orange
+	'Teal and orange': (color) => {
+		const y = luma(color)
+		const toned = mix([0.1, 0.32, 0.38], [1, 0.72, 0.45], y)
+		return mix(color, toned, 0.35).map((v) => curve(v, 0.6)) as Rgb
+	},
+	// silver kept in the print: less colour, harder light
+	'Bleach bypass': (color) => {
+		const y = luma(color)
+		return mix(color, [y, y, y], 0.6).map((v) => curve(contrast(v, 1.15), 0.9)) as Rgb
+	},
+	// slide film in the wrong chemicals: greens and yellows pushed, blue shadows
+	'Cross process': ([r, g, b]) => [curve(r, 1.1), clamp(g * 1.05 + 0.03), clamp(b * 0.75 + 0.12)],
+	// a warm old print, faded blacks
+	'Warm film': ([r, g, b]) => [clamp(r * 0.92 + 0.08), clamp(g * 0.86 + 0.06), clamp(b * 0.7 + 0.05)],
+	// cold and blue, as films shoot night by day
+	Moonlight: (color) => {
+		const y = luma(color)
+		return [clamp(y * 0.55), clamp(y * 0.75 + 0.02), clamp(y * 1.05 + 0.06)]
+	},
+	// as the colour came out of an early colour film: two strips, red and cyan
+	'Two strip': ([r, g, b]) => {
+		const cyan = (g + b) / 2
+		return [clamp(r), clamp(cyan * 0.9 + r * 0.1), clamp(cyan)]
+	}
+}
+
+/** A grade as the text of a `.3dl` file: the steps on the first line, then a colour out for each in, red slowest, blue fastest */
+export function threeDl(grade: (color: Rgb) => Rgb): string {
+	const top = 4095
+	const steps = Array.from({ length: SIZE }, (_, i) => Math.round((i / (SIZE - 1)) * 1023))
+	const lines = [steps.join(' ')]
+	for (let r = 0; r < SIZE; r++)
+		for (let g = 0; g < SIZE; g++)
+			for (let b = 0; b < SIZE; b++) {
+				const out = grade([r / (SIZE - 1), g / (SIZE - 1), b / (SIZE - 1)])
+				lines.push(out.map((v) => Math.round(clamp(v) * top)).join(' '))
+			}
+	// Babylon reads the table as a share of its brightest value: one more of full white past its end (read, and left
+	// out of the table) so that a grade that darkens is not brightened back
+	lines.push(`${top} ${top} ${top}`)
+	return lines.join('\n')
+}
+
+/**
+ * Teaches the picture where the grades are: `grades/<name>.3dl` resolved to a file made in the page (a blob, which
+ * Babylon reads as a `.3dl`). Gives back what forgets them again
+ */
+export function teachGrades(client: GameClientApi): () => void {
+	const picture = client.picture
+	const before = picture.resolve
+	const urls = new Map<string, string>()
+	for (const [name, grade] of Object.entries(GRADES))
+		urls.set(gradePath(name), URL.createObjectURL(new Blob([threeDl(grade)], { type: 'text/plain' })))
+	picture.resolve = (path) => urls.get(path) ?? before(path)
+	return () => {
+		picture.resolve = before
+		for (const url of urls.values()) URL.revokeObjectURL(url)
+	}
+}
+
+/** The path a grade is known by */
+export const gradePath = (name: string): string => `grades/${name.toLowerCase().replace(/ /g, '-')}.3dl`