@v12-engine/create 0.1.0 → 0.4.0

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

@@ -0,0 +1,100 @@
+/**
+ * Outlines, rings and pings, on the client's side. The view says how the selected (`units.select`), what the pointer is
+ * over (`units.hover`) and what a spell is aimed at (`units.target`) are outlined, and the pings the team may send
+ * (`pings.kinds`). In code: `client.outline(id, look)` puts an outline of its own on a unit until its handle takes it
+ * off; `client.ping` and `kit.ring` draw rings on the ground; `client.pings.send` pings for the team, `client.minimapPing`
+ * on the minimap alone
+ */
+import { type GameClientApi, type OutlineHandle, type OutlineLook, presetPings } from '@v12-engine/client'
+import { button, type ExampleLook, select } from '../../shell/look'
+import { BRUTE } from './feel'
+import { IDLE_SKELETON, MARKS_AT } from './marks'
+import { aim, idsOf, where } from './stage'
+
+/** The outlines the card puts on the nearer skeleton, by name */
+const OUTLINES: Record<string, OutlineLook | undefined> = {
+	None: undefined,
+	'A red line': { color: [1, 0.25, 0.2], width: 3 },
+	'A soft glow': { color: [0.4, 0.85, 1], width: 4, style: 'glow' },
+	'A pulsing glow': { color: [1, 0.8, 0.3], width: 5, style: 'glow', pulse: 1.2 },
+	'Seen through walls': { color: [0.7, 0.4, 1], width: 3, throughWalls: true, pulse: true }
+}
+
+let outline: OutlineHandle | undefined
+
+/** Puts the chosen outline on the nearer skeleton, the last one off */
+function mark(client: GameClientApi, name: string): void {
+	outline?.remove()
+	outline = undefined
+	const look = OUTLINES[name]
+	const [skeleton] = idsOf(client, IDLE_SKELETON)
+	if (look && skeleton !== undefined) outline = client.outline(skeleton, look)
+}
+
+/** A spot near the middle, a little to one side at random */
+const near = () => ({ x: MARKS_AT.x + (Math.random() - 0.5) * 8, z: MARKS_AT.z + (Math.random() - 0.5) * 6 })
+
+export const marksLook: ExampleLook = {
+	view: (view) => ({
+		...view,
+		units: {
+			...view.units,
+			// the selected in green, what the pointer is over in gold, what a spell is aimed at in red
+			select: { color: [0.45, 1, 0.55], width: 2.5 },
+			hover: { color: [1, 0.85, 0.35], width: 2 },
+			target: { color: [1, 0.3, 0.25], width: 3, pulse: true }
+		},
+		pings: { ...view.pings, kinds: presetPings() }
+	}),
+	controls: [
+		select(
+			'Outline the skeleton',
+			Object.keys(OUTLINES),
+			'A pulsing glow',
+			(client, name) => mark(client, name),
+			'An outline drawn round the skeleton on the left, in the look chosen (`client.outline`)'
+		),
+		button(
+			'Ring on the ground',
+			(client) => {
+				const at = near()
+				client.ping(at.x, at.z, [0.4, 0.9, 1])
+			},
+			'The ring a move order leaves on the ground, at a spot near the middle (`client.ping`)'
+		),
+		button(
+			'Ring going out',
+			(client) => {
+				const [brute] = idsOf(client, BRUTE)
+				const at = (brute !== undefined && where(client, brute)) || MARKS_AT
+				client.renderer.kit.ring(at.x, at.z, [1, 0.75, 0.3], 0.5, 5)
+			},
+			'A ring round the brute that grows and fades (`kit.ring`)'
+		),
+		button(
+			'Danger ping',
+			(client) => void client.pings.send('danger', near()),
+			'A danger ping for the team near the middle: a mark, a sound and a line in the chat'
+		),
+		button(
+			'On my way',
+			(client) => void client.pings.send('onMyWay', near()),
+			'Another kind of ping for the team, near the middle: its own mark and words'
+		),
+		button(
+			'Minimap ping',
+			(client) => client.minimapPing(MARKS_AT.x, MARKS_AT.z, '#ff4a3a', 4),
+			'A red ping on the minimap alone, in the corner of the screen'
+		)
+	],
+	ready: (client) => {
+		aim(client, { x: MARKS_AT.x, z: MARKS_AT.z + 1 }, 19, 0.8)
+		const [brute] = idsOf(client, BRUTE)
+		if (brute !== undefined) client.controller.select([brute])
+		mark(client, 'A pulsing glow')
+		return () => {
+			outline?.remove()
+			outline = undefined
+		}
+	}
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Outlines, rings and pings, on the rules' side: the brute of the player's, a bowman beside him, and two skeletons
+ * across from them to mark. Everything marked is the screen's alone (`./marks.look.ts`)
+ */
+import type { Game } from '@v12-engine/engine'
+import { ENEMY, PLAYER } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+import { BRUTE } from './feel'
+
+/** A skeleton that stands and takes what it is given: something of the enemy's to mark */
+export const IDLE_SKELETON = 'fxIdleSkeleton'
+
+export const MARKS_AT = { x: 24, z: 24 }
+
+export const marks: ExampleDef = {
+	id: 'fx-marks',
+	category: 'fx',
+	title: 'Outlines, rings and pings',
+	summary:
+		'How the screen marks things: the outline of what is selected and what the pointer is over, an outline of your own on a unit (a line, a glow, a pulse), rings on the ground, pings for the team and on the minimap. Hover and click the units; press the buttons.',
+	tags: ['outline', 'selection', 'hover', 'glow', 'ring', 'ping', 'minimap', 'indicators', 'markers'],
+	map: () => exampleField({ name: 'Field', players: 2 }),
+	start: (world) => {
+		// the brute and the bowman strike only when told: nothing here fights
+		world.spawn(BRUTE, { at: { x: MARKS_AT.x - 2, z: MARKS_AT.z - 1.5 }, owner: PLAYER })
+		world.spawn('fxBowman', { at: { x: MARKS_AT.x - 3.5, z: MARKS_AT.z - 2.5 }, owner: PLAYER })
+		world.spawn(IDLE_SKELETON, { at: { x: MARKS_AT.x + 2.5, z: MARKS_AT.z + 2 }, owner: ENEMY })
+		world.spawn(IDLE_SKELETON, { at: { x: MARKS_AT.x + 4, z: MARKS_AT.z + 0.5 }, owner: ENEMY })
+	},
+	source: ['examples/fx/marks.ts', 'examples/fx/marks.look.ts']
+}
+
+/** Registers the skeleton that stands */
+export function marksRules(game: Game<any>): void {
+	game.unit({ id: IDLE_SKELETON, name: 'Skeleton', kind: 'unit', radius: 0.45, stats: { health: 380, moveSpeed: 3 }, sight: 8 })
+}

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

@@ -0,0 +1,92 @@
+/**
+ * Missiles and impacts, on the client's side: each shooter's look with its `shot` (`ShotDef`). A shot is a ball in a
+ * colour, a model (`model`), or an effect carried as it flies (`fx`), with sparks behind it (`trail`), an arc, and an
+ * effect where it lands (`impact`). Every effect named is a ready-made one (`presetFx`), tuned by its knobs
+ */
+import type { UnitLook } from '@v12-engine/client'
+import { button, type ExampleLook, select } from '../../shell/look'
+import { character, hold, person } from '../common/looks'
+import { SHOOTERS, shoot, SHOOTER_Z, DUMMY_Z } from './shots'
+import { aim } from './stage'
+
+/** Each shooter's look: who it is, and what it shoots */
+export const shooterLooks: Record<(typeof SHOOTERS)[number], UnitLook> = {
+	// an arrow, the gear's own model, on a low arc, with a few sparks where it strikes
+	fxBowman: {
+		height: 1.7,
+		model: character('ranger', 0.68, { hold: [hold('bow')], animations: { attack: 'Ranged_Bow_Release' } }),
+		shot: { model: 'gear/arrow_bow.glb', size: 0.9, arc: 0.18, impact: { fx: 'spark-burst', params: { count: 10, size: 0.5 } } },
+		shapes: person(1.7)
+	},
+	// the ready-made fireball carried as it flies, in the place of a ball; a small explosion where it lands
+	fxFireMage: {
+		height: 1.8,
+		model: character('mage', 0.72, { hold: [hold('staff')], animations: { attack: 'Ranged_Magic_Shoot' } }),
+		shot: { fx: { fx: 'fireball', params: { size: 0.55 } }, impact: { fx: 'explosion', params: { size: 0.6, shake: 0.12, light: 3 } } },
+		shapes: person(1.8, [0.8, 0.25, 0.1])
+	},
+	// a pale ball with a trail of sparks, the burst of cold where it lands
+	fxFrostMage: {
+		height: 1.8,
+		model: character('mage', 0.72, { hold: [hold('wand')], animations: { attack: 'Spell_Simple_Shoot' } }),
+		shot: {
+			color: [0.6, 0.9, 1],
+			size: 0.35,
+			trail: { color: [0.7, 0.95, 1], tint: [1, 1, 1], count: 60 },
+			impact: { fx: 'frost', params: { size: 0.7 } }
+		},
+		shapes: person(1.8, [0.4, 0.7, 1])
+	},
+	// a quick spark, and lightning called down on what it strikes
+	fxStormMage: {
+		height: 1.8,
+		model: character('mage', 0.72, { hold: [hold('staff')], animations: { attack: 'Ranged_Magic_Shoot' } }),
+		shot: {
+			color: [0.75, 0.85, 1],
+			size: 0.22,
+			trail: { color: [0.6, 0.75, 1], tint: [1, 1, 1], count: 90 },
+			impact: { fx: 'lightning', params: { size: 0.8, shake: 0.12 } }
+		},
+		shapes: person(1.8, [0.5, 0.5, 0.9])
+	},
+	// a bomb lobbed high, trailing smoke, a ring blown over the ground where it lands
+	fxBombardier: {
+		height: 1.8,
+		model: character('barbarian', 0.72, { animations: { attack: 'Ranged_1H_Shoot' } }),
+		shot: {
+			model: 'gear/smokebomb.glb',
+			size: 0.6,
+			arc: 0.55,
+			fx: { fx: 'smoke-trail', params: { size: 0.5, rate: 40 } },
+			impact: { fx: 'impact-ring', params: { size: 0.7, shake: 0.15 } }
+		},
+		shapes: person(1.8, [0.5, 0.4, 0.3])
+	}
+}
+
+/** What the card's choice of shooter names, and the id `fx.shoot` is told */
+const WHO: Record<string, string> = {
+	'All of them': 'all',
+	'Bowman: an arrow': 'fxBowman',
+	'Fire mage: a fireball': 'fxFireMage',
+	'Frost mage: a frost bolt': 'fxFrostMage',
+	'Storm mage: lightning': 'fxStormMage',
+	'Bombardier: a bomb': 'fxBombardier'
+}
+
+export const shotsLook: ExampleLook = {
+	controls: [
+		select(
+			'Who shoots',
+			Object.keys(WHO),
+			'All of them',
+			(client, choice) => client.session.send(shoot.make({ who: WHO[choice] ?? 'all' })),
+			'Which shooter fires at its dummy, over and over: each missile has its own trail and impact'
+		),
+		button('Hold fire', (client) => client.session.send(shoot.make({ who: 'none' })), 'Every shooter stops; choose one above to start again')
+	],
+	ready: (client) => {
+		aim(client, { x: 24, z: (SHOOTER_Z + DUMMY_Z) / 2 }, 31, 0.68)
+		client.session.send(shoot.make({ who: 'all' }))
+	}
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Missiles and impacts, on the rules' side: five shooters, each across from a dummy of its own. To the rules they are
+ * five ranged units alike; what each shot looks like, as it flies and where it lands, is all the client's
+ * (`./shots.look.ts`). They shoot only when told (`fx.shoot`): they look for nothing to shoot of themselves
+ */
+import { defineCommand, type Game, text, type UnitTypeDef } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+
+/** The shooters' ids, in their lanes from left to right */
+export const SHOOTERS = ['fxBowman', 'fxFireMage', 'fxFrostMage', 'fxStormMage', 'fxBombardier'] as const
+
+/** A ranged unit that shoots `speed` cells a second at what it is told to, from `range` away */
+const shooter = (id: string, name: string, speed: number, cooldown = 1.2): UnitTypeDef => ({
+	id,
+	name,
+	kind: 'unit',
+	radius: 0.42,
+	stats: { health: 400, attackDamage: 20, attackSpeed: 1 / cooldown, attackRange: 12, moveSpeed: 0 },
+	sight: 14,
+	// it looks for nothing to shoot: what it shoots is what `fx.shoot` says
+	attacks: [{ damagePoint: 0.45, acquisitionRange: 0, projectileSpeed: speed }]
+})
+
+const units: UnitTypeDef[] = [
+	shooter(SHOOTERS[0], 'Bowman', 24, 0.9),
+	shooter(SHOOTERS[1], 'Fire mage', 13),
+	shooter(SHOOTERS[2], 'Frost mage', 16),
+	shooter(SHOOTERS[3], 'Storm mage', 30, 1.4),
+	shooter(SHOOTERS[4], 'Bombardier', 11, 1.8)
+]
+
+/** Where each lane is across, and where its shooter and its dummy stand */
+export const laneX = (lane: number) => 16 + lane * 4
+export const SHOOTER_Z = 20
+export const DUMMY_Z = 29
+
+/** Sets one shooter or all of them (`all`) on their dummies, or (`none`) stops them all */
+export const shoot = defineCommand('fx.shoot', { who: text }, (world, _player, { who }) => {
+	const dummies = [...world.units.values()].filter((unit) => unit.def.id === UNIT.dummy && unit.alive)
+	for (const unit of world.units.values()) {
+		if (!unit.alive || !(SHOOTERS as readonly string[]).includes(unit.def.id)) continue
+		const dummy = dummies.sort((a, b) => Math.abs(a.pos.x - unit.pos.x) - Math.abs(b.pos.x - unit.pos.x))[0]
+		if (dummy && (who === 'all' || who === unit.def.id)) unit.order('attack', dummy)
+		else unit.order('stop')
+	}
+})
+
+export const shots: ExampleDef = {
+	id: 'fx-shots',
+	category: 'fx',
+	title: 'Missiles and impacts',
+	summary:
+		"Five shooters, five looks of a shot: an arrow on an arc, a fireball that explodes, a frost bolt, a storm bolt that calls lightning down, a bomb trailing smoke. Pick who shoots; each shot is the unit look's `shot`, with its effect as it flies and its impact.",
+	tags: ['projectile', 'missile', 'shot', 'impact', 'fireball', 'arrow', 'trail', 'ShotDef'],
+	// two players: the shooters' and the dummies' they shoot
+	map: () => exampleField({ name: 'Range', players: 2 }),
+	start: (world) => {
+		SHOOTERS.forEach((type, lane) => {
+			world.spawn(type, { at: { x: laneX(lane), z: SHOOTER_Z }, owner: PLAYER, facing: 0 })
+			world.spawn(UNIT.dummy, { at: { x: laneX(lane), z: DUMMY_Z }, owner: ENEMY })
+		})
+	},
+	source: ['examples/fx/shots.ts', 'examples/fx/shots.look.ts']
+}
+
+/** Registers the shooters and their command */
+export function shotsRules(game: Game<any>): void {
+	for (const unit of units) game.unit(unit)
+	game.command(shoot)
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Spell styles, on the client's side: a look for each spell (`AbilityLook`), keyed by the ability's id, naming the style
+ * that draws it and its colour, and the style's own options. Buffs have looks too: `aura` is the style drawn on their
+ * carrier for as long as it carries them, `counter` a pip a stack, `until` the buff a tether lasts as long as. The
+ * styles are the client's (`presetSpellStyles`, which the game's `presetView` takes in)
+ */
+import type { AbilityLooks, UnitLook } from '@v12-engine/client'
+import { button, type ExampleLook, select } from '../../shell/look'
+import { character, hold, person } from '../common/looks'
+import { aura, CASTER_AT, cast, GLOWS, glowBuff, MARK_AT, SPELLS } from './spells'
+import { aim } from './stage'
+
+const GOLD: [number, number, number] = [1, 0.82, 0.35]
+const ARCANE: [number, number, number] = [0.7, 0.45, 1]
+const FROST: [number, number, number] = [0.55, 0.85, 1]
+
+/** Each spell's look, by its id: the style that draws it, its colour, and what the style is told besides */
+export const spellLooks: AbilityLooks = {
+	fxRing: { color: FROST, style: 'ring' },
+	fxBurst: { color: [0.45, 1, 0.55], style: 'burst', options: { count: 70, rise: 2.5, ring: 2 } },
+	fxSlam: { color: [0.85, 0.7, 0.45], style: 'slam' },
+	fxSmash: { color: [1, 0.55, 0.2], style: 'smash' },
+	fxSonar: { color: [0.5, 1, 0.8], style: 'sonar' },
+	// a star falls from 14 cells up onto the ring, sparks rising from it as it waits
+	fxStar: { color: GOLD, style: 'mark', options: { falls: 14, sparks: 30, fill: true, lasts: 1.2 } },
+	// a field for the zone's life; its ground drawn too (`ground`)
+	fxField: { color: ARCANE, style: 'mark', options: { lasts: 4, sparks: 40, fill: true } },
+	// rockets from the sky, one for each `after`, the last a great blast
+	fxBarrage: { color: [1, 0.45, 0.15], style: 'barrage', options: { hits: [1, 1.5, 2, 2.6], power: [1, 1, 1, 2], scatter: 0.6 } },
+	fxArrow: { color: [0.9, 0.85, 0.7], style: 'missile', options: { shape: 'arrow', trail: 30 } },
+	fxHawk: { color: [0.6, 0.85, 1], style: 'missile', options: { shape: 'hawk', trail: 60 } },
+	fxRock: { color: [0.6, 0.5, 0.4], style: 'missile', options: { shape: 'rock', arc: 2 } },
+	fxOrb: { color: ARCANE, style: 'missile', options: { shape: 'ball', size: 1.5, trail: 80 } },
+	fxTornado: { color: [0.8, 0.88, 0.95], style: 'tornado' },
+	// a rope for as long as the target is bound
+	fxTether: { color: [0.95, 0.3, 0.35], style: 'tether', until: 'fxBound' },
+	// the buffs: a pip a stack over the bleeding one, a glow of each shape on the caster
+	fxBleeding: { color: [0.9, 0.1, 0.12], counter: { max: 5 }, aura: 'glow', options: { shape: 'fall' } },
+	fxBound: { color: [0.95, 0.3, 0.35] },
+	...Object.fromEntries(
+		GLOWS.map((shape) => [
+			glowBuff(shape),
+			{ color: shape === 'dust' ? ([0.7, 0.6, 0.45] as const) : GOLD, aura: 'glow', options: { shape, streaks: shape === 'rise' } }
+		])
+	)
+}
+
+/** The caster's look: the mage, a staff in hand */
+export const casterLook: UnitLook = {
+	height: 1.8,
+	model: character('mage', 0.75, { hold: [hold('staff')] }),
+	shapes: person(1.8, ARCANE)
+}
+
+/** The card's names of the spells, and the spell each casts */
+const NAMES = Object.fromEntries(SPELLS.map((each) => [each.name, each.id]))
+/** The spell the card has chosen */
+let chosen = 'fxStar'
+
+export const spellsLook: ExampleLook = {
+	controls: [
+		select(
+			'Spell',
+			Object.keys(NAMES),
+			'Falling star',
+			(client, name) => {
+				chosen = NAMES[name] ?? chosen
+				client.session.send(cast.make({ ability: chosen }))
+			},
+			'A spell, cast at once at the middle dummy: each its own look'
+		),
+		button('Cast', (client) => client.session.send(cast.make({ ability: chosen })), 'Casts the spell at the middle dummy again'),
+		select(
+			'Wear an aura',
+			['none', ...GLOWS],
+			'none',
+			(client, shape) => client.session.send(aura.make({ shape })),
+			"A buff on the caster, drawn round it in one of the `glow` style's shapes"
+		)
+	],
+	ready: (client) => {
+		aim(client, { x: (CASTER_AT.x + MARK_AT.x) / 2, z: (CASTER_AT.z + MARK_AT.z) / 2 + 1 }, 19, 0.8)
+		client.session.send(aura.make({ shape: 'rise' }))
+		chosen = 'fxStar'
+		client.session.send(cast.make({ ability: chosen }))
+	}
+}

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

@@ -0,0 +1,122 @@
+/**
+ * Spell styles, on the rules' side: a caster with an ability for each way the client draws one, and dummies to cast
+ * them at. The abilities do little (a little damage, a buff); what each looks like is its look's `style`
+ * (`./spells.look.ts`). The card casts them through `fx.cast`, and puts a buff of each glow on the caster with `fx.aura`
+ */
+import { type AbilityDef, applyBuff, type BuffDef, defineCommand, type EffectDef, type Game, removeBuff, text } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+
+export const CASTER = 'fxCaster'
+
+/** Where the caster stands, and the dummy it casts at */
+export const CASTER_AT = { x: 24, z: 19 }
+export const MARK_AT = { x: 24, z: 27 }
+
+/** A bit of damage over a radius: what most of the spells do, for something to happen */
+const hurt = (radius?: number, amount = 30): EffectDef => ({ type: 'damage', amount, ...(radius && { radius }) })
+
+/** A spell with no cost and no wait, aimed as `target` says */
+const spell = (id: string, name: string, target: AbilityDef['target'], effects: EffectDef[], own: Partial<AbilityDef> = {}): AbilityDef => ({
+	id,
+	name,
+	target,
+	range: 14,
+	manaCost: 0,
+	cooldown: 0,
+	effects,
+	...(target === 'unit' && { targets: { enemies: true } }),
+	...own
+})
+
+/** A missile flying 14 cells the way it is aimed, hurting what it passes */
+const missile = (own: Partial<EffectDef> = {}): EffectDef =>
+	({ type: 'missile', speed: 13, distance: 14, radius: 0.8, effects: [hurt()], ...own }) as EffectDef
+
+/** Every spell, by the style that draws it: its id, its name on the card */
+export const SPELLS: readonly AbilityDef[] = [
+	spell('fxRing', 'Ring', 'point', [hurt(2)]),
+	spell('fxBurst', 'Burst', 'none', [{ type: 'heal', amount: 40 }]),
+	spell('fxSlam', 'Slam', 'none', [hurt(3)]),
+	// a second's windup: its circle shown on the ground for everyone until it lands (the telegraph every ability gets)
+	spell('fxSmash', 'Smash (telegraphed)', 'point', [hurt(2.5)], { castTime: 1 }),
+	spell('fxSonar', 'Sonar', 'point', [{ type: 'reveal', duration: 3, radius: 6 }]),
+	spell('fxStar', 'Falling star', 'point', [{ type: 'after', delay: 1.2, effects: [hurt(2.5, 80)] }]),
+	spell('fxField', 'Field', 'point', [{ type: 'zone', duration: 4, radius: 3, effects: [hurt(3, 6)] }]),
+	spell(
+		'fxBarrage',
+		'Barrage',
+		'point',
+		[1, 1.5, 2, 2.6].map((delay): EffectDef => ({ type: 'after', delay, effects: [hurt(3, 40)] }))
+	),
+	spell('fxArrow', 'Arrow', 'direction', [missile()]),
+	spell('fxHawk', 'Hawk', 'direction', [missile({ speed: 10 })]),
+	spell('fxRock', 'Rock', 'direction', [missile({ speed: 9 })]),
+	spell('fxOrb', 'Orb', 'direction', [missile({ speed: 11 })]),
+	spell('fxTornado', 'Tornado', 'direction', [missile({ delay: 0.75, speed: 8, radius: 1.4 })]),
+	spell('fxTether', 'Tether', 'unit', [{ type: 'buff', buff: 'fxBound', duration: 3 }]),
+	spell('fxBleed', 'Bleed (stacks)', 'unit', [{ type: 'buff', buff: 'fxBleeding', duration: 6, stack: true }])
+]
+
+/** The glows a buff can wear on its carrier (the `glow` style's shapes), one buff each */
+export const GLOWS = ['rise', 'fall', 'dust', 'about', 'column', 'ring', 'shell'] as const
+export const glowBuff = (shape: string) => `fxGlow${shape[0]!.toUpperCase()}${shape.slice(1)}`
+
+const buffs: BuffDef[] = [
+	{ id: 'fxBound', name: 'Bound', duration: 3, harmful: true },
+	{ id: 'fxBleeding', name: 'Bleeding', duration: 6, harmful: true, maxStacks: 5 },
+	...GLOWS.map((shape): BuffDef => ({ id: glowBuff(shape), name: `Glow (${shape})`, duration: 60 }))
+]
+
+/** The caster casts a spell by its id: at the dummy, at its spot, toward it, or with no aim, as the spell is aimed */
+export const cast = defineCommand('fx.cast', { ability: text }, (world, _player, { ability }) => {
+	const caster = [...world.units.values()].find((unit) => unit.def.id === CASTER && unit.alive)
+	const dummy = [...world.units.values()].find((unit) => unit.def.id === UNIT.dummy && unit.alive)
+	const def = SPELLS.find((each) => each.id === ability)
+	if (!caster || !dummy || !def) return
+	if (def.target === 'none') caster.order('cast', { ability })
+	else if (def.target === 'unit') caster.order('cast', { ability, target: dummy.id })
+	else caster.order('cast', { ability, point: { x: dummy.pos.x, z: dummy.pos.z } })
+})
+
+/** Puts the glow of a shape on the caster, the others off; `none` takes them all off */
+export const aura = defineCommand('fx.aura', { shape: text }, (world, _player, { shape }) => {
+	const caster = [...world.units.values()].find((unit) => unit.def.id === CASTER && unit.alive)
+	if (!caster) return
+	for (const each of GLOWS) removeBuff(world, caster, glowBuff(each))
+	if ((GLOWS as readonly string[]).includes(shape)) applyBuff(world, caster, glowBuff(shape), 60, caster)
+})
+
+export const spells: ExampleDef = {
+	id: 'fx-spell-styles',
+	category: 'fx',
+	title: 'How spells are drawn',
+	summary:
+		'A caster with a spell for each style the client draws abilities in: rings, bursts, slams, a smash telegraphed on the ground as it winds up, a falling star, a barrage, missiles of four shapes, a tornado, a tether, stacks. Pick a spell to cast it at the dummy, or an aura to wear.',
+	tags: ['spell styles', 'abilities', 'AbilityLook', 'presetSpellStyles', 'aura', 'glow', 'buff', 'missile', 'tornado', 'tether', 'barrage'],
+	// two players: the caster's and the dummies'
+	map: () => exampleField({ name: 'Spells', players: 2 }),
+	start: (world) => {
+		world.spawn(CASTER, { at: CASTER_AT, owner: PLAYER, facing: 0 })
+		world.spawn(UNIT.dummy, { at: MARK_AT, owner: ENEMY })
+		for (const dx of [-4, 4]) world.spawn(UNIT.dummy, { at: { x: MARK_AT.x + dx, z: MARK_AT.z + 2 }, owner: ENEMY })
+	},
+	source: ['examples/fx/spells.ts', 'examples/fx/spells.look.ts']
+}
+
+/** Registers the caster, its spells, the buffs and the commands */
+export function spellsRules(game: Game<any>): void {
+	for (const buff of buffs) game.buff(buff)
+	for (const ability of SPELLS) game.ability(ability)
+	game.unit({
+		id: CASTER,
+		name: 'Spellweaver',
+		kind: 'unit',
+		radius: 0.45,
+		stats: { health: 800, mana: 500, manaRegen: 50, attackDamage: 10, attackRange: 6, moveSpeed: 0 },
+		sight: 16,
+		abilities: SPELLS.map((each) => each.id)
+	})
+	game.command(cast)
+	game.command(aura)
+}

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

@@ -0,0 +1,31 @@
+/**
+ * What the effects' examples share on the client's side: the camera put close to where an effect plays, and the units
+ * of a type found as the screen knows them. Client code: only looks files import it
+ */
+import type { GameClientApi } from '@v12-engine/client'
+
+/** Looks at a spot from `distance` cells away, `pitch` radians down from level (0.75 a little low, 1.1 steep), turned `yaw` */
+export function aim(client: GameClientApi, at: { x: number; z: number }, distance: number, pitch = 0.8, yaw?: number): void {
+	client.camera.setPose({ x: at.x, z: at.z, distance, pitch, yaw: yaw ?? client.camera.pose().yaw })
+}
+
+/** The ids of the units of a type the screen knows of, alive, in the order they came into the world */
+export function idsOf(client: GameClientApi, type: string): number[] {
+	const ids: number[] = []
+	for (const entity of client.state.entities.values()) if (entity.def.id === type && entity.health > 0) ids.push(entity.id)
+	return ids.sort((a, b) => a - b)
+}
+
+/** Where a unit is drawn now, on the ground: where it is when it is not drawn */
+export function where(client: GameClientApi, id: number): { x: number; z: number } | undefined {
+	const drawn = client.renderer.kit.drawn(id)
+	if (drawn) return { x: drawn.position.x, z: drawn.position.z }
+	const entity = client.state.entities.get(id)
+	return entity && { x: entity.pos.x, z: entity.pos.z }
+}
+
+/** Runs `step` every frame with the seconds since the last, until what it gives back is called */
+export function everyFrame(client: GameClientApi, step: (dt: number) => void): () => void {
+	const observer = client.scene.onBeforeRenderObservable.add(() => step(Math.min(client.scene.getEngine().getDeltaTime() / 1000, 0.1)))
+	return () => client.scene.onBeforeRenderObservable.remove(observer)
+}