@v12-engine/create 0.1.0 → 0.4.0

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

@@ -0,0 +1,26 @@
+/**
+ * A meteor, on the rules' side: footmen standing about a field for it to fall among. The meteor is the view's effect
+ * (`./meteor.look.ts`); the rules could call one down for every player with `world.fx('customFx.meteor', { at })`
+ */
+import { exactMath } from '@v12-engine/engine'
+import { PLAYER, UNIT } from '../common/units'
+import type { ExampleDef } from '../define'
+
+export const METEOR_AT = { x: 24, z: 25 }
+
+export const meteor: ExampleDef = {
+	id: 'custom-fx-meteor',
+	category: 'custom-fx',
+	title: 'A meteor',
+	summary:
+		'An effect with a way of its own (`path`): a burning rock falls from the sky trailing fire and light, then the blast, a ring thrown out, rocks flung that trail smoke as they fly (particles that emit particles), the ground cracked and burning. Call one down, or a shower.',
+	tags: ['path', 'meteor', 'sub-emitters', 'trail', 'shake', 'decal', 'explosion', 'FxDef'],
+	environment: 'dusk',
+	start: (world) => {
+		for (let i = 0; i < 8; i++) {
+			const angle = (i / 8) * Math.PI * 2
+			world.spawn(UNIT.footman, { at: { x: METEOR_AT.x + exactMath.cos(angle) * 6, z: METEOR_AT.z + exactMath.sin(angle) * 6 }, owner: PLAYER })
+		}
+	},
+	source: ['examples/custom-fx/meteor.ts', 'examples/custom-fx/meteor.look.ts']
+}

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

