@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/testing.js

@@ -0,0 +1,822 @@
+import { Et as Terrain, Qt as createMap, Ud as dist } from "./debugCommands-CzjrSm66.js";
+import { i as createWorld, o as loadWorld } from "./game-DiJEN-Ks.js";
+import { ct as saveWorld, it as encodeSave, rt as decodeSave } from "./coreComponents-syuh2fPG.js";
+import { a as worldHash, i as worldFingerprint, n as firstDifference, o as worldState, s as withHeroes, t as checkDeterminism } from "./determinism-BCymQwiE.js";
+import { t as LocalSession } from "./local-Dkovq42k.js";
+import { S as checkBrain, t as Brain, wt as explainGoal } from "./brain-BvVdUhX8.js";
+import { i as winRates, n as playGame, r as simulate, t as defineSimulation } from "./simulate-oXBiw1Ff.js";
+//#region src/fixture.ts
+var worker = {
+	id: "worker",
+	name: "Worker",
+	kind: "unit",
+	radius: .4,
+	stats: {
+		health: 100,
+		attackDamage: 5,
+		attackSpeed: 1,
+		attackRange: .5,
+		moveSpeed: 4
+	},
+	sight: 8,
+	attacks: [{
+		damagePoint: .3,
+		acquisitionRange: 0,
+		targets: ["unit", "building"]
+	}],
+	cost: { gold: 50 },
+	supply: 1,
+	buildTime: 10,
+	harvester: {
+		capacity: 10,
+		gatherTime: 1
+	},
+	builds: [
+		"hall",
+		"supply",
+		"barracks",
+		"tower",
+		"altar"
+	]
+};
+var soldier = {
+	id: "soldier",
+	name: "Soldier",
+	kind: "unit",
+	radius: .45,
+	stats: {
+		health: 200,
+		attackDamage: 10,
+		attackSpeed: 1,
+		attackRange: .5,
+		armor: 10,
+		moveSpeed: 4
+	},
+	sight: 10,
+	attacks: [{
+		damagePoint: .3,
+		acquisitionRange: 8
+	}],
+	cost: { gold: 100 },
+	supply: 2,
+	buildTime: 10,
+	abilities: ["guard"]
+};
+var archer = {
+	id: "archer",
+	name: "Archer",
+	kind: "unit",
+	radius: .45,
+	stats: {
+		health: 100,
+		attackDamage: 10,
+		attackSpeed: 1,
+		attackRange: 6,
+		moveSpeed: 4
+	},
+	sight: 10,
+	attacks: [{
+		damagePoint: .3,
+		acquisitionRange: 8,
+		projectileSpeed: 20,
+		targets: ["ground", "air"]
+	}],
+	cost: {
+		gold: 100,
+		lumber: 20
+	},
+	supply: 2,
+	buildTime: 10
+};
+var hero = {
+	id: "hero",
+	name: "Hero",
+	kind: "unit",
+	radius: .5,
+	stats: {
+		health: 300,
+		mana: 100,
+		manaRegen: 1,
+		attackDamage: 20,
+		attackSpeed: 1,
+		attackRange: .5,
+		armor: 10,
+		moveSpeed: 4
+	},
+	sight: 12,
+	attacks: [{
+		damagePoint: .3,
+		acquisitionRange: 8
+	}],
+	hero: {
+		growth: { stats: {
+			health: 20,
+			mana: 10,
+			attackDamage: 2
+		} },
+		learns: ["heal", "guard"]
+	},
+	inventory: 6,
+	cost: {
+		gold: 400,
+		lumber: 100
+	},
+	supply: 5,
+	buildTime: 40
+};
+var creep = {
+	id: "creep",
+	name: "Creep",
+	kind: "unit",
+	radius: .45,
+	stats: {
+		health: 200,
+		attackDamage: 10,
+		attackSpeed: 1,
+		attackRange: .5,
+		moveSpeed: 3
+	},
+	sight: 8,
+	attacks: [{
+		damagePoint: .3,
+		acquisitionRange: 5
+	}],
+	level: 1,
+	bounty: [10, 10],
+	xp: 20
+};
+var hall = {
+	id: "hall",
+	name: "Hall",
+	kind: "building",
+	radius: 2,
+	footprint: {
+		w: 4,
+		d: 4
+	},
+	stats: {
+		health: 1500,
+		armor: 10
+	},
+	sight: 12,
+	cost: {
+		gold: 400,
+		lumber: 200
+	},
+	buildTime: 40,
+	supplyProvided: 10,
+	trains: ["worker"],
+	dropOff: true,
+	upgradesTo: "keep"
+};
+var keep = {
+	...hall,
+	id: "keep",
+	name: "Keep",
+	stats: {
+		health: 2e3,
+		armor: 10
+	},
+	cost: {
+		gold: 300,
+		lumber: 200
+	},
+	provides: ["hall"],
+	upgradesTo: void 0
+};
+var supply = {
+	id: "supply",
+	name: "Supply",
+	kind: "building",
+	radius: 1,
+	footprint: {
+		w: 2,
+		d: 2
+	},
+	stats: {
+		health: 500,
+		armor: 10
+	},
+	sight: 6,
+	cost: { gold: 50 },
+	buildTime: 10,
+	supplyProvided: 10
+};
+var barracks = {
+	id: "barracks",
+	name: "Barracks",
+	kind: "building",
+	radius: 1.5,
+	footprint: {
+		w: 3,
+		d: 3
+	},
+	stats: {
+		health: 1e3,
+		armor: 10
+	},
+	sight: 9,
+	cost: {
+		gold: 150,
+		lumber: 50
+	},
+	buildTime: 20,
+	trains: ["soldier", "archer"],
+	researches: ["armour"]
+};
+var tower = {
+	id: "tower",
+	name: "Tower",
+	kind: "building",
+	radius: 1,
+	footprint: {
+		w: 2,
+		d: 2
+	},
+	stats: {
+		health: 500,
+		attackDamage: 20,
+		attackSpeed: 1,
+		attackRange: 8,
+		armor: 10
+	},
+	sight: 12,
+	attacks: [{
+		damagePoint: .3,
+		acquisitionRange: 8,
+		projectileSpeed: 20,
+		targets: ["ground", "air"]
+	}],
+	cost: {
+		gold: 100,
+		lumber: 50
+	},
+	buildTime: 20,
+	requires: ["barracks"]
+};
+var altar = {
+	id: "altar",
+	name: "Altar",
+	kind: "building",
+	radius: 1.5,
+	footprint: {
+		w: 3,
+		d: 3
+	},
+	stats: {
+		health: 1e3,
+		armor: 10
+	},
+	sight: 9,
+	cost: {
+		gold: 200,
+		lumber: 50
+	},
+	buildTime: 30,
+	trains: ["hero"],
+	revives: true
+};
+var mine = {
+	id: "mine",
+	name: "Mine",
+	kind: "resource",
+	radius: 2,
+	footprint: {
+		w: 4,
+		d: 4
+	},
+	stats: { health: 1 },
+	sight: 0,
+	invulnerable: true,
+	resource: {
+		kind: "gold",
+		amount: 1e4,
+		slots: 1,
+		entered: true
+	}
+};
+var tree = {
+	id: "tree",
+	name: "Tree",
+	kind: "resource",
+	radius: .5,
+	footprint: {
+		w: 1,
+		d: 1
+	},
+	stats: { health: 1 },
+	sight: 0,
+	invulnerable: true,
+	fellable: true,
+	resource: {
+		kind: "lumber",
+		amount: 50,
+		slots: 1,
+		gatherTime: 5
+	}
+};
+var armour = {
+	id: "armour",
+	name: "Armour",
+	description: "+10 armor for soldiers and archers",
+	cost: {
+		gold: 100,
+		lumber: 50
+	},
+	researchTime: 20,
+	maxLevel: 2,
+	effects: [{
+		units: ["soldier", "archer"],
+		stats: { armor: 10 }
+	}]
+};
+var guarded = {
+	id: "guarded",
+	name: "Guarded",
+	description: "+20 armor",
+	duration: 10,
+	stats: { armor: 20 }
+};
+var abilities = [
+	{
+		id: "heal",
+		name: "Heal",
+		description: "Heals a friendly unit for 100 or 200",
+		target: "unit",
+		targets: {
+			allies: true,
+			self: false
+		},
+		manaCost: 10,
+		cooldown: 5,
+		range: 6,
+		effects: [{
+			type: "heal",
+			amount: [100, 200]
+		}]
+	},
+	{
+		id: "guard",
+		name: "Guard",
+		description: "+20 armor for 10 seconds",
+		target: "none",
+		cooldown: 10,
+		effects: [{
+			type: "buff",
+			buff: "guarded",
+			on: "caster"
+		}]
+	},
+	{
+		id: "drink",
+		name: "Drink",
+		description: "Heals 100",
+		target: "none",
+		cooldown: 10,
+		effects: [{
+			type: "heal",
+			amount: 100,
+			on: "caster"
+		}]
+	}
+];
+var items = [{
+	id: "sword",
+	name: "Sword",
+	description: "+10 attack damage",
+	tier: "basic",
+	cost: { gold: 100 },
+	bonus: { stats: { attackDamage: 10 } }
+}, {
+	id: "potion",
+	name: "Potion",
+	description: "Heals 100 when drunk",
+	tier: "consumable",
+	cost: { gold: 50 },
+	charges: 1,
+	ability: "drink"
+}];
+/** A hall where a player starts, and five workers on the side of the closest mine */
+function startingBase(world, player, at) {
+	const base = world.spawn("hall", player, at);
+	let closest;
+	for (const entity of world.entities.values()) {
+		if (entity.def.resource?.kind !== "gold" || dist(entity.pos, base.pos) > 20) continue;
+		if (!closest || dist(entity.pos, base.pos) < dist(closest, base.pos)) closest = entity.pos;
+	}
+	const towards = closest ? {
+		x: Math.sign(closest.x - at.x),
+		z: Math.sign(closest.z - at.z)
+	} : {
+		x: 1,
+		z: 0
+	};
+	for (let i = 0; i < 5; i++) world.spawn("worker", player, {
+		x: at.x + towards.x * 4 + (i - 2) * towards.z,
+		z: at.z + towards.z * 4 + (i - 2) * towards.x
+	});
+}
+/**
+* The fixture game (see the top of this file): every role of the kit, with round numbers. Gold and lumber, 1000 of each
+* to start with; a hall and five workers at each start; heroes on (`withHeroes`); no fog explored at the start. A new
+* one each time, for a test to change
+*
+* @beta
+*/
+function fixtureGame() {
+	return {
+		id: "fixture",
+		name: "Fixture",
+		version: "1.0.0",
+		units: [
+			worker,
+			soldier,
+			archer,
+			hero,
+			creep,
+			hall,
+			keep,
+			supply,
+			barracks,
+			tower,
+			altar,
+			mine,
+			tree
+		].map((def) => structuredClone(def)),
+		upgrades: [structuredClone(armour)],
+		abilities: structuredClone(abilities),
+		buffs: [structuredClone(guarded)],
+		items: structuredClone(items),
+		resources: [{
+			id: "gold",
+			name: "Gold",
+			start: 1e3
+		}, {
+			id: "lumber",
+			name: "Lumber",
+			start: 1e3
+		}],
+		currency: "gold",
+		packs: [withHeroes()],
+		start: { spawn: startingBase }
+	};
+}
+/**
+* A map of the fixture game, 64 cells a side: two players, starting at opposite corners (12, 12 and 52, 52), a gold
+* mine and a row of trees by each start, and a camp of three creeps in the middle
+*
+* @beta
+*/
+function fixtureMap() {
+	const map = createMap({
+		name: "Fixture",
+		width: 64,
+		depth: 64,
+		game: "fixture"
+	});
+	map.players[0].start = {
+		x: 12,
+		z: 12
+	};
+	map.players[1].start = {
+		x: 52,
+		z: 52
+	};
+	let id = 1;
+	const object = (type, x, z) => map.objects.push({
+		id: id++,
+		type,
+		owner: 0,
+		x,
+		z,
+		facing: 0,
+		scale: 1
+	});
+	object("mine", 12, 22);
+	object("mine", 52, 42);
+	for (let i = 0; i < 6; i++) {
+		object("tree", 22.5 + i, 4.5);
+		object("tree", 36.5 + i, 59.5);
+	}
+	map.camps.push({
+		id: id++,
+		x: 32,
+		z: 32,
+		units: [
+			"creep",
+			"creep",
+			"creep"
+		]
+	});
+	return map;
+}
+//#endregion
+//#region src/aiTesting.ts
+/**
+* Testing a computer player (AI plan, E3): what a game's tests of its brains are written with, in
+* `@v12-engine/engine/testing` beside `testWorld` and `run`. A brain is tested as it plays, through the world it sits in:
+*
+*     const world = await testWorld(myGame)
+*     world.computers.seat(ENEMY, { enemyBases: [home], brain: myBrain })
+*     const watch = watchComputer(world, ENEMY)        // its invariants, every think
+*     run(world, 120)
+*     expectDecision(thinkOnce(world, ENEMY), 'ai.attack')
+*     watch.assert()                                     // no rule broken
+*
+* `thinkOnce` has a seated brain think now and gives its report; `expectDecision` says a goal runs, or why not in
+* words; `watchComputer` checks the invariants of `ai/checks.ts` after every think (a unit in one squad, gold spent
+* once, finite numbers, commands about what it sees, no churn, nothing stuck) and keeps what it decided; `fairPlay` is
+* the one about seeing; `recordDecisions` keeps every computer's decisions for a replay's side file; `checkComputerSave`
+* is the seventh invariant: a game saved and loaded decides the same from then on. These take the world, which a test
+* may: the brains under test never do.
+*/
+/**
+* The brain that plays a player, where one is seated (`world.computers.seat`): none where nobody is, or where what is
+* seated is not a brain (`defineComputer`)
+*
+* @beta
+*/
+function brainOf(world, player) {
+	const computer = world.computers.get(player)?.computer;
+	return computer instanceof Brain ? computer : void 0;
+}
+/** The brain at a player, or an error that says what is seated there instead */
+function seated(world, player) {
+	const brain = brainOf(world, player);
+	if (brain) return brain;
+	const system = world.computers.get(player);
+	throw new Error(system ? `The computer player at ${player} is not a brain (defineBrain): it has no report` : `No computer player is seated at ${player}`);
+}
+/**
+* Has the brain at a player think now, all of it (a think its budget slices over ticks is run to its end), over a new
+* picture of the game, and gives its report: what a test reads after setting a scene. Its commands land at the next
+* tick, as a think's do. A think the seat would have had is not skipped: this one is beside them
+*
+* @beta
+*/
+function thinkOnce(world, player) {
+	const brain = seated(world, player);
+	do
+		brain.think();
+	while (brain.busy);
+	return brain.report();
+}
+/**
+* Says that a goal runs, as of a report (`thinkOnce`, `Brain.report`): it is picked and holds what it claimed. Throws
+* where it does not, with its row in words (`Brain.explain`): what each consideration answered and what kept it out.
+* Gives the goal's row. With `picked: false`, says it does not run
+*
+*     expectDecision(thinkOnce(world, ENEMY), 'ai.defend')
+*
+* @beta
+*/
+function expectDecision(report, goal, options = {}) {
+	const wanted = options.picked ?? true;
+	const row = report.goals.find((each) => each.id === goal);
+	if (!row) throw new Error(`The brain ${report.brain} has no goal "${goal}": its goals are ${report.goals.map((each) => each.id).join(", ") || "none"}`);
+	if (row.picked === wanted) return row;
+	const seconds = (tick) => tick / report.tickRate;
+	throw new Error(`Expected ${goal} ${wanted ? "to run" : "not to run"} at ${report.time.toFixed(1)} s, and it ${wanted ? "does not" : "does"}. ${explainGoal(row, seconds, report.time)}${report.goal && report.goal !== goal ? ` The best goal is ${report.goal}.` : ""}`);
+}
+/**
+* Follows the brain at a player from now on: after every think, the invariants of `ai/checks.ts` (a unit in one squad
+* and one hold, gold spent once, finite numbers, commands about what it sees, no order sent again to a unit still at
+* it, builders, tasks, holds and wants that end), with what it decided and sent. A broken rule is kept, not thrown,
+* unless `onViolation` throws: `assert` at the end says them all
+*
+* @beta
+*/
+function watchComputer(world, player, options = {}) {
+	const brain = seated(world, player);
+	const violations = [];
+	const decisions = [];
+	let thinks = 0;
+	let commands = 0;
+	const { stop: unchecked } = checkBrain(brain, {
+		...options,
+		onViolation: (violation) => {
+			violations.push(violation);
+			options.onViolation?.(violation);
+		}
+	});
+	const observer = options.observe ? new LocalSession(world, player, { observer: true }) : void 0;
+	const unwatched = brain.watch({
+		sent: (command) => {
+			commands++;
+			options.sent?.(command, brain);
+		},
+		decided: (decision) => void decisions.push(decision),
+		thought: () => {
+			thinks++;
+			if (observer) options.observe(observer.snapshot(), brain);
+		}
+	});
+	return {
+		brain,
+		violations,
+		decisions,
+		get thinks() {
+			return thinks;
+		},
+		get commands() {
+			return commands;
+		},
+		assert() {
+			if (!violations.length) return;
+			const lines = violations.slice(0, 20).map((each) => `  ${each.invariant} at tick ${each.tick}: ${each.message}`);
+			const more = violations.length > 20 ? `\n  and ${violations.length - 20} more` : "";
+			throw new Error(`The computer player at ${player} broke ${violations.length} rule${violations.length === 1 ? "" : "s"}:\n${lines.join("\n")}${more}`);
+		},
+		stop() {
+			unchecked();
+			unwatched();
+			observer?.dispose();
+		}
+	};
+}
+/**
+* Follows the brain at a player from now on for fair play: that it never sends a command about an entity its snapshot
+* did not have (a fog leak: its seat's session would drop the command, so a game shows nothing; this says it), and
+* counts what the game refused
+*
+* @beta
+*/
+function fairPlay(world, player) {
+	const watch = watchComputer(world, player, { invariants: ["commands"] });
+	const brain = watch.brain;
+	const refusedBefore = brain.stats.refused;
+	return {
+		get unfair() {
+			return watch.violations;
+		},
+		get refused() {
+			return brain.stats.refused - refusedBefore;
+		},
+		assert: () => watch.assert(),
+		stop: () => watch.stop()
+	};
+}
+/** How many recorders were made: each one's system a name of its own */
+var recorders = 0;
+/**
+* Keeps the decisions of every brain seated at a world, from now on, those seated later included (looked for at each
+* tick, by a system of its own that keeps nothing in a save)
+*
+* @beta
+*/
+function recordDecisions(world) {
+	const decisions = [];
+	const watched = /* @__PURE__ */ new Map();
+	const look = () => {
+		for (const player of world.computers.list()) {
+			const brain = brainOf(world, player);
+			if (!brain || watched.has(brain)) continue;
+			watched.set(brain, brain.watch({ decided: (decision) => void decisions.push({
+				...decision,
+				player: brain.playerId,
+				brain: brain.def.id
+			}) }));
+		}
+	};
+	look();
+	const name = `core.ai.recordDecisions.${++recorders}`;
+	world.addSystem({
+		name,
+		update: look
+	});
+	return {
+		decisions,
+		stop() {
+			world.removeSystem(name);
+			for (const unwatch of watched.values()) unwatch();
+			watched.clear();
+		}
+	};
+}
+/**
+* The seventh invariant of a computer player: a game saved at tick `from` and loaded makes the same decisions from then
+* on as the game it was saved from, under the same commands. Makes the world with `make` (its computers seated, as a
+* game seats them), runs it to `from`, saves it as a file would keep it and loads that with `game`, then runs both to
+* `ticks` and compares what every computer decided. What lost rng, tasks or memory in a restore shows as
+*
+*     expect(await checkComputerSave(() => duel(), { from: 600, ticks: 2400, game: melee })).toBeNull()
+*
+* @beta
+*/
+async function checkComputerSave(make, options) {
+	const saved = await make();
+	let loaded;
+	try {
+		while (saved.tick < options.from) saved.step();
+		loaded = await loadWorld(decodeSave(encodeSave(saveWorld(saved))), { game: options.game });
+		const before = recordDecisions(saved);
+		const after = recordDecisions(loaded);
+		while (saved.tick < options.ticks) {
+			saved.step();
+			loaded.step();
+		}
+		before.stop();
+		after.stop();
+		const a = before.decisions;
+		const b = after.decisions;
+		for (let i = 0; i < Math.max(a.length, b.length); i++) if (JSON.stringify(a[i]) !== JSON.stringify(b[i])) return {
+			index: i,
+			...a[i] && { saved: a[i] },
+			...b[i] && { loaded: b[i] }
+		};
+		return null;
+	} finally {
+		saved.dispose();
+		loaded?.dispose();
+	}
+}
+//#endregion
+//#region src/testing.ts
+/**
+* Flat ground, `size` cells a side: 48 when left out
+*
+* @beta
+*/
+var flatTerrain = (size = 48) => new Terrain(size, size, new Float32Array((size + 1) * (size + 1)));
+/**
+* The players of a test world, when a test says none: a neutral one, and two who are enemies
+*
+* @beta
+*/
+var TEST_PLAYERS = [
+	{
+		id: 0,
+		name: "Neutral",
+		team: 0,
+		color: [
+			1,
+			1,
+			0
+		],
+		neutral: true
+	},
+	{
+		id: 1,
+		name: "Player",
+		team: 1,
+		color: [
+			0,
+			0,
+			1
+		]
+	},
+	{
+		id: 2,
+		name: "Enemy",
+		team: 2,
+		color: [
+			1,
+			0,
+			0
+		]
+	}
+];
+/**
+* A small world of a game for a test: flat ground, a neutral player and two enemies (`TEST_PLAYERS`), the same every
+* time (seed 7). Each of them is the test's to say otherwise
+*
+* @beta
+*/
+function testWorld(game, options = {}) {
+	return createWorld({
+		terrain: options.terrain ?? flatTerrain(options.size),
+		game,
+		seed: options.seed ?? 7,
+		players: options.players ?? TEST_PLAYERS.map((player) => ({ ...player })),
+		log: options.log
+	});
+}
+/**
+* Steps the world for up to `seconds`, stopping early once `until` holds. Returns the time that went by in it
+*
+* @beta
+*/
+function run(world, seconds, until) {
+	const ticks = Math.ceil(seconds * world.tickRate);
+	for (let i = 0; i < ticks; i++) {
+		world.step();
+		if (until?.()) return (i + 1) / world.tickRate;
+	}
+	return seconds;
+}
+/**
+* Gives units an order, as their owner would: taken up at the next tick. `queue` adds it after what they are doing
+*
+* @beta
+*/
+var order = (world, entities, init, queue = false) => world.issue({
+	type: "order",
+	player: entities[0].owner,
+	entities: entities.map((entity) => entity.id),
+	order: init,
+	queue
+});
+//#endregion
+export { TEST_PLAYERS, brainOf, checkComputerSave, checkDeterminism, defineSimulation, expectDecision, fairPlay, firstDifference, fixtureGame, fixtureMap, flatTerrain, order, playGame, recordDecisions, run, simulate, testWorld, thinkOnce, watchComputer, winRates, worldFingerprint, worldHash, worldState };
+
+//# sourceMappingURL=testing.js.map