Supalosa's Chrono Divide Bot

中文版文档

Chrono Divide is a ground-up rebuild of Red Alert 2 in the browser. It is feature-complete and allows for online skirmish play against other players. It also provides an API to build bots, as there is no built-in AI yet.

This repository is one such implementation of a bot. The original template for the bot is available at game-api-playground.

Development State and Future plans

The developer of Chrono Divide has integrated the bot into the game. Therefore, its intention is to be a stable, performant implementation for newer players to play against, rather than a complex and competitive opponent.

See TODO.md for a granular list of structural changes and feature improvements that are planned for the bot.

Feel free to contribute to the repository, or even fork the repo and build your own version.

Repository structure

• packages/chronodivide-bot: The actual bot logic. This is also published to @supalosa/chronodivide-bot and used by the live Chrono Divide game.
• packages/chronodivide-bot-driver: A project that runs the bot and will soon provide debug visualisation capability (since the bot will normally run in headless mode).

Quick start instructions

Node 20 is required by the Chrono Divide API. However, publishing is done on Node 24 or above.

From the root directory:

npm install
npm run watch # will monitor and recompile upon any changes to the bot or driver

Then, in another terminal, from the packages/chronodivide-bot-driver directory:

# for example
export GAMEPATH="C:\Origin\Command and Conquer Red Alert II"

npx cross-env MIX_DIR="${GAMEPATH}" npm start

This will create a replay (.rpl) file that can be imported into the live game.

You can modify index.ts to configure the match. You will most likely want to look at the line with const mapName = "..." to change the map, or the const offlineSettingsXXX to change the bot countries.

Playing against the bot

Currently, playing against this bot is only possible for developers, because it requires you to run this repository from source. Follow these steps to set up online play.

Initial set up steps (one time only)

From the packages/chronodivide-bot-driver directory:

1. Create a Chronodivide account for your bot using the official client at [https://game.chronodivide.com].
2. If you don't already have a Chronodivide account, also create one for you as the player.
3. Copy .env.template to .env. The .env file is not checked into the repo.
4. Set the value of ONLINE_BOT_NAME to the username of the bot from step 1.
5. Set the value of ONLINE_BOT_PASSWORD to the password from step 1.
6. Set the value of PLAYER_NAME to the human's account name.
7. (Optional) Change SERVER_URL if you want to connect to another server. The Chronodivide accounts from step 1 and 2 need to be present on that server.

Running the bot and connecting to the game

Start the bot with ONLINE_MATCH=1. For example:

ONLINE_MATCH=1 npx cross-env MIX_DIR="${GAMEPATH}" npm --node-options="${NODE_OPTIONS} --inspect" start

The bot will connect to the server and should return output like this:

You may use the following link(s) to join, after the game is created:

https://game.chronodivide.com/#/game/12345/supalosa


Press ENTER to create the game now...

Navigate to the link, log in using the human credentials first, then hit ENTER in the terminal so the bot can create the game. Do not hit ENTER too early, as there is a very narrow window for the human to connect to the match.

Debugging

There are many ways to debug the bot.

Breakpoints

To run in headless mode with debugging enabled (i.e. being able to set breakpoints), do:

# VSCode will need to be configured with "auto attach" (ctrl-shift-P -> Debug: Toggle Auto Attach) first.
npx cross-env MIX_DIR="${GAMEPATH}" npm --node-options="${NODE_OPTIONS} --inspect" start

Action logging

The CD API also includes a DEBUG_LOGGING environment variable to log all actions generated by the bot.

DEBUG_LOGGING="action" npx cross-env MIX_DIR="${GAMEPATH}" npm --node-options="${NODE_OPTIONS} --inspect" start

In-replay strings: "global debug text" / "unit debug text"

We also take advantage of the in-game bot debug functionality provided by CD. These are debug actions that are saved into the replay (by way of actionsApi.setGlobalDebugText and actionsApi.setUnitDebugText). The bot must be configured with .setDebugMode(true) to save these actions. When viewing these replays, type the following into the DevTools console of the game client (not this project):

r.debug_text = true;

Snapshot visualisation

The bot driver code includes a extended version of the bot (VisualisedBot) that dumps its state into a PNG file, every X ticks.

new VisualisedBot({
    outFolder: "debug/", tickInterval: 15 * 30
}, botName1, Countries.FRANCE, [], true),

Publishing

A Github Action has been set up on the main repo. We use npmjs's trusted publisher setup to do this.

To publish a new version of the bot, from the root directory (IMPORTANT), do this. (The --workspaces is important to update all of the subpackages)

# usually will be `patch`, can be `minor`/`major` for bigger releases
npm version patch --workspaces --include-workspace-root --no-git-tag-version

To set the version to a beta version, do one of the following:

# prepatch: 0.6.0 -> 0.6.1-beta.0
# preminor: 0.6.0 -> 0.7.0-beta.0
# premajor: 0.6.0 -> 1.0.0-beta.0
npm version prepatch --preid=beta --workspaces  --include-workspace-root --no-git-tag-version

If you are already on a beta version, use the following to increment the .0:

npm version prerelease --workspaces --include-workspace-root --no-git-tag-version

Once the version is set, do the following (unfortunately with npm workspaces we don't get this for free with npm version):

npm install
git add package{,-lock}.json packages/**/*.json
VERSION=$(npm pkg get version | tr -d '"')
git commit --message ${VERSION}
git tag v${VERSION}
git push origin tag v${VERSION}

Contributors

• use-strict: Making Chrono Divide
• Libi: Improvements to base structure placement performance
• Dogemoon: CN Documentation