@v12-engine/create 0.1.1 → 0.4.0

package/starters/examples/src/examples/fx/floats.look.ts

@@ -0,0 +1,108 @@
+/**
+ * Floating combat text, on the client's side. The view's `hud.floats` says what each kind of event floats: the
+ * ready-made ones (`presetFloats`), one changed (crits bigger and gold), and one of the game's own (`fxCombo`). The
+ * card puts words up in code with `client.floats.show(def, { on, amount })`: a kind's def, words alone, or a def made
+ * there, and a handle to count a number up as a channel ticks (`handle.update`)
+ */
+import { type FloatDef, type FloatSet, type GameClientApi, presetFloats } from '@v12-engine/client'
+import { button, type ExampleLook, toggle } from '../../shell/look'
+import { UNIT } from '../common/units'
+import { BRUTE } from './feel'
+import { fight } from './fight'
+import { FLOATS_AT } from './floats'
+import { aim, idsOf } from './stage'
+
+/** Every ready-made kind, a critical strike bigger and golden, and a combo of the game's own that bounces */
+const FLOATS: FloatSet = {
+	...presetFloats(),
+	crit: { ...presetFloats(['crit']).crit, style: { color: '#ffcf3a', size: 28, stroke: { color: '#5a1a00', width: 4 } } },
+	fxCombo: {
+		text: 'Combo ×{amount}',
+		style: { color: '#ff8aff', size: 20, background: { color: 'rgba(30, 0, 30, 0.75)', padding: 5, radius: 6 } },
+		motion: [{ bounce: { height: 0.7, times: 2, seconds: 0.8 } }, { pop: { from: 0.4, seconds: 0.25, ease: 'outBack' } }],
+		seconds: 1.6
+	}
+}
+
+/** A kind's def as the view has it now */
+const kind = (client: GameClientApi, name: string): FloatDef | undefined => {
+	const rule = client.floats.def(name)
+	return rule && typeof rule === 'object' ? rule : undefined
+}
+
+/** Floats a kind over a unit, as the client floats it for an event of its kind */
+function float(client: GameClientApi, name: string, on: 'brute' | 'dummy', amount?: number, params?: Record<string, unknown>): void {
+	const [id] = idsOf(client, on === 'brute' ? BRUTE : UNIT.dummy)
+	const def = kind(client, name)
+	if (id === undefined || !def) return
+	client.floats.show(def, { kind: name, on: id, ...(amount !== undefined && { amount }), ...(params && { params }) })
+}
+
+const random = (least: number, most: number) => Math.round(least + Math.random() * (most - least))
+
+let combo = 0
+
+export const floatsLook: ExampleLook = {
+	view: (view) => ({ ...view, hud: { ...view.hud, floats: FLOATS } }),
+	controls: [
+		button(
+			'Damage',
+			(client) => float(client, 'damage', 'dummy', random(20, 60)),
+			'A damage number over the dummy: press fast and hits within 0.8 s merge into one number that counts up'
+		),
+		button(
+			'Critical strike',
+			(client) => float(client, 'crit', 'dummy', random(150, 320)),
+			'A critical strike over the dummy: this game made it bigger and gold'
+		),
+		button('Miss', (client) => float(client, 'miss', 'dummy'), 'The word a dodged blow floats over the dummy'),
+		button('Heal', (client) => float(client, 'heal', 'brute', random(40, 120)), 'A green heal number over the brute'),
+		button(
+			'Heal over time',
+			(client) => {
+				// one number told more as the channel ticks, counted up, then let go
+				const [brute] = idsOf(client, BRUTE)
+				if (brute === undefined) return
+				const channel = client.floats.show({ ...kind(client, 'heal'), merge: { window: 2, countUp: 0.3 } }, { kind: 'heal', on: brute, amount: 15 })
+				let total = 15
+				let ticks = 0
+				const tick = window.setInterval(() => {
+					total += 15
+					channel?.update(total)
+					if (++ticks >= 7) {
+						window.clearInterval(tick)
+						channel?.end()
+					}
+				}, 300)
+			},
+			'A heal that ticks for two seconds: one number over the brute counts up as it goes, rather than eight numbers (FloatHandle.update)'
+		),
+		button('Experience', (client) => float(client, 'xp', 'brute', random(20, 90)), 'The experience a kill brings, over the brute'),
+		button('Mana', (client) => float(client, 'mana', 'brute', -random(30, 80)), 'Mana lost, in blue, over the brute'),
+		button('Gold', (client) => float(client, 'bounty', 'dummy', random(5, 40)), 'The gold a kill pays, over the dummy'),
+		button('Level up', (client) => float(client, 'levelUp', 'brute', random(2, 10)), 'The level-up banner over the brute'),
+		button(
+			'Combo (your own)',
+			(client) => float(client, 'fxCombo', 'brute', ++combo),
+			'A float this game made itself, by its id: it bounces, and counts up each press'
+		),
+		button(
+			'Words',
+			(client) => {
+				const [brute] = idsOf(client, BRUTE)
+				if (brute !== undefined) client.floats.show(['Rally!', 'For the king!', 'Hold the line!'][random(0, 2)]!, { on: brute })
+			},
+			"Plain words over the brute, in the overlay's plain look"
+		),
+		toggle(
+			'The brute fights',
+			false,
+			(client, on) => client.session.send(fight.make({ on })),
+			'The brute attacks the dummy for real: every hit floats its damage by itself'
+		)
+	],
+	ready: (client) => {
+		combo = 0
+		aim(client, { x: FLOATS_AT.x + 0.8, z: FLOATS_AT.z + 1.5 }, 18, 0.8)
+	}
+}

