@v12-engine/create 0.1.0 → 0.4.0

package/starters/empty/src/view.ts

@@ -0,0 +1,82 @@
+/**
+ * How the game looks and sounds (`GameView`): the client's, fetched as the page first plays the game
+ * (`game.view(() => import('./view'))` in `src/game.ts`): nothing of it is in what a server, a test or a worker reads
+ */
+import { type GameView, hotView, presetView } from '@v12-engine/client'
+import type { Unit } from './rules'
+
+/**
+ * The look: a unit type is drawn from `parts` (boxes, cylinders, cones, spheres, pyramids) until it has a model, a
+ * `.glb` in `public/models/` named by `model` (`{ src: 'scout.glb', scale: 1 }`). `color: 'team'` is its side's colour
+// @if assets
+ *
+ * The shared art has models to start with: `import { characters } from '@v12-engine/assets'` and
+ * `model: { src: characters.models.knight, scale: 0.6 }` (played with its own clips)
+// @end
+ *
+ * `presetView` lays in the client's ready-made looks, which it draws none of by itself: the rain and snow (its map has
+ * some), the abilities' styles, a building's rally flag, the glow over a unit with a buff and the looks of the engine's
+ * tiles, each under what the view says of its own
+ */
+export const view: GameView<Unit> = presetView({
+	world: {
+		// trees and scenery in front of the player's own units faded out (`seeThrough`): who for, how, how much
+		seeThrough: {},
+		/**
+		 * Looks by name to start a map from: the map editor's Look panel puts one on a map (Preset), a scene plays a map with
+		 * one (`gameScene({ environment: 'dusk' })`), the rules change to one (`world.setEnvironment(view.world.environments.storm,
+		 * { over: 20 })`). Each is a `MapEnvironment`: sky, light, mist, wind, clouds, weather, water
+		 */
+		environments: {
+			dusk: {
+				sky: [0.55, 0.42, 0.5],
+				clouds: { cover: 0.4, color: [1, 0.8, 0.7] },
+				light: { sunUp: 12, sunAround: 250, sunColor: [1, 0.62, 0.42], sun: 1, ambient: 0.45, ambientColor: [0.8, 0.7, 0.9] },
+				fog: { start: 60, end: 200 },
+				mist: { ground: { base: 0, top: 2, density: 0.25 } }
+			},
+			storm: {
+				sky: [0.3, 0.33, 0.38],
+				clouds: { cover: 0.9, color: [0.55, 0.57, 0.6] },
+				cloudLayer: { height: 18, cover: 0.7, opacity: 0.55, shadows: 0.5 },
+				light: { sun: 0.7, ambient: 0.5 },
+				wind: { around: 70, strength: 0.8, gusts: 0.6 },
+				weather: { kind: 'rain', amount: 0.9, splashes: 0.6 },
+				fog: { start: 40, end: 140 }
+			}
+		}
+	},
+	/*
+	 * How hits feel (`feel`): the struck flashes and flinches, a pause on a critical strike or a kill, a streak behind a
+	 * melee swing, a shake for what is big. On as it comes; each piece takes its own values or `false`, and `feel: false`
+	 * turns it all off: `feel: { hitStop: false, trails: { color: [1, 0.9, 0.6] } }`
+	 */
+	units: {
+		looks: {
+			scout: {
+				// once it has a model with several attack clips, they take turns, never the same twice running:
+				// `attacks: [{ clip: ['Attack_1', 'Attack_2'], order: 'random', crit: 'Attack_Big' }]` (`UnitLook.attacks`)
+				height: 1.4,
+				shapes: [
+					{ shape: 'cylinder', size: [0.6, 1, 0.6], offset: [0, 0.5, 0], color: 'team' },
+					{ shape: 'sphere', size: [0.45, 0.45, 0.45], offset: [0, 1.2, 0], color: [0.9, 0.8, 0.65] }
+				]
+			}
+		}
+	},
+	ground: {
+		/**
+		 * How each tile of the ground (`tiles` in src/rules.ts) looks: a colour (the minimap's, and the ground's until its picture comes)
+		 * and a picture repeated over the ground. A picture is a file in `public/textures/` by its path there, or made in
+		 * code with no file: `pattern: 'grass'` (grass, gravel, rock, cobbles, planks, ice, lava… fifteen), with a `recipe` (a second
+		 * colour, specks, how strong, and the pattern's own parameters: `params: { seams: 1.2 }`), or a pattern of the
+		 * game's own (`patterns: { cobbles: definePattern({ name, params, shade }) }` on the view, then `pattern: 'cobbles'`;
+		 * the map editor offers it with a slider for each parameter)
+		 */
+		// the road as gravel of a colour of its own, over the client's looks of the engine's tiles (made in code, no files)
+		tiles: { road: { color: [0.55, 0.52, 0.47], pattern: 'gravel' } }
+	}
+})
+
+// saved while it runs (npm run dev): the game and the editor open take its new look, with no new page
+if (import.meta.hot) import.meta.hot.accept((module) => hotView(import.meta.hot, 'my-game', view, module?.view))

