@v12-engine/engine 0.1.0 → 0.4.0

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","names":[],"sources":["../src/fixture.ts","../src/aiTesting.ts","../src/testing.ts"],"sourcesContent":["/**\n * The fixture game: the smallest game the engine's kit has a part for each of its roles in (a hall and its workers,\n * supply, a barracks of a fighter and an archer, a tower, an altar and a hero, a gold mine and trees, a creep, an\n * upgrade, abilities and items), for the engine's own tests and a game's. Its numbers are round (health 100 or 200,\n * damage 10, speed 4) so that what a test expects reads as what it means: a soldier hits an archer ten times\n */\nimport type { AbilityDef, BuffDef, ItemDef, UnitTypeDef, UpgradeDef } from './defs'\nimport type { GameModule } from './game'\nimport { createMap, type GameMap } from './map'\nimport { dist, type Vec2 } from './math'\nimport { withHeroes } from './packs/heroes'\nimport type { PlayerId } from './entity'\nimport type { World } from './world'\n\nconst worker: UnitTypeDef = {\n\tid: 'worker',\n\tname: 'Worker',\n\tkind: 'unit',\n\tradius: 0.4,\n\tstats: { health: 100, attackDamage: 5, attackSpeed: 1, attackRange: 0.5, moveSpeed: 4 },\n\tsight: 8,\n\tattacks: [{ damagePoint: 0.3, acquisitionRange: 0, targets: ['unit', 'building'] }],\n\tcost: { gold: 50 },\n\tsupply: 1,\n\tbuildTime: 10,\n\tharvester: { capacity: 10, gatherTime: 1 },\n\tbuilds: ['hall', 'supply', 'barracks', 'tower', 'altar']\n}\n\nconst soldier: UnitTypeDef = {\n\tid: 'soldier',\n\tname: 'Soldier',\n\tkind: 'unit',\n\tradius: 0.45,\n\tstats: { health: 200, attackDamage: 10, attackSpeed: 1, attackRange: 0.5, armor: 10, moveSpeed: 4 },\n\tsight: 10,\n\tattacks: [{ damagePoint: 0.3, acquisitionRange: 8 }],\n\tcost: { gold: 100 },\n\tsupply: 2,\n\tbuildTime: 10,\n\tabilities: ['guard']\n}\n\nconst archer: UnitTypeDef = {\n\tid: 'archer',\n\tname: 'Archer',\n\tkind: 'unit',\n\tradius: 0.45,\n\tstats: { health: 100, attackDamage: 10, attackSpeed: 1, attackRange: 6, moveSpeed: 4 },\n\tsight: 10,\n\tattacks: [{ damagePoint: 0.3, acquisitionRange: 8, projectileSpeed: 20, targets: ['ground', 'air'] }],\n\tcost: { gold: 100, lumber: 20 },\n\tsupply: 2,\n\tbuildTime: 10\n}\n\nconst hero: UnitTypeDef = {\n\tid: 'hero',\n\tname: 'Hero',\n\tkind: 'unit',\n\tradius: 0.5,\n\tstats: { health: 300, mana: 100, manaRegen: 1, attackDamage: 20, attackSpeed: 1, attackRange: 0.5, armor: 10, moveSpeed: 4 },\n\tsight: 12,\n\tattacks: [{ damagePoint: 0.3, acquisitionRange: 8 }],\n\thero: { growth: { stats: { health: 20, mana: 10, attackDamage: 2 } }, learns: ['heal', 'guard'] },\n\tinventory: 6,\n\tcost: { gold: 400, lumber: 100 },\n\tsupply: 5,\n\tbuildTime: 40\n}\n\nconst creep: UnitTypeDef = {\n\tid: 'creep',\n\tname: 'Creep',\n\tkind: 'unit',\n\tradius: 0.45,\n\tstats: { health: 200, attackDamage: 10, attackSpeed: 1, attackRange: 0.5, moveSpeed: 3 },\n\tsight: 8,\n\tattacks: [{ damagePoint: 0.3, acquisitionRange: 5 }],\n\tlevel: 1,\n\tbounty: [10, 10],\n\txp: 20\n}\n\nconst hall: UnitTypeDef = {\n\tid: 'hall',\n\tname: 'Hall',\n\tkind: 'building',\n\tradius: 2,\n\tfootprint: { w: 4, d: 4 },\n\tstats: { health: 1500, armor: 10 },\n\tsight: 12,\n\tcost: { gold: 400, lumber: 200 },\n\tbuildTime: 40,\n\tsupplyProvided: 10,\n\ttrains: ['worker'],\n\tdropOff: true,\n\tupgradesTo: 'keep'\n}\n\nconst keep: UnitTypeDef = {\n\t...hall,\n\tid: 'keep',\n\tname: 'Keep',\n\tstats: { health: 2000, armor: 10 },\n\tcost: { gold: 300, lumber: 200 },\n\tprovides: ['hall'],\n\tupgradesTo: undefined\n}\n\nconst supply: UnitTypeDef = {\n\tid: 'supply',\n\tname: 'Supply',\n\tkind: 'building',\n\tradius: 1,\n\tfootprint: { w: 2, d: 2 },\n\tstats: { health: 500, armor: 10 },\n\tsight: 6,\n\tcost: { gold: 50 },\n\tbuildTime: 10,\n\tsupplyProvided: 10\n}\n\nconst barracks: UnitTypeDef = {\n\tid: 'barracks',\n\tname: 'Barracks',\n\tkind: 'building',\n\tradius: 1.5,\n\tfootprint: { w: 3, d: 3 },\n\tstats: { health: 1000, armor: 10 },\n\tsight: 9,\n\tcost: { gold: 150, lumber: 50 },\n\tbuildTime: 20,\n\ttrains: ['soldier', 'archer'],\n\tresearches: ['armour']\n}\n\nconst tower: UnitTypeDef = {\n\tid: 'tower',\n\tname: 'Tower',\n\tkind: 'building',\n\tradius: 1,\n\tfootprint: { w: 2, d: 2 },\n\tstats: { health: 500, attackDamage: 20, attackSpeed: 1, attackRange: 8, armor: 10 },\n\tsight: 12,\n\tattacks: [{ damagePoint: 0.3, acquisitionRange: 8, projectileSpeed: 20, targets: ['ground', 'air'] }],\n\tcost: { gold: 100, lumber: 50 },\n\tbuildTime: 20,\n\trequires: ['barracks']\n}\n\nconst altar: UnitTypeDef = {\n\tid: 'altar',\n\tname: 'Altar',\n\tkind: 'building',\n\tradius: 1.5,\n\tfootprint: { w: 3, d: 3 },\n\tstats: { health: 1000, armor: 10 },\n\tsight: 9,\n\tcost: { gold: 200, lumber: 50 },\n\tbuildTime: 30,\n\ttrains: ['hero'],\n\trevives: true\n}\n\nconst mine: UnitTypeDef = {\n\tid: 'mine',\n\tname: 'Mine',\n\tkind: 'resource',\n\tradius: 2,\n\tfootprint: { w: 4, d: 4 },\n\tstats: { health: 1 },\n\tsight: 0,\n\tinvulnerable: true,\n\tresource: { kind: 'gold', amount: 10000, slots: 1, entered: true }\n}\n\nconst tree: UnitTypeDef = {\n\tid: 'tree',\n\tname: 'Tree',\n\tkind: 'resource',\n\tradius: 0.5,\n\tfootprint: { w: 1, d: 1 },\n\tstats: { health: 1 },\n\tsight: 0,\n\tinvulnerable: true,\n\tfellable: true,\n\tresource: { kind: 'lumber', amount: 50, slots: 1, gatherTime: 5 }\n}\n\nconst armour: UpgradeDef = {\n\tid: 'armour',\n\tname: 'Armour',\n\tdescription: '+10 armor for soldiers and archers',\n\tcost: { gold: 100, lumber: 50 },\n\tresearchTime: 20,\n\tmaxLevel: 2,\n\teffects: [{ units: ['soldier', 'archer'], stats: { armor: 10 } }]\n}\n\nconst guarded: BuffDef = { id: 'guarded', name: 'Guarded', description: '+20 armor', duration: 10, stats: { armor: 20 } }\n\nconst abilities: AbilityDef[] = [\n\t{\n\t\tid: 'heal',\n\t\tname: 'Heal',\n\t\tdescription: 'Heals a friendly unit for 100 or 200',\n\t\ttarget: 'unit',\n\t\ttargets: { allies: true, self: false },\n\t\tmanaCost: 10,\n\t\tcooldown: 5,\n\t\trange: 6,\n\t\teffects: [{ type: 'heal', amount: [100, 200] }]\n\t},\n\t{\n\t\tid: 'guard',\n\t\tname: 'Guard',\n\t\tdescription: '+20 armor for 10 seconds',\n\t\ttarget: 'none',\n\t\tcooldown: 10,\n\t\teffects: [{ type: 'buff', buff: 'guarded', on: 'caster' }]\n\t},\n\t{ id: 'drink', name: 'Drink', description: 'Heals 100', target: 'none', cooldown: 10, effects: [{ type: 'heal', amount: 100, on: 'caster' }] }\n]\n\nconst items: ItemDef[] = [\n\t{ id: 'sword', name: 'Sword', description: '+10 attack damage', tier: 'basic', cost: { gold: 100 }, bonus: { stats: { attackDamage: 10 } } },\n\t{ id: 'potion', name: 'Potion', description: 'Heals 100 when drunk', tier: 'consumable', cost: { gold: 50 }, charges: 1, ability: 'drink' }\n]\n\n/** A hall where a player starts, and five workers on the side of the closest mine */\nfunction startingBase(world: World, player: PlayerId, at: Vec2): void {\n\tconst base = world.spawn('hall', player, at)\n\tlet closest: Vec2 | undefined\n\tfor (const entity of world.entities.values()) {\n\t\tif (entity.def.resource?.kind !== 'gold' || dist(entity.pos, base.pos) > 20) continue\n\t\tif (!closest || dist(entity.pos, base.pos) < dist(closest, base.pos)) closest = entity.pos\n\t}\n\tconst towards = closest ? { x: Math.sign(closest.x - at.x), z: Math.sign(closest.z - at.z) } : { x: 1, z: 0 }\n\tfor (let i = 0; i < 5; i++)\n\t\tworld.spawn('worker', player, { x: at.x + towards.x * 4 + (i - 2) * towards.z, z: at.z + towards.z * 4 + (i - 2) * towards.x })\n}\n\n/**\n * The fixture game (see the top of this file): every role of the kit, with round numbers. Gold and lumber, 1000 of each\n * to start with; a hall and five workers at each start; heroes on (`withHeroes`); no fog explored at the start. A new\n * one each time, for a test to change\n *\n * @beta\n */\nexport function fixtureGame(): GameModule {\n\treturn {\n\t\tid: 'fixture',\n\t\tname: 'Fixture',\n\t\tversion: '1.0.0',\n\t\tunits: [worker, soldier, archer, hero, creep, hall, keep, supply, barracks, tower, altar, mine, tree].map((def) => structuredClone(def)),\n\t\tupgrades: [structuredClone(armour)],\n\t\tabilities: structuredClone(abilities),\n\t\tbuffs: [structuredClone(guarded)],\n\t\titems: structuredClone(items),\n\t\tresources: [\n\t\t\t{ id: 'gold', name: 'Gold', start: 1000 },\n\t\t\t{ id: 'lumber', name: 'Lumber', start: 1000 }\n\t\t],\n\t\tcurrency: 'gold',\n\t\tpacks: [withHeroes()],\n\t\tstart: { spawn: startingBase }\n\t}\n}\n\n/**\n * A map of the fixture game, 64 cells a side: two players, starting at opposite corners (12, 12 and 52, 52), a gold\n * mine and a row of trees by each start, and a camp of three creeps in the middle\n *\n * @beta\n */\nexport function fixtureMap(): GameMap {\n\tconst map = createMap({ name: 'Fixture', width: 64, depth: 64, game: 'fixture' })\n\tmap.players[0].start = { x: 12, z: 12 }\n\tmap.players[1].start = { x: 52, z: 52 }\n\tlet id = 1\n\tconst object = (type: string, x: number, z: number) => map.objects.push({ id: id++, type, owner: 0, x, z, facing: 0, scale: 1 })\n\tobject('mine', 12, 22)\n\tobject('mine', 52, 42)\n\tfor (let i = 0; i < 6; i++) {\n\t\tobject('tree', 22.5 + i, 4.5)\n\t\tobject('tree', 36.5 + i, 59.5)\n\t}\n\tmap.camps.push({ id: id++, x: 32, z: 32, units: ['creep', 'creep', 'creep'] })\n\treturn map\n}\n","/**\n * Testing a computer player (AI plan, E3): what a game's tests of its brains are written with, in\n * `@v12-engine/engine/testing` beside `testWorld` and `run`. A brain is tested as it plays, through the world it sits in:\n *\n *     const world = await testWorld(myGame)\n *     world.computers.seat(ENEMY, { enemyBases: [home], brain: myBrain })\n *     const watch = watchComputer(world, ENEMY)        // its invariants, every think\n *     run(world, 120)\n *     expectDecision(thinkOnce(world, ENEMY), 'ai.attack')\n *     watch.assert()                                     // no rule broken\n *\n * `thinkOnce` has a seated brain think now and gives its report; `expectDecision` says a goal runs, or why not in\n * words; `watchComputer` checks the invariants of `ai/checks.ts` after every think (a unit in one squad, gold spent\n * once, finite numbers, commands about what it sees, no churn, nothing stuck) and keeps what it decided; `fairPlay` is\n * the one about seeing; `recordDecisions` keeps every computer's decisions for a replay's side file; `checkComputerSave`\n * is the seventh invariant: a game saved and loaded decides the same from then on. These take the world, which a test\n * may: the brains under test never do.\n */\nimport { type AiCheckOptions, type AiViolation, checkBrain } from './ai/checks'\nimport { Brain } from './ai/brain'\nimport type { GoalReport } from './ai/goals'\nimport { type AiDecision, type AiReport, explainGoal } from './ai/report'\nimport type { PlayerId } from './entity'\nimport { type GameModule, loadWorld } from './game'\nimport { decodeSave, encodeSave, saveWorld } from './save'\nimport { LocalSession } from './session/local'\nimport type { PlayerCommand, Snapshot } from './session/protocol'\nimport type { World } from './world'\n\n/**\n * The brain that plays a player, where one is seated (`world.computers.seat`): none where nobody is, or where what is\n * seated is not a brain (`defineComputer`)\n *\n * @beta\n */\nexport function brainOf(world: World, player: PlayerId): Brain | undefined {\n\tconst computer = world.computers.get(player)?.computer\n\treturn computer instanceof Brain ? computer : undefined\n}\n\n/** The brain at a player, or an error that says what is seated there instead */\nfunction seated(world: World, player: PlayerId): Brain {\n\tconst brain = brainOf(world, player)\n\tif (brain) return brain\n\tconst system = world.computers.get(player)\n\tthrow new Error(\n\t\tsystem ? `The computer player at ${player} is not a brain (defineBrain): it has no report` : `No computer player is seated at ${player}`\n\t)\n}\n\n/**\n * 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\n * picture of the game, and gives its report: what a test reads after setting a scene. Its commands land at the next\n * tick, as a think's do. A think the seat would have had is not skipped: this one is beside them\n *\n * @beta\n */\nexport function thinkOnce(world: World, player: PlayerId): AiReport {\n\tconst brain = seated(world, player)\n\tdo brain.think()\n\twhile (brain.busy)\n\treturn brain.report()\n}\n\n/**\n * Says that a goal runs, as of a report (`thinkOnce`, `Brain.report`): it is picked and holds what it claimed. Throws\n * where it does not, with its row in words (`Brain.explain`): what each consideration answered and what kept it out.\n * Gives the goal's row. With `picked: false`, says it does not run\n *\n *     expectDecision(thinkOnce(world, ENEMY), 'ai.defend')\n *\n * @beta\n */\nexport function expectDecision(report: AiReport, goal: string, options: { picked?: boolean } = {}): GoalReport {\n\tconst wanted = options.picked ?? true\n\tconst row = report.goals.find((each) => each.id === goal)\n\tif (!row)\n\t\tthrow new Error(`The brain ${report.brain} has no goal \"${goal}\": its goals are ${report.goals.map((each) => each.id).join(', ') || 'none'}`)\n\tif (row.picked === wanted) return row\n\tconst seconds = (tick: number) => tick / report.tickRate\n\tthrow new Error(\n\t\t`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)}${\n\t\t\treport.goal && report.goal !== goal ? ` The best goal is ${report.goal}.` : ''\n\t\t}`\n\t)\n}\n\n/**\n * A computer player followed over a run (`watchComputer`): the rules it broke, what it decided and sent, and, where\n * asked, what an observer saw at each of its thinks\n *\n * @beta\n */\nexport interface ComputerWatch {\n\t/** The brain watched */\n\treadonly brain: Brain\n\t/** Every invariant it broke, in the order found (`ai/checks.ts`) */\n\treadonly violations: readonly AiViolation[]\n\t/** What it decided while watched, oldest first: every line, not only the last fifty its log keeps */\n\treadonly decisions: readonly AiDecision[]\n\t/** Its thinks while watched */\n\treadonly thinks: number\n\t/** Commands it sent while watched */\n\treadonly commands: number\n\t/** Throws, listing them, where it broke any rule */\n\tassert(): void\n\t/** Stops watching */\n\tstop(): void\n}\n\n/**\n * How a computer player is watched (`watchComputer`): which invariants and how long things may go on (`AiCheckOptions`),\n * and what to be shown at each think\n *\n * @beta\n */\nexport interface WatchOptions extends AiCheckOptions {\n\t/**\n\t * Shown, at the end of each of its thinks, the game as an observer sees it (everything, no fog) and the brain: for a\n\t * look at what it does (a test that writes frames, a page that draws them). An observer's seat is made only when given\n\t */\n\tobserve?: (snapshot: Snapshot, brain: Brain) => void\n\t/** Each command as it sends it */\n\tsent?: (command: PlayerCommand, brain: Brain) => void\n}\n\n/**\n * Follows the brain at a player from now on: after every think, the invariants of `ai/checks.ts` (a unit in one squad\n * and one hold, gold spent once, finite numbers, commands about what it sees, no order sent again to a unit still at\n * it, builders, tasks, holds and wants that end), with what it decided and sent. A broken rule is kept, not thrown,\n * unless `onViolation` throws: `assert` at the end says them all\n *\n * @beta\n */\nexport function watchComputer(world: World, player: PlayerId, options: WatchOptions = {}): ComputerWatch {\n\tconst brain = seated(world, player)\n\tconst violations: AiViolation[] = []\n\tconst decisions: AiDecision[] = []\n\tlet thinks = 0\n\tlet commands = 0\n\tconst { stop: unchecked } = checkBrain(brain, {\n\t\t...options,\n\t\tonViolation: (violation) => {\n\t\t\tviolations.push(violation)\n\t\t\toptions.onViolation?.(violation)\n\t\t}\n\t})\n\tconst observer = options.observe ? new LocalSession(world, player, { observer: true }) : undefined\n\tconst unwatched = brain.watch({\n\t\tsent: (command) => {\n\t\t\tcommands++\n\t\t\toptions.sent?.(command, brain)\n\t\t},\n\t\tdecided: (decision) => void decisions.push(decision),\n\t\tthought: () => {\n\t\t\tthinks++\n\t\t\tif (observer) options.observe!(observer.snapshot(), brain)\n\t\t}\n\t})\n\treturn {\n\t\tbrain,\n\t\tviolations,\n\t\tdecisions,\n\t\tget thinks() {\n\t\t\treturn thinks\n\t\t},\n\t\tget commands() {\n\t\t\treturn commands\n\t\t},\n\t\tassert() {\n\t\t\tif (!violations.length) return\n\t\t\tconst lines = violations.slice(0, 20).map((each) => `  ${each.invariant} at tick ${each.tick}: ${each.message}`)\n\t\t\tconst more = violations.length > 20 ? `\\n  and ${violations.length - 20} more` : ''\n\t\t\tthrow new Error(\n\t\t\t\t`The computer player at ${player} broke ${violations.length} rule${violations.length === 1 ? '' : 's'}:\\n${lines.join('\\n')}${more}`\n\t\t\t)\n\t\t},\n\t\tstop() {\n\t\t\tunchecked()\n\t\t\tunwatched()\n\t\t\tobserver?.dispose()\n\t\t}\n\t}\n}\n\n/**\n * Whether a computer player played fair over a run (`fairPlay`): every command it sent named what its own snapshot\n * had, and how many the game refused\n *\n * @beta\n */\nexport interface FairPlay {\n\t/** Commands that named an entity it did not see, or a place off the map */\n\treadonly unfair: readonly AiViolation[]\n\t/** Commands the game refused while watched (a unit that could not do it, a place it could not build at) */\n\treadonly refused: number\n\t/** Throws where it sent any command about what it did not see */\n\tassert(): void\n\tstop(): void\n}\n\n/**\n * Follows the brain at a player from now on for fair play: that it never sends a command about an entity its snapshot\n * did not have (a fog leak: its seat's session would drop the command, so a game shows nothing; this says it), and\n * counts what the game refused\n *\n * @beta\n */\nexport function fairPlay(world: World, player: PlayerId): FairPlay {\n\tconst watch = watchComputer(world, player, { invariants: ['commands'] })\n\tconst brain = watch.brain\n\tconst refusedBefore = brain.stats.refused\n\treturn {\n\t\tget unfair() {\n\t\t\treturn watch.violations\n\t\t},\n\t\tget refused() {\n\t\t\treturn brain.stats.refused - refusedBefore\n\t\t},\n\t\tassert: () => watch.assert(),\n\t\tstop: () => watch.stop()\n\t}\n}\n\n/**\n * One thing a computer player decided, with whose: a line of a replay's side file (`recordDecisions`)\n *\n * @beta\n */\nexport interface RecordedDecision extends AiDecision {\n\tplayer: PlayerId\n\t/** The brain's id */\n\tbrain: string\n}\n\n/**\n * The decisions of every computer of a world, as they are made (`recordDecisions`): plain data, for a side file beside a\n * replay of commands, read back by whoever wonders why the computer did what the replay shows\n *\n * @beta\n */\nexport interface DecisionRecorder {\n\t/** Every decision so far, in the order made */\n\treadonly decisions: readonly RecordedDecision[]\n\tstop(): void\n}\n\n/** How many recorders were made: each one's system a name of its own */\nlet recorders = 0\n\n/**\n * Keeps the decisions of every brain seated at a world, from now on, those seated later included (looked for at each\n * tick, by a system of its own that keeps nothing in a save)\n *\n * @beta\n */\nexport function recordDecisions(world: World): DecisionRecorder {\n\tconst decisions: RecordedDecision[] = []\n\tconst watched = new Map<Brain, () => void>()\n\tconst look = () => {\n\t\tfor (const player of world.computers.list()) {\n\t\t\tconst brain = brainOf(world, player)\n\t\t\tif (!brain || watched.has(brain)) continue\n\t\t\twatched.set(brain, brain.watch({ decided: (decision) => void decisions.push({ ...decision, player: brain.playerId, brain: brain.def.id }) }))\n\t\t}\n\t}\n\tlook()\n\tconst name = `core.ai.recordDecisions.${++recorders}`\n\tworld.addSystem({ name, update: look })\n\treturn {\n\t\tdecisions,\n\t\tstop() {\n\t\t\tworld.removeSystem(name)\n\t\t\tfor (const unwatch of watched.values()) unwatch()\n\t\t\twatched.clear()\n\t\t}\n\t}\n}\n\n/**\n * Where a game saved and loaded first decided otherwise than the game it was saved from (`checkComputerSave`): the\n * decision each made at that place in their logs. `null` where they decided alike to the end\n *\n * @beta\n */\nexport interface DecisionsApart {\n\t/** How many decisions since the save they shared before this one */\n\tindex: number\n\t/** The game that went on from the save */\n\tsaved?: RecordedDecision\n\t/** The game loaded from it */\n\tloaded?: RecordedDecision\n}\n\n/**\n * The seventh invariant of a computer player: a game saved at tick `from` and loaded makes the same decisions from then\n * on as the game it was saved from, under the same commands. Makes the world with `make` (its computers seated, as a\n * game seats them), runs it to `from`, saves it as a file would keep it and loads that with `game`, then runs both to\n * `ticks` and compares what every computer decided. What lost rng, tasks or memory in a restore shows as\n *\n *     expect(await checkComputerSave(() => duel(), { from: 600, ticks: 2400, game: melee })).toBeNull()\n *\n * @beta\n */\nexport async function checkComputerSave(\n\tmake: () => World | Promise<World>,\n\toptions: { from: number; ticks: number; game: GameModule }\n): Promise<DecisionsApart | null> {\n\tconst saved = await make()\n\tlet loaded: World | undefined\n\ttry {\n\t\twhile (saved.tick < options.from) saved.step()\n\t\tloaded = await loadWorld(decodeSave(encodeSave(saveWorld(saved))), { game: options.game })\n\t\tconst before = recordDecisions(saved)\n\t\tconst after = recordDecisions(loaded)\n\t\twhile (saved.tick < options.ticks) {\n\t\t\tsaved.step()\n\t\t\tloaded.step()\n\t\t}\n\t\tbefore.stop()\n\t\tafter.stop()\n\t\tconst a = before.decisions\n\t\tconst b = after.decisions\n\t\tfor (let i = 0; i < Math.max(a.length, b.length); i++)\n\t\t\tif (JSON.stringify(a[i]) !== JSON.stringify(b[i])) return { index: i, ...(a[i] && { saved: a[i] }), ...(b[i] && { loaded: b[i] }) }\n\t\treturn null\n\t} finally {\n\t\tsaved.dispose()\n\t\tloaded?.dispose()\n\t}\n}\n","/**\n * `@v12-engine/engine/testing`: what a game's tests are written with. A world runs in a test as it does in a page, with no\n * screen: these make one, step it and give its units orders, so that a test says what happens in the game and little\n * else.\n *\n *     const world = await testWorld(myGame.rules)\n *     const knight = world.spawn('knight', 1, { x: 10, z: 10 })\n *     order(world, [knight], { type: 'move', point: { x: 30, z: 10 } })\n *     run(world, 5, () => knight.pos.x > 29)\n */\nimport type { Entity } from './entity'\nimport { createWorld, type GameModule } from './game'\nimport type { PlayerInit } from './player'\nimport type { Logger } from './log'\nimport type { OrderInit } from './registry'\nimport { Terrain } from './terrain'\nimport type { World } from './world'\n\n/**\n * Flat ground, `size` cells a side: 48 when left out\n *\n * @beta\n */\nexport const flatTerrain = (size = 48): Terrain => new Terrain(size, size, new Float32Array((size + 1) * (size + 1)))\n\n/**\n * The players of a test world, when a test says none: a neutral one, and two who are enemies\n *\n * @beta\n */\nexport const TEST_PLAYERS: PlayerInit[] = [\n\t{ id: 0, name: 'Neutral', team: 0, color: [1, 1, 0], neutral: true },\n\t{ id: 1, name: 'Player', team: 1, color: [0, 0, 1] },\n\t{ id: 2, name: 'Enemy', team: 2, color: [1, 0, 0] }\n]\n\n/**\n * A small world of a game for a test: flat ground, a neutral player and two enemies (`TEST_PLAYERS`), the same every\n * time (seed 7). Each of them is the test's to say otherwise\n *\n * @beta\n */\nexport function testWorld(\n\tgame: GameModule,\n\toptions: { terrain?: Terrain; size?: number; players?: PlayerInit[]; seed?: number; log?: Logger } = {}\n): Promise<World> {\n\treturn createWorld({\n\t\tterrain: options.terrain ?? flatTerrain(options.size),\n\t\tgame,\n\t\tseed: options.seed ?? 7,\n\t\tplayers: options.players ?? TEST_PLAYERS.map((player) => ({ ...player })),\n\t\tlog: options.log\n\t})\n}\n\n/**\n * Steps the world for up to `seconds`, stopping early once `until` holds. Returns the time that went by in it\n *\n * @beta\n */\nexport function run(world: World, seconds: number, until?: () => boolean): number {\n\tconst ticks = Math.ceil(seconds * world.tickRate)\n\tfor (let i = 0; i < ticks; i++) {\n\t\tworld.step()\n\t\tif (until?.()) return (i + 1) / world.tickRate\n\t}\n\treturn seconds\n}\n\n/**\n * Gives units an order, as their owner would: taken up at the next tick. `queue` adds it after what they are doing\n *\n * @beta\n */\nexport const order = (world: World, entities: Entity[], init: OrderInit, queue = false): void =>\n\tworld.issue({ type: 'order', player: entities[0].owner, entities: entities.map((entity) => entity.id), order: init, queue })\n\n// the fixture game, every role of the kit with round numbers: see `fixture.ts`\nexport { fixtureGame, fixtureMap } from './fixture'\n// many games at once, for balance: see `simulate.ts`\nexport {\n\ttype BrainResults,\n\ttype ComputerMeasures,\n\tdefineSimulation,\n\tplayGame,\n\ttype Counted,\n\ttype SimulatedGame,\n\ttype SimulateOptions,\n\tsimulate,\n\ttype Simulation,\n\twinRates\n} from './simulate'\n// a computer player under test: see `aiTesting.ts`\nexport {\n\tbrainOf,\n\tcheckComputerSave,\n\ttype ComputerWatch,\n\ttype DecisionRecorder,\n\ttype DecisionsApart,\n\texpectDecision,\n\ttype FairPlay,\n\tfairPlay,\n\ttype RecordedDecision,\n\trecordDecisions,\n\tthinkOnce,\n\twatchComputer,\n\ttype WatchOptions\n} from './aiTesting'\n\nexport {\n\ttype Apart,\n\tcheckDeterminism,\n\ttype DeterminismOptions,\n\ttype DeterminismReport,\n\ttype Difference,\n\tfirstDifference,\n\tworldFingerprint,\n\tworldHash,\n\tworldState\n} from './determinism'\n"],"mappings":"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"}
+{"version":3,"file":"testing.js","names":[],"sources":["../src/testing.ts"],"sourcesContent":["/**\n * `@v12-engine/engine/testing`: what a game's tests are written with. A world runs in a test as it does in a page, with no\n * screen: these make one, step it and give its units orders, so that a test says what happens in the game and little\n * else.\n *\n *     const world = await testWorld(myGame.rules)\n *     const knight = world.spawn('knight', 1, { x: 10, z: 10 })\n *     order(world, [knight], { type: 'move', point: { x: 30, z: 10 } })\n *     run(world, 5, () => knight.pos.x > 29)\n */\nimport type { Entity } from './entity'\nimport { createWorld, type Rules } from './game'\nimport { type Game, rulesOf } from './createGame'\nimport type { PlayerInit } from './player'\nimport type { Logger } from './log'\nimport type { OrderInit } from './registry'\nimport { Terrain } from './terrain'\nimport type { World } from './world'\n\n/**\n * Flat ground, `size` cells a side: 48 when left out\n *\n * @beta\n */\nexport const flatTerrain = (size = 48): Terrain => new Terrain(size, size, new Float32Array((size + 1) * (size + 1)))\n\n/**\n * The players of a test world, when a test says none: a neutral one, and two who are enemies\n *\n * @beta\n */\nexport const TEST_PLAYERS: PlayerInit[] = [\n\t{ id: 0, name: 'Neutral', team: 0, color: [1, 1, 0], neutral: true },\n\t{ id: 1, name: 'Player', team: 1, color: [0, 0, 1] },\n\t{ id: 2, name: 'Enemy', team: 2, color: [1, 0, 0] }\n]\n\n/**\n * A small world of a game for a test (the game, `createGame`, or its module, `Rules`): flat ground, a neutral player and two enemies (`TEST_PLAYERS`), the same every\n * time (seed 7). Each of them is the test's to say otherwise\n *\n * @public\n */\nexport function testWorld(\n\tgame: Game<unknown> | Rules,\n\toptions: { terrain?: Terrain; size?: number; players?: PlayerInit[]; seed?: number; log?: Logger } = {}\n): Promise<World> {\n\treturn createWorld({\n\t\tterrain: options.terrain ?? flatTerrain(options.size),\n\t\trules: rulesOf(game),\n\t\tseed: options.seed ?? 7,\n\t\tplayers: options.players ?? TEST_PLAYERS.map((player) => ({ ...player })),\n\t\tlog: options.log\n\t})\n}\n\n/**\n * Steps the world for up to `seconds`, stopping early once `until` holds. Returns the time that went by in it\n *\n * @public\n */\nexport function run(world: World, seconds: number, until?: () => boolean): number {\n\tconst ticks = Math.ceil(seconds * world.tickRate)\n\tfor (let i = 0; i < ticks; i++) {\n\t\tworld.step()\n\t\tif (until?.()) return (i + 1) / world.tickRate\n\t}\n\treturn seconds\n}\n\n/**\n * Gives units an order, as their owner would: taken up at the next tick. `queue` adds it after what they are doing\n *\n * @public\n */\nexport const order = (world: World, entities: Entity[], init: OrderInit, queue = false): void =>\n\tworld.issue({ type: 'order', player: entities[0].owner, entities: entities.map((entity) => entity.id), order: init, queue })\n\n// the fixture game, every role of the kit with round numbers: see `fixture.ts`\nexport { fixtureGame, fixtureMap } from './fixture'\n// many games at once, for balance: see `simulate.ts`\nexport {\n\ttype BrainResults,\n\ttype ComputerMeasures,\n\tplayGame,\n\ttype Counted,\n\ttype SimulatedGame,\n\ttype SimulateOptions,\n\tsimulate,\n\ttype Simulation,\n\twinRates\n} from './simulate'\n// a computer player under test: see `aiTesting.ts`\nexport {\n\tbrainOf,\n\tcheckComputerSave,\n\ttype ComputerWatch,\n\ttype DecisionRecorder,\n\ttype DecisionsApart,\n\texpectDecision,\n\ttype FairPlay,\n\tfairPlay,\n\ttype RecordedDecision,\n\trecordDecisions,\n\tthinkOnce,\n\twatchComputer,\n\ttype WatchOptions\n} from './aiTesting'\n\nexport {\n\ttype Apart,\n\tcheckDeterminism,\n\ttype DeterminismOptions,\n\ttype DeterminismReport,\n\ttype Difference,\n\tfirstDifference,\n\tworldFingerprint,\n\tworldHash,\n\tworldState\n} from './determinism'\n"],"mappings":";;;;;;;;;;;;;AAwBA,IAAa,eAAe,OAAO,OAAgB,IAAI,QAAQ,MAAM,MAAM,IAAI,cAAc,OAAO,MAAM,OAAO,EAAE,CAAC;;;;;;AAOpH,IAAa,eAA6B;CACzC;EAAE,IAAI;EAAG,MAAM;EAAW,MAAM;EAAG,OAAO;GAAC;GAAG;GAAG;EAAC;EAAG,SAAS;CAAK;CACnE;EAAE,IAAI;EAAG,MAAM;EAAU,MAAM;EAAG,OAAO;GAAC;GAAG;GAAG;EAAC;CAAE;CACnD;EAAE,IAAI;EAAG,MAAM;EAAS,MAAM;EAAG,OAAO;GAAC;GAAG;GAAG;EAAC;CAAE;AACnD;;;;;;;AAQA,SAAgB,UACf,MACA,UAAqG,CAAC,GACrF;CACjB,OAAO,YAAY;EAClB,SAAS,QAAQ,WAAW,YAAY,QAAQ,IAAI;EACpD,OAAO,QAAQ,IAAI;EACnB,MAAM,QAAQ,QAAQ;EACtB,SAAS,QAAQ,WAAW,aAAa,KAAK,YAAY,EAAE,GAAG,OAAO,EAAE;EACxE,KAAK,QAAQ;CACd,CAAC;AACF;;;;;;AAOA,SAAgB,IAAI,OAAc,SAAiB,OAA+B;CACjF,MAAM,QAAQ,KAAK,KAAK,UAAU,MAAM,QAAQ;CAChD,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,KAAK;EAC/B,MAAM,KAAK;EACX,IAAI,QAAQ,GAAG,QAAQ,IAAI,KAAK,MAAM;CACvC;CACA,OAAO;AACR;;;;;;AAOA,IAAa,SAAS,OAAc,UAAoB,MAAiB,QAAQ,UAChF,MAAM,MAAM;CAAE,MAAM;CAAS,QAAQ,SAAS,EAAE,CAAC;CAAO,UAAU,SAAS,KAAK,WAAW,OAAO,EAAE;CAAG,OAAO;CAAM;AAAM,CAAC"}