@@ -0,0 +1,193 @@
+/**
+ * An effect from parts, on the client's side: `customFx.blast`, a timeline of parts (`FxPart`) each starting `at`
+ * seconds in and lasting `for`, every field a value or a function of the knobs (`params`). Particles burst and stream;
+ * a sub-emitter throws sparks off each spark as it dies; a light and a shake grow with `size`; a scorch is laid; another
+ * effect (smoke) plays as a part. A ready-made effect is changed by its knobs alone with `fx.extend`
+ */
+import { fx, type FxDef, type FxHandle, type GameClientApi } from '@v12-engine/client'
+import { button, type ExampleLook, select, slider, toggle } from '../../shell/look'
+import { aim } from '../fx/stage'
+import { BLAST_AT } from './parts'
+
+/** The blast: everything in it reads `size`, `color` (its heart) and `tint` (its edge) */
+const blast: FxDef = {
+	params: { size: 1, color: '#fff0b0', tint: '#ff5a14' },
+	knobs: {
+		size: { min: 0.3, max: 3, step: 0.1, about: 'How big the blast is' },
+		color: { about: 'Its heart' },
+		tint: { about: 'Its edge, its sparks' }
+	},
+	parts: [
+		// a white flash: a few big soft dots, gone in a blink
+		{
+			particles: {
+				bursts: [{ at: 0, count: 6 }],
+				lifetime: 0.15,
+				size: (p) => [4 * Number(p.size), 6 * Number(p.size)],
+				color: '#ffffff',
+				texture: 'flare'
+			}
+		},
+		// the fireball: puffs flung out and slowing, from the heart's colour to the edge's to smoke
+		{
+			particles: {
+				bursts: [{ at: 0, count: 40 }],
+				shape: { type: 'sphere', radius: 0.3 },
+				speed: (p) => [2 * Number(p.size), 5 * Number(p.size)],
+				drag: 0.9,
+				lifetime: [0.5, 0.9],
+				size: (p) => [
+					[0, 1.2 * Number(p.size)],
+					[1, 2.8 * Number(p.size)]
+				],
+				color: (p) => [
+					[0, String(p.color)],
+					[0.35, String(p.tint)],
+					[1, '#2a201a']
+				],
+				texture: 'puff',
+				rotation: [-1, 1]
+			}
+		},
+		// sparks thrown high, falling, each throwing a few small ones as it dies (`sub`)
+		{
+			particles: {
+				bursts: [{ at: 0, count: 50 }],
+				shape: 'hemisphere',
+				spread: 1,
+				speed: (p) => [6 * Number(p.size), 12 * Number(p.size)],
+				gravity: 9,
+				lifetime: [0.6, 1.2],
+				size: [0.25, 0.05],
+				color: (p) => [String(p.color), String(p.tint)],
+				texture: 'spark',
+				billboard: 'stretched',
+				stretch: 3,
+				sub: [
+					{
+						on: 'death',
+						particles: {
+							bursts: [{ at: 0, count: 4 }],
+							shape: 'sphere',
+							speed: [1, 3],
+							lifetime: 0.3,
+							size: [0.12, 0],
+							color: (p) => String(p.tint),
+							texture: 'dot'
+						}
+					}
+				]
+			}
+		},
+		// a ring of dust thrown out along the ground
+		{
+			at: 0.05,
+			particles: {
+				bursts: [{ at: 0, count: 30 }],
+				shape: { type: 'ring', radius: 0.4 },
+				speed: (p) => [4 * Number(p.size), 6 * Number(p.size)],
+				drag: 0.95,
+				lifetime: [0.8, 1.4],
+				size: [0.8, 2],
+				color: '#9a8466',
+				texture: 'puff',
+				blend: 'alpha',
+				lit: true
+			}
+		},
+		// the light, as bright as the blast is big, fading; the view shaken; the ground scorched for half a minute
+		{ light: { color: (p) => String(p.tint), intensity: (p) => 5 * Number(p.size), range: (p) => 9 * Number(p.size), fade: 0.7 } },
+		{ shake: (p) => ({ strength: 0.35 * Number(p.size), time: 0.35 }) },
+		{ at: 0.1, decal: { size: (p) => 3.2 * Number(p.size), time: 30, color: '#140d08' } },
+		// smoke rising after, another effect of its own played as a part for 5 seconds
+		{ at: 0.25, for: 5, fx: 'customFx.smoke', params: (p) => ({ size: p.size }) }
+	]
+}
+
+/** The smoke after: one emitter, made with `fx.particles` */
+const smoke: FxDef = fx.particles(
+	{
+		rate: (p) => 18 * Number(p.size),
+		over: { rate: [1, 0] },
+		shape: { type: 'sphere', radius: 0.6 },
+		speed: [0.6, 1.4],
+		direction: [0, 1, 0],
+		lifetime: [2.5, 4],
+		size: (p) => [
+			[0, 0.8 * Number(p.size)],
+			[1, 3 * Number(p.size)]
+		],
+		color: ['#4a4440', '#2a2826'],
+		alpha: [0.6, 0],
+		texture: 'puff',
+		blend: 'alpha',
+		wind: 1,
+		lit: true
+	},
+	{ params: { size: 1 } }
+)
+
+/** The effects of this example, taken into the game's view: the blast, its smoke, and a fire made frost */
+export const partsFx: Record<string, FxDef> = {
+	'customFx.blast': blast,
+	'customFx.smoke': smoke,
+	// the ready-made fire with knobs of its own: blue flames, a cold light, no smoke
+	'customFx.frostFire': fx.extend('fire', { color: '#c8f4ff', tint: '#2a7fff', smoke: false, light: 2 })
+}
+
+/** The colours the card offers, as the blast's heart and edge */
+const COLORS: Record<string, { color: string; tint: string }> = {
+	Fire: { color: '#fff0b0', tint: '#ff5a14' },
+	Frost: { color: '#f0ffff', tint: '#38a8ff' },
+	Venom: { color: '#f4ffb0', tint: '#58d020' },
+	Arcane: { color: '#ffe0ff', tint: '#a040ff' }
+}
+
+const chosen = { size: 1, colors: 'Fire' }
+let frostFire: FxHandle | undefined
+
+/** Plays the blast where it goes off, with the card's knobs */
+const play = (client: GameClientApi) => client.fx.play('customFx.blast', { at: BLAST_AT, params: { size: chosen.size, ...COLORS[chosen.colors] } })
+
+export const partsLook: ExampleLook = {
+	controls: [
+		button('Blast', (client) => play(client), 'Plays the blast again, at the size and colour chosen'),
+		slider(
+			'Size',
+			{ min: 0.3, max: 3, step: 0.1, value: chosen.size },
+			(_client, size) => (chosen.size = size),
+			'How big the next blast is, its light and shake too (the knob `size`, read by every part): press Blast to see it'
+		),
+		select(
+			'Colour',
+			Object.keys(COLORS),
+			chosen.colors,
+			(client, name) => {
+				chosen.colors = name
+				play(client)
+			},
+			'The blast’s colours, its heart and its edge: choosing plays it'
+		),
+		toggle(
+			'Frost fire',
+			true,
+			(client, on) => {
+				frostFire?.stop({ mode: 'fade', fade: 0.6 })
+				frostFire = on ? client.fx.play('customFx.frostFire', { at: { x: BLAST_AT.x - 6, z: BLAST_AT.z + 2 } }) : undefined
+			},
+			'The blue fire to the left: the ready-made fire made frost by its knobs alone (`fx.extend`)'
+		)
+	],
+	ready: (client) => {
+		chosen.size = 1
+		chosen.colors = 'Fire'
+		aim(client, { x: BLAST_AT.x - 2, z: BLAST_AT.z + 0.5 }, 18, 0.6)
+		frostFire = client.fx.play('customFx.frostFire', { at: { x: BLAST_AT.x - 6, z: BLAST_AT.z + 2 } })
+		const first = window.setTimeout(() => play(client), 400)
+		return () => {
+			window.clearTimeout(first)
+			frostFire?.stop({ mode: 'at-once' })
+			frostFire = undefined
+		}
+	}
+}

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