package/starters/examples/src/examples/fx/floats.ts

@@ -0,0 +1,24 @@
+/**
+ * Floating combat text, on the rules' side: the brute and a dummy for him to hit. The words themselves are the
+ * screen's: what each kind of event floats (`./floats.look.ts`), and words put up in code
+ */
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+import { BRUTE } from './feel'
+
+export const FLOATS_AT = { x: 24, z: 24 }
+
+export const floats: ExampleDef = {
+	id: 'fx-floats',
+	category: 'fx',
+	title: 'Floating combat text',
+	summary:
+		'Numbers and words over units: damage, critical strikes, heals, misses, experience, gold, a level up, a heal that counts up as it ticks, and words of your own. Press one to float it, or let the brute fight to see the damage floats merge.',
+	tags: ['floats', 'floating text', 'damage numbers', 'combat text', 'presetFloats', 'FloatDef'],
+	map: () => exampleField({ name: 'Yard', players: 2 }),
+	start: (world) => {
+		world.spawn(BRUTE, { at: FLOATS_AT, owner: PLAYER })
+		world.spawn(UNIT.dummy, { at: { x: FLOATS_AT.x + 1.6, z: FLOATS_AT.z + 0.8 }, owner: ENEMY })
+	},
+	source: ['examples/fx/floats.ts', 'examples/fx/floats.look.ts']
+}

package/starters/examples/src/examples/fx/gallery.look.ts

