@v12-engine/create 0.1.1 → 0.4.0

package/starters/examples/src/examples/custom-animation/looks.ts

@@ -0,0 +1,523 @@
+/**
+ * The examples of moves made in code, on the client's side. Two ways in: a look's `pose` (`UnitLook.pose`), called
+ * every frame after the client has placed the unit, to move, turn and squash its whole body (the hops, the waddle, the
+ * springs, the banking); and the model's bones, turned after the clips have posed them (`./bones.ts`: the look, the
+ * reach). And a renderer of the game's own for what is not a unit at all (`./runes.ts`)
+ */
+import { MeshBuilder } from '@babylonjs/core/Meshes/meshBuilder.js'
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial.js'
+import { Color3 } from '@babylonjs/core/Maths/math.color.js'
+import { Vector3 } from '@babylonjs/core/Maths/math.vector.js'
+import type { EntityView, GameClientApi, GameView, ShapeDef, UnitLook } from '@v12-engine/client'
+import { presetFx } from '@v12-engine/client'
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode.js'
+import { button, type CategoryLooks, readout, slider, toggle } from '../../shell/look'
+import { character, hold, person, TWO_HANDED } from '../common/looks'
+import { afterClips, aimBone, approach, boneOf, groundUnder, trackPointer, turnBone, worldOf } from './bones'
+import { MOVE, summon } from './index'
+import { runesRenderer } from './runes'
+
+// ---- a pose of one's own: what each unit keeps from frame to frame, by its id
+
+/** What a pose keeps of a unit between frames: where it was, how fast it went, where it is in its step */
+interface Kept {
+	x: number
+	z: number
+	facing: number
+	speed: number
+	turn: number
+	phase: number
+	/** A spring's lean, and how fast it leans, across and along (the springs) */
+	lean: { x: number; z: number; vx: number; vz: number }
+	health: number
+}
+const kept = new Map<number, Kept>()
+/** What the poses kept, forgotten as an example is left: the next one's units start afresh */
+const forget = () => kept.clear()
+
+/** What a pose keeps of this unit, its speed and its turning measured from where it is drawn now and was last frame */
+function measure(entity: EntityView, root: TransformNode, dt: number): Kept {
+	let own = kept.get(entity.id)
+	if (!own) {
+		own = {
+			x: root.position.x,
+			z: root.position.z,
+			facing: root.rotation.y,
+			speed: 0,
+			turn: 0,
+			phase: 0,
+			lean: { x: 0, z: 0, vx: 0, vz: 0 },
+			health: entity.health
+		}
+		kept.set(entity.id, own)
+	}
+	if (dt > 0) {
+		const speed = Math.hypot(root.position.x - own.x, root.position.z - own.z) / dt
+		let turned = root.rotation.y - own.facing
+		turned = Math.atan2(Math.sin(turned), Math.cos(turned))
+		// smoothed: the snapshots come a few times a second, a frame's own step is uneven
+		own.speed = approach(own.speed, speed, 10, dt)
+		own.turn = approach(own.turn, turned / dt, 6, dt)
+	}
+	own.x = root.position.x
+	own.z = root.position.z
+	own.facing = root.rotation.y
+	return own
+}
+
+// ---- the slimes: hops
+
+/** How squashy the slimes are, from the card: 0 not at all */
+const slimes = { squash: 0.6 }
+
+/** A slime hops while it goes: up in an arc each hop, stretched tall as it leaves and comes down, squashed flat as it lands */
+function hop(entity: EntityView, root: TransformNode, frame: { dt: number; time: number }): void {
+	const own = measure(entity, root, frame.dt)
+	const going = Math.min(own.speed / 2, 1)
+	// it finishes the hop it is in before it stops
+	const inHop = own.phase % 1
+	if (going > 0.1 || inHop > 0.02) own.phase += frame.dt * 2.4
+	else own.phase = 0
+	const t = own.phase % 1
+	const height = Math.sin(t * Math.PI)
+	const rising = Math.cos(t * Math.PI)
+	let tall = 1
+	if (own.phase > 0) {
+		// stretched by how fast it goes up or down; squashed in the moment it touches the ground
+		tall += slimes.squash * 0.35 * Math.abs(rising) * height
+		if (t < 0.12) tall -= slimes.squash * 0.45 * (1 - t / 0.12)
+		if (t > 0.92) tall -= slimes.squash * 0.3 * ((t - 0.92) / 0.08)
+	} else tall += Math.sin(frame.time * 3 + entity.id) * 0.04 * (0.5 + slimes.squash)
+	root.position.y += height * 0.7 * (own.phase > 0 ? 1 : 0)
+	// as much of it as before: what it gains in height it loses across
+	root.scaling.y *= tall
+	root.scaling.x /= Math.sqrt(tall)
+	root.scaling.z /= Math.sqrt(tall)
+}
+
+// ---- the waddlers: a walk of rocks and bobs
+
+/** A waddler rocks from foot to foot as it walks and bobs on each step, leans forward as fast as it goes, and into its turns */
+function waddle(entity: EntityView, root: TransformNode, frame: { dt: number; time: number }): void {
+	const own = measure(entity, root, frame.dt)
+	const going = Math.min(own.speed / 2.2, 1)
+	own.phase += frame.dt * (1 + own.speed * 2.2)
+	root.rotation.z += Math.sin(own.phase * Math.PI) * 0.22 * going - Math.max(-0.35, Math.min(0.35, own.turn * 0.18))
+	root.rotation.x += 0.12 * going
+	root.position.y += Math.abs(Math.cos(own.phase * Math.PI)) * 0.12 * going
+	// standing, it breathes
+	root.scaling.y *= 1 + Math.sin(frame.time * 2.5 + entity.id) * 0.02 * (1 - going)
+}
+
+// ---- the jellies: springs
+
+/** The springs of the jellies, from the card: how stiff (how fast they sway back), how damped (how soon they settle) */
+const springs = { stiffness: 90, damping: 5 }
+
+/**
+ * A jelly sways away from each blow and back on a spring until it settles: a hit (its health down since last frame)
+ * pushes the spring away from the brute, which stands to its west. Each frame the spring pulls it back by how far it
+ * leans (`stiffness`) and slows it by how fast it moves (`damping`)
+ */
+function wobble(entity: EntityView, root: TransformNode, frame: { dt: number; time: number }): void {
+	const own = measure(entity, root, frame.dt)
+	const { lean } = own
+	if (entity.health < own.health - 3) {
+		// away from the brute, which stands to its west, and a little to one side or the other
+		lean.vx += 2.6
+		lean.vz += Math.sin(frame.time * 7 + entity.id) * 1.2
+	}
+	own.health = entity.health
+	// a few small steps a frame, so a stiff spring does not fly apart on a long frame
+	const steps = 4
+	const dt = frame.dt / steps
+	for (let i = 0; i < steps; i++) {
+		lean.vx += (-springs.stiffness * lean.x - springs.damping * lean.vx) * dt
+		lean.vz += (-springs.stiffness * lean.z - springs.damping * lean.vz) * dt
+		lean.x += lean.vx * dt
+		lean.z += lean.vz * dt
+	}
+	root.rotation.x += lean.z
+	root.rotation.z -= lean.x
+	// squashed by how hard it is moving: a jelly
+	const squash = 1 - Math.min(0.3, Math.hypot(lean.vx, lean.vz) * 0.05)
+	root.scaling.y *= squash
+	root.scaling.x /= Math.sqrt(squash)
+	root.scaling.z /= Math.sqrt(squash)
+}
+
+// ---- the glider: banking
+
+/** The glider banks as hard as it turns, rises and falls gently along its way, and pitches with it */
+function bank(entity: EntityView, root: TransformNode, frame: { dt: number; time: number }): void {
+	const own = measure(entity, root, frame.dt)
+	own.phase = approach(own.phase, Math.max(-1.1, Math.min(1.1, own.turn * 0.75)), 4, frame.dt)
+	root.rotation.z -= own.phase
+	const climb = Math.cos(frame.time * 0.8) * 0.8
+	root.position.y += Math.sin(frame.time * 0.8) * 1.0
+	root.rotation.x -= climb * 0.25
+}
+
+// ---- the looks of the category's units
+
+const shape = (
+	shape: ShapeDef['shape'],
+	size: ShapeDef['size'],
+	offset: ShapeDef['offset'],
+	color: ShapeDef['color'],
+	own: Partial<ShapeDef> = {}
+): ShapeDef => ({
+	shape,
+	size,
+	offset,
+	color,
+	...own
+})
+const WHITE: [number, number, number] = [0.97, 0.97, 0.95]
+const BLACK: [number, number, number] = [0.05, 0.05, 0.08]
+
+const looks: Record<string, UnitLook> = {
+	[MOVE.customAnimationKnight]: {
+		height: 1.8,
+		model: character('knight', 0.7, { hold: [hold('sword_1handed'), hold('shield_round', 'l')] }),
+		shapes: person(1.8)
+	},
+	// the slimes, waddlers, jellies and the glider are a few solids on purpose: no model and no clips, every move theirs
+	// is the look's `pose`, in code
+	[MOVE.customAnimationSlime]: {
+		height: 0.9,
+		shapes: [
+			shape('sphere', [0.95, 0.75, 0.95], [0, 0.36, 0], [0.35, 0.82, 0.4]),
+			shape('sphere', [0.22, 0.26, 0.12], [-0.17, 0.5, 0.38], WHITE),
+			shape('sphere', [0.22, 0.26, 0.12], [0.17, 0.5, 0.38], WHITE),
+			shape('sphere', [0.1, 0.13, 0.06], [-0.17, 0.5, 0.44], BLACK),
+			shape('sphere', [0.1, 0.13, 0.06], [0.17, 0.5, 0.44], BLACK)
+		],
+		pose: hop
+	},
+	[MOVE.customAnimationWaddler]: {
+		height: 1.1,
+		shapes: [
+			shape('sphere', [0.7, 0.85, 0.65], [0, 0.5, 0], [0.18, 0.22, 0.3]),
+			shape('sphere', [0.5, 0.6, 0.2], [0, 0.48, 0.24], WHITE),
+			shape('sphere', [0.46, 0.46, 0.46], [0, 1.05, 0.02], [0.18, 0.22, 0.3]),
+			shape('cone', [0.14, 0.22, 0.14], [0, 1.0, 0.3], [1, 0.6, 0.15], { tilt: Math.PI / 2 }),
+			shape('sphere', [0.08, 0.08, 0.05], [-0.1, 1.12, 0.22], WHITE),
+			shape('sphere', [0.08, 0.08, 0.05], [0.1, 1.12, 0.22], WHITE),
+			shape('box', [0.18, 0.06, 0.26], [-0.16, 0.03, 0.08], [1, 0.6, 0.15]),
+			shape('box', [0.18, 0.06, 0.26], [0.16, 0.03, 0.08], [1, 0.6, 0.15])
+		],
+		pose: waddle
+	},
+	[MOVE.customAnimationJelly]: {
+		height: 1.5,
+		shapes: [
+			shape('sphere', [1.3, 1.3, 1.3], [0, 0.62, 0], [0.85, 0.3, 0.6]),
+			shape('sphere', [0.24, 0.3, 0.12], [-0.22, 0.85, -0.6], WHITE),
+			shape('sphere', [0.24, 0.3, 0.12], [0.22, 0.85, -0.6], WHITE),
+			shape('sphere', [0.11, 0.14, 0.06], [-0.22, 0.85, -0.66], BLACK),
+			shape('sphere', [0.11, 0.14, 0.06], [0.22, 0.85, -0.66], BLACK)
+		],
+		pose: wobble
+	},
+	[MOVE.customAnimationBrute]: {
+		height: 2,
+		model: character('barbarian', 0.8, { hold: [hold('axe_2handed')] }),
+		attacks: [TWO_HANDED],
+		shapes: person(2)
+	},
+	[MOVE.customAnimationGlider]: {
+		height: 1,
+		altitude: 4,
+		motion: { bob: 0 },
+		shapes: [
+			shape('cone', [0.7, 2.9, 0.7], [0, 0, 0.15], [0.92, 0.9, 0.85], { tilt: Math.PI / 2 }),
+			shape('box', [5.2, 0.1, 1.3], [0, 0.03, -0.1], [0.85, 0.25, 0.2]),
+			shape('box', [1.8, 0.08, 0.65], [0, 0.08, -1.4], [0.85, 0.25, 0.2]),
+			shape('box', [0.08, 0.75, 0.55], [0, 0.36, -1.4], [0.92, 0.9, 0.85])
+		],
+		pose: bank
+	},
+	[MOVE.customAnimationAdept]: { height: 1.8, model: character('mage', 0.7, { hold: [hold('staff')] }), shapes: person(1.8) }
+}
+
+/** The one unit of a type the client knows, if it does */
+const one = (client: GameClientApi, type: string) => [...client.state.entities.values()].find((each) => each.def.id === type && each.health > 0)
+
+/** Puts the camera at a point, `distance` back and as steep as `pitch` */
+const stage = (client: GameClientApi, x: number, z: number, distance: number, pitch: number, yaw = 0) =>
+	client.camera.setPose({ x, z, distance, yaw, pitch })
+
+// ---- the look: the head and the chest turned to the point under the pointer
+
+const looking = { on: true, most: 1.2 }
+
+/** Every frame once the clip has posed the knight: its chest turned a third of the way to the point, its head the rest, eased */
+function lookAtPointer(client: GameClientApi): () => void {
+	const { scene } = client
+	const now = { yaw: 0, pitch: 0 }
+	const pointer = trackPointer(scene)
+	const stop = afterClips(scene, (dt) => {
+		const knight = one(client, MOVE.customAnimationKnight)
+		const root = knight && client.renderer.kit.model(knight.id)?.root
+		const head = knight && boneOf(client, knight.id, 'head')
+		const chest = knight && boneOf(client, knight.id, 'chest')
+		if (!knight || !root || !head || !chest) return
+		const facing = root.rotation.y
+		const at = worldOf(head)
+		const target = looking.on && pointer.at ? groundUnder(scene, pointer.at.x, pointer.at.y) : undefined
+		let yaw = 0
+		let pitch = 0
+		if (target) {
+			const dx = target.x - at.x
+			const dz = target.z - at.z
+			const away = Math.atan2(dx, dz) - facing
+			// how far round from where it faces, the short way, no farther than a neck and a waist turn
+			yaw = Math.max(-looking.most, Math.min(looking.most, Math.atan2(Math.sin(away), Math.cos(away))))
+			pitch = Math.min(0.7, Math.atan2(at.y, Math.hypot(dx, dz)) * 0.8)
+		}
+		now.yaw = approach(now.yaw, yaw, 8, dt)
+		now.pitch = approach(now.pitch, pitch, 8, dt)
+		turnBone(chest, now.yaw * 0.35, 0, facing)
+		turnBone(head, now.yaw * 0.65, now.pitch, facing + now.yaw * 0.35)
+	})
+	return () => {
+		stop()
+		pointer.stop()
+	}
+}
+
+// ---- the reach: the sword arm aimed at an orb, the lower arm then the upper, twice over
+
+const reaching = { pointer: false, on: true }
+
+function reachForOrb(client: GameClientApi): () => void {
+	const { scene } = client
+	const orb = MeshBuilder.CreateSphere('examples.orb', { diameter: 0.22, segments: 12 }, scene)
+	const material = new StandardMaterial('examples.orb', scene)
+	material.emissiveColor = new Color3(0.4, 0.85, 1)
+	material.disableLighting = true
+	orb.material = material
+	const pointer = trackPointer(scene)
+	let time = 0
+	const stop = afterClips(scene, (dt) => {
+		time += dt
+		const knight = one(client, MOVE.customAnimationKnight)
+		const root = knight && client.renderer.kit.model(knight.id)?.root
+		if (!knight || !root) return
+		const shoulder = boneOf(client, knight.id, 'upperarm.r')
+		const elbow = boneOf(client, knight.id, 'lowerarm.r')
+		const hand = boneOf(client, knight.id, 'hand.r')
+		if (!shoulder || !elbow || !hand) return
+		const base = root.position
+		// the orb: where the pointer is (no farther than a step from the knight), or wandering before it on its own
+		let target = new Vector3(
+			base.x + Math.sin(time * 0.9) * 0.9,
+			base.y + 1.05 + Math.sin(time * 1.7) * 0.45,
+			base.z - 0.75 + Math.cos(time * 0.6) * 0.35
+		)
+		const under = reaching.pointer && pointer.at ? groundUnder(scene, pointer.at.x, pointer.at.y) : undefined
+		if (under) {
+			const dx = under.x - base.x
+			const dz = under.z - base.z
+			const far = Math.hypot(dx, dz)
+			const k = far > 1.6 ? 1.6 / far : 1
+			target = new Vector3(base.x + dx * k, base.y + 1.1, base.z + dz * k)
+		}
+		orb.position.copyFrom(target)
+		if (!reaching.on) return
+		// a reach in two joints: the elbow aims the hand at the orb, then the shoulder does, twice over (CCD)
+		for (let pass = 0; pass < 2; pass++) {
+			aimBone(elbow, worldOf(hand), target, 0.8)
+			aimBone(shoulder, worldOf(hand), target, 0.8)
+		}
+	})
+	return () => {
+		stop()
+		pointer.stop()
+		orb.dispose()
+		material.dispose()
+	}
+}
+
+export const category: CategoryLooks = {
+	view: (view: GameView<any>) => ({
+		...view,
+		units: { ...view.units, looks: { ...view.units.looks, ...looks } },
+		fx: { ...view.fx, defs: { ...presetFx(['smoke-trail']), ...view.fx?.defs } }
+	}),
+	looks: {
+		'custom-animation-look-at': {
+			controls: [
+				toggle(
+					'Look at the pointer',
+					true,
+					(_client, on) => (looking.on = on),
+					'On, the knight’s head and chest turn to the ground under the pointer (move it over the field); off, they ease back to the clip'
+				),
+				slider(
+					'How far it turns',
+					{ min: 0.2, max: 1.8, step: 0.05, value: 1.2 },
+					(_client, value) => (looking.most = value),
+					'How far the knight may turn to follow the pointer, in radians either way: the waist and the neck together'
+				),
+				button(
+					'Play a swing',
+					(client) => {
+						const knight = one(client, MOVE.customAnimationKnight)
+						if (knight) client.playClip(knight.id, 'Melee_1H_Attack_Chop')
+					},
+					'The knight swings once: its head keeps looking while the clip moves the rest'
+				),
+				readout(
+					'Turned by',
+					() => 'scene.onAfterAnimationsObservable, after the clip',
+					'Where the code turns the bones: each frame, once the clip has posed them'
+				)
+			],
+			ready: (client) => {
+				Object.assign(looking, { on: true, most: 1.2 })
+				stage(client, 24, 23, 9, 0.75)
+				return lookAtPointer(client)
+			}
+		},
+		'custom-animation-reach': {
+			controls: [
+				toggle(
+					'Reach',
+					true,
+					(_client, on) => (reaching.on = on),
+					'On, the knight’s sword arm is turned toward the orb each frame; off, the arm is the clip’s alone'
+				),
+				toggle(
+					'The orb follows the pointer',
+					false,
+					(_client, on) => (reaching.pointer = on),
+					'On, the orb goes where the pointer is over the ground, no farther than a step from the knight; off, it wanders by itself'
+				),
+				button(
+					'Play a swing',
+					(client) => {
+						const knight = one(client, MOVE.customAnimationKnight)
+						if (knight) client.playClip(knight.id, 'Melee_1H_Attack_Stab')
+					},
+					'The knight stabs once: the reach is laid over the clip'
+				)
+			],
+			ready: (client) => {
+				Object.assign(reaching, { on: true, pointer: false })
+				stage(client, 24, 23.6, 8.5, 0.5)
+				return reachForOrb(client)
+			}
+		},
+		'custom-animation-hop': {
+			controls: [
+				slider(
+					'Squash and stretch',
+					{ min: 0, max: 1.5, step: 0.05, value: 0.6 },
+					(_client, value) => (slimes.squash = value),
+					'How much the slimes stretch as they leave the ground and squash as they land: 0 hops stiff'
+				)
+			],
+			ready: (client) => {
+				slimes.squash = 0.6
+				stage(client, 24, 22, 20, 0.7)
+				return forget
+			}
+		},
+		'custom-animation-waddle': {
+			controls: [
+				readout(
+					'Each frame',
+					() => 'rock, bob, lean: from how fast it goes and turns',
+					'What the pose works out for each waddler every frame, from its speed and its turning'
+				)
+			],
+			ready: (client) => {
+				stage(client, 24, 22, 16, 0.65)
+				return forget
+			}
+		},
+		'custom-animation-springs': {
+			controls: [
+				slider(
+					'Stiffness',
+					{ min: 10, max: 300, step: 5, value: 90 },
+					(_client, value) => (springs.stiffness = value),
+					'How hard the spring pulls it back upright: higher sways faster'
+				),
+				slider(
+					'Damping',
+					{ min: 0.5, max: 25, step: 0.5, value: 5 },
+					(_client, value) => (springs.damping = value),
+					'How soon a sway dies down: low wobbles on and on'
+				),
+				readout(
+					'Spring',
+					() => `stiffness ${springs.stiffness} · damping ${springs.damping}`,
+					'The two sliders’ values, which every jelly’s spring uses'
+				)
+			],
+			ready: (client) => {
+				springs.stiffness = 90
+				springs.damping = 5
+				stage(client, 25, 24, 21, 0.55)
+				return forget
+			}
+		},
+		'custom-animation-flight': {
+			controls: [
+				button(
+					'Follow it',
+					(client) => {
+						const glider = one(client, MOVE.customAnimationGlider)
+						if (glider) client.follow(glider.id)
+					},
+					'The camera follows the glider round its figure of eight: watch it bank into each turn'
+				),
+				button(
+					'Watch from above',
+					(client) => {
+						client.follow(null)
+						stage(client, 24, 23, 30, 0.8)
+					},
+					'The camera stops following and looks down on the whole figure of eight'
+				)
+			],
+			ready: (client) => {
+				stage(client, 24, 23, 30, 0.8)
+				let trail: ReturnType<GameClientApi['fx']['play']> | undefined
+				// the trail once the glider is drawn: on it, following it
+				const start = setInterval(() => {
+					const glider = one(client, MOVE.customAnimationGlider)
+					if (!glider || trail) return
+					trail = client.fx.play('smoke-trail', { on: glider.id, params: { color: '#e8eef5' } })
+					clearInterval(start)
+				}, 250)
+				return () => {
+					clearInterval(start)
+					trail?.stop()
+				}
+			}
+		},
+		'custom-animation-renderer': {
+			view: (view) => ({ ...view, renderers: [...(view.renderers ?? []), runesRenderer(MOVE.customAnimationAdept, [0.55, 0.85, 1])] }),
+			controls: [
+				button(
+					'Summon three more',
+					(client) => client.session.send(summon.make({})),
+					'Three more adepts pop in: the renderer is told of each and gives it three runes'
+				),
+				readout(
+					'Adepts · runes',
+					(client) => {
+						const adepts = [...client.state.entities.values()].filter((each) => each.def.id === MOVE.customAnimationAdept && each.health > 0).length
+						return `${adepts} · ${adepts * 3}`
+					},
+					'How many adepts there are, and the runes the renderer draws for them'
+				)
+			],
+			ready: (client) => stage(client, 24, 22.5, 16, 0.6)
+		}
+	}
+}

