@v12-engine/create 0.1.1 → 0.4.0

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

@@ -0,0 +1,444 @@
+/**
+ * The animation examples on the client's side: each character with its model, gear and clips (`UnitLook`), and the
+ * cards that play clips on them (`client.playClip`), change how fast, blend one into the next, and swap what they hold
+ * (`client.looks.set`). A clip is played by its name in the model's file: the shared characters' are KayKit's
+ */
+import type { GameClientApi, GameView, ModelDef, UnitLook } from '@v12-engine/client'
+import { presetFx } from '@v12-engine/client'
+import { button, type CategoryLooks, readout, select, slider, toggle } from '../../shell/look'
+import { character, hold, ONE_HANDED, person, TWO_HANDED } from '../common/looks'
+import { ANIM, type Character, CHARACTERS, characterType, raise, strike } from './index'
+
+/** The clips every character of the shared art has (KayKit's medium rig), by what they are for */
+export const CLIPS = [
+	'Idle_A',
+	'Idle_B',
+	'Walking_A',
+	'Running_A',
+	'Running_B',
+	'Jump_Full_Short',
+	'Melee_1H_Attack_Chop',
+	'Melee_1H_Attack_Slice_Diagonal',
+	'Melee_1H_Attack_Stab',
+	'Melee_2H_Attack_Chop',
+	'Melee_2H_Attack_Slice',
+	'Melee_Dualwield_Attack_Chop',
+	'Melee_Unarmed_Attack_Punch_A',
+	'Melee_Block',
+	'Melee_Blocking',
+	'Ranged_1H_Shoot',
+	'Ranged_2H_Shoot',
+	'Ranged_Bow_Release',
+	'Ranged_Magic_Shoot',
+	'Ranged_Magic_Spellcasting',
+	'Ranged_Magic_Spellcasting_Long',
+	'Throw',
+	'Use_Item',
+	'Interact',
+	'PickUp',
+	'Hit_A',
+	'Death_A',
+	'Death_B',
+	'Spawn_Ground',
+	'Chop',
+	'Chopping',
+	'Dig',
+	'Digging',
+	'Hammer',
+	'Hammering',
+	'Pickaxe',
+	'Pickaxing'
+] as const
+/** The skeletons' own, besides */
+export const SKELETON_CLIPS = [
+	'Skeletons_Awaken_Floor',
+	'Skeletons_Awaken_Standing',
+	'Skeletons_Taunt',
+	'Skeletons_Idle',
+	'Skeletons_Walking',
+	'Skeletons_Death'
+] as const
+
+/** What each character holds: its gear, from the shared art's `gear/` */
+const GEAR: Record<Character, ModelDef['hold']> = {
+	knight: [hold('sword_1handed'), hold('shield_badge_color', 'l')],
+	barbarian: [hold('axe_2handed')],
+	mage: [hold('staff')],
+	ranger: [hold('bow_with_string', 'l')],
+	rogue: [hold('dagger'), hold('dagger', 'l')],
+	rogue_hooded: [hold('crossbow_1handed')],
+	skeleton_warrior: [hold('sword_1handed'), hold('shield_round', 'l')],
+	skeleton_mage: [hold('wand')],
+	skeleton_rogue: [hold('axe_1handed')],
+	skeleton_minion: []
+}
+
+/** A character's look: its model at the size of the shared units, holding its gear */
+const characterLook = (name: Character, own: Partial<ModelDef> = {}): UnitLook => ({
+	height: 1.8,
+	model: character(name, 0.7, { hold: GEAR[name], ...own }),
+	shapes: person(1.8)
+})
+
+/** The knight of the examples here, a sword in its right hand and a shield in its left */
+const knight = (own: Partial<ModelDef> = {}, look: Partial<UnitLook> = {}): UnitLook => ({
+	height: 1.8,
+	model: character('knight', 0.7, { hold: [hold('sword_1handed'), hold('shield_round', 'l')], ...own }),
+	shapes: person(1.8),
+	...look
+})
+
+/** How far a model walks in a second with its walk clip at normal speed, at size 1 (`ModelDef.stride`): KayKit's walk and run */
+const STRIDE = { walk: 5.5, run: 10 }
+
+/** The looks of the category's units */
+const looks: Record<string, UnitLook> = {
+	...Object.fromEntries(CHARACTERS.map((name) => [characterType(name), characterLook(name)])),
+	// three swordsmen, each swinging another way (`AttackLook`): in turn, at random, two-handed
+	[ANIM.animationTurns]: knight(
+		{},
+		{ attacks: [{ clip: ['Melee_1H_Attack_Chop', 'Melee_1H_Attack_Slice_Diagonal', 'Melee_1H_Attack_Stab'], order: 'turn' }] }
+	),
+	[ANIM.animationRandom]: knight({}, { attacks: [ONE_HANDED] }),
+	[ANIM.animationTwoHanded]: { ...characterLook('barbarian', { hold: [hold('sword_2handed_color')] }), attacks: [TWO_HANDED] },
+	// the walkers: each clip's speed is matched to how fast the unit goes by its stride
+	[ANIM.animationSlow]: knight({ stride: STRIDE.walk }),
+	[ANIM.animationJog]: knight({ stride: STRIDE.walk }),
+	[ANIM.animationRun]: knight({ stride: STRIDE.run, animations: { walk: 'Running_A' } }),
+	[ANIM.animationWielder]: knight({}, { attacks: [ONE_HANDED] }),
+	// five deaths of the same skeleton, one each by where it stands in the row (`onDeath`)
+	[ANIM.animationVictim]: {
+		...characterLook('skeleton_warrior'),
+		onDeath: (entity) => DEATHS[deathOf(entity.pos.x)]
+	},
+	[ANIM.animationWaver]: { height: 1.8, model: character('mage', 0.7, { hold: [hold('staff')], stride: STRIDE.walk }), shapes: person(1.8) }
+}
+
+/** The five deaths, in the row's order from the left */
+const DEATHS: NonNullable<UnitLook['death']>[] = [
+	{ clip: 'Death_A', corpse: { lie: 4, sink: 2 } },
+	{ clip: 'Death_B', corpse: { lie: 4, fade: 1.5 } },
+	{ clip: 'Death_B', keep: true },
+	{ shatter: 14, fx: 'dust' },
+	{ clip: 'Death_A', fx: 'smoke', corpse: { lie: 0.6, sink: 1.5 } }
+]
+/** Which of the row a skeleton is, by where it stands (laid out 2.2 apart round x 24) */
+const deathOf = (x: number) => Math.max(0, Math.min(4, Math.round((x - 24) / 2.2) + 2))
+const DEATH_NAMES = ['falls, lies, sinks', 'falls, fades', 'falls, stays for good', 'shatters', 'falls in smoke, sinks']
+
+// ---- what the cards do
+
+/** The ids of the units of the given types the client knows */
+const idsOf = (client: GameClientApi, types: (type: string) => boolean): number[] =>
+	[...client.state.entities.values()].filter((each) => each.health > 0 && types(each.def.id)).map((each) => each.id)
+
+/** The ten characters of the clips example */
+const LINEUP = new Set(CHARACTERS.map(characterType))
+const lineup = (client: GameClientApi) => idsOf(client, (type) => LINEUP.has(type))
+
+/** What the clips example's card has chosen, by client */
+const chosen = new WeakMap<GameClientApi, { clip: string; loop: boolean; speed: number }>()
+const choiceOf = (client: GameClientApi) => chosen.get(client) ?? { clip: 'Idle_A', loop: true, speed: 1 }
+
+/**
+ * Plays the chosen clip on every character that has it, as fast as the slider says: its length at its own speed
+ * (`animator.seconds`) over the speed. A loop plays until another is chosen; once, it goes back to standing
+ */
+function playChosen(client: GameClientApi): void {
+	const { clip, loop, speed } = choiceOf(client)
+	for (const id of lineup(client)) {
+		const length = client.renderer.kit.model(id)?.animator?.seconds(clip)
+		if (length === undefined) {
+			// a clip this character has not got (a skeleton's, on a knight): it stands
+			client.stopClip(id)
+			continue
+		}
+		client.playClip(id, clip, { loop, seconds: length / speed })
+	}
+}
+
+/** The clip shown next to the one chosen on the clips example's card, a step along the list */
+function stepClip(client: GameClientApi, by: number): void {
+	const all = [...CLIPS, ...SKELETON_CLIPS] as string[]
+	const choice = choiceOf(client)
+	const next = all[(all.indexOf(choice.clip) + by + all.length) % all.length]!
+	chosen.set(client, { ...choice, clip: next })
+	playChosen(client)
+}
+
+/** Puts the camera before the middle of the field, `distance` back and as steep as `pitch`, a little to the south */
+function stage(client: GameClientApi, at: { x: number; z: number }, distance: number, pitch = 0.45, yaw = 0): void {
+	client.camera.setPose({ x: at.x, z: at.z, distance, yaw, pitch })
+}
+
+// ---- the blending example: two knights playing the same clips in turn, one blending and the other snapping
+
+/** The pairs of clips the blending example plays in turn */
+const PAIRS: Record<string, [string, string]> = {
+	'idle and a swing': ['Idle_A', 'Melee_2H_Attack_Chop'],
+	'walk and run': ['Walking_A', 'Running_A'],
+	'block and punch': ['Melee_Blocking', 'Melee_Unarmed_Attack_Punch_A'],
+	'cast and throw': ['Ranged_Magic_Spellcasting', 'Throw']
+}
+const blending = new WeakMap<GameClientApi, { pair: string; seconds: number; timer?: ReturnType<typeof setInterval> }>()
+
+/** Both knights' looks again with the blend time chosen: the knight's for every clip, the barbarian's none at all */
+async function setBlend(client: GameClientApi, seconds: number): Promise<void> {
+	const state = blending.get(client) ?? { pair: 'idle and a swing', seconds }
+	state.seconds = seconds
+	blending.set(client, state)
+	const look = client.looks.get(characterType('knight'))
+	if (look?.model) await client.looks.set(characterType('knight'), { ...look, model: { ...look.model, blends: [{ seconds }] } })
+}
+
+/** Plays the pair's clips on both, one then the other, a second and a half each, over and over */
+function playPair(client: GameClientApi): void {
+	const state = blending.get(client) ?? { pair: 'idle and a swing', seconds: 0.4 }
+	blending.set(client, state)
+	clearInterval(state.timer)
+	let turn = 0
+	const ids = idsOf(client, (type) => type === characterType('knight') || type === characterType('barbarian'))
+	const play = () => {
+		const clip = PAIRS[state.pair]![turn++ % 2]!
+		for (const id of ids) client.playClip(id, clip, { loop: true })
+	}
+	play()
+	state.timer = setInterval(play, 1500)
+}
+
+// ---- the weapons example: the knight's look again with other gear in its hands, and the swing that goes with it
+
+const RIGHT = ['sword_1handed', 'axe_1handed', 'dagger', 'wand', 'sword_2handed', 'axe_2handed', 'staff', 'crossbow_1handed', 'nothing'] as const
+const LEFT = [
+	'shield_round',
+	'shield_badge_color',
+	'shield_spikes_color',
+	'shield_square',
+	'spellbook_open',
+	'dagger',
+	'mug_full',
+	'nothing'
+] as const
+const TWO_HANDS = new Set<string>(['sword_2handed', 'axe_2handed', 'staff'])
+const wielding = new WeakMap<GameClientApi, { right: string; left: string }>()
+
+/** The wielder's look with the gear chosen: what it holds, and its swings (two-handed, one-handed, or its fists) */
+function wield(client: GameClientApi, change: Partial<{ right: string; left: string }>): void {
+	const now = { ...(wielding.get(client) ?? { right: 'sword_1handed', left: 'shield_round' }), ...change }
+	wielding.set(client, now)
+	const look = client.looks.get(ANIM.animationWielder)
+	if (!look?.model) return
+	const twoHanded = TWO_HANDS.has(now.right)
+	const gear = [
+		...(now.right === 'nothing' ? [] : [hold(now.right)]),
+		// a two-handed weapon takes both hands: nothing in the left
+		...(now.left === 'nothing' || twoHanded ? [] : [hold(now.left, 'l')])
+	]
+	const attacks = now.right === 'nothing' ? [{ clip: 'Melee_Unarmed_Attack_Punch_A' }] : twoHanded ? [TWO_HANDED] : [ONE_HANDED]
+	void client.looks.set(ANIM.animationWielder, { ...look, model: { ...look.model, hold: gear }, attacks })
+}
+
+// ---- the layers example: a clip on the upper body while the legs walk on
+
+const LAYERED = ['Ranged_Magic_Spellcasting', 'Throw', 'Interact', 'Ranged_Magic_Shoot', 'Use_Item', 'Melee_Block'] as const
+const layering = new WeakMap<GameClientApi, string>()
+
+function playLayered(client: GameClientApi, mask: 'upper' | null): void {
+	const clip = layering.get(client) ?? LAYERED[0]
+	for (const id of idsOf(client, (type) => type === ANIM.animationWaver)) client.playClip(id, clip, { mask })
+}
+
+export const category: CategoryLooks = {
+	view: (view: GameView<any>) => ({
+		...view,
+		units: { ...view.units, looks: { ...view.units.looks, ...looks } },
+		fx: { ...view.fx, defs: { ...presetFx(['dust', 'smoke']), ...view.fx?.defs } }
+	}),
+	looks: {
+		'animation-clips': {
+			controls: [
+				select(
+					'Clip',
+					[...CLIPS, ...SKELETON_CLIPS],
+					'Idle_A',
+					(client, clip) => {
+						chosen.set(client, { ...choiceOf(client), clip })
+						playChosen(client)
+					},
+					'The clip every character plays, by its name in the model’s file; one a character has not got, it stands for'
+				),
+				button('Next clip', (client) => stepClip(client, 1), 'Plays the clip after this one in the list'),
+				button('Clip before', (client) => stepClip(client, -1), 'Plays the clip before this one in the list'),
+				toggle(
+					'Over and over',
+					true,
+					(client, loop) => {
+						chosen.set(client, { ...choiceOf(client), loop })
+						playChosen(client)
+					},
+					'On, the clip loops; off, it plays once and they go back to standing'
+				),
+				slider(
+					'Speed',
+					{ min: 0.1, max: 3, step: 0.05, value: 1 },
+					(client, speed) => {
+						chosen.set(client, { ...choiceOf(client), speed })
+						playChosen(client)
+					},
+					'How fast the clip plays: 1 as it was made, 0.1 a tenth as fast'
+				),
+				readout(
+					'Playing',
+					(client) => {
+						const { clip } = choiceOf(client)
+						// its length on the first that has it: a skeleton's own clips only the skeletons have
+						const seconds = lineup(client)
+							.map((id) => client.renderer.kit.model(id)?.animator?.seconds(clip))
+							.find((each) => each !== undefined)
+						return seconds === undefined ? clip : `${clip} · ${seconds.toFixed(2)} s`
+					},
+					'The clip played and how long it is at normal speed'
+				)
+			],
+			ready: (client) => stage(client, { x: 26.5, z: 24.5 }, 25, 0.5)
+		},
+		'animation-attacks': {
+			controls: [
+				readout('Left', () => 'chop, slice, stab, in turn', 'The left knight swings its three clips one after another (`order: turn`)'),
+				readout('Middle', () => 'the same three, at random', 'The middle knight picks one of the same three at random each blow'),
+				readout('Right', () => 'two-handed chop and slice', 'The barbarian on the right swings its two-handed clips')
+			],
+			ready: (client) => stage(client, { x: 26.5, z: 24.5 }, 25, 0.5)
+		},
+		'animation-blending': {
+			controls: [
+				select(
+					'Clips',
+					Object.keys(PAIRS),
+					'idle and a swing',
+					(client, pair) => {
+						blending.set(client, { ...(blending.get(client) ?? { seconds: 0.4 }), pair })
+						playPair(client)
+					},
+					'The two clips both play in turn, a second and a half each: watch the change from one to the other'
+				),
+				slider(
+					'Blend (left knight)',
+					{ min: 0, max: 1, step: 0.05, value: 0.4 },
+					(client, seconds) => void setBlend(client, seconds),
+					'Seconds one clip takes to melt into the next (`ModelDef.blends`). The barbarian on the right snaps, with none'
+				),
+				readout(
+					'Left · right',
+					(client) => `blends over ${(blending.get(client)?.seconds ?? 0.4).toFixed(2)} s · snaps`,
+					'How each changes clip: the knight melts over the blend time, the barbarian jumps at once'
+				)
+			],
+			view: (view) => {
+				// the barbarian on the right snaps from clip to clip; the knight on the left blends as the slider says
+				const units = view.units.looks
+				const knightLook = units[characterType('knight')]!
+				const barbarian = units[characterType('barbarian')]!
+				return {
+					...view,
+					units: {
+						...view.units,
+						looks: {
+							...units,
+							[characterType('knight')]: { ...knightLook, model: { ...knightLook.model!, blends: [{ seconds: 0.4 }] } },
+							[characterType('barbarian')]: { ...barbarian, model: { ...barbarian.model!, blends: [{ seconds: 0 }] } }
+						}
+					}
+				}
+			},
+			ready: (client) => {
+				stage(client, { x: 25, z: 23.5 }, 12, 0.5)
+				playPair(client)
+				return () => clearInterval(blending.get(client)?.timer)
+			}
+		},
+		'animation-paces': {
+			controls: [
+				toggle(
+					'Feet matched to the pace',
+					true,
+					(client, on) => {
+						// matched: the stride the clip covers at normal speed; not: a stride that plays each clip at its own speed whatever the pace
+						for (const [type, stride, speed] of [
+							[ANIM.animationSlow, STRIDE.walk, 2],
+							[ANIM.animationJog, STRIDE.walk, 3.2],
+							[ANIM.animationRun, STRIDE.run, 6.5]
+						] as const) {
+							const look = client.looks.get(type)
+							if (look?.model) void client.looks.set(type, { ...look, model: { ...look.model, stride: on ? stride : speed / look.model.scale } })
+						}
+					},
+					'On, each walk clip plays as fast as its unit goes, so the feet keep to the ground; off, every clip plays at one speed and the feet slide'
+				),
+				readout('Paces', () => 'stroll 2 · walk 3.2 · run 6.5 cells a second', 'How fast the stroller, the walker and the runner each go')
+			],
+			ready: (client) => stage(client, { x: 25, z: 24 }, 25, 0.55)
+		},
+		'animation-weapons': {
+			controls: [
+				select(
+					'Right hand',
+					RIGHT,
+					'sword_1handed',
+					(client, right) => wield(client, { right }),
+					'What the knight holds in its right hand: a two-handed one takes both hands, and swings two-handed'
+				),
+				select(
+					'Left hand',
+					LEFT,
+					'shield_round',
+					(client, left) => wield(client, { left }),
+					'What the knight holds in its left hand, unless the right holds a two-handed weapon'
+				),
+				readout(
+					'Swings',
+					(client) => {
+						const { right } = wielding.get(client) ?? { right: 'sword_1handed' }
+						return right === 'nothing' ? 'punches' : TWO_HANDS.has(right) ? 'two-handed' : 'one-handed, three swings at random'
+					},
+					'The attack clips that go with what it holds'
+				)
+			],
+			ready: (client) => stage(client, { x: 24.6, z: 24.3 }, 11, 0.45, -0.3)
+		},
+		'animation-deaths': {
+			controls: [
+				button(
+					'Strike one down',
+					(client) => client.session.send(strike.make({})),
+					'Kills the next skeleton standing, from the left: each of the five dies its own way'
+				),
+				button('Raise them again', (client) => client.session.send(raise.make({})), 'Takes the dead away and stands a new row of five'),
+				readout('Left to right', () => DEATH_NAMES.join(' · '), 'How each of the row dies, from the left')
+			],
+			ready: (client) => stage(client, { x: 25.5, z: 23.5 }, 17, 0.6)
+		},
+		'animation-layers': {
+			controls: [
+				select(
+					'Clip',
+					LAYERED,
+					LAYERED[0],
+					(client, clip) => {
+						layering.set(client, clip)
+						playLayered(client, 'upper')
+					},
+					'The clip the walking mage plays, on its upper body: its legs walk on'
+				),
+				button(
+					'On the upper body',
+					(client) => playLayered(client, 'upper'),
+					'Plays the clip on the chest, arms and head alone, the legs still walking'
+				),
+				button('On the whole body', (client) => playLayered(client, null), 'Plays the clip on the whole body: the legs stop walking and slide'),
+				readout('Legs', () => 'walking round the square all the while', 'The mage walks round a square the whole time: only the clip on top changes')
+			],
+			ready: (client) => stage(client, { x: 24.5, z: 23.5 }, 19, 0.65)
+		}
+	}
+}

package/starters/examples/src/examples/catalog.ts

@@ -0,0 +1,52 @@
+/**
+ * Every example on the rules' side, by category: what the list shows, and what each adds to the game's rules (`src/rules.ts`
+ * registers them). The engine alone, as the rules are. A category's examples are its folder's `index.ts`; their looks
+ * its `looks.ts` (`./looks.ts` lists those)
+ */
+import { CATEGORIES, type CategoryId, type ExampleCategory, type ExampleDef } from './define'
+import { category as mechanics } from './mechanics/index'
+import { category as abilities } from './abilities/index'
+import { category as moba } from './moba/index'
+import { category as rts } from './rts/index'
+import { category as fx } from './fx/index'
+import { category as customFx } from './custom-fx/index'
+import { category as animation } from './animation/index'
+import { category as customAnimation } from './custom-animation/index'
+import { category as destruction } from './destruction/index'
+import { category as construction } from './construction/index'
+import { category as nature } from './nature/index'
+import { category as post } from './post/index'
+import { category as dynamicMap } from './dynamic-map/index'
+import { category as cinematics } from './cinematics/index'
+import { category as dialogs } from './dialogs/index'
+import { category as gui } from './gui/index'
+import { category as showcase } from './showcase/index'
+import { category as performance } from './performance/index'
+
+/** The categories' rules and examples, by category id */
+export const categories: Record<CategoryId, ExampleCategory> = {
+	mechanics,
+	abilities,
+	moba,
+	rts,
+	fx,
+	'custom-fx': customFx,
+	animation,
+	'custom-animation': customAnimation,
+	destruction,
+	construction,
+	nature,
+	post,
+	'dynamic-map': dynamicMap,
+	cinematics,
+	dialogs,
+	gui,
+	showcase,
+	performance
+}
+
+/** Every example, in the list's order */
+export const examples: readonly ExampleDef[] = CATEGORIES.flatMap((each) => categories[each.id].examples)
+
+/** An example by its id */
+export const exampleNamed = (id: string): ExampleDef | undefined => examples.find((each) => each.id === id)