@v12-engine/create 0.1.0 → 0.4.0

package/starters/examples/src/examples/abilities/control.ts

@@ -0,0 +1,158 @@
+/**
+ * Crowd control: buffs with a flag, put on by the `buff` effect. Stun, root, silence, disarm, knocked up, knocked
+ * down, fear, charm, taunt, sleep, polymorph, suppression and a slow; then cleanse and dispel to take them off. The
+ * footmen walk up and down so that what holds them, slows them or turns them shows
+ */
+import { type AbilityDef, type BuffDef, defineCommand, type World } from '@v12-engine/engine'
+import { exampleField } from '../define'
+import { ENEMY } from '../common/units'
+import type { Family } from './family'
+import { caster, lineUp, put, sparring } from './kit'
+
+/** A crowd control buff of `seconds`, harmful, with its flags */
+const held = (id: string, name: string, duration: number, flags: Partial<BuffDef>): BuffDef => ({ id, name, harmful: true, duration, ...flags })
+
+const buffs: BuffDef[] = [
+	held('abilitiesStunned', 'Stunned', 2, { stun: true }),
+	held('abilitiesRooted', 'Rooted', 3, { root: true }),
+	held('abilitiesSilenced', 'Silenced', 3, { silence: true }),
+	held('abilitiesDisarmed', 'Disarmed', 3, { disarm: true }),
+	// a stun that throws it up, and one that lays it down: stuns with a look
+	held('abilitiesKnockedUp', 'Airborne', 1, { stun: true, airborne: true }),
+	held('abilitiesKnockedDown', 'Knocked down', 2, { stun: true, down: true }),
+	// controls: who carries one walks away from (fear), toward (charm) or attacks (taunt) whoever put it on
+	held('abilitiesFeared', 'Terrified', 2.5, { control: 'fear' }),
+	held('abilitiesCharmed', 'Charmed', 2.5, { control: 'charm' }),
+	held('abilitiesTaunted', 'Taunted', 3, { control: 'taunt' }),
+	// a stun broken by the first damage
+	held('abilitiesAsleep', 'Asleep', 6, { stun: true, breaksOn: ['damage'] }),
+	// a polymorph: can't attack or cast, slower, and drawn as a sheep (`drawnAs` on its look)
+	held('abilitiesHexed', 'Hexed', 4, { disarm: true, silence: true, percent: { moveSpeed: -0.4 } }),
+	// held like a stun, but tenacity doesn't shorten it nor cleanse take it off
+	held('abilitiesSuppressed', 'Suppressed', 2.5, { suppress: true }),
+	held('abilitiesFrost', 'Frost', 4, { percent: { moveSpeed: -0.6, attackSpeed: -0.3 } })
+]
+
+/** An ability putting a buff on the enemy it is cast on, or on every enemy within `radius` of the spot */
+const putOn = (id: string, name: string, hotkey: string, buff: string, description: string, radius?: number): AbilityDef => ({
+	id,
+	name,
+	description,
+	hotkey,
+	target: radius ? 'point' : 'unit',
+	...(!radius && { targets: { enemies: true } }),
+	range: 12,
+	cooldown: 0.5,
+	effects: [{ type: 'buff', buff, ...(radius && { radius }) }]
+})
+
+const abilities: AbilityDef[] = [
+	putOn('abilitiesThunderBolt', 'Stun', 'Q', 'abilitiesStunned', 'Can not move, attack or cast for 2 seconds; what it was told waits'),
+	putOn('abilitiesEntangle', 'Root', 'W', 'abilitiesRooted', 'Can not move for 3 seconds, but still attacks and casts'),
+	putOn('abilitiesSilence', 'Silence', 'E', 'abilitiesSilenced', 'Can not cast for 3 seconds, everyone within 3 of the spot', 3),
+	putOn('abilitiesDisarm', 'Disarm', 'R', 'abilitiesDisarmed', 'Can not attack for 3 seconds: the brute stops swinging'),
+	putOn('abilitiesKnockUp', 'Knock up', 'T', 'abilitiesKnockedUp', 'Thrown in the air for a second, everyone within 2.5 of the spot', 2.5),
+	putOn('abilitiesKnockDown', 'Knock down', 'D', 'abilitiesKnockedDown', 'Laid on the ground for 2 seconds'),
+	{
+		// on everyone near the caster: they run from it
+		id: 'abilitiesTerrify',
+		name: 'Fear',
+		description: 'Every enemy within 12 runs away from the caster for 2.5 seconds',
+		hotkey: 'F',
+		target: 'none',
+		cooldown: 0.5,
+		effects: [{ type: 'buff', buff: 'abilitiesFeared', radius: 12 }]
+	},
+	putOn('abilitiesCharm', 'Charm', 'G', 'abilitiesCharmed', 'Walks helplessly toward the caster for 2.5 seconds'),
+	putOn('abilitiesTaunt', 'Taunt', 'Z', 'abilitiesTaunted', 'Must attack the caster for 3 seconds: cast on the brute, it leaves the footman'),
+	putOn('abilitiesSleep', 'Sleep', 'X', 'abilitiesAsleep', 'Asleep for 6 seconds, until something hurts it'),
+	putOn('abilitiesHex', 'Polymorph', 'C', 'abilitiesHexed', 'A sheep for 4 seconds: can not attack or cast, and slow'),
+	putOn('abilitiesNetherGrasp', 'Suppress', 'V', 'abilitiesSuppressed', 'Held for 2.5 seconds; cleanse does not take it off'),
+	putOn('abilitiesFrostNova', 'Slow', 'B', 'abilitiesFrost', 'Everyone within 3 of the spot is 60% slower for 4 seconds', 3),
+	{
+		// cleanse takes off stuns, roots, silences, disarms, controls and slows; allies when not said, the enemies here
+		id: 'abilitiesUnbind',
+		name: 'Cleanse',
+		description: 'Takes stuns, roots, silences, fears and slows off every enemy within 12 (not a suppression)',
+		hotkey: 'N',
+		target: 'none',
+		cooldown: 0.5,
+		effects: [{ type: 'cleanse', radius: 12, affects: 'enemies' }]
+	},
+	{
+		// dispel takes off whatever buff may be dispelled, the good and the bad
+		id: 'abilitiesPurge',
+		name: 'Dispel',
+		description: 'Takes every buff that may be dispelled off every unit within 12, a suppression too',
+		hotkey: 'Y',
+		target: 'none',
+		cooldown: 0.5,
+		effects: [{ type: 'dispel', radius: 12, affects: 'all' }]
+	}
+]
+
+/**
+ * Each footman walks up and down its own line, so that what stops, slows or turns it shows; a sentry (the vision
+ * example's) across the north. The ranger who hides stays where it is
+ */
+function patrolAll(world: World): void {
+	const ranger = world.named('ranger')
+	for (const unit of world.units.values()) {
+		if (!unit.alive || unit.owner !== ENEMY || unit === ranger) continue
+		if (unit.def.id === 'abilitiesTarget') unit.order('patrol', { x: unit.pos.x, z: unit.pos.z + 6 })
+		if (unit.def.id === 'abilitiesSentry') unit.order('patrol', { x: unit.pos.x + 8, z: unit.pos.z + 2 })
+	}
+}
+
+/** Sends the footmen walking again: what a control or a stun took away from them */
+export const walkAgain = defineCommand('abilities.walk', {}, (world) => patrolAll(world))
+
+export const control: Family = {
+	abilities,
+	buffs,
+	commands: [walkAgain],
+	units: [
+		caster(
+			'abilitiesBinder',
+			'Binder',
+			abilities.map((each) => each.id),
+			{
+				stats: {
+					health: 4000,
+					healthRegen: 40,
+					mana: 1000,
+					manaRegen: 60,
+					attackDamage: 30,
+					attackSpeed: 1,
+					attackRange: 6,
+					moveSpeed: 4.2,
+					armor: 20
+				}
+			}
+		),
+		// a brute that fights what is next to it, for disarm and taunt
+		sparring('abilitiesBrute', 'Brute', {
+			radius: 0.55,
+			stats: { health: 1500, healthRegen: 30, attackDamage: 12, attackSpeed: 1, attackRange: 0.6, moveSpeed: 3.6, armor: 5 },
+			attacks: [{ damagePoint: 0.4, acquisitionRange: 2 }]
+		}),
+		// what the polymorph draws its target as (`drawnAs`): a type of its own, never put down
+		{ id: 'abilitiesSheep', name: 'Sheep', kind: 'unit', radius: 0.4, stats: { health: 10, moveSpeed: 2 }, sight: 2 }
+	],
+	example: {
+		id: 'abilities-control',
+		category: 'abilities',
+		title: 'Crowd control',
+		summary:
+			'Stun, root, silence, disarm, knock up and down, fear, charm, taunt, sleep, polymorph, suppress and slow, then cleanse and dispel to take them off. The footmen walk up and down so each shows; the brute on the right fights a footman of yours.',
+		tags: ['crowd control', 'cc', 'stun', 'root', 'silence', 'fear', 'charm', 'taunt', 'polymorph', 'sleep', 'slow', 'cleanse', 'dispel', 'knock up'],
+		source: ['examples/abilities/control.ts', 'examples/abilities/kit.ts'],
+		map: () => exampleField({ name: 'Crowd control', players: 2 }),
+		start: (world) => {
+			lineUp(world, 'abilitiesBinder', 'abilitiesTarget', 4)
+			// the brute, and a footman of yours by it to fight
+			put(world, 'abilitiesBrute', ENEMY, { x: 31, z: 22 }, 'brute', -Math.PI / 2)
+			put(world, 'abilitiesWounded', 1, { x: 29.8, z: 22 }, 'ally', Math.PI / 2)
+		}
+	}
+}