@@ -0,0 +1,168 @@
+/**
+ * Every ready-made effect, on the client's side: the presets (`PRESET_FX`) and the links (`LINK_FX`) in a list, each
+ * played on this screen alone with `client.fx.play`. How each is played follows what it is: a missile is flown at the
+ * footman and lands with its `impact`, a trail is carried round him, a link reaches from him to the archer, the rest
+ * play on him and follow him
+ */
+import { type FxHandle, type GameClientApi, LINK_FX, PRESET_FX } from '@v12-engine/client'
+import { button, type ExampleLook, readout, select, slider, toggle } from '../../shell/look'
+import { STAGE } from './gallery'
+import { aim, everyFrame, idsOf } from './stage'
+import { UNIT } from '../common/units'
+
+/** Every effect there is to play, in the order the docs list them: fire, smoke, explosions, earth, magic, water, blood, links */
+const NAMES = [...Object.keys(PRESET_FX), ...Object.keys(LINK_FX)]
+
+/** What the card has chosen, and what plays */
+const chosen = { name: 'explosion', scale: 1, oneAtATime: true }
+let playing: FxHandle[] = []
+/** Missiles on their way: the effect, where it is, where it goes */
+let flights: { handle: FxHandle; at: { x: number; y: number; z: number }; to: { x: number; y: number; z: number } }[] = []
+/** Trails carried round the footman: the effect, and how long it has gone round */
+let rounds: { handle: FxHandle; age: number }[] = []
+
+/** Plays an effect the way it is made to be seen */
+function play(client: GameClientApi, name: string): void {
+	const [footman] = idsOf(client, UNIT.footman)
+	const [archer] = idsOf(client, UNIT.archer)
+	if (footman === undefined) return
+	if (chosen.oneAtATime) stopAll()
+	const def = client.fx.get(name)
+	const tags = def?.tags ?? []
+	const scale = chosen.scale
+	const ground = (x: number, z: number) => client.session.terrain.heightAt(x, z)
+	if (name in LINK_FX) {
+		// drawn between two: from the footman toward the archer, both ends followed as they move
+		// a link of a chain lasts its `time` (0.4 s): longer here, to be seen
+		playing.push(client.fx.play(name, { on: footman, toward: archer, scale, ...(name === 'chain' && { params: { time: 1.5 } }) }))
+	} else if (tags.includes('projectile')) {
+		// a missile: flown from the thrower's spot at the footman, landing with what its `impact` knob names
+		const { thrower, target } = STAGE
+		const at = { x: thrower.x, y: ground(thrower.x, thrower.z) + 1.4, z: thrower.z }
+		const handle = client.fx.play(name, { at, scale })
+		flights.push({ handle, at, to: { x: target.x, y: ground(target.x, target.z) + 1.1, z: target.z } })
+		playing.push(handle)
+	} else if (tags.includes('trail')) {
+		// left behind what moves: carried round the footman, so what it leaves shows
+		const handle = client.fx.play(name, { at: { x: STAGE.target.x + 3, z: STAGE.target.z }, scale })
+		rounds.push({ handle, age: 0 })
+		playing.push(handle)
+	} else {
+		playing.push(client.fx.play(name, { on: footman, scale }))
+	}
+}
+
+/** Stops every effect played here, letting what is alive of each fade */
+function stopAll(): void {
+	for (const handle of playing) handle.stop({ mode: 'fade', fade: 0.4 })
+	playing = []
+	flights = []
+	rounds = []
+}
+
+/** Moves what flies and what goes round, a frame's worth */
+function step(client: GameClientApi, dt: number): void {
+	flights = flights.filter((flight) => {
+		const { at, to, handle } = flight
+		if (!handle.alive) return false
+		const left = Math.hypot(to.x - at.x, to.y - at.y, to.z - at.z)
+		const move = 14 * dt
+		if (left <= move) {
+			// landed: what it was carrying lets its trail finish, and its impact goes off where it struck
+			handle.stop()
+			const impact = handle.params.impact
+			if (typeof impact === 'string' && impact)
+				playing.push(
+					client.fx.play(impact, { at: { x: to.x, z: to.z }, params: { size: Number(handle.params.impactSize ?? 1) }, scale: chosen.scale })
+				)
+			return false
+		}
+		at.x += ((to.x - at.x) / left) * move
+		at.y += ((to.y - at.y) / left) * move
+		at.z += ((to.z - at.z) / left) * move
+		handle.move({ at: { ...at } })
+		return true
+	})
+	rounds = rounds.filter((round) => {
+		round.age += dt
+		if (!round.handle.alive) return false
+		if (round.age > 5) {
+			round.handle.stop()
+			return false
+		}
+		const angle = round.age * 1.4
+		round.handle.move({ at: { x: STAGE.target.x + Math.cos(angle) * 3, z: STAGE.target.z + Math.sin(angle) * 3 } })
+		return true
+	})
+}
+
+/** Plays every effect in turn, one each `seconds`, until stopped */
+let tour: number | undefined
+function playAll(client: GameClientApi, seconds = 3): void {
+	if (tour !== undefined) window.clearInterval(tour)
+	let next = 0
+	const one = () => {
+		if (next >= NAMES.length) {
+			window.clearInterval(tour)
+			tour = undefined
+			return
+		}
+		chosen.name = NAMES[next++]!
+		play(client, chosen.name)
+	}
+	one()
+	tour = window.setInterval(one, seconds * 1000)
+}
+
+export const galleryLook: ExampleLook = {
+	controls: [
+		select(
+			'Effect',
+			NAMES,
+			chosen.name,
+			(client, name) => {
+				chosen.name = name
+				play(client, name)
+			},
+			'One of the ready-made effects: choosing it plays it in the middle of the stage'
+		),
+		button('Play', (client) => play(client, chosen.name), 'Plays the chosen effect again'),
+		button('Play them all', (client) => playAll(client), 'Every effect in turn, three seconds each'),
+		button(
+			'Stop',
+			() => {
+				if (tour !== undefined) window.clearInterval(tour)
+				tour = undefined
+				stopAll()
+			},
+			'Stops what plays: what is alive of it fades'
+		),
+		slider(
+			'Scale',
+			{ min: 0.25, max: 3, step: 0.05, value: chosen.scale },
+			(_client, value) => (chosen.scale = value),
+			'How big the next one plays (`FxPlay.scale`): press Play to see it'
+		),
+		toggle('One at a time', chosen.oneAtATime, (_client, on) => (chosen.oneAtATime = on), 'On: each play stops the one before; off, they pile up'),
+		readout(
+			'Playing',
+			(client) => {
+				const stats = client.fx.stats()
+				return `${tour !== undefined ? chosen.name : playing.some((each) => each.alive) ? chosen.name : '–'} · ${stats.particles} particles, ${stats.lights} lights`
+			},
+			'What plays now, and how many particles and lights every effect on screen holds'
+		)
+	],
+	ready: (client) => {
+		aim(client, { x: 25, z: 24.5 }, 20, 0.62)
+		const stop = everyFrame(client, (dt) => step(client, dt))
+		// a first one, so the stage is not empty
+		window.setTimeout(() => play(client, chosen.name), 300)
+		return () => {
+			stop()
+			if (tour !== undefined) window.clearInterval(tour)
+			tour = undefined
+			stopAll()
+		}
+	}
+}

