AI Starter Guide

This document is not yet complete.


Why make AI?


AI scripts are among the most powerful tools developers have when making custom maps, and are the driving force for almost all engagement in an RTS game. High quality AI will consistently challenge players to refine their skills and game knowledge in order to claim victory, either as ruthless enemies or competent allies. Though AI in singleplayer contexts is invariably linear, as only a finite amount of permutations and pseudo-randomness can exist in singleplayer contexts, high quality AI bucks the industry-standard trend of static, uninteractive opponents with nigh-infinite resources and a staggering amount of pre-placed assets, and instead aims to provide as level a playing field as possible.

From mods to cripple-A, $60 products, AI is almost universally subpar, leaving it up to the player to seek out any and all engagement they can get from a title and rarely punishing them for poor or lazy play. Our AI ought to be different, with a penchant for expressing their own personalities, and an innate desire to defeat their opponents and claim victory for themselves - traits often exclusively associated with human players, and rarely expected of AI entities. The simplest way to preserve immersion in your RTS is to make the AI-controlled factions of the world as competent as they are in the narrative, and the simplest way to do that is to write good AI.

This document will introduce you to the technical concepts behind AI scripts, and teach you how to write one of your own. By the end of this starter guide, you'll be able to write better scripts than Blizzard's own, and know what to watch out for when debugging your custom AI. The most important lesson from this foreword is the motivation to design your own AI in the first place - the desire for better gameplay, for better expression of faction personalities, and for better consistency with your campaign's narrative, should it have one.

This is by no means an exhaustive guide, and if you aren't already familiar with the process of unit-testing, you would do well to start now. Changing even small aspects of aiscripts can result in drastic changes in performance, including outright breaking the AI in ways you never thought possible. AI editing is by no means "safe", insofar as your Starcraft instance can crash or freeze if your code is improper, or if you venture too far towards some of the hard-coded limits of the AI system. It is perfectly normal to run into such issues during your scripting adventures, but learning best practices for testing and debugging will save you a lot of time in the long run.

Tools for the Task


The following resources are used on a daily basis by myself and several other aiscripters:
  • The Python Modding Suite (PyMS)
    • Veeq7's version of the Python Modding Suite by poiuy_qwert, used for general modding in addition to importing your aiscripts into your mod.
  • AI extension plugin (experimental commit)
    • Commonly referred to as 'aise', this vital plugin was created by Neiv and is maintained by him and iquare. Its exact features are explained in the extended AI command guide. The plugin is open source and written in the rust programming language, and in its compiled form, it is added to 1.16.1 exes using Firegraft.
  • AI debug plugin
    • Created by Neiv, this plugin is loaded to 1.16.1 exes with Firegraft and allows you to see AI requests and towns, map features like resource areas and regions, a game timer in the form of a frame counter, and other vital information. While in game, use the tilde key () to access the console, and type "help" for a list of commands.
  • Firegraft v0.93
    • For creating custom techtrees, you’ll need to configure a unit's Dat Requirements using Firegraft. This will ensure AI players can train your new units. You must also use Firegraft to create a modded executable, and to add plugins, such as aise or the AI debug plugin, to that exe.
  • AI reference sheet and extended AI reference sheet
    • Exhaustive reference sheets compiled by Nekron and myself respectively. You need not memorize them; think of them instead as encyclopedias that you consult when the syntax or function of a command is hazy or unclear.
  • Expanded unitdef file
    • For use with PyAI. This file replaces the default one in the PyMS folder, providing an exhaustive list of unit ids that you can use should you do any techtree modding in your projects. Keep backups before you edit it for your own purposes, and load the file to PyAI by launching the program and pressing Ctrl+X to bring up the external definitions manager.
  • Notepad++ syntax highlighter
    • Designed by myself, for the purpose of making aiscripts easier to read and to write. No longer shall silly typos prevent you from compiling your aiscript! It automatically associates with .asc3 files, so give your aiscripts that extension. For best visibility, open Notepad++, go to settings -> style configurator, and untick 'global foreground color'.
  • AI archive
    • Includes all AI from the base game and all from every released project of mine. I make references to them in the text below; download them at your own discretion and use them as a learning resource. Reach out for questions if you have any, and remember that the older the project, the more likely the scripting technique is outdated.
  • AI starter video
    • A less technical form of this guide that demonstrates the setup process of PyAI. Due to the video's age, it may contain outdated terms or info. If there are any conflicts, assume the info present on this page is more up-to-date.

Anatomy of an AI


Though this may come as a surprise, I actually recommend opening up Blizzard's campaign AI (or melee, if you intend to write melee AI), if only to take in some information as to how the base game's scripts were written. I myself find them both lacking and poorly organized, but for greenhorns, it's better to look them over than to stare at a blank canvas. Let's dive into the script for the first mission of the UED Campaign, 'First Strike'. Note that this is actually the second mission in Starcraft called 'First Strike', because Blizzard is very creative.

Here's the aiscript in question. It's not a whole lot to work with, and admittedly the script makes liberal use of self-explanatory commands. You can find detailed and mostly-accurate descriptions of commands by mousing over them in PyAI, and use the reference sheets provided above if you need a refresher on any of the more nebulous info.

Every AI begins the same way: with header commands! These are often bizarrely-named (i.e. look them up in the reference sheets to be sure you understand them) and can have far-reaching effects on the AI player's performance. The first lardism to note is that Blizzard calls start_campaign, a header that sets the script class to campaign, changing a wide swath of behaviors of which we don't have complete documentation. They call this command in the script because they didn't realize that the engine does that for them whenever the game type is set to Use Map Settings, so save yourself some effort and forget that command exists unless you're doing something really weird with melee AI. Following that, they do the standard campaign town initialization that you'll become exceedingly familiar with the more you write AI.

Assuming you are in agreement with my position - that AI should start out on a more level playing field than what you find in most RTS content, custom or otherwise - you should take special note of how braindead Blizzard wrote their scripts. Opening the map up yields a huge amount of preplaced bullshit the player must slog through, but scrolling down in the aiscript that hands instructions to the player reveals tiny attacks the likes of which we should never see in a 1v1. When designing AI that is meant to directly confront the player, attacks that don't cause significant damage are wastes of time, both for the computer and for the human player. As such, please don't tell your custom AI to attack a player with a measly 4 marines when they own 155 supply at the start of the game.

More coming soon.

Writing AI


Coming soon.

References


Need a quick example of certain behaviors? Grab the following scripts from the AI archive to see how I made AI that:

  • Sunken pushes
    • Hydra 2.0 -> vterran01, p7_yellowzerg.asc3
    • Stormborne 2019 -> p7_renegadeZ.asc3
  • Tank pushes
    • Hydra 2.0 -> vzerg01, p5_siennamech.asc3


More coming soon.