Tutorials/Artificial Intelligence

From SC2Mapster Wiki
Jump to: navigation, search

Artificial Intelligence (AI)


AI management is scattered across the editor as it needs to have handles in all parts of the editor in order to function.

  • The trigger module contains functions for starting the AI, as well as issuing specific orders.
  • The data module contains information about how the AI should deal with units and spellcasting.
  • The AI Module contains information on how attack waves should be composed and when they should be sent.
  • The Map properties contains information on which players are controlled by AI:s and what difficylty level they should be playing at.

All in all, working with AI requires a good overall knowledge about how the SC2 editor works and fits together. As a result, this walkthrough does not go into very deep detail about the different aspects of the editor.


  • You don't need to use the AI modules if you only want to spawn units and send them at the players. See the "Attack waves without Attack waves" chapter.
  • AIs are only useful if you want to build a custom melee AI or if you want to have a "realistic" base-builder/rebuilder behavuiour from the AI.
  • The easiest way to work with AI is to use the melee AI, launched with Method 2 below. Then you can spawn small groups of units and micro them.

AI vocabulary

AIs have their own unique words that does not really appear in the rest of the game. Here are some efforts in defining and discussing them.

APM limit

AI:s have "superman fingers" which can type and give controls at almost infinite speed - at least in comparison to humans. To cap this activity it can be a good idea to limit the AI:s APM (actions per minute). The default maximum value is 200.


Escorts are assigned by adding a escort to a Wave Target (unit, point, region etc). The result will be a unit that walks at a polar coordinate calculated on the target units location and direction. The Wings of Liberty map "The great Train Robbery" uses the Escorts extensively, as the train components has got escorts.


Towns are bases, as sc2 gamers are used to handle them. The AI defines a town as a point with a radious in which it builds all the buildings. Towns usually have a Town Center, which is a Command Center, Nexus or Hatchery. Depending on how you set up your AI, it will need to have these towns specified, where the specification is a point. In melee maps the start locations are these points. In campaign maps you would have to add these points manually. Make sure that there is enough room for a town center at the location you choose.


Bullies are harassment and guardian units which the AI tries to reproduce at a target location, which is defined when the "build bully" order is issued. Bullies can be used for harassment. Let's say you would like to have some Reapers sent to a enemy base - then make the AI create some Reapoers at the location of the enemy base.

  • Bullies are defined in the Trigger module.
  • Bullies are counted into Stock.
  • Bullies are not the same as Attack Waves.
  • Bullies are included into Attack Waves by default. You have to exclude them manually with the exclude bully function.
  • Bullies can be set to suicide. If so this bully unit will go out and attack until it dies.
  • Bullies are marked as bullies by a unit specific flag, which is not reachable with test functions. Units marked for suicide are.
  • Preplaced units with the "Initially created" checkbox unmarked functions similarly to bullies. But the bullies defined in the Trigger module are dynamic.

Attack Wave

Attack waves are a formalized way of organizing what kind of units the AI should send at their enemies - human or AI. There is quite a lot of actions dedicated to managing this. There is also the AI module, which is dedicated into managing this with a better overview.

  • Attack waves are similar to unit groups, but has additional attributes such as target and orders.
  • Attack waves can be defined with Triggers
  • Attack waves can be defined with the AI Module.

Time Parameters

Time is sometimes mentioned as arrival time and sometimes as departure time.

  • Arrival time refers to how long it should take until the wave is standing at the target point.
  • Departure time refers to how long it should take until the wave is being sent.
  • They are both refered to as "time" in the editor.


A wave is a variable type and contains information about units. You can add and exclude units from a wave. By default, the AI adds units which they have available, which are not marked as "scripted" or "bullies".

  • Waves have Wave Info
  • Waves have a Player
  • Waves have a Staging point.

Wave Info

Wave info carries information about how a wave should be built up. It is not defined by ready units on the map, rather how the wave should be composed, where it should attack and where it should gather. A bit like the settings available in AI Module.

  • Wave info contains the Unit Types (not actual Units) that belongs to the wave.
    • Add units to a wave by adding them to the wave info.
  • Wave info contains Attack instructions:
    • Suicide Attack Info: flags all units as "suicide" which excludes them from stock and makes the AI build more right away.
    • Attack Info: normal attack wave target.

Wave Target

Wave targets can be points, players, units, regions and other things. Instead of always using points the Wave Target offers more freedom in terms of what a target can be. It also contains certain scripting for behaviour of the wave.

  • Escorts use a unit or unit group as target.
  • Harassment can be managed with Targets.
  • A player - including all its bases and units - can be vague target.
  • A point can be assigned as a very specific target.