package/starters/examples/src/examples/fx/gallery.ts

@@ -0,0 +1,23 @@
+/**
+ * Every ready-made effect, on the rules' side: a footman to play them on, and an archer for those drawn between two.
+ * The effects themselves are the client's alone (`./gallery.look.ts`): nothing here knows of them
+ */
+import { PLAYER, UNIT } from '../common/units'
+import type { ExampleDef } from '../define'
+
+/** Where the gallery's three places are: the footman effects play on, the archer links reach, where missiles leave from */
+export const STAGE = { target: { x: 24, z: 24 }, other: { x: 29, z: 26 }, thrower: { x: 16, z: 21 } }
+
+export const gallery: ExampleDef = {
+	id: 'fx-gallery',
+	category: 'fx',
+	title: 'Every ready-made effect',
+	summary:
+		'All the effects the client ships, from fire to blood. Pick one and press Play: it plays on the footman, flies at him if it is a missile, or reaches from him to the archer if it is drawn between two. Play them all runs through every one.',
+	tags: ['presetFx', 'linkFx', 'particles', 'fire', 'explosion', 'magic', 'smoke', 'water', 'blood', 'gallery'],
+	start: (world) => {
+		world.spawn(UNIT.footman, { at: STAGE.target, owner: PLAYER, facing: Math.PI })
+		world.spawn(UNIT.archer, { at: STAGE.other, owner: PLAYER, facing: Math.PI })
+	},
+	source: ['examples/fx/gallery.ts', 'examples/fx/gallery.look.ts']
+}

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

@@ -0,0 +1,30 @@
+/**
+ * The effects' examples on the rules' side (`ExampleCategory`): their list entries, maps and starts, and the units,
+ * abilities and commands they add to the game. Each example is a file of its own here, its look beside it
+ * (`<name>.look.ts`, gathered in `./looks.ts`)
+ */
+import type { Game } from '@v12-engine/engine'
+import type { ExampleCategory } from '../define'
+import { blood, bloodRules } from './blood'
+import { feel, feelRules } from './feel'
+import { fight } from './fight'
+import { floats } from './floats'
+import { gallery } from './gallery'
+import { links, linksRules } from './links'
+import { map } from './map'
+import { marks, marksRules } from './marks'
+import { shots, shotsRules } from './shots'
+import { spells, spellsRules } from './spells'
+
+export const category: ExampleCategory = {
+	rules: (game: Game<any>) => {
+		game.command(fight)
+		shotsRules(game)
+		spellsRules(game)
+		feelRules(game)
+		bloodRules(game)
+		marksRules(game)
+		linksRules(game)
+	},
+	examples: [gallery, shots, spells, links, feel, floats, blood, marks, map]
+}

package/starters/examples/src/examples/fx/links.look.ts

