The Abathur Framework (Prototype)

A bachelor project about developing a framework for modularized bots in StarCraft II.

The goal of the project is to develop a framework that allows developers and researchers to easily develop AIs for specific purposes without having to deal with the full complexity of the game. This is done through a modular design that allows the developer to replace individual modules built around core functionalities that allow for easier interpretation of the current game state.

Our framework is still an early prototype but we would very much appreciate if you would give it a try. We do not accept pull requests at the moment (to avoid potential complex plagiarism issues) but are very open to suggesting (use abathur@adequatesource.com). Please consider filling out your mail (or name) in the questionnaire, as it will help us compare the responses with responses on the evaluation questionnaire.

Menu

Example of one of the simplest, yet still valid, AIs you can write using the framework (with automatic requirement detection).

The framework can do much more than this – explore for yourself!

//TODO: Update video material 
This is actually an older test, the refinery is now queued earlier.

Design must be simple. Elegant. Implementation, less so.

– Abathur

Quick Setup

The Abathur Framework is designed to make it easy to get started working with artificial intelligence for StarCraft II. That being said, this is an early version still in development.

  • Get StarCraft II ready!
    • Download it here from Blizzard (free)
    • Create an account and log in to BattleNet
    • Download ladder 2018 maps and unzip
    • Place them in C:\Program Files (x86)\StarCraft II\Maps (create if folder if non-existing)
  • Get the Abathur Framework
    • Fork the AbathurBot repository
    • Compile and run (initial startup sequence will run)
    • Write your own module using the template /Modules/EmptyModule.cs
    • Configure which modules Abathur should include in /Data/setup.json
    • Fill out this questionnaire (optional, but very kind move)
  • Code some awesome AIs
    • Get familiar with the framework using the included examples
    • Inform us of ‘happy little accidents’ and provide feedback
    • Complain that we are taking too long time patching the happy accident

I will show you the future of the Swarm.

– Abathur

Functionality

The core functionality is now stable enough to release an early prototype. Functionality is still being added, tweaked and polished.

  • Abathur – handles game loop and setup
    • Inherit from IModule and configure your AI using the setup.json file
    • Inherit from IReplacebleModule to allow for replacement of modules at runtime
    • Access the full framework through dependency injection
    • Play Abathur vs Blizzard AI,  Abathur vs. Human or Abathur vs Abathur in realtime or step-mode
    • Access everything from Python using NydusWorm (IN DEVELOPMENT)
  • Intel Manager – handles the representation of the current game state
    • Access enemy and own unit information sorted into three categories: workers, structures, and units.
    • Access ‘colonies’ – clustered minerals, vespene geysers, structures, and workers.
    • Access current researched upgrades.
    • Access current production queue.
    • Register handlers to get events on unit/structure/worker added/destroyed and depleted minerals.
  • Combat Manager – handles commands to units or ‘squads’ (collection of units)
    • Attack, move and use abilities on Squad or a single unit.
    • Register MicroControllers to handle specific unit types differently.
    • Assign a SquadController to squads in order to overwrite default behaviour.
  • Production Manager – handles production queue
    • Queue units, structures and research.
    • Always attempts to satisfy the order, will log a warning if the queue was automatically updated.
    • Will automatically find valid placement with optional spacing and/or near given location
  • Raw Manager – handles communication with StarCraft II client
    • Send async proto request or wait for the client to answer
  • Tech Tree
    • Get unit, structure or research requirements.
  • Game Map
    • Find nearest valid placement for structure (detects energy and creep requirements based on unit type)
    • Check if placement if valid
    • Find chokepoints, fastest path and approximated distance in game steps (IN DEVELOPMENT)
  • Ability, Buff, UnitType, Upgrade repositories – access cached patch-dependent information
    • Cached and saved in a binary file for faster startup
    • Access all or get by id
  • SquadRepository, Squads, Colonies, and Units – always up to date
    • Create Squads (collection of units) and access by name in all modules
    • Dead units are automatically removed from squads
    • Dead workers, depleted minerals are automatically removed from colonies
    • Unit information is updated each frame (if visible) – access frameSinceSeen to check last update status
    • Colonies and squads are synchronized across programming languages – add/remove one and the other modules will know

Perfection goal that always changes. Can pursue, cannot obtain.

– Abathur

Known issues

Issues are expected to arise as the project is still in the early development stages. Keep track of them here and let us know if we missed one.

  • General
    • Mac and Linux not supported in NydusNetwork due to the executable path being for Windows (NydusNetwork 0.1.1)
  • Terran
    • Production Manager queue marines in barrack with techlab, even though barrack with reactor is free.
    • Lift-off will cause the grid to still be seen as ‘blocked’ (unbuildable)
  • Zerg
    • Queuing two zerlings after each other can result in both being set to ‘built’ when the first hatch as the unit added event trickers twice.
    • Lacking creep will halt the production manager, queue with small spacing.
    • Uprooting will cause the grid to still be seen as ‘blocked’ (unbuildable)
  • Protoss
    • Production Manager is unable to handle lack of energy fields. Queue pylons with a large spacing (e.g. 4) to create a large enough energy field to allow for structures to be placed.
    • Prodcution Manager can not use warp gates (coming).

Report unexpected feature Help us (questionnaire)

You. Efficiency hindered. Heal immediately.

– Abathur

Get Started

Abathur Framework

Creating your very first StarCraft II bot

Getting Started With Abathur! The quickest way to get started is to simply fork the AbathurBot repository and get coding! It includes examples and is…
Abathur Framework

Configuring Abathur Modules

Introduction This post covers how to configure the setup.json file for the Abathur Framework and which modules the framework comes pre-packed with. Contents of the…
Nydus Network
Nydus Network Game Settings File
Nydus Network
Connecting with the StarCraft II Client