@@ -0,0 +1,21 @@
+/**
+ * An effect made of parts, on the rules' side: a knight to stand by it. The effect is the view's (`./parts.look.ts`);
+ * the rules could play it too, for every player, with `world.fx('customFx.blast', { at, params })`
+ */
+import { PLAYER, UNIT } from '../common/units'
+import type { ExampleDef } from '../define'
+
+export const BLAST_AT = { x: 25.5, z: 25 }
+
+export const parts: ExampleDef = {
+	id: 'custom-fx-parts',
+	category: 'custom-fx',
+	title: 'An effect from parts',
+	summary:
+		'A blast of your own, written as a timeline of parts: a flash, sparks that throw sparks of their own as they die, a fireball, a light, a shake, a scorch, smoke after. Its knobs (size, colour) are sliders here; a ready-made fire is made frost with `fx.extend`.',
+	tags: ['FxDef', 'parts', 'knobs', 'params', 'particles', 'sub-emitters', 'fx.extend', 'timeline', 'shake', 'decal'],
+	start: (world) => {
+		world.spawn(UNIT.knight, { at: { x: BLAST_AT.x - 4, z: BLAST_AT.z - 1 }, owner: PLAYER })
+	},
+	source: ['examples/custom-fx/parts.ts', 'examples/custom-fx/parts.look.ts']
+}

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

