@v12-engine/engine 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Doron Torangy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/abilities/buffs.d.ts

@@ -0,0 +1,83 @@
+import { type AbilityDef, type BuffDef, type Layer } from '#engine/defs';
+import type { Entity } from '#engine/entity';
+import type { World } from '#engine/world';
+/**
+ * Auras keep their buff alive by renewing it. It wears off this long after leaving the aura
+ *
+ * @beta
+ */
+export declare const AURA_LINGER = 0.75;
+/** @beta */
+export declare function hasBuff(entity: Entity, buff: string): boolean;
+/**
+ * Puts a buff on an entity. Buffs do not stack with themselves: a second one of the
+ * same kind renews the first when it lasts longer.
+ *
+ * @beta
+ */
+export declare function applyBuff(world: World, target: Entity, buff: string, duration?: number, source?: Entity, level?: number, ability?: string): void;
+/** What the shield of a buff holds when it is new */
+export declare function fullShield(world: World, def: BuffDef, source: Entity, level: number): number;
+/**
+ * Takes a buff off, before its time is up: the one of it `source` put on, for buffs each source has their own of, or
+ * the first. The `buffEnd` hook hears of it, and the buff's `onRemove`
+ *
+ * @beta
+ */
+export declare function removeBuff(world: World, entity: Entity, buff: string, source?: Entity): void;
+/** Whether an ability gets through a unit's immunity to spells: always, never, or as its function says for the unit */
+export declare const pierces: (world: World, ability: AbilityDef, target: Entity) => boolean;
+/** Whether a buff a unit carries keeps it from attacking now (`BuffDef.disarm`) */
+export declare const isDisarmed: (world: World, entity: Entity) => boolean;
+/**
+ * Whether a unit is immune to spells: by its type, or a buff it carries (an avatar), as declared or as code decides
+ *
+ * @beta
+ */
+export declare function isSpellImmune(world: World, entity: Entity): boolean;
+/** @beta */
+export declare function avoids(world: World, entity: Entity, ability: AbilityDef): boolean;
+/** Whether a buff keeps a unit from doing what it wants: stuns and slows. Tenacity cuts those short */
+export declare function isCrowdControl(def: BuffDef): boolean;
+/** @beta */
+export declare const isStunned: (world: World, entity: Entity) => boolean;
+/**
+ * Held to the spot: it can do everything but walk
+ *
+ * @beta
+ */
+export declare const isRooted: (world: World, entity: Entity) => boolean;
+/**
+ * Kept from using its abilities: from this one, when it says which (a silence of fire spells only). Without an
+ * ability, whether anything keeps it from using some
+ *
+ * @beta
+ */
+export declare const isSilenced: (world: World, entity: Entity, ability?: AbilityDef) => boolean;
+/**
+ * Whether a buff's `silence` keeps its carrier from an ability, or from any when none is said. For both ends
+ *
+ * @beta
+ */
+export declare const silences: (silence: BuffDef['silence'], ability?: AbilityDef) => boolean;
+/**
+ * Where an entity is right now. What flies is in the air, unless something holds it down
+ *
+ * @beta
+ */
+export declare function layerOf(world: World, entity: Entity): Layer;
+/**
+ * What is left of the shields on an entity
+ *
+ * @beta
+ */
+export declare function shieldOf(entity: Entity): number;
+/** Lets the shields of an entity take damage. Returns what they could not hold */
+export declare function absorb(entity: Entity, amount: number): number;
+/**
+ * A buff put on, to those who see who has it. Put on again, only where its level changed: an aura renews its buff
+ * every round, and what is left of it is the snapshot's (`EntityState.buffTimes`)
+ */
+export declare const toldBuffOn: import("..").ReplicatedEvent;
+/** A buff gone, to those who see who had it */
+export declare const toldBuffOff: import("..").ReplicatedEvent;

package/dist/abilities/castTold.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What players are told of casting (the cast order's events): the wind-up, a channel's start and end, the cast. Beside
+ * the abilities, whose order emits them
+ */
+/** A spell being wound up, to those who see the caster: where it aims, and for how long */
+export declare const toldWindup: import("..").ReplicatedEvent;
+/** A channel begun, to those who see the caster */
+export declare const toldChannelStarted: import("..").ReplicatedEvent;
+/** A channel over, to those who see the caster */
+export declare const toldChannelEnded: import("..").ReplicatedEvent;
+/** A cast, to those who see the caster or where it lands */
+export declare const toldCast: import("..").ReplicatedEvent;

package/dist/abilities/charges.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Charges: an ability used so many times before it waits (`AbilityDef.charges`). A use spends one, and one comes back
+ * every `refill` seconds while it holds fewer than it can. What a state says nothing of is full, so an ability learned,
+ * a level gone up and a save from before it all start full without anyone filling them in
+ */
+import { type AbilityDef } from '#engine/defs';
+import type { AbilityState, Entity } from '#engine/entity';
+import type { World } from '#engine/world';
+/**
+ * Spends a use of an ability with charges, as it goes off: the refill starts, where it was not running already.
+ * `plain` for what nothing shortens (an item's, a spell brought along). Nothing for one without charges, and nothing
+ * while the debug switch for no cooldowns is on
+ */
+export declare function spendUse(world: World, caster: Entity, ability: AbilityDef, state: AbilityState, plain: boolean): void;
+/**
+ * The seconds of a tick go by for the uses of an ability (`pass`: Infinity fills them at once): one back every
+ * `refill`, until it holds all it can. `item` for the ability of something carried
+ */
+export declare function refillUses(world: World, caster: Entity, state: AbilityState, pass: number, item?: boolean): void;
+/** Ready again at once, with all the uses it holds: a hero revived, the `refresh` effect */
+export declare function readyAgain(state: AbilityState): void;
+/**
+ * Gives an entity's ability with charges uses back, up to all it holds: `count` of them, or all when left out. What a
+ * game's effect or hook does where the data's `refill` is not the way (a kill gives one back). Its cooldown stays
+ *
+ * @beta
+ */
+export declare function restoreCharges(world: World, entity: Entity, ability: string, count?: number): void;

package/dist/abilities/dispel.d.ts

@@ -0,0 +1,9 @@
+import type { Entity } from '#engine/entity';
+import type { World } from '#engine/world';
+/**
+ * Takes buffs off a unit, as a dispel does: the good ones of an enemy of `by`, the bad ones of a friend. Those that say
+ * they cannot be (`BuffDef.dispellable: false`) stay. How many it took
+ *
+ * @beta
+ */
+export declare function dispelBuffs(world: World, entity: Entity, by: Entity): number;

package/dist/abilities/effectFields.d.ts

@@ -0,0 +1,10 @@
+import type { EffectCommon, EffectFields } from '#engine/defs';
+import type { EditableField } from '#engine/gameData';
+/** The fields every effect may have, whatever its type (`EffectCommon`): offered on every row of effects */
+export declare const COMMON_EFFECT_FIELDS: Readonly<Record<keyof EffectCommon, EditableField>>;
+/**
+ * The engine's fields of an effect by name (`EffectFields`), as the Data panel shows them; `effects`, `onEnd` and
+ * `otherwise` are lists of effects. Those of a few values (a missile's `arc`) are a field for each, null for one that
+ * is no single value
+ */
+export declare const EFFECT_FIELDS: Readonly<Record<keyof EffectFields, EditableField | readonly EditableField[] | null>>;

package/dist/abilities/effects/buff.d.ts

@@ -0,0 +1,8 @@
+export declare const buffEffect: import("../effects").EffectKind<"buff">;
+/**
+ * Puts `buff` on the caster for as long as it likes, or takes it off when it has it: a stance, burrowing. Cast again to
+ * come back out
+ */
+export declare const toggleEffect: import("../effects").EffectKind<"toggle">;
+/** auras are kept up by the ability system, there is nothing to do at the moment of casting */
+export declare const auraEffect: import("../effects").EffectKind<"aura">;

package/dist/abilities/effects/core.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/abilities/effects/damage.d.ts

@@ -0,0 +1 @@
+export declare const damageEffect: import("../effects").EffectKind<"damage">;

package/dist/abilities/effects/heal.d.ts

@@ -0,0 +1,2 @@
+export declare const healEffect: import("../effects").EffectKind<"heal">;
+export declare const manaEffect: import("../effects").EffectKind<"mana">;

package/dist/abilities/effects/missile.d.ts

@@ -0,0 +1 @@
+export declare const missileEffect: import("../effects").EffectKind<"missile">;

package/dist/abilities/effects/moves.d.ts

@@ -0,0 +1,11 @@
+/** The caster is somewhere else at once: towards where it was aimed, as far as `distance` lets it */
+export declare const blinkEffect: import("../effects").EffectKind<"blink">;
+/**
+ * The caster is somewhere else at once, however far (`to`): its side's home (`homeOf`, a recall), where it was aimed
+ * (`point`, when left out), or by its target. Nothing where there is no such place
+ */
+export declare const teleportEffect: import("../effects").EffectKind<"teleport">;
+/** The caster rushes to the spot, through whatever is in the way. `effects` happen around where it ends */
+export declare const dashEffect: import("../effects").EffectKind<"dash">;
+/** Throws the targets `distance` away from the caster. Nothing stops them on the way, and who is rushing somewhere is not thrown */
+export declare const knockbackEffect: import("../effects").EffectKind<"knockback">;

package/dist/abilities/effects/passives.d.ts

@@ -0,0 +1,15 @@
+/** `onHit` is about attacks, not about the moment of casting: see the function of that name */
+export declare const onHitEffect: import("../effects").EffectKind<"onHit">;
+/** For passives: `effects` happen around whoever the carrier kills. The killing sets it off, see `onKill` */
+export declare const onKillEffect: import("../effects").EffectKind<"onKill">;
+/** For passives: `effects` happen to the carrier whenever it casts. The casting sets it off, see `onCast` */
+export declare const onCastEffect: import("../effects").EffectKind<"onCast">;
+/** The caster is ready to strike again at once */
+export declare const resetAttackEffect: import("../effects").EffectKind<"resetAttack">;
+/** An ability of the caster is ready again, with all the charges it holds: the one named, or the one the effect belongs to */
+export declare const refreshEffect: import("../effects").EffectKind<"refresh">;
+/**
+ * `effects` when the ability went off charged, `otherwise` when it did not. With `on: 'caster'` what it does
+ * charged happens where the caster stands, wherever it was aimed
+ */
+export declare const chargedEffect: import("../effects").EffectKind<"charged">;

package/dist/abilities/effects/sight.d.ts

@@ -0,0 +1,4 @@
+/** The caster's team sees the spot for a while, with nothing standing there */
+export declare const revealEffect: import("../effects").EffectKind<"reveal">;
+/** Finds what is invisible around the spot: the caster's team sees it for as long as `duration` says */
+export declare const detectEffect: import("../effects").EffectKind<"detect">;

package/dist/abilities/effects/spawn.d.ts

@@ -0,0 +1,2 @@
+/** Brings a unit of the caster's into the world where it landed, like a ward. `duration` is how long it lasts */
+export declare const spawnEffect: import("../effects").EffectKind<"spawn">;

package/dist/abilities/effects/timed.d.ts

@@ -0,0 +1,4 @@
+/** `effects` happen at the spot, `delay` seconds from now */
+export declare const afterEffect: import("../effects").EffectKind<"after">;
+/** For `duration` seconds `effects` happen to what is at the spot, over and over, and `onEnd` to what is there at the end */
+export declare const zoneEffect: import("../effects").EffectKind<"zone">;

package/dist/abilities/effects/trade.d.ts

@@ -0,0 +1 @@
+export declare const exchangeEffect: import("../effects").EffectKind<"exchange">;

package/dist/abilities/effects.d.ts

@@ -0,0 +1,122 @@
+import { type AbilityDef, type EffectCommon, type EffectDef, type EffectFields, type EffectOf, type EffectTypes } from '#engine/defs';
+import type { EditableField } from '#engine/gameData';
+import { type Dash, type Entity } from '#engine/entity';
+import { type Vec2 } from '#engine/math';
+import type { World } from '#engine/world';
+/** @beta */
+export interface EffectContext {
+    world: World;
+    caster: Entity;
+    ability: AbilityDef;
+    /** Level the ability was cast at */
+    level: number;
+    /** The unit the ability was cast on, if any */
+    target?: Entity;
+    /** Where the ability landed: the target, the chosen spot, or the caster */
+    point: Vec2;
+    /** How far what carried the effect here has come, for what a missile does */
+    distance?: number;
+    /**
+     * What part of their amounts the effects come to (`damage`, `heal`, `mana`): less on every spring of a missile that
+     * bounces (`EffectFields.bounce`). All of it when left out; a game's own effect with an amount multiplies by it too
+     */
+    share?: number;
+    /** How many of the buff that ran out there were, for what happens when it does */
+    stacks?: number;
+    /** The ability went off charged, see `charge` on the ability */
+    charged?: boolean;
+    /**
+     * For an effect that is kept up all the time (a passive asked every round): the seconds since it was last asked.
+     * Something that works per second multiplies by this, rather than counting on how often it is asked
+     */
+    interval?: number;
+}
+/**
+ * Carries out an effect, whatever its type: what the registry hands for a type (`registry.effect`), to call with an
+ * effect of that type
+ *
+ * @beta
+ */
+export type EffectHandler = (context: EffectContext, effect: EffectDef) => void;
+/**
+ * A kind of effect: its type and what it does (`defineEffect`). The engine's are the game's from the start; a game
+ * lists its own in `GameModule.effects`, and one of a type the engine has takes its place
+ *
+ * @beta
+ */
+export interface EffectKind<K extends keyof EffectTypes = keyof EffectTypes> {
+    readonly type: K;
+    /** Carries out an effect of the type, for a cast (or a passive asked, a missile's hit...) */
+    run(context: EffectContext, effect: EffectOf<K>): void;
+    /** An effect of the type, for an ability's list: `pull.of({ distance: 3 })` is `{ type: 'pull', distance: 3 }` */
+    of(fields: EffectCommon & EffectTypes[K]): EffectOf<K>;
+    /**
+     * The fields an effect of the type reads, besides those every effect has (`EffectCommon`): what the editor's Data
+     * panel offers on a row of the type (campaign plan RC2). None said, it offers those a row has
+     */
+    readonly fields?: readonly EditableField[];
+}
+/**
+ * What a kind of effect says besides what it does (`defineEffect`): the fields it reads, each the name of one of the
+ * engine's (`EffectFields`) or said in full, its path the field's name in the effect (`{ path: 'pull', kind: 'number' }`)
+ *
+ * @beta
+ */
+export interface EffectKindOptions {
+    fields?: readonly (keyof EffectFields | EditableField)[];
+}
+/**
+ * A kind of effect, its type and what it does together: `defineEffect('pull', (context, effect) => ...)`, listed in
+ * `GameModule.effects`. Its fields are said by declaring the type in `EffectTypes`
+ * (`declare module '@v12-engine/engine' { interface EffectTypes { pull: { distance: number } } }`), so that a handler
+ * reads them typed, and an ability's effect of the type is checked for them
+ *
+ * @beta
+ */
+export declare function defineEffect<K extends keyof EffectTypes>(type: K, run: (context: EffectContext, effect: EffectOf<K>) => void, options?: EffectKindOptions): EffectKind<K>;
+/**
+ * Who an effect applies to
+ *
+ * @beta
+ */
+export declare function effectTargets(context: EffectContext, effect: EffectDef, fallback: 'enemies' | 'allies'): Entity[];
+/**
+ * What the attacks of a unit do on top of their damage: the `onHit` effects among what its abilities, and
+ * the items it carries, do all the time. Called for every attack that lands
+ */
+export declare function onHit(world: World, attacker: Entity, target: Entity): void;
+/** Whether an ability of the caster is charged: its `charge` buff is on it with as many stacks as it can have */
+export declare function isCharged(world: World, caster: Entity, ability: AbilityDef): boolean;
+/**
+ * What the passives of the caster do whenever it casts an ability: for a hero, one of the abilities it learns.
+ * Called once the ability went off, and not for one that went off charged: what spends a charge does not count to the next
+ */
+export declare function onCast(world: World, caster: Entity, cast: AbilityDef): void;
+/**
+ * Takes someone off the ground for a leap or a throw. Up there it is nobody's obstacle: it pushes no one
+ * on its way over them, and goes straight over what cannot be walked
+ */
+/**
+ * Sends an entity rushing to a spot (`dash.x`, `dash.z`): nothing stops it on the way, its orders wait, and what
+ * `dash.effects` do happens where it ends. A leap (`dash.height`) takes it off the ground until it comes down
+ *
+ * @beta
+ */
+export declare function startDash(world: World, entity: Entity, dash: Omit<Dash, 'from'>): void;
+/**
+ * What killing someone sets off: the `onKill` effects among what the abilities of the killer do all the time.
+ * `attack` says whether it was one of its attacks that killed
+ */
+export declare function onKill(world: World, killer: Entity, victim: Entity, attack: boolean): void;
+/** Moves the missiles of abilities along, and lets them do what they do to what they pass through and where they come down */
+export declare function updateMissiles(world: World, dt: number): void;
+/** What abilities left behind to happen later, and the ground they go on working on */
+export declare function updateLingering(world: World, dt: number): void;
+/** Carries those who rush somewhere towards where they are going. Nothing holds them up, and what it does happens when they arrive */
+export declare function updateDashes(world: World, dt: number): void;
+/** A missile reaching what it hits, to those who see what it hits */
+export declare const toldMissileHit: import("..").ReplicatedEvent;
+/** Mana given or taken: its side's alone */
+export declare const toldMana: import("..").ReplicatedEvent;
+/** The missiles of abilities in flight the player is told of: their side's, and those where they see (`Snapshot.missiles`); none to a computer */
+export declare const missilesPart: import("..").SnapshotPart<keyof import("..").Snapshot>;

package/dist/abilities/land.d.ts

@@ -0,0 +1,21 @@
+import { type EffectDef } from '#engine/defs';
+import type { BuffInstance, Entity } from '#engine/entity';
+import type { World } from '#engine/world';
+import type { EffectContext } from './effects';
+/** Runs each effect of a list by its handler (`registry.effect`) */
+export declare function run(context: EffectContext, effects: EffectDef[] | undefined): void;
+/** What something an ability set off does where it arrives, and the word to everyone that it did */
+export declare function land(context: EffectContext, effects: EffectDef[] | undefined, impact?: string): void;
+/**
+ * Effects of a buff on its carrier (`onApply`, `onTick`), in the name of who put it there, while they live: from the
+ * ability it came from, or from the buff itself for one put on otherwise
+ */
+export declare function buffEffects(world: World, carrier: Entity, instance: BuffInstance, effects: EffectDef[]): void;
+/**
+ * What a buff that ran out leaves behind: its `onEnd`, in the name of who put it there
+ *
+ * @beta
+ */
+export declare function buffEnded(world: World, carrier: Entity, instance: BuffInstance): void;
+/** Where a spell lands, to those who see the caster or the spot */
+export declare const toldStrike: import("..").ReplicatedEvent;

package/dist/abilities/scaled.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What an ability's numbers come to for the unit that casts it: the parts that grow with its stats, its level as a hero,
+ * its own attack (`Scaling`). Above the stats (`stats.ts`), which know nothing of heroes: a hero's level is the heroes
+ * pack's
+ */
+import { type CasterFacts } from './text';
+import { type Scaling } from '#engine/defs';
+import type { Entity } from '#engine/entity';
+import type { World } from '#engine/world';
+/**
+ * An amount with what the stats of the caster, and the levels of a hero, add to it
+ *
+ * @beta
+ */
+export declare function scaled(world: World, caster: Entity, amount: number, scaling: Scaling | undefined, level: number): number;
+/**
+ * What an entity brings to the numbers of its abilities, now (see `CasterFacts`)
+ *
+ * @beta
+ */
+export declare function casterFacts(world: World, caster: Entity): CasterFacts;

package/dist/abilities/text.d.ts

@@ -0,0 +1,113 @@
+import { type AbilityDef, type BuffDef, type Scaled, type Scaling, type StatKey, type Stats } from '#engine/defs';
+/**
+ * What the caster brings to an ability's numbers: its stats now, its level as a hero, and the attack damage of its own
+ *
+ * @beta
+ */
+export interface CasterFacts {
+    stats: Readonly<Stats>;
+    /** 1 for what is not a hero */
+    heroLevel: number;
+    /** The attack damage it has from its type and its levels, without what it carries or what is on it */
+    ownAttackDamage: number;
+}
+/**
+ * What the text of an ability is worked out from: the ability at a level, its caster, and the buffs it puts on
+ *
+ * @beta
+ */
+export interface AbilityTextContext {
+    ability: AbilityDef;
+    /** The level of the ability: 1 for one that has no levels */
+    level: number;
+    caster: CasterFacts;
+    /** A buff by id, for how long the ones the ability puts on last */
+    buff?: (id: string) => BuffDef | undefined;
+    /** A value of the ability, by name, worked out (see `abilityValues`) */
+    value(name: string): AbilityValue | undefined;
+}
+/**
+ * A part of a value that comes from a stat of the caster: 60% of ability power
+ *
+ * @beta
+ */
+export interface ValuePart {
+    /** The stat, `level` for each level of a hero past the first, `bonusAttackDamage` for what is added to its own */
+    stat: StatKey | 'level' | 'bonusAttackDamage';
+    /** How much of it: 0.6 */
+    ratio: number;
+    /** What that comes to now */
+    amount: number;
+}
+/**
+ * A number of an ability, worked out: its total, and what it is made of
+ *
+ * @beta
+ */
+export interface AbilityValue {
+    total: number;
+    /** What it is without the stats of the caster */
+    base: number;
+    parts: ValuePart[];
+    /** What follows the number: `s` for seconds, `%`. Nothing when left out */
+    unit?: string;
+}
+/**
+ * How a game gives a value of an ability: an amount and what scales it, or worked out in code
+ *
+ * @beta
+ */
+export type AbilityValueDef = {
+    amount?: Scaled;
+    scaling?: Scaling;
+    unit?: string;
+    percent?: boolean;
+} | ((context: AbilityTextContext) => number | AbilityValue);
+/**
+ * A piece of the text of an ability: words, or a value to show as one (bold, its parts in their colours)
+ *
+ * @beta
+ */
+export type TextSegment = string | {
+    name: string;
+    value: AbilityValue;
+};
+/**
+ * The values of an ability at a level, for a caster, by name: its own (`AbilityDef.values`), and what its effects say
+ * when it does not name them itself: `damage`, `heal`, `shield` and `amount` (the first effect of each kind with an
+ * amount), `duration`, `radius`, `range`, `cooldown`, `charges` and `refill`, `mana`, `count` and `distance`
+ *
+ * @beta
+ */
+export declare function abilityValues(ability: AbilityDef, level: number, caster: CasterFacts, buff?: (id: string) => BuffDef | undefined): Map<string, AbilityValue>;
+/**
+ * What the ability says it does, for this caster now: its description with each `{value}` worked out (or its own
+ * `describe`), as words and values. A name it has no value for is left as it is written, braces and all
+ *
+ * @beta
+ */
+export declare function describeAbility(ability: AbilityDef, level: number, caster: CasterFacts, buff?: (id: string) => BuffDef | undefined): TextSegment[];
+/**
+ * How a stat is called in the text of an ability
+ *
+ * @beta
+ */
+export declare const STAT_WORDS: Partial<Record<ValuePart['stat'], string>>;
+/**
+ * A number as an ability's text shows it: whole, or with one decimal when it is small and has one
+ *
+ * @beta
+ */
+export declare function formatNumber(value: number): string;
+/**
+ * A value in words: `80`, or `80 (50 + 60% ability power)` when stats add to it
+ *
+ * @beta
+ */
+export declare function valueText(value: AbilityValue): string;
+/**
+ * The text of an ability as plain words: for a tooltip of words only, a log, a test
+ *
+ * @beta
+ */
+export declare function abilityText(segments: readonly TextSegment[]): string;

package/dist/ai/area.d.ts

@@ -0,0 +1,53 @@
+/**
+ * An area of a brain (`AiArea`): a part of what it keeps and does that its modules share, its economy, its scouting, a
+ * game's own diplomacy, kept in its memory under its id and reported under it. The brain keeps a list of them and asks
+ * each the same things (`ai.area(Economy)`), so that one of a game's own is a peer of the kit's and adding one touches
+ * nothing of the brain
+ */
+import type { Brain } from './brain';
+import type { AiReport } from './report';
+/**
+ * What a brain asks of each of its areas
+ *
+ * @beta
+ */
+export interface AiArea {
+    /** Unique in a brain: what its memory and its report are kept under */
+    readonly id: string;
+    /** Whether it has anything to remember now: one that does not is left out of a save */
+    remembers(): boolean;
+    /** What it remembers, for a save: plain data */
+    save(): unknown;
+    /** Takes back what `save` gave: false for a shape it does not read, and it starts afresh */
+    restore(memory: unknown): boolean;
+    /** What the log says where a save's memory of it is of a shape it does not read */
+    readonly afresh?: string;
+    /** What it says in its brain's report (`AiReport`): its own part of it, written in */
+    reportTo?(report: AiReport): void;
+}
+/**
+ * What finds an area of a brain, and makes it the first time it is asked for (`ai.area(key)`): a class of the kit's
+ * with a static `id` and `make`, or what `defineArea` gives
+ *
+ * @beta
+ */
+export interface AreaKey<T extends AiArea> {
+    readonly id: string;
+    make(ai: Brain): T;
+}
+/**
+ * An area of a game's own, for its brains (`ai.area(diplomacy)`): made for each brain the first time a module asks for it,
+ * remembered in a save under its id (`BrainMemory.areas`) as the kit's are
+ *
+ * @beta
+ */
+export declare function defineArea<T extends AiArea>(id: string, make: (ai: Brain) => T): AreaKey<T>;
+/**
+ * What a brain's areas remember, by id (`BrainMemory.areas`): each area of the kit adds its own here, as a game's own may
+ * (`declare module '@v12-engine/engine/ai' { interface AreaMemories { 'mygame.diplomacy'?: DiplomacyMemory } }`)
+ *
+ * @beta
+ */
+export interface AreaMemories {
+    [id: string]: unknown;
+}