package/starters/examples/src/examples/abilities/controlLooks.ts

@@ -0,0 +1,78 @@
+/** How the crowd control example looks, and its card: a button for each hold, and one to send the footmen walking */
+import { button } from '../../shell/look'
+import { character, hold, person, sharedLooks, TWO_HANDED } from '../common/looks'
+import { control, walkAgain } from './control'
+import type { FamilyLooks } from './looks'
+import { castButton, look, readyOn, resetButton } from './lookKit'
+
+/** A buff's look on its carrier: sparks of `shape` in its colour (`glow`) */
+const glow = (color: [number, number, number], shape: string, more: Record<string, unknown> = {}) =>
+	look(color, undefined, { aura: 'glow', options: { shape, ...more } })
+
+/** The abilities cast on the brute rather than on the nearest footman */
+const onBrute = new Set(['abilitiesDisarm', 'abilitiesTaunt'])
+/** The abilities cast on a footman, where the brute is as near */
+const onFootman = new Set([
+	'abilitiesHex',
+	'abilitiesThunderBolt',
+	'abilitiesEntangle',
+	'abilitiesKnockDown',
+	'abilitiesCharm',
+	'abilitiesSleep',
+	'abilitiesNetherGrasp'
+])
+
+export const controlLooks: FamilyLooks = {
+	units: {
+		abilitiesBinder: sharedLooks.mage,
+		abilitiesBrute: { height: 2.3, model: character('barbarian', 0.95, { hold: [hold('axe_2handed')] }), attacks: [TWO_HANDED], shapes: person(2.3) },
+		// the shared art has no animals: a sheep of parts, a woolly body and a dark head
+		abilitiesSheep: {
+			height: 0.9,
+			shapes: [
+				{ shape: 'sphere', size: [0.9, 0.7, 1.1], offset: [0, 0.6, 0], color: [0.95, 0.95, 0.9] },
+				{ shape: 'sphere', size: [0.4, 0.4, 0.45], offset: [0, 0.85, 0.55], color: [0.15, 0.15, 0.15] }
+			]
+		}
+	},
+	abilities: {
+		abilitiesThunderBolt: look([1, 0.95, 0.5], 'burst'),
+		abilitiesEntangle: look([0.35, 0.8, 0.25], 'burst'),
+		abilitiesSilence: look([0.6, 0.4, 1], 'sonar'),
+		abilitiesKnockUp: look([0.8, 0.7, 0.5], 'smash'),
+		abilitiesTerrify: look([0.55, 0.15, 0.7], 'sonar'),
+		abilitiesHex: look([0.4, 1, 0.4], 'burst'),
+		abilitiesFrostNova: look([0.6, 0.85, 1], 'slam'),
+		abilitiesUnbind: look([1, 1, 1], 'sonar'),
+		abilitiesPurge: look([0.5, 1, 0.9], 'sonar'),
+		abilitiesStunned: glow([1, 0.95, 0.5], 'ring', { at: 'head' }),
+		abilitiesRooted: glow([0.35, 0.8, 0.25], 'column'),
+		abilitiesSilenced: glow([0.6, 0.4, 1], 'ring', { at: 'head' }),
+		abilitiesDisarmed: glow([0.8, 0.8, 0.8], 'ring', { at: 'head' }),
+		abilitiesAsleep: glow([0.5, 0.6, 1], 'rise'),
+		// the hexed footman drawn as a sheep
+		abilitiesHexed: look([0.4, 1, 0.4], undefined, { drawnAs: 'abilitiesSheep' }),
+		abilitiesSuppressed: glow([0.5, 0.1, 0.6], 'shell'),
+		abilitiesFrost: glow([0.6, 0.85, 1], 'fall'),
+		// the mark over a feared, charmed or taunted unit, in its colour
+		abilitiesFeared: look([0.55, 0.15, 0.7], undefined, { marker: true }),
+		abilitiesCharmed: look([1, 0.45, 0.75], undefined, { marker: true }),
+		abilitiesTaunted: look([1, 0.3, 0.2], undefined, { marker: true })
+	},
+	examples: {
+		'abilities-control': {
+			ready: (client) => {
+				readyOn(client, 'abilitiesBinder', { minX: 17, minZ: 14, maxX: 33, maxZ: 31 })
+				// the footmen set walking, once the game runs
+				client.session.send(walkAgain.make({}))
+			},
+			controls: [
+				...control.abilities.map((ability) =>
+					castButton(ability, onBrute.has(ability.id) ? { at: 'brute' } : onFootman.has(ability.id) ? { at: 'enemy2' } : {})
+				),
+				button('Walk again', (client) => client.session.send(walkAgain.make({})), 'Sends the footmen up and down their lines again'),
+				resetButton('abilities-control')
+			]
+		}
+	}
+}

