@chronodivide/game-api 0.45.0 → 0.46.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+# 0.46.0
+
+- Update game engine version to 0.52
+- Add `actionsApi.setGlobalDebugText` and `actionsApi.setUnitDebugText`
+- Add `Bot.logger` and `Bot.getDebugMode`/`Bot.setDebugMode` as preferred method of logging
+- Deprecated `Point2D` inteface in favor of `Vector2`
+- **BREAKING**: Add `CreateOnlineOpts.botPassword`. This is used for the bot to login to the server, using `Bot.name` as nickname.
+- Add filter predicate to `gameApi.getAllUnits`
+- Add `gameApi.getNeutralUnits` and `gameApi.getUnitsInArea`
+- Add `gameApi.getAiIni`
+- Add `gameApi.getBaseTickRate` and `gameApi.getCurrentTime`
+- Add `GameMath` export, which provides deterministic cross-platform versions of `Math.pow`, `Math.sqrt` and trigonometric functions
+- Add `mapApi.getRealMapSize`
+- Add `mapApi.findPath`
+- Improve performance of `gameApi.canPlaceBuilding` when called many times in succession using different tile values.
+
 # 0.45.0
 
 - Update game engine version to 0.51

package/README.md

@@ -64,16 +64,17 @@ main().catch(e => {
 
 ## Online Games
 
-Online games between an AI and a human opponent are also possible, but require a Chrono Divide server URL to connect to. Online games can be created with minimal changes to the `createGame` function from the previous example:
+Online games between an AI and a human opponent are also possible, but require a Chrono Divide server URL to connect to and a bot account. Online games can be created with minimal changes to the `createGame` function from the previous example:
 
 ```ts
 const game = await cdapi.createGame({
     online: true,
     serverUrl: process.env.SERVER_URL!,
     clientUrl: process.env.CLIENT_URL!,
+    botPassword: process.env.BOT_PASSWORD!,
     agents: [
-        new ExampleBot(`Agent${String(Date.now()).substr(-6)}`, "Americans"),
-        { name: `Human${String(Date.now()).substr(-6)}`, country: "French" }
+        new ExampleBot(`BotNickname`, "Americans"),
+        { name: `PlayerNickname`, country: "French" }
     ],
 
     buildOffAlly: false,
@@ -92,3 +93,82 @@ const game = await cdapi.createGame({
 ## API Reference
 
 Please refer to the [TypeScript definitions](./dist/index.d.ts).
+
+## Debugging
+
+### Application logging
+
+Debug logging can be enabled by setting the `DEBUG_LOGGING` environment variable when running in the sandbox, or the `r.debug_logging` console variable in the game client. To enable, set this variable to a string containing a comma-delimited list of loggers.
+
+For example, to print player actions as they are processed, you can set `DEBUG_LOGGING=action`.
+
+### Bot logger
+
+The `Bot` class exposes its own `logger`, which allows more granular control and filtering, especially when there are multiple bots printing messages at the same time. Logged messages are also prefixed with the bot name and in-game timestamp.
+
+By default, the logger prints only warnings and errors. Debug mode (see below) enables all log levels.
+
+### Debug mode
+
+Bot debug mode is a flag set on the `Bot` class, which toggles certain debug features on or off, like logging or setting debug labels. Debug mode is generally controlled automatically by the game client, but it can also be enabled from the sandbox, by calling `botInstance.setDebugMode(true)`.
+
+**IMPORTANT**: `setDebugMode()` should never be called from within the bot implementation class itself.
+
+Debug mode can be enabled within the game client by setting the value of the `r.debug_bot` console variable to the player index (0-based) of the bot that is being debugged.
+
+E.g.: `r.debug_bot=1` will debug the bot in player slot index 1 (the second slot) and `r.debug_bot=0` will disable debugging.
+
+### Unit debug labels and global debug text
+
+The game client offers the following features which can aid debugging bot code:
+
+- Displaying a multiline debug string attached to a unit or building. To use this feature, the bot implementation should call `actionsApi.setUnitDebugText`. Once set, this text is persistent, until overwritten by a new value.
+- Displaying a sticky always-on-top multiline text, at a fixed position on the screen, below the chat area. To use this, call `actionsApi.setGlobalDebugText`. This text is also persistent and offers no scrolling functionality. The value is simply overwritten. Use this feature to display relevant debug stats on the screen. Logging should be done using the bot logger instead.
+
+In both cases, debug text will be printed in the game client only if the console variable `r.debug_text=1` is set.
+
+**IMPORTANT**: Both `actionsApi.setUnitDebugText` and `actionsApi.setGlobalDebugText` will generate a player action as workaround for not being able to directly remote control a game client. This is a consequence of the bot code running in its own sandbox and not being directly connected to a game client. As a result, this can generate considerable network noise, as well as increased replay file size. For this reason, both functions only work when bot debug mode is enabled and require an account with bot privileges in online mode.
+
+## Notes on deterministic code
+
+The game loop must be guaranteed to give the exact same game simulation provided that the player inputs/commands and initial state are identical. This means that code must be deterministic, or, given the same input, it will always produce the same output. Otherwise, multiplayer games will often result in fatal desyncs, because each client will have its own slightly different version of reality. Singleplayer games will not crash, but loading replay files or save games will be unreliable for the same reason.
+
+Even though a bot running in the sandbox doesn't necessarily need to be deterministic when fighting a real player over the network, it does however need to be once integrated in the game loop. Below is a non-exhaustive table of unsafe JavaScript built-in functions, and their safe version offered through the game API.
+
+|JavaScript built-in | Game API equivalent | Notes |
+|--|--|--|
+| `Math.random` | `gameApi.generateRandom` and `gameApi.generateRandomInt` | Uses a PRNG |
+| `Math.pow`, `**` operator | `GameMath.pow` | Only works with integer exponents; precision of 6 decimals |
+| `Math.sqrt` | `GameMath.sqrt` | |
+| `Math.sin` | `GameMath.sin` | Uses a LUT; resolution of ~0.006rad |
+| `Math.cos` | `GameMath.cos` | Uses a LUT; resolution of ~0.006rad |
+| `Math.asin` | `GameMath.asin` | Uses reverse LUT lookup |
+| `Math.acos` | `GameMath.acos` | Uses reverse LUT lookup |
+| `Math.atan2` | `GameMath.atan2` | Precision of 3 decimals |
+| `Math.acosh` | Unsupported | |
+| `Math.asinh` | Unsupported | |
+| `Math.atan` | Unsupported | |
+| `Math.atanh` | Unsupported | |
+| `Math.cbrt` | Unsupported | |
+| `Math.cosh` | Unsupported | |
+| `Math.exp` | Unsupported | |
+| `Math.expm1` | Unsupported | |
+| `Math.hypot` | Unsupported | |
+| `Math.log` | Unsupported | |
+| `Math.log10` | Unsupported | |
+| `Math.log1p` | Unsupported | |
+| `Math.log2` | Unsupported | |
+| `Math.sinh` | Unsupported | |
+| `Math.tan` | Unsupported | |
+| `Math.tanh` | Unsupported | |
+
+Safe version of THREE.js geometry/math classes are also provided:
+
+| THREE.js class | Game API equivalent |
+|--|--|
+| THREE.Vector2 | Vector2 |
+| THREE.Vector3 | Vector3 |
+| THREE.Box2 | Box2 |
+| THREE.Euler | Euler |
+| THREE.Quaternion | Quaternion |
+| THREE.Matrix4 | Matrix4 |

package/dist/index.d.ts

@@ -1,6 +1,3 @@
-import { Euler as Euler_2 } from 'three';
-import { Quaternion as Quaternion_2 } from 'three';
-
 export declare class ActionsApi {
     #private;
     placeBuilding(buildingName: string, rx: number, ry: number): void;
@@ -22,6 +19,30 @@ export declare class ActionsApi {
     orderUnits(unitIds: number[], orderType: OrderType, targetUnit: number): void;
     orderUnits(unitIds: number[], orderType: OrderType, rx: number, ry: number, onBridge?: boolean): void;
     sayAll(text: string): void;
+    /**
+     * Prints a persistent multiline debug string in the game client at a fixed position on the screen
+     *
+     * **IMPORTANT**: This method only works when bot debug mode is enabled
+     *
+     * If the bot is in online mode, it will send this text as a player action (only enabled for bot accounts).
+     * The game client also needs to have r.debug_text=1 enabled in the dev console.
+     *
+     * If the bot is in offline mode, this method will still generate actions that may increase the replay file size
+     * significantly.
+     */
+    setGlobalDebugText(text: string | undefined): void;
+    /**
+     * Sets a persistent multiline debug label for a given unit, which the game client will display anchored to the unit
+     *
+     * **IMPORTANT**: This method only works when bot debug mode is enabled
+     *
+     * If the bot is in online mode, it will send this text as a player action (only enabled for bot accounts).
+     * The game client also needs to have r.debug_text=1 enabled in the dev console.
+     *
+     * If the bot is in offline mode, this method will still generate actions that may increase the replay file size
+     * significantly.
+     */
+    setUnitDebugText(unitId: number, text: string | undefined): void;
     quitGame(): void;
 }
 
@@ -76,17 +97,30 @@ export declare enum AttackState {
 }
 
 export declare class Bot {
+    #private;
     name: string;
     country: string;
     protected gameApi: GameApi;
     protected actionsApi: ActionsApi;
     protected productionApi: ProductionApi;
+    protected logger: LoggerApi;
     constructor(name: string, country: string);
+    /**
+     * Toggles bot debug mode, allowing the bot implementation to switch some debug features on or off.
+     * This also enables or disables debug logging.
+     *
+     * This method is controlled by internal game code and should not be called by the bot implementation itself.
+     */
+    setDebugMode(debugMode: boolean): this;
+    getDebugMode(): boolean;
     onGameStart(gameApi: GameApi): void;
     onGameTick(gameApi: GameApi): void;
     onGameEvent(ev: ApiEvent, gameApi: GameApi): void;
 }
 
+export declare class Box2 extends THREE.Box2 {
+}
+
 export declare enum BuildCat {
     Combat = 0,
     Tech = 1,
@@ -98,7 +132,7 @@ export declare interface BuildingPlacementData {
     /** The size of the building foundation in tiles */
     foundation: Size;
     /** The offset of the foundation center tile */
-    foundationCenter: Point2D;
+    foundationCenter: Vector2;
 }
 
 export declare enum BuildStatus {
@@ -208,6 +242,7 @@ export declare interface CreateOnlineOpts extends CreateBaseOpts {
     online: true;
     serverUrl: string;
     clientUrl: string;
+    botPassword: string;
     agents: [Bot, ...Agent[]];
 }
 
@@ -238,7 +273,7 @@ export declare class Euler extends THREE.Euler {
     private _z;
     private _order;
     setFromRotationMatrix(m: Matrix4, order?: string, update?: boolean): this;
-    reorder(newOrder: string): Euler_2;
+    reorder(newOrder: string): this;
     toVector3(optionalResult?: Vector3): Vector3;
 }
 
@@ -278,7 +313,12 @@ export declare class GameApi {
     getPlayers(): string[];
     getPlayerData(playerName: string): PlayerData;
     getAllTerrainObjects(): number[];
-    getAllUnits(): number[];
+    /** Queries all units and buildings on the map, regardless of owner */
+    getAllUnits(filter?: (r: TechnoRules) => boolean): number[];
+    /** Queries neutral units and buildings on the map */
+    getNeutralUnits(filter?: (r: TechnoRules) => boolean): number[];
+    /** Queries units in a given area of tiles. Uses a quadtree and is more efficient than scanning tile by tile. */
+    getUnitsInArea(tileRange: Box2): number[];
     /**
      * Gets a list of units which are visible to the given player (not under the shroud), based on hostility
      *
@@ -292,6 +332,7 @@ export declare class GameApi {
     getGeneralRules(): GeneralRules;
     getRulesIni(): IniFile;
     getArtIni(): IniFile;
+    getAiIni(): IniFile;
     /**
      * Generates a random integer in the specified [min, max] interval using the internal PRNG.
      * Must be used instead of Math.random() when computing game state to prevent desyncs between clients
@@ -302,9 +343,16 @@ export declare class GameApi {
      * Must be used instead of Math.random() when computing game state to prevent desyncs between clients
      */
     generateRandom(): number;
-    /** Current game speed in ticks/second. IMPORTANT: The game speed can change during a game */
+    /** Current game speed in ticks per real-time second. IMPORTANT: The game speed can change during a game */
     getTickRate(): number;
+    /** Game speed in ticks per in-game second (at game speed 4) */
+    getBaseTickRate(): number;
     getCurrentTick(): number;
+    /**
+     * Current game time in game seconds.
+     * The get the time in real-time seconds, use {@link GameApi.getCurrentTick} / {@link GameApi.getTickRate} instead
+     */
+    getCurrentTime(): number;
 }
 
 export declare class GameInstanceApi {
@@ -319,6 +367,23 @@ export declare class GameInstanceApi {
     dispose(): void;
 }
 
+/**
+ * Defines custom approximations of built-in Math functions, guaranteed to yield consistent results across platforms
+ *
+ * See https://stackoverflow.com/questions/42181795/is-ieee-754-2008-deterministic and
+ * https://stackoverflow.com/a/56486907
+ */
+export declare class GameMath {
+    /** Raises base to an integer power */
+    static pow(x: number, y: number): number;
+    static sqrt(x: number): number;
+    static sin(x: number): number;
+    static cos(x: number): number;
+    static asin(x: number): number;
+    static acos(x: number): number;
+    static atan2(y: number, x: number): number;
+}
+
 export declare interface GameObjectData {
     id: number;
     type: ObjectType;
@@ -402,7 +467,7 @@ export declare class GeneralRules {
     wallBuildSpeedCoefficient: number;
     readIni(ini: IniSection): void;
     private readPrereqCategories;
-    getMissileRules(type: string): DMislRules | V3RocketRules;
+    getMissileRules(type: string): V3RocketRules | DMislRules;
 }
 
 export declare class HoverRules {
@@ -551,10 +616,30 @@ export declare enum LocomotorType {
     Vehicle = 8
 }
 
+export declare class LoggerApi {
+    #private;
+    debug(...x: any[]): void;
+    info(...x: any[]): void;
+    log(...x: any[]): void;
+    warn(...x: any[]): void;
+    error(...x: any[]): void;
+    time(label: string): void;
+    timeEnd(label: string): void;
+}
+
 export declare class MapApi {
     #private;
+    /**
+     * The map size in real/world space tiles.
+     *
+     * IMPORTANT: Tile coordinates within the real map size only correspond to actual tiles if those tiles are
+     * within the visible map area. The visible map area uses ISO screen projection,
+     * depends on tile elevations, and cannot be deduced using linear transformations or used to compute map boundaries.
+     * Use {@link MapApi.getTile} instead to check if a given tile is within the map boundaries.
+     */
+    getRealMapSize(): Size;
     /** Tile coordinates for each player starting position */
-    getStartingLocations(): Point2D[];
+    getStartingLocations(): Vector2[];
     getTheaterType(): TheaterType;
     getTile(rx: number, ry: number): Tile | undefined;
     getTilesInRect(baseTile: Tile, size: Size): Tile[];
@@ -562,6 +647,13 @@ export declare class MapApi {
     hasBridgeOnTile(tile: Tile): boolean;
     hasHighBridgeOnTile(tile: Tile): boolean;
     isPassableTile(tile: Tile, speedType: SpeedType, onBridge: boolean): boolean;
+    /**
+     * Returns the path between two points on the map for the given SpeedType.
+     *
+     * Should only be used with ground, non-teleporting units.
+     * This method has a big performance penalty and should be used with care.
+     */
+    findPath(speedType: SpeedType, from: PathNode, to: PathNode, options?: PathFinderOptions): PathNode[];
     /** If the tile is not covered by shroud for the specified player */
     isVisibleTile(tile: Tile, playerName: string): boolean;
     getTileResourceData(tile: Tile): TileResourceData | undefined;
@@ -792,6 +884,20 @@ export declare interface ParadropSquad {
     num: number;
 }
 
+export declare interface PathFinderOptions {
+    /** Restricts the number of searched path nodes (default = Infinity) */
+    maxExpandedNodes?: number;
+    /** If true, returns a partial path, even if the target is unreachable (default = true) */
+    bestEffort?: boolean;
+    /** Dynamically exclude path nodes */
+    excludeNodes?(node: PathNode): boolean;
+}
+
+export declare interface PathNode {
+    tile: Tile;
+    onBridge: boolean;
+}
+
 export declare enum PipColor {
     Green = 0,
     Yellow = 1,
@@ -804,7 +910,7 @@ export declare interface PlayerData {
     name: string;
     country: Country | undefined;
     /** The starting tile coordinates for the player (where the initial MCV is placed) */
-    startLocation: Point2D;
+    startLocation: Vector2;
     isObserver: boolean;
     /** Whether the player is an integrated AI. Not applicable to sandbox agents. */
     isAi: boolean;
@@ -824,6 +930,7 @@ export declare interface PlayerStats {
     startLocation: number;
 }
 
+/** @deprecated use Vector2 instead */
 export declare interface Point2D {
     x: number;
     y: number;
@@ -923,7 +1030,7 @@ export declare class Quaternion extends THREE.Quaternion {
     setFromAxisAngle(axis: Vector3, angle: number): this;
     setFromRotationMatrix(m: Matrix4): this;
     length(): number;
-    slerp(qb: Quaternion, t: number): this | Quaternion_2;
+    slerp(qb: Quaternion, t: number): this;
 }
 
 export declare interface QueueData {
@@ -1660,6 +1767,13 @@ export declare class V3RocketRules extends MissileRules {
     readIni(ini: IniSection): this;
 }
 
+export declare class Vector2 extends THREE.Vector2 {
+    length(): number;
+    angle(): number;
+    distanceTo(v: Vector2): number;
+    rotateAround(center: Vector2, angle: number): this;
+}
+
 export declare class Vector3 extends THREE.Vector3 {
     applyEuler(euler: Euler): this;
     applyAxisAngle(axis: Vector3, angle: number): this;