@@ -0,0 +1,193 @@
+/**
+ * Two portals, on the client's side. `customFx.gate` is parts: one made in code (`make`: a frame, and a disc drawn by a
+ * shader of its own, a swirl turning inward), motes drawn in toward it, and its light. `customFx.warp` is the flash the
+ * rules play where a footman leaves and comes: a burst, a ring, a light. The gates are put on the map as the example
+ * opens (`MapEnvironment.fx`), the warps played by the rules
+ */
+import { Constants } from '@babylonjs/core/Engines/constants.js'
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial.js'
+import { Color3 } from '@babylonjs/core/Maths/math.color.js'
+import { CreateDisc } from '@babylonjs/core/Meshes/Builders/discBuilder.js'
+import { CreateTorus } from '@babylonjs/core/Meshes/Builders/torusBuilder.js'
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode.js'
+import type { FxDef, FxInstance, FxContext } from '@v12-engine/client'
+import { button, type ExampleLook } from '../../shell/look'
+import { aim } from '../fx/stage'
+import { PORTALS, stepThrough } from './portal'
+import { type TwoShaders, shaderMaterial } from './shader'
+
+/**
+ * The swirl: in polar terms about the disc's middle, arms that wind tighter toward it and turn with time, between two
+ * colours, bright in the middle, fading out at the rim
+ */
+const SWIRL: TwoShaders = {
+	glsl: {
+		vertex: `precision highp float;
+attribute vec3 position;
+attribute vec2 uv;
+uniform mat4 worldViewProjection;
+varying vec2 vUV;
+void main() {
+	gl_Position = worldViewProjection * vec4(position, 1.0);
+	vUV = uv;
+}`,
+		fragment: `precision highp float;
+uniform float time;
+uniform vec3 inner;
+uniform vec3 outer;
+varying vec2 vUV;
+void main() {
+	vec2 p = vUV * 2.0 - 1.0;
+	float r = length(p);
+	float a = atan(p.y, p.x);
+	float arms = sin(a * 5.0 + 6.0 / (r + 0.15) - time * 4.0) * 0.5 + 0.5;
+	float fine = sin(a * 11.0 - 9.0 / (r + 0.2) + time * 2.5) * 0.5 + 0.5;
+	vec3 color = mix(outer, inner, arms * (1.0 - r) + 0.25) + vec3(1.0) * pow(max(1.0 - r * 1.6, 0.0), 3.0);
+	float alpha = (0.35 + arms * 0.5 + fine * 0.25) * smoothstep(1.0, 0.82, r);
+	gl_FragColor = vec4(color * alpha, alpha);
+}`
+	},
+	wgsl: {
+		vertex: `attribute position: vec3f;
+attribute uv: vec2f;
+uniform worldViewProjection: mat4x4f;
+varying vUV: vec2f;
+@vertex
+fn main(input: VertexInputs) -> FragmentInputs {
+	vertexOutputs.position = uniforms.worldViewProjection * vec4f(vertexInputs.position, 1.0);
+	vertexOutputs.vUV = vertexInputs.uv;
+}`,
+		fragment: `uniform time: f32;
+uniform inner: vec3f;
+uniform outer: vec3f;
+varying vUV: vec2f;
+@fragment
+fn main(input: FragmentInputs) -> FragmentOutputs {
+	let p = fragmentInputs.vUV * 2.0 - 1.0;
+	let r = length(p);
+	let a = atan2(p.y, p.x);
+	let arms = sin(a * 5.0 + 6.0 / (r + 0.15) - uniforms.time * 4.0) * 0.5 + 0.5;
+	let fine = sin(a * 11.0 - 9.0 / (r + 0.2) + uniforms.time * 2.5) * 0.5 + 0.5;
+	let color = mix(uniforms.outer, uniforms.inner, arms * (1.0 - r) + 0.25) + vec3f(1.0) * pow(max(1.0 - r * 1.6, 0.0), 3.0);
+	let alpha = (0.35 + arms * 0.5 + fine * 0.25) * smoothstep(1.0, 0.82, r);
+	fragmentOutputs.color = vec4f(color * alpha, alpha);
+}`
+	}
+}
+
+/** A colour of the knobs as Babylon's */
+const color3 = (hex: unknown) => Color3.FromHexString(String(hex))
+
+/** The gate made in code: a stone-and-light frame standing up, the swirl inside it, turning */
+function gate({ scene, anchor, params }: FxContext): FxInstance {
+	const root = new TransformNode('customFx.gate', scene)
+	root.parent = anchor
+	root.position.y = 1.7
+	const frame = CreateTorus('customFx.gateFrame', { diameter: 3.2, thickness: 0.28, tessellation: 48 }, scene)
+	frame.rotation.x = Math.PI / 2
+	frame.parent = root
+	const stone = new StandardMaterial('customFx.gateStone', scene)
+	stone.diffuseColor = new Color3(0.25, 0.22, 0.28)
+	stone.emissiveColor = color3(params.outer).scale(0.6)
+	frame.material = stone
+	const disc = CreateDisc('customFx.gateSwirl', { radius: 1.5, tessellation: 64 }, scene)
+	disc.parent = root
+	const swirl = shaderMaterial('customFxSwirl', scene, SWIRL, ['time', 'inner', 'outer'], ['position', 'uv'])
+	swirl.alphaMode = Constants.ALPHA_ADD
+	swirl.backFaceCulling = false
+	disc.material = swirl
+	for (const mesh of [frame, disc]) mesh.isPickable = false
+	let time = 0
+	let inner = color3(params.inner)
+	let outer = color3(params.outer)
+	return {
+		update: (dt) => {
+			time += dt
+			swirl.setFloat('time', time)
+			swirl.setColor3('inner', inner)
+			swirl.setColor3('outer', outer)
+		},
+		set: (next) => {
+			inner = color3(next.inner)
+			outer = color3(next.outer)
+			stone.emissiveColor = outer.scale(0.6)
+		},
+		dispose: () => {
+			root.dispose(false, true)
+			swirl.dispose()
+		}
+	}
+}
+
+/** The effects of this example, taken into the game's view */
+export const portalFx: Record<string, FxDef> = {
+	'customFx.gate': {
+		params: { inner: '#e6d4ff', outer: '#7a3cff' },
+		parts: [
+			{ make: gate },
+			// motes drawn in from all round toward the middle of the swirl
+			{
+				offset: [0, 1.7, 0],
+				particles: {
+					rate: 50,
+					shape: { type: 'sphere', radius: 2.6, rim: true },
+					speed: [-2.6, -1.8],
+					lifetime: 1,
+					size: [0.05, 0.2],
+					color: (p) => [String(p.outer), String(p.inner)],
+					alpha: [0, 1],
+					texture: 'flare'
+				}
+			},
+			{ offset: [0, 1.7, 0.6], light: { color: (p) => String(p.outer), intensity: 2.2, range: 9, flicker: 0.1 } }
+		]
+	},
+	'customFx.warp': {
+		parts: [
+			{
+				particles: {
+					bursts: [{ at: 0, count: 40 }],
+					shape: { type: 'cylinder', radius: 0.5, height: 2 },
+					direction: [0, 1, 0],
+					speed: [2, 6],
+					lifetime: [0.4, 0.8],
+					size: [0.3, 0],
+					color: ['#ffffff', '#b07aff'],
+					texture: 'spark',
+					billboard: 'stretched',
+					stretch: 3
+				}
+			},
+			{ particles: { bursts: [{ at: 0, count: 3 }], lifetime: 0.25, size: [3, 5], color: '#d8c0ff', texture: 'flare', order: 1 }, offset: [0, 1, 0] },
+			{ fx: 'shockwave', params: { size: 0.5, color: '#c8a8ff', dust: false } },
+			{ light: { color: '#b07aff', intensity: 4, range: 8, fade: 0.5 } }
+		]
+	}
+}
+
+export const portalLook: ExampleLook = {
+	controls: [
+		button(
+			'Send one through',
+			(client) => client.session.send(stepThrough.make({})),
+			'A footman steps into one gate and out of the other: a flash at both ends'
+		),
+		button(
+			'Send them all',
+			(client) => {
+				for (let i = 0; i < 4; i++) window.setTimeout(() => client.session.send(stepThrough.make({})), i * 400)
+			},
+			'Four footmen through, one after another'
+		)
+	],
+	ready: (client) => {
+		// the gates laid on the map as its own effects, the second a warmer one
+		client.setEnvironment({
+			fx: [
+				{ id: 1, name: 'gate 1', fx: 'customFx.gate', ...PORTALS[0] },
+				{ id: 2, name: 'gate 2', fx: 'customFx.gate', ...PORTALS[1], params: { inner: '#fff0c8', outer: '#ff7a1a' } }
+			]
+		})
+		aim(client, { x: (PORTALS[0].x + PORTALS[1].x) / 2, z: PORTALS[0].z - 1 }, 25, 0.45)
+	}
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Two portals, on the rules' side: footmen by the first, and a command that sends one through, from whichever portal
+ * he is nearer to the other, with a flash at both ends that every player sees (`world.fx`). The portals themselves are
+ * the screen's: an effect made in code with a shader of its own (`./portal.look.ts`)
+ */
+import { defineCommand, type Game, exactMath } from '@v12-engine/engine'
+import { PLAYER, UNIT } from '../common/units'
+import type { ExampleDef } from '../define'
+
+export const PORTALS = [
+	{ x: 18, z: 25 },
+	{ x: 30, z: 25 }
+] as const
+
+/** A footman steps through: put down at the other portal, walking on out of it, a flash where he left and where he came */
+export const stepThrough = defineCommand('customFx.step', {}, (world) => {
+	const footmen = [...world.units.values()].filter((unit) => unit.def.id === UNIT.footman && unit.alive)
+	const away = (unit: { pos: { x: number; z: number } }, at: { x: number; z: number }) => exactMath.hypot(unit.pos.x - at.x, unit.pos.z - at.z)
+	// the one nearest either portal
+	const one = footmen.sort((a, b) => Math.min(away(a, PORTALS[0]), away(a, PORTALS[1])) - Math.min(away(b, PORTALS[0]), away(b, PORTALS[1])))[0]
+	if (!one) return
+	const [from, to] = away(one, PORTALS[0]) < away(one, PORTALS[1]) ? PORTALS : [PORTALS[1], PORTALS[0]]
+	world.fx('customFx.warp', { at: { x: one.pos.x, z: one.pos.z } })
+	world.place(one, { x: to.x, z: to.z - 0.8 })
+	world.fx('customFx.warp', { at: { x: to.x, z: to.z - 0.8 } })
+	// on out, a few steps the way he was going
+	one.order('move', { x: to.x + (to.x - from.x) * 0.25 + (world.rng.next() - 0.5) * 3, z: to.z - 3 - world.rng.next() * 2 })
+})
+
+export const portal: ExampleDef = {
+	id: 'custom-fx-portal',
+	category: 'custom-fx',
+	title: 'Portals (a shader)',
+	summary:
+		'Two gates, each an effect made in code: a frame, a swirl drawn by a shader of your own, motes drawn in, a light. Send footmen through: the rules move them and play a flash at both ends for every player.',
+	tags: ['portal', 'shader', 'ShaderMaterial', 'make', 'teleport', 'world.fx', 'swirl'],
+	environment: 'night',
+	start: (world) => {
+		for (let i = 0; i < 4; i++)
+			world.spawn(UNIT.footman, { at: { x: PORTALS[0].x - 1.5 + (i % 2) * 3, z: PORTALS[0].z - 3 - Math.floor(i / 2) * 1.4 }, owner: PLAYER })
+	},
+	source: ['examples/custom-fx/portal.ts', 'examples/custom-fx/portal.look.ts', 'examples/custom-fx/shader.ts']
+}
+
+/** Registers the command */
+export function portalRules(game: Game<any>): void {
+	game.command(stepThrough)
+}

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

@@ -0,0 +1,139 @@
+/**
+ * A renderer of your own, on the client's side: a `RendererFactory` in the view's `renderers`, handed the render kit
+ * (`RenderKit`: the scene, the state the screen knows, where each unit is drawn). It gives back a `FeatureRenderer`:
+ * `sync` hears what each snapshot brought (units come and gone, events: an attack, a blow), `frame` draws every
+ * frame, `dispose` takes it all away. Here, a ring under every unit coloured by its health, flaring at a blow, and a
+ * line from each attacker to what it attacks
+ */
+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 { CreateLines } from '@babylonjs/core/Meshes/Builders/linesBuilder.js'
+import { CreateTorus } from '@babylonjs/core/Meshes/Builders/torusBuilder.js'
+import type { LinesMesh } from '@babylonjs/core/Meshes/linesMesh.js'
+import type { Mesh } from '@babylonjs/core/Meshes/mesh.js'
+import type { RendererFactory } from '@v12-engine/client'
+import { button, type ExampleLook, toggle } from '../../shell/look'
+import { ENEMY } from '../common/units'
+import { clash, lineUpAgain } from '../fx/blood'
+import { aim } from '../fx/stage'
+
+/** Whether the card shows what the renderer draws */
+const shown = { rings: true, lines: true }
+
+const GREEN = new Color3(0.2, 1, 0.35)
+const YELLOW = new Color3(1, 0.85, 0.2)
+const RED = new Color3(1, 0.15, 0.1)
+
+/** Green when whole, yellow at half, red near none */
+const healthColor = (share: number, out: Color3) =>
+	share > 0.5 ? Color3.LerpToRef(YELLOW, GREEN, (share - 0.5) * 2, out) : Color3.LerpToRef(RED, YELLOW, share * 2, out)
+
+const ringsAndLines: RendererFactory = (kit) => {
+	const rings = new Map<number, { mesh: Mesh; material: StandardMaterial; flare: number }>()
+	const lines: { mesh: LinesMesh; from: number; to: number; age: number }[] = []
+	const ringOf = (id: number) => {
+		let ring = rings.get(id)
+		if (ring) return ring
+		const mesh = CreateTorus('customFx.healthRing', { diameter: 1.25, thickness: 0.07, tessellation: 32 }, kit.scene)
+		const material = new StandardMaterial('customFx.healthRing', kit.scene)
+		material.disableLighting = true
+		mesh.material = material
+		mesh.isPickable = false
+		ring = { mesh, material, flare: 0 }
+		rings.set(id, ring)
+		return ring
+	}
+	/** Where a unit's line ends: over its head, so the line reads above the crowd */
+	const middle = (id: number) => {
+		const drawn = kit.drawn(id)
+		return drawn && drawn.visible ? drawn.position.add(new Vector3(0, 2.3, 0)) : undefined
+	}
+	return {
+		sync(changes) {
+			for (const event of changes.events) {
+				// a blow: the ring of the struck flares
+				if (event.type === 'damage') ringOf(event.id).flare = 1
+				// an attack begun: a line from the attacker to its target, its side's colour
+				if (event.type === 'attack' && event.target !== undefined) {
+					const a = middle(event.id)
+					const b = middle(event.target)
+					if (!a || !b) continue
+					const mesh = CreateLines('customFx.threat', { points: [a, b], updatable: true }, kit.scene)
+					mesh.color = kit.state.entities.get(event.id)?.owner === ENEMY ? new Color3(1, 0.35, 0.3) : new Color3(0.4, 0.8, 1)
+					mesh.isPickable = false
+					lines.push({ mesh, from: event.id, to: event.target, age: 0 })
+				}
+			}
+			for (const gone of changes.removed) {
+				const ring = rings.get(gone.id)
+				ring?.mesh.dispose()
+				ring?.material.dispose()
+				rings.delete(gone.id)
+			}
+		},
+		frame(_alpha, dt) {
+			for (const entity of kit.state.entities.values()) {
+				const drawn = kit.drawn(entity.id)
+				const ring = ringOf(entity.id)
+				const share = entity.health / Math.max(entity.maxHealth, 1)
+				ring.mesh.setEnabled(shown.rings && !!drawn?.visible && entity.health > 0)
+				if (!drawn) continue
+				ring.mesh.position.set(drawn.position.x, drawn.position.y + 0.05, drawn.position.z)
+				// a blow flares it white and wide, fading back in a third of a second
+				ring.flare = Math.max(ring.flare - dt * 3, 0)
+				healthColor(share, ring.material.emissiveColor)
+				Color3.LerpToRef(ring.material.emissiveColor, Color3.White(), ring.flare, ring.material.emissiveColor)
+				ring.mesh.scaling.setAll(1 + ring.flare * 0.35)
+			}
+			for (let i = lines.length - 1; i >= 0; i--) {
+				const line = lines[i]!
+				line.age += dt
+				const a = middle(line.from)
+				const b = middle(line.to)
+				if (line.age > 0.8 || !a || !b) {
+					line.mesh.dispose()
+					lines.splice(i, 1)
+					continue
+				}
+				CreateLines('customFx.threat', { points: [a, b], instance: line.mesh })
+				line.mesh.alpha = 1 - line.age / 0.8
+				line.mesh.setEnabled(shown.lines)
+			}
+		},
+		dispose() {
+			for (const ring of rings.values()) {
+				ring.mesh.dispose()
+				ring.material.dispose()
+			}
+			for (const line of lines) line.mesh.dispose()
+			rings.clear()
+			lines.length = 0
+		}
+	}
+}
+
+export const rendererLook: ExampleLook = {
+	view: (view) => ({ ...view, renderers: [...(view.renderers ?? []), ringsAndLines] }),
+	controls: [
+		button(
+			'Fight',
+			(client) => client.session.send(clash.make({})),
+			'Both sides go at each other: the rings redden as they are hurt, lines join each attacker to its target'
+		),
+		button('Line them up again', (client) => client.session.send(lineUpAgain.make({})), 'Everyone back in line, whole, their rings green again'),
+		toggle(
+			'Health rings',
+			true,
+			(_client, on) => (shown.rings = on),
+			'The ring under each unit, green to red as it is hurt, flaring white at a blow'
+		),
+		toggle('Attack lines', true, (_client, on) => (shown.lines = on), 'A fading line from each attacker to what it attacks, as it strikes')
+	],
+	ready: (client) => {
+		shown.rings = shown.lines = true
+		aim(client, { x: 24, z: 24 }, 18, 0.8)
+		const go = window.setTimeout(() => client.session.send(clash.make({})), 1200)
+		return () => window.clearTimeout(go)
+	}
+}

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

@@ -0,0 +1,18 @@
+/**
+ * A renderer of your own, on the rules' side: the footmen and skeletons of the blood example's fight, on a field of
+ * their own. What is drawn over them is the screen's (`./renderer.look.ts`)
+ */
+import { type ExampleDef, exampleField } from '../define'
+import { blood } from '../fx/blood'
+
+export const renderer: ExampleDef = {
+	id: 'custom-fx-renderer',
+	category: 'custom-fx',
+	title: 'A renderer of your own',
+	summary:
+		"Something drawn for every unit by code of the game's own (`GameView.renderers`): a ring under each, from green to red as it is hurt, flaring white at each blow; a line from each attacker to what it attacks, fading. Fight, and watch the field read itself.",
+	tags: ['renderer', 'RendererFactory', 'FeatureRenderer', 'sync', 'events', 'health', 'lines', 'kit'],
+	map: () => exampleField({ name: 'Field', players: 2 }),
+	start: blood.start,
+	source: ['examples/custom-fx/renderer.ts', 'examples/custom-fx/renderer.look.ts', 'examples/fx/blood.ts']
+}