@v12-engine/create 0.1.1 → 0.4.0

package/starters/examples/src/examples/custom-fx/glaive.look.ts

@@ -0,0 +1,110 @@
+/**
+ * A shot drawn your own way, on the client's side: the thrower's `shot.draw`, called as each glaive leaves with what
+ * the shot is (`ShotContext`: the shot, its shooter, where it left from, the render kit). It makes the glaive (three
+ * blades of meshes and a ribbon behind them, `TrailMesh`), is told where it is every frame (`move`, with the way it
+ * goes) and spins it, and as it lands (`dispose`) throws sparks there and lets the ribbon fade before it goes
+ */
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial.js'
+import { Color3 } from '@babylonjs/core/Maths/math.color.js'
+import { CreateBox } from '@babylonjs/core/Meshes/Builders/boxBuilder.js'
+import { CreateCylinder } from '@babylonjs/core/Meshes/Builders/cylinderBuilder.js'
+import { TrailMesh } from '@babylonjs/core/Meshes/trailMesh.js'
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode.js'
+import type { ShotContext, ShotDrawing, UnitLook } from '@v12-engine/client'
+import { type ExampleLook, select } from '../../shell/look'
+import { character, person } from '../common/looks'
+import { aim } from '../fx/stage'
+import { GLAIVE_AT } from './glaive'
+
+/** The blades' glow, as the card sets it */
+const glow = new Color3(0.3, 1, 0.75)
+
+/** One glaive on its way */
+function drawGlaive({ kit, from }: ShotContext): ShotDrawing {
+	const { scene } = kit
+	const root = new TransformNode('customFx.glaive', scene)
+	root.position.set(from.x, from.y, from.z)
+	const spinner = new TransformNode('customFx.glaiveSpin', scene)
+	spinner.parent = root
+	const steel = new StandardMaterial('customFx.glaiveSteel', scene)
+	steel.diffuseColor = new Color3(0.2, 0.22, 0.25)
+	steel.emissiveColor = glow.clone()
+	steel.specularColor = new Color3(1, 1, 1)
+	// three curved-looking blades round a hub, lying flat
+	const hub = CreateCylinder('customFx.glaiveHub', { height: 0.08, diameter: 0.25, tessellation: 12 }, scene)
+	hub.parent = spinner
+	hub.material = steel
+	for (let i = 0; i < 3; i++) {
+		const blade = CreateBox('customFx.glaiveBlade', { width: 0.7, height: 0.04, depth: 0.12 }, scene)
+		blade.parent = spinner
+		blade.material = steel
+		blade.rotation.y = (i / 3) * Math.PI * 2
+		blade.position.set(Math.cos(-blade.rotation.y) * 0.32, 0, Math.sin(-blade.rotation.y) * 0.32)
+		blade.rotation.y += 0.5
+	}
+	// the ribbon: a point at the tip of one blade, sweeping as it spins
+	const tip = new TransformNode('customFx.glaiveTip', scene)
+	tip.parent = spinner
+	tip.position.x = 0.62
+	const trail = new TrailMesh('customFx.glaiveTrail', tip, scene, 0.12, 40, true)
+	const ribbon = new StandardMaterial('customFx.glaiveRibbon', scene)
+	ribbon.emissiveColor = glow.clone()
+	ribbon.disableLighting = true
+	ribbon.alpha = 0.55
+	trail.material = ribbon
+	for (const mesh of [hub, trail, ...spinner.getChildMeshes()]) mesh.isPickable = false
+	let spin = 0
+	return {
+		move(at, heading) {
+			root.position.set(at.x, at.y, at.z)
+			root.rotation.set(0, heading.yaw, 0)
+			// tipped a little, spinning fast
+			spin += 0.45
+			spinner.rotation.set(0.25, spin, 0)
+		},
+		dispose() {
+			kit.fx.play('spark-burst', {
+				at: { x: root.position.x, y: root.position.y, z: root.position.z },
+				params: { count: 20, color: glow.toHexString(), size: 0.7 }
+			})
+			root.dispose(false, true)
+			steel.dispose()
+			// the ribbon fades where it was, then goes
+			let left = 0.35
+			const fade = scene.onBeforeRenderObservable.add(() => {
+				left -= scene.getEngine().getDeltaTime() / 1000
+				ribbon.alpha = Math.max(left / 0.35, 0) * 0.55
+				if (left > 0) return
+				scene.onBeforeRenderObservable.remove(fade)
+				trail.dispose()
+				ribbon.dispose()
+			})
+		}
+	}
+}
+
+/** The thrower: the rogue, a glaive drawn the game's own way */
+export const glaiverLook: UnitLook = {
+	height: 1.8,
+	model: character('rogue_hooded', 0.72, { animations: { attack: 'Ranged_1H_Shoot' } }),
+	shot: { draw: drawGlaive },
+	shapes: person(1.8, [0.2, 0.5, 0.4])
+}
+
+const COLORS: Record<string, [number, number, number]> = { Jade: [0.3, 1, 0.75], Ember: [1, 0.5, 0.15], Frost: [0.5, 0.8, 1], Blood: [1, 0.15, 0.2] }
+
+export const glaiveLook: ExampleLook = {
+	controls: [
+		select(
+			'Glow',
+			Object.keys(COLORS),
+			'Jade',
+			(_client, name) => glow.set(...(COLORS[name] ?? COLORS.Jade!)),
+			'The colour the blades and the ribbon behind them glow, on every glaive in the air'
+		)
+	],
+	ready: (client) => {
+		glow.set(...COLORS.Jade!)
+		aim(client, GLAIVE_AT, 15, 0.6)
+	}
+}