@@ -0,0 +1,83 @@
+/**
+ * Beams, tethers and chains, on the client's side: the link effects (`linkFx`: `ray`, `tether`, `chain`) played on one
+ * unit `toward` another, which the effect asks where it is every frame, so both ends follow. A ray and a rope play
+ * until stopped (`time: 0`); a link of a chain lasts its `time`. Chain lightning is links played one after another,
+ * each from the last struck to the next, with a spark where it lands
+ */
+import type { FxHandle, GameClientApi } from '@v12-engine/client'
+import { button, type ExampleLook, toggle } from '../../shell/look'
+import { UNIT } from '../common/units'
+import { LINK_MAGE_AT, ray } from './links'
+import { aim, idsOf } from './stage'
+
+/** The beam and the rope while they are on */
+const held: { beam?: FxHandle; rope?: FxHandle } = {}
+/** The leaps of a chain still to come */
+let leaps: number[] = []
+
+/** Lightning from the mage to the first dummy, and on from each to the next, 0.18 s apart */
+function chainLightning(client: GameClientApi): void {
+	for (const leap of leaps) window.clearTimeout(leap)
+	const [mage] = idsOf(client, UNIT.mage)
+	const dummies = idsOf(client, UNIT.dummy)
+	if (mage === undefined) return
+	const hops = [mage, ...dummies]
+	leaps = hops.slice(1).map((to, i) =>
+		window.setTimeout(() => {
+			client.fx.play('chain', { on: hops[i], toward: to, params: { time: 0.5, width: 0.12 } })
+			client.fx.play('spark-burst', { on: to, point: 'chest', params: { count: 16, color: '#bfe0ff', size: 0.6 } })
+			// each struck flashes as the bolt lands
+			client.renderer.kit.flash(to, [0.6, 0.8, 1], 0.2)
+		}, i * 180)
+	)
+}
+
+export const linksLook: ExampleLook = {
+	controls: [
+		toggle(
+			'Beam',
+			true,
+			(client, on) => {
+				held.beam?.stop({ mode: 'fade', fade: 0.3 })
+				held.beam = undefined
+				const [mage] = idsOf(client, UNIT.mage)
+				const [footman] = idsOf(client, UNIT.footman)
+				if (on && mage !== undefined) held.beam = client.fx.play('ray', { on: mage, toward: footman })
+			},
+			'A ray from the mage to the first footman, held as he walks'
+		),
+		toggle(
+			'Tether',
+			true,
+			(client, on) => {
+				held.rope?.stop({ mode: 'fade', fade: 0.3 })
+				held.rope = undefined
+				const [mage] = idsOf(client, UNIT.mage)
+				const footmen = idsOf(client, UNIT.footman)
+				if (on && mage !== undefined) held.rope = client.fx.play('tether', { on: mage, toward: footmen[1], params: { color: '#ff7a8a' } })
+			},
+			'A rope that sags as he comes near and pulls tight as he goes'
+		),
+		button('Chain lightning', (client) => chainLightning(client), 'Links one after another, along the dummies'),
+		button(
+			'A ray from the rules',
+			(client) => client.session.send(ray.make({})),
+			'A ray played by the rules (`world.fx`) rather than the screen: every player sees it'
+		)
+	],
+	ready: (client) => {
+		aim(client, { x: LINK_MAGE_AT.x, z: LINK_MAGE_AT.z + 4 }, 32, 0.8)
+		const [mage] = idsOf(client, UNIT.mage)
+		const footmen = idsOf(client, UNIT.footman)
+		if (mage !== undefined) {
+			held.beam = client.fx.play('ray', { on: mage, toward: footmen[0] })
+			held.rope = client.fx.play('tether', { on: mage, toward: footmen[1], params: { color: '#ff7a8a' } })
+		}
+		return () => {
+			held.beam?.stop({ mode: 'at-once' })
+			held.rope?.stop({ mode: 'at-once' })
+			held.beam = held.rope = undefined
+			for (const leap of leaps) window.clearTimeout(leap)
+		}
+	}
+}

package/starters/examples/src/examples/fx/links.ts