package/starters/examples/src/examples/abilities/damage.ts

@@ -0,0 +1,156 @@
+/**
+ * Damage and heal: the `damage`, `heal` and `mana` effects, how much they do (by level, by the target's health, by
+ * chance), and the conditions that pick one or the other (`if`). A mage casts each on a row of sparring footmen and on a
+ * wounded ally
+ */
+import type { AbilityDef } from '@v12-engine/engine'
+import { exampleField } from '../define'
+import type { Family } from './family'
+import { caster, lineUp, sparring } from './kit'
+
+const abilities: AbilityDef[] = [
+	{
+		// the plainest: magic damage to the unit it is cast on
+		id: 'abilitiesFireBolt',
+		name: 'Fire Bolt',
+		description: 'Burns an enemy for {damage}',
+		hotkey: 'Q',
+		target: 'unit',
+		targets: { enemies: true },
+		range: 8,
+		manaCost: 40,
+		cooldown: 1,
+		effects: [{ type: 'damage', amount: 140, damageType: 'magic' }]
+	},
+	{
+		// a radius makes it an area: every enemy within 2.5 cells of the spot
+		id: 'abilitiesShockBlast',
+		name: 'Shock Blast',
+		description: 'Blasts the ground: {damage} to every enemy within {radius}',
+		hotkey: 'W',
+		target: 'point',
+		range: 9,
+		manaCost: 60,
+		cooldown: 1.5,
+		effects: [{ type: 'damage', amount: 90, radius: 2.5 }]
+	},
+	{
+		// an `if` asks about the target: below half its health it takes true damage that ignores armor, more the more it lacks
+		id: 'abilitiesExecute',
+		name: 'Execute',
+		description: 'Below half health, a blow of true damage that grows with the health it lacks; above, a plain cut',
+		hotkey: 'E',
+		target: 'unit',
+		targets: { enemies: true },
+		range: 8,
+		manaCost: 50,
+		cooldown: 1,
+		effects: [
+			{
+				type: 'if',
+				target: { healthBelow: 0.5 },
+				effects: [{ type: 'damage', amount: 150, byMissingHealth: 0.5, damageType: 'true' }],
+				otherwise: [{ type: 'damage', amount: 60, damageType: 'physical' }]
+			}
+		]
+	},
+	{
+		// heal reaches allies: the wounded footman beside the mage
+		id: 'abilitiesHolyLight',
+		name: 'Holy Light',
+		description: 'Heals an ally for {heal}',
+		hotkey: 'R',
+		target: 'unit',
+		targets: { allies: true, self: true },
+		range: 8,
+		manaCost: 50,
+		cooldown: 1,
+		effects: [{ type: 'heal', amount: 200 }]
+	},
+	{
+		// hurt one, heal the caster: two effects, one with `on: 'caster'`
+		id: 'abilitiesDrain',
+		name: 'Drain',
+		description: 'Takes {damage} from an enemy and heals the caster as much',
+		hotkey: 'T',
+		target: 'unit',
+		targets: { enemies: true },
+		range: 8,
+		manaCost: 40,
+		cooldown: 1,
+		effects: [
+			{ type: 'damage', amount: 80 },
+			{ type: 'heal', amount: 80, on: 'caster' }
+		]
+	},
+	{
+		// the three most hurt allies around the caster, picked by a condition, sorted and limited
+		id: 'abilitiesMend',
+		name: 'Mend',
+		description: 'Heals the three most hurt allies near for {heal}, and gives them back mana',
+		hotkey: 'D',
+		target: 'none',
+		manaCost: 60,
+		cooldown: 2,
+		effects: [
+			{ type: 'heal', amount: 120, radius: 8, affects: 'allies', sort: 'lowestHealthShare', limit: 3 },
+			{ type: 'mana', amount: 50, radius: 8 }
+		]
+	},
+	{
+		// a zone hurts those inside four times a second: a share of their most health, so it bites big and small alike
+		id: 'abilitiesDecay',
+		name: 'Decay',
+		description: 'Rots the ground for 4 seconds: each second, 4% of the most health of every enemy on it',
+		hotkey: 'F',
+		target: 'point',
+		range: 9,
+		manaCost: 70,
+		cooldown: 3,
+		effects: [{ type: 'zone', radius: 2.5, duration: 4, effects: [{ type: 'damage', amount: 0, byMaxHealth: 0.01, damageType: 'true' }] }]
+	},
+	{
+		// a chance on any effect: here a third of the time it strikes twice
+		id: 'abilitiesLuckyStrike',
+		name: 'Lucky Strike',
+		description: 'Strikes for 70, and a third of the time for 140 more',
+		hotkey: 'G',
+		target: 'unit',
+		targets: { enemies: true },
+		range: 8,
+		cooldown: 0.5,
+		effects: [
+			{ type: 'damage', amount: 70, damageType: 'physical' },
+			{ type: 'damage', amount: 140, damageType: 'physical', chance: 0.33 }
+		]
+	}
+]
+
+export const damage: Family = {
+	abilities,
+	units: [
+		caster(
+			'abilitiesHealer',
+			'Battle mage',
+			abilities.map((each) => each.id)
+		),
+		sparring('abilitiesTarget', 'Sparring footman'),
+		// an ally to heal: it comes in wounded, and does not heal by itself
+		sparring('abilitiesWounded', 'Wounded footman', { stats: { health: 900, moveSpeed: 3.2, armor: 5 } })
+	],
+	example: {
+		id: 'abilities-damage',
+		category: 'abilities',
+		title: 'Damage and heal',
+		summary:
+			'Damage, heal and mana: plain amounts, areas, a blow that grows with the health the target lacks, a condition, a chance. Press a button to cast it; the wounded footman on the left is the one healed.',
+		tags: ['damage', 'heal', 'mana', 'execute', 'if', 'chance', 'zone', 'true damage'],
+		source: ['examples/abilities/damage.ts', 'examples/abilities/kit.ts'],
+		map: () => exampleField({ name: 'Damage and heal', players: 2 }),
+		start: (world) => {
+			lineUp(world, 'abilitiesHealer', 'abilitiesTarget', 3, 'abilitiesWounded')
+			const wounded = world.named('ally')
+			if (wounded) wounded.health = wounded.maxHealth * 0.3
+		}
+	}
+}