package/starters/examples/src/examples/custom-fx/glaive.ts

@@ -0,0 +1,40 @@
+/**
+ * A shot drawn your own way, on the rules' side: two glaive throwers and the dummies they throw at. To the rules a
+ * glaive is a shot like any; how it flies on the screen is its look's `draw` (`./glaive.look.ts`)
+ */
+import type { Game } from '@v12-engine/engine'
+import { ENEMY, PLAYER, UNIT } from '../common/units'
+import { type ExampleDef, exampleField } from '../define'
+
+export const GLAIVER = 'customFxGlaiver'
+export const GLAIVE_AT = { x: 24, z: 24 }
+
+export const glaive: ExampleDef = {
+	id: 'custom-fx-glaive',
+	category: 'custom-fx',
+	title: 'A shot of your own',
+	summary:
+		"A shot drawn in code (`ShotDef.draw`): a spinning three-bladed glaive made of meshes, a glowing ribbon behind it (Babylon's `TrailMesh`), sparks where it lands. The throwers keep throwing; turn the blades' colour.",
+	tags: ['ShotDef.draw', 'projectile', 'missile', 'TrailMesh', 'ribbon', 'meshes', 'custom shot'],
+	environment: 'dusk',
+	map: () => exampleField({ name: 'Range', players: 2 }),
+	start: (world) => {
+		world.spawn(GLAIVER, { at: { x: GLAIVE_AT.x - 5, z: GLAIVE_AT.z - 2 }, owner: PLAYER })
+		world.spawn(GLAIVER, { at: { x: GLAIVE_AT.x - 5, z: GLAIVE_AT.z + 2 }, owner: PLAYER })
+		for (const dz of [-3, 0, 3]) world.spawn(UNIT.dummy, { at: { x: GLAIVE_AT.x + 5, z: GLAIVE_AT.z + dz }, owner: ENEMY })
+	},
+	source: ['examples/custom-fx/glaive.ts', 'examples/custom-fx/glaive.look.ts']
+}
+
+/** Registers the thrower: slow glaives, from 11 cells away */
+export function glaiveRules(game: Game<any>): void {
+	game.unit({
+		id: GLAIVER,
+		name: 'Glaive thrower',
+		kind: 'unit',
+		radius: 0.42,
+		stats: { health: 400, attackDamage: 25, attackSpeed: 0.8, attackRange: 11, moveSpeed: 4 },
+		sight: 13,
+		attacks: [{ damagePoint: 0.4, acquisitionRange: 12, projectileSpeed: 9 }]
+	})
+}