package/starters/examples/README.md

@@ -0,0 +1,83 @@
+# My game
+
+What V12 can do, a small scene each, as [three.js's examples](https://threejs.org/examples/) are: the list down the left, searched and by category, and the example on the right, playing, with a card of its controls over it. Each is a few dozen lines to read, copy into a game of your own, and change.
+
+| To                     | Run                                                                  |
+| ---------------------- | -------------------------------------------------------------------- |
+| See the examples       | `npm run dev`, and open the page it says: the list first             |
+| Open one straight      | its id after the address: `/?mechanics-battle`                       |
+<!-- @if editor -->
+| Make maps              | `npm run dev`, and open `/?editor`: Save writes them into `src/maps` |
+| Check the maps         | `npm run map check`: every map in `src/maps` against the game's rules |
+<!-- @end -->
+<!-- @if server -->
+<!-- @if !rooms -->
+| Play it on a server    | `npm run server`, beside `npm run dev`, and open `/?server`          |
+<!-- @end -->
+<!-- @if rooms -->
+| Play it online         | `npm run server`, beside `npm run dev`, and open `/?find-game`       |
+<!-- @end -->
+<!-- @end -->
+<!-- @if tests -->
+| Test the examples      | `npm test`: each one's world made, started and run with no page      |
+<!-- @end -->
+| Check the types        | `npm run typecheck`                                                  |
+| Build the page to host | `npm run build`, into `dist/`                                        |
+<!-- @if desktop -->
+| Play it as an app      | `npm run app`: the page in a window of its own (Electron, fetched the first time) |
+| Make the app to hand out | `npm run package`, into `out/`                                     |
+<!-- @end -->
+
+## The categories
+
+| Category              | Folder                              |
+| --------------------- | ----------------------------------- |
+| Core mechanics        | `src/examples/mechanics/`           |
+| Abilities             | `src/examples/abilities/`           |
+| Like a MOBA           | `src/examples/moba/`                |
+| Like an RTS           | `src/examples/rts/`                 |
+| Effects               | `src/examples/fx/`                  |
+| Your own effects      | `src/examples/custom-fx/`           |
+| Animation             | `src/examples/animation/`           |
+| Your own animation    | `src/examples/custom-animation/`    |
+| Destruction           | `src/examples/destruction/`         |
+| Construction          | `src/examples/construction/`        |
+| Nature and weather    | `src/examples/nature/`              |
+| Post-processing       | `src/examples/post/`                |
+| A changing map        | `src/examples/dynamic-map/`         |
+| Cinematics            | `src/examples/cinematics/`          |
+| Dialogue              | `src/examples/dialogs/`             |
+| Interfaces            | `src/examples/gui/`                 |
+| Showcase              | `src/examples/showcase/`            |
+| Performance           | `src/examples/performance/`         |
+
+## An example of your own
+
+1. **Its rules.** In a category's `index.ts`, an entry in its `examples` (`ExampleDef`, `src/examples/define.ts`): an `id` starting with the category's (`fx-my-burst`), a `title`, a `summary`, and what it plays: a `map` (a flat field when left out, `exampleField`) and a `start` that puts units, buildings and scenery in the world. Units, abilities and commands it needs go in the category's `rules(game)`. The engine alone here (`@v12-engine/engine`): the server and the tests read it.
+2. **Its look and controls.** In the category's `looks.ts`, by the example's id (`ExampleLook`, `src/shell/look.ts`): `view` changes the game's look for it, `controls` are the card's buttons, switches, sliders and choices (`button`, `toggle`, `slider`, `select`, `readout`), each run with the client, and `ready(client)` runs once it is drawn (the camera put where it should look). A control that changes the world sends a command of the category's (`client.session.send(command.make({ … }))`), as `src/examples/mechanics` does.
+3. **A category of your own.** A folder with an `index.ts` and a `looks.ts`, its id in `CATEGORIES` (`src/examples/define.ts`), and its two files in `src/examples/catalog.ts` and `src/examples/looks.ts`.
+
+## What is where
+
+- `src/examples/<category>/index.ts`: a category's examples, their maps and starts, and the units, abilities and commands they add (`ExampleCategory`). The engine alone, so the page, the server, the editor and the tests play the same game
+- `src/examples/<category>/looks.ts`: their looks and controls (`CategoryLooks`), fetched with the game's look, never with the list
+- `src/examples/common/`: the units the examples share (a footman, an archer, a mage, a knight who is a hero, a training dummy) and their looks
+- `src/examples/define.ts`: what an example is, the categories, and the field an example plays when it says no map
+- `src/rules.ts`: the one game every example plays (`createGame`), each category's rules registered on it
+- `src/game.ts`: the game whole, its look given (`game.view(() => import('./view'))`)
+- `src/view.ts`: how it looks (`GameView`): the shared units', and each category's over them
+- `src/shell/`: the list and the card (plain HTML: the list's page carries nothing of the client), and the scenes: the list's own page and one for each example
+- `src/main.ts`: the page, the examples' scenes beside the usual ones `appScenes` makes (the start screen is `/?home`)
+<!-- @if editor -->
+- `src/editor.ts`: the map editor's own settings, for `appScenes`
+<!-- @end -->
+<!-- @if server -->
+- `server.ts`: a server of the game, on its field
+<!-- @end -->
+<!-- @if tests -->
+- `tests/`: every example's world made, started and run for five seconds with no page
+<!-- @end -->
+<!-- @if desktop -->
+- `electron/`: the shell around the page, Electron's main process; `src/shell.ts` is all the page asks of it and `src/desktop.ts` what it does with that
+<!-- @end -->
+- `@v12-engine/assets`: the shared models the examples are drawn with (adventurers with their clips, buildings, trees and rocks, props, weapons), served by `assetsPackage()` in `vite.config.ts`. Whose each file is: its group's `CREDITS.md` in `node_modules/@v12-engine/assets/groups/`

package/starters/examples/layers/tests/tests/examples.test.ts

@@ -0,0 +1,30 @@
+/** The examples, tested with no page: each one's world made and stepped here as it is in a page (`@v12-engine/engine/testing`) */
+import { createWorldFromMap } from '@v12-engine/engine'
+import { run } from '@v12-engine/engine/testing'
+import { describe, expect, it } from 'vitest'
+import { examples, game } from '../src/game'
+import { CATEGORIES, exampleField } from '../src/examples/define'
+
+describe('the examples', () => {
+	it('fits together: every id it names is its own, every effect has a handler (check)', async () => {
+		expect((await game.check()).filter((problem) => problem.level === 'error')).toEqual([])
+	})
+
+	it('has an id of its own for each example, starting with its category', () => {
+		const ids = examples.map((each) => each.id)
+		expect(new Set(ids).size).toBe(ids.length)
+		for (const each of examples) {
+			expect(CATEGORIES.some((category) => category.id === each.category)).toBe(true)
+			expect(each.id.startsWith(`${each.category}-`), each.id).toBe(true)
+		}
+	})
+
+	for (const example of examples)
+		it(`plays ${example.id}: its world made from its map, started and run for five seconds`, async () => {
+			const map = await (example.map?.() ?? exampleField())
+			const world = await createWorldFromMap({ map, rules: game.toRules(), seed: 1 })
+			await example.start?.(world, { map, player: map.players[0]?.id })
+			run(world, 5)
+			world.dispose()
+		})
+})

package/starters/examples/package.json

@@ -0,0 +1,5 @@
+{
+	"dependencies": {
+		"solid-js": "^1.9.17"
+	}
+}

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

@@ -0,0 +1,165 @@
+/**
+ * Areas and shapes: where an effect lands and what it covers. A cone, a ring, a cross and a crescent; ground that burns
+ * a while, a wall of fire, an edge that stuns who crosses it; a blast that falls a moment later; a channel; a ray aimed
+ * along two points; a zone the caster carries
+ */
+import type { AbilityDef, BuffDef } from '@v12-engine/engine'
+import { exampleField } from '../define'
+import type { Family } from './family'
+import { caster, lineUp } from './kit'
+
+const buffs: BuffDef[] = [{ id: 'abilitiesHorizonStun', name: 'Stunned', harmful: true, duration: 1.2, stun: true }]
+
+const abilities: AbilityDef[] = [
+	{
+		// a quarter-circle from the caster toward the spot: drawn on the ground while aiming, flashed as it goes off
+		id: 'abilitiesBreath',
+		name: 'Breath of Fire',
+		description: 'A cone of fire, 7 cells long',
+		hotkey: 'Q',
+		target: 'point',
+		range: 7,
+		cooldown: 1,
+		castTime: 0.3,
+		effects: [{ type: 'damage', amount: 90, shape: 'cone', length: 7, angle: Math.PI / 2 }]
+	},
+	{
+		// the outer ring hurts, the middle does not
+		id: 'abilitiesDecimate',
+		name: 'Decimate',
+		description: 'A ring around the caster: the outer 1.5 cells of a 5-cell circle',
+		hotkey: 'W',
+		target: 'none',
+		cooldown: 1,
+		castTime: 0.4,
+		effects: [{ type: 'damage', amount: 100, shape: 'ring', radius: 5, width: 1.5 }]
+	},
+	{
+		// an X at the spot, 45° off the aim
+		id: 'abilitiesCross',
+		name: 'Death from Below',
+		description: 'An X of blades at the spot',
+		hotkey: 'E',
+		target: 'point',
+		range: 9,
+		cooldown: 1,
+		castTime: 0.4,
+		effects: [{ type: 'damage', amount: 110, shape: 'cross', length: 7, width: 0.7 }]
+	},
+	{
+		// a crescent round the caster, centred on the aim
+		id: 'abilitiesCrescent',
+		name: 'Crescent Sweep',
+		description: 'A crescent swept round in front of the caster',
+		hotkey: 'R',
+		target: 'direction',
+		range: 6,
+		cooldown: 1,
+		castTime: 0.25,
+		effects: [{ type: 'damage', amount: 80, shape: 'arc', radius: 7, angle: Math.PI / 1.5, width: 2 }]
+	},
+	{
+		// a zone: its effects run on those inside four times a second, for its duration
+		id: 'abilitiesFlameStrike',
+		name: 'Flame Strike',
+		description: 'Burns the ground for 5 seconds',
+		hotkey: 'T',
+		target: 'point',
+		range: 10,
+		cooldown: 1,
+		effects: [{ type: 'zone', radius: 2.5, duration: 5, effects: [{ type: 'damage', amount: 8 }] }]
+	},
+	{
+		// a shaped zone keeps the way it was cast
+		id: 'abilitiesFireWall',
+		name: 'Wall of Fire',
+		description: 'A wall of fire across the way, for 6 seconds',
+		hotkey: 'D',
+		target: 'point',
+		range: 10,
+		cooldown: 1,
+		effects: [{ type: 'zone', duration: 6, shape: 'rect', length: 7, width: 0.5, effects: [{ type: 'damage', amount: 10 }] }]
+	},
+	{
+		// whoever crosses its edge, in or out, is stunned
+		id: 'abilitiesEventHorizon',
+		name: 'Event Horizon',
+		description: 'A ring that stuns whoever crosses its edge, for 4 seconds',
+		hotkey: 'F',
+		target: 'point',
+		range: 10,
+		cooldown: 1,
+		effects: [{ type: 'zone', duration: 4, radius: 3, edge: [{ type: 'buff', buff: 'abilitiesHorizonStun' }] }]
+	},
+	{
+		// lands a moment later where it was aimed: the screen marks the spot until then
+		id: 'abilitiesMeteor',
+		name: 'Meteor',
+		description: 'A star falls on the spot 1.2 seconds later',
+		hotkey: 'G',
+		target: 'point',
+		range: 10,
+		cooldown: 1,
+		effects: [{ type: 'after', delay: 1.2, effects: [{ type: 'damage', amount: 220, radius: 3 }] }]
+	},
+	{
+		// a channel: the caster stands and keeps it up, its effects every second; another order breaks it
+		id: 'abilitiesBlizzard',
+		name: 'Blizzard',
+		description: 'Ice falls on the spot every second for 5 seconds, while the caster keeps it up',
+		hotkey: 'Z',
+		target: 'point',
+		range: 10,
+		cooldown: 1,
+		aim: { shape: 'circle', radius: 2.5 },
+		effects: [],
+		channel: { duration: 5, every: 1, effects: [{ type: 'damage', amount: 40, radius: 2.5 }] }
+	},
+	{
+		// two points: where it starts, then which way
+		id: 'abilitiesDeathRay',
+		name: 'Death Ray',
+		description: 'Aimed by two points, where it starts and which way: a ray across the line of enemies',
+		hotkey: 'X',
+		target: 'vector',
+		range: 10,
+		cooldown: 1,
+		effects: [{ type: 'missile', speed: 20, distance: 8, radius: 0.8, effects: [{ type: 'damage', amount: 90 }] }]
+	},
+	{
+		// carried: it moves and turns with the caster
+		id: 'abilitiesFlamespitter',
+		name: 'Flamespitter',
+		description: 'A cone of fire in front of the caster for 3 seconds, wherever it walks',
+		hotkey: 'C',
+		target: 'none',
+		cooldown: 1,
+		effects: [
+			{ type: 'zone', duration: 3, follow: 'caster', effects: [{ type: 'damage', amount: 6, shape: 'cone', length: 5, angle: Math.PI / 2.5 }] }
+		]
+	}
+]
+
+export const areas: Family = {
+	abilities,
+	buffs,
+	units: [
+		caster(
+			'abilitiesShaper',
+			'Area mage',
+			abilities.map((each) => each.id)
+		)
+	],
+	example: {
+		id: 'abilities-areas',
+		category: 'abilities',
+		title: 'Areas and shapes',
+		summary:
+			'Cones, rings, crosses and crescents, burning ground, a wall of fire, a stunning edge, a falling star, a channel, a ray aimed by two points and a zone the caster carries. Each shows its shape on the ground as it goes off.',
+		tags: ['area', 'cone', 'line', 'ring', 'cross', 'arc', 'zone', 'channel', 'vector', 'delayed', 'telegraph'],
+		source: ['examples/abilities/areas.ts', 'examples/abilities/kit.ts'],
+		map: () => exampleField({ name: 'Areas', players: 2 }),
+		// the sparring footmen are the damage example's (`./damage.ts`)
+		start: (world) => lineUp(world, 'abilitiesShaper', 'abilitiesTarget', 5)
+	}
+}

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

@@ -0,0 +1,30 @@
+/** How the areas example looks, and its card: a button for each shape (`./areas.ts`) */
+import { sharedLooks } from '../common/looks'
+import { areas } from './areas'
+import type { FamilyLooks } from './looks'
+import { castButton, look, readyOn, resetButton } from './lookKit'
+
+export const areasLooks: FamilyLooks = {
+	units: { abilitiesShaper: sharedLooks.mage },
+	abilities: {
+		abilitiesBreath: look([1, 0.45, 0.1], 'burst'),
+		abilitiesDecimate: look([0.85, 0.15, 0.1], 'slam'),
+		abilitiesCross: look([0.3, 0.8, 0.75], 'smash'),
+		abilitiesCrescent: look([0.75, 0.85, 1], 'slam'),
+		// the fall a mark, then the zone burning for its life
+		abilitiesFlameStrike: look([1, 0.5, 0.1], 'mark', { options: { column: true, burst: 30 } }),
+		abilitiesFireWall: look([1, 0.35, 0.05], 'ring'),
+		abilitiesEventHorizon: look([0.6, 0.3, 1], 'ring'),
+		abilitiesMeteor: look([1, 0.55, 0.2], 'mark', { options: { lasts: 1.2, falls: 18, fill: true, burst: 40, sparks: 20 } }),
+		abilitiesBlizzard: look([0.7, 0.9, 1], 'barrage'),
+		abilitiesDeathRay: look([1, 0.3, 0.3], 'missile', { options: { shape: 'hawk' } }),
+		abilitiesFlamespitter: look([1, 0.5, 0.1], 'ring'),
+		abilitiesHorizonStun: look([0.6, 0.3, 1], undefined, { aura: 'glow', options: { shape: 'ring', at: 'head' } })
+	},
+	examples: {
+		'abilities-areas': {
+			ready: (client) => readyOn(client, 'abilitiesShaper'),
+			controls: [...areas.abilities.map((ability) => castButton(ability)), resetButton('abilities-areas')]
+		}
+	}
+}