@v12-engine/engine 0.1.1 → 0.4.0

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","names":["commandRejectedEvent","commandHandledEvent"],"sources":["../src/commands.ts"],"sourcesContent":["import { commandHandled as commandHandledEvent, commandRejected as commandRejectedEvent, constructionCancelled } from '#engine/engineEvents'\nimport { aimKind } from './targeting'\nimport type { Message } from './messages'\nimport type { RejectedKind } from './errors'\nimport { productionOf } from './systems/productionQueue'\nimport { statsOf } from './stats'\nimport { constructionSite, underConstruction } from './systems/construction'\nimport { isStunned } from './abilities/buffs'\nimport { steerMissile } from './abilities/effects'\nimport { dashing } from './dashing'\nimport type { Entity, EntityId, PlayerId } from './entity'\nimport { bool, type Checked, type Fields, id, ids, index, Invalid, number, object, oneOf, optional, point, string } from './fields'\nimport { formationPoints } from './formation'\nimport { distSq, type Vec2 } from './math'\nimport { castAside, notReady } from './orders/cast'\nimport { createOrder, giveOrder, interrupt } from './orders/queue'\nimport { giveBack } from './player'\nimport type { OrderInit } from './registry'\nimport { smartOrder } from './smart'\nimport { chat, ping } from './talk'\nimport { give, shareWith } from './trade'\nimport { askPause, surrender } from './endings'\nimport { canAttack } from './systems/combat'\nimport { runOrder } from './systems/orders'\nimport { joinFormation } from './systems/movement'\nimport { cameraCommanded, cameraCommandFields } from './cameraOrders'\nimport { CINEMATIC_OUTCOMES, cinematicChose, cinematicEnded } from './cinematics'\nimport { cancelProduction, enqueueMorph, enqueueProduction, enqueueResearch } from './systems/production'\nimport type { World } from './world'\nimport { atan2 } from './exactMath'\nimport { fighting, moving } from './entity'\nimport { replicateEvent } from './replication'\n\n/**\n * Commands are everything a player can ask for: plain data, and the only way input reaches the simulation,\n * which keeps the door open for replays, the AI and multiplayer.\n *\n * A command type is a `CommandDef`: the fields it carries, and what it does. What arrives is checked against the\n * fields before anything happens, because on a server it is whatever anyone sends. The engine's own commands are\n * defined the same way as a game module's (`Rules.commands`).\n *\n * @beta\n */\nexport interface CommandDef<F extends Fields = Fields> {\n\t/** The command's name, which a sent command carries as its `type` */\n\ttype: string\n\t/** What it carries, besides its type and the player who sent it. See `fields.ts` for the checkers */\n\tfields: F\n\t/** Carries it out, for `player`. Whether the player owns or can see what it names is for this to check */\n\texecute(world: World, player: PlayerId, command: Checked<F>): void\n\t/**\n\t * Carried out at once when given between two ticks, a paused game's too, not at the start of the next (`World.issue`):\n\t * talk, a line of chat or a ping, which a game that waits is still to hear. Counted by the talk's own rate, not the\n\t * commands a tick may have; a replay keeps it where it was given (RV14)\n\t */\n\toutsideTick?: boolean\n}\n\ndeclare const modCommandBrand: unique symbol\n\n/**\n * A command of a game module, as its definition's `make` puts it together. Sessions send it like the engine's own\n *\n * @beta\n */\nexport type ModCommand = { readonly type: string; readonly [modCommandBrand]: true }\n\n/**\n * A command type, with `make` to put one together for a session to send\n *\n * @beta\n */\nexport type DefinedCommand<T extends string, F extends Fields> = CommandDef<F> & {\n\ttype: T\n\tmake(fields: Checked<F>): ModCommand\n}\n\n/**\n * Defines a command type, for a game module's `commands`: its type, its fields (see `fields.ts`), and what it does.\n * `command` is typed by the fields.\n *\n * ```ts\n * const sellTower = defineCommand('sellTower', { tower: id }, (world, player, command) => { ... })\n * session.send(sellTower.make({ tower: 12 }))\n * ```\n *\n * @public\n */\nexport function defineCommand<const T extends string, F extends Fields>(\n\ttype: T,\n\tfields: F,\n\texecute: (world: World, player: PlayerId, command: Checked<F>) => void,\n\toptions: { outsideTick?: boolean } = {}\n): DefinedCommand<T, F> {\n\t// what every command carries of its own: a field of the same name would be written over on the way in\n\tfor (const own of ['type', 'player', 'seq']) {\n\t\tif (own in fields)\n\t\t\tthrow new Error(`Command \"${type}\": \"${own}\" is what every command carries (who sent it, and the like), name the field otherwise`)\n\t}\n\treturn {\n\t\ttype,\n\t\tfields,\n\t\texecute,\n\t\t...(options.outsideTick && { outsideTick: true }),\n\t\tmake: (values) => ({ ...values, type }) as unknown as ModCommand\n\t}\n}\n\n/** What a command looks like on its way in: its type, who sent it, and its fields */\ntype CommandOf<D> = D extends DefinedCommand<infer T, infer F> ? { type: T; player: PlayerId } & Checked<F> : never\n\n/** Part of the cost returned when a construction site is cancelled */\n\n/** The buildings something is to be made in: the selected ones, of which the least busy gets it. `building` for just one */\n/** @internal */\nexport const producers = { building: optional(id), buildings: optional(ids) }\n\n/**\n * Of the player's buildings that were named, the one that will get to something first: finished, able to make it,\n * and with the shortest queue that has room. As in classic RTS games, a group of barracks shares the work. When none has\n * room, the first that could make it, which then says its queue is full\n *\n * @internal\n */\nexport function leastBusy(\n\tworld: World,\n\tplayer: PlayerId,\n\tcommand: { building?: EntityId; buildings?: EntityId[] },\n\tfits: (entity: Entity) => boolean\n): Entity | undefined {\n\tconst named = [...(command.building !== undefined ? [command.building] : []), ...(command.buildings ?? [])]\n\tlet best: Entity | undefined\n\tlet first: Entity | undefined\n\tfor (const entity of owned(world, player, named)) {\n\t\tconst production = productionOf(entity)\n\t\tif (!production || !entity.operational || !fits(entity)) continue\n\t\tfirst ??= entity\n\t\tconst length = production.queue.length\n\t\tif (length < world.settings.production.queue && (!best || length < productionOf(best)!.queue.length)) best = entity\n\t}\n\treturn best ?? first\n}\n\n/**\n * The units a command names that the player may command: their own, and what another shares control of with them\n * (`world.mayCommand`). One of another's, or one there never was, is what their own client never sends: it is\n * turned away (`commandRejected`), and the rest goes on. One that has died meanwhile is let be\n *\n * @internal\n */\nexport function owned(world: World, player: PlayerId, ids: EntityId[]): Entity[] {\n\tconst result: Entity[] = []\n\tfor (const id of ids) {\n\t\tconst entity = world.get(id)\n\t\tif (entity && world.mayCommand(player, entity)) result.push(entity)\n\t\telse if (entity) world.events.emit(commandRejectedEvent, { player, kind: 'notTheirs', reason: `unit ${id} is not theirs` })\n\t\telse if (!world.made(id)) world.events.emit(commandRejectedEvent, { player, kind: 'noSuchUnit', reason: `there is no unit ${id}` })\n\t}\n\treturn result\n}\n\n/** Direction from the middle of a group to where it was sent, so the whole group ends up facing the same way */\nfunction travelDirection(entities: Entity[], point: Vec2): number | undefined {\n\tlet x = 0\n\tlet z = 0\n\tfor (const entity of entities) {\n\t\tx += entity.pos.x\n\t\tz += entity.pos.z\n\t}\n\tx = point.x - x / entities.length\n\tz = point.z - z / entities.length\n\treturn x * x + z * z > 0.04 ? atan2(x, z) : undefined\n}\n\n/**\n * Entity a player may point at: one their team sees, a structure they have seen before, or, on a map explored from\n * the start, a structure of nobody's (a tree, a mine). Commands naming anything else are probing for what the player\n * cannot know.\n *\n * @internal\n */\nexport function known(world: World, player: PlayerId, id: EntityId | undefined): Entity | undefined {\n\tconst entity = world.get(id)\n\tif (!entity) return undefined\n\tconst { team } = world.player(player)\n\tif (world.areAllies(entity.owner, player) || world.isVisibleTo(entity, team)) return entity\n\tif (!entity.isStructure) return undefined\n\tif (world.sight.hasSeen(entity, team)) return entity\n\t// on a map explored from the start, what stands on it and is no player's (trees, mines, the creeps' own) is known\n\t// from the first snapshot, out of sight, as the session tells it (`TeamMemory.startKnown`): an order on it stands\n\tconst owner = world.players.get(entity.owner)\n\treturn world.fog.exploredFromStart && (owner?.neutral || owner?.creeps) ? entity : undefined\n}\n\n/** What a unit is told to do, as a command carries it. See `OrderInit` */\nconst orderInit = object({\n\ttype: string,\n\ttarget: optional(id),\n\tpoint: optional(point),\n\tunitType: optional(string),\n\tability: optional(string),\n\titem: optional(index),\n\tfacing: optional(number),\n\tpath: optional(string),\n\ttowards: optional(oneOf('first', 'last')),\n\tformation: optional(string),\n\ttogether: optional(bool)\n})\n\n// ---- the engine's commands\n\n/**\n * The engine's `order` command: gives an order to entities the player owns, replacing theirs or queued after them\n *\n * @internal\n */\nexport const orderCommand = defineCommand(\n\t'order',\n\t{ entities: ids, order: orderInit, queue: optional(bool) },\n\t(world, player, { entities: chosen, order: init, queue = false }) => {\n\t\tif (!world.registry.orders.has(init.type)) return\n\t\tif (init.target && !known(world, player, init.target)) return\n\t\tconst behavior = world.registry.order(init.type)\n\t\tlet entities = owned(world, player, chosen).filter((entity) => !entity.has(constructionSite) && behavior.accepts(world, entity, init))\n\t\t// what is carried and used on the spot does not stop whoever carries it\n\t\tif (init.type === 'cast' && init.item !== undefined && !queue) entities = entities.filter((entity) => !castAside(world, entity, init))\n\t\t// told to attack what it is attacking already: it goes on as it was, and only what was to come after is dropped\n\t\tif (init.type === 'attack' && init.target !== undefined && !queue) {\n\t\t\tentities = entities.filter((entity) => {\n\t\t\t\tconst current = entity.orders[0]\n\t\t\t\tif (current?.type !== 'attack' || current.init.target !== init.target) return true\n\t\t\t\tentity.keepOrders(1)\n\t\t\t\treturn false\n\t\t\t})\n\t\t}\n\t\tif (entities.length === 0) return\n\n\t\tconst groupId = world.newId()\n\t\tconst facing = init.facing ?? (init.point && !init.target ? travelDirection(entities, init.point) : undefined)\n\t\t// those who walk line up on the ground, those who fly above it\n\t\tconst points = new Map<EntityId, Vec2>()\n\t\tif (behavior.formation && init.point && !init.target && entities.length > 1) {\n\t\t\tconst id = init.formation ?? world.settings.movement.formation(world, entities, init)\n\t\t\t// a formation nobody knows is no formation: the units go as the rules have them, rather than nowhere\n\t\t\tconst formation = world.registry.formations.has(id)\n\t\t\t\t? world.registry.formation(id)\n\t\t\t\t: world.registry.formation(world.settings.movement.formation(world, entities, init))\n\t\t\tconst flyers = entities.filter((entity) => entity.flying)\n\t\t\tconst walkers = entities.filter((entity) => !entity.flying)\n\t\t\tfor (const [id, point] of formationPoints(world, walkers, init.point, formation, init.facing)) points.set(id, point)\n\t\t\tfor (const [id, point] of formationPoints(world, flyers, init.point, formation, init.facing)) points.set(id, point)\n\t\t}\n\t\t// a group that goes together goes at its slowest's pace: what the slowest of them goes, as they are now\n\t\tconst together = init.type === 'move' && !init.target && entities.length > 1 && (init.together ?? false)\n\t\tconst speedCap = together ? Math.min(...entities.map((entity) => statsOf(world, entity).moveSpeed)) : undefined\n\t\tfor (const entity of entities) {\n\t\t\tconst point = points.get(entity.id) ?? init.point\n\t\t\tgiveOrder(world, entity, createOrder(world, { ...init, point, facing, ...(speedCap !== undefined && { speedCap }) }, groupId), queue)\n\t\t\t// one of a formation: it keeps its place in it, and swaps places with the others on the way (`MovementState.formation`)\n\t\t\tif (points.has(entity.id) && entity.orders.at(-1)?.groupId === groupId) joinFormation(entity, groupId)\n\t\t}\n\t}\n)\n\n/**\n * The engine's `rally` command: sets where the units a building makes go, a point or an entity\n *\n * @internal\n */\nexport const rallyCommand = defineCommand('rally', { buildings: ids, point, target: optional(id) }, (world, player, command) => {\n\tconst target = known(world, player, command.target)\n\tfor (const building of owned(world, player, command.buildings)) {\n\t\tconst production = productionOf(building)\n\t\tif (!production) continue\n\t\t// clicking the building itself clears the rally point\n\t\tif (target === building) production.rally = null\n\t\telse production.rally = { point: { x: command.point.x, z: command.point.z }, target: target?.id ?? 0 }\n\t}\n})\n\n/**\n * The right-click: every unit does what makes sense for it, buildings set their rally point\n *\n * @internal\n */\nexport const smartCommand = defineCommand(\n\t'smart',\n\t{ entities: ids, point, target: optional(id), queue: optional(bool), formation: optional(string), facing: optional(number) },\n\t(world, player, { point, queue, formation, facing, ...command }) => {\n\t\tconst target = known(world, player, command.target)\n\t\tconst entities = owned(world, player, command.entities)\n\t\tconst units = entities.filter((entity) => entity.get(moving))\n\t\tif (units.length === 0) {\n\t\t\trallyCommand.execute(world, player, { buildings: entities.map((entity) => entity.id), point, target: target?.id })\n\t\t\treturn\n\t\t}\n\t\t// units that end up with the same order are commanded together, so they move as a group\n\t\tconst groups = new Map<string, { order: OrderInit; ids: EntityId[] }>()\n\t\tfor (const unit of units) {\n\t\t\tconst order = smartOrder(world, unit, point, target)\n\t\t\tif (!order) continue\n\t\t\tif (formation !== undefined) order.formation = formation\n\t\t\tif (facing !== undefined && !target) order.facing = facing\n\t\t\t// moves of a group together, where the rules say (not attack-moves: those fight their way, each as it can)\n\t\t\tif (order.type === 'move' && world.settings.movement.together) order.together = true\n\t\t\tconst key = `${order.type}:${order.target ?? ''}`\n\t\t\tlet group = groups.get(key)\n\t\t\tif (!group) groups.set(key, (group = { order, ids: [] }))\n\t\t\tgroup.ids.push(unit.id)\n\t\t}\n\t\tfor (const group of groups.values()) orderCommand.execute(world, player, { entities: group.ids, order: group.order, queue })\n\t}\n)\n\n/**\n * Attack the target, for whoever can. Everyone else, or without a target: attack-move to the point\n *\n * @internal\n */\nexport const attackCommand = defineCommand(\n\t'attack',\n\t{ entities: ids, point, target: optional(id), queue: optional(bool), formation: optional(string) },\n\t(world, player, { point, queue, formation, ...command }) => {\n\t\tconst target = known(world, player, command.target)\n\t\tconst units = owned(world, player, command.entities).filter((entity) => entity.get(moving) || entity.get(fighting))\n\t\tconst attackers = target ? units.filter((unit) => canAttack(world, unit, target, true)) : []\n\t\tif (target && attackers.length) {\n\t\t\torderCommand.execute(world, player, { entities: attackers.map((unit) => unit.id), order: { type: 'attack', target: target.id }, queue })\n\t\t\treturn\n\t\t}\n\t\torderCommand.execute(world, player, { entities: units.map((unit) => unit.id), order: { type: 'attackMove', point }, queue })\n\t}\n)\n\n/**\n * Use an ability. Abilities that need a target are cast by one unit, the one that can and is closest\n *\n * @internal\n */\nexport const castCommand = defineCommand(\n\t'cast',\n\t{ entities: ids, ability: string, point: optional(point), to: optional(point), target: optional(id), queue: optional(bool) },\n\t(world, player, command) => {\n\t\tconst { queue } = command\n\t\tif (!world.registry.abilities.has(command.ability)) return\n\t\tconst ability = world.registry.ability(command.ability)\n\t\tconst target = known(world, player, command.target)\n\t\tif (command.target && !target) return\n\t\tconst init: OrderInit = { type: 'cast', ability: ability.id, target: target?.id, point: command.point, ...(command.to && { to: command.to }) }\n\t\tconst kind = aimKind(world.registry, ability)\n\t\tconst behavior = world.registry.order('cast')\n\t\tconst casters = owned(world, player, command.entities).filter((entity) => behavior.accepts(world, entity, init))\n\t\tif (casters.length === 0) return\n\n\t\t// what goes off on the spot goes off now: a move given in the same breath must not get in first\n\t\tconst instant = !queue && !ability.castTime && (kind === 'none' || kind === 'direction')\n\t\tconst give = (caster: Entity) => {\n\t\t\tconst order = createOrder(world, init)\n\t\t\tgiveOrder(world, caster, order, queue)\n\t\t\t// only what it was given: an order the rules refused (`beforeOrder`), or a unit under control did not take, is in no queue\n\t\t\tif (instant && caster.orders[0] === order && !isStunned(world, caster) && !caster.get(dashing)?.pulled) runOrder(world, caster, order, 0)\n\t\t}\n\t\tif (kind === 'none') {\n\t\t\tfor (const caster of casters) {\n\t\t\t\tif (queue) give(caster)\n\t\t\t\t// on the spot, in the middle of whatever the caster is doing\n\t\t\t\telse if (!notReady(world, caster, ability) && !castAside(world, caster, { ability: ability.id })) give(caster)\n\t\t\t}\n\t\t\treturn\n\t\t}\n\t\tconst aim = target?.pos ?? command.point\n\t\tconst ready = casters.filter((caster) => !notReady(world, caster, ability))\n\t\tconst pool = ready.length ? ready : casters\n\t\tlet best = pool[0]\n\t\tfor (const caster of pool) {\n\t\t\tif (aim && distSq(caster.pos, aim) < distSq(best.pos, aim)) best = caster\n\t\t}\n\t\t// towards somewhere, at once: in the middle of whatever the caster is doing, like the ones cast on the spot\n\t\tif (instant && !notReady(world, best, ability) && castAside(world, best, { ability: ability.id }, command.point)) return\n\t\t// with nobody ready the order still goes out, so the player hears why it failed\n\t\tgive(best)\n\t}\n)\n\n/**\n * Turns the player's missiles of an ability that are steered (`EffectFields.steer`) towards a point, as they fly\n * (`steerMissile`): what the screen sends while one is in the air, for where the pointer is\n *\n * @beta\n */\nexport const steerCommand = defineCommand('steer', { ability: string, point }, (world, player, command) => {\n\tfor (const missile of world.missiles) if (missile.owner === player && missile.ability === command.ability) steerMissile(world, missile, command.point)\n})\n\n/**\n * The engine's `autocast` command: turns an ability's autocast on or off for the entities named\n *\n * @internal\n */\nexport const autocastCommand = defineCommand('autocast', { entities: ids, ability: string, enabled: bool }, (world, player, command) => {\n\tfor (const entity of owned(world, player, command.entities)) {\n\t\tconst state = entity.abilities.find((ability) => ability.id === command.ability)\n\t\tif (state) state.autocast = command.enabled\n\t}\n})\n\n/**\n * Stops what units are doing, as the classic Stop does: a plain interrupt. They fight what comes near again at once; a\n * unit that is to stand down and take no fights is put in a stance (`stanceCommand`, `stancesPack`)\n *\n * @beta\n */\nexport const stopCommand = defineCommand('stop', { entities: ids }, (world, player, command) => {\n\tfor (const entity of owned(world, player, command.entities)) interrupt(world, entity)\n})\n\n/**\n * The engine's `train` command: queues a unit type at the least busy building that can train it\n *\n * @internal\n */\nexport const trainCommand = defineCommand('train', { ...producers, unitType: string }, (world, player, command) => {\n\tconst building = leastBusy(world, player, command, (entity) => !!entity.def.trains?.includes(command.unitType))\n\tif (building) enqueueProduction(world, building, command.unitType)\n})\n\n/**\n * The engine's `research` command: queues an upgrade at the least busy building that can research it\n *\n * @internal\n */\nexport const researchCommand = defineCommand('research', { ...producers, upgrade: string }, (world, player, command) => {\n\tconst building = leastBusy(world, player, command, (entity) => !!entity.def.researches?.includes(command.upgrade))\n\tif (building) enqueueResearch(world, building, command.upgrade)\n})\n\n/**\n * Upgrades a building into a type it can become: `into`, one of its `upgradesTo`, or the first where none is named\n *\n * @internal\n */\nexport const upgradeBuildingCommand = defineCommand('upgradeBuilding', { building: id, into: optional(string) }, (world, player, command) => {\n\tconst [building] = owned(world, player, [command.building])\n\tif (building) enqueueMorph(world, building, command.into)\n})\n\n/**\n * The engine's `cancelTrain` command: takes the item at an index out of a building's queue\n *\n * @internal\n */\nexport const cancelTrainCommand = defineCommand('cancelTrain', { building: id, index }, (world, player, command) => {\n\tconst [building] = owned(world, player, [command.building])\n\tif (building) cancelProduction(world, building, command.index)\n})\n\n/**\n * The engine's `cancelConstruction` command: stops a building under construction, refunds part of its cost and removes it\n *\n * @internal\n */\nexport const cancelConstructionCommand = defineCommand('cancelConstruction', { building: id }, (world, player, command) => {\n\tconst [building] = owned(world, player, [command.building])\n\tconst site = building && underConstruction(building)\n\tif (!site) return\n\tgiveBack(world, player, site.paid ?? building.def.cost, world.settings.production.cancelRefund, 'structure', building.def.id)\n\tworld.events.emit(constructionCancelled, building)\n\tworld.kill(building, undefined, false, 'cancelled')\n})\n\n/** The player skips the line of dialog they hear: a conversation goes on to its next line. See `world.dialog` */\nexport const skipLineCommand = defineCommand('skipLine', {}, (world, player) => world.dialog.skip(player))\n\n/** A player marks a spot of the map for their allies: `look`, `danger`, `assist` or `onMyWay` (see `ping`) */\nexport const pingCommand = defineCommand(\n\t'ping',\n\t{ point, kind: optional(string), to: optional(string), by: optional(string) },\n\t(world, player, command) => ping(world, player, command.point, command.kind, command.to, command.by),\n\t{ outsideTick: true }\n)\n\n/** A player says a line of chat: to `allies` (when left out), or to `all` (see `chat`) */\nexport const chatCommand = defineCommand(\n\t'chat',\n\t{ text: string, to: optional(string), by: optional(string) },\n\t(world, player, command) => chat(world, player, command.text, command.to, command.by),\n\t{ outsideTick: true }\n)\n\n/** A player gives an ally some of a resource they have (see `give`) */\nexport const giveCommand = defineCommand('give', { to: id, resource: string, amount: number }, (world, player, command) =>\n\tgive(world, player, command.to, command.resource, command.amount)\n)\n\n/** A player shares control of their units, or their team's sight, with an ally, or no longer (see `shareWith`) */\nexport const shareCommand = defineCommand('share', { with: id, vision: optional(bool), control: optional(bool) }, (world, player, command) =>\n\tshareWith(world, player, command.with, { vision: command.vision, control: command.control })\n)\n\n/**\n * A player gives up: out of the game, as if beaten (see `surrender`)\n *\n * @internal\n */\nexport const surrenderCommand = defineCommand('surrender', {}, (world, player) => surrender(world, player))\n\n/**\n * A player asks for the game to be paused, one of their pauses (see `askPause`): whoever runs it pauses it\n *\n * @internal\n */\nexport const pauseCommand = defineCommand('pause', {}, (world, player) => askPause(world, player))\n\n/**\n * A player's own screen says something of its camera (see `cameraFor`): being a command, a replay has it. A seat that\n * names another's (`seat`) is refused\n *\n * @internal\n */\nexport const cameraCommand = defineCommand('camera', cameraCommandFields, cameraCommanded)\n\n/**\n * A player's screen says a cinematic the rules played on it is over, and how (see `cinematic`'s `wait`): sent by the\n * client as the cinematic ends, so that the rules hear it in the same tick on every machine and in a replay\n *\n * @internal\n */\nexport const cinematicCommand = defineCommand('cinematic', { cinematic: string, outcome: oneOf(...CINEMATIC_OUTCOMES) }, (world, player, command) =>\n\tcinematicEnded(world, player, command.cinematic, command.outcome)\n)\n\n/**\n * A player's screen says which answer of a cinematic's choice they picked (C3): heard by the rules in the same tick on\n * every machine and in a replay, as `cinematicChoice`\n *\n * @internal\n */\nexport const cinematicChoiceCommand = defineCommand(\n\t'cinematicChoice',\n\t{ cinematic: string, question: string, choice: string, timedOut: optional(bool) },\n\t(world, player, command) =>\n\t\tcinematicChose(world, { player, cinematic: command.cinematic, question: command.question, choice: command.choice, timedOut: !!command.timedOut })\n)\n\n/**\n * The commands the engine knows, which every game has\n *\n * @beta\n */\nexport const coreCommands = [\n\tcameraCommand,\n\torderCommand,\n\tsmartCommand,\n\tattackCommand,\n\tcastCommand,\n\tsteerCommand,\n\tautocastCommand,\n\tstopCommand,\n\ttrainCommand,\n\tresearchCommand,\n\tupgradeBuildingCommand,\n\tcancelTrainCommand,\n\trallyCommand,\n\tcancelConstructionCommand,\n\tskipLineCommand,\n\tpingCommand,\n\tchatCommand,\n\tgiveCommand,\n\tshareCommand,\n\tsurrenderCommand,\n\tpauseCommand,\n\tcinematicCommand,\n\tcinematicChoiceCommand\n] as const\n\n/**\n * The commands a world takes, by who defines them: the engine's (`core`), and each pack's, which adds its own by\n * declaration merging, as the heroes pack does:\n *\n * ```ts\n * declare module '@v12-engine/engine' {\n * \tinterface Commands {\n * \t\tmypack: (typeof myPackCommands)[number]\n * \t}\n * }\n * ```\n *\n * @beta\n */\nexport interface Commands {\n\t/** The engine's commands, as a union of their types; a game or pack adds its own by merging into `Commands` */\n\tcore: (typeof coreCommands)[number]\n}\n\n/**\n * A command a world takes, as it comes in: its type, who sent it, and its fields. The engine's, and its packs'\n * (`Commands`)\n *\n * @beta\n */\nexport type Command = CommandOf<Commands[keyof Commands]>\n\n/**\n * Any command on its way in: the engine's own, or a game module's\n *\n * @beta\n */\nexport type IssuedCommand = (Command | (ModCommand & { player: PlayerId })) & {\n\t/** The sender's own number for it, told back with how it went (`commandHandled`): what a screen waits on */\n\tseq?: number\n}\n\n/** Type and sender, the part every command has */\nconst head = object({ type: string, player: id })\n\n/**\n * Checks a command and carries it out. A command that is not what it says it is (an unknown type, a field missing\n * or of the wrong kind, a player that is not in the game) is turned away with `commandRejected`, and changes nothing\n */\nexport function executeCommand(world: World, raw: unknown): void {\n\tlet def: CommandDef\n\tlet player: PlayerId\n\tlet fields: Checked<Fields>\n\tlet kind: RejectedKind = 'badFields'\n\ttry {\n\t\tconst { type, player: sender } = head(raw, 'command')\n\t\tconst found = world.registry.command(type)\n\t\tkind = 'unknownType'\n\t\tif (!found) throw new Invalid(`there is no command \"${type}\"`)\n\t\tkind = 'noSuchPlayer'\n\t\tif (!world.players.has(sender)) throw new Invalid(`there is no player ${sender}`)\n\t\tkind = 'badFields'\n\t\tdef = found\n\t\tplayer = sender\n\t\tfields = object(def.fields)(raw, '')\n\t} catch (error) {\n\t\tif (!(error instanceof Invalid)) throw error\n\t\tconst { type, player, seq } = (typeof raw === 'object' && raw ? raw : {}) as Record<string, unknown>\n\t\tconst sender = typeof player === 'number' ? player : undefined\n\t\tworld.events.emit(commandRejectedEvent, { player: sender, type: typeof type === 'string' ? type : undefined, kind, reason: error.message })\n\t\tif (sender !== undefined && typeof seq === 'number')\n\t\t\tworld.events.emit(commandHandledEvent, { player: sender, seq, refusal: { key: error.message } })\n\t\treturn\n\t}\n\tconst seq = (raw as { seq?: unknown }).seq\n\t// who is out has no say any more\n\tif (world.player(player).defeated) {\n\t\tif (typeof seq === 'number') world.events.emit(commandHandledEvent, { player, seq, refusal: { key: 'defeated' } })\n\t\treturn\n\t}\n\t// what the rules refuse it with as it is carried out, they tell the player: the first of it is the answer\n\tconst handling = { player, refusal: undefined as Message | undefined }\n\tworld.handling = handling\n\ttry {\n\t\tdef.execute(world, player, fields)\n\t} catch (error) {\n\t\t// what the world says of errors (`World.caught`): it throws, or the command is refused and the tick goes on\n\t\tworld.caught(error, { kind: 'command', id: def.type, player })\n\t\thandling.refusal ??= { key: 'failed' }\n\t} finally {\n\t\tworld.handling = undefined\n\t}\n\tif (typeof seq === 'number') world.events.emit(commandHandledEvent, { player, seq, refusal: handling.refusal })\n}\n\n/** What became of a command: to whoever sent it */\nexport const toldCommand = replicateEvent(commandHandledEvent, 'command', ({ player, seq, refusal }, view) =>\n\tplayer === view.player ? { type: 'command', seq, ...(refusal ? { refusal } : {}) } : undefined\n)\n"],"mappings":"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"}

package/dist/components.d.ts

@@ -9,7 +9,8 @@ import type { World } from './world';
  * and nothing else.
  *
  * A component is plain data, so that it goes into a save with the rest of the world (see `saveWorld`): numbers,
- * text, lists and plain objects, with other entities by id.
+ * text, lists and plain objects, with other entities by id. One kept otherwise while the game runs (a `Map`, bytes)
+ * says how it is saved and loaded (`save`, `load`), wherever it is held.
  *
  * `T` is what the component holds; `S` is what a player's snapshot carries of it (`snapshot`), `T` itself when it is
  * sent as it is
@@ -17,6 +18,7 @@ import type { World } from './world';
  * @beta
  */
 export interface Component<T, S = T> {
+    /** The component's id, which saves and snapshots keep it under */
     readonly id: string;
     /** What it starts as. Needed for world and player state, which is there from the moment it is asked for */
     readonly default?: () => T;
@@ -86,13 +88,19 @@ export interface Component<T, S = T> {
     passable?(value: T, entity: Entity): boolean;
     /**
      * What a save keeps of it, where that is not its value as it is (plain data: numbers, text, lists, plain objects): a
-     * `Map` as its entries, an effect as where it is in its ability. Its value as it is when left out, which has to be
-     * plain data then
+     * `Map` as its entries, an effect as where it is in its ability, bytes kept for speed as the record a save has always
+     * had. Its value as it is when left out, which has to be plain data then. For each of its holders: an entity, the
+     * world (`world.state`) and a player (`player.state`)
      *
      * @beta
      */
     save?(value: T, world: World): unknown;
-    /** It again, of what `save` gave, as a save is loaded: the save's value as it is when left out @beta */
+    /**
+     * It again, of what `save` gave, as a save is loaded: the save's value as it is when left out. Given a copy of the
+     * save's, its own to keep or change
+     *
+     * @beta
+     */
     load?(saved: unknown, registry: Registry): T;
     /**
      * The ids of the game's definitions a save of it names (of what `save` gave, or its value): what a save is checked
@@ -109,13 +117,22 @@ export interface Component<T, S = T> {
  * @beta
  */
 export interface SavedRefs {
+    /** Ids of unit types the saved value names */
     units?: readonly string[];
+    /** Ids of abilities the saved value names */
     abilities?: readonly string[];
+    /** Ids of buffs the saved value names */
     buffs?: readonly string[];
+    /** Ids of items the saved value names */
     items?: readonly string[];
+    /** Ids of upgrades the saved value names */
     upgrades?: readonly string[];
 }
-/** @beta */
+/**
+ * Who a part of a snapshot is for: the owner alone, the owner and allies, or everyone
+ *
+ * @beta
+ */
 export type Audience = 'owner' | 'allies' | 'everyone';
 /**
  * A map field of a component's: as a game's own field on a map (`MapFieldDef`), its id the component's
@@ -129,6 +146,7 @@ export type ComponentFieldDef = Omit<MapFieldDef, 'id'>;
  * @beta
  */
 export interface SnapshotView {
+    /** The world the snapshot is made from */
     readonly world: World;
     /** The player it is made for; `undefined` for an observer */
     readonly player: PlayerId | undefined;
@@ -136,6 +154,7 @@ export interface SnapshotView {
     readonly own: boolean;
     /** Whether the entity's owner is the player, or an ally of theirs (an observer is everyone's) */
     readonly ally: boolean;
+    /** Whether the snapshot is for an observer, who has no player */
     readonly observer: boolean;
     /** Whether the player's team can see another entity right now (`SessionView.knows`): what else of it the part may name */
     readonly knows: (entity: Entity) => boolean;
@@ -151,17 +170,19 @@ export interface SnapshotView {
  */
 export type ComponentOptions<T, S = T> = Omit<Component<T, S>, 'id' | 'slot'>;
 /**
- * A typed key for state of a game's own: `const wave = defineComponent<WaveState>('td.waves', { default: () => ... })`.
+ * A typed key for state of a game's own: `const wave = defineComponent<WaveState>({ id: 'td.waves', default: () => ... })`.
  * Give it a prefix of the game's or the mod's: the engine's own are `core.`. A game lists its own
- * (`GameModule.components`), and its world finds them by id in its registry: another game of the process may have one
+ * (`Rules.components`), and its world finds them by id in its registry: another game of the process may have one
  * of the same id, and a module loaded again (as a dev server does) defines it again.
  *
  * With `snapshot` and `same` the component shapes what players are sent of it and how a change is found; with `index`
  * it is filed for systems to go through; with `field` the map editor sets it
  *
- * @beta
+ * @public
  */
-export declare function defineComponent<T, S = T>(id: string, options?: ComponentOptions<T, S>): Component<T, S>;
+export declare function defineComponent<T, S = T>(def: {
+    id: string;
+} & ComponentOptions<T, S>): Component<T, S>;
 /**
  * What a snapshot carries of a component, typed: `snapshotOf(entity.state, shopStock)` on a screen, or in a computer
  * player's view. `undefined` when the player was not told it
@@ -176,7 +197,7 @@ export declare function snapshotOf<T, S>(state: {
  * component's default
  */
 export declare class StateStore {
-    /** By component id. Plain data, for a save */
+    /** By component id. Plain data, or what its component's `save` writes as plain data (`Component.save`) */
     readonly values: Record<string, unknown>;
     get<T>(key: Component<T, unknown>): T;
     set<T>(key: Component<T, unknown>, value: T): void;

package/dist/components.js

@@ -0,0 +1,74 @@
+//#region src/components.ts
+/**
+* Each component's number by its id (`slot`): the code's, one id one number in a process, so that a module loaded
+* again (a dev server's) reads what its world holds of it, and `entity.get` is one load. Numbers and nothing else: a
+* world finds its game's components in its registry (`Registry.component`), which lists the engine's own and the
+* game's (`Rules.components`), and nothing of another game of the process
+*/
+var slots = /* @__PURE__ */ new Map();
+/**
+* A typed key for state of a game's own: `const wave = defineComponent<WaveState>({ id: 'td.waves', default: () => ... })`.
+* Give it a prefix of the game's or the mod's: the engine's own are `core.`. A game lists its own
+* (`Rules.components`), and its world finds them by id in its registry: another game of the process may have one
+* of the same id, and a module loaded again (as a dev server does) defines it again.
+*
+* With `snapshot` and `same` the component shapes what players are sent of it and how a change is found; with `index`
+* it is filed for systems to go through; with `field` the map editor sets it
+*
+* @public
+*/
+function defineComponent(def) {
+	const { id, ...options } = def;
+	let slot = slots.get(id);
+	if (slot === void 0) slots.set(id, slot = slots.size);
+	return {
+		id,
+		slot,
+		default: void 0,
+		replicate: void 0,
+		portable: void 0,
+		snapshot: void 0,
+		same: void 0,
+		index: void 0,
+		field: void 0,
+		save: void 0,
+		load: void 0,
+		refs: void 0,
+		passable: void 0,
+		...options
+	};
+}
+/**
+* What a snapshot carries of a component, typed: `snapshotOf(entity.state, shopStock)` on a screen, or in a computer
+* player's view. `undefined` when the player was not told it
+*
+* @beta
+*/
+function snapshotOf(state, component) {
+	return state.components?.[component.id];
+}
+/**
+* State kept by component, for the world or a player. Asking for one that is not there yet makes it from the
+* component's default
+*/
+var StateStore = class {
+	/** By component id. Plain data, or what its component's `save` writes as plain data (`Component.save`) */
+	values = {};
+	get(key) {
+		if (!(key.id in this.values)) {
+			if (!key.default) throw new Error(`State "${key.id}" has no default: give it one in defineComponent, or set it first`);
+			this.values[key.id] = key.default();
+		}
+		return this.values[key.id];
+	}
+	set(key, value) {
+		this.values[key.id] = value;
+	}
+	has(key) {
+		return key.id in this.values;
+	}
+};
+//#endregion
+export { StateStore, defineComponent, snapshotOf };
+
+//# sourceMappingURL=components.js.map

package/dist/components.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.js","names":[],"sources":["../src/components.ts"],"sourcesContent":["import type { Entity, PlayerId } from './entity'\nimport type { MapFieldDef } from './mapFields'\nimport type { Registry } from './registry'\nimport type { World } from './world'\n\n/*\n * How one of the engine's own parts becomes a component (master plan FD1, done for the shop; OB1 for the inventory\n * (`inventorySlots`) and the harvester (`gathering`); OB2 for a site (`constructionSite`) and what a building makes\n * (`productionQueue`); OB3 for the hero (`heroState`, filed by owner); OB4 follows for the hero rules, a pack):\n *\n * 1. Define it where its rules live (`shopStock` in `items.ts`): `defineComponent<State, Sent>({ id: 'core.<part>', replicate,\n *    snapshot, same, index })`, the snapshot shaped for the screen (`StockInfo[]`, `InventoryInfo`), `same` comparing it\n *    field by field, `index: 'owner'` where a player's own are asked for (heroes), `true` where every one is (shops).\n * 2. The entity's field goes (`Entity.shop`); `spawn` sets the component (`entity.set`); every reader is\n *    `entity.get(component)` (or a reader of the part's: `slotsOf`, `harvesterOf`), every walk `world.index.with(component)`.\n * 3. The snapshot's typed fields go; readers use `snapshotOf(state, component)` (the client's entity a getter over it:\n *    `inventory`, `carries`, `load`). Nothing is kept for the old shape: no alias, no deprecated field.\n * 4. Saves need nothing: an entity's components are saved with it. `checkSave`'s walk of ids reads the component. No\n *    format step for saves made before: the engine and its games are still being made.\n * 5. The index's own set for the part goes (`shopSet`).\n * 6. The HUD and the computer player read the snapshot through `snapshotOf`; the inspector's parts list loses the field.\n * 7. `npm run api -- --local`, the report read; `tick.bench.ts`, `client-frame.bench.ts`, `hud.bench.ts` flat.\n */\n\n/**\n * Components are typed state a game module or a mod keeps where the engine has no field for it: on an entity\n * (`entity.get(key)`), for the whole world (`world.state(key)`) or for each player (`player.state(key)`). The engine's\n * own parts are components too (`core.`: what a shop sells, an illusion's source), so that a game pays for what it uses\n * and nothing else.\n *\n * A component is plain data, so that it goes into a save with the rest of the world (see `saveWorld`): numbers,\n * text, lists and plain objects, with other entities by id. One kept otherwise while the game runs (a `Map`, bytes)\n * says how it is saved and loaded (`save`, `load`), wherever it is held.\n *\n * `T` is what the component holds; `S` is what a player's snapshot carries of it (`snapshot`), `T` itself when it is\n * sent as it is\n *\n * @beta\n */\nexport interface Component<T, S = T> {\n\t/** The component's id, which saves and snapshots keep it under */\n\treadonly id: string\n\t/**\n\t * Where an entity keeps it (`Entity.get`): a number of its own, given as it is defined, the same for every\n\t * definition of one id\n\t *\n\t * @internal\n\t */\n\treadonly slot: number\n\t/** What it starts as. Needed for world and player state, which is there from the moment it is asked for */\n\treadonly default?: () => T\n\t/**\n\t * Who gets an entity's component in their snapshot (`EntityState.components`), for a game's view to show:\n\t * the player it belongs to, their allies too, or everyone who sees the entity. Nobody when left out\n\t */\n\treadonly replicate?: Audience\n\t/**\n\t * `false` for what is the app's, not the game's rules (where the screen is played from, a tool's own): kept in the\n\t * app's saves, but left out of a scenario (`scenarioOfWorld`), which is loaded where only the game is (a test)\n\t */\n\treadonly portable?: boolean\n\t/**\n\t * What a player's snapshot carries of it, worked out for each player told (`replicate`): a part of it, rounded,\n\t * or shaped for the screen (a shop's stock with how far the next one is, not the seconds left). A copy of the whole\n\t * value when left out. What it returns is plain data; `undefined` sends nothing to that player\n\t *\n\t * @beta\n\t */\n\tsnapshot?(value: T, entity: Entity, view: SnapshotView): S | undefined\n\t/**\n\t * Whether two snapshots of it say the same, for the delta a player is sent (`same`): field by field, as the\n\t * component knows its shape. Compared as text (`JSON.stringify`) when left out, which costs with a big value\n\t *\n\t * @beta\n\t */\n\tsame?(a: S, b: S): boolean\n\t/**\n\t * Filed in the world's index (`world.index.with(key)`, always kept), and by owner too (`'owner'`:\n\t * `world.index.with(key, player)`) for what a player asks for often (their heroes), so a system goes through what\n\t * has the component and nothing else\n\t *\n\t * @beta\n\t */\n\treadonly index?: boolean | 'owner'\n\t/**\n\t * A field of the map editor's for it: what is placed on a map starts with the component set to what the field says\n\t * (`MapObject.data[id]`, under the component's own id), the editor's Inspector shows it for what `for` names, and\n\t * the game has it from the moment the world is made, with nothing to copy over in a `mapObject` hook\n\t *\n\t * @beta\n\t */\n\treadonly field?: ComponentFieldDef\n\t/**\n\t * What an entity starts with of it, as it is made (`World.spawn`), by its type: a building that makes things gets\n\t * its queue, a unit that carries its slots. Run for every entity made, the engine's parts first and in their order,\n\t * before the `made` hook; what it does not want of an entity, it leaves alone\n\t *\n\t * @beta\n\t */\n\treadonly onSpawn?: (entity: Entity, world: World) => void\n\t/**\n\t * What is called off of it as the entity leaves its owner: it dies (before the `death` hook), or is given to\n\t * another (`World.setOwner`). Run for an entity that has it\n\t *\n\t * @beta\n\t */\n\treadonly onLeave?: (entity: Entity, world: World) => void\n\t/**\n\t * Whether a structure that has it stands open now, in nobody's way (a gate opened): what puts the world back from a\n\t * save leaves it out of the ways as it was. The part that opens and shuts it takes it out and puts it back as it\n\t * goes (`World.nav`). Run for an entity that has it\n\t *\n\t * @beta\n\t */\n\tpassable?(value: T, entity: Entity): boolean\n\t/**\n\t * What a save keeps of it, where that is not its value as it is (plain data: numbers, text, lists, plain objects): a\n\t * `Map` as its entries, an effect as where it is in its ability, bytes kept for speed as the record a save has always\n\t * had. Its value as it is when left out, which has to be plain data then. For each of its holders: an entity, the\n\t * world (`world.state`) and a player (`player.state`)\n\t *\n\t * @beta\n\t */\n\tsave?(value: T, world: World): unknown\n\t/**\n\t * It again, of what `save` gave, as a save is loaded: the save's value as it is when left out. Given a copy of the\n\t * save's, its own to keep or change\n\t *\n\t * @beta\n\t */\n\tload?(saved: unknown, registry: Registry): T\n\t/**\n\t * The ids of the game's definitions a save of it names (of what `save` gave, or its value): what a save is checked\n\t * for before a world is made of it, so that one naming what the game no longer has is refused all at once, saying\n\t * what (`SaveMissing`)\n\t *\n\t * @beta\n\t */\n\trefs?(saved: unknown): SavedRefs\n}\n\n/**\n * The ids of the game's definitions a component's saved value names, by kind (`Component.refs`)\n *\n * @beta\n */\nexport interface SavedRefs {\n\t/** Ids of unit types the saved value names */\n\tunits?: readonly string[]\n\t/** Ids of abilities the saved value names */\n\tabilities?: readonly string[]\n\t/** Ids of buffs the saved value names */\n\tbuffs?: readonly string[]\n\t/** Ids of items the saved value names */\n\titems?: readonly string[]\n\t/** Ids of upgrades the saved value names */\n\tupgrades?: readonly string[]\n}\n\n/**\n * Who a part of a snapshot is for: the owner alone, the owner and allies, or everyone\n *\n * @beta\n */\nexport type Audience = 'owner' | 'allies' | 'everyone'\n\n/**\n * A map field of a component's: as a game's own field on a map (`MapFieldDef`), its id the component's\n *\n * @beta\n */\nexport type ComponentFieldDef = Omit<MapFieldDef, 'id'>\n\n/**\n * Who a snapshot is being made for, as a component shapes its part of it\n *\n * @beta\n */\nexport interface SnapshotView {\n\t/** The world the snapshot is made from */\n\treadonly world: World\n\t/** The player it is made for; `undefined` for an observer */\n\treadonly player: PlayerId | undefined\n\t/** Whether the entity is the player's own */\n\treadonly own: boolean\n\t/** Whether the entity's owner is the player, or an ally of theirs (an observer is everyone's) */\n\treadonly ally: boolean\n\t/** Whether the snapshot is for an observer, who has no player */\n\treadonly observer: boolean\n\t/** Whether the player's team can see another entity right now (`SessionView.knows`): what else of it the part may name */\n\treadonly knows: (entity: Entity) => boolean\n\t/** Whether an owner is the player or an ally of theirs (`SessionView.isAlly`) */\n\treadonly isAlly: (owner: PlayerId) => boolean\n\t/** Whether the player's team sees a spot of the map right now (`SessionView.sees`) */\n\treadonly sees: (x: number, z: number) => boolean\n}\n\n/**\n * What `defineComponent` takes: everything of a component but its id\n *\n * @beta\n */\nexport type ComponentOptions<T, S = T> = Omit<Component<T, S>, 'id' | 'slot'>\n\n/**\n * Each component's number by its id (`slot`): the code's, one id one number in a process, so that a module loaded\n * again (a dev server's) reads what its world holds of it, and `entity.get` is one load. Numbers and nothing else: a\n * world finds its game's components in its registry (`Registry.component`), which lists the engine's own and the\n * game's (`Rules.components`), and nothing of another game of the process\n */\nconst slots = new Map<string, number>()\n\n/**\n * A typed key for state of a game's own: `const wave = defineComponent<WaveState>({ id: 'td.waves', default: () => ... })`.\n * Give it a prefix of the game's or the mod's: the engine's own are `core.`. A game lists its own\n * (`Rules.components`), and its world finds them by id in its registry: another game of the process may have one\n * of the same id, and a module loaded again (as a dev server does) defines it again.\n *\n * With `snapshot` and `same` the component shapes what players are sent of it and how a change is found; with `index`\n * it is filed for systems to go through; with `field` the map editor sets it\n *\n * @public\n */\nexport function defineComponent<T, S = T>(def: { id: string } & ComponentOptions<T, S>): Component<T, S> {\n\tconst { id, ...options } = def\n\t// every field there, in one order, whatever the options say: every component one shape, so that reading its id (as\n\t// `entity.get` does, many times a tick, with every kind of component) is one load and not a search through shapes\n\tlet slot = slots.get(id)\n\tif (slot === undefined) slots.set(id, (slot = slots.size))\n\tconst component: Component<T, S> = {\n\t\tid,\n\t\tslot,\n\t\tdefault: undefined,\n\t\treplicate: undefined,\n\t\tportable: undefined,\n\t\tsnapshot: undefined,\n\t\tsame: undefined,\n\t\tindex: undefined,\n\t\tfield: undefined,\n\t\tsave: undefined,\n\t\tload: undefined,\n\t\trefs: undefined,\n\t\tpassable: undefined,\n\t\t...options\n\t}\n\treturn component\n}\n\n/**\n * What a snapshot carries of a component, typed: `snapshotOf(entity.state, shopStock)` on a screen, or in a computer\n * player's view. `undefined` when the player was not told it\n *\n * @beta\n */\nexport function snapshotOf<T, S>(state: { components?: Record<string, unknown> }, component: Component<T, S>): S | undefined {\n\treturn state.components?.[component.id] as S | undefined\n}\n\n/**\n * State kept by component, for the world or a player. Asking for one that is not there yet makes it from the\n * component's default\n */\nexport class StateStore {\n\t/** By component id. Plain data, or what its component's `save` writes as plain data (`Component.save`) */\n\treadonly values: Record<string, unknown> = {}\n\n\tget<T>(key: Component<T, unknown>): T {\n\t\tif (!(key.id in this.values)) {\n\t\t\tif (!key.default) throw new Error(`State \"${key.id}\" has no default: give it one in defineComponent, or set it first`)\n\t\t\tthis.values[key.id] = key.default()\n\t\t}\n\t\treturn this.values[key.id] as T\n\t}\n\n\tset<T>(key: Component<T, unknown>, value: T): void {\n\t\tthis.values[key.id] = value\n\t}\n\n\thas(key: Component<unknown, unknown>): boolean {\n\t\treturn key.id in this.values\n\t}\n}\n"],"mappings":";;;;;;;AAkNA,IAAM,wBAAQ,IAAI,IAAoB;;;;;;;;;;;;AAatC,SAAgB,gBAA0B,KAA+D;CACxG,MAAM,EAAE,IAAI,GAAG,YAAY;CAG3B,IAAI,OAAO,MAAM,IAAI,EAAE;CACvB,IAAI,SAAS,KAAA,GAAW,MAAM,IAAI,IAAK,OAAO,MAAM,IAAK;CAiBzD,OAAO;EAfN;EACA;EACA,SAAS,KAAA;EACT,WAAW,KAAA;EACX,UAAU,KAAA;EACV,UAAU,KAAA;EACV,MAAM,KAAA;EACN,OAAO,KAAA;EACP,OAAO,KAAA;EACP,MAAM,KAAA;EACN,MAAM,KAAA;EACN,MAAM,KAAA;EACN,UAAU,KAAA;EACV,GAAG;CAEG;AACR;;;;;;;AAQA,SAAgB,WAAiB,OAAiD,WAA2C;CAC5H,OAAO,MAAM,aAAa,UAAU;AACrC;;;;;AAMA,IAAa,aAAb,MAAwB;;CAEvB,SAA2C,CAAC;CAE5C,IAAO,KAA+B;EACrC,IAAI,EAAE,IAAI,MAAM,KAAK,SAAS;GAC7B,IAAI,CAAC,IAAI,SAAS,MAAM,IAAI,MAAM,UAAU,IAAI,GAAG,kEAAkE;GACrH,KAAK,OAAO,IAAI,MAAM,IAAI,QAAQ;EACnC;EACA,OAAO,KAAK,OAAO,IAAI;CACxB;CAEA,IAAO,KAA4B,OAAgB;EAClD,KAAK,OAAO,IAAI,MAAM;CACvB;CAEA,IAAI,KAA2C;EAC9C,OAAO,IAAI,MAAM,KAAK;CACvB;AACD"}

package/dist/computers.d.ts

@@ -17,7 +17,7 @@ export type BrainSeat = (world: World, player: PlayerId, options: AiOptions) =>
  * @beta
  */
 export interface SeatRequest extends AiOptions {
-    /** The brain, or its id (one the game lists in `GameModule.brains`): the first the game lists when left out */
+    /** The brain, or its id (one the game lists in `Rules.brains`): the first the game lists when left out */
     brain?: BrainDef | string;
 }
 /**
@@ -55,12 +55,12 @@ export declare class Computers {
     constructor(world: World);
     /**
      * Seats the computer at a player, and remembers it: a game loaded from a save of this one has it back, with its memory
-     * (`restore`). `request.brain` is one of the game's (`defineBrain`; one listed in `GameModule.brains` is found again by
+     * (`restore`). `request.brain` is one of the game's (`defineBrain`; one listed in `Rules.brains` is found again by
      * its id for a load, one that is not is kept by id only, and a load without it warns and leaves the seat empty), or
      * its id, or left out for the first brain the game lists. Of the rest of the request (`AiOptions`), the data is kept
      * (numbers, lists, names); a function given in it is dropped from the save, said in the log, and a load has what the
      * brain's definition gives: a game that wants its function back after a load puts it in the brain it lists in
-     * `GameModule.brains`. A player seated already is unseated first. What thinks in it is a `Brain` unless the brain was
+     * `Rules.brains`. A player seated already is unseated first. What thinks in it is a `Brain` unless the brain was
      * made otherwise (`defineComputer`: say which)
      */
     seat<C extends ComputerPlayer = Brain>(player: PlayerId, request?: SeatRequest): ComputerSystem<C>;
@@ -97,7 +97,7 @@ export declare class Computers {
      * (`GameAi.defaults.brain`). Nothing where none says: the game's first brain
      */
     private brainFor;
-    /** A brain by id: one the game lists (`GameModule.brains`) */
+    /** A brain by id: one the game lists (`Rules.brains`) */
     brain(id: string): BrainDef | undefined;
     /**
      * Seats again the computers a save remembers, in a world loaded from it: what `loadWorld` does before the game's

package/dist/computers.js

@@ -0,0 +1,194 @@
+import { defineComponent } from "./components.js";
+import { plainParts } from "./plain.js";
+//#region src/computers.ts
+/**
+* The computer players of a world (`world.computers`): who is seated where, kept in the world so that a save has them
+* and a loaded game seats them again. The seats alone, no brain: a brain seats itself (`BrainDef.seat`, the AI kit's
+* `defineBrain` gives it one), so that the engine's core loads nothing of the computer player's kit
+* (`@v12-engine/engine/ai`) a game does not list
+*/
+/**
+* Who the computer plays, by player, with what they were seated with: in the world, so that a save keeps it and a
+* loaded game seats them again by itself (`world.computers`)
+*/
+var computerSeats = defineComponent({
+	id: "core.computers",
+	default: () => ({})
+});
+/**
+* What every seat of the world is given where its request says nothing (`world.computers.defaults`): data only, kept in
+* the world so a save has it, and a computer seated after a load gets it too
+*/
+var computerDefaults = defineComponent({
+	id: "core.computerDefaults",
+	default: () => ({})
+});
+/**
+* The computer players of a world: who is seated, kept in the world and in a save (`core.computers`), so that a game
+* loaded from a save has them back without the game's doing, and how the game reaches a seated brain while it plays
+* (`tell`, `pause`, `get`)
+*
+* @beta
+*/
+var Computers = class {
+	world;
+	/** The seats, by player, in the order they were taken */
+	seats = /* @__PURE__ */ new Map();
+	constructor(world) {
+		this.world = world;
+	}
+	/**
+	* Seats the computer at a player, and remembers it: a game loaded from a save of this one has it back, with its memory
+	* (`restore`). `request.brain` is one of the game's (`defineBrain`; one listed in `Rules.brains` is found again by
+	* its id for a load, one that is not is kept by id only, and a load without it warns and leaves the seat empty), or
+	* its id, or left out for the first brain the game lists. Of the rest of the request (`AiOptions`), the data is kept
+	* (numbers, lists, names); a function given in it is dropped from the save, said in the log, and a load has what the
+	* brain's definition gives: a game that wants its function back after a load puts it in the brain it lists in
+	* `Rules.brains`. A player seated already is unseated first. What thinks in it is a `Brain` unless the brain was
+	* made otherwise (`defineComputer`: say which)
+	*/
+	seat(player, request = {}) {
+		const { brain: asked_, ...asked } = request;
+		const options = {
+			...this.defaults,
+			...asked
+		};
+		const brain = asked_ ?? this.brainFor(player);
+		const def = typeof brain === "string" ? this.brain(brain) : brain;
+		if (typeof brain === "string" && !def) throw new Error(`No brain is called "${brain}": list it in Rules.brains, or seat the brain itself`);
+		if (this.seats.has(player)) this.unseat(player);
+		const system = this.seated(player, def, options);
+		this.world.addSystem(system);
+		this.seats.set(player, system);
+		this.world.setState(computerSeats, {
+			...this.world.state(computerSeats),
+			[player]: {
+				...def && { brain: def.id },
+				options: dataOf(options, this.world, player)
+			}
+		});
+		return system;
+	}
+	/**
+	* What every computer seated from now on is given where its request says nothing (`AiOptions`, data only: a
+	* difficulty, a personality), over what the map says of the player (`MapPlayer.data.ai`): a campaign's difficulty,
+	* set before a mission seats its computers. Kept in the world, so a save has it. Those seated already keep what they
+	* were seated with
+	*/
+	get defaults() {
+		return this.world.states.has(computerDefaults) ? this.world.state(computerDefaults) : {};
+	}
+	set defaults(defaults) {
+		this.world.setState(computerDefaults, { ...defaults });
+	}
+	/** Takes the computer out of a player's seat, and out of what a save remembers. False where none was seated */
+	unseat(player) {
+		const system = this.seats.get(player);
+		if (this.world.states.has(computerSeats) && player in this.world.state(computerSeats)) {
+			const { [player]: _gone, ...rest } = this.world.state(computerSeats);
+			this.world.setState(computerSeats, rest);
+		}
+		if (!system) return false;
+		this.seats.delete(player);
+		this.world.removeSystem(system.name);
+		system.dispose();
+		return true;
+	}
+	/** The seat the computer plays a player from, while it does */
+	get(player) {
+		return this.seats.get(player);
+	}
+	/** The players the computer plays, in the order they were seated */
+	list() {
+		return [...this.seats.keys()];
+	}
+	/**
+	* Tells a computer player a word, with data to go with it: what a mission's script says to its brain
+	* (`world.computers.tell(ENEMY, 'raid', { at })`), taken by a rule of the brain's (`when.told`). False where nobody is
+	* seated there, or what is seated takes no words
+	*/
+	tell(player, word, data) {
+		const computer = this.get(player)?.computer;
+		if (!computer?.tell) return false;
+		computer.tell(word, data, this.world.tick);
+		return true;
+	}
+	/** Has a computer player sit still until `resume`: kept in a save. False where none is seated, or it cannot be paused */
+	pause(player) {
+		return this.setPaused(player, true);
+	}
+	/** Has a paused computer player think again */
+	resume(player) {
+		return this.setPaused(player, false);
+	}
+	setPaused(player, paused) {
+		const computer = this.get(player)?.computer;
+		if (!computer || !("paused" in computer)) return false;
+		computer.paused = paused;
+		return true;
+	}
+	/** The system a player's seat is: the brain's own seat (`BrainDef.seat`), the first brain the game lists where none is named. Throws for a game that lists none */
+	seated(player, def, options) {
+		const game = this.world.registry.module;
+		const brain = def ?? game?.brains?.[0];
+		if (!brain) throw new Error(`The game "${game?.id}" gives no computer player to seat at player ${player}: list a brain in Rules.brains (meleeBrain of @v12-engine/engine/ai plays melee), or seat a brain`);
+		if (!brain.seat) throw new Error(`The brain "${brain.id}" was not made with defineBrain or defineComputer (@v12-engine/engine/ai): it has no seat`);
+		return brain.seat(this.world, player, options);
+	}
+	/**
+	* The brain a player is seated with where the seat names none, by id: the map's for the player (`MapAi.brain`, where
+	* the map gives the player to the computer), else its race's (`GameAi.races[race].brain`), else the game's defaults'
+	* (`GameAi.defaults.brain`). Nothing where none says: the game's first brain
+	*/
+	brainFor(player) {
+		const mapped = this.world.map.player(player);
+		const map = mapped?.controller === "computer" ? mapped.data?.ai : void 0;
+		if (map && typeof map === "object" && typeof map.brain === "string") return map.brain;
+		const ai = this.world.registry.module?.ai;
+		const race = this.world.players.get(player)?.race;
+		return (race !== void 0 ? ai?.races?.[race]?.brain : void 0) ?? ai?.defaults?.brain;
+	}
+	/** A brain by id: one the game lists (`Rules.brains`) */
+	brain(id) {
+		return this.world.registry.module?.brains?.find((brain) => brain.id === id);
+	}
+	/**
+	* Seats again the computers a save remembers, in a world loaded from it: what `loadWorld` does before the game's
+	* `afterLoad`. One the game seated already is left as it is; one whose brain is not to be found (seated by an object
+	* the game does not list) is left empty, and the log says so
+	*/
+	restore() {
+		if (!this.world.states.has(computerSeats)) return;
+		for (const [id, seat] of Object.entries(this.world.state(computerSeats))) {
+			const player = Number(id);
+			if (this.seats.has(player)) continue;
+			const def = seat.brain === void 0 ? void 0 : this.brain(seat.brain);
+			if (seat.brain !== void 0 && !def) {
+				this.world.log.warn("ai", `the save seats the brain "${seat.brain}" at player ${player}, which the game does not list (Rules.brains): the seat is left empty`, {
+					player,
+					brain: seat.brain
+				});
+				continue;
+			}
+			const system = this.seated(player, def, seat.options);
+			this.world.addSystem(system);
+			this.seats.set(player, system);
+		}
+	}
+};
+/**
+* The data part of a seat's options, for a save: what is plain data is kept as it is, and what is not (a function, or a
+* list with a function in it: `goals`, a flag given as a function in `settings`) is dropped, said in the log
+*/
+function dataOf(options, world, player) {
+	const { kept, dropped } = plainParts(options);
+	if (dropped.length) world.log.debug("ai", `the options ${dropped.map((key) => `"${key}"`).join(", ")} of the computer at player ${player} are code, and not kept in a save`, {
+		player,
+		dropped
+	});
+	return kept;
+}
+//#endregion
+export { Computers, computerDefaults, computerSeats };
+
+//# sourceMappingURL=computers.js.map

package/dist/computers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"computers.js","names":[],"sources":["../src/computers.ts"],"sourcesContent":["/**\n * The computer players of a world (`world.computers`): who is seated where, kept in the world so that a save has them\n * and a loaded game seats them again. The seats alone, no brain: a brain seats itself (`BrainDef.seat`, the AI kit's\n * `defineBrain` gives it one), so that the engine's core loads nothing of the computer player's kit\n * (`@v12-engine/engine/ai`) a game does not list\n */\nimport { defineComponent } from './components'\nimport type { PlayerId } from './entity'\nimport { plainParts } from './plain'\nimport type { World } from './world'\nimport type { AiOptions } from './ai/options'\nimport type { Brain, BrainDef } from './ai/brain'\nimport type { ComputerPlayer, ComputerSystem } from './ai/computer'\n\n/**\n * How a brain is seated at a player (`BrainDef.seat`): the system the seat is, a computer thinking in it. What\n * `defineBrain` and `defineComputer` give a brain, so that the core seats it without knowing how\n *\n * @beta\n */\nexport type BrainSeat = (world: World, player: PlayerId, options: AiOptions) => ComputerSystem\n\n/**\n * What a seat is asked for (`world.computers.seat(player, request)`): the brain (one of the game's, `defineBrain`, or\n * its id; the first the game lists when left out) and what it is seated with (`AiOptions`)\n *\n * @beta\n */\nexport interface SeatRequest extends AiOptions {\n\t/** The brain, or its id (one the game lists in `Rules.brains`): the first the game lists when left out */\n\tbrain?: BrainDef | string\n}\n\n/**\n * A seat as a save keeps it (`core.computers`): the brain by id, and the data part of its options\n *\n * @beta\n */\nexport interface ComputerSeat {\n\t/** The brain's id. Left out for the first brain the game lists */\n\tbrain?: string\n\t/** What it was seated with, the data of it (`AiOptions`) */\n\toptions: Record<string, unknown>\n}\n\n/**\n * Who the computer plays, by player, with what they were seated with: in the world, so that a save keeps it and a\n * loaded game seats them again by itself (`world.computers`)\n */\nexport const computerSeats = defineComponent<Record<string, ComputerSeat>>({ id: 'core.computers', default: () => ({}) })\n\n/**\n * What every seat of the world is given where its request says nothing (`world.computers.defaults`): data only, kept in\n * the world so a save has it, and a computer seated after a load gets it too\n */\nexport const computerDefaults = defineComponent<Record<string, unknown>>({ id: 'core.computerDefaults', default: () => ({}) })\n\n/**\n * The computer players of a world: who is seated, kept in the world and in a save (`core.computers`), so that a game\n * loaded from a save has them back without the game's doing, and how the game reaches a seated brain while it plays\n * (`tell`, `pause`, `get`)\n *\n * @beta\n */\nexport class Computers {\n\t/** The seats, by player, in the order they were taken */\n\tprivate readonly seats = new Map<PlayerId, ComputerSystem>()\n\n\tconstructor(private readonly world: World) {}\n\n\t/**\n\t * Seats the computer at a player, and remembers it: a game loaded from a save of this one has it back, with its memory\n\t * (`restore`). `request.brain` is one of the game's (`defineBrain`; one listed in `Rules.brains` is found again by\n\t * its id for a load, one that is not is kept by id only, and a load without it warns and leaves the seat empty), or\n\t * its id, or left out for the first brain the game lists. Of the rest of the request (`AiOptions`), the data is kept\n\t * (numbers, lists, names); a function given in it is dropped from the save, said in the log, and a load has what the\n\t * brain's definition gives: a game that wants its function back after a load puts it in the brain it lists in\n\t * `Rules.brains`. A player seated already is unseated first. What thinks in it is a `Brain` unless the brain was\n\t * made otherwise (`defineComputer`: say which)\n\t */\n\tseat<C extends ComputerPlayer = Brain>(player: PlayerId, request: SeatRequest = {}): ComputerSystem<C> {\n\t\tconst { brain: asked_, ...asked } = request\n\t\t// what the world gives every seat, under what the request says (and over what the map says: `mapAiOptions`)\n\t\tconst options: AiOptions = { ...this.defaults, ...asked }\n\t\t// the seat's brain, else the map's for the player, else its race's (AR3); the game's first where none says\n\t\tconst brain = asked_ ?? this.brainFor(player)\n\t\tconst def = typeof brain === 'string' ? this.brain(brain) : brain\n\t\tif (typeof brain === 'string' && !def) throw new Error(`No brain is called \"${brain}\": list it in Rules.brains, or seat the brain itself`)\n\t\tif (this.seats.has(player)) this.unseat(player)\n\t\tconst system = this.seated(player, def, options)\n\t\tthis.world.addSystem(system)\n\t\tthis.seats.set(player, system)\n\t\tthis.world.setState(computerSeats, {\n\t\t\t...this.world.state(computerSeats),\n\t\t\t[player]: { ...(def && { brain: def.id }), options: dataOf(options, this.world, player) }\n\t\t})\n\t\treturn system as ComputerSystem<C>\n\t}\n\n\t/**\n\t * What every computer seated from now on is given where its request says nothing (`AiOptions`, data only: a\n\t * difficulty, a personality), over what the map says of the player (`MapPlayer.data.ai`): a campaign's difficulty,\n\t * set before a mission seats its computers. Kept in the world, so a save has it. Those seated already keep what they\n\t * were seated with\n\t */\n\tget defaults(): Readonly<Pick<AiOptions, 'difficulty' | 'personality'>> {\n\t\treturn this.world.states.has(computerDefaults) ? (this.world.state(computerDefaults) as Pick<AiOptions, 'difficulty' | 'personality'>) : {}\n\t}\n\n\tset defaults(defaults: Pick<AiOptions, 'difficulty' | 'personality'>) {\n\t\tthis.world.setState(computerDefaults, { ...defaults })\n\t}\n\n\t/** Takes the computer out of a player's seat, and out of what a save remembers. False where none was seated */\n\tunseat(player: PlayerId): boolean {\n\t\tconst system = this.seats.get(player)\n\t\tif (this.world.states.has(computerSeats) && player in this.world.state(computerSeats)) {\n\t\t\tconst { [player]: _gone, ...rest } = this.world.state(computerSeats)\n\t\t\tthis.world.setState(computerSeats, rest)\n\t\t}\n\t\tif (!system) return false\n\t\tthis.seats.delete(player)\n\t\tthis.world.removeSystem(system.name)\n\t\tsystem.dispose()\n\t\treturn true\n\t}\n\n\t/** The seat the computer plays a player from, while it does */\n\tget(player: PlayerId): ComputerSystem | undefined {\n\t\treturn this.seats.get(player)\n\t}\n\n\t/** The players the computer plays, in the order they were seated */\n\tlist(): PlayerId[] {\n\t\treturn [...this.seats.keys()]\n\t}\n\n\t/**\n\t * Tells a computer player a word, with data to go with it: what a mission's script says to its brain\n\t * (`world.computers.tell(ENEMY, 'raid', { at })`), taken by a rule of the brain's (`when.told`). False where nobody is\n\t * seated there, or what is seated takes no words\n\t */\n\ttell(player: PlayerId, word: string, data?: unknown): boolean {\n\t\tconst computer = this.get(player)?.computer\n\t\tif (!computer?.tell) return false\n\t\tcomputer.tell(word, data, this.world.tick)\n\t\treturn true\n\t}\n\n\t/** Has a computer player sit still until `resume`: kept in a save. False where none is seated, or it cannot be paused */\n\tpause(player: PlayerId): boolean {\n\t\treturn this.setPaused(player, true)\n\t}\n\n\t/** Has a paused computer player think again */\n\tresume(player: PlayerId): boolean {\n\t\treturn this.setPaused(player, false)\n\t}\n\n\tprivate setPaused(player: PlayerId, paused: boolean): boolean {\n\t\tconst computer = this.get(player)?.computer\n\t\tif (!computer || !('paused' in computer)) return false\n\t\tcomputer.paused = paused\n\t\treturn true\n\t}\n\n\t/** The system a player's seat is: the brain's own seat (`BrainDef.seat`), the first brain the game lists where none is named. Throws for a game that lists none */\n\tprivate seated(player: PlayerId, def: BrainDef | undefined, options: AiOptions): ComputerSystem {\n\t\tconst game = this.world.registry.module\n\t\tconst brain = def ?? game?.brains?.[0]\n\t\tif (!brain)\n\t\t\tthrow new Error(\n\t\t\t\t`The game \"${game?.id}\" gives no computer player to seat at player ${player}: list a brain in Rules.brains (meleeBrain of @v12-engine/engine/ai plays melee), or seat a brain`\n\t\t\t)\n\t\tif (!brain.seat) throw new Error(`The brain \"${brain.id}\" was not made with defineBrain or defineComputer (@v12-engine/engine/ai): it has no seat`)\n\t\treturn brain.seat(this.world, player, options)\n\t}\n\n\t/**\n\t * The brain a player is seated with where the seat names none, by id: the map's for the player (`MapAi.brain`, where\n\t * the map gives the player to the computer), else its race's (`GameAi.races[race].brain`), else the game's defaults'\n\t * (`GameAi.defaults.brain`). Nothing where none says: the game's first brain\n\t */\n\tprivate brainFor(player: PlayerId): string | undefined {\n\t\tconst mapped = this.world.map.player(player)\n\t\tconst map = mapped?.controller === 'computer' ? (mapped.data?.ai as { brain?: unknown } | undefined) : undefined\n\t\tif (map && typeof map === 'object' && typeof map.brain === 'string') return map.brain\n\t\tconst ai = this.world.registry.module?.ai\n\t\tconst race = this.world.players.get(player)?.race\n\t\treturn (race !== undefined ? ai?.races?.[race]?.brain : undefined) ?? ai?.defaults?.brain\n\t}\n\n\t/** A brain by id: one the game lists (`Rules.brains`) */\n\tbrain(id: string): BrainDef | undefined {\n\t\treturn this.world.registry.module?.brains?.find((brain) => brain.id === id)\n\t}\n\n\t/**\n\t * Seats again the computers a save remembers, in a world loaded from it: what `loadWorld` does before the game's\n\t * `afterLoad`. One the game seated already is left as it is; one whose brain is not to be found (seated by an object\n\t * the game does not list) is left empty, and the log says so\n\t */\n\trestore(): void {\n\t\tif (!this.world.states.has(computerSeats)) return\n\t\tfor (const [id, seat] of Object.entries(this.world.state(computerSeats))) {\n\t\t\tconst player = Number(id)\n\t\t\tif (this.seats.has(player)) continue\n\t\t\tconst def = seat.brain === undefined ? undefined : this.brain(seat.brain)\n\t\t\tif (seat.brain !== undefined && !def) {\n\t\t\t\tthis.world.log.warn(\n\t\t\t\t\t'ai',\n\t\t\t\t\t`the save seats the brain \"${seat.brain}\" at player ${player}, which the game does not list (Rules.brains): the seat is left empty`,\n\t\t\t\t\t{\n\t\t\t\t\t\tplayer,\n\t\t\t\t\t\tbrain: seat.brain\n\t\t\t\t\t}\n\t\t\t\t)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tconst system = this.seated(player, def, seat.options as AiOptions)\n\t\t\tthis.world.addSystem(system)\n\t\t\tthis.seats.set(player, system)\n\t\t}\n\t}\n}\n\n/**\n * The data part of a seat's options, for a save: what is plain data is kept as it is, and what is not (a function, or a\n * list with a function in it: `goals`, a flag given as a function in `settings`) is dropped, said in the log\n */\nfunction dataOf(options: AiOptions, world: World, player: PlayerId): Record<string, unknown> {\n\tconst { kept, dropped } = plainParts(options)\n\tif (dropped.length)\n\t\tworld.log.debug(\n\t\t\t'ai',\n\t\t\t`the options ${dropped.map((key) => `\"${key}\"`).join(', ')} of the computer at player ${player} are code, and not kept in a save`,\n\t\t\t{\n\t\t\t\tplayer,\n\t\t\t\tdropped\n\t\t\t}\n\t\t)\n\treturn kept as Record<string, unknown>\n}\n"],"mappings":"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"}

package/dist/concealment.d.ts

@@ -7,7 +7,7 @@ import type { World } from './world';
  * or from close by (`reach`). An attacker in one is seen by whom it hits for a moment, as anyone is (`expose`), and
  * what detects the invisible (`entity.detected`) sees it too. A game turns it on, on as many layers as it likes:
  *
- *     export const rules = { ...myGame, packs: [withConcealment({ layer: 'bush' })] }
+ *     export const rules = { ...myGame, packs: [concealmentPack({ layer: 'bush' })] }
  *
  * Everything that asks what a team sees (`world.isVisibleTo`) goes by it: what units pick to attack, the commands a
  * player may give, the fog's memory, and each player's snapshots, so the computer player and the players over a wire
@@ -41,6 +41,29 @@ export interface ConcealmentOptions {
     rustleEvery?: number;
     /** The id of its hook and its system, to replace or leave out: `concealment:<layer>` when left out */
     id?: string;
+    /**
+     * Which cells of the layer hide, by their index: every cell that is not 0 when left out. The patches are of the
+     * cells that do (those that touch), so grass that is cut or burnt neither hides nor joins two patches. What the
+     * foliage pack hides by: a style that conceals, in a state that still does (`foliagePack`). Asked as the patches are
+     * worked out, not for every unit
+     */
+    conceals?: (world: World, cell: number) => boolean;
+    /**
+     * Other layers whose cells decide what hides (`conceals`), by id: the patches are worked out again when one of them
+     * changes, as when the layer itself does. The foliage pack's state layer (`foliageStateLayer`)
+     */
+    follows?: readonly string[];
+    /**
+     * Told of each unit on the map as the count goes through the units at the start of a tick (alive, not inside
+     * anything), with the cell it stands in (`unit`), and once the count is done (`done`, whether it changed cells of the
+     * layer or of one it follows: the count is made again of the patches as they are now). What the foliage pack
+     * tramples by, in the same pass over the units as the count (`FoliageStyleDef.trample`). Never told from a `visible`
+     * asked before the tick's count
+     */
+    eachUnit?: {
+        unit(world: World, entity: Entity, cell: number): void;
+        done(world: World): boolean;
+    };
 }
 /**
  * The patch of a layer an entity stands in, 1 and up, or 0 where it stands in none (`ConcealmentOptions`). For a
@@ -56,6 +79,6 @@ export declare function patchAt(world: World, layer: string, x: number, z: numbe
  *
  * @beta
  */
-export declare function withConcealment(options: ConcealmentOptions): GamePack;
+export declare function concealmentPack(options: ConcealmentOptions): GamePack;
 /** One hidden moving in a layer: where the player sees the ground, to whom the rules tell it, a shake of the bushes */
 export declare const toldRustle: import("./replication").ReplicatedEvent;