Personalities are defined in the AI Module. They set the rules for the attack waves which are defined there. You have a list of available personalities which you can assign to an AI from the Trigger Module. It is not possible to design personalities from the Trigger Module. However, it is still possible to add more attack wave rules and setups using custom scripting.

Melee and campaign AIs

The melee AI which you are playing against on Battle.net is embedded into the game libraries. It is not accessible in the Trigger editor. In order to manipulate this AI you will need to extract the appropriate files and edit them.

The making of a campaign AI can be useful if you are building a melee style campaign map, or if you are interested in how the AI is built in StarCraft II. The level of customization is something you have to decide on yourself.

You can make your own Melee AI if you want. But then you would have use the Campaign AI as a starting point. If you use the Melee AI it would have predefined build orders which you can't manipulate.


Tactics refer to how unit types (like Marine, Zergling or Zealot) should use their special abilities when they encounter enemy units. Since this is so ability/unit centered, these settings are located in the Data Module, int Data/Tactical AI Cooldowns and Data/Tactical AI Data. In most cases the default values are good enough. The extra special details is possible to achieve with custom triggers if needed.


AIs can be ordered to rebuild specific structures and units a certain number of times. The settings for this can be found in Unit properties in the Terrain Editor. There is also actions to achieve this. Depending on the AI difficulty various options can be chosen. Easier AIs usually dont rebuild while harder AIs always rebuild. This will manipulate how the AI is percieved to be healing itself when it looses buildings. Heavy rebuilding also means that the players will need to be more agressive in their gameplay. An AI will not rebuild unless they have the resources to do so.

Build order

Build order in AI settings can refer to different things. From a melee gamers perspective, it defines the order in which a player is constructing and training units. In the AI-realm it refers to specific orders which are issued to the AI to build specific units.

  • "Gamer build orders" translates into "AI stock order" and "direct Build/train/research orders".
  • AI Build refers to structures
  • AI Train refers to units
  • AI Research refers to upgrades


Stock settings define how many things of a certain type a AI should target. The AI is stupid about it and does not understand the tech-tree. So if you want a AI to have a Stock of 50 Marines, it would not understand that it first have to build many SCVs, Supply Depots and Barracks. It would look for Barracks and try to que up Marines in them. If the don't exist it will do nothing. Stocks are also incremental in a way that is not entierly obvious. This is how Stock are implemented:

  • AISetStock(2,5,"SCV")
  • AISetStock(2,1,"SupplyDepot")
  • AISetStock(2,10,"SCV")
  • AISetStock(2,3,"SupplyDepot")
  • AIEnableStock(2)

The AI would first build 5 SCVs, then 1 Supply Depots, then 5 more SCVs and then 2 more Supply Depots. If a SCV or Supply Depot gets killed then the AI would try to rebuild it. It would not skip a step even though it could.

  • If the AI does not have enough supply to continue, it will not continue! The AI will just stupidly try to build more workers infinititely.
  • If you dont add the EnableStock then nothing will get built.
  • The AISetStock() functions contains hidden "wait" orders. The AI will not skip a Stock order if it can't build the previous ones.
  • You cant add "Wait()" into the list of Stock orders (like the one above). Doing so will simply delay the EnableStock call which in turn prevents the AI from start building anything. If you want to add delays into the building, like conditions and branching, you would have to add small segments of Stock build orders and add Wait() and conditions after the EnableStock.
  • The cousin of Stock is the direct Build, Train and Research orders. Mixing the two can become very complicated, since the results of the direct build orders will be counted into the Stock.


Almost the same thing as the UnitIssueOrder() action. In this case the AI will try follow through the order for a specified time and also check if there is room for it in regard to its APM limitation.


Filters are used in the interactions between AI units and enemy (or friendly) units. Filters can help targeting the apropriate units.

Flag & State

These two are hidden arrays which all AI players have. You can manipulate them with actions and check their values with conditions.

  • Flags are values in a boolean array
  • State are values in a integer array
  • This means there are two arrays which you can manipulate.
  • The meaning of the flags are up to you to define.
  • States may not be 0.


