@v12-engine/create 0.1.1 → 0.4.0

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

@@ -0,0 +1,296 @@
+/**
+ * Summons and ground objects: units an ability brings into the world. Summons that fight beside the caster, a ward,
+ * the dead raised and brought back, illusions; and with the ground objects pack (`groundObjectsPack`), a trap, walls,
+ * a wall that eats missiles, a lantern an ally uses, kegs that set each other off, and a shadow and a ball the caster
+ * casts from
+ */
+import { type AbilityDef, defineCommand, type UnitTypeDef } from '@v12-engine/engine'
+import { exampleField } from '../define'
+import { ENEMY, PLAYER } from '../common/units'
+import type { Family } from './family'
+import { caster, put, sparring } from './kit'
+
+/** Something put on the ground: small, one hit, out of the way */
+const placed = (id: string, name: string, own: Partial<UnitTypeDef>): UnitTypeDef => ({
+	id,
+	name,
+	kind: 'unit',
+	radius: 0.3,
+	stats: { health: 1 },
+	sight: 2,
+	...own
+})
+
+const units: UnitTypeDef[] = [
+	sparring('abilitiesElemental', 'Water Elemental', {
+		radius: 0.5,
+		stats: { health: 500, attackDamage: 20, attackSpeed: 1, attackRange: 4, moveSpeed: 3.5 },
+		attacks: [{ damagePoint: 0.3, acquisitionRange: 7, projectileSpeed: 12 }]
+	}),
+	sparring('abilitiesVoidling', 'Voidling', {
+		radius: 0.3,
+		stats: { health: 60, attackDamage: 9, attackSpeed: 1.4, attackRange: 0.5, moveSpeed: 5 },
+		attacks: [{ damagePoint: 0.25, acquisitionRange: 7 }]
+	}),
+	sparring('abilitiesSkeleton', 'Skeleton', {
+		stats: { health: 200, attackDamage: 12, attackSpeed: 1, attackRange: 0.5, moveSpeed: 3.6 },
+		attacks: [{ damagePoint: 0.4, acquisitionRange: 7 }]
+	}),
+	// sees round it, unseen by enemies after a second, gone after two hits whatever they deal
+	placed('abilitiesWard', 'Sentry Ward', { sight: 10, lifetime: 60, invisible: { after: 1 }, uses: 2 }),
+	// goes off as an enemy comes within 0.9, armed a second after it is put down
+	placed('abilitiesShroom', 'Noxious Trap', { invisible: { after: 1 }, trigger: { ability: 'abilitiesShroomBurst', radius: 0.9, arm: 1 } }),
+	placed('abilitiesIceWall', 'Ice Wall', { radius: 0.55, invulnerable: true, stats: { health: 100 } }),
+	// eats every missile that meets it, the caster's own too
+	placed('abilitiesWindWall', 'Wind Wall', { radius: 0.6, invulnerable: true, lifetime: 6, blocksMissiles: 'all' }),
+	// allies use it: walk up and right-click
+	placed('abilitiesLantern', 'Lantern', { lifetime: 20, use: { ability: 'abilitiesLanternLight', range: 1.5, times: 1 } }),
+	// where one dies its ability goes off, and those of its kind within 4 die too
+	placed('abilitiesKeg', 'Powder Keg', { radius: 0.4, stats: { health: 50 }, burst: { ability: 'abilitiesKegBlast', chain: 4 } }),
+	placed('abilitiesShadow', 'Living Shadow', { radius: 0.4, invulnerable: true }),
+	placed('abilitiesBall', 'The Ball', { radius: 0.3, invulnerable: true, sight: 4 })
+]
+
+const abilities: AbilityDef[] = [
+	{
+		// at a spot near the caster (summoned where the caster stands, it would stand inside it); follows its master,
+		// fights who fights it, dies with it
+		id: 'abilitiesSummonElemental',
+		name: 'Water Elemental',
+		description: 'An elemental beside the caster for 30 seconds',
+		hotkey: 'Q',
+		target: 'point',
+		range: 4,
+		cooldown: 1,
+		effects: [{ type: 'summon', unit: 'abilitiesElemental', lifetime: 30 }]
+	},
+	{
+		// four that go for the nearest enemy at once
+		id: 'abilitiesVoidSwarm',
+		name: 'Void Swarm',
+		description: 'Four voidlings for 8 seconds, going for the nearest enemy',
+		hotkey: 'W',
+		target: 'none',
+		cooldown: 1,
+		effects: [{ type: 'summon', unit: 'abilitiesVoidling', count: 4, lifetime: 8, spread: 1.5, aggro: 'nearest' }]
+	},
+	{
+		id: 'abilitiesPlaceWard',
+		name: 'Sentry Ward',
+		description: 'A ward at the spot: it sees, and is unseen after a second',
+		hotkey: 'E',
+		target: 'point',
+		range: 10,
+		cooldown: 1,
+		effects: [{ type: 'spawn', unit: 'abilitiesWard' }]
+	},
+	{
+		// corpses round the spot stand up again, the caster's for 30 seconds
+		id: 'abilitiesRaiseDead',
+		name: 'Raise Dead',
+		description: 'The fallen enemies on the left rise as skeletons of yours',
+		hotkey: 'R',
+		target: 'point',
+		range: 12,
+		cooldown: 1,
+		effects: [{ type: 'raiseDead', unit: 'abilitiesSkeleton', count: 3, duration: 30, radius: 4 }]
+	},
+	{
+		// the side's own dead back as they were, for good
+		id: 'abilitiesResurrection',
+		name: 'Resurrection',
+		description: 'Your fallen footmen on the right come back as they were',
+		hotkey: 'T',
+		target: 'none',
+		cooldown: 1,
+		effects: [{ type: 'revive', count: 6, radius: 12 }]
+	},
+	{
+		// copies of the caster that deal a third and take double
+		id: 'abilitiesMirrorImage',
+		name: 'Mirror Image',
+		description: 'Two copies of the caster for 15 seconds, weaker than it',
+		hotkey: 'D',
+		target: 'none',
+		cooldown: 1,
+		effects: [{ type: 'illusion', count: 2, duration: 15, dealt: 0.33, taken: 2, on: 'caster' }]
+	},
+	{
+		id: 'abilitiesNoxiousTrap',
+		name: 'Noxious Trap',
+		description: 'A hidden mushroom under the nearest enemy: it goes off a second later',
+		hotkey: 'F',
+		target: 'point',
+		range: 12,
+		cooldown: 1,
+		effects: [{ type: 'spawn', unit: 'abilitiesShroom' }]
+	},
+	{
+		// several along a line laid across the aim: a wall in front
+		id: 'abilitiesCrystallize',
+		name: 'Crystallize',
+		description: 'A wall of ice across the way for 5 seconds',
+		hotkey: 'G',
+		target: 'point',
+		range: 10,
+		cooldown: 1,
+		effects: [{ type: 'spawn', unit: 'abilitiesIceWall', duration: 5, line: { count: 5, length: 4, across: true } }]
+	},
+	{
+		id: 'abilitiesCastWindWall',
+		name: 'Wind Wall',
+		description: 'A wall of wind in front that eats missiles: fire a bolt through it',
+		hotkey: 'Z',
+		target: 'point',
+		range: 3,
+		cooldown: 1,
+		effects: [{ type: 'spawn', unit: 'abilitiesWindWall', line: { count: 4, length: 3, across: true } }]
+	},
+	{
+		id: 'abilitiesProbe',
+		name: 'Bolt',
+		description: 'A bolt at the nearest enemy, to see a wind wall eat it',
+		hotkey: 'X',
+		target: 'direction',
+		range: 12,
+		cooldown: 0.3,
+		effects: [{ type: 'missile', speed: 14, distance: 12, radius: 0.5, pierce: false, effects: [{ type: 'damage', amount: 60 }] }]
+	},
+	{
+		id: 'abilitiesPlaceLantern',
+		name: 'Lantern',
+		description: 'A lantern by your wounded footman: it walks up and uses it',
+		hotkey: 'C',
+		target: 'point',
+		range: 12,
+		cooldown: 1,
+		effects: [{ type: 'spawn', unit: 'abilitiesLantern' }]
+	},
+	{
+		id: 'abilitiesPlaceKegs',
+		name: 'Powder Kegs',
+		description: 'Three kegs by the enemies: a fuse sets one off, and it sets off the rest',
+		hotkey: 'V',
+		target: 'point',
+		range: 12,
+		cooldown: 1,
+		effects: [{ type: 'spawn', unit: 'abilitiesKeg', line: { count: 3, length: 6, across: true } }]
+	},
+	{
+		// a keg with a short life: dying, it bursts, and the others within 4 burst after it
+		id: 'abilitiesFuse',
+		name: 'Light a fuse',
+		description: 'A keg that bursts in a second, setting off every keg within 4',
+		hotkey: 'B',
+		target: 'point',
+		range: 12,
+		cooldown: 1,
+		effects: [{ type: 'spawn', unit: 'abilitiesKeg', duration: 1 }]
+	},
+	{
+		id: 'abilitiesPlaceShadow',
+		name: 'Living Shadow',
+		description: 'A shadow to the side for 8 seconds: the shuriken flies from it too',
+		hotkey: 'N',
+		target: 'point',
+		range: 10,
+		cooldown: 1,
+		effects: [{ type: 'spawn', unit: 'abilitiesShadow', duration: 8 }]
+	},
+	{
+		// goes off from the caster and from every shadow of its own (`origin`); the caster's damage still
+		id: 'abilitiesShuriken',
+		name: 'Razor Shuriken',
+		description: 'A shuriken from the caster and from each shadow, at the enemies',
+		hotkey: 'Y',
+		target: 'point',
+		range: 10,
+		cooldown: 0.5,
+		effects: [
+			{
+				type: 'missile',
+				speed: 17,
+				distance: 10,
+				radius: 0.6,
+				origin: { proxy: 'abilitiesShadow', pick: 'all', caster: true },
+				effects: [{ type: 'damage', amount: 70 }]
+			}
+		]
+	},
+	{
+		// thrown from wherever the ball is, then the ball sent there
+		id: 'abilitiesCommandAttack',
+		name: 'Command: Attack',
+		description: 'A shot from the ball to the spot, and the ball goes there',
+		hotkey: 'U',
+		target: 'point',
+		range: 12,
+		cooldown: 0.5,
+		effects: [
+			{
+				type: 'missile',
+				speed: 12,
+				toPoint: true,
+				distance: 12,
+				radius: 0.8,
+				origin: { proxy: 'abilitiesBall', caster: 'otherwise' },
+				effects: [{ type: 'damage', amount: 60 }]
+			},
+			{ type: 'sendProxy', speed: 12, origin: { proxy: 'abilitiesBall' } }
+		]
+	}
+]
+
+/** What the placed things set off: not on the card */
+const more: AbilityDef[] = [
+	{ id: 'abilitiesShroomBurst', name: 'Noxious Burst', target: 'none', effects: [{ type: 'damage', amount: 120, radius: 2 }] },
+	{ id: 'abilitiesLanternLight', name: 'Lantern Light', target: 'none', effects: [{ type: 'heal', amount: 400, radius: 2.5 }] },
+	{ id: 'abilitiesKegBlast', name: 'Keg Blast', target: 'none', effects: [{ type: 'damage', amount: 90, radius: 2.5 }] }
+]
+
+/**
+ * The fallen, laid once the game runs (the card sends it as it opens): enemies on the left to raise, footmen of yours
+ * on the right to bring back
+ */
+export const layFallen = defineCommand('abilities.fallen', {}, (world) => {
+	for (const z of [21, 22.5, 24]) world.kill(put(world, 'abilitiesTarget', ENEMY, { x: 16, z }), undefined)
+	for (const z of [20, 21.5]) world.kill(put(world, 'abilitiesSoldier', PLAYER, { x: 31, z }), undefined)
+})
+
+/** Your wounded footman walks to the nearest lantern and uses it */
+export const useLantern = defineCommand('abilities.useLantern', {}, (world, player) => {
+	const ally = world.named('ally')
+	if (!ally || ally.owner !== player) return
+	const lantern = [...world.units.values()].find((each) => each.alive && each.def.id === 'abilitiesLantern')
+	if (lantern) ally.order('useObject', lantern)
+})
+
+export const summons: Family = {
+	abilities,
+	more,
+	units: [
+		caster(
+			'abilitiesSummoner',
+			'Summoner',
+			abilities.map((each) => each.id)
+		),
+		...units
+	],
+	commands: [useLantern, layFallen],
+	example: {
+		id: 'abilities-summons',
+		category: 'abilities',
+		title: 'Summons and ground objects',
+		summary:
+			'Summons, a ward, the dead raised and brought back, illusions; a trap, an ice wall, a wall that eats missiles, a lantern, kegs that chain, and a shadow and a ball the caster casts from. Press a button to see each.',
+		tags: ['summon', 'spawn', 'ward', 'raise dead', 'revive', 'illusion', 'trap', 'wall', 'wind wall', 'lantern', 'barrel', 'keg', 'proxy', 'shadow'],
+		source: ['examples/abilities/summons.ts', 'examples/abilities/kit.ts'],
+		map: () => exampleField({ name: 'Summons', players: 2 }),
+		start: (world) => {
+			put(world, 'abilitiesSummoner', PLAYER, { x: 24, z: 17 }, 'caster')
+			put(world, 'abilitiesWounded', PLAYER, { x: 21, z: 17 }, 'ally').health = 300
+			put(world, 'abilitiesBall', PLAYER, { x: 26, z: 18 })
+			for (const [i, x] of [21, 24, 27].entries()) put(world, 'abilitiesTarget', ENEMY, { x, z: 25 }, `enemy${i + 1}`, Math.PI)
+		}
+	}
+}

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