package/starters/examples/src/examples/custom-fx/gpu.look.ts

@@ -0,0 +1,145 @@
+/**
+ * Particles on the graphics card, on the client's side: `customFx.fountain` is made in code (`FxDef.make`), with
+ * Babylon's `GPUParticleSystem` where the browser can move particles on the graphics card, its `ParticleSystem`
+ * otherwise. `make` is handed the scene, a node that moves with the effect (`anchor`) and the knobs; it gives back what
+ * runs every frame, what changes with the knobs, and what takes it all away. A light and the glow of the scene make
+ * it shine on what is round it
+ */
+import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture.js'
+import { NoiseProceduralTexture } from '@babylonjs/core/Materials/Textures/Procedurals/noiseProceduralTexture.js'
+import { Color3, Color4 } from '@babylonjs/core/Maths/math.color.js'
+import { Vector3 } from '@babylonjs/core/Maths/math.vector.js'
+import { PointLight } from '@babylonjs/core/Lights/pointLight.js'
+import { GPUParticleSystem } from '@babylonjs/core/Particles/gpuParticleSystem.js'
+import { ParticleSystem } from '@babylonjs/core/Particles/particleSystem.js'
+import type { Scene } from '@babylonjs/core/scene.js'
+import type { FxDef, FxHandle, GameClientApi } from '@v12-engine/client'
+import { type ExampleLook, readout, slider, toggle } from '../../shell/look'
+import { aim } from '../fx/stage'
+import { FOUNTAIN_AT } from './gpu'
+
+/** A soft round spark, drawn once in a canvas: white, so the system's colours colour it */
+function sparkTexture(scene: Scene): DynamicTexture {
+	const texture = new DynamicTexture('customFx.spark', 64, scene, false)
+	const context = texture.getContext()
+	const glow = context.createRadialGradient(32, 32, 0, 32, 32, 32)
+	glow.addColorStop(0, 'rgba(255,255,255,1)')
+	glow.addColorStop(0.25, 'rgba(255,255,255,0.8)')
+	glow.addColorStop(1, 'rgba(255,255,255,0)')
+	context.fillStyle = glow
+	context.fillRect(0, 0, 64, 64)
+	texture.update()
+	texture.hasAlpha = true
+	return texture
+}
+
+/** The fountain: sparks thrown up from a ring, turning from white to cyan to violet as they fall, thrown about by noise */
+const fountain: FxDef = {
+	params: { count: 100_000, gpu: true },
+	make: ({ scene, anchor, params }) => {
+		const count = Number(params.count)
+		const onCard = params.gpu !== false && GPUParticleSystem.IsSupported
+		const system = onCard
+			? new GPUParticleSystem('customFx.fountain', { capacity: count }, scene)
+			: new ParticleSystem('customFx.fountain', count, scene)
+		system.particleTexture = sparkTexture(scene)
+		system.emitter = anchor as never
+		// a ring at the foot, each spark sent up and a little out
+		system.createDirectedCylinderEmitter(0.6, 0.1, 0.2, new Vector3(-0.12, 1, -0.12), new Vector3(0.12, 1, 0.12))
+		system.emitRate = count / 3.2
+		system.minLifeTime = 2.4
+		system.maxLifeTime = 3.2
+		system.minEmitPower = 9
+		system.maxEmitPower = 13
+		system.gravity = new Vector3(0, -7, 0)
+		system.minSize = 0.04
+		system.maxSize = 0.11
+		system.addColorGradient(0, new Color4(1, 1, 1, 0.45))
+		system.addColorGradient(0.25, new Color4(0.3, 0.85, 1, 0.4))
+		system.addColorGradient(0.7, new Color4(0.55, 0.25, 1, 0.3))
+		system.addColorGradient(1, new Color4(0.3, 0.1, 0.8, 0))
+		system.blendMode = ParticleSystem.BLENDMODE_ADD
+		// noise: each spark pushed about by where it is in a field that moves, so the jet frays as it falls
+		const noise = new NoiseProceduralTexture('customFx.noise', 256, scene)
+		noise.animationSpeedFactor = 4
+		noise.persistence = 1.6
+		noise.brightness = 0.5
+		system.noiseTexture = noise
+		system.noiseStrength = new Vector3(4, 1, 4)
+		system.start()
+		// its light, breathing
+		const light = new PointLight('customFx.fountainLight', new Vector3(0, 3, 0), scene)
+		light.parent = anchor
+		light.diffuse = new Color3(0.45, 0.6, 1)
+		light.range = 16
+		let time = 0
+		let stoppedAt: number | undefined
+		return {
+			update: (dt) => {
+				time += dt
+				light.intensity = (2.2 + Math.sin(time * 3) * 0.4) * (stoppedAt === undefined ? 1 : Math.max(1 - (time - stoppedAt) / 3, 0))
+				// over once the last sparks let go have fallen
+				return stoppedAt === undefined || time - stoppedAt < 3.3
+			},
+			stop: () => {
+				system.stop()
+				stoppedAt = time
+			},
+			dispose: () => {
+				system.dispose()
+				noise.dispose()
+				light.dispose()
+			}
+		}
+	}
+}
+
+/** The fountain of this example, taken into the game's view */
+export const gpuFx: Record<string, FxDef> = { 'customFx.fountain': fountain }
+
+const chosen = { count: 100_000, gpu: true }
+let playing: FxHandle | undefined
+
+/** Plays it again with the card's count and where it is moved */
+function replay(client: GameClientApi): void {
+	playing?.stop({ mode: 'at-once' })
+	playing = client.fx.play('customFx.fountain', { at: FOUNTAIN_AT, params: { ...chosen } })
+}
+
+export const gpuLook: ExampleLook = {
+	controls: [
+		slider(
+			'Sparks',
+			{ min: 5000, max: 200_000, step: 5000, value: chosen.count },
+			(client, count) => {
+				chosen.count = count
+				replay(client)
+			},
+			'How many sparks the fountain keeps in the air: watch the frames a second as it climbs'
+		),
+		toggle(
+			'On the graphics card',
+			true,
+			(client, on) => {
+				chosen.gpu = on
+				replay(client)
+			},
+			'Off: the same fountain moved by the CPU frame by frame, which keeps far fewer sparks a second'
+		),
+		readout(
+			'Frames a second',
+			(client) => `${Math.round(client.scene.getEngine().getFps())}${GPUParticleSystem.IsSupported ? '' : ' (no GPU particles here)'}`,
+			'How fast the page draws now: what the sparks cost'
+		)
+	],
+	ready: (client) => {
+		chosen.count = 100_000
+		chosen.gpu = true
+		aim(client, { x: FOUNTAIN_AT.x, z: FOUNTAIN_AT.z }, 34, 0.3)
+		replay(client)
+		return () => {
+			playing?.stop({ mode: 'at-once' })
+			playing = undefined
+		}
+	}
+}

