@v12-engine/create 0.1.0 → 0.4.0

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

@@ -0,0 +1,447 @@
+/**
+ * The destruction examples on the client's side: how what they break looks, and how it comes apart (`UnitLook.death`:
+ * a building crumbling, blown apart or toppled, trees and rocks shattered into pieces of their own models, flung with
+ * the client's physics), the grass they burn, and the buttons. The meteor's fall is drawn here; where it lands is the
+ * rules' (`destruction.meteor`)
+ */
+import type { DeathDef, DebrisPiece, GameClientApi, GameView, ModelDef, UnitLook } from '@v12-engine/client'
+import { foliage, presetFoliage, presetFx } from '@v12-engine/client'
+import { button, type CategoryLooks, type ExampleLook, readout, slider, toggle } from '../../shell/look'
+import { bombard, D, fuse, GRASS, HOW, hurt, meteor, raze, relay, shockwave, smash } from './index'
+
+/** A model of the shared art made `width` across: its size at scale 1 (across, up, deep) is in the assets' `manifest.json` */
+const sized = (src: string, size: [number, number, number], width: number, own: Partial<ModelDef> = {}): ModelDef => ({
+	src,
+	scale: width / Math.max(size[0], size[2]),
+	...own
+})
+
+const STONE: [number, number, number] = [0.6, 0.58, 0.55]
+const WOOD: [number, number, number] = [0.45, 0.31, 0.18]
+const LEAF: [number, number, number] = [0.22, 0.45, 0.18]
+
+/** Planks, stones and straw: what a house throws down when it is told to (`death.debris`) */
+const PLANKS: DebrisPiece[] = [
+	{ shape: 'box', size: [1.1, 0.12, 0.28], color: [0.45, 0.3, 0.18], count: 14 },
+	{ shape: 'box', size: [0.4, 0.3, 0.35], color: [0.55, 0.53, 0.5], count: 10 },
+	{ shape: 'box', size: [0.35, 0.05, 0.35], color: [0.85, 0.72, 0.38], count: 8 }
+]
+
+/** Blown apart: pieces of itself flung hard, an explosion, smoke after, smoke trailing a third of the pieces */
+const EXPLODE: DeathDef = {
+	collapse: { look: 'explode', pieces: 36, dust: true },
+	strength: 3.2,
+	fx: [
+		{ fx: 'explosion', params: { size: 1.4 } },
+		{ fx: 'smoke', delay: 0.4 }
+	],
+	pieces: { fx: 'smoke-trail', share: 0.3, landed: 'dust', params: { size: 0.5 } }
+}
+
+/** How a building comes down, by how the rules said it died */
+const BUILDING_DEATH: DeathDef = {
+	collapse: { look: 'crumble', pieces: 26, dust: true },
+	fx: 'rubble-fall',
+	how: {
+		[HOW.crumble]: { collapse: { look: 'crumble', pieces: 30, dust: true }, fx: 'rubble-fall', pieces: { landed: 'dust', share: 0.2 } },
+		[HOW.explode]: EXPLODE,
+		[HOW.blasted]: { ...EXPLODE, strength: 4 },
+		[HOW.swept]: { ...EXPLODE, fx: 'dust' },
+		[HOW.topple]: { collapse: { look: 'topple', time: 2.4, dust: true }, fx: 'rubble-fall' },
+		[HOW.sink]: {
+			collapse: { look: 'sink', time: 3, dust: true },
+			fx: [
+				{ fx: 'dust', params: { size: 2 } },
+				{ fx: 'ground-crack', params: { size: 1.4 } }
+			]
+		},
+		[HOW.shatter]: { shatter: 40, strength: 1.4, fx: 'dust', pieces: { landed: 'dust', share: 0.15, params: { size: 0.4 } } },
+		[HOW.planks]: { debris: PLANKS, strength: 1.6, fx: 'rubble-fall' },
+		[HOW.crushed]: { collapse: { look: 'crumble', pieces: 30, dust: true }, strength: 1.2, fx: 'rubble-fall' }
+	}
+}
+
+/** Smoke under half its health, fire under a quarter; both go as it is mended */
+const HURT: UnitLook['damaged'] = [
+	{ below: 0.5, fx: 'smoke', params: { size: 0.9 } },
+	{ below: 0.25, fx: 'fire', params: { size: 0.9 } }
+]
+
+/** A building of the shared art: its model, the box drawn while it loads, how it comes down and how it looks hurt */
+const house = (height: number, model: ModelDef, box: [number, number, number], own: Partial<UnitLook> = {}): UnitLook => ({
+	height,
+	model,
+	shapes: [{ shape: 'box', size: box, offset: [0, box[1] / 2, 0], color: WOOD }],
+	death: BUILDING_DEATH,
+	damaged: HURT,
+	// put down again (Lay it out again), it rises out of the ground
+	construction: { motion: 'rise', done: { fx: 'dust' } },
+	...own
+})
+
+/** Trees of the shared art's forest a tree is drawn as, one picked for each */
+const TREES = ['common_tree_1', 'common_tree_2', 'common_tree_3', 'common_tree_5', 'pine_1', 'pine_2', 'pine_3', 'pine_5']
+const ROCKS = ['rock_medium_1', 'rock_medium_2', 'rock_medium_3']
+
+/** Scenery broken: into pieces of its own model, flung away from what broke it */
+const shattered = (pieces: number, strength: number, fx: string): DeathDef => ({
+	shatter: pieces,
+	strength,
+	fx,
+	pieces: { landed: 'dust', share: 0.1, params: { size: 0.3 } }
+})
+
+const looks: Record<string, UnitLook> = {
+	[D.house]: house(2.6, sized('rts/house.glb', [2.6, 2.3, 3.5], 3), [2.6, 2, 2.6], {
+		// one of three houses for each, picked by its id
+		looks: {
+			house: sized('rts/house.glb', [2.6, 2.3, 3.5], 3),
+			house_3: sized('rts/house_3.glb', [2.7, 2.8, 2.4], 3),
+			house_4: sized('rts/house_4.glb', [2.7, 2.3, 2.6], 3)
+		},
+		mix: ['house', 'house_3', 'house_4']
+	}),
+	[D.hut]: house(2.2, sized('rts/hut.glb', [2.6, 2.3, 2.3], 2.1), [1.8, 1.6, 1.8]),
+	[D.tower]: house(4.6, sized('rts/watch_tower.glb', [1.5, 4.4, 1.6], 1.9), [1.4, 4, 1.4], {
+		// a tower falls over rather than in on itself, when nothing else is said
+		death: { ...BUILDING_DEATH, collapse: { look: 'topple', time: 2, dust: true } }
+	}),
+	[D.wall]: house(1.4, sized('rts/stone_wall.glb', [4.7, 1.3, 0.7], 3.1), [3, 1.2, 0.7], {
+		shapes: [{ shape: 'box', size: [3, 1.2, 0.7], offset: [0, 0.6, 0], color: STONE }],
+		death: { ...BUILDING_DEATH, collapse: { look: 'crumble', pieces: 16, dust: true } }
+	}),
+	[D.fence]: house(1.4, sized('rts/wooden_wall.glb', [4.1, 1.6, 0.2], 3.1), [3, 1.1, 0.2], {
+		death: { shatter: 10, strength: 2, fx: 'dust', how: { [HOW.planks]: { debris: PLANKS.slice(0, 1), strength: 1.5 } } },
+		damaged: []
+	}),
+	[D.keg]: {
+		height: 1,
+		model: sized('dungeon/barrel.glb', [1, 1.3, 1], 0.8),
+		shapes: [{ shape: 'cylinder', size: [0.7, 0.9, 0.7], offset: [0, 0.45, 0], color: [0.5, 0.33, 0.18] }],
+		// the blast is the rules' (an explosion where it stood): the keg itself goes to splinters
+		death: { shatter: 10, strength: 3.5, pieces: { fx: 'fire-trail', share: 0.4, params: { size: 0.3 } } }
+	},
+	[D.tree]: {
+		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: WOOD },
+			{ shape: 'cone', size: [1.5, 1.8, 1.5], offset: [0, 1.7, 0], color: LEAF }
+		],
+		death: {
+			...shattered(12, 1.6, 'leaves'),
+			how: {
+				[HOW.blasted]: shattered(14, 3.4, 'leaves'),
+				// a wood broken at once: fewer pieces each, so the physics keeps up
+				[HOW.swept]: shattered(6, 4, 'leaves'),
+				[HOW.crushed]: { clip: undefined, fx: 'leaves', shatter: 10, strength: 1.4 }
+			}
+		},
+		// grown back: up out of the ground, leaves shaken off it as it is whole
+		construction: { motion: 'grow', done: { fx: 'leaves' } }
+	},
+	[D.rock]: {
+		height: 1.3,
+		looks: Object.fromEntries(ROCKS.map((name) => [name, { src: `forest/${name}.glb`, scale: 1.25 }])),
+		mix: ROCKS,
+		vary: { scale: 0.2 },
+		shapes: [{ shape: 'sphere', size: [1.8, 1.2, 1.8], offset: [0, 0.5, 0], color: STONE }],
+		death: { ...shattered(18, 1.6, 'dust'), how: { [HOW.blasted]: shattered(20, 3.2, 'dust'), [HOW.swept]: shattered(18, 2.8, 'dust') } },
+		construction: { motion: 'rise', done: { fx: 'dust' } }
+	},
+	// the shared art has no catapult: a cart of the village's, its shafts to the back, a boulder of the RTS kit's loaded
+	// on it, throwing boulders like it. The parts below are drawn while it loads
+	[D.catapult]: {
+		height: 2,
+		model: {
+			...sized('village/cart.glb', [0.693, 1.194, 1.391], 2.1, { turn: Math.PI }),
+			points: { load: { offset: [0, 0.75, -0.2] } },
+			hold: [{ src: 'rts/rock.glb', at: 'load' }]
+		},
+		shapes: [
+			{ shape: 'box', size: [1.4, 0.4, 2], offset: [0, 0.5, 0], color: WOOD },
+			{ shape: 'cylinder', size: [0.7, 0.25, 0.7], offset: [-0.8, 0.35, 0.6], color: [0.3, 0.2, 0.12] },
+			{ shape: 'cylinder', size: [0.7, 0.25, 0.7], offset: [0.8, 0.35, 0.6], color: [0.3, 0.2, 0.12] },
+			{ shape: 'cylinder', size: [0.7, 0.25, 0.7], offset: [-0.8, 0.35, -0.6], color: [0.3, 0.2, 0.12] },
+			{ shape: 'cylinder', size: [0.7, 0.25, 0.7], offset: [0.8, 0.35, -0.6], color: [0.3, 0.2, 0.12] },
+			{ shape: 'box', size: [0.2, 1.8, 0.2], offset: [0, 1.4, -0.3], color: [0.55, 0.38, 0.22] },
+			{ shape: 'box', size: [0.6, 0.25, 0.6], offset: [0, 2.3, -0.3], color: 'team' }
+		],
+		shot: { model: 'rts/rock.glb', color: [0.5, 0.48, 0.45], size: 0.55 },
+		death: { debris: PLANKS.slice(0, 1), strength: 1.2, fx: 'dust' }
+	},
+	// nothing to see: where a blast comes from
+	[D.blast]: { height: 0.1, shapes: [], death: 'none' }
+}
+
+/** The ground's grass of these examples: a meadow, drawn black and short where it burnt, flat where it was laid down */
+const grass = foliage({ ...presetFoliage.meadow, ruined: { stubble: 0.12 } })
+
+// ---- the meteor's fall, drawn
+
+/** How long a meteor takes to come down, in seconds */
+const FALL = 0.9
+
+/**
+ * A meteor falls on a point: a fireball from high in the sky, its trail behind it, and when it reaches the ground the
+ * rules are told (`destruction.meteor`): what breaks is theirs. The fall is the screen's alone
+ */
+function callMeteor(client: GameClientApi, at: { x: number; z: number }, size = 1): void {
+	const from = { x: at.x - 14, y: 34, z: at.z + 10 }
+	const ball = client.fx.play('fireball', { at: from, params: { size: 2.4 * size, light: 4, impact: '' } })
+	client.timers.tween(
+		FALL,
+		(t) => {
+			const ease = t * t
+			ball.move({ at: { x: from.x + (at.x - from.x) * ease, y: from.y * (1 - ease) + 0.5, z: from.z + (at.z - from.z) * ease } })
+		},
+		{
+			onEnd: () => {
+				ball.stop()
+				client.session.send(meteor.make({ x: at.x, z: at.z, size }))
+			}
+		}
+	)
+}
+
+/** Where on the ground a click of 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
+}
+
+/**
+ * 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 })
+}
+
+/** A count of what still stands of some types */
+const standing = (client: GameClientApi, types: readonly string[]) =>
+	client.session.snapshot().entities.filter((each) => types.includes(each.type) && each.health > 0).length
+
+const again = (id: string) =>
+	button(
+		'Lay it out again',
+		(client) => client.session.send(relay.make({ example: id })),
+		'Clears what is left and puts the scene back as it started: buildings rise out of the ground, the grass whole again.'
+	)
+
+/** Whether a click calls a meteor down where it lands: the meteor example's, off as it is left */
+let clickToStrike = false
+
+const examples: Record<string, ExampleLook> = {
+	'destruction-collapse': {
+		controls: [
+			button(
+				'Crumble',
+				(client) => client.session.send(raze.make({ how: HOW.crumble })),
+				'Brings down the first building of the row still standing: pieces of its own model slump where it stood, in a cloud of dust.'
+			),
+			button(
+				'Blow apart',
+				(client) => client.session.send(raze.make({ how: HOW.explode })),
+				'Blows up the next building: an explosion flings pieces of its model away, a third of them trailing smoke.'
+			),
+			button(
+				'Topple',
+				(client) => client.session.send(raze.make({ how: HOW.topple })),
+				'The next building tips over, away from the camera, in one piece and sinks into the ground.'
+			),
+			button(
+				'Sink',
+				(client) => client.session.send(raze.make({ how: HOW.sink })),
+				'The next building sinks straight down into the ground in one piece, the ground cracking round it.'
+			),
+			button(
+				'Shatter',
+				(client) => client.session.send(raze.make({ how: HOW.shatter })),
+				'The next building is split into 40 pieces of its own model that tumble with physics and settle on the ground.'
+			),
+			button(
+				'Planks',
+				(client) => client.session.send(raze.make({ how: HOW.planks })),
+				'The next building falls as pieces described in code, planks, stones and straw, rather than pieces of its model.'
+			),
+			button(
+				'Hurt them',
+				(client) => client.session.send(hurt.make({ share: 0.2 })),
+				'Takes every building down to a fifth of its health: each smokes under half and burns under a quarter.'
+			),
+			again('destruction-collapse'),
+			readout('Standing', (client) => `${standing(client, [D.house, D.hut, D.tower])} of 6`, 'How many of the six buildings of the row still stand.')
+		],
+		// the row a little left of the middle: the card stands over the right of the picture
+		ready: (client) => look(client, 31, 22, 60, 44)
+	},
+	'destruction-meteor': {
+		controls: [
+			button(
+				'Meteor',
+				(client) => callMeteor(client, { x: 24, z: 24 }, 1),
+				'Drops a meteor on the middle of the village: it digs a crater and blows apart what stands near.'
+			),
+			button(
+				'Meteor shower',
+				(client) => {
+					const spots = [
+						[17, 29],
+						[31, 27],
+						[24, 17],
+						[14, 18],
+						[34, 18],
+						[24, 34]
+					]
+					spots.forEach(([x, z], i) => client.timers.after(i * 0.45, () => callMeteor(client, { x, z }, 0.6)))
+				},
+				'Six smaller meteors, one after another round the village: each digs its own crater and burns the grass.'
+			),
+			toggle(
+				'Click to strike',
+				false,
+				(_client, on) => (clickToStrike = on),
+				'While on, a click on the ground calls a meteor down where you clicked, instead of selecting.'
+			),
+			again('destruction-meteor'),
+			readout('Still standing', (client) => `${standing(client, [D.house, D.hut, D.tower, D.fence])} buildings · ${standing(client, [D.tree])} trees`)
+		],
+		ready: (client) => {
+			const camera = look(client, 24, 22, 58, 48)
+			const canvas = client.scene.getEngine().getRenderingCanvas()
+			const strike = (event: PointerEvent) => {
+				if (!clickToStrike || event.button !== 0) return
+				const at = groundUnder(client, event)
+				if (!at) return
+				// the click is the meteor's: nothing is selected by it
+				event.stopImmediatePropagation()
+				callMeteor(client, at, 0.8)
+			}
+			canvas?.addEventListener('pointerdown', strike, { capture: true })
+			return () => {
+				clickToStrike = false
+				canvas?.removeEventListener('pointerdown', strike, { capture: true })
+				camera()
+			}
+		}
+	},
+	'destruction-shockwave': {
+		controls: [
+			button(
+				'Shockwave',
+				(client) => client.session.send(shockwave.make({})),
+				'The knight sends a ring out round him: every tree, rock and fence it passes is broken and flung away, the grass laid flat.'
+			),
+			again('destruction-shockwave'),
+			readout('Trees standing', (client) => String(standing(client, [D.tree])))
+		],
+		ready: (client) => {
+			const camera = look(client, 24, 24, 60, 55)
+			// a whole wood broken at once: room for many more pieces than the player's Debris setting keeps
+			const was = client.debrisMost
+			client.debrisMost = 1500
+			return () => {
+				client.debrisMost = was
+				camera()
+			}
+		}
+	},
+	'destruction-chain': {
+		controls: [
+			button(
+				'Light the fuse',
+				(client) => client.session.send(fuse.make({})),
+				'Sets off the first keg of powder: its blast sets off the kegs near it, and the fort goes up one keg after another.'
+			),
+			again('destruction-chain'),
+			readout('Kegs left', (client) => String(standing(client, [D.keg])))
+		],
+		ready: (client) => look(client, 23, 24, 62, 55)
+	},
+	'destruction-regrow': {
+		controls: [
+			button(
+				'Smash it all',
+				(client) => client.session.send(smash.make({})),
+				'Breaks every tree and rock of the meadow at once: a few seconds later each grows back out of the ground where it stood, and the grass comes back.'
+			),
+			readout('Standing', (client) => `${standing(client, [D.tree])} trees · ${standing(client, [D.rock])} rocks`)
+		],
+		ready: (client) => look(client, 24, 25, 52, 48)
+	},
+	'destruction-siege': {
+		controls: [
+			button(
+				'Fire!',
+				(client) => client.session.send(bombard.make({})),
+				'Each catapult throws boulders at what of the fort is nearest it, and at the next as that falls.'
+			),
+			slider(
+				'Debris pieces',
+				{ min: 0, max: 600, step: 20, value: 240 },
+				(client, value) => (client.debrisMost = value),
+				'The most broken pieces drawn at once (the Debris setting): at 0 nothing breaks apart into pieces, buildings fall without them; fire again to see the difference.'
+			),
+			again('destruction-siege'),
+			readout('Fort standing', (client) => `${standing(client, [D.wall, D.tower, D.house, D.hut])} of 10`)
+		],
+		ready: (client) => look(client, 24, 23, 56, 48)
+	}
+}
+
+/** The ready-made effects the destruction examples play (`presetFx`): a view plays none it did not take */
+const FX = [
+	'explosion',
+	'fireball',
+	'smoke',
+	'fire',
+	'dust',
+	'rubble-fall',
+	'ground-crack',
+	'shockwave',
+	'impact-ring',
+	'leaves',
+	'smoke-trail',
+	'fire-trail',
+	'blood-burst',
+	'spark-burst'
+] as const
+
+/** The meteor and the shockwave kill people too: blown off their feet (`deathFor`, for every type of the game) */
+const blownApart = (view: GameView): GameView['units'] => ({
+	...view.units,
+	looks: { ...view.units?.looks, ...looks },
+	deathFor: (entity, death) => {
+		if (entity.def.kind === 'unit' && (death.how === HOW.blasted || death.how === HOW.swept))
+			return { fx: [{ fx: 'blood-burst' }, { fx: 'dust' }], strength: 2 }
+		return view.units?.deathFor?.(entity, death)
+	},
+	// no bars over scenery, nor over a tree growing back: only over what is fought over
+	hud: {
+		...view.units?.hud,
+		bars: (entity) => (SCENERY.has(entity.def.id) ? { hide: true } : view.units?.hud?.bars?.(entity))
+	}
+})
+
+/** What stands about to be broken: no health or progress bars over it */
+const SCENERY = new Set<string>([D.tree, D.rock, D.keg, D.fence, D.blast])
+
+export const category: CategoryLooks = {
+	looks: examples,
+	view: (view) => ({
+		...view,
+		units: blownApart(view),
+		// the ready-made effects these examples play, under what the game's view says of them
+		fx: { ...view.fx, defs: { ...presetFx(FX), ...view.fx?.defs } },
+		ground: { ...view.ground, cellLayers: { ...view.ground?.cellLayers, [GRASS]: grass } }
+	})
+}