@@ -0,0 +1,115 @@
+/** How the summons example looks, and its card: a button for each summon and thing put down (`./summons.ts`) */
+import { button } from '../../shell/look'
+import { character, hold, ONE_HANDED, person, sharedLooks } from '../common/looks'
+import type { FamilyLooks } from './looks'
+import { castButton, look, readyOn } from './lookKit'
+import { reset } from './kit'
+import { layFallen, summons, useLantern } from './summons'
+
+type Color = [number, number, number]
+
+/** Where each is aimed, where the nearest enemy is not it */
+const aims: Record<string, { point?: { x: number; z: number } }> = {
+	abilitiesSummonElemental: { point: { x: 26, z: 18.5 } },
+	abilitiesPlaceWard: { point: { x: 27.5, z: 21.5 } },
+	abilitiesRaiseDead: { point: { x: 16, z: 22.5 } },
+	abilitiesCrystallize: { point: { x: 24, z: 22 } },
+	abilitiesCastWindWall: { point: { x: 24, z: 20 } },
+	abilitiesPlaceLantern: { point: { x: 22.5, z: 19.5 } },
+	abilitiesPlaceKegs: { point: { x: 24, z: 23 } },
+	abilitiesFuse: { point: { x: 22.5, z: 22 } },
+	abilitiesPlaceShadow: { point: { x: 29, z: 19 } }
+}
+
+/** A thing on the ground, as parts: a post with something on it. What shows while its model loads */
+const thing = (color: Color, height: number, top: 'sphere' | 'box' = 'sphere') => ({
+	height,
+	shapes: [
+		{
+			shape: 'cylinder' as const,
+			size: [0.12, height, 0.12] as [number, number, number],
+			offset: [0, height / 2, 0] as [number, number, number],
+			color: [0.35, 0.25, 0.15] as Color
+		},
+		{ shape: top, size: [0.35, 0.35, 0.35] as [number, number, number], offset: [0, height, 0] as [number, number, number], color }
+	]
+})
+
+export const summonsLooks: FamilyLooks = {
+	units: {
+		abilitiesSummoner: sharedLooks.mage,
+		// the shared art's mannequin in the water's blue, a skeleton minion small and in the void's violet: both with the clips
+		abilitiesElemental: {
+			height: 1.7,
+			model: character('mannequin_medium', 0.8, { tint: [0.35, 0.65, 1] }),
+			shapes: [{ shape: 'sphere', size: [1, 1.6, 1], offset: [0, 0.8, 0], color: [0.3, 0.6, 1] }]
+		},
+		abilitiesVoidling: {
+			height: 0.8,
+			model: character('skeleton_minion', 0.38, { tint: [0.6, 0.3, 0.85] }),
+			shapes: [{ shape: 'sphere', size: [0.6, 0.6, 0.6], offset: [0, 0.35, 0], color: [0.5, 0.15, 0.7] }]
+		},
+		abilitiesSkeleton: {
+			height: 1.7,
+			model: character('skeleton_minion', 0.7, { hold: [hold('sword_1handed')] }),
+			attacks: [ONE_HANDED],
+			shapes: person(1.7)
+		},
+		// a standing torch: what sees round it
+		abilitiesWard: { ...thing([1, 0.85, 0.3], 1), model: { src: 'dungeon-kit/torch.glb', scale: 0.8, raise: 0.55 } },
+		abilitiesShroom: {
+			height: 0.5,
+			model: { src: 'forest/mushroom_common.glb', scale: 2 },
+			shapes: [{ shape: 'sphere', size: [0.5, 0.3, 0.5], offset: [0, 0.25, 0], color: [0.7, 0.2, 0.6] }]
+		},
+		// ice and wind have no model in the shared art: a block of ice and a pale sheet, as parts
+		abilitiesIceWall: { height: 1.8, shapes: [{ shape: 'box', size: [1, 1.8, 0.6], offset: [0, 0.9, 0], color: [0.7, 0.9, 1] }] },
+		abilitiesWindWall: { height: 2.2, shapes: [{ shape: 'box', size: [1.1, 2.2, 0.2], offset: [0, 1.1, 0], color: [0.85, 0.95, 1] }] },
+		abilitiesLantern: { ...thing([0.4, 1, 0.6], 1.2, 'box'), model: { src: 'props/candle_stick_stand.glb', scale: 1 } },
+		abilitiesKeg: {
+			height: 0.8,
+			model: { src: 'props/barrel.glb', scale: 0.9 },
+			shapes: [{ shape: 'cylinder', size: [0.7, 0.8, 0.7], offset: [0, 0.4, 0], color: [0.5, 0.3, 0.15] }]
+		},
+		abilitiesShadow: {
+			height: 1.8,
+			model: character('rogue_hooded', 0.72, { hold: [hold('dagger'), hold('dagger', 'l')] }),
+			shapes: person(1.8, [0.1, 0.05, 0.15])
+		},
+		// a ball that floats and is sent about: the shared art has no orb to fit, so it is a sphere
+		abilitiesBall: { height: 0.8, shapes: [{ shape: 'sphere', size: [0.5, 0.5, 0.5], offset: [0, 0.8, 0], color: [0.75, 0.7, 0.5] }] }
+	},
+	abilities: {
+		abilitiesSummonElemental: look([0.3, 0.6, 1], 'burst'),
+		abilitiesVoidSwarm: look([0.5, 0.15, 0.7], 'burst'),
+		abilitiesRaiseDead: look([0.5, 1, 0.5], 'sonar'),
+		abilitiesResurrection: look([1, 0.95, 0.6], 'sonar'),
+		abilitiesMirrorImage: look([0.6, 0.6, 1], 'burst'),
+		abilitiesShroomBurst: look([0.7, 0.2, 0.6], 'burst'),
+		abilitiesProbe: look([1, 0.6, 0.3], 'missile', { options: { shape: 'ball' } }),
+		abilitiesLanternLight: look([0.4, 1, 0.6], 'burst'),
+		abilitiesKegBlast: look([1, 0.55, 0.15], 'smash'),
+		abilitiesShuriken: look([0.85, 0.85, 0.9], 'missile', { options: { shape: 'arrow' } }),
+		abilitiesCommandAttack: look([0.75, 0.7, 0.5], 'missile', { options: { shape: 'ball' } })
+	},
+	examples: {
+		'abilities-summons': {
+			ready: (client) => {
+				readyOn(client, 'abilitiesSummoner', { minX: 14, minZ: 14, maxX: 34, maxZ: 28 })
+				client.session.send(layFallen.make({}))
+			},
+			controls: [
+				...summons.abilities.map((ability) => castButton(ability, aims[ability.id])),
+				button('Use the lantern', (client) => client.session.send(useLantern.make({})), 'Your wounded footman walks to the lantern and uses it'),
+				button(
+					'Start again',
+					(client) => {
+						client.session.send(reset.make({ example: 'abilities-summons' }))
+						client.session.send(layFallen.make({}))
+					},
+					'Takes everything away and lays the example out again, the fallen on both sides too'
+				)
+			]
+		}
+	}
+}

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