package/starters/examples/src/examples/custom-fx/gpu.ts

@@ -0,0 +1,22 @@
+/**
+ * Particles on the graphics card, on the rules' side: nothing but a mage to stand by the fountain. The fountain is the
+ * view's effect, made of Babylon's own particle system (`./gpu.look.ts`)
+ */
+import { PLAYER, UNIT } from '../common/units'
+import type { ExampleDef } from '../define'
+
+export const FOUNTAIN_AT = { x: 24, z: 24 }
+
+export const gpu: ExampleDef = {
+	id: 'custom-fx-gpu-particles',
+	category: 'custom-fx',
+	title: "Babylon's particles, a hundred thousand",
+	summary:
+		'An effect that makes its own Babylon `GPUParticleSystem` (`make`): a fountain of up to 200 000 sparks moved on the graphics card, thrown about by noise, falling back. Turn the count up; turn the graphics card off to see what the CPU manages.',
+	tags: ['GPUParticleSystem', 'ParticleSystem', 'Babylon', 'make', 'gpu', 'noise', 'particles', 'performance'],
+	environment: 'night',
+	start: (world) => {
+		world.spawn(UNIT.mage, { at: { x: FOUNTAIN_AT.x - 4, z: FOUNTAIN_AT.z - 2 }, owner: PLAYER })
+	},
+	source: ['examples/custom-fx/gpu.ts', 'examples/custom-fx/gpu.look.ts']
+}

