Program Overview

High-level look at basic bot program.

Program Lifecycle

At start, you are in full control of the program.

Initialization

  • You need to change current working directory to the bin directory in the game installation. Without it, the game will be unable to load maps and assets, even if it might load the shared library.

Warning

Do not change current working directory once configured.

  • Next, you load the shared library.

TODO

The library is automatically loaded when you first access the global Game object. This happens inside the Bot constructor.

  • Setup all your callbacks now. You may also set some parameters for the connection.

Connect

There are multiple ways to connect to a game server. The usual approach is to first try reconnecting, in case the game has crashed previously. Second, you connect to an existing server using the parameters provided in the environment variables, if any. Third, you spin up your own server.

Alternatively, you may implement your own logic to determine how to connect to a server.

No matter the method, the game will now take control over the program. Your program is blocked until the network connection closes. All your further actions will happen inside callbacks only.

Game Loop

All your registered callbacks are now called, when appropriate. Notably, the Update callback is periodically called, no matter the game state. This is where you keep track of the state of the game, and perform any of your actions.

Warning

The Update callback, and some others, may be called before the game has actually started (eg. in Session), or when the map is not yet Loaded. Be mindful of what operations are valid in these circumstances.

You may prematurely close the connection with the Disconnect function. This will do a graceful closing of the connection, that is, you will get some additional callbacks called. After that the connect function will return.

Finalization

When the connection function returns, the network connection has already been closed, and you take back control over the program. You may do any cleanup operations, for example you may save some statistics from the game. Ultimately, you should unload the shared library, and exit the program.

It may be tempting to just loop over and connect to next server, however this is strongly discouraged.

Network

The game is designed for multiplayer, and always plays over network, even in single-player scenarios.

Any actions that you do in your program are first send to the game server, then processed, and then the results are send back to your client.

Example: you call a function to place a construction. After that you look through all the entities and the construction is not there, as expected. You will not know the id of the entity either. The construction will appear only after the game server has processed the request. It is recommended to wait several ticks between these kinds of actions, to avoid placing same construction multiple times in different places.

Note

Test your program over a real network, not just localhost.

Client-only State

Some state is stored on client only, notably:

  • Units orders

  • Pathfinding

  • Logistics planning

Environment Variables

Some variables that may alter the behavior of your bot program.

  • UNNATURAL_ROOT - path to the bin folder that contains the shared library.

  • UNNATURAL_CONNECT_LOBBY - id of Steam lobby to connect to.

  • UNNATURAL_CONNECT_ADDR - IP address or domain name to connect to.

  • UNNATURAL_CONNECT_PORT - port of the game server to connect to.