@@ -0,0 +1,204 @@
+/**
+ * Triggers and passives: always on, each doing something when something happens. A blademaster striking a dummy has a
+ * chance to crit, hits harder every fourth blow, an orb of fire (and one of frost the fire's slot leaves out), grows
+ * faster with every spell, heals as its spells hurt and gathers souls from what it kills; its Siphoning Strike
+ * empowers the next blow and Quick Strike makes it come at once. A warden beside it hurts whoever hurts it, shields
+ * itself low, and cheats death
+ */
+import { type AbilityDef, type BuffDef, defineCommand } from '@v12-engine/engine'
+import { exampleField } from '../define'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import type { Family } from './family'
+import { caster, put, sparring } from './kit'
+
+const buffs: BuffDef[] = [
+	{ id: 'abilitiesSiphoning', name: 'Siphoning Strike', description: 'The next blow deals 120 more', duration: 8 },
+	{ id: 'abilitiesSouls', name: 'Souls', description: '+4 attack damage a soul', maxStacks: 100, perStack: true, stats: { attackDamage: 4 } },
+	{
+		id: 'abilitiesFlurry',
+		name: 'Flurry',
+		description: '+15% attack speed a stack',
+		duration: 6,
+		maxStacks: 5,
+		perStack: true,
+		percent: { attackSpeed: 0.15 }
+	},
+	{ id: 'abilitiesChilled', name: 'Chilled', harmful: true, duration: 2, percent: { moveSpeed: -0.3 } },
+	{ id: 'abilitiesWardShield', name: 'Mana Barrier', description: 'A shield as health runs low', duration: 6, shield: 400 },
+	{ id: 'abilitiesReborn', name: 'Reborn', description: 'Back from the dead, untouchable a moment', duration: 2, invulnerable: true }
+]
+
+/** The blademaster's passives: each a trigger in an ability aimed at nothing (`passive`) */
+const passives: AbilityDef[] = [
+	{
+		id: 'abilitiesCrit',
+		name: 'Critical Strike',
+		description: 'A blow that lands has a 25% chance to deal 80 more',
+		target: 'passive',
+		effects: [{ type: 'onHit', chance: 0.25, effects: [{ type: 'damage', amount: 80, damageType: 'physical' }] }]
+	},
+	{
+		id: 'abilitiesWhisper',
+		name: 'Every Fourth',
+		description: 'Every fourth blow that lands deals 150 more',
+		target: 'passive',
+		effects: [{ type: 'onHit', every: 4, effects: [{ type: 'damage', amount: 150, damageType: 'physical' }] }]
+	},
+	{
+		// two orbs in one slot: only the one of the highest priority goes off, as Warcraft III's orbs
+		id: 'abilitiesFrostOrb',
+		name: 'Orb of Frost',
+		description: 'Blows chill (but the Orb of Fire shares its slot, and wins)',
+		target: 'passive',
+		effects: [{ type: 'onHit', slot: 'orb', effects: [{ type: 'buff', buff: 'abilitiesChilled' }] }]
+	},
+	{
+		id: 'abilitiesFireOrb',
+		name: 'Orb of Fire',
+		description: 'Blows burn round the target for 25',
+		target: 'passive',
+		effects: [{ type: 'onHit', slot: 'orb', priority: 1, effects: [{ type: 'damage', amount: 25, radius: 1.5 }] }]
+	},
+	{
+		id: 'abilitiesFlurryPassive',
+		name: 'Flurry',
+		description: 'Every spell cast: a stack of 15% attack speed',
+		target: 'passive',
+		effects: [{ type: 'onCast', effects: [{ type: 'buff', buff: 'abilitiesFlurry', stack: true, on: 'caster' }] }]
+	},
+	{
+		id: 'abilitiesSpellVamp',
+		name: 'Spell Vamp',
+		description: 'Each enemy its spells hurt heals it for a third of the damage',
+		target: 'passive',
+		effects: [{ type: 'onAbilityHit', effects: [{ type: 'heal', amount: 0, byDamage: 0.33, on: 'caster' }] }]
+	},
+	{
+		id: 'abilitiesSoulHarvest',
+		name: 'Soul Harvest',
+		description: 'Each enemy it kills: a soul, 4 more attack damage for good',
+		target: 'passive',
+		effects: [{ type: 'onKill', effects: [{ type: 'buff', buff: 'abilitiesSouls', stack: true, on: 'caster' }] }]
+	}
+]
+
+const abilities: AbilityDef[] = [
+	{
+		// cast: a buff on the caster; its own passive part spends it on the next blow (`whileBuff`, `consumes`)
+		id: 'abilitiesSiphoningStrike',
+		name: 'Siphoning Strike',
+		description: 'The next blow deals 120 more, and a kill with it gives two souls',
+		hotkey: 'Q',
+		target: 'none',
+		cooldown: 1,
+		effects: [{ type: 'buff', buff: 'abilitiesSiphoning', on: 'caster' }],
+		passive: [
+			{ type: 'onHit', whileBuff: 'abilitiesSiphoning', consumes: true, effects: [{ type: 'damage', amount: 120, damageType: 'physical' }] },
+			{ type: 'onKill', whileBuff: 'abilitiesSiphoning', effects: [{ type: 'buff', buff: 'abilitiesSouls', stack: true, on: 'caster' }] }
+		]
+	},
+	{
+		// the next blow at once, not when the swing comes round
+		id: 'abilitiesQuickStrike',
+		name: 'Quick Strike',
+		description: 'The next blow comes at once',
+		hotkey: 'W',
+		target: 'none',
+		cooldown: 1,
+		effects: [{ type: 'resetAttack' }]
+	},
+	{
+		// a spell that hurts: Flurry and Spell Vamp go off with it
+		id: 'abilitiesWindSlash',
+		name: 'Wind Slash',
+		description: 'Slashes every enemy within 3 for 90',
+		hotkey: 'E',
+		target: 'none',
+		cooldown: 1,
+		effects: [{ type: 'damage', amount: 90, radius: 3 }]
+	}
+]
+
+/** The warden's passives: what happens as it is hurt */
+const wardenPassives: AbilityDef[] = [
+	{
+		// triggered damage never sets off another `onDamaged`: two thorny units don't echo forever
+		id: 'abilitiesThorns',
+		name: 'Thorns',
+		description: 'Who strikes it up close takes half the damage back',
+		target: 'passive',
+		effects: [{ type: 'onDamaged', melee: true, effects: [{ type: 'damage', amount: 0, byDamage: 0.5 }] }]
+	},
+	{
+		id: 'abilitiesManaBarrier',
+		name: 'Mana Barrier',
+		description: 'Under 40% health, a shield of 400, once every 12 seconds',
+		target: 'passive',
+		effects: [{ type: 'onLowHealth', below: 0.4, cooldown: 12, effects: [{ type: 'buff', buff: 'abilitiesWardShield', on: 'caster' }] }]
+	},
+	{
+		// a killing blow stopped: it keeps all its health, a moment untouchable
+		id: 'abilitiesReincarnation',
+		name: 'Reincarnation',
+		description: 'A killing blow leaves it whole again, once every 20 seconds',
+		target: 'passive',
+		effects: [{ type: 'onFatal', cooldown: 20, effects: [{ type: 'buff', buff: 'abilitiesReborn', on: 'caster' }] }]
+	}
+]
+
+/** Sends three weaklings at the blademaster, to kill and gather souls from */
+export const sendWeaklings = defineCommand('abilities.weaklings', {}, (world) => {
+	for (const x of [22.5, 24, 25.5]) put(world, 'abilitiesWeakling', ENEMY, { x, z: 25 }, undefined, Math.PI)
+})
+
+export const triggers: Family = {
+	abilities,
+	more: [...passives, ...wardenPassives],
+	buffs,
+	commands: [sendWeaklings],
+	units: [
+		caster('abilitiesBlademaster', 'Blademaster', [...abilities.map((each) => each.id), ...passives.map((each) => each.id)], {
+			stats: {
+				health: 1400,
+				healthRegen: 10,
+				mana: 1000,
+				manaRegen: 60,
+				attackDamage: 40,
+				attackSpeed: 1,
+				attackRange: 0.6,
+				moveSpeed: 4.2,
+				armor: 10
+			},
+			attacks: [{ damagePoint: 0.4, acquisitionRange: 8 }]
+		}),
+		caster(
+			'abilitiesWarden',
+			'Warden',
+			wardenPassives.map((each) => each.id),
+			{ stats: { health: 1000, healthRegen: 20, mana: 300, attackDamage: 10, attackSpeed: 1, attackRange: 0.6, moveSpeed: 3.5, armor: 5 } }
+		),
+		// what hurts the warden: hard blows, slow
+		sparring('abilitiesBerserker', 'Berserker', {
+			radius: 0.55,
+			stats: { health: 3000, healthRegen: 60, attackDamage: 140, attackSpeed: 0.8, attackRange: 0.6, moveSpeed: 3.5 },
+			attacks: [{ damagePoint: 0.4, acquisitionRange: 3 }]
+		}),
+		sparring('abilitiesWeakling', 'Weakling', { stats: { health: 160, moveSpeed: 3 } })
+	],
+	example: {
+		id: 'abilities-triggers',
+		category: 'abilities',
+		title: 'Triggers and passives',
+		summary:
+			'On the left a blademaster strikes a dummy: crits, every fourth blow, an orb, flurry, spell vamp and souls from kills; empower or hurry its next blow. On the right a berserker beats a warden that hurts back, shields itself low and cheats death.',
+		tags: ['passive', 'trigger', 'on hit', 'on kill', 'on cast', 'on damaged', 'thorns', 'crit', 'orb', 'cheat death', 'reincarnation', 'empower'],
+		source: ['examples/abilities/triggers.ts', 'examples/abilities/kit.ts'],
+		map: () => exampleField({ name: 'Triggers', players: 2 }),
+		start: (world) => {
+			put(world, 'abilitiesBlademaster', PLAYER, { x: 20, z: 21 }, 'caster')
+			put(world, UNIT.dummy, ENEMY, { x: 20, z: 23 }, 'dummy', Math.PI)
+			put(world, 'abilitiesWarden', PLAYER, { x: 29, z: 21 }, 'ally')
+			put(world, 'abilitiesBerserker', ENEMY, { x: 29, z: 22.6 }, 'berserker', Math.PI)
+		}
+	}
+}

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