package/starters/examples/src/examples/abilities/damageLooks.ts

@@ -0,0 +1,37 @@
+/** How the damage and heal example looks, and its card: a button for each ability (`./damage.ts`) */
+import { readout } from '../../shell/look'
+import { sharedLooks } from '../common/looks'
+import { damage } from './damage'
+import type { FamilyLooks } from './looks'
+import { castButton, look, readyOn, resetButton } from './lookKit'
+
+export const damageLooks: FamilyLooks = {
+	units: {
+		abilitiesHealer: sharedLooks.mage,
+		abilitiesTarget: sharedLooks.footman,
+		abilitiesWounded: sharedLooks.footman
+	},
+	abilities: {
+		abilitiesFireBolt: look([1, 0.45, 0.1], 'burst'),
+		abilitiesShockBlast: look([0.55, 0.75, 1], 'smash'),
+		abilitiesExecute: look([0.85, 0.1, 0.1], 'burst'),
+		abilitiesHolyLight: look([1, 0.9, 0.45], 'burst'),
+		abilitiesDrain: look([0.6, 0.1, 0.5], 'tether'),
+		abilitiesMend: look([0.45, 1, 0.55], 'sonar'),
+		abilitiesDecay: look([0.4, 0.75, 0.2], 'mark'),
+		abilitiesLuckyStrike: look([1, 0.8, 0.2], 'burst')
+	},
+	examples: {
+		'abilities-damage': {
+			ready: (client) => readyOn(client, 'abilitiesHealer'),
+			controls: [
+				...damage.abilities.map((ability) => castButton(ability)),
+				resetButton('abilities-damage'),
+				readout('Wounded ally', (client) => {
+					const ally = client.session.snapshot().entities.find((each) => each.type === 'abilitiesWounded')
+					return ally ? `${Math.round(ally.health)} health` : '—'
+				})
+			]
+		}
+	}
+}