package/starters/examples/src/examples/custom-fx/index.ts

@@ -0,0 +1,25 @@
+/**
+ * The examples of effects of your own, on the rules' side (`ExampleCategory`): their list entries, maps and starts,
+ * and what they add to the game. Most effects of one's own are the screen's alone, so most examples here put a unit or
+ * two down and leave the rest to their look (`<name>.look.ts` beside each, gathered in `./looks.ts`)
+ */
+import type { Game } from '@v12-engine/engine'
+import type { ExampleCategory } from '../define'
+import { glaive, glaiveRules } from './glaive'
+import { gpu } from './gpu'
+import { lights } from './lights'
+import { meteor } from './meteor'
+import { parts } from './parts'
+import { portal, portalRules } from './portal'
+import { renderer } from './renderer'
+import { ribbons } from './ribbons'
+import { shield, shieldRules } from './shield'
+
+export const category: ExampleCategory = {
+	rules: (game: Game<any>) => {
+		shieldRules(game)
+		portalRules(game)
+		glaiveRules(game)
+	},
+	examples: [parts, ribbons, meteor, gpu, shield, portal, glaive, renderer, lights]
+}

package/starters/examples/src/examples/custom-fx/lights.look.ts

@@ -0,0 +1,144 @@
+/**
+ * Lights that move, on the client's side: lights of the world added in code (`client.lights.add(LightDef)`), on
+ * always (`when: 'always'`; a lamp's are at night alone), each with a handle to move it and change it
+ * (`handle.set({ x, y, z, color })`) and take it away. A `halo` draws the light itself as a glowing ball; a `spot`
+ * shines one way. The quality's `lights` says how many are drawn at once
+ */
+import type { GameClientApi, LightHandle, Rgb } from '@v12-engine/client'
+import { type ExampleLook, select, slider, toggle } from '../../shell/look'
+import { UNIT } from '../common/units'
+import { aim, everyFrame, idsOf, where } from '../fx/stage'
+import { LIGHTS_AT } from './lights'
+
+const PALETTES: Record<string, Rgb[]> = {
+	Spirits: [
+		[0.4, 0.8, 1],
+		[0.7, 0.5, 1],
+		[0.4, 1, 0.75]
+	],
+	Embers: [
+		[1, 0.55, 0.15],
+		[1, 0.8, 0.3],
+		[1, 0.3, 0.1]
+	],
+	Rainbow: [
+		[1, 0.25, 0.25],
+		[1, 0.8, 0.2],
+		[0.3, 1, 0.4],
+		[0.3, 0.6, 1],
+		[0.8, 0.3, 1]
+	]
+}
+
+const chosen = { count: 6, palette: 'Spirits', flicker: false }
+let wisps: LightHandle[] = []
+let lantern: LightHandle | undefined
+let beam: LightHandle | undefined
+
+/** The wisps made again, as many as the card says, in its colours */
+function makeWisps(client: GameClientApi): void {
+	for (const wisp of wisps) wisp.dispose()
+	const colors = PALETTES[chosen.palette]!
+	wisps = Array.from({ length: chosen.count }, (_, i) =>
+		client.lights.add({
+			name: `wisp ${i + 1}`,
+			...LIGHTS_AT,
+			y: 1.5,
+			color: colors[i % colors.length],
+			intensity: 1.6,
+			range: 5,
+			halo: 0.35,
+			when: 'always',
+			...(chosen.flicker && { flicker: { amount: 0.4, speed: 2 } })
+		})
+	)
+}
+
+export const lightsLook: ExampleLook = {
+	controls: [
+		slider(
+			'Wisps',
+			{ min: 0, max: 16, step: 1, value: chosen.count },
+			(client, count) => {
+				chosen.count = count
+				makeWisps(client)
+			},
+			'How many wisps circle the mage, each a light of its own on the ground under it'
+		),
+		select(
+			'Colours',
+			Object.keys(PALETTES),
+			chosen.palette,
+			(client, name) => {
+				chosen.palette = name
+				makeWisps(client)
+			},
+			'The colours the wisps take, in turn'
+		),
+		toggle(
+			'Flicker',
+			false,
+			(client, on) => {
+				chosen.flicker = on
+				makeWisps(client)
+			},
+			'The wisps waver in brightness, as a flame does'
+		),
+		toggle('Lighthouse beam', true, (_client, on) => beam?.set({ on }), 'The spot light sweeping round the field, on or off')
+	],
+	ready: (client) => {
+		Object.assign(chosen, { count: 6, palette: 'Spirits', flicker: false })
+		aim(client, LIGHTS_AT, 22, 0.75)
+		makeWisps(client)
+		lantern = client.lights.add({
+			name: 'lantern',
+			...LIGHTS_AT,
+			y: 1.6,
+			color: [1, 0.75, 0.4],
+			intensity: 1.8,
+			range: 7,
+			halo: 0.18,
+			when: 'always',
+			flicker: 0.15
+		})
+		beam = client.lights.add({
+			name: 'beam',
+			x: LIGHTS_AT.x - 9,
+			y: 6,
+			z: LIGHTS_AT.z - 7,
+			kind: 'spot',
+			angle: 0.35,
+			focus: 4,
+			color: [1, 0.95, 0.8],
+			intensity: 3,
+			range: 30,
+			when: 'always'
+		})
+		let time = 0
+		const stop = everyFrame(client, (dt) => {
+			time += dt
+			// the wisps on circles of their own about the mage, rising and falling
+			const center = where(client, idsOf(client, UNIT.mage)[0] ?? -1) ?? LIGHTS_AT
+			wisps.forEach((wisp, i) => {
+				const turn = time * (0.5 + (i % 3) * 0.15) + (i / wisps.length) * Math.PI * 2
+				const radius = 2.2 + (i % 2) * 1.4
+				wisp.set({ x: center.x + Math.cos(turn) * radius, z: center.z + Math.sin(turn) * radius, y: 1.3 + Math.sin(time * 2 + i) * 0.5 })
+			})
+			// the lantern in the footman's hand, wherever he walks
+			const [footman] = idsOf(client, UNIT.footman)
+			const hand = footman !== undefined ? client.renderer.kit.point(footman, 'handslot.l') : undefined
+			const feet = footman !== undefined ? where(client, footman) : undefined
+			if (hand) lantern?.set({ x: hand.x, y: hand.y, z: hand.z })
+			else if (feet) lantern?.set({ x: feet.x, y: 1.4, z: feet.z })
+			// the beam sweeping round over the field
+			const sweep = time * 0.6
+			beam?.set({ direction: [Math.cos(sweep), -0.45, Math.sin(sweep)] })
+		})
+		return () => {
+			stop()
+			for (const light of [...wisps, lantern, beam]) light?.dispose()
+			wisps = []
+			lantern = beam = undefined
+		}
+	}
+}