package/dist/tiles.d.ts

@@ -1,7 +1,7 @@
 /**
  * What the ground of a map can be painted with, named by the game: grass, road, sand. A cell holds the index of its
  * paint: 0 for none, left to the slope and the height, and 1 and up for the game's tiles in the order it gives them
- * (`GameModule.tiles`). The rules read and paint by name (`registry.tile('road')`); what each looks like is the
+ * (`Rules.tiles`). The rules read and paint by name (`registry.tile('road')`); what each looks like is the
  * view's (`GameView.ground.tiles`).
  *
  * A map file says the name of each index it was painted with (`GameMap.tileset`), so that a map keeps its paint when

package/dist/tiles.js

@@ -0,0 +1,43 @@
+//#region src/tiles.ts
+/**
+* Typed help for writing a tile
+*
+* @beta
+*/
+var defineTile = (def) => def;
+/**
+* The most tiles a game can have: a cell holds its tile in a byte, and 0 is none
+*
+* @beta
+*/
+var MAX_TILES = 255;
+/**
+* The tiles every map was painted with before maps said which: the client's list as it was then, by index. A map
+* file of format 1 means these
+*
+* @internal
+*/
+var LEGACY_TILESET = [
+	"grass",
+	"darkGrass",
+	"dirt",
+	"road",
+	"sand",
+	"rock",
+	"snow"
+];
+/**
+* The index of each tile of `from` in `to`, by name: what turns paint made with one list into paint of the other.
+* A name `to` does not have is 0, no paint
+*
+* @internal
+*/
+function tileRemap(from, to) {
+	const table = new Uint8Array(from.length + 1);
+	from.forEach((id, i) => table[i + 1] = to.indexOf(id) + 1);
+	return table;
+}
+//#endregion
+export { LEGACY_TILESET, MAX_TILES, defineTile, tileRemap };
+
+//# sourceMappingURL=tiles.js.map

package/dist/tiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiles.js","names":[],"sources":["../src/tiles.ts"],"sourcesContent":["/**\n * What the ground of a map can be painted with, named by the game: grass, road, sand. A cell holds the index of its\n * paint: 0 for none, left to the slope and the height, and 1 and up for the game's tiles in the order it gives them\n * (`Rules.tiles`). The rules read and paint by name (`registry.tile('road')`); what each looks like is the\n * view's (`GameView.ground.tiles`).\n *\n * A map file says the name of each index it was painted with (`GameMap.tileset`), so that a map keeps its paint when\n * the game adds tiles or puts them in another order: it is brought in line with the game's list by name\n *\n * @beta\n */\nexport interface TileDef {\n\t/** Shared by every game, like other ids */\n\tid: string\n\t/** What the editor's palette calls it */\n\tname: string\n\t/**\n\t * How fast one on foot goes over it, as a multiplier of its speed: mud at 0.5, a road at 1.2. 1 when left out. What\n\t * flies or sails is not slowed; the game's own `moveSpeed` rule keeps the last word (`groundSpeedAt`)\n\t */\n\tspeed?: number\n}\n\n/**\n * Typed help for writing a tile\n *\n * @beta\n */\nexport const defineTile = (def: TileDef): TileDef => def\n\n/**\n * The most tiles a game can have: a cell holds its tile in a byte, and 0 is none\n *\n * @beta\n */\nexport const MAX_TILES = 255\n\n/**\n * The tiles every map was painted with before maps said which: the client's list as it was then, by index. A map\n * file of format 1 means these\n *\n * @internal\n */\nexport const LEGACY_TILESET: readonly string[] = ['grass', 'darkGrass', 'dirt', 'road', 'sand', 'rock', 'snow']\n\n/**\n * The index of each tile of `from` in `to`, by name: what turns paint made with one list into paint of the other.\n * A name `to` does not have is 0, no paint\n *\n * @internal\n */\nexport function tileRemap(from: readonly string[], to: readonly string[]): Uint8Array {\n\tconst table = new Uint8Array(from.length + 1)\n\tfrom.forEach((id, i) => (table[i + 1] = to.indexOf(id) + 1))\n\treturn table\n}\n"],"mappings":";;;;;;AA4BA,IAAa,cAAc,QAA0B;;;;;;AAOrD,IAAa,YAAY;;;;;;;AAQzB,IAAa,iBAAoC;CAAC;CAAS;CAAa;CAAQ;CAAQ;CAAQ;CAAQ;AAAM;;;;;;;AAQ9G,SAAgB,UAAU,MAAyB,IAAmC;CACrF,MAAM,QAAQ,IAAI,WAAW,KAAK,SAAS,CAAC;CAC5C,KAAK,SAAS,IAAI,MAAO,MAAM,IAAI,KAAK,GAAG,QAAQ,EAAE,IAAI,CAAE;CAC3D,OAAO;AACR"}

package/dist/timers.d.ts

@@ -4,7 +4,7 @@ import type { System } from './registry';
 import type { World } from './world';
 /**
  * Something a game does after a while, or every so often: a wave coming, a spell wearing off, a line of dialog.
- * Made with `defineTimer` and given in `GameModule.timers`, the way listeners are, so that a loaded save finds the
+ * Made with `defineTimer` and given in `Rules.timers`, the way listeners are, so that a loaded save finds the
  * code by id: what is waiting in the world is data, which timer and with what, never a function
  *
  * @beta
@@ -12,14 +12,18 @@ import type { World } from './world';
 export interface TimerDef<T = any> {
     /** Shared by every game, like other ids: give it a prefix of the game's (`'td.waveComes'`) */
     readonly id: string;
+    /** What happens when the timer goes off: given the world, the data it was set with and which timer this is */
     run(world: World, data: T, timer: TimerInfo): void;
 }
 /**
- * Typed help: `defineTimer<{ wave: number }>('td.waveComes', (world, { wave }) => ...)`
+ * Typed help: `defineTimer<{ wave: number }>({ id: 'td.waveComes', run: (world, { wave }) => ... })`
  *
- * @beta
+ * @public
  */
-export declare function defineTimer<T = undefined>(id: string, run: (world: World, data: T, timer: TimerInfo) => void): TimerDef<T>;
+export declare function defineTimer<T = undefined>(def: {
+    id: string;
+    run: (world: World, data: T, timer: TimerInfo) => void;
+}): TimerDef<T>;
 /** A timer as it waits in the world. Plain data: it goes into a save */
 interface Waiting {
     /** Unique in the world, for `cancel` and `left` */
@@ -39,11 +43,17 @@ interface Waiting {
  * @beta
  */
 export interface WaitingTimer {
+    /** The waiting timer's id in the world, for `cancel` and `left` */
     id: number;
+    /** The id of the `TimerDef` it runs */
     timer: string;
+    /** What it was set with, handed to the timer's `run` */
     data: unknown;
+    /** Seconds until it next goes off */
     left: number;
+    /** Seconds between two times, for one that repeats */
     every?: number;
+    /** How many more times it goes off, for one that repeats a number of times */
     times?: number;
 }
 /**
@@ -65,6 +75,7 @@ export type EveryOptions<T> = {
  * @beta
  */
 export interface TimerInfo {
+    /** The id of the timer that went off, as `world.timers` gave it */
     id: number;
     /** How many more times it goes off after this one: 0 for the last, undefined for one that repeats forever */
     left?: number;
@@ -76,8 +87,11 @@ export interface TimerInfo {
  * @beta
  */
 export interface ShownTimer {
+    /** The timer's id in the world */
     id: number;
+    /** The words shown for it */
     label: Message;
+    /** The tick it goes off at, which the screen counts down to */
     at: number;
 }
 /** The timers each player is shown, by the id of each and its words: kept in the world, so that a save has them */
@@ -108,6 +122,9 @@ export declare const waitingTimers: (state: Record<string, unknown>) => string[]
 export declare class Timers {
     private readonly world;
     private readonly defs;
+    /** Those waiting as a binary heap, the first due on top (`heap`), and the list it was made of */
+    private due;
+    private heapOf;
     constructor(world: World, defs: readonly TimerDef[]);
     /** Goes off once, `seconds` from now. Returns its id, for `cancel` and `left` */
     after<T>(seconds: number, timer: TimerDef<T>, ...data: T extends undefined ? [] : [T]): number;
@@ -138,6 +155,14 @@ export declare class Timers {
     /** Sets off what is due. The `timers` system calls it at the start of every tick */
     update(): void;
     private add;
+    /**
+     * Those waiting as a heap, the first due on top: what `update` looks at, so that a tick with nothing due costs one
+     * look whatever waits. Worked out from the world's list, never saved, and made again when the list is another's (a
+     * loaded save, a state set whole)
+     */
+    private heap;
+    /** Takes the one at `index` out of the heap */
+    private take;
     private ticks;
     private state;
 }

package/dist/timers.js

@@ -0,0 +1,242 @@
+import { defineComponent } from "./components.js";
+import { toMessage } from "./messages.js";
+import { assertPlainData } from "./debug2.js";
+//#region src/timers.ts
+/**
+* Typed help: `defineTimer<{ wave: number }>({ id: 'td.waveComes', run: (world, { wave }) => ... })`
+*
+* @public
+*/
+function defineTimer(def) {
+	return def;
+}
+/** The timers each player is shown, by the id of each and its words: kept in the world, so that a save has them */
+var shownTimers = defineComponent({
+	id: "core.shownTimers",
+	default: () => ({})
+});
+/** The timers waiting in a world, kept in it so that a save has them */
+var waiting = defineComponent({
+	id: "core.timers",
+	default: () => ({
+		next: 1,
+		list: []
+	})
+});
+/** The timers waiting in the state of a save, by the id of their definition: what a game must still have to load it */
+var waitingTimers = (state) => (state[waiting.id]?.list ?? []).map((due) => due.timer);
+/** Whether `a` goes off before `b`: the one due first, then the one set first */
+var before = (a, b) => a.at < b.at || a.at === b.at && a.id < b.id;
+/** Moves the one at `index` up the heap to where nothing above it goes off later */
+function rise(heap, index) {
+	const entry = heap[index];
+	while (index > 0) {
+		const parent = index - 1 >> 1;
+		if (!before(entry, heap[parent])) break;
+		heap[index] = heap[parent];
+		index = parent;
+	}
+	heap[index] = entry;
+}
+/** Moves the one at `index` down the heap to where nothing below it goes off sooner */
+function sink(heap, index) {
+	const entry = heap[index];
+	const size = heap.length;
+	for (;;) {
+		let child = 2 * index + 1;
+		if (child >= size) break;
+		if (child + 1 < size && before(heap[child + 1], heap[child])) child++;
+		if (!before(heap[child], entry)) break;
+		heap[index] = heap[child];
+		index = child;
+	}
+	heap[index] = entry;
+}
+/**
+* The timers of a world. Time is counted in ticks, which every machine counts the same, never with the clock:
+* a timer goes off at the start of the tick it is due, after the players' commands and before anything else, in the
+* order they are due and then the order they were set
+*
+* @beta
+*/
+var Timers = class {
+	world;
+	defs = /* @__PURE__ */ new Map();
+	/** Those waiting as a binary heap, the first due on top (`heap`), and the list it was made of */
+	due = [];
+	heapOf;
+	constructor(world, defs) {
+		this.world = world;
+		for (const def of defs) {
+			if (this.defs.has(def.id)) throw new Error(`Timer "${def.id}" is there twice`);
+			this.defs.set(def.id, def);
+		}
+	}
+	/** Goes off once, `seconds` from now. Returns its id, for `cancel` and `left` */
+	after(seconds, timer, ...data) {
+		return this.add(timer, data[0], this.ticks(seconds));
+	}
+	/**
+	* Goes off every `seconds`: the first time `seconds` from now, or after `first` seconds; `times` times, or until
+	* cancelled. Returns its id
+	*/
+	every(seconds, timer, options) {
+		const every = Math.max(1, this.ticks(seconds));
+		if (options.times !== void 0 && options.times < 1) return 0;
+		return this.add(timer, options.data, options.first === void 0 ? every : this.ticks(options.first), every, options.times);
+	}
+	/** Stops a timer from going off again. Whether it was still waiting */
+	cancel(id) {
+		const state = this.state();
+		const index = state.list.findIndex((entry) => entry.id === id);
+		if (index < 0) return false;
+		const heap = this.heap(state);
+		const [gone] = state.list.splice(index, 1);
+		this.take(heap, heap.indexOf(gone));
+		return true;
+	}
+	/**
+	* Shows a player a timer (campaign plan CP5): its words and when it goes off, counted down on their screen (the HUD's
+	* timers) for as long as it waits. A timer that repeats is shown to each time it next goes off
+	*/
+	show(player, id, options) {
+		const all = { ...this.world.state(shownTimers) };
+		all[player] = [...(all[player] ?? []).filter((shown) => shown.id !== id), {
+			id,
+			label: toMessage(options.label)
+		}];
+		this.world.setState(shownTimers, all);
+	}
+	/** Shows a player a timer no more */
+	hide(player, id) {
+		const all = { ...this.world.state(shownTimers) };
+		if (!all[player]) return;
+		all[player] = all[player].filter((shown) => shown.id !== id);
+		this.world.setState(shownTimers, all);
+	}
+	/** The timers a player is shown that still wait, with the tick each goes off at next */
+	shownTo(player) {
+		const shown = this.world.states.has(shownTimers) ? this.world.state(shownTimers)[player] : void 0;
+		if (!shown?.length) return [];
+		const { list } = this.state();
+		return shown.flatMap(({ id, label }) => {
+			const entry = list.find((candidate) => candidate.id === id);
+			return entry ? [{
+				id,
+				label,
+				at: entry.at
+			}] : [];
+		});
+	}
+	/** Seconds until the timer next goes off, or undefined when it is not waiting any more */
+	left(id) {
+		const entry = this.state().list.find((candidate) => candidate.id === id);
+		return entry && (entry.at - this.world.tick) / this.world.tickRate;
+	}
+	/** Whether the timer is still waiting */
+	has(id) {
+		return this.state().list.some((entry) => entry.id === id);
+	}
+	/** What is waiting, in the order it was set: a copy, for the debug tools */
+	list() {
+		const { tickRate, tick } = this.world;
+		return this.state().list.map((entry) => ({
+			id: entry.id,
+			timer: entry.timer,
+			data: structuredClone(entry.data),
+			left: (entry.at - tick) / tickRate,
+			every: entry.every === void 0 ? void 0 : entry.every / tickRate,
+			times: entry.times
+		}));
+	}
+	/** Sets off what is due. The `timers` system calls it at the start of every tick */
+	update() {
+		const state = this.state();
+		const now = this.world.tick;
+		for (;;) {
+			const heap = this.heap(state);
+			const due = heap[0];
+			if (!due || due.at > now) return;
+			const def = this.defs.get(due.timer);
+			if (!def) throw new Error(`Timer "${due.timer}" went off, and the game has no such timer: give it in Rules.timers`);
+			const last = due.times === 1 || due.every === void 0;
+			if (last) {
+				state.list.splice(state.list.indexOf(due), 1);
+				this.take(heap, 0);
+			} else {
+				due.at += due.every;
+				if (due.times !== void 0) due.times--;
+				sink(heap, 0);
+			}
+			if (this.world.disabled.has(`timer:${due.timer}`)) continue;
+			try {
+				def.run(this.world, due.data, {
+					id: due.id,
+					left: last ? 0 : due.times
+				});
+			} catch (error) {
+				this.world.caught(error, {
+					kind: "timer",
+					id: due.timer
+				});
+			}
+		}
+	}
+	add(timer, data, after, every, times) {
+		if (!this.defs.has(timer.id)) throw new Error(`Timer "${timer.id}" is not the game's: give it in Rules.timers, so that a save can find it`);
+		if (this.world.checks.events) assertPlainData(data, `Timer "${timer.id}"`);
+		const state = this.state();
+		const id = state.next++;
+		const entry = {
+			id,
+			timer: timer.id,
+			data,
+			at: this.world.tick + Math.max(1, after),
+			every,
+			times
+		};
+		const heap = this.heap(state);
+		state.list.push(entry);
+		heap.push(entry);
+		rise(heap, heap.length - 1);
+		return id;
+	}
+	/**
+	* Those waiting as a heap, the first due on top: what `update` looks at, so that a tick with nothing due costs one
+	* look whatever waits. Worked out from the world's list, never saved, and made again when the list is another's (a
+	* loaded save, a state set whole)
+	*/
+	heap(state) {
+		if (this.heapOf !== state.list || this.due.length !== state.list.length) {
+			this.due = [...state.list].sort((a, b) => before(a, b) ? -1 : 1);
+			this.heapOf = state.list;
+		}
+		return this.due;
+	}
+	/** Takes the one at `index` out of the heap */
+	take(heap, index) {
+		const moved = heap.pop();
+		if (index >= heap.length) return;
+		heap[index] = moved;
+		rise(heap, index);
+		sink(heap, index);
+	}
+	ticks(seconds) {
+		return Math.round(seconds * this.world.tickRate);
+	}
+	state() {
+		return this.world.state(waiting);
+	}
+};
+/** Sets off the timers that are due, at the start of the tick, after the players' commands */
+var timerSystem = {
+	name: "timers",
+	phase: "commands",
+	update(world) {
+		world.timers.update();
+	}
+};
+//#endregion
+export { Timers, defineTimer, shownTimers, timerSystem, waiting, waitingTimers };
+
+//# sourceMappingURL=timers.js.map

package/dist/timers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.js","names":[],"sources":["../src/timers.ts"],"sourcesContent":["import { defineComponent } from './components'\nimport { assertPlainData } from './debug'\nimport type { PlayerId } from './entity'\nimport { type Message, type MessageRef, toMessage } from './messages'\nimport type { System } from './registry'\nimport type { World } from './world'\n\n/**\n * Something a game does after a while, or every so often: a wave coming, a spell wearing off, a line of dialog.\n * Made with `defineTimer` and given in `Rules.timers`, the way listeners are, so that a loaded save finds the\n * code by id: what is waiting in the world is data, which timer and with what, never a function\n *\n * @beta\n */\nexport interface TimerDef<T = any> {\n\t/** Shared by every game, like other ids: give it a prefix of the game's (`'td.waveComes'`) */\n\treadonly id: string\n\t/** What happens when the timer goes off: given the world, the data it was set with and which timer this is */\n\trun(world: World, data: T, timer: TimerInfo): void\n}\n\n/**\n * Typed help: `defineTimer<{ wave: number }>({ id: 'td.waveComes', run: (world, { wave }) => ... })`\n *\n * @public\n */\nexport function defineTimer<T = undefined>(def: { id: string; run: (world: World, data: T, timer: TimerInfo) => void }): TimerDef<T> {\n\treturn def\n}\n\n/** A timer as it waits in the world. Plain data: it goes into a save */\ninterface Waiting {\n\t/** Unique in the world, for `cancel` and `left` */\n\tid: number\n\ttimer: string\n\tdata: unknown\n\t/** The tick it goes off at */\n\tat: number\n\t/** Ticks between two times, for one that repeats */\n\tevery?: number\n\t/** How many times it still goes off, for one that repeats a number of times. Forever when left out */\n\ttimes?: number\n}\n\n/**\n * A timer as the debug tools show it: seconds until it goes off, and between two times\n *\n * @beta\n */\nexport interface WaitingTimer {\n\t/** The waiting timer's id in the world, for `cancel` and `left` */\n\tid: number\n\t/** The id of the `TimerDef` it runs */\n\ttimer: string\n\t/** What it was set with, handed to the timer's `run` */\n\tdata: unknown\n\t/** Seconds until it next goes off */\n\tleft: number\n\t/** Seconds between two times, for one that repeats */\n\tevery?: number\n\t/** How many more times it goes off, for one that repeats a number of times */\n\ttimes?: number\n}\n\n/**\n * How a timer repeats, and what it is given, for one whose handler takes something\n *\n * @beta\n */\nexport type EveryOptions<T> = { times?: number; first?: number } & (T extends undefined ? { data?: undefined } : { data: T })\n\n/**\n * What a timer's handler is told about the time it went off\n *\n * @beta\n */\nexport interface TimerInfo {\n\t/** The id of the timer that went off, as `world.timers` gave it */\n\tid: number\n\t/** How many more times it goes off after this one: 0 for the last, undefined for one that repeats forever */\n\tleft?: number\n}\n\n/**\n * A timer the rules show a player (`world.timers.show`): its words, and the tick it goes off at, for the screen to count\n * down to\n *\n * @beta\n */\nexport interface ShownTimer {\n\t/** The timer's id in the world */\n\tid: number\n\t/** The words shown for it */\n\tlabel: Message\n\t/** The tick it goes off at, which the screen counts down to */\n\tat: number\n}\n\n/** The timers each player is shown, by the id of each and its words: kept in the world, so that a save has them */\nexport const shownTimers = defineComponent<Record<number, { id: number; label: Message }[]>>({ id: 'core.shownTimers', default: () => ({}) })\n\n/** The timers waiting in a world, kept in it so that a save has them */\nexport const waiting = defineComponent<{ next: number; list: Waiting[] }>({ id: 'core.timers', default: () => ({ next: 1, list: [] }) })\n\n/** The timers waiting in the state of a save, by the id of their definition: what a game must still have to load it */\nexport const waitingTimers = (state: Record<string, unknown>): string[] =>\n\t((state[waiting.id] as { list?: Waiting[] } | undefined)?.list ?? []).map((due) => due.timer)\n\n/** Whether `a` goes off before `b`: the one due first, then the one set first */\nconst before = (a: Waiting, b: Waiting): boolean => a.at < b.at || (a.at === b.at && a.id < b.id)\n\n/** Moves the one at `index` up the heap to where nothing above it goes off later */\nfunction rise(heap: Waiting[], index: number): void {\n\tconst entry = heap[index]\n\twhile (index > 0) {\n\t\tconst parent = (index - 1) >> 1\n\t\tif (!before(entry, heap[parent])) break\n\t\theap[index] = heap[parent]\n\t\tindex = parent\n\t}\n\theap[index] = entry\n}\n\n/** Moves the one at `index` down the heap to where nothing below it goes off sooner */\nfunction sink(heap: Waiting[], index: number): void {\n\tconst entry = heap[index]\n\tconst size = heap.length\n\tfor (;;) {\n\t\tlet child = 2 * index + 1\n\t\tif (child >= size) break\n\t\tif (child + 1 < size && before(heap[child + 1], heap[child])) child++\n\t\tif (!before(heap[child], entry)) break\n\t\theap[index] = heap[child]\n\t\tindex = child\n\t}\n\theap[index] = entry\n}\n\n/**\n * The timers of a world. Time is counted in ticks, which every machine counts the same, never with the clock:\n * a timer goes off at the start of the tick it is due, after the players' commands and before anything else, in the\n * order they are due and then the order they were set\n *\n * @beta\n */\nexport class Timers {\n\tprivate readonly defs = new Map<string, TimerDef>()\n\t/** Those waiting as a binary heap, the first due on top (`heap`), and the list it was made of */\n\tprivate due: Waiting[] = []\n\tprivate heapOf: Waiting[] | undefined\n\n\tconstructor(\n\t\tprivate readonly world: World,\n\t\tdefs: readonly TimerDef[]\n\t) {\n\t\tfor (const def of defs) {\n\t\t\tif (this.defs.has(def.id)) throw new Error(`Timer \"${def.id}\" is there twice`)\n\t\t\tthis.defs.set(def.id, def)\n\t\t}\n\t}\n\n\t/** Goes off once, `seconds` from now. Returns its id, for `cancel` and `left` */\n\tafter<T>(seconds: number, timer: TimerDef<T>, ...data: T extends undefined ? [] : [T]): number {\n\t\treturn this.add(timer, data[0], this.ticks(seconds))\n\t}\n\n\t/**\n\t * Goes off every `seconds`: the first time `seconds` from now, or after `first` seconds; `times` times, or until\n\t * cancelled. Returns its id\n\t */\n\tevery<T>(seconds: number, timer: TimerDef<T>, options: EveryOptions<T>): number {\n\t\tconst every = Math.max(1, this.ticks(seconds))\n\t\tif (options.times !== undefined && options.times < 1) return 0\n\t\treturn this.add(timer, options.data, options.first === undefined ? every : this.ticks(options.first), every, options.times)\n\t}\n\n\t/** Stops a timer from going off again. Whether it was still waiting */\n\tcancel(id: number): boolean {\n\t\tconst state = this.state()\n\t\tconst index = state.list.findIndex((entry) => entry.id === id)\n\t\tif (index < 0) return false\n\t\tconst heap = this.heap(state)\n\t\tconst [gone] = state.list.splice(index, 1)\n\t\tthis.take(heap, heap.indexOf(gone))\n\t\treturn true\n\t}\n\n\t/**\n\t * Shows a player a timer (campaign plan CP5): its words and when it goes off, counted down on their screen (the HUD's\n\t * timers) for as long as it waits. A timer that repeats is shown to each time it next goes off\n\t */\n\tshow(player: PlayerId, id: number, options: { label: MessageRef }): void {\n\t\tconst all = { ...this.world.state(shownTimers) }\n\t\tall[player] = [...(all[player] ?? []).filter((shown) => shown.id !== id), { id, label: toMessage(options.label) }]\n\t\tthis.world.setState(shownTimers, all)\n\t}\n\n\t/** Shows a player a timer no more */\n\thide(player: PlayerId, id: number): void {\n\t\tconst all = { ...this.world.state(shownTimers) }\n\t\tif (!all[player]) return\n\t\tall[player] = all[player].filter((shown) => shown.id !== id)\n\t\tthis.world.setState(shownTimers, all)\n\t}\n\n\t/** The timers a player is shown that still wait, with the tick each goes off at next */\n\tshownTo(player: PlayerId): ShownTimer[] {\n\t\tconst shown = this.world.states.has(shownTimers) ? this.world.state(shownTimers)[player] : undefined\n\t\tif (!shown?.length) return []\n\t\tconst { list } = this.state()\n\t\treturn shown.flatMap(({ id, label }) => {\n\t\t\tconst entry = list.find((candidate) => candidate.id === id)\n\t\t\treturn entry ? [{ id, label, at: entry.at }] : []\n\t\t})\n\t}\n\n\t/** Seconds until the timer next goes off, or undefined when it is not waiting any more */\n\tleft(id: number): number | undefined {\n\t\tconst entry = this.state().list.find((candidate) => candidate.id === id)\n\t\treturn entry && (entry.at - this.world.tick) / this.world.tickRate\n\t}\n\n\t/** Whether the timer is still waiting */\n\thas(id: number): boolean {\n\t\treturn this.state().list.some((entry) => entry.id === id)\n\t}\n\n\t/** What is waiting, in the order it was set: a copy, for the debug tools */\n\tlist(): WaitingTimer[] {\n\t\tconst { tickRate, tick } = this.world\n\t\treturn this.state().list.map((entry) => ({\n\t\t\tid: entry.id,\n\t\t\ttimer: entry.timer,\n\t\t\tdata: structuredClone(entry.data),\n\t\t\tleft: (entry.at - tick) / tickRate,\n\t\t\tevery: entry.every === undefined ? undefined : entry.every / tickRate,\n\t\t\ttimes: entry.times\n\t\t}))\n\t}\n\n\t/** Sets off what is due. The `timers` system calls it at the start of every tick */\n\tupdate(): void {\n\t\tconst state = this.state()\n\t\tconst now = this.world.tick\n\t\t// one at a time, the first due of those waiting each time: a timer that goes off may set or cancel others\n\t\tfor (;;) {\n\t\t\tconst heap = this.heap(state)\n\t\t\tconst due = heap[0]\n\t\t\tif (!due || due.at > now) return\n\t\t\tconst def = this.defs.get(due.timer)\n\t\t\tif (!def) throw new Error(`Timer \"${due.timer}\" went off, and the game has no such timer: give it in Rules.timers`)\n\t\t\tconst last = due.times === 1 || due.every === undefined\n\t\t\tif (last) {\n\t\t\t\tstate.list.splice(state.list.indexOf(due), 1)\n\t\t\t\tthis.take(heap, 0)\n\t\t\t} else {\n\t\t\t\tdue.at += due.every!\n\t\t\t\tif (due.times !== undefined) due.times--\n\t\t\t\tsink(heap, 0)\n\t\t\t}\n\t\t\t// one switched off for having thrown (`World.caught`) no longer goes off: what was set is let go\n\t\t\tif (this.world.disabled.has(`timer:${due.timer}`)) continue\n\t\t\ttry {\n\t\t\t\tdef.run(this.world, due.data, { id: due.id, left: last ? 0 : due.times })\n\t\t\t} catch (error) {\n\t\t\t\tthis.world.caught(error, { kind: 'timer', id: due.timer })\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate add(timer: TimerDef, data: unknown, after: number, every?: number, times?: number): number {\n\t\tif (!this.defs.has(timer.id)) throw new Error(`Timer \"${timer.id}\" is not the game's: give it in Rules.timers, so that a save can find it`)\n\t\tif (this.world.checks.events) assertPlainData(data, `Timer \"${timer.id}\"`)\n\t\tconst state = this.state()\n\t\tconst id = state.next++\n\t\t// due at the start of a later tick: never the one that is going on\n\t\tconst entry: Waiting = { id, timer: timer.id, data, at: this.world.tick + Math.max(1, after), every, times }\n\t\tconst heap = this.heap(state)\n\t\tstate.list.push(entry)\n\t\theap.push(entry)\n\t\trise(heap, heap.length - 1)\n\t\treturn id\n\t}\n\n\t/**\n\t * Those waiting as a heap, the first due on top: what `update` looks at, so that a tick with nothing due costs one\n\t * look whatever waits. Worked out from the world's list, never saved, and made again when the list is another's (a\n\t * loaded save, a state set whole)\n\t */\n\tprivate heap(state: { list: Waiting[] }): Waiting[] {\n\t\tif (this.heapOf !== state.list || this.due.length !== state.list.length) {\n\t\t\t// sorted is a heap already\n\t\t\tthis.due = [...state.list].sort((a, b) => (before(a, b) ? -1 : 1))\n\t\t\tthis.heapOf = state.list\n\t\t}\n\t\treturn this.due\n\t}\n\n\t/** Takes the one at `index` out of the heap */\n\tprivate take(heap: Waiting[], index: number): void {\n\t\tconst moved = heap.pop()!\n\t\tif (index >= heap.length) return\n\t\theap[index] = moved\n\t\trise(heap, index)\n\t\tsink(heap, index)\n\t}\n\n\tprivate ticks(seconds: number): number {\n\t\treturn Math.round(seconds * this.world.tickRate)\n\t}\n\n\tprivate state() {\n\t\treturn this.world.state(waiting)\n\t}\n}\n\n/** Sets off the timers that are due, at the start of the tick, after the players' commands */\nexport const timerSystem: System = {\n\tname: 'timers',\n\tphase: 'commands',\n\tupdate(world) {\n\t\tworld.timers.update()\n\t}\n}\n"],"mappings":"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"}

package/dist/tomes.d.ts

@@ -31,18 +31,18 @@ export declare const gainedStats: import("./components").Component<GainedStats,
 /**
  * Gives a unit stats for good, as a tome does: added to what it gained before, kept with it in a save, its health and
  * mana raised with them. For the tomes pack's `tome` effect and a game's own rules (a shrine that makes a unit
- * stronger); it works in a game with the tomes pack (`withTomes`), which adds what was gained to the stats
+ * stronger); it works in a game with the tomes pack (`tomesPack`), which adds what was gained to the stats
  *
  * @beta
  */
 export declare function gainStats(world: World, entity: Entity, change: StatChange): void;
 /**
  * Tomes, as in classic RTS games: the `tome` effect (`EffectTypes.tome`) gives what it reaches stats for good (`gain`: a
- * point of strength with the attributes pack), a hero experience (`xp`) and levels (`levels`). A tome is an item whose
+ * point of a stat of the game's own), a hero experience (`xp`) and levels (`levels`). A tome is an item whose
  * ability has the effect, with a charge, used from the inventory, or as it is picked up with the runes pack
- * (`withRunes`). What a unit gained is kept with it and in a save (`gainedStats`), and a game gives it from its own
+ * (`runesPack`). What a unit gained is kept with it and in a save (`gainedStats`), and a game gives it from its own
  * rules with `gainStats`
  *
  * @beta
  */
-export declare function withTomes(): GamePack;
+export declare function tomesPack(): GamePack;

package/dist/tomes.js

@@ -0,0 +1,94 @@
+import { defineComponent } from "./components.js";
+import { invalidateStats, refreshVitals } from "./stats.js";
+import { grantXp, heroOf, maxLevelOf } from "./hero.js";
+import { defineEffect, effectTargets } from "./abilities/effects.js";
+//#region src/tomes.ts
+/**
+* The tomes pack's id
+*
+* @beta
+*/
+var TOMES = "core.tomes";
+/**
+* What a unit gained for good from tomes or the game's own rules (`gainStats`): saved with it
+*
+* @beta
+*/
+var gainedStats = defineComponent({ id: "core.gainedStats" });
+/**
+* Gives a unit stats for good, as a tome does: added to what it gained before, kept with it in a save, its health and
+* mana raised with them. For the tomes pack's `tome` effect and a game's own rules (a shrine that makes a unit
+* stronger); it works in a game with the tomes pack (`tomesPack`), which adds what was gained to the stats
+*
+* @beta
+*/
+function gainStats(world, entity, change) {
+	const had = entity.get(gainedStats);
+	const next = {
+		stats: { ...had?.stats },
+		percent: { ...had?.percent },
+		times: (had?.times ?? 0) + 1
+	};
+	for (const key in change.stats) next.stats[key] = (next.stats[key] ?? 0) + change.stats[key];
+	for (const key in change.percent) next.percent[key] = (next.percent[key] ?? 0) + change.percent[key];
+	entity.set(gainedStats, next);
+	invalidateStats(world, entity);
+	refreshVitals(world, entity);
+}
+/** A tome read: what it gives for good, the experience and the levels it gives a hero */
+var tomeEffect = defineEffect({
+	type: "tome",
+	run: (context, effect) => {
+		const { world } = context;
+		for (const entity of effectTargets(context, effect, "allies")) {
+			if (effect.gain) gainStats(world, entity, effect.gain);
+			if (effect.xp) grantXp(world, entity, effect.xp);
+			for (let i = 0; i < (effect.levels ?? 0); i++) {
+				const hero = heroOf(entity);
+				if (!hero || hero.level >= maxLevelOf(world, entity)) break;
+				grantXp(world, entity, world.settings.heroes.xpForLevel(hero.level + 1) - hero.xp);
+			}
+		}
+	},
+	fields: [{
+		path: "xp",
+		kind: "integer",
+		min: 0,
+		hint: "Experience a hero gains"
+	}, {
+		path: "levels",
+		kind: "integer",
+		min: 0,
+		hint: "Levels a hero gains"
+	}]
+});
+/** What was gained, added to the stats: worked out again each time something is gained */
+var gained = {
+	id: "tomes",
+	stamp: (entity) => entity.get(gainedStats)?.times ?? 0,
+	add(_world, entity, sum) {
+		const had = entity.get(gainedStats);
+		if (had) sum.add(had);
+	}
+};
+/**
+* Tomes, as in classic RTS games: the `tome` effect (`EffectTypes.tome`) gives what it reaches stats for good (`gain`: a
+* point of a stat of the game's own), a hero experience (`xp`) and levels (`levels`). A tome is an item whose
+* ability has the effect, with a charge, used from the inventory, or as it is picked up with the runes pack
+* (`runesPack`). What a unit gained is kept with it and in a save (`gainedStats`), and a game gives it from its own
+* rules with `gainStats`
+*
+* @beta
+*/
+function tomesPack() {
+	return {
+		id: TOMES,
+		components: [gainedStats],
+		effects: [tomeEffect],
+		statFields: [gained]
+	};
+}
+//#endregion
+export { TOMES, gainStats, gainedStats, tomesPack };
+
+//# sourceMappingURL=tomes.js.map