Getting started#

From nothing to two bots playing a match, then a bot of your own.

What you need#

• Windows 10 or 11.
• Inversus on your Steam account. The framework is built for version 1.2.0, the one Steam serves; ibf setup downloads exactly that version from your account.
• Python 3.11 or later from python.org, 64-bit or 32-bit. Tick "Add python.exe to PATH" in its installer.

Nothing else: the framework's DLLs need no runtime installed, and you need no compiler unless you write bots in C or C++.

1. Install the package#

pip install ibf-0.9.0-py3-none-win_amd64.whl

Take the wheel that matches your Python: win_amd64 for 64-bit, win32 for 32-bit (python -c "import struct; print(struct.calcsize('P') * 8)" says which). The wheel holds the Python package and the ibf command, the client library, the files ibf setup puts into the game, the example bots, and the C/C++ SDK. Check it with ibf --version.

2. Set up the game#

ibf setup "C:\Games\Inversus"

Give it any folder: an empty one, or one that already has the game. It runs four stages, each checking its own result, and prints a summary:

1. Game files. If the folder lacks the game, Steam must be running and signed in. ibf setup opens the Steam console and shows one line to paste into it (download_depot 432980 432981 2896194810162905201). Steam then downloads Inversus 1.2.0 (about 55 MB) without showing progress; ibf setup waits, and copies the files over when they are complete. If you already have the files somewhere, --source <folder> skips the download. Every file is checked against the known build.
2. Patch. The Steam build carries a copy protection (SteamStub) that keeps the framework out; a fixed set of byte edits removes it. The original is kept as Inversus.exe.bak.
3. Deploy. extension.dll next to Inversus.exe, the host and its game profiles in ibf\, and ibf's own steam_api.dll, which answers the game's Steam calls and loads extension.dll (Valve's is kept as steam_api.dll.valve). It writes ibf\ibf.toml, the configuration, with player slots 0 and 1 as bot pads: the controllers bots play.
4. Smoke test. It starts the game, asks the framework for its status, and closes it.

ibf setup remembers the folder, so the other commands find the game without being told. Run it again whenever you like, for instance after installing a newer ibf: it skips what is done and updates the framework's files.

3. Launch the game#

ibf launch

This starts the game from its folder and waits until the framework inside it answers. A status bar appears at the top of the game window: the frame rate, whether your keyboard and mouse reach the game, the overlay's state, the tick and the game's phase, and how many bots are connected.

Some keys, which work in the game window:

Your keyboard and mouse are held back at first, so that typing in another window cannot steer the game while bots play. Press F5 to play by hand; press it again to hold them back.

4. Watch a match#

ibf match hunter idle

hunter and idle are two of the example bots that come with the package: hunter lines up with its enemy and shoots, idle stands still. ibf match starts each bot as a separate process on pads 0 and 1, sets the match up through the game's own menus, follows it round by round, and writes the results to results\<time>.json.

The first versus match on a new save starts with the game's how-to-play: a few pages that each wait until both players have done what they teach (moving, firing, charging, a pickup, a kill). The framework plays them for the bots, which takes a minute or two each time the game shows them. The game writes its save only when it exits cleanly, so after a game that was killed it shows them again. A versus match is first to three rounds. --matches 5 plays five, --map 1 picks another map, and --record records each match (see Matches, lockstep and replays).

5. Your own bot#

ibf new mybot
ibf match mybot.py idle

ibf new writes mybot.py, a working bot to change: it walks toward the nearest enemy over the tiles it can stand on, and shoots when they share a clear row or column. Open it in an editor; Writing bots explains every part.

While you work on it, play it on its own and let it restart whenever you save:

ibf run mybot.py --pad 0 --watch

On its own, a bot only holds its pad: start a match by hand (F5, then the menus), or leave the matches to ibf match.

To play against your bot with a controller, make only slot 1 a bot pad (in ibf\ibf.toml, bot_pads = [1], then restart the game). Your controller is then player 1 and drives the menus, and your bot plays player 2: ibf run mybot.py --pad 1.

Stopping and uninstalling#

Close the game as usual; bots stop when the game goes. Ctrl+C stops a bot or a match.

To turn the framework off without uninstalling: set enabled = false under [host] in ibf\ibf.toml, or set the environment variable IBF_DISABLE=1. To put the game back as it was (the original Inversus.exe and Valve's steam_api.dll):

ibf setup "C:\Games\Inversus" --uninstall

It keeps ibf\ (your configuration and the logs); --purge removes that too.