package/starters/examples/src/examples/custom-fx/lights.ts

@@ -0,0 +1,25 @@
+/**
+ * Lights that move, on the rules' side: a night, a mage in the middle, a footman walking his round. The lights are
+ * the screen's (`./lights.look.ts`)
+ */
+import { PLAYER, UNIT } from '../common/units'
+import type { ExampleDef } from '../define'
+
+export const LIGHTS_AT = { x: 24, z: 24 }
+
+export const lights: ExampleDef = {
+	id: 'custom-fx-lights',
+	category: 'custom-fx',
+	title: 'Lights that move',
+	summary:
+		"Lights added in code (`client.lights.add`), moved every frame: wisps circling the mage, each a glowing ball (`halo`) lighting the ground under it; a lantern carried by a walking footman; a beam sweeping round like a lighthouse's. Change how many wisps, their colours, the flicker.",
+	tags: ['lights', 'dynamic lights', 'point light', 'spot light', 'halo', 'night', 'WorldLights', 'LightDef'],
+	environment: 'night',
+	start: (world) => {
+		world.spawn(UNIT.mage, { at: LIGHTS_AT, owner: PLAYER })
+		world
+			.spawn(UNIT.footman, { at: { x: LIGHTS_AT.x - 8, z: LIGHTS_AT.z + 5 }, owner: PLAYER })
+			.order('patrol', { x: LIGHTS_AT.x + 8, z: LIGHTS_AT.z + 5 })
+	},
+	source: ['examples/custom-fx/lights.ts', 'examples/custom-fx/lights.look.ts']
+}

