The No-Frauds Club » Starcraft » SCAI Command Guide
AI Command Guide
Introduction
The following is a reference sheet of commands for ASC3, originally collated by Nekron.
ASC3 is a procedural programming language used in the games Starcraft and Starcraft: Brood War for AI scripting.
Other useful files include:
Flags and headers
farms_notiming
"Sets a flag that makes the Computer Player build necessary farms (Overlords, Supply Depots, Pylons - only of the Computer Player’s respective race) only when it hits exactly the maximum supply available."Notes:
1) The Computer Player can get stuck if it’s waiting to train a 2-supply unit but is missing 1 supply to get capped.
farms_timing
"Sets a flag that makes the Computer Player build necessary farms with a correct timing, so that it never gets supply capped."start_areatown
"Starts the AI Script for area town management. Uses the trigger location (NOT regions) as its bounds for assigning buildings to the town, but the state 5 and 6 regions themselves are created in relation to building placement, not the location. Might cause issues with town management if used mid-game, mostly intended for preplaced bases, ran at the time of town init."start_campaign
"Sets the campaign flag which affects town management significantly. Redundant in UMS, since the UMS game setting forces it onto all players."Generic header structure for towns:
wait 1
start_town
defaultbuild_off
default_min 0
wait 1
And for areatowns:
start_campaign
start_areatown
defaultbuild_off
default_min 0
wait 1
Notes:
1) Waits in both headers should NOT be removed, but start_campaign can. Removing the waits desyncs building assignment.
start_town
"Starts the AI Script for town management."Notes:
1) Buildings need to be assigned to a town to be used at all by the Computer Player. All pre-placed buildings that are not inside of an areatown get assigned to the last called start_town.
2) start_town is also needed for every block that an expansion opcode uses, but notably there are no race checks for assigning a worker that starts the new town.
transports_off
"The Computer Player will not train transports and observers on its own."Notes:
1) It will still use existing ones.
check_transports
"Makes the Computer Player train transports on its own beyond their base values."Notes:
1) Trains transports or overlords up to 5. The first transport is built at priority 80 and subsequent transports are built at priority 50. Protoss also trains up to 5 observers at priority 80. The numbers might change depending on the amount of preplaced transports and whether the Computer Player has the campaign flag set or not.
Train commands
default_build
"If the Computer Player has more than 600 minerals and 300 gas and no other requests, it will continuously train race specific units until it reaches the define_max value or gets supply capped.If it has other requests, it instead requires at least 1500 minerals and gas to train default_build units."
Terran: marine, ghost, siege_tank, goliath, wraith, battlecruiser.
Zerg: hydralisk, mutalisk.
Protoss: zealot, dragoon, reaver, scout, carrier.
Notes:
1) default_build is on by default. To turn it off, use defaultbuild_off.
2) In the vanilla game, using train/wait_force/do_morph for (unittype) while the Computer Player is requesting a guard replacement of (unittype) will instead call default_build that lasts until the train/wait_force request is filled.
defaultbuild_off
"Turns off default_build. default_build should realistically always be turned off."train
train quantity military"Train %2military until at least %1quantity of them are being trained, at priority 50. Waits and stops script execution until the condition is fulfilled."
Notes:
1) Doesn’t execute if the Computer Player has other requests while simultaneously having less than 1500 minerals and gas. The request is checked every 30 frames, and the command waits for 16 frames every time the requirement is not filled.
do_morph
do_morph quantity military"If Computer Player commands less than %1quantity of %2unit, attempt to immediately train one of %2unit. Doesn’t re-apply the train request and doesn’t wait for anything."
wait_train
wait_train %quantity %military"Wait until the Computer Player commands %1quantity %2military. Does not request training."
wait_force
wait_force quantity unit"Wait until the Computer Player commands %1quantity %2unit, while training up to %1quantity %2unit as long as it’s waiting. The submitted train request is re-checked every 30 frames, and the command waits 16 frames every time the requirement is not filled."
Attack commands
Attack note: You should never use attack_prepare or target_expansion before 16 frames have passed or else the attacks will have a broken timeout timer and will possibly never fire.
The default target is picked semi-randomly for campaign scripts, or is the closest possible target for melee scripts. Grouping occurs within 5 pathfinding regions of the target for campaign scripts, for melee scripts there’s an additional check to see whether the area’s safe before picking a grouping region. Some commands check force values in the region where the target is located at the time of their usage.
Attacking uses 3 different states. More on region states under “SCAI#Region States”.
attack_add
attack_add quantity military"Add %1quantity %2military to the current attacking party. Trains units at priority 50 if attack_prepare was used, but requires separate train uses for special attacks like target_expansion or eval_harass."
Notes:
1) %1byte can be at most 64; the units beyond the 64th one are ignored and not added to the attack. Multirunning multiple attack forces in a way that keeps units as already attacking can be used to bypass the 64 size limit.
2) In unmodded Starcraft, Zerg AIs ignore units inside cocoons or eggs, so any training command including attack_add with attack_prepare will cause Zerg AIs to overtrain certain units, and in the case of hydra->lurker and muta->guard/devo transitions, use them in the attack.
3) Unit IDs of Defiler, Queen, Science Vessel, High Templar will arrive in the grouping region for the attack, but don’t follow the attack force after grouping is finished. Other casters and hero casters follow properly, though all units without a weapon will retreat after getting attacked.
attack_clear
"Resets the existing state 8 regions to 0, and clears the attack list."Notes:
1) Some types of attacks can’t start unless the attack data is cleared first.
attack_do
"Prepare the attack and attack the enemy with the current attacking party afterwards. Waits for grouping to finish and for the attack to launch before resuming script execution."Notes:
1) Preparing the attack has a hard-cap on it’s length of 120 (melee) or 180 (campaign) seconds - after this time, the attack will commence even if the Computer Player didn’t manage to group all units.
2) If a special attack type or attack_prepare has already been used, this command only waits.
3) Should not be used with attack types that don’t perform grouping.
4) Captain unit note: SC1 AI has no captain units, instead region centers are used for rallying.
attack_prepare
"Prepare the attack and attack the enemy with the current attacking party afterwards."Generic attack structure:
attack_add 4 marine
attack_do
attack_clear
set_attacks
set_attacks value"Sets the number of attacks possible to execute with target_expansion. Cannot be used if the campaign flag is set."
Notes:
1) With enough set_attacks left, target_expansion can re-prepare the same force and execute the attack again.
target_expansion
"Executes an expansion attack with a deadline of 1 second."Notes:
1) Requires the units to be trained beforehand and practically has no grouping.
2) Expansion attacks never choose bases built around start locations before 1500 in-game seconds. They can acquire those bases as targets afterwards, but they will still prefer to target expansions.
quick_attack
"Sets the starting attack point back far enough in time so that the deadline goes down to 5 seconds."Notes:
1) Never use this if it would set the starting point to before the first 16 frames of the game. For example, don’t use it with normal attacks in campaigns before 2976 frames have passed.
2) Never use it in conjunction with eval_harass or target_expansion.
eval_harass
eval_harass block"Compares current attack force (of units attack_added to current team) to the enemy forces (uses strength formula for calculations) in a randomized attack region picked based on AI type; if current attack force is stronger than the enemy forces, jumps to %1block and executes an attack that targets that region without preparing. If it’s not, it sets the attack timer back [lapsed game seconds] and terminates it after ~80 frames."
harass_factor
harass_factor value"If AI is grouping to attack, get player id of closest enemy unit to grouping region, get sum of ground and air strength of this player's units, and if strength > 0, and calculate intensity value.
Intensity value is calculated as "(sum of strength + %1value) - 1)/%1value - 1". If intensity value > 3, set it to 3.
The attack list is then modified, duplicating or triplicating its unit quantities."
The formula is as follows:
((enemystrength-1)/(value))-1
Division is rounded down, multiplication is in range of 1 (no change) to 3.
wait_finishattack
"Waits until there are no state 1/2/8/9 regions existing for the owner of the thread."prep_down
prep_down quantity1 quantity2 unitId"Add all %3unitId to the current attacking party except for %1quantity1 of them. However it must send, and trains, a minimum of %2quantity2 of them."
Defense commands
defensebuild_aa
defensebuild_aa quantity unitId"Train %1quantity %2unitId to defend against enemy air force or enemy air + ground force in unpathable regions."
defensebuild_ag
defensebuild_ag quantity unitId"Train %1quantity %2unitId to defend against enemy air force in pathable regions."
defensebuild_ga
defensebuild_ga quantity unitId"Train %1quantity %2unitId to defend against enemy ground force in unpathable regions that have no enemy air units in them."
defensebuild_gg
defensebuild_gg quantity unitId"Train %1quantity %2unitId to defend against enemy ground force in pathable regions."
Defense note:
The maximum quantity values of all defense requests of a given type (for example _aa) can reach 20 maximum. Requests beyond this will be ignored.
defensebuild order is as follows:
1) Check regions that need only air strength and train from _aa/_ag until force requirements are met
2) Check regions that need ground strength but have a nonzero air strength and train from _aa/_ag until force requirements are filled, however air force values of trained units are used to calculate vs ground force region requirements
3) Check regions that need ground strength and have no air force and train from _gg/_ga until force requirements are met
defenseclear_aa
"Clear all requests for _aa defense."defenseclear_ag
"Clear all requests for _ag defense."defenseclear_ga
"Clear all requests for _ga defense."defenseclear_gg
"Clear all requests for _gg defense."defenseuse_aa
defenseuse_aa quantity unitId"Use %1quantity %2unitId to defend against enemy air force or enemy air + ground force in unpathable regions."
defenseuse_ag
defenseuse_ag quantity unitId"Use %1quantity %2unitId to defend against enemy air force in pathable regions."
defenseuse_ga
defenseuse_ga quantity unitId"Use %1quantity %2unitId to defend against enemy ground force in unpathable regions that have no enemy air units in them."
defenseuse_gg
defenseuse_gg quantity unitId"Use %1quantity %2unitId to defend against enemy ground force in pathable regions."
max_force
max_force value"Lets the Computer Player use up to %1value worth of units to defend any given defensible region."
%1value is based off the following formula:
(sqrt((range / cooldown) factor† damage + (((factor damage 2048) / cooldown) (hp + shields)) / 256) 7.58) / unit_specific_reduction‡ script_class_modifier§ + 0.5 energy for casters¶
† factor: Weapon factors from weapons.dat.
‡ unit_specific_reduction: Workers get 25% of default; Interceptors, Scarabs, and Spider Mines get 0%; Firebats, Mutalisks, and Zealots get 200%; Defilers and Infested Terrans get 1/16; Reavers get 10%.
§ script_class_modifier: 1 for campaign, 1.5 for melee.
¶ energy for casters: Updated on spawn and whenever they’re marked as active. All weaponless casters have a force value of 1 by default, making their force value 26 when spawned without energy upgrades. This value is never used for casters in production, where it’s 0 instead.
Notes:
1) On melee, only state 3 and 4 regions will respect max_force values assigned for mirrored defense reqs.
2) On melee, the default max_force for ground units is 1500 and for air units is 1000, and there's a limited possibility of making max_force changes.
guard_all
"Sets all regions containing units owned by the Computer Player to state 5. Identical on melee."help_iftrouble
"For every active Computer Player allied to the AI Script owner, sets their regions to state 4 in every region the AI Script owner has a non-zero state."default_min
default_min value"Sets the default needed force value for state 4 and state 6 regions. default_min is 0 when not specified."
Notes:
1) In melee, the Computer Player will have a default force value of 1000 ground force for regions attacked by air units, and of 1000 air force for regions attacked by ground units
capt_expand
"Creates state 4 regions around the Computer Player’s state 5 regions and around other state 4 regions.If default_min is greater than 0, causes the Computer Player to train first of it’s defensebuild_gg and _aa units until it hits a supply cap, define_max limit or has no resources left. The Computer Player then tries to distribute all these units over to state 4 regions, as evenly as possible. The production of these units has a priority based on the regions they’d be sent to, which usually results in a priority of 10."
guard_resources
guard_resources unitId"Send units of type %1unitId to guard as many unacquired base locations as possible (1 per spot)."
place_guard
place_guard unitId location"Place one %1unitId to guard town at strategic %2location, at priority 60."
location has three valid parameters:
- 0 = town center
- 1 = mineral line
- 2 = geyser/refinery
1) Preplaced units in campaign scripts also become guards.
2) Guards don’t get removed unless they die three times while still being a guard.
3) Guards are bound to a specific spot on the map: Transports, Carriers and Reavers will never travel to that point though, and morphing units tend to be displaced from the spot they should be sitting in after they morph (this includes both archons).
4) A guard unit can be assigned to defending or attacking - then it loses it’s guard status and the Computer Player will try retraining a guard for that spot every (unit training time + 5) in-game seconds.
5) High and Dark Templar can morph into Archons while still being considered guards. This causes one of them to count as killed (raises kill count of the guard spot by 1) and the other to retain it’s guard status as an Archon - even though the guard spot would still be assigned to a Templar in theory. Overall, most morphing units will cause noticeable overproduction of their composite units and be off-centered with where they stand compared to other non-morphing units.
6) There is a vanilla 1.16/1.20+ bug that crashes the game related to guards - more in “SCAI#Additional bugs issues".
Techtree commands
Build/Tech/Upgrade note: Max of 100 Build/Tech/Upgrade requests can be made per town. Crashes above 100.
build
build quantity unitId priority"Build %2unitId until it commands %1quantity of them, at %3priority."
Notes:
1) The maximum value of %1quantity is 30 per town. Max worker values can be lower and are dynamic, based on the number of mineral patches.
player_need
player_need quantity unitId"Adds a request to the town that makes it so that if the player does not own %1quantity of %2unitId anywhere, then he rebuilds them in this town at priority 80."
wait_build
wait_build quantity unitId"Wait until the Computer Player has finished construction of or commands %1quantity %2unitId. Works only for buildings, workers, and overlords."
wait_buildstart
wait_buildstart quantity unitId"Wait until the Computer Player has started, finished construction of, or commands %1quantity %2unitId."
build_bunkers
"Builds up to 3 bunkers around the base (Terran only). Seems to build them in regions where there are no static defenses."build_turrets
"Builds up to 6 missile turrets around the base (Terran only). Seems to build them in regions where there are no static defenses."Notes:
1) Terran AIs will always place siege_tank and ghost guards around newly built bunkers, and a ghost guard around newly built missile turrets.
wait_bunkers
"Waits for the build_bunkers command to finish. Takes no parameters."wait_secure
"Wait until the Computer Player trains a defenseunit with a defensebuild command of any type. Is usable again after going through within about 7 seconds earlygame or 37 seconds later in the game (likely after 1500 frames)."wait_turrets
"Waits for the build_turrets command to finish. Takes no parameters."tech
tech techId priority"Research technology %1techId at %2priority."
upgrade
upgrade level upgradeId priority"Research upgrade %2upgradeId up to %1level at %3priority. The maximum value for %1level is 31."
wait_upgrades
"Waits until all upgrade (but not tech) requests have begun researching. Only works in campaign scripts."Notes:
1) Supposedly waits until level 3 has started researching if you use it immediately from 0. You should wait approximately 30 seconds (wait 480) before setting the requests and using wait_upgrades, so that the request log has enough time to update.
wait
wait quantityWait until %1quantity frames have passed. 24 frames is one second on the fastest game speed.
Flow control commands
call
call block"Call %1block as a sub-routine."
Notes:
1) Only one call can be made in the game at all times from any Computer Player running a script. In the vanilla game, if player 1 makes a call, and then player 2 makes a call, it will override player 1's call and control the flow of the return statement. Can be used for multiple players to simultaneously execute the same code.
2) Be sure that there are no wait commands or blocking commands inside the call to have it function correctly with multiple players.
return
"Return to the flow point of the call command."enemyowns_jump
enemyowns_jump unitId block"If an enemy player commands at least one %1unitId (includes buildings in construction), jump to %2block."
enemyresources_jump
enemyresources_jump quantity1 quantity2 block"If the closest enemy player has at least %1quantity1 minerals and %2quantity2 gas then jump to %3block."
goto
goto block"Jump to %1block."
groundmap_jump
groundmap_jump block"If the closest enemy player can be reached without using transports, jump to %1block."
region_size
region_size value block"Jump to %2block if the town this command is used in has a pathfinder region count (meaning the sum of pathfinder regions connected and pathable by ground) below 32 times %1value."
if_owned
if_owned unitId block"If the player owns a %1unitId (includes incomplete), jump to %2block."
killable
"Sets a flag that allows the current thread to be killed by another one. The killed thread always finishes whatever wait command it’s currently stuck on before stopping."kill_thread
"Kills all threads that have the killable flag, including threads owned by other players."notowns_jump
notowns_jump unitId block"If the Computer Player doesn't have a %1unitId, jump to %2block."
Changed in aise: now only checks completed units.
race_jump
race_jump block1 block2 block3"Jump to %1block1 if the race of the nearest enemy player is Terran, %2block2 if Zerg, or %3block3 if Protoss."
random_jump
random_jump chance block"Has a %1chance out of 256 to jump to %2block."
resources_jump
resources_jump quantity1 quantity2 block"If the current player has at least %1quantity1 minerals and %2quantity2 gas, jump to %3block."
time_jump
time_jump quantity block"If %1quantity normal game minutes have elapsed in the game, jump to %2block."
try_townpoint
try_townpoint quantity block"If the Computer Player does not have at least %1quantity expansions (includes areatowns), jump to %2block."
rush
rush value block"If %1value rush condition is met, jump to %2block. It also picks a target and calls “attack_clear” afterwards.
(Possibly a special attack? needs more research, reach out if you have more accurate information.)"
Rush conditions
TERRAN
0: Is constructing or commands a Barracks
1: Infantry Score result > 16
2: Infantry Score result > 24
3: Infantry Score result > 5
4: Infantry Score result > 16
5: Infantry Score result > 6
6: Infantry Score result > 12
7: Commands a Siege Tank
8: Infantry Score result > 5
9: Infantry Score result > 9
10: Infantry Score result > 4
11: Infantry Score result > 10
12: Infantry Score result > 16
13: Infantry Score result > 24
ZERG
0: Is constructing or commands a Spawning Pool
1: Ground Score result > 10
2: Air Score result > 10
3: Ground Score result > 2, or commands a Hydralisk Den
4: Ground Score result > 10
5: Ground Score result > 6
6: Zerg Sunken Colonies > 1
7: Commands a Queen
8: Ground Score result > 2
9: Ground Score result > 4
10: Ground Score result > 4
11: Ground Score result > 10
12: Air Score result > 5
13: Air Score result > 10
PROTOSS
0: Is constructing or commands a Gateway
1: Zealots > 6
2: unused
3: Zealots > 1
4: Zealots > 8
5: Zealots > 3
6: Dragoons > 1
7: Zealots > 6
8: Zealots > 1
9: Zealots > 5
10: Zealots > 2
11: Zealots > 5
12: Air Score result > 2
13: Air Score result > 7
Rush scoring system
TERRAN Infantry Score
if (bunkers 4 <= marines)
result = marines + bunkers 4;
else
result = 2 marines;
ZERG Ground Score
result = Hydralisks + Sunken Colonies 2
ZERG Air Score
result = Hydralisks + Mutalisks + Spore Colonies 2
PROTOSS Air Score
result = Dragoons + Scouts
stop
"Stop script code execution."
Multithreaded commands
expand
expand value block"Run code at %2block for expansion %1number."
allies_watch
allies_watch resarea block"Expand at %1resarea using %2block. Does nothing if the expansion is occupied (Resarea flag = 1)."
Notes:
1) The maximum value for %1resarea is 250.
2) If %1resarea is equal or less than the number of start locations on the map, the expansion will be in a player's starting base.
panic
panic block"If the Computer Player has not expanded yet and the total unmined minerals in the connected fields is less than 7500, expand using %1block. If the Computer Player has expanded before, the command triggers every time there are less than 7500 unmined minerals total in all owned bases, or there are less than 2 owned geysers that are not depleted."
Notes:
1) Can cause crashes if any of the map’s free resareas have no resources and never had them.
multirun
multirun block"Run %1(block) simultaneously, as a new thread with the same town ID."
Notes:
1) In unmodded Starcraft, there is a limit of 100 threads working on a map simultaneously.
Misc commands
create_nuke
"Create a nuke. Requires an empty nuclear silo for the Computer Player."create_unit
create_unit unitId PosX PosY"Create %1unitId at map coordinates %2PosX %3PosY."
creep
creep value"Controls the spread of photon cannons and creep colonies. Wide if %1value = 4, or narrow if it’s anything else."
debug
debug block string"Show debug string %2string and jump to %1block. Does not work in aiscripts included in bwscript.bin."
define_max
define_max quantity unitId"Defines the maximum %1quantity of %2unitId the Computer Player can train. %1quantity of 255 equals zero."
Notes:
1) Preplaced guards don’t count towards the limit.
fatal_error
"Crashes Starcraft with a fatal error and the message 'Illegal AI script executed.'."get_oldpeons
get_oldpeons quantity"Transfer %1quantity workers from the main to the expansion. Should be used after the expansion town center has finished building."
give_money
"Gives the Computer Player 2000 minerals if it has less than 500, and gives 2000 gas if it has less than 500. Does nothing if neither resources are below 500."nuke_pos
nuke_pos posX posY"Launch a nuke at map coordinates %1PosX %2PosY. Requires an available ghost and armed nuclear silo."
nuke_rate
nuke_rate quantity"Sets the nuke timer to %1quantity, which causes the Computer Player to try using nukes every %1quantity game minutes. nuke_rate is 0 when not specified."
Notes:
1) nuke_rate 0 allows the Computer Player to launch multiple nuclear missiles at once, up to the number of armed nuclear silos.
2) The nuke timer resets only when a nuke has been launched, otherwise the AI will continuously send ghosts one by one or waits until a nuclear missile has finished production.
fake_nuke
"Resets the Computer Player's nuke timer."send_suicide
send_suicide value"The Computer Player executes a random or strategic suicide mission. %value determines which type."
value has two valid parameters:
0: Strategic Suicide Mission
Sends all units that are not set to ignore strategic suicide missions in units.dat, in a manner identical to a normal attack. Can only be used one time until attack_clear is used.
1: Random Suicide Mission
Sends all units, including workers and heroes, to attack the nearest enemy unit. Needs to be repeated on a loop, otherwise units will become idle after destroying/losing their target.
Notes:
1) After sending a strategic suicide mission, attack_clear should not be used before the units have finished preparing. Using attack_do eliminates the risk of clearing the attack too soon, and makes the strategic suicide mission valid for wait_finishattack and other such attack commands. attack_prepare does not seem to be of any use here.
set_randomseed
set_randomseed dword"Set random seed to %1dword. Supposedly limits the number of random scenarios that can occur. Player inputs cause random seeds to be unpredictable, thus it’d only ever be useable in opening cutscenes. Due to a general lack of information on what it changes, its usage is niche and obscure."
Notes:
1) %1dword is an integer value in the range 0 through 4294967295.
implode
"Changes the state of AI regions to 4 for any region which has state 0, 1, 2, or 3 that's connected to at most one pathfinding region by ground."Region States
state 0Nothing: might “need” a force, but is not defended unless within (some) radius of a state 5 region. It then can turn into state 6 or 3.
If defended, defense priority is 10.
When a region is denoted as “being created” below, it usually means that it’s state is turning from state 0 into something else - since regions obviously can’t get created mid-game.
state 1
Continue attack here. Not defended.
state 2
Attacking: Always appears before state 1 and is used for the first attack target. Not defended.
state 3
Enemy spotted: Can’t repair/rebuild and defend if made from a state 5 region. If there are neighboring state 4 regions when it’s created, it can set one of them to state 7.
state 4
This state is used by numerous commands:
It’s used for defending future towns, and a few temporary state 4 regions are created around expansions that are currently being constructed;
Multiple state 4 regions are created by capt_expand, surrounding town regions and filling in the blanks between state 5’s: they’re also used to distribute units made from capt_expand’s secondary function.
implode creates state 4 regions in state 0, 1, 2, 3 regions that are connected to at most 1 ground region.
help_iftrouble creates state 4 regions for allied AIs near and inside of the defended player’s towns.
It is important to know that state 4 regions are usually temporary: after they have been defended for the first time, they tend to either turn into state 0’s or into state 3’s: they also turn into state 6’s or 3’s immediately as they are attacked.
Defense priority 40.
state 5
Town, created around most non-supply and non-defensive structures and campaign beacons, also created with value_area script: turns into state 6 when attacked and turns back into state 5 when idle again. Might turn into state 3 and then into 6 and back into 5. Defended. Sometimes created for friendly AIs by help_iftrouble in vital town parts of the defended AI.
Defense priority 50.
NOTE ABOUT STATES 0, 3, 4, 5: Their needed strength (force) value decays over time (even if the AI player has a default_min value) if (unknown conditions) occur. Usually just happens for abandoned and outlying regions.
state 6
Actively defending. Each town has it’s town center highlighted by it being a permanent state 6 region. If the AI is sending units to a state 6 region it has no units in, it will change to state 3.
NOTE ABOUT STATES 4, 6: These states are the only ones to recognize default_min values: it tells them how much force do they need to defend at all times, though outer state 4’s are still affected by strength decay. Ground regions only request ground defenses and air regions only request air defenses from default_min.
state 7
Chase away - targets a defended region and uses its needed force value to prepare defenses in this region. If the AI is sending units to a state 7 region it has no units in, it will change to state 3, except if it was created by another state 3 region.
Defense priority for states 6, 7 is 100 or 110 if the region has a worker or a building inside.
state 8
Preparing attack. Not defended. The target region is used for eval_harass and harass_factor calculations.
state 9
Preparing attack after state 8 region was deemed unreachable - occurs in the (nearest?) region with enemy units in it. Attacks going to state 9 regions will generally act the same as ones going to state 8, but their respective attack won’t wait until attack preparation finishes, like it usually would. They also don’t stop grouping after attack_clear.
Should never occur with vanilla attack region selection code.
StarEdit commands
clear_combatdata
"Removes all units in a map location from existing and past attacking parties."disruption_web
"Orders a Protoss Corsair to cast Disruption Web in the center of the map location."enter_bunker
"Orders all eligible units in the location to enter the nearest bunker to them. If the nearest bunker is full, the unit(s) will ignore the order."enter_transport
"Orders units in the location to enter the nearest bunker or transport. If the nearest bunker or transport is full, the unit(s) will ignore the order."exit_transport
"Orders transports and bunkers in the location to unload their units."junkyard_dog
"Changes the Computer-Idle AI Action of Computer-owned units in a map location to "Move (Junk Yard Dog)". Computer units will move to a random map coordinate and attack enemy units if able."Notes:
1) If the map location is smaller than a unit's collision box, that unit will not be set to Junk Yard Dog.
make_patrol
"Orders units in a map location to patrol to the Generic Command Target."set_gencmd
"Sets the Generic Command Target to the center of a map location."move_dt
"Orders the Computer Player to move all Dark Templar (Hero) and Protoss Dark Templar to the map location."Notes:
1) Crashes if there are any Dark Templar in training.
nuke_location
"Orders a Terran Ghost to nuke the center of the map location. Requires an available ghost and armed nuclear silo."player_ally
"Makes all players in the map location an ally of the trigger owner."player_enemy
"Makes all players in the map location an enemy of the trigger owner."recall_location
"Orders a Protoss Arbiter to use recall at the center of the map location."sharedvision_off
sharedvision_off playerId"The player will lose vision of %1playerId."
sharedvision_on
sharedvision_on playerId"The player will gain vision of %1playerId."
value_area
"The Computer Player will set the region in the center of the map location to state 5. If the Computer Player doesn’t control any buildings in the region, it will only be defended once. Doesn’t do anything if the region already has enemy units inside of it."switch_rescue
"Switch the Computer Player to a Rescuable Player." Unused commands
if_towns
"Unused and no longer in game memory."harass_location
harass_location dword"Supposedly caused the Computer Player to prefer attacking the selected region. Currently (1.16.1+) unused."
scout_with
scout_with unitId"Does not exist in memory."
if_dif
if_dif comparison value block"Jumps to %3block if %2value is different than an internal value related to an unused difficulty setting, which is now always 1 for active (ones that called start_town) players, 0 for inactive, using %comparison (0 = greater than, 1 = less than)."
easy_attack
easy_attack quantity unitId"Functions the same as attack_add, but used only in conjunction with an unused difficulty setting."
AI limits
requests - 100 per AI town (each separate build, tech, player_need and upgrade use is a request)
Results of breaching: corrupts other towns, almost always results in crashes
guard units - 1000 globally (both alive and requested)
Result of breaching: guard requests no longer work, units spawned via triggers or create_unit get frozen
military units - 1000 globally (only defenseuse/attack units matter for this limit)
Result of breaching: new units that get trained get frozen
workers - 1000 globally, 30 hardcoded per AI
Result of breaching: unknown for the global limit, workers work correctly for the single player limit
town buildings - 1000 globally (also includes workers, larvae, eggs and overlords)
Result of breaching: unknown
threads - 100 globally (this includes town scripts, areatown scripts, and all multiran or otherwise existing threads)
Result of breaching: unknown, might cause crashes
towns - 100 globally (start_town scripts and threads and start_areatown scripts)
Result of breaching: unknown, might cause crashes
defenseuse_xy - 20 per defenseuse type, separate for each player
Result of breaching: units beyond the 20th will not be used for defense of a given type
attack_add - 63 without overwriting attack target, also affects all other ways of adding units to an attack
Result of breaching: if overwritten, the attack functions completely correctly
resareas - 250
Result of breaching: cannot be breached
Additional bugs/issues
- The attacks will seldom stop its attacking units midway of an attack preparation when the first target dies, especially in melee scripts
- If an upgrade/tech ID corresponds to the worker ID (i. e. ID 7 for SCV, irradiate and t_inf_weapon) of the given race in an AI town, then the upgrade/tech level can never be higher than the town’s worker limit (which is 3 with just a geyser; can be 0 if the town has no resources assigned; can be fixed using max_workers from the aiscript extender)
- If an SCV is destroyed during the construction of a building, the AI tries to repair the building instead of renewing construction, and the given town’s request log hangs up until the building is destroyed (fixed with a 1.16.1 exe edit)
- The AI will sometimes to attempt casting targeted spells while not having enough energy for them
- The AI has no checks for overkilling enemies with spells and will use multiples of them on a single target (area) if applicable and possible
- Train requests (Using train, do_morph, wait_force and possibly wait_train) used when the AI has a guard of the same type that you want to train, while the guard needs to be replenished, while the guard area is not in combat, causes the train request to be ignored and makes the AI train units as if you had defaultbuild enabled (fixed by the aiscript extender)
- Train->Morph requests (Archons, Guardians, Devourers…) can get deleted if the AI can't immediately act upon them: the AI should have a perfectly clear request log before training those units if you want them to accurately show up without any abnormalities
- Non-guard (military) High Templars the AI controls won't merge into Archons unless they are in a region with state 4, 5, 8 or 9
- Preplaced Creep Colonies can’t be morphed into anything by the AI because their primary order is Nothing instead of Computer Script
- Attacks started at 0 frames have no expiration deadline
- Zerg Eggs owned by the AI killed in the last 10 frames of hatching (visually, this makes the unit completely disappear) can cause a crash if their town is not eliminated quickly
- AI won’t build buildings near state 0 regions that were recently attacked (and “recently” means until the region state changes)
- The guard crash - steps to reproduce (as discovered by Neiv; fixed by the aiscript extender)
- A guard needs to have been killed at least twice while still being a guard
- Once the AI starts the request to replace the guard, it must be busy enough to take a few seconds before acting on it
- One unit build time later, the AI needs to have another idle production building which can start creating the second guard.
- The first guard spawns after the second guard has started production
- The first guard dies before the second guard finishes
- The second guard spawns, and stays alive long enough that its guard ai gets reused for some unrelated request
- The game crashes
Credits
This reference sheet was initially collated by Nekron and ported to wikidot by DarkenedFantasies. It was then ported to fraudsclub.com by Pr0nogo.
Accessory credits go to:
- Neiv, for creating accurate descriptions of attack commands, and helping with scripting and documenting almost all of the previously undocumented commands.
- Heinermann, for writing the original post on which this is based, and writing descriptions of multiple AI functions.
- Many others for in-game function testing.