package/starters/examples/src/examples/abilities/family.ts

@@ -0,0 +1,29 @@
+/**
+ * A family of abilities, as an example shows it: the abilities, the buffs and units they use, and the example that
+ * casts them. Each family's file gives one; `./index.ts` registers them all
+ */
+import type { AbilityDef, BuffDef, CommandDef, Game, UnitTypeDef } from '@v12-engine/engine'
+import type { ExampleDef } from '../define'
+import { starts } from './kit'
+
+export interface Family {
+	/** The example that shows them */
+	example: ExampleDef
+	/** The abilities, in the order the card's buttons cast them */
+	abilities: AbilityDef[]
+	/** Abilities used but not cast from a button: what a trap or a barrel sets off, a passive of another's */
+	more?: AbilityDef[]
+	buffs?: BuffDef[]
+	units: UnitTypeDef[]
+	/** Commands of its own its card sends */
+	commands?: CommandDef<any>[]
+}
+
+/** Registers a family's definitions on the game, and its start for the reset command */
+export function registerFamily(game: Game<any>, family: Family): void {
+	for (const unit of family.units) game.unit(unit)
+	for (const ability of [...family.abilities, ...(family.more ?? [])]) game.ability(ability)
+	for (const buff of family.buffs ?? []) game.buff(buff)
+	for (const command of family.commands ?? []) game.command(command)
+	if (family.example.start) starts[family.example.id] = family.example.start as (world: Parameters<(typeof starts)[string]>[0]) => void
+}

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