@@ -0,0 +1,53 @@
+/** How the triggers example looks, and its card: what the blademaster casts, weaklings to kill, and readouts */
+import { button, readout } from '../../shell/look'
+import { character, hold, person, sharedLooks, TWO_HANDED } from '../common/looks'
+import type { FamilyLooks } from './looks'
+import { castButton, look, readyOn, resetButton } from './lookKit'
+import { sendWeaklings, triggers } from './triggers'
+
+/** 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 } })
+
+export const triggersLooks: FamilyLooks = {
+	units: {
+		abilitiesBlademaster: {
+			height: 1.9,
+			model: character('barbarian', 0.75, { hold: [hold('sword_2handed')] }),
+			attacks: [TWO_HANDED],
+			shapes: person(1.9)
+		},
+		abilitiesWarden: { ...sharedLooks.footman, model: character('knight', 0.75, { hold: [hold('sword_1handed'), hold('shield_spikes', 'l')] }) },
+		abilitiesBerserker: {
+			height: 2.3,
+			model: character('barbarian', 0.95, { hold: [hold('axe_2handed')] }),
+			attacks: [TWO_HANDED],
+			shapes: person(2.3)
+		},
+		abilitiesWeakling: { height: 1.5, model: character('skeleton_minion', 0.6), shapes: person(1.5) }
+	},
+	abilities: {
+		abilitiesWindSlash: look([0.75, 0.9, 1], 'slam'),
+		abilitiesQuickStrike: look([1, 0.9, 0.4], 'burst'),
+		abilitiesSiphoning: glow([0.4, 0.8, 1], 'about', { streaks: true }),
+		abilitiesSouls: look([0.5, 1, 0.8], undefined, { counter: true, aura: 'glow', options: { shape: 'rise', rate: 4 } }),
+		abilitiesFlurry: look([1, 0.85, 0.3], undefined, { counter: { max: 5 } }),
+		abilitiesChilled: glow([0.6, 0.85, 1], 'fall'),
+		abilitiesWardShield: glow([0.45, 0.6, 1], 'shell'),
+		abilitiesReborn: glow([1, 0.9, 0.5], 'column')
+	},
+	examples: {
+		'abilities-triggers': {
+			ready: (client) => readyOn(client, 'abilitiesBlademaster', { minX: 16, minZ: 16, maxX: 33, maxZ: 27 }),
+			controls: [
+				...triggers.abilities.map((ability) => castButton(ability)),
+				button('Send weaklings', (client) => client.session.send(sendWeaklings.make({})), 'Three weaklings to kill, a soul each'),
+				resetButton('abilities-triggers'),
+				readout('Souls', (client) => {
+					const blademaster = client.session.snapshot().entities.find((each) => each.type === 'abilitiesBlademaster')
+					return String(blademaster?.stacks?.abilitiesSouls ?? 0)
+				})
+			]
+		}
+	}
+}