Beacons are invisible target points which the AI is using to navigate in the game world. It is a Preset type and is accessible through the Trigger Modules actions. They are not automated, so if you set up a BeaconExpand somewhere, the campaign AI will not react to it. It is more of a way to organize locations which are important. You could make your own list of beacons. On the other hand, there are special alerts corresponding to these beacons, so the Melee AI you are playing with on Battle.net probably uses them to alert fellow players of activity.

  • BeaconScout
  • BeaconRally
  • BeconIdle
  • BeaconHarass
  • BeaconExpand
  • BeaconDetect
  • BeaconDefend
  • BeaconCustom4
  • BeaconCustom3
  • BeaconCustom2
  • BeaconCustom1
  • BeaconClaim
  • BeaconAuto
  • BeaconAttack


This feature of AI library is quite self explanatory, as the goal is to send out a unit which will travel around in unexplored terrain. If there are town-centers it will try to travel to these locations. You define the scouting activity depending on how much minerals the player has gathered and various time values.

(Direct) Order

While the Stock system gives the AI a order in which it should expand its base and army, the direct orders are complementary. If you give an AI a direct order (build, train or research) it will try to do that immideatly. If it can't do it - it will not do it. The window of that order is gone and you would have to issue the order later on again. The Stock and Wave systems on the other hand makes the AI wait until it has the capacity to carry out the order - and then does it.

  • Specific units can be given specific orders (movement/spellcasting).
  • Attack waves are sent with the Send attack wave function.
  • AIBuild() is used for buildings
  • AITrain() is used for units
  • AIResearch() is used for upgrades
  • AIOrder() is for issuing orders to units. It makes it possible to wait until a good opportunity will occur.
  • UnitIssueOrder() is used for specific units. It will try to cast it immideately. If it can't it will skip the order and move on.
  • UnitGroupIssueOrder() is used for unit groups. It will try to cast it immideately. If it can't it will skip the order and move on.


AI:s usually have individual difficulties.

'The prefered way:' in the terrain editor, the variable type "Difficulty" and the game variant settings, the difficulties are:

  • Very easy
  • Easy
  • Medium
  • Hard
  • Harder
  • Very Hard
  • Elite
  • Cheater 1
  • Cheater 2
  • Cheater 3

In the Blizzard campaigns they are using the difficulties:

  • Easy
  • Normal
  • Hard
  • Brutal

In the trigger editor, some functions that use difficulty use the difficulties:

  • Easy
  • Normal
  • Hard
  • Expert

As you can see, they are very inconsistent! But to be sure that your map can facilitate all the difficulty levels you want: the first setup (10 options) is the prefered one. This will enable your players to choose difficylty in the default Battle.net game lobby as well as make it possible for you to customize the unit (rebuilding) on your map. See a discussion further down in this article about difficulty levels vs. player skill.

  • There is a difficulty setting for the Test Document in Preferences, but it is unclear how this parameter defines the game.

Building an AI from scratch


In order to run a AI you need to make a Player controlled by a Computer.

  • Map>Player Settings : make player controlled by computer.

Next thing to do is to launch the AI when the map is initiating. This is done by creating a new Trigger with an event listener "Map Init". In this trigger you use one of the following methods, depending on what you wish to achieve. The reason why Blizzard developers made so many methods of starting an AI is a big question mark. Just pick one and move forward.

Method 1 - Default Melee

This method will set up the default melee resources for all players.

  • MeleeInitOptions() - Sets visibility and other options, like melee gameplay.
  • MeleeInitResources() - Gives the players 100 minerals each.
  • MeleeInitUnits() - creates 6 workers and 1 town center for all players, but only if you have defined starting locations.
  • MeleeInitAI() - launches the ai and its build orders. The AI will play out like the standard melee ai, with the difficulty set in game lobby.

Method 2 - Selective Melee

This method will launch melee settings for one player at a time. The above example affected all players.

  • MeleeInitOptions()
  • MeleeInitResourcesForPlayer(2)
  • MeleeInitUnitsForPlayer(2)
  • AIMeleeStart(2)

Method 3 - Super specifific Melee AI