@@ -0,0 +1,32 @@
+/**
+ * The abilities examples on the rules' side: a family of the engine's abilities each (`./family.ts`), every one cast
+ * from a button of the card by the command of `./kit.ts`. Their packs, abilities, buffs and units are registered here
+ */
+import type { Game } from '@v12-engine/engine'
+import type { ExampleCategory } from '../define'
+import { areas } from './areas'
+import { buffsFamily } from './buffs'
+import { changing } from './changing'
+import { control } from './control'
+import { damage } from './damage'
+import { type Family, registerFamily } from './family'
+import { abilityPacks, kitRules } from './kit'
+import { missiles } from './missiles'
+import { moves } from './moves'
+import { recasts } from './recasts'
+import { resources } from './resources'
+import { summons } from './summons'
+import { triggers } from './triggers'
+import { vision } from './vision'
+
+/** The families, in the list's order */
+export const families: Family[] = [damage, missiles, areas, control, buffsFamily, moves, summons, triggers, recasts, resources, vision, changing]
+
+export const category: ExampleCategory = {
+	rules: (game: Game<any>) => {
+		abilityPacks(game)
+		kitRules(game)
+		for (const family of families) registerFamily(game, family)
+	},
+	examples: families.map((family) => family.example)
+}

package/starters/examples/src/examples/abilities/kit.ts