package/starters/examples/src/examples/custom-fx/looks.ts

@@ -0,0 +1,36 @@
+/**
+ * The examples of effects of your own, on the client's side (`CategoryLooks`): each example's look and controls by its
+ * id, and what they add to the game's look: their effects (`fx.defs`, every name starting `customFx.`) and the looks of
+ * the units they add
+ */
+import type { CategoryLooks } from '../../shell/look'
+import { GLAIVER } from './glaive'
+import { glaiveLook, glaiverLook } from './glaive.look'
+import { gpuFx, gpuLook } from './gpu.look'
+import { lightsLook } from './lights.look'
+import { meteorFx, meteorLook } from './meteor.look'
+import { partsFx, partsLook } from './parts.look'
+import { portalFx, portalLook } from './portal.look'
+import { rendererLook } from './renderer.look'
+import { ribbonsFx, ribbonsLook } from './ribbons.look'
+import { WARDEN } from './shield'
+import { shieldLook, wardenLook } from './shield.look'
+
+export const category: CategoryLooks = {
+	view: (view) => ({
+		...view,
+		units: { ...view.units, looks: { ...view.units.looks, [WARDEN]: wardenLook, [GLAIVER]: glaiverLook } },
+		fx: { ...view.fx, defs: { ...view.fx?.defs, ...partsFx, ...ribbonsFx, ...meteorFx, ...gpuFx, ...portalFx } }
+	}),
+	looks: {
+		'custom-fx-parts': partsLook,
+		'custom-fx-ribbons': ribbonsLook,
+		'custom-fx-meteor': meteorLook,
+		'custom-fx-gpu-particles': gpuLook,
+		'custom-fx-shield': shieldLook,
+		'custom-fx-portal': portalLook,
+		'custom-fx-glaive': glaiveLook,
+		'custom-fx-renderer': rendererLook,
+		'custom-fx-lights': lightsLook
+	}
+}

package/starters/examples/src/examples/custom-fx/meteor.look.ts