Sets up an melee AI using the most specific method. This AI will build according to the default melee stock-scheme.

  • PlayerModifyPropertyInt(2, c_playerPropMinerals, c_playerPropOperSetTo, 100)
  • PlayerModifyPropertyInt(2, c_playerPropVespene, c_playerPropOperSetTo, 0) - no vespene
  • UnitCreate(6, "SCV", No Options, 2, (UnitGetPosition(CommandCenter[x,y], 270))
  • AIStart(2, false, 200)
  • AISetAllStates(2,1)
  • AIDeclareTown(2,0,(UnitGetPosition(CommandCenter[x,y], 270))
  • AIHarvest(2,0)

Method 4 - A basic Campaign AI

This AI will not build anything.

  • PlayerModifyPropertyInt(2, c_playerPropMinerals, c_playerPropOperSetTo, 100)
  • PlayerModifyPropertyInt(2, c_playerPropVespene, c_playerPropOperSetTo, 0) - no vespene
  • UnitCreate(6, "SCV", No Options, 2, (UnitGetPosition(CommandCenter[x,y], 270))
  • AICampaignStart(2)

Method 5 - "AI module" AI

This method requires that you have defined a personality in the AI module.

  • PlayerModifyPropertyInt(2, c_playerPropMinerals, c_playerPropOperSetTo, 100)
  • PlayerModifyPropertyInt(2, c_playerPropVespene, c_playerPropOperSetTo, 0) - no vespene
  • UnitCreate(6, "SCV", No Options, 2, (UnitGetPosition(CommandCenter[x,y], 270))
  • cai_start(###,2) - starts the AI with personality ###.

Method 6 - Campaign launcher

Uses the same function as method 3, but does not require the same settings in the beginning. They will however have to be added later when build orders are issued.

  • PlayerModifyPropertyInt(2, c_playerPropMinerals, c_playerPropOperSetTo, 100)
  • PlayerModifyPropertyInt(2, c_playerPropVespene, c_playerPropOperSetTo, 0) - no vespene
  • UnitCreate(6, "SCV", No Options, 2, (UnitGetPosition(CommandCenter[x,y], 270))
  • AIStart(2,true,200)

Town Management

Depending on the AI you decided to use (Melee or Campaign) different scenarios unfold here. If you chose Melee AI, not much to do. If you picked the Campaign AI it is a different matter. These functions regulate town management.

  • AIDeclareTown()

Build Orders


Attack waves without Attack waves

In the simplest form, you will not need to use attack wave variables. In many cases the easiest way to achieve an attacking group of enemies is to simply spawn them and give them an order to attack a players base. This can be done with:

  • UnitCreate()
  • UnitGroupAdd()
  • UnitGroupIssueOrder()

The problem of working like this is that it will make the AI uncertain about what the orders should be. Should it gather the units for the next attack wave or should it send them forward. Don't be surprised if the units are moving back and forward in a strange pattern.

Attack waves with Triggers

Attack waves with AI Module


When you are using the campaign AI, it will not know when it should surrender. Even if all its buildings are lost it does not know that it should surrender. As a result, you will have to set up a trigger wich regurarly counts the players units. If this value is lower then some threshold you will have to run a GameOver() action. Usually, when mapmakers are working with custom AI:s, the campaign or mission is defining the victory conditions, so this problem has a tendency to solve itself.

Templates & Tricks

Build Orders


Preplaced Hidden Units as blueprints

In the units properties it is possible to check a box called "Initially Created". If you uncheck this box, the model on the map will become transparent. If you play the game you will see that the building (or unit) is not created. To make an AI build this unit, simply launch a campaign AI using method 4-6. The AI will try to rebuild them and prioritize them higher then their other stock. You can of course still set the rebuild count to specific values in the unit properties.

Difficulty level vs. player skill

Not an exact science...

A difficulty trick

This trick makes it very clear what the consequences of different difficulty levels will affect the game.

Create a function called "intByDifficulty(player,a,b,c,d,e,f,g,h,i,j)" where the letters indicate a difficulty option (a=very easy, j = cheater 3). Add a switch in the function, and let it switch on the players difficulty. Return the parameter that corresponds to the players difficulty. This makes it possible to work like this:

  • player = 2;
  • numMarinesToSpawn = intByDifficulty(player,0,0,0,0,0,3,5,6,10,20);

If the AI of player 2 is set to be very easy, no Marines will be spawned. If the player has been set to Cheater 3, it will spawn 20.

Nyus worms and AI:s

Nydus worms are tricky in terms of AI orders. Once you suck units into them their handles dissapears. A fix for this is to create a "Move Unit to Point" action followed with a "Actor play animation" for the Nydus worms ejection (the blurp animation).

Forking stock and build orders

To better manage different "recipies" for construction, consider using Triggers instead of Actions. Triggers can be stored as variables and sent as parameters. If you write your scripts directly as code you can do the same thing with Actions, but this will not work in the graphical interface of the Trigger Module.


SC2Mapster AI Forum

Wiki reference sheet

How to work with AI:s

AI examples

Battle.net Forum Threads