@v12-engine/create 0.1.1 → 0.4.0

package/starters/examples/src/examples/dynamic-map/looks.ts

@@ -0,0 +1,301 @@
+/**
+ * The dynamic-map examples on the client's side: a click on the ground sends where it was to the rules (the brush,
+ * the paint), the tree and the grass the examples grow, and the buttons. Nothing of the ground is drawn here: the
+ * client draws it again by itself as the rules reshape it (a `ground` event, `world.reshapeGround`)
+ */
+import type { GameClientApi, UnitLook } from '@v12-engine/client'
+import { foliage, presetFoliage, presetFx } from '@v12-engine/client'
+import { button, type CategoryLooks, type ExampleLook, readout, select, slider, toggle } from '../../shell/look'
+import {
+	BRUSHES,
+	clearRoad,
+	cutRamp,
+	GRASS,
+	growGrass,
+	lower,
+	paint,
+	PAINTS,
+	plantWood,
+	raiseLand,
+	raiseWall,
+	relay,
+	road,
+	sculpt,
+	setFlood,
+	sink,
+	spreadSnow,
+	TREE
+} from './index'
+
+const TREES = ['common_tree_1', 'common_tree_2', 'common_tree_3', 'common_tree_5', 'pine_1', 'pine_2', 'pine_3', 'pine_5']
+
+const tree: UnitLook = {
+	height: 3,
+	looks: Object.fromEntries(TREES.map((name) => [name, { src: `forest/${name}.glb`, scale: 0.8 }])),
+	mix: TREES,
+	vary: { scale: 0.25, lean: 0.06 },
+	shapes: [
+		{ shape: 'cylinder', size: [0.3, 1, 0.3], offset: [0, 0.5, 0], color: [0.45, 0.31, 0.18] },
+		{ shape: 'cone', size: [1.5, 1.8, 1.5], offset: [0, 1.7, 0], color: [0.22, 0.45, 0.18] }
+	],
+	// planted: it grows up out of the ground, leaves shaken off it as it is whole; felled, it falls
+	construction: { motion: 'grow', done: { fx: 'leaves' } },
+	death: { collapse: { look: 'topple', time: 2.5 }, fx: 'leaves' }
+}
+
+/**
+ * The camera over a point: how far back and how steeply, turned as it is. Farther than the player may zoom out (48
+ * cells), the limit is let out for this example: what it gives back puts it back
+ */
+function look(client: GameClientApi, x: number, z: number, distance: number, pitch = 50): () => void {
+	if (distance > client.camera.farthest) client.camera.setLimits({ max: distance })
+	client.camera.setPose({ x, z, distance, yaw: client.camera.pose().yaw, pitch: (pitch * Math.PI) / 180 })
+	return () => client.camera.setLimits({ max: 48 })
+}
+
+/** Where on the ground the pointer is, or nothing over the sky */
+function groundUnder(client: GameClientApi, event: PointerEvent): { x: number; z: number } | null {
+	const canvas = client.scene.getEngine().getRenderingCanvas()
+	if (!canvas) return null
+	const rect = canvas.getBoundingClientRect()
+	// the client's own (`GameClient.groundAt`): what a click picks; not in `GameClientApi`, so asked for by name
+	const picker = client as GameClientApi & { groundAt?: (x: number, y: number) => { x: number; z: number } | null }
+	return picker.groundAt?.(event.clientX - rect.left, event.clientY - rect.top) ?? null
+}
+
+/**
+ * Left clicks on the ground, and drags, while `on()` says so, are `stroke`'s, not the selection's: one stroke where it
+ * went down and one every so often as it is dragged. What it gives back stops listening
+ */
+function brushClicks(client: GameClientApi, on: () => boolean, stroke: (at: { x: number; z: number }) => void, every = 0.12): () => void {
+	const canvas = client.scene.getEngine().getRenderingCanvas()
+	let down = false
+	let last = 0
+	const at = (event: PointerEvent) => {
+		const ground = groundUnder(client, event)
+		if (!ground) return
+		const now = performance.now() / 1000
+		if (now - last < every) return
+		last = now
+		stroke(ground)
+	}
+	const press = (event: PointerEvent) => {
+		if (!on() || event.button !== 0) return
+		event.stopImmediatePropagation()
+		down = true
+		last = 0
+		at(event)
+	}
+	const move = (event: PointerEvent) => {
+		if (!down || !on()) return
+		event.stopImmediatePropagation()
+		at(event)
+	}
+	const up = (event: PointerEvent) => {
+		if (!down) return
+		down = false
+		event.stopImmediatePropagation()
+	}
+	canvas?.addEventListener('pointerdown', press, { capture: true })
+	canvas?.addEventListener('pointermove', move, { capture: true })
+	window.addEventListener('pointerup', up, { capture: true })
+	return () => {
+		canvas?.removeEventListener('pointerdown', press, { capture: true })
+		canvas?.removeEventListener('pointermove', move, { capture: true })
+		window.removeEventListener('pointerup', up, { capture: true })
+	}
+}
+
+/** Where the camera looks: what the buttons act on when nothing is clicked */
+const focus = (client: GameClientApi) => {
+	const pose = client.camera.pose()
+	return { x: pose.x, z: pose.z }
+}
+
+const again = (id: string) =>
+	button(
+		'Start again',
+		(client) => client.session.send(relay.make({ example: id })),
+		'Puts the ground, its water and what stands on it back as the example started.'
+	)
+
+/** The sculpting brush, as its controls set it: one for the example, as the page has one example open at a time */
+const brush = { on: true, kind: 'Raise' as (typeof BRUSHES)[number], radius: 4 }
+const painter = { on: true, tile: 'road' as (typeof PAINTS)[number], radius: 2 }
+let seed = 1
+
+const trees = (client: GameClientApi) => client.session.snapshot().entities.filter((each) => each.type === TREE && each.health > 0).length
+
+const examples: Record<string, ExampleLook> = {
+	'dynamic-map-sculpt': {
+		controls: [
+			toggle(
+				'Sculpt with the mouse',
+				true,
+				(_client, on) => (brush.on = on),
+				'While on, a click or a drag on the ground sculpts it with the brush below; off, the mouse selects and orders as in a game.'
+			),
+			select(
+				'Brush',
+				BRUSHES,
+				'Raise',
+				(_client, kind) => (brush.kind = kind as (typeof BRUSHES)[number]),
+				'What the next stroke does: raise a hill or dig a hollow a little more each time, flatten, lift a plateau with cliffs, or sink a pool of water. Click the ground or the button below to use it.'
+			),
+			slider(
+				'Size',
+				{ min: 1, max: 10, step: 0.5, value: 4 },
+				(_client, radius) => (brush.radius = radius),
+				'How wide the brush is, in cells: takes effect on the next stroke.'
+			),
+			button(
+				'Where the camera looks',
+				(client) => client.session.send(sculpt.make({ ...focus(client), radius: brush.radius, brush: brush.kind })),
+				'One stroke of the brush in the middle of the screen, without clicking the ground.'
+			),
+			again('dynamic-map-sculpt')
+		],
+		ready: (client) => {
+			brush.on = true
+			const camera = look(client, 24, 23, 44, 48)
+			const stop = brushClicks(
+				client,
+				() => brush.on,
+				(at) => client.session.send(sculpt.make({ ...at, radius: brush.radius, brush: brush.kind }))
+			)
+			return () => {
+				stop()
+				camera()
+			}
+		}
+	},
+	'dynamic-map-paint': {
+		controls: [
+			toggle(
+				'Paint with the mouse',
+				true,
+				(_client, on) => (painter.on = on),
+				'While on, a click or a drag on the ground paints it with the tile below; off, the mouse selects and orders as in a game.'
+			),
+			select(
+				'Paint',
+				PAINTS,
+				'road',
+				(_client, tile) => (painter.tile = tile as (typeof PAINTS)[number]),
+				'Which tile the brush paints: drag on the ground to lay it, its edges blending into the tiles round it.'
+			),
+			slider(
+				'Size',
+				{ min: 0, max: 8, step: 1, value: 2 },
+				(_client, radius) => (painter.radius = radius),
+				'How wide the paint brush is, in cells (0 is a single cell): takes effect on the next stroke.'
+			),
+			button('A road across', (client) => client.session.send(road.make({})), 'Paints a winding road from the west edge of the field to the east.'),
+			button(
+				'Snow spreads',
+				(client) => client.session.send(spreadSnow.make(focus(client))),
+				'Snow spreads out from the middle of the screen, a ring of tiles at a time, until it covers the field.'
+			),
+			again('dynamic-map-paint')
+		],
+		ready: (client) => {
+			painter.on = true
+			const camera = look(client, 24, 23, 44, 50)
+			const stop = brushClicks(
+				client,
+				() => painter.on,
+				(at) => client.session.send(paint.make({ ...at, radius: painter.radius, tile: painter.tile })),
+				0.05
+			)
+			return () => {
+				stop()
+				camera()
+			}
+		}
+	},
+	'dynamic-map-water': {
+		controls: [
+			button(
+				'Flood',
+				(client) => client.session.send(setFlood.make({ level: -0.3 })),
+				'Fills the valley up to just under its banks: deep in the middle, a shallow ford in the east that units can wade.'
+			),
+			button(
+				'Half full',
+				(client) => client.session.send(setFlood.make({ level: -1.3 })),
+				'Sets the water halfway up: the river runs only in the deepest middle, the ford dry.'
+			),
+			button('Drain', (client) => client.session.send(setFlood.make({ level: -3 })), 'Drains the valley: the water goes and its bare bed shows.'),
+			again('dynamic-map-water')
+		],
+		ready: (client) => look(client, 24, 24, 46, 52)
+	},
+	'dynamic-map-cliffs': {
+		controls: [
+			button(
+				'Raise a cliff wall',
+				(client) => client.session.send(raiseWall.make({})),
+				'Lifts a band of the field a level up, across it from west to east: cliffs on both sides, only its ends to go round.'
+			),
+			button(
+				'Cut a ramp',
+				(client) => client.session.send(cutRamp.make({})),
+				'Cuts a ramp through the middle of the wall, up one side, over and down the other: the way across is open.'
+			),
+			button('Lower it all', (client) => client.session.send(lower.make({})), 'Takes the wall and the ramp away: the field flat again.'),
+			again('dynamic-map-cliffs')
+		],
+		ready: (client) => look(client, 24, 24, 48, 50)
+	},
+	'dynamic-map-generate': {
+		controls: [
+			button(
+				'Raise new land',
+				(client) => client.session.send(raiseLand.make({ seed })),
+				'Generates land with the seed below and lays it into the sea on the east side: hills, plateaus, ponds and trees.'
+			),
+			button(
+				'Another seed',
+				(client) => client.session.send(raiseLand.make({ seed: ++seed })),
+				'The next seed: different land in its place, the trees of the old one gone with it.'
+			),
+			button('Back to the sea', (client) => client.session.send(sink.make({})), 'Sinks the land again: the sea back where it was.'),
+			readout('Seed', () => String(seed), 'The seed the land was made from: the same seed always makes the same land.'),
+			readout('Trees', (client) => String(trees(client)))
+		],
+		ready: (client) => look(client, 30, 24, 54, 55)
+	},
+	'dynamic-map-forest': {
+		controls: [
+			button(
+				'Plant a wood',
+				(client) => client.session.send(plantWood.make({})),
+				'Plants a round wood in the middle of the field: each tree grows up out of the ground.'
+			),
+			button('Grow grass', (client) => client.session.send(growGrass.make({})), 'Grass grows over the meadow, eased in over five seconds.'),
+			button(
+				'Clear a road',
+				(client) => client.session.send(clearRoad.make({})),
+				'Clears a winding road through the wood: its trees fall, its grass goes, the ground is paved, and the footmen walk along it.'
+			),
+			again('dynamic-map-forest'),
+			readout('Trees', (client) => String(trees(client)))
+		],
+		ready: (client) => look(client, 25, 24, 46, 52)
+	}
+}
+
+export const category: CategoryLooks = {
+	looks: examples,
+	view: (view) => ({
+		...view,
+		units: {
+			...view.units,
+			looks: { ...view.units?.looks, [TREE]: tree },
+			// no bars over a tree, growing or standing
+			hud: { ...view.units?.hud, bars: (entity) => (entity.def.id === TREE ? { hide: true } : view.units?.hud?.bars?.(entity)) }
+		},
+		ground: { ...view.ground, cellLayers: { ...view.ground?.cellLayers, [GRASS]: foliage(presetFoliage.meadow) } },
+		fx: { ...view.fx, defs: { ...presetFx(['leaves', 'dust']), ...view.fx?.defs } }
+	})
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Blood and what it leaves, on the client's side: the view's `units.blood` (`BloodLook`: its colour, how many drops,
+ * the pools and how long they stay) and `bloodFor`, which decides it hit by hit: a death bursts (`blood-burst`), and a
+ * skeleton sheds bone dust rather than blood. The marks dry away over their `seconds`; the player's `decals` setting
+ * (`client.decalsAmount`) says how much lies on the ground and how long
+ */
+import type { BloodLook, UnitLook } from '@v12-engine/client'
+import { button, type ExampleLook, slider, toggle } from '../../shell/look'
+import { character, hold, ONE_HANDED, person } from '../common/looks'
+import { clash, lineUpAgain, SKELETON } from './blood'
+import { aim } from './stage'
+
+/** The skeleton: the shared art's warrior, an axe in hand */
+export const skeletonLook: UnitLook = {
+	height: 1.8,
+	model: character('skeleton_warrior', 0.7, { hold: [hold('axe_1handed')] }),
+	attacks: [ONE_HANDED],
+	shapes: person(1.8, [0.85, 0.82, 0.72])
+}
+
+/** Every blow's blood: dark red drops, a pool where one falls, staying 40 seconds */
+const BLOOD: BloodLook = { color: [0.5, 0.02, 0.03], amount: 20, pool: 1.3, seconds: 40 }
+
+export const bloodLook: ExampleLook = {
+	view: (view) => ({
+		...view,
+		units: {
+			...view.units,
+			blood: BLOOD,
+			bloodFor: (entity, event) => {
+				// bones bleed dust; the rest bleed, and burst as they die
+				if (entity.def.id === SKELETON) return { color: [0.82, 0.78, 0.66], amount: 10, pool: 0, spray: 'dust' }
+				return event.kind === 'death' ? { ...BLOOD, amount: 70, pool: 1.8, spray: 'blood-burst' } : undefined
+			}
+		}
+	}),
+	controls: [
+		button(
+			'Fight',
+			(client) => client.session.send(clash.make({})),
+			'Both sides go at each other: footmen bleed and leave pools, the skeletons shed bone dust'
+		),
+		button(
+			'Line them up again',
+			(client) => client.session.send(lineUpAgain.make({})),
+			'Takes everyone away and lines them up again: the stains on the ground stay, drying'
+		),
+		toggle('Blood', true, (client, on) => (client.blood = on), 'Off: the same blows land with no drops, no pools and no bursts'),
+		slider(
+			'Marks on the ground',
+			{ min: 0, max: 1, step: 0.05, value: 1 },
+			(client, value) => (client.decalsAmount = value),
+			"The player's setting for marks on the ground: at 0 no pools are left, higher keeps more and longer"
+		)
+	],
+	ready: (client) => {
+		aim(client, { x: 24, z: 24 }, 18, 0.72)
+		client.blood = true
+		client.decalsAmount = 1
+		client.session.send(clash.make({}))
+	}
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Blood and the marks it leaves, on the rules' side: footmen against skeletons, a fight to start and to lay out again.
+ * The blood is the screen's (`./blood.look.ts`, the view's `units.blood`): the rules only deal the blows
+ */
+import { defineCommand, type Game, type World } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+
+export const SKELETON = 'fxSkeleton'
+
+/** Two ranks facing each other across the middle */
+function lineUp(world: World): void {
+	for (let i = 0; i < 6; i++) {
+		world.spawn(UNIT.footman, { at: { x: 20.5 + i * 1.4, z: 19 }, owner: PLAYER })
+		world.spawn(SKELETON, { at: { x: 20.5 + i * 1.4, z: 29 }, owner: ENEMY })
+	}
+}
+
+/** Both sides go at each other, fighting what they meet */
+export const clash = defineCommand('fx.clash', {}, (world) => {
+	for (const unit of world.units.values()) {
+		if (!unit.alive) continue
+		if (unit.owner === PLAYER) unit.order('attackMove', { x: unit.pos.x, z: 30 })
+		if (unit.owner === ENEMY) unit.order('attackMove', { x: unit.pos.x, z: 18 })
+	}
+})
+
+/** Takes everyone away and lines them up again: the blood on the ground stays, drying */
+export const lineUpAgain = defineCommand('fx.lineUp', {}, (world) => {
+	for (const unit of [...world.units.values()]) if (unit.alive) world.kill(unit, undefined, false, 'removed')
+	lineUp(world)
+})
+
+export const blood: ExampleDef = {
+	id: 'fx-blood',
+	category: 'fx',
+	title: 'Blood and what it leaves',
+	summary:
+		'Footmen against skeletons with blood on: a spray where each blow lands, a burst where one dies, pools and splatters left on the ground to dry. Fight, then line them up again and fight on the stains; turn blood off to see the same fight without.',
+	tags: ['blood', 'gore', 'decals', 'splatter', 'pools', 'BloodLook', 'death'],
+	map: () => exampleField({ name: 'Field', players: 2, tile: 'dirt' }),
+	start: lineUp,
+	source: ['examples/fx/blood.ts', 'examples/fx/blood.look.ts']
+}
+
+/** Registers the skeletons and the commands */
+export function bloodRules(game: Game<any>): void {
+	game.unit({
+		id: SKELETON,
+		name: 'Skeleton',
+		kind: 'unit',
+		radius: 0.45,
+		stats: { health: 380, attackDamage: 16, attackSpeed: 1, attackRange: 0.5, armor: 8, moveSpeed: 3.6 },
+		sight: 10,
+		attacks: [{ damagePoint: 0.45, acquisitionRange: 8 }]
+	})
+	game.command(clash)
+	game.command(lineUpAgain)
+}

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

@@ -0,0 +1,86 @@
+/**
+ * The feel of a hit, on the client's side: the view's `feel` (`FeelLook`), written out whole so each piece can be
+ * read and changed: the flash of the struck, its flinch, the hit-stop, the swing's streak, and the shake and words of a
+ * critical strike and a kill. Each piece `false` turns it off; `feel: false` all of it. The player's own settings turn
+ * the hit-stop (`client.hitStop`) and the shake down. The card's Flash and Shake play the same by hand (`kit.flash`,
+ * `kit.shake`)
+ */
+import { type FeelLook, presetFloats, type UnitLook } from '@v12-engine/client'
+import { button, type ExampleLook, slider, toggle } from '../../shell/look'
+import { character, hold, person, TWO_HANDED } from '../common/looks'
+import { UNIT } from '../common/units'
+import { BRUTE, BRUTE_AT, strike } from './feel'
+import { fight } from './fight'
+import { aim, idsOf, where } from './stage'
+
+/** The brute: the knight, bigger, a two-handed sword leaving a warm streak */
+export const bruteLook: UnitLook = {
+	height: 2.3,
+	model: character('knight', 0.95, { hold: [hold('sword_2handed')], animations: { attack: 'Melee_2H_Attack_Chop' } }),
+	attacks: [{ ...TWO_HANDED, trail: { color: [1, 0.78, 0.4], width: 0.3, seconds: 0.24, alpha: 0.85 } }],
+	shapes: person(2.3, [0.6, 0.6, 0.65])
+}
+
+/** The feel, every piece of it: a little more than the client's own, so it reads */
+const FEEL: FeelLook = {
+	// the struck goes white a moment, warm and longer on a critical strike
+	flash: { color: [1, 1, 1], time: 0.12, strength: 0.45, crit: { color: [1, 0.75, 0.4], time: 0.2, strength: 0.85 } },
+	// a flinch clip where it stands, a nudge away where it is busy; a heavy hit is 8% of its health or more
+	reaction: { clip: 'Hit_A', nudge: 0.18, heavy: 0.08, crits: true },
+	// seconds both pause: a critical strike, a kill, a heavy hit
+	hitStop: { crit: 0.09, kill: 0.13, heavy: 0.03 },
+	// the streak behind every melee swing, where an attack's look says none of its own
+	trails: { color: [1, 1, 1], width: 0.14, seconds: 0.18, melee: true },
+	// the view shaken, and words over the struck
+	crit: { shake: 0.25, float: 'Crit!', who: 'all' },
+	kill: { shake: 0.4, who: 'all' }
+}
+
+export const feelLook: ExampleLook = {
+	view: (view) => ({ ...view, feel: FEEL, hud: { ...view.hud, floats: { ...presetFloats(['damage', 'crit']), ...view.hud?.floats } } }),
+	controls: [
+		button('Strike', (client) => client.session.send(strike.make({ kind: 'hit' })), 'The brute strikes the dummy once: a flash and a flinch'),
+		button(
+			'Critical strike',
+			(client) => client.session.send(strike.make({ kind: 'crit' })),
+			'A critical strike: a warmer flash, a short pause, a shake and words'
+		),
+		button(
+			'Killing blow',
+			(client) => client.session.send(strike.make({ kind: 'kill' })),
+			'A footman brought and cut down: the longest pause, the hardest shake'
+		),
+		toggle(
+			'Keep swinging',
+			false,
+			(client, on) => client.session.send(fight.make({ on })),
+			'The brute attacks the dummy over and over: watch the streak behind each swing'
+		),
+		slider(
+			'Hit-stop',
+			{ min: 0, max: 1, step: 0.05, value: 1 },
+			(client, value) => (client.hitStop = value),
+			"The player's setting for the pause on heavy blows: at 0 there is none, at 1 the whole of what the game asks"
+		),
+		button(
+			'Flash',
+			(client) => {
+				for (const id of idsOf(client, UNIT.dummy)) client.renderer.kit.flash(id, [0.4, 0.8, 1], 0.3)
+			},
+			'Flashes the dummies blue by hand (kit.flash)'
+		),
+		button(
+			'Shake',
+			(client) => {
+				const [brute] = idsOf(client, BRUTE)
+				const at = (brute !== undefined && where(client, brute)) || BRUTE_AT
+				client.renderer.kit.shake(at.x, at.z, 0.8)
+			},
+			'Shakes the view by hand (kit.shake): less the farther it is'
+		)
+	],
+	ready: (client) => {
+		aim(client, { x: BRUTE_AT.x, z: BRUTE_AT.z + 1 }, 15, 0.7)
+		client.hitStop = 1
+	}
+}

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

@@ -0,0 +1,57 @@
+/**
+ * The feel of a hit, on the rules' side: a brute and dummies to strike. A blow is damage dealt with `world.damage`
+ * (an attack's, a critical one, one that kills); the flash, the flinch, the pause, the shake and the streak of the swing
+ * are all the screen's (`./feel.look.ts`, the view's `feel`)
+ */
+import { defineCommand, type Game, oneOf } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+import { nearestEnemy } from './fight'
+
+export const BRUTE = 'fxBrute'
+export const BRUTE_AT = { x: 24, z: 22 }
+
+/** The brute strikes the nearest dummy: a plain blow, a critical one, or one that kills a footman brought for it */
+export const strike = defineCommand('fx.strike', { kind: oneOf('hit', 'crit', 'kill') }, (world, _player, { kind }) => {
+	const brute = [...world.units.values()].find((unit) => unit.def.id === BRUTE && unit.alive)
+	if (!brute) return
+	if (kind === 'kill') {
+		// a footman to fall, in front of the brute: the blow that kills it is a critical one, the most the screen shows
+		const victim = world.spawn(UNIT.footman, { at: { x: brute.pos.x + 1.4, z: brute.pos.z + 0.4 }, owner: ENEMY })
+		world.damage(victim, 9999, brute, { attack: true, crit: true })
+		return
+	}
+	const dummy = nearestEnemy(world, brute)
+	if (dummy) world.damage(dummy, kind === 'crit' ? 180 : 60, brute, { attack: true, crit: kind === 'crit' })
+})
+
+export const feel: ExampleDef = {
+	id: 'fx-hit-feel',
+	category: 'fx',
+	title: 'The feel of a hit',
+	summary:
+		'What makes a blow land: the struck flashes and flinches, both pause a few frames on a critical strike or a kill (hit-stop), the view shakes, the swing leaves a streak. Strike, crit or kill, or let the brute swing on his own.',
+	tags: ['feel', 'hit-stop', 'flash', 'flinch', 'shake', 'trail', 'crit', 'juice', 'FeelLook'],
+	map: () => exampleField({ name: 'Yard', players: 2 }),
+	start: (world) => {
+		world.spawn(BRUTE, { at: BRUTE_AT, owner: PLAYER })
+		world.spawn(UNIT.dummy, { at: { x: BRUTE_AT.x + 1.5, z: BRUTE_AT.z + 1 }, owner: ENEMY })
+		world.spawn(UNIT.dummy, { at: { x: BRUTE_AT.x - 2.5, z: BRUTE_AT.z + 2 }, owner: ENEMY })
+	},
+	source: ['examples/fx/feel.ts', 'examples/fx/feel.look.ts', 'examples/fx/fight.ts']
+}
+
+/** Registers the brute and the command */
+export function feelRules(game: Game<any>): void {
+	game.unit({
+		id: BRUTE,
+		name: 'Brute',
+		kind: 'unit',
+		radius: 0.55,
+		stats: { health: 2000, attackDamage: 70, attackSpeed: 0.9, attackRange: 0.8, armor: 20, moveSpeed: 3.5 },
+		sight: 10,
+		// he strikes when told (`fx.fight`, `fx.strike`), not of himself
+		attacks: [{ damagePoint: 0.45, acquisitionRange: 0 }]
+	})
+	game.command(strike)
+}

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

@@ -0,0 +1,28 @@
+/**
+ * What several of the effects' examples share on the rules' side: a command that sets the player's units on the
+ * nearest enemy, or stops them, so that blows land for the screen to show
+ */
+import { bool, defineCommand, type Entity, type World, exactMath } from '@v12-engine/engine'
+import { ENEMY, PLAYER } from '../common/units'
+
+/** The living enemy nearest a unit */
+export function nearestEnemy(world: World, unit: Entity): Entity | undefined {
+	let best: Entity | undefined
+	let bestAway = Infinity
+	for (const other of world.units.values()) {
+		if (!other.alive || other.owner !== ENEMY) continue
+		const away = exactMath.hypot(other.pos.x - unit.pos.x, other.pos.z - unit.pos.z)
+		if (away < bestAway) [best, bestAway] = [other, away]
+	}
+	return best
+}
+
+/** Every unit of the player's goes for the enemy nearest it (`on`), or stops where it is */
+export const fight = defineCommand('fx.fight', { on: bool }, (world, _player, { on }) => {
+	for (const unit of world.units.values()) {
+		if (!unit.alive || unit.owner !== PLAYER || !unit.def.attacks?.length) continue
+		const enemy = on ? nearestEnemy(world, unit) : undefined
+		if (enemy) unit.order('attack', enemy)
+		else unit.order('stop')
+	}
+})