@@ -0,0 +1,49 @@
+/**
+ * Beams, tethers and chains, on the rules' side: a mage in the middle, two footmen walking back and forth past him,
+ * and a row of dummies for lightning to leap along. The links are the screen's (`./links.look.ts`); here, the rules
+ * play one too, every player seeing it (`world.fx` with `toward`), from the command `fx.ray`
+ */
+import { defineCommand, defineTimer, type Game } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+
+export const LINK_MAGE_AT = { x: 24, z: 22 }
+
+/** What puts the rules' ray out, set to go off as it is played: a timer, so a save and a replay keep it */
+const rayEnds = defineTimer<{ fx: number }>({ id: 'fx.rayEnds', run: (world, { fx }) => world.stopFx(fx, { fade: 0.4 }) })
+
+/** The rules play a ray from the mage to the farthest dummy: an effect drawn between two, sent to every screen */
+export const ray = defineCommand('fx.ray', {}, (world) => {
+	const mage = [...world.units.values()].find((unit) => unit.def.id === UNIT.mage && unit.alive)
+	const dummies = [...world.units.values()].filter((unit) => unit.def.id === UNIT.dummy && unit.alive)
+	const far = dummies.sort((a, b) => b.pos.x - a.pos.x)[0]
+	if (!mage || !far) return
+	const id = world.fx('ray', { on: mage, toward: far, params: { color: '#ffcf6a' } })
+	// it lasts as long as the rules say: two seconds
+	world.timers.after(2, rayEnds, { fx: id })
+})
+
+export const links: ExampleDef = {
+	id: 'fx-links',
+	category: 'fx',
+	title: 'Beams, tethers and chains',
+	summary:
+		'Effects drawn between two, each end followed as it moves: a beam, a rope that sags, lightning that leaps from one to the next. The footmen walk; the links keep hold. One ray is played by the rules, for every player.',
+	tags: ['linkFx', 'ray', 'beam', 'tether', 'chain', 'lightning', 'toward', 'link'],
+	map: () => exampleField({ name: 'Field', players: 2 }),
+	start: (world) => {
+		world.spawn(UNIT.mage, { at: LINK_MAGE_AT, owner: PLAYER })
+		// two footmen walking to and fro past the mage
+		world.spawn(UNIT.footman, { at: { x: 17, z: 24 }, owner: PLAYER }).order('patrol', { x: 31, z: 24 })
+		world.spawn(UNIT.footman, { at: { x: 31, z: 18.5 }, owner: PLAYER }).order('patrol', { x: 17, z: 18.5 })
+		// dummies for the chain, in a line
+		for (let i = 0; i < 6; i++) world.spawn(UNIT.dummy, { at: { x: 16 + i * 3.2, z: 33 + (i % 2) * 1.2 }, owner: ENEMY })
+	},
+	source: ['examples/fx/links.ts', 'examples/fx/links.look.ts']
+}
+
+/** Registers the command */
+export function linksRules(game: Game<any>): void {
+	game.command(ray)
+	game.timer(rayEnds)
+}

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

@@ -0,0 +1,55 @@
+/**
+ * The effects' examples on the client's side (`CategoryLooks`): each example's look and controls by its id, and what
+ * they all need of the game's look: every ready-made effect (`presetFx`), the links (`linkFx`) and the marks laid on
+ * the ground (`presetDecals`), taken into the game's effects for any example to play, and the looks of the units and
+ * spells the examples add
+ */
+import { linkFx, presetDecals, presetFx } from '@v12-engine/client'
+import type { CategoryLooks } from '../../shell/look'
+import { SKELETON } from './blood'
+import { bloodLook, skeletonLook } from './blood.look'
+import { BRUTE } from './feel'
+import { bruteLook, feelLook } from './feel.look'
+import { floatsLook } from './floats.look'
+import { galleryLook } from './gallery.look'
+import { linksLook } from './links.look'
+import { mapLook } from './map.look'
+import { IDLE_SKELETON } from './marks'
+import { marksLook } from './marks.look'
+import { shooterLooks, shotsLook } from './shots.look'
+import { CASTER } from './spells'
+import { casterLook, spellLooks, spellsLook } from './spells.look'
+
+export const category: CategoryLooks = {
+	view: (view) => ({
+		...view,
+		units: {
+			...view.units,
+			looks: {
+				...view.units.looks,
+				...shooterLooks,
+				[CASTER]: casterLook,
+				[BRUTE]: bruteLook,
+				[SKELETON]: skeletonLook,
+				[IDLE_SKELETON]: skeletonLook
+			}
+		},
+		fx: {
+			...view.fx,
+			defs: { ...presetFx(), ...linkFx(), ...view.fx?.defs },
+			abilities: { ...view.fx?.abilities, looks: { ...view.fx?.abilities?.looks, ...spellLooks } }
+		},
+		ground: { ...view.ground, decals: { ...presetDecals(), ...view.ground?.decals } }
+	}),
+	looks: {
+		'fx-gallery': galleryLook,
+		'fx-shots': shotsLook,
+		'fx-spell-styles': spellsLook,
+		'fx-links': linksLook,
+		'fx-hit-feel': feelLook,
+		'fx-floats': floatsLook,
+		'fx-blood': bloodLook,
+		'fx-marks': marksLook,
+		'fx-map': mapLook
+	}
+}