package/starters/examples/src/examples/custom-animation/runes.ts

@@ -0,0 +1,82 @@
+/**
+ * A renderer of the game's own (`GameView.renderers`): three runes that orbit every adept, made as one comes into view
+ * and taken away as it goes, moved every frame round where the client draws it. Made once from the client's render
+ * kit (`RenderKit`): its scene to make meshes in, `drawn` for where a unit is this frame, `timers` for a tween
+ */
+import { MeshBuilder } from '@babylonjs/core/Meshes/meshBuilder.js'
+import type { Mesh } from '@babylonjs/core/Meshes/mesh.js'
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode.js'
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial.js'
+import { Color3 } from '@babylonjs/core/Maths/math.color.js'
+import { ease, type FeatureRenderer, type RenderKit } from '@v12-engine/client'
+
+/** How many runes go round each, how far out, how fast (turns a second) */
+const RUNES = 3
+const RADIUS = 0.95
+const SPEED = 0.35
+
+/** The runes round the units of a type: `type` is the unit type's id */
+export const runesRenderer =
+	(type: string, color: [number, number, number]) =>
+	(kit: RenderKit): FeatureRenderer => {
+		const material = new StandardMaterial('examples.runes', kit.scene)
+		material.emissiveColor = new Color3(...color)
+		material.diffuseColor = Color3.Black()
+		material.disableLighting = true
+		// one rune made, the others its copies: the same mesh drawn three times a unit
+		const source = MeshBuilder.CreatePolyhedron('examples.rune', { type: 1, size: 0.13 }, kit.scene)
+		source.material = material
+		source.setEnabled(false)
+		/** Each adept's runes, by its id: the node they turn round, and the runes */
+		const orbits = new Map<number, { node: TransformNode; runes: Mesh[]; tween?: number; born: number }>()
+		let time = 0
+
+		const add = (id: number) => {
+			const node = new TransformNode(`examples.runes.${id}`, kit.scene)
+			const runes = Array.from({ length: RUNES }, (_, i) => {
+				const rune = source.clone(`examples.rune.${id}.${i}`, node)
+				rune.setEnabled(true)
+				return rune
+			})
+			node.scaling.setAll(0)
+			// popping in: from nothing to its size and a little past, and back (`ease.outBack`), over half a second
+			const tween = kit.timers.tween(0.5, (t) => node.scaling.setAll(ease.outBack(t)))
+			orbits.set(id, { node, runes, tween, born: time })
+		}
+		const remove = (id: number) => {
+			const orbit = orbits.get(id)
+			if (!orbit) return
+			if (orbit.tween !== undefined) kit.timers.cancel(orbit.tween)
+			orbit.node.dispose()
+			orbits.delete(id)
+		}
+
+		return {
+			sync: (changes) => {
+				for (const entity of changes.added) if (entity.def.id === type) add(entity.id)
+				for (const entity of changes.removed) remove(entity.id)
+				// one that died stays in the state a while, lying: its runes go at once
+				for (const entity of changes.changed) if (entity.health <= 0) remove(entity.id)
+			},
+			frame: (_alpha, dt) => {
+				time += dt
+				for (const [id, orbit] of orbits) {
+					const drawn = kit.drawn(id)
+					orbit.node.setEnabled(!!drawn?.visible)
+					if (!drawn?.visible) continue
+					orbit.node.position.set(drawn.position.x, drawn.position.y + 1.1, drawn.position.z)
+					orbit.runes.forEach((rune, i) => {
+						const angle = (time * SPEED + i / RUNES) * Math.PI * 2 + id
+						// round in a ring that tilts as it turns, each rune bobbing on a beat of its own, spinning
+						rune.position.set(Math.cos(angle) * RADIUS, Math.sin(angle * 2 + i) * 0.18, Math.sin(angle) * RADIUS)
+						rune.rotation.set(time * 2 + i, time * 3, 0)
+					})
+				}
+			},
+			dispose: () => {
+				for (const id of [...orbits.keys()]) remove(id)
+				source.dispose()
+				material.dispose()
+			}
+		}
+	}