@@ -0,0 +1,179 @@
+/**
+ * What the abilities examples share on the rules' side (the MOBA ones too): the packs their abilities need, a caster
+ * made of a list of abilities, sparring partners to cast on, and the command a card button sends to cast one. The
+ * engine alone
+ */
+import {
+	abilityChangesPack,
+	type AbilityDef,
+	aimKind,
+	defineCommand,
+	type Entity,
+	type Game,
+	type GamePack,
+	groundObjectsPack,
+	holdsPack,
+	manaBurnPack,
+	movesPack,
+	optional,
+	point,
+	releaseHold,
+	resourcesPack,
+	string,
+	type UnitTypeDef,
+	type Vec2,
+	visionPack,
+	type World,
+	exactMath
+} from '@v12-engine/engine'
+import { ENEMY, PLAYER } from '../common/units'
+
+/**
+ * Adds a pack to the game unless it has one of that id already: the game is one for every example, and two of a pack
+ * would run its rules twice
+ */
+export function packOnce(game: Game<any>, pack: GamePack): void {
+	if ((game.toRules().packs ?? []).some((each) => each.id === pack.id)) return
+	game.pack(pack)
+}
+
+/**
+ * The packs the engine's abilities need beyond its core: moves (dash to a unit, swap, attach), ground objects (traps,
+ * walls, barrels), holds (hold to charge, aimed channels), pools (energy, fury, heat, ammo), vision (marks, camouflage,
+ * true sight), changing abilities (grant, swap, steal) and mana burn. Each does nothing to a unit that uses none of it
+ */
+export function abilityPacks(game: Game<any>): void {
+	for (const pack of [movesPack(), groundObjectsPack(), holdsPack(), resourcesPack(), visionPack(), abilityChangesPack(), manaBurnPack()])
+		packOnce(game, pack)
+}
+
+/**
+ * A caster for an example: a mage of plenty of mana, quick to get it back, who knows `abilities` (each at level 1). It
+ * strikes nothing of its own (no reach to find a fight), so what it does is what it is told
+ */
+export const caster = (id: string, name: string, abilities: readonly string[], own: Partial<UnitTypeDef> = {}): UnitTypeDef => ({
+	id,
+	name,
+	kind: 'unit',
+	radius: 0.45,
+	stats: { health: 1200, healthRegen: 4, mana: 1000, manaRegen: 60, attackDamage: 30, attackSpeed: 1, attackRange: 6, moveSpeed: 4.2 },
+	sight: 12,
+	attacks: [{ damagePoint: 0.5, acquisitionRange: 0, projectileSpeed: 20 }],
+	abilities: [...abilities],
+	...own
+})
+
+/**
+ * Something to cast on: a footman of a side who never strikes back (no attack), holds its ground until moved, and heals
+ * fast, so a cast can be tried again and again
+ */
+export const sparring = (id: string, name: string, own: Partial<UnitTypeDef> = {}): UnitTypeDef => ({
+	id,
+	name,
+	kind: 'unit',
+	radius: 0.45,
+	stats: { health: 900, healthRegen: 30, mana: 300, manaRegen: 5, moveSpeed: 3.2, armor: 5 },
+	sight: 8,
+	...own
+})
+
+/** The point `distance` from `from` toward `to` */
+export function toward(from: Vec2, to: Vec2, distance: number): Vec2 {
+	const dx = to.x - from.x
+	const dz = to.z - from.z
+	const length = exactMath.hypot(dx, dz) || 1
+	return { x: from.x + (dx / length) * distance, z: from.z + (dz / length) * distance }
+}
+
+/** The living enemy of `of` nearest to it, of the other side */
+export function nearestEnemy(world: World, of: Entity): Entity | undefined {
+	let best: Entity | undefined
+	let far = Infinity
+	for (const unit of world.units.values()) {
+		if (!unit.alive || unit.hidden || !world.areEnemies(of.owner, unit.owner)) continue
+		const d = exactMath.hypot(unit.pos.x - of.pos.x, unit.pos.z - of.pos.z)
+		if (d < far) {
+			far = d
+			best = unit
+		}
+	}
+	return best
+}
+
+/**
+ * Casts an ability as a player would, aimed for them: the unit named `by` (`caster` when not said) casts `ability` on
+ * the unit named `at`, or at `point`. With neither, it aims as the ability asks: an enemy's ability at the nearest
+ * enemy, an ally's at the unit named `ally` (itself where there is none), a point or a direction at the nearest enemy,
+ * nothing at nothing. Cast again while its window is open, it is the recast
+ */
+export function castFor(world: World, player: number, ability: string, options: { by?: string; at?: string; point?: Vec2 } = {}): void {
+	const unit = world.named(options.by ?? 'caster')
+	if (!unit || unit.owner !== player || !world.registry.abilities.has(ability)) return
+	const def: AbilityDef = world.registry.ability(ability)
+	const kind = aimKind(world.registry, def)
+	const named = options.at ? world.named(options.at) : undefined
+	const friendly = def.targets && !def.targets.enemies && (def.targets.allies || def.targets.self)
+	const target = named ?? (friendly ? (world.named('ally') ?? unit) : nearestEnemy(world, unit))
+	const at = options.point ?? target?.pos
+	switch (kind) {
+		case 'none':
+			return unit.order('cast', { ability })
+		case 'unit':
+			return target ? unit.order('cast', { ability, target: target.id }) : undefined
+		case 'point':
+		case 'direction':
+			return at ? unit.order('cast', { ability, point: { x: at.x, z: at.z } }) : undefined
+		case 'vector': {
+			// from beside the target, across it
+			if (!at) return
+			const side = { x: at.x - (at.z - unit.pos.z) * 0.6, z: at.z + (at.x - unit.pos.x) * 0.6 }
+			return unit.order('cast', { ability, point: side, to: { x: at.x, z: at.z } })
+		}
+	}
+}
+
+/** The command a card button sends: casts an ability for its player (`castFor`) */
+export const cast = defineCommand(
+	'abilities.cast',
+	{ ability: string, by: optional(string), at: optional(string), point: optional(point) },
+	(world, player, { ability, by, at, point }) => castFor(world, player, ability, { by, at, point })
+)
+
+/** Lets go of a held ability (hold to charge, release to fire) of the unit named `by`, toward the nearest enemy */
+export const release = defineCommand('abilities.release', { by: optional(string) }, (world, player, { by }) => {
+	const unit = world.named(by ?? 'caster')
+	if (!unit || unit.owner !== player) return
+	const enemy = nearestEnemy(world, unit)
+	releaseHold(world, unit, enemy ? { x: enemy.pos.x, z: enemy.pos.z } : undefined)
+})
+
+/** Each example's start by its id, for the reset command to lay one out again */
+export const starts: Record<string, (world: World) => void> = {}
+
+/** Takes every unit away and lays the example out again as it started (`starts`) */
+export const reset = defineCommand('abilities.reset', { example: string }, (world, _player, { example }) => {
+	const start = starts[example]
+	if (!start) return
+	for (const unit of [...world.units.values()]) if (unit.alive) world.kill(unit, undefined, false, 'removed')
+	start(world)
+})
+
+/** Puts a unit down for a side, named when it is to be found again, facing `facing` (radians; toward +z is 0) */
+export function put(world: World, type: string, owner: number, at: Vec2, name?: string, facing = 0): Entity {
+	return world.spawn(type, { at, owner, facing, ...(name && { name }) })
+}
+
+/** The usual lay-out of a family: the caster at the south, an ally by it, enemies in a row to the north */
+export function lineUp(world: World, casterType: string, enemyType: string, count = 3, ally?: string): void {
+	put(world, casterType, PLAYER, { x: 24, z: 18 }, 'caster')
+	if (ally) put(world, ally, PLAYER, { x: 21.5, z: 17 }, 'ally')
+	for (let i = 0; i < count; i++)
+		put(world, enemyType, ENEMY, { x: 24 + (i - (count - 1) / 2) * 2.5, z: 26 + (i % 2) * 1.2 }, `enemy${i + 1}`, Math.PI)
+}
+
+/** Registers the shared commands once on the game */
+export function kitRules(game: Game<any>): void {
+	game.command(cast)
+	game.command(release)
+	game.command(reset)
+}