package/starters/examples/src/examples/fx/map.look.ts

@@ -0,0 +1,93 @@
+/**
+ * Effects laid on the map, on the client's side. A map's file keeps its own effects (`MapEnvironment.fx`: an effect of
+ * the game's by name, where, its knobs, when it plays), its lights (`lights`) and the marks on its ground (`decals`, by
+ * the game's decal looks, `presetDecals`); the editor's effect tool (X) places them. Here they are laid in code with
+ * `client.setEnvironment`, which a map's file does as it loads, and found again by name with `client.mapFx.named`
+ */
+import type { GameClientApi, MapDecal, MapFx, MapLightSource } from '@v12-engine/client'
+import type { MapEnvironment } from '@v12-engine/engine'
+import { type ExampleLook, slider, toggle } from '../../shell/look'
+import { CAMP } from './map'
+import { aim } from './stage'
+
+const { x, z } = CAMP
+
+/** The effects of the map: each plays for as long as the map does, or at night alone (`when`) */
+const FX: MapFx[] = [
+	{ id: 1, name: 'campfire', fx: 'campfire', x, z, params: { size: 0.9 } },
+	// four torches round the camp, lit at night
+	...[0, 1, 2, 3].map((i): MapFx => {
+		const angle = (i / 4) * Math.PI * 2 + Math.PI / 4
+		return { id: 2 + i, name: `torch ${i + 1}`, fx: 'torch', x: x + Math.cos(angle) * 6, z: z + Math.sin(angle) * 6, height: 1.6, when: 'night' }
+	}),
+	{ id: 6, name: 'smoke', fx: 'chimney', x: x - 7, z: z + 5, height: 2.5 },
+	{ id: 7, name: 'mist', fx: 'mist', x: x + 8, z: z + 8, params: { radius: 5 } },
+	{ id: 8, name: 'portal', fx: 'portal', x: x + 7, z: z - 6, params: { size: 0.9 } },
+	{ id: 9, name: 'wisp', fx: 'glow', x: x - 6, z: z - 5, height: 1.4, params: { color: '#7fe0ff' }, when: 'night' },
+	{ id: 10, name: 'wisp 2', fx: 'glow', x: x - 8, z: z - 2, height: 2, params: { color: '#b48cff', size: 0.7 }, when: 'night' },
+	{ id: 11, name: 'sparkle', fx: 'sparkle', x: x - 6, z: z - 5, params: { color: '#a8e6ff' } },
+	{ id: 12, name: 'embers', fx: 'embers', x: x + 3.5, z: z + 6.5, params: { radius: 1 } }
+]
+
+/** The map's own lights besides what the effects bring: a cold one over the runes, always on */
+const LIGHTS: MapLightSource[] = [
+	{ id: 1, name: 'rune light', x: x - 6, z: z - 5, height: 2, color: [0.45, 0.75, 1], intensity: 1.4, range: 7, when: 'always' }
+]
+
+/** The marks on the ground: runes that glow, a scorch round the fire, cracks, cart ruts */
+const DECALS: MapDecal[] = [
+	{ id: 1, look: 'scorch', x, z, size: 3.4 },
+	{ id: 2, look: 'rune', x: x - 6, z: z - 5, size: 3.5 },
+	{ id: 3, look: 'glyph', x: x + 7, z: z - 6, size: 4.2, tint: [0.75, 0.5, 1] },
+	{ id: 4, look: 'crack', x: x + 5, z: z + 3, size: 3, facing: 0.6 },
+	{ id: 5, look: 'ruts', x: x - 3, z: z + 7, size: 4, facing: 1.2 },
+	{ id: 6, look: 'blood', x: x + 2.5, z: z - 3.2, size: 1.2, fade: 0.3 }
+]
+
+/** The night the example opens on (the game's look named `night`, `src/view.ts`), and the day turned to */
+const NIGHT: Partial<MapEnvironment> = {
+	sky: [0.05, 0.07, 0.14],
+	light: { sunUp: 35, sunAround: 200, sunColor: [0.55, 0.65, 1], sun: 0.35, ambient: 0.25, ambientColor: [0.35, 0.4, 0.7] },
+	fog: { start: 40, end: 160 }
+}
+const DAY: Partial<MapEnvironment> = {
+	sky: [0.55, 0.72, 0.95],
+	light: { sunUp: 50, sunAround: 210, sun: 1.1, ambient: 0.6, sunColor: [1, 0.97, 0.9], ambientColor: [0.85, 0.9, 1] },
+	fog: { start: 80, end: 260 }
+}
+
+/** The fire's size, through what plays of it on the map */
+const fire = (client: GameClientApi, size: number) => client.mapFx?.named('campfire')?.set({ size })
+
+export const mapLook: ExampleLook = {
+	controls: [
+		toggle(
+			'Day',
+			false,
+			(client, on) => client.setEnvironment(on ? DAY : NIGHT, { over: 1.5 }),
+			'Day or night, over a second and a half: the torches and wisps play by night alone (`when: night`)'
+		),
+		slider(
+			'Fire',
+			{ min: 0.2, max: 2.5, step: 0.05, value: 0.9 },
+			(client, size) => fire(client, size),
+			"How big the campfire burns: the map's effect changed while it plays (`client.mapFx.named('campfire').set`)"
+		),
+		toggle(
+			'Torches',
+			true,
+			(client, on) => client.setEnvironment({ fx: FX.map((each) => (each.fx === 'torch' ? { ...each, on } : each)) }),
+			'Puts the torches round the camp out or lights them again (`on: false` on the map effect)'
+		),
+		toggle(
+			'Marks on the ground',
+			true,
+			(client, on) => client.setEnvironment({ decals: on ? DECALS : [] }),
+			'The marks painted on the ground round the camp: a scorch, runes, a crack, ruts and blood (`decals`)'
+		)
+	],
+	ready: (client) => {
+		client.setEnvironment({ fx: FX, lights: LIGHTS, decals: DECALS })
+		aim(client, { x: x - 0.5, z: z - 0.5 }, 24, 0.68)
+	}
+}

package/starters/examples/src/examples/fx/map.ts

@@ -0,0 +1,33 @@
+/**
+ * Effects laid on the map, on the rules' side: a night, and footmen round where the fire will be. The fire, the
+ * torches, the lights and the marks on the ground are the map's look (`MapEnvironment.fx`, `lights`, `decals`), which
+ * the rules never see: `./map.look.ts` lays them as the map's file would
+ */
+import { exactMath } from '@v12-engine/engine'
+import { PLAYER, UNIT } from '../common/units'
+import type { ExampleDef } from '../define'
+
+/** The middle of the camp: where the fire burns */
+export const CAMP = { x: 24, z: 24 }
+
+export const map: ExampleDef = {
+	id: 'fx-map',
+	category: 'fx',
+	title: 'A camp at night',
+	summary:
+		"Effects that play for as long as the map does: a campfire, torches that light at night, smoke, mist, a portal, wisps; the map's own lights; runes, scorches and cracks laid on the ground. Turn day on to see what is lit only at night; turn the fire up.",
+	tags: ['map fx', 'MapFx', 'decals', 'lights', 'night', 'campfire', 'torch', 'environment', 'placed'],
+	environment: 'night',
+	start: (world) => {
+		for (let i = 0; i < 5; i++) {
+			const angle = (i / 5) * Math.PI * 2 + 0.3
+			world.spawn(UNIT.footman, {
+				at: { x: CAMP.x + exactMath.cos(angle) * 2.6, z: CAMP.z + exactMath.sin(angle) * 2.6 },
+				owner: PLAYER,
+				// each facing the fire
+				facing: exactMath.atan2(-exactMath.cos(angle), -exactMath.sin(angle))
+			})
+		}
+	},
+	source: ['examples/fx/map.ts', 'examples/fx/map.look.ts']
+}