@@ -0,0 +1,133 @@
+/**
+ * A meteor, on the client's side: `customFx.meteor`, its fall and its landing in one timeline. The fall is parts on
+ * a `path` (a function of the part's age: where it is, from where the effect plays), so the flames, the glowing rock,
+ * the ribbon behind it and its light come down together. At `FALL` seconds the landing: ready-made effects as parts
+ * (`explosion`, `impact-ring`, `burning-ground`), rocks flung that each trail smoke all their life (`sub` on `birth`),
+ * a shake and a crack laid on the ground
+ */
+import type { FxDef, FxPath, GameClientApi } from '@v12-engine/client'
+import { button, type ExampleLook, slider } from '../../shell/look'
+import { aim } from '../fx/stage'
+import { METEOR_AT } from './meteor'
+
+/** Seconds it falls */
+const FALL = 1.1
+
+/** Down from high up and off to one side, faster as it comes: where it is, from where it lands */
+const fall: FxPath = (age, _life, p) => {
+	const t = Math.min(age / FALL, 1)
+	const left = 1 - t * t
+	const size = Number(p.size)
+	return [-9 * left * size, 0.4 + 26 * left * size, -6 * left * size]
+}
+
+const meteor: FxDef = {
+	params: { size: 1 },
+	knobs: { size: { min: 0.4, max: 2.5, step: 0.1, about: 'How big the rock, and all it does' } },
+	parts: [
+		// the fall: a white-hot rock, flames streaming off it, a ribbon of fire, its light
+		{
+			for: FALL,
+			path: fall,
+			particles: { rate: 40, lifetime: 0.12, size: (p) => 1.6 * Number(p.size), color: ['#ffffff', '#ffd27a'], texture: 'flare', local: true }
+		},
+		{
+			for: FALL,
+			path: fall,
+			particles: {
+				rate: 260,
+				shape: { type: 'sphere', radius: 0.4 },
+				speed: [0.5, 2],
+				lifetime: [0.3, 0.7],
+				size: (p) => [
+					[0, 1.2 * Number(p.size)],
+					[1, 0.2]
+				],
+				color: [
+					[0, '#fff0b0'],
+					[0.4, '#ff7a1a'],
+					[1, '#3a1a0a']
+				],
+				texture: 'puff'
+			}
+		},
+		{ for: FALL, path: fall, trail: { color: '#ff8a2a', width: (p) => 0.9 * Number(p.size), time: 0.4, soft: true, blend: 'add', taper: true } },
+		{ for: FALL, path: fall, light: { color: '#ffa040', intensity: 4, range: 14 } },
+		// the landing
+		{ at: FALL, fx: 'explosion', params: (p) => ({ size: 1.6 * Number(p.size), shake: 0 }) },
+		{ at: FALL, fx: 'impact-ring', params: (p) => ({ size: 1.5 * Number(p.size), shake: 0 }) },
+		{ at: FALL, shake: (p) => ({ strength: 0.9 * Number(p.size), time: 0.6 }) },
+		{ at: FALL, decal: { texture: 'crack', size: (p) => 6 * Number(p.size), time: 40, color: '#1a120c' } },
+		// rocks flung out on high arcs, each trailing smoke for as long as it flies
+		{
+			at: FALL,
+			particles: {
+				bursts: [{ at: 0, count: 26 }],
+				shape: 'hemisphere',
+				spread: 0.7,
+				speed: (p) => [7 * Number(p.size), 13 * Number(p.size)],
+				gravity: 16,
+				lifetime: [0.8, 1.4],
+				size: [0.35, 0.25],
+				color: '#ff9a4a',
+				texture: 'dot',
+				sub: [
+					{
+						on: 'birth',
+						particles: {
+							rate: 30,
+							lifetime: [0.4, 0.8],
+							size: [0.3, 1],
+							color: ['#5a4a40', '#2a2420'],
+							alpha: [0.7, 0],
+							texture: 'puff',
+							blend: 'alpha'
+						}
+					}
+				]
+			}
+		},
+		{ at: FALL + 0.1, for: 6, fx: 'burning-ground', params: (p) => ({ radius: 1.6 * Number(p.size), scorch: false }) }
+	]
+}
+
+/** The meteor of this example, taken into the game's view */
+export const meteorFx: Record<string, FxDef> = { 'customFx.meteor': meteor }
+
+let size = 1
+let shower: number[] = []
+
+/** Calls one down a little way from the middle, or (`exact`) on it */
+const call = (client: GameClientApi, exact = false) =>
+	client.fx.play('customFx.meteor', {
+		at: exact ? METEOR_AT : { x: METEOR_AT.x + (Math.random() - 0.5) * 9, z: METEOR_AT.z + (Math.random() - 0.5) * 7 },
+		params: { size: exact ? size : size * (0.5 + Math.random() * 0.6) }
+	})
+
+export const meteorLook: ExampleLook = {
+	controls: [
+		button('Call a meteor', (client) => call(client, true), 'One meteor falls on the middle of the field, at the size below'),
+		button(
+			'A shower',
+			(client) => {
+				shower = Array.from({ length: 7 }, (_, i) => window.setTimeout(() => call(client), i * 450 + Math.random() * 200))
+			},
+			'Seven meteors, one after another, at spots round the middle'
+		),
+		slider(
+			'Size',
+			{ min: 0.4, max: 2.5, step: 0.1, value: 1 },
+			(_client, value) => (size = value),
+			'How big the next meteor is, its blast and crack too (the knob `size`): call one to see it'
+		)
+	],
+	ready: (client) => {
+		size = 1
+		aim(client, METEOR_AT, 26, 0.55)
+		const first = window.setTimeout(() => call(client, true), 500)
+		return () => {
+			window.clearTimeout(first)
+			for (const one of shower) window.clearTimeout(one)
+		}
+	}
+}