@v12-engine/engine 0.1.1 → 0.4.0

package/dist/ai/knowledge.d.ts

@@ -1,4 +1,4 @@
-import type { ResourceKind } from '#engine/defs';
+import type { ResourceId } from '#engine/defs';
 import type { AiArea } from './area';
 import type { PlayerId } from '#engine/entity';
 import { type Vec2 } from '#engine/math';
@@ -31,12 +31,19 @@ export interface KnowledgeOptions {
  * @beta
  */
 export interface StructureSeen {
+    /** The entity id of the structure */
     id: number;
+    /** The unit type id of the structure */
     type: string;
+    /** The player the structure belonged to when seen */
     owner: PlayerId;
+    /** Where the structure stands, in cells */
     at: Vec2;
+    /** The tick it was first in sight */
     first: number;
+    /** The tick it was last in sight */
     last: number;
+    /** The tick it was known to be gone; nothing while it stands as far as known */
     gone?: number;
 }
 /**
@@ -46,15 +53,21 @@ export interface StructureSeen {
  * @beta
  */
 export interface ArmySighting {
+    /** Where the middle of the group was, in cells */
     at: Vec2;
+    /** The tick the group was seen at */
     tick: number;
+    /** The player the most of the group belong to */
     owner: PlayerId;
+    /** How many fighters the group has */
     count: number;
     /** Their health together, as seen */
     health: number;
     /** Their strength together, as seen (`Strength.of`, with the health each had left) */
     strength: number;
+    /** How many of each unit type are in the group, by type id */
     types: Record<string, number>;
+    /** How many heroes are among them */
     heroes: number;
 }
 /**
@@ -64,12 +77,19 @@ export interface ArmySighting {
  * @beta
  */
 export interface UnitSeen {
+    /** The entity id of the unit */
     id: number;
+    /** The unit type id of the unit */
     type: string;
+    /** The player the unit belongs to */
     owner: PlayerId;
+    /** Where it was last seen, in cells */
     at: Vec2;
+    /** The tick it was last seen at */
     tick: number;
+    /** The hero's level as last seen; none for a unit that is not a hero */
     level?: number;
+    /** The tick it was seen to die; nothing while it is not known dead */
     died?: number;
 }
 /**
@@ -78,8 +98,11 @@ export interface UnitSeen {
  * @beta
  */
 export interface TypeSeen {
+    /** The tick the type was first seen */
     first: number;
+    /** The tick the type was last seen */
     last: number;
+    /** The most units of the type seen at once */
     most: number;
 }
 /**
@@ -90,16 +113,21 @@ export interface TypeSeen {
  * @beta
  */
 export interface EnemyBase {
+    /** The player the base belongs to */
     owner: PlayerId;
+    /** Where the base is, in cells: its middle */
     at: Vec2;
     /** When the first of it was seen */
     first: number;
     /** When any of it was last in sight */
     last: number;
+    /** The structures of it as remembered, gone ones included */
     structures: StructureSeen[];
     /** Whether it is around what takes deposits: a hall, not a lone tower */
     hall: boolean;
+    /** Whether every structure of it is known gone */
     gone: boolean;
+    /** Whether it is a further base of the owner, not the first seen of theirs */
     expansion: boolean;
 }
 /**
@@ -108,10 +136,15 @@ export interface EnemyBase {
  * @beta
  */
 export interface Loss {
+    /** The entity id of what died */
     id: number;
+    /** The unit type id of what died */
     type: string;
+    /** Where it died, in cells */
     at: Vec2;
+    /** The tick it died at */
     tick: number;
+    /** The unit type id of its killer, when it was seen */
     by?: string;
 }
 /**
@@ -120,8 +153,11 @@ export interface Loss {
  * @beta
  */
 export interface AttackSent {
+    /** The tick the attack was sent at */
     tick: number;
+    /** Where the attack was sent, in cells */
     at: Vec2;
+    /** How many units it was sent with */
     count: number;
 }
 /**
@@ -130,9 +166,13 @@ export interface AttackSent {
  * @beta
  */
 export interface PingHeard {
+    /** The tick the ping was heard at */
     tick: number;
+    /** The player who pinged */
     player: PlayerId;
+    /** Where the ping marked, in cells */
     at: Vec2;
+    /** The kind of ping, its id */
     kind: string;
 }
 /**
@@ -142,12 +182,19 @@ export interface PingHeard {
  * @beta
  */
 export interface DamageSeen {
+    /** The tick the damage was seen in */
     tick: number;
+    /** The entity id of what was damaged */
     id: number;
+    /** The unit type id of what was damaged */
     type: string;
+    /** The player whose entity it is */
     owner: PlayerId;
+    /** Where it stood, in cells */
     at: Vec2;
+    /** The damage done to it over the think */
     amount: number;
+    /** The unit type id of what did it, when it was seen */
     by?: string;
 }
 /**
@@ -156,11 +203,17 @@ export interface DamageSeen {
  * @beta
  */
 export interface DeathSeen {
+    /** The tick the death was seen in */
     tick: number;
+    /** The entity id of what died */
     id: number;
+    /** The unit type id of what died */
     type: string;
+    /** The player whose it was */
     owner: PlayerId;
+    /** Where it died, in cells */
     at: Vec2;
+    /** The unit type id of what killed it, when it was seen */
     by?: string;
 }
 /**
@@ -170,14 +223,19 @@ export interface DeathSeen {
  * @beta
  */
 export interface KnowledgeMemory {
+    /** The version of the memory's format: 1 so far */
     v: 1;
     /** The tick it was last brought up to date */
     tick: number;
+    /** The enemy structures remembered */
     structures: StructureSeen[];
     /** Newest first */
     army: ArmySighting[];
+    /** The enemy workers last seen */
     workers: UnitSeen[];
+    /** The enemy heroes last seen */
     heroes: UnitSeen[];
+    /** The enemy unit types seen, by type id */
     types: Record<string, TypeSeen>;
     /** The tick each cell of the map was last in sight, row by row (-1: never); `cols` cells a row */
     looked: {
@@ -185,19 +243,24 @@ export interface KnowledgeMemory {
         rows: number;
         ticks: number[];
     };
+    /** The own things that died, newest first */
     lost: Loss[];
+    /** The attacks a module sent */
     attacks: AttackSent[];
     /** What was gathered of each resource since the game began, as far as rises in what the player has tell */
-    gathered: Record<ResourceKind, number>;
+    gathered: Record<ResourceId, number>;
     /** What the player had at the last update, to see the next rise against */
-    had?: Record<ResourceKind, number>;
+    had?: Record<ResourceId, number>;
     /** Samples of `gathered`, oldest first */
     history: {
         tick: number;
-        gathered: Record<ResourceKind, number>;
+        gathered: Record<ResourceId, number>;
     }[];
+    /** The pings heard */
     pings: PingHeard[];
+    /** The damage seen in the last thinks */
     damage: DamageSeen[];
+    /** The deaths seen in the last thinks */
     deaths: DeathSeen[];
 }
 declare const LIMITS: {
@@ -237,6 +300,7 @@ export declare class Knowledge implements AiArea {
     readonly events: HeardEvents;
     /** Where in the fog each cell of the map is read: found again when the fog or the map is of another size */
     private sample;
+    /** The options it runs with: those given over the defaults, the limits being the built-in ones */
     readonly options: Required<Omit<KnowledgeOptions, 'army' | 'limits'>> & Pick<KnowledgeOptions, 'army'> & {
         limits: typeof LIMITS;
     };
@@ -285,6 +349,7 @@ export declare class Knowledge implements AiArea {
     /** What it remembers, as plain data for a save: a copy */
     /** Whether it has anything to remember now: one that does not is left out of a save */
     remembers(): boolean;
+    /** Gives a copy of what is known, as plain data for a save of the brain */
     save(): KnowledgeMemory;
     /** Takes back what `save` gave. Memory of another shape is dropped: it starts afresh */
     restore(memory: unknown): boolean;
@@ -386,11 +451,11 @@ export declare class OwnKnowledge {
      * What it gathers of a resource a minute, over the last so many seconds (60): from the rises in what it has, so it
      * is at least this (what was gathered and spent between two thinks does not show). Bounty counts as gathered
      */
-    income(kind: ResourceKind, seconds?: number): number;
+    income(kind: ResourceId, seconds?: number): number;
     /** The income of every resource gathered so far, a minute (`income`) */
-    incomes(seconds?: number): Record<ResourceKind, number>;
+    incomes(seconds?: number): Record<ResourceId, number>;
     /** What was gathered of each resource since the game began, as far as the rises tell */
-    get gathered(): Readonly<Record<ResourceKind, number>>;
+    get gathered(): Readonly<Record<ResourceId, number>>;
     /** The samples of what was gathered, oldest first */
     get history(): KnowledgeMemory['history'];
 }