@chronodivide/game-api 0.35.0

package/CHANGELOG.md

@@ -0,0 +1,164 @@
+# Changelog
+
+# 0.35.0
+
+- Update game engine version to 0.42
+
+# 0.34.0
+
+- Update game engine version to 0.41
+
+# 0.33.0
+
+- Update game engine version to 0.40
+
+# 0.32.0
+
+- Update game engine version to 0.39
+
+# 0.31.0
+
+- Update game engine version to 0.38
+
+# 0.30.0
+
+- Update game engine version to 0.37
+
+# 0.29.0
+
+- Update game engine version to 0.36
+
+# 0.28.0
+
+- Update game engine version to 0.35
+
+# 0.27.0
+
+- Update game engine version to 0.34
+
+# 0.26.0
+
+- Update game engine version to 0.33
+
+# 0.25.0
+
+- Add `gameApi.rulesApi`
+- Add `UnitData.isWarpedOut`, `UnitData.mindControlledBy` and `UnitData.tntTimer`
+
+# 0.24.0
+
+- Update game engine version to 0.32
+
+# 0.23.0
+
+- Update game engine version to 0.31
+
+# 0.22.0
+
+- Update game engine version to 0.30
+
+# 0.21.0
+
+- Update game engine version to 0.29
+
+# 0.20.0
+
+- Update game engine version to 0.28
+
+## 0.19.0
+
+- Update game engine version to 0.27
+
+## 0.18.0
+
+- Update game engine version to 0.26
+
+## 0.17.0
+
+- Update game engine version to 0.25
+
+## 0.16.0
+
+- Update game engine version to 0.24
+
+## 0.15.0
+
+- Add `gameApi.getAllSuperWeaponData` and `actionApi.activateSuperWeapon`
+- Update game engine version to 0.19
+
+## 0.14.0
+
+- **BREAKING**: Replace `gameInstanceApi.getTickMillis` and `gameApi.getTickMillis` with `getTickRate`
+- **BREAKING**: Remove `gameApi.getSpeedMultiplier`
+- **BREAKING**: When constructing a `Bot` instance or an `Agent` object, `country` must now be the country name from rules.ini (e.g. "Americans")
+
+## 0.13.0
+
+- **BREAKING**: `gameApi.canPlaceBuilding` and `actionsApi.placeBuilding` now use the normalized (screen top) tile as parameter instead of center tile
+- Update game engine version to 0.18
+
+## 0.12.0
+
+- Add `gameInstanceApi.getCurrentTick`, `gameInstanceApi.getTickMillis` and `gameInstanceApi.getPlayerStats`
+
+## 0.11.0
+
+- **BREAKING**: Remove `gameApi.actions`, `gameApi.getActions` and `gameApi.getProduction`
+- **BREAKING**: Rename `gameApi.map` to `gameApi.mapApi`
+- **BREAKING**: Rename `Bot.actions` to `Bot.actionsApi` and `Bot.production` to `Bot.productionApi`
+- **BREAKING**: Move gameApi methods that where unrelated to game state into a separate `GameInstanceApi`, only accessible top-level via `cdapi.createGame`. `Bot` instances will no longer have implicit access to these methods. Game state is now available only within the `Bot` class.
+- **BREAKING**: Consolidate `gameApi.waitForTick` and `game.tick` into a single `game.update` method
+- Add `Bot.gameApi`
+
+## 0.10.0
+
+- **BREAKING**: The `agents` option for `cdapi.createGame` must now contain `Bot` class instances for non-human players
+- Bot code is now added by extending the base `Bot` class and overriding the `onGameStart`, `onGameTick` and `onGameEvent` methods. The `actions` and `production` properties provide access to scoped `actionsApi` and `productionApi` respectively.
+- `mapApi.getTilesInRect` now properly filters out tiles which are outside the map boundaries
+- Add `mapApi.getAllTilesResourceData` and `mapApi.getTileResourceData`
+- Add `gameApi.getAllTerrainObjects`
+
+## Version 0.9.0
+
+- Add `onBridge` optional argument to `actionsApi#orderUnits`
+- Add `mapApi#hasBridgeOnTile` and `mapApi#hasHighBridgeOnTile` methods
+- Add `gameApi.generateRandom` and `gameApi.generateRandomInt` methods
+- **BREAKING**: `PlayerData.startLocation` now returns the start coords instead of the index into the startingLocations array
+- **BREAKING**: `PlayerData.country` is now a `Country` object instead of the country name string
+- **BREAKING**: `UnitData.owner` now returns the player name instead of the player index
+- **BREAKING**: `PlayerData.isLowPower` is replaced by a `power` property which also includes the total power and drain
+- Add doc-blocks to most API methods and interface properties
+
+## Version 0.8.1
+
+- Add `gameApi.getBuildingPlacementData`
+- Add `gameApi.getPlayers`
+- Add `gameApi.getArtIni`
+
+## Version 0.8.0
+
+- Add `gameApi.getActions`
+- Add online mode
+
+## Version 0.7.4
+
+- Add `gameApi.getSpeedMultiplier`
+- Add `actionsApi.quitGame`
+- Fix replays when actions are issued for multiple agents
+
+## Version 0.7.3
+
+- Fix fatal error caused by a [Webpack compilation bug](https://github.com/webpack/webpack/pull/15246)
+- Update game engine to version 0.17
+
+## Version 0.7.2
+
+- Use the original game *.mix archives instead of the custom JSON files
+
+## Version 0.7.1
+
+- Fix errors caused by special characters in replay file names
+
+## Version 0.7.0
+
+- Initial version (game engine version 0.7)

package/README.md

@@ -0,0 +1,94 @@
+# Chrono Divide Game API
+
+This is a TypeScript/JavaScript API and development sandbox for the [Chrono Divide](https://chronodivide.com) game engine. It can be used to develop and test AI bots by running the game headless, in an isolated command-line environment. The API can create offline games between computer-controlled agents, or even online games, played in real-time versus human opponents.
+
+## Prerequisites
+
+* NodeJS 14+
+* TypeScript 4.3.5+ (optional)
+* MIX files from an original RA2 installation
+
+## Installation
+
+```
+npm install @chronodivide/game-api
+```
+
+## Basic Usage
+
+The following code example creates an offline game, between two AI agents, runs the simulation until the game ends, then saves the game replay and exits.
+
+The bot implementation is not provided.
+
+```ts
+import { cdapi, OrderType, ApiEventType, Bot, GameApi, ApiEvent } from "@chronodivide/game-api";
+
+class ExampleBot extends Bot {}
+
+async function main() {
+    const mapName = "mp03t4.map";
+
+    // Replace MIX_DIR with your original RA2 installation folder
+    await cdapi.init(process.env.MIX_DIR || "./");
+
+    const game = await cdapi.createGame({
+        agents: [
+            new ExampleBot("AgentRed", "Americans"),
+            new ExampleBot("AgentBlue", "French")
+        ],
+        buildOffAlly: false,
+        cratesAppear: false,
+        credits: 10000,
+        gameMode: cdapi.getAvailableGameModes(mapName)[0],
+        gameSpeed: 5,
+        mapName,
+        mcvRepacks: true,
+        shortGame: true,
+        superWeapons: false,
+        unitCount: 10
+    });
+
+    while (!game.isFinished()) {
+        await game.update();
+    }
+
+    game.saveReplay();
+    game.dispose();
+}
+
+main().catch(e => {
+    console.error(e);
+    process.exit(1);
+});
+```
+
+## 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:
+
+```ts
+const game = await cdapi.createGame({
+    online: true,
+    serverUrl: process.env.SERVER_URL!,
+    clientUrl: process.env.CLIENT_URL!,
+    agents: [
+        new ExampleBot(`Agent${String(Date.now()).substr(-6)}`, "Americans"),
+        { name: `Human${String(Date.now()).substr(-6)}`, country: "French" }
+    ],
+
+    buildOffAlly: false,
+    cratesAppear: false,
+    credits: 10000,
+    gameMode: cdapi.getAvailableGameModes(mapName)[0],
+    gameSpeed: 5,
+    mapName,
+    mcvRepacks: true,
+    shortGame: true,
+    superWeapons: false,
+    unitCount: 10
+});
+```
+
+## API Reference
+
+Please refer to the [TypeScript definitions](./dist/index.d.ts).