AIScript Commands

Help - Resources - AI Scripting - Grafting - Plugins - Modding Projects
Heinermann
Posts: 362
Joined: Thu Apr 26, 2007 12:42 am

AIScript Commands

Postby Heinermann » Sun Dec 30, 2012 8:12 am

Note: This is a continuation of the following topic: http://broodwarai.com/forums/viewtopic.php?f=5&t=11

Updated known commands for Broodwar AIScript

Stuff in blue denotes information that has been updated.
Stuff in green indicates stuff that will be used in the BWScript Emulator AI module for BWAPI, and that AI script writers should keep these in mind when writing scripts.

Header commands

farms_notiming
Build necessary farms only when it hits the maximum supply available.

farms_timing
Build necessary farms with a correct timing, so nothing is paused by a maximum supply limit hit.

start_areatown
Starts the AI Script for area town management. Should only be used in campaign scripts, as it uses the trigger location as its bounds (or area).

start_campaign
Starts the AI Script for Campaign. Note: This command may have many subtle (but significant in number) changes to AI behaviour which may be desirable in some cases, but not in others.

start_town
Starts the AI Script for town management.

transports_off
Computer will not manage/build transports on its own.


check_transports
Informs computer to build transports on its own. If start_campaign was called, then 2 transports will be built, otherwise 5 will be built. The first transport is built at priority 80 and subsequent transports are built at priority 50. Protoss also trains up to 2 observers at priority 80. Used with header transports_off.



Build/Attack/Defense order commands

attack_add (byte) (military)
Add %1(byte) %2(military) to the current attacking party. %1 (byte) can be at most 62, otherwise the command is ignored.
In BWScriptEmulator this limitation will be removed.

attack_clear
Clear the attack data.

attack_do
Attack the enemy with the current attacking party.

attack_prepare
Prepare the attack.

build (byte) (building) (byte)
Build %2(building) until it commands %1(byte) of them, at priority %3(byte). The maximum value of %1(byte) is 30.
In BWScriptEmulator this limitation will be removed.

defensebuild_aa (byte) (military)
Build %1(byte) %2(military) to defend against enemy attacking air units.

defensebuild_ag (byte) (military)
Build %1(byte) %2(military) to defend against enemy attacking air units.

defensebuild_ga (byte) (military)
Build %1(byte) %2(military) to defend against enemy attacking ground units.

defensebuild_gg (byte) (military)
Build %1(byte) %2(military) to defend against enemy attacking ground units.

defenseclear_aa
Clear defense against enemy attacking air units.

defenseclear_ag
Clear defense against enemy attacking air units.

defenseclear_ga
Clear defense against enemy attacking ground units.

defenseclear_gg
Clear defense against enemy attacking ground units.

defenseuse_aa (byte) (military)
Use %1(byte) %2(military) to defend against enemy attacking air units.

defenseuse_ag (byte) (military)
Use %1(byte) %2(military) to defend against enemy attacking air units.

defenseuse_ga (byte) (military)
Use %1(byte) %2(military) to defend against enemy attacking ground units.

defenseuse_gg (byte) (military)
Use %1(byte) %2(military) to defend against enemy attacking ground units.

do_morph (byte) (military)
Morph %2(military) until it commands %1(byte) of them.


get_oldpeons (byte)
This command takes X number of workers from the main to move to the expansion. Should be used after the expansion is completed.


guard_all
Uses all available units to guard the town.


guard_resources (military)
Send units of type %1(military) to guard as many unacquired base locations as possible(1 per spot).

place_guard (unit) (byte)
Place one %1(unit) to guard town at strategic location %2.
Location:
0 = town center
1 = mineral line
2 = geyser/refinery


player_need (byte) (building)
If the player does not own %1(byte) number of %2(building), then build it at priority 80, otherwise ignore this opcode.
This command is different from build because it is global and not local to the town.


prep_down (byte) (byte) (military)
Add all %3(military) to the current attacking party except for %1(byte) of them, however it must send a minimum of %2(byte) of them.


tech (tech) (byte)
Research technology %1(technology), at priority %2(byte).

train (byte) (military)
Train %2(military) until it commands %1(byte) of them.

upgrade (byte) (upgrade) (byte)
Research upgrade %2(upgrade) up to level %1(byte), at priority %3(byte). The maximum supported upgrade level is 31.
In BWScriptEmulator this limitation will be removed.

wait (word)
Wait for %1(word) logical game frames. A game frame is 42 milliseconds on fastest game speed.

wait_finishattack
Wait until attacking party has finished to attack.

wait_force (byte) (unit)
Wait until computer commands %1(byte) %2(unit).


wait_build (byte) (building)
Wait until computer commands %1(byte) %2(building).

wait_buildstart (byte) (building)
Wait until construction of %1(byte) %2(building) has started.

wait_train (byte) (military)
Wait until computer commands %1(byte) %2(military).


Flow control commands

call (block)
Call %1(block) as a sub-routine. Only one call can be made in the game at all times from any computer player running a script.
If an AI owned by player 1 makes a call, then player 2 makes a call, will override player 1's call and controls the flow of the return statement.
Be sure that there is no wait command or blocking command inside the call to have it function correctly.
In BWScript Emulator, this command will be fixed and function as it was intended.

enemyowns_jump (unit) (block)
If enemy has a %1(unit), jump to %2(block).

enemyresources_jump (word) (word) (block)
If enemy has at least %1(word) minerals and %2(word) gas then jump in %3(block).

goto (block)
Jump to %1(block).

groundmap_jump (block)
If it is a ground map(in other words, if the enemy is reachable without transports), jump to %1(block). This will jump if any enemy structure is reachable at any given point.

if_owned (unit) (block)
If the player owns a %1(unit) (includes incomplete) then jump to %2(block).


killable
Allows the current thread to be killed by another one.

kill_thread
Kills all threads that have the killable attribute (including threads owned by other players). This should not be used in a script.

notowns_jump (unit) (block)
If computer doesn't have a %1(unit), jump to %2(block).

race_jump (block) (block) (block)
According to the enemy race, jump in %1(block) if enemy is Terran, %2(block) if Zerg or %3(block) if Protoss.

random_jump (byte) (block)
There is %1(byte) chances out of 256 to jump to %2(block).

resources_jump (word) (word) (block)
If computer has at least %1(word) minerals and %2(word) gas then jump in %3(block).

return
Return to the flow point of the call command.

rush (byte) (block)
will jump to %2(block) if %1(byte) conditions exist.

Rush scoring system:

Code: Select all

// Protoss Air Score
result = ProtossDragoons + ProtossScouts

// Zerg Ground Score
result = ZergHydralisks + ZergSunkenColonies * 2

// Zerg Air Score
result = ZergHydralisks + ZergMutalisks + ZergSporeColonies * 2

// Terran Infantry Score
if (bunkers * 4 <= marines)
        result = marines + bunkers * 4;
else
        result = 2 * marines;


Rush conditions:
TERRAN
0: Commands a Barracks
1: Terran Infantry Score > 16
2: Terran Infantry Score > 24
3: Terran Infantry Score > 5
4: Terran Infantry Score > 16
5: Terran Infantry Score > 6
6: Terran Infantry Score > 12
7: Commands a Siege Tank
8: Terran Infantry Score > 5
9: Terran Infantry Score > 9
10: Terran Infantry Score > 4
11: Terran Infantry Score > 10
12: Terran Infantry Score > 16
13: Terran Infantry Score > 24

ZERG
0: Commands a Spawning Pool
1: Zerg Ground Score > 10
2: Zerg Air Score > 10
3: Zerg Ground Score > 2, or commands a Hydralisk Den
4: Zerg Ground Score > 10
5: Zerg Ground Score > 6
6: Zerg Sunken Colonies > 1
7: Commands a Queen
8: Zerg Ground Score > 2
9: Zerg Ground Score > 4
10: Zerg Ground Score > 4
11: Zerg Ground Score > 10
12: Zerg Air Score > 5
13: Zerg Air Score > 10

PROTOSS
0: Commands a Gateway
1: Protoss Zealots > 6
2: Not used
3: Protoss Zealots > 1
4: Protoss Zealots > 8
5: Protoss Zealots > 3
6: Protoss Dragoons > 1
7: Protoss Zealots > 6
8: Protoss Zealots > 1
9: Protoss Zealots > 5
10: Protoss Zealots > 2
11: Protoss Zealots > 5
12: Protoss Air Score > 2
13: Protoss Air Score > 7
---

stop
Stop script code execution. Often used to close script blocks called simultaneously.

time_jump (byte) (block)
Jumps to %2(block) if %1(byte) normal game minutes have passed in the game.

[color=blue]try_townpoint (byte) (block)
Jump to %2(block) when the AI owns %1 number of expansions.



Multiple threads commands

expand (byte) (block)
Run code at %2(block) for expansion number %1(byte)

multirun (block)
Run simultaneously code at %1(block).


Miscellaneous commands

create_nuke
Create a nuke. Should only be used in campaign scripts.
The BWScript Emulator cannot emulate this opcode. It will be ignored.

create_unit (unit) (word) (word)
Create %1(unit) at map position (x,y) where x = %2(word) and y = %3(word). Should only be used in campaign scripts.
The BWScript Emulator cannot emulate this opcode. It will be ignored.

creep (flag)
Builds structures(towers?) far if the flag is set to 4, or near if the flag is anything else.
The creep command is used for expanding the zerg creep.


debug (block) (string)
Show debug string %2(string) and continue in %1(block). (unsupported by scAIEditIII)

The BWScript Emulator will send the string as a text message to all players.

define_max (byte) (unit)
Define maximum number of %2(unit) to %1(byte).

fatal_error
Crashes starcraft with a fatal error and the message "Illegal AI script executed.".

In BWScript Emulator, this will simply send the text message "Illegal AI script executed".

give_money
Gives 2000 ore if ore is currently below 500 and gives 2000 gas if gas is currently below 500. This is executed immediately, the AI does not wait until it falls below 500 resources. This will be skipped entirely of no resource is below 500.
In BWScript Emulator, this will use the cheat codes "whats mine is mine" and "breathe deep" four times in a row under the same conditions. This will not work in multiplayer.

nuke_pos (word) (word)
Launch a nuke at map position (x,y) where x = %1(word) and y = %2(word). Should only be used in campaign scripts.

nuke_rate (byte)
Builds and uses nukes every %1(byte) minutes.


send_suicide (byte)
Send all units to suicide mission. %1(byte) determines which type: 0 = Strategic suicide; 1 = Random suicide.
* 1 = includes workers too.

set_randomseed (dword)
Set random seed to %1(dword). Note: This affects other scripts and should not be used.

StarEdit commands

clear_combatdata
Clears all AI attack data for all units in the location.

disruption_web
Orders a Protoss Corsair to cast Disruption Web in the location.

enter_bunker
Orders units in the location to enter the closest bunker.

enter_transport
Orders units in the location to enter the closest transport.

exit_transport
Orders transports in the location to unload their units.

harass_location
AI Harass at selected location. (Needs definition)

junkyard_dog
Orders the unit to run on "Junk Yard Dog" (similar to critter).

make_patrol
Orders the units to patroll to the Generic Command Target.

move_dt
Orders the computer to move all Dark Templars to the specified region.

nuke_location
Orders a computer player to nuke the selected location.

player_ally
Makes all players in a specified location an ally of the trigger owner.

player_enemy
Makes all players in a specified location an enemy of the trigger owner.

recall_location
Orders an Arbiter to use recall at this location.

sharedvision_off (player)
Orders the specified player to unvision the trigger owner.
The BWScript Emulator cannot emulate this opcode, however it can emulate the inverse, and the current player will unvision the specified player.

sharedvision_on (player)
Orders the specified player to give vision to the trigger owner.
The BWScript Emulator cannot emulate this opcode, however it can emulate the inverse, and the current player will share vision with the specified player.

value_area
Causes the computer to value a specified area higher than any other area. It may guard the area with units.



Unused commands

if_towns
Does not exist in memory.


scout_with (military)
This command has no action associated with it and therefore cannot be used.

In the BWScript Emulator, this command will correctly send the given military to scout the enemy.


List of unknown or unclear commands
Unknown purpose commands
Note: These are the most interesting commands to make research on. With the accurate opcode name list, they're now easier to decipher, but many still don't act as expected, or are still too obscure.

allies_watch (byte) (block)
Expands at hardcoded expansion number %1 (byte) using %2 (block). Note: If %1 is < 8 then it is a player's start location, otherwise it is a map's base location. Does nothing if the expansion is occupied. The maximum value for %1 (byte) is 250.

capt_expand
Causes the AI to expand using a default expansion block. Takes no parameter.
The actual expansion block is unknown and needs research.


default_min (byte)
Defines how much standing army (from defenseuse commands) will be placed at expansions. The greater the value, more units will be sent. If (byte) = 0, then it will send units only if the expansion is under attack

defaultbuild_off
Turns off default_build. Note: "default build" is on by default.

fake_nuke
Resets the AI nuke timer. Behaviour is unknown.

max_force (word)
Takes %1(word) as parameter. Unknown.

panic (block)
If AI has not expanded yet and total unmined minerals in the mineral line are less than 7500, then it will expand using (block). If the AI 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 Refineries that are not depleted.

region_size (byte) (block)
Jump to block %2 if the computer's region tile count is below %1. Untested.


set_attacks (byte)
The use of this command is unknown. Takes %1(byte) as parameter.

target_expansion
The use of this command is unknown. Takes no parameter.
appeared in vanilla SC scripts. Looks like was a general "attack" command not necessarily expansions.
Update: This only sets a flag. The actual effects from that flag are unknown.
Update2: Only used with set_attacks, does nothing if the start_campaign opcode was executed.


build_bunkers
Builds up to 3 bunkers around the base (Terran only). Takes no parameters.

build_turrets
Builds up to 6 missile turrets around the base (Terran only). Takes no parameters.

default_build
If the AI has more than 600 minerals and 300 gas, it will continuously train race specific units until it reaches the define_max value.
Terran: marine, ghost, siege tank, goliath, wraith, battlecruiser.
Zerg: hydralisk, mutalisk.
Protoss: zealot, dragoon, reaver, scout, carrier.

Note: "default build" is on by default. To turn it off, use defaultbuild_off


easy_attack (byte) (unit)
The definition of this command is unknown. Supposedly attacks the enemy with %1 units of type %2 without having to do attack_add, attack_prepare, and attack_do.

eval_harass (block)
Jumps to a block when an unknown condition related to the town and attack manager are met. Also uses enemy unit ground/air strength values to compare with something.

harass_factor (word)
Something related to unit strengths in a region.

if_dif (byte) (byte) (block)
Jumps to block %3 if value %2 is different than an unknown internal value (related to attacking?), using modifier %1(0 = greater than, 1 = less than).

implode
The definition of this command is unknown. Takes no parameter.

quick_attack
Supposedly perform an attack quickly without preparing it. (?) Takes no parameter.

wait_bunkers
Supposedly waits for the command build_bunkers to finish. Takes no parameters.

wait_secure
The definition of this command is unknown. Takes no parameters.

wait_turrets
Supposedly waits for the command build_turrets to finish. Takes no parameters.

wait_upgrades
Waits for all upgrades and research to finish. Takes no parameter.
Last edited by Google Adsense [Bot] on Sun Dec 30, 2012 6:40 pm, edited 1 time in total.
Heinermann
Posts: 362
Joined: Thu Apr 26, 2007 12:42 am

Re: AIScript Commands

Postby Heinermann » Sun Dec 30, 2012 8:12 am

List of commands that should be used in AIScripts

Header commands
  • farms_notiming, farms_timing
  • start_campaign
  • start_town
  • transports_off, check_transports

Build/Attack/Defense order commands
  • attack_add
  • attack_clear
  • attack_do
  • attack_prepare
  • build
  • defensebuild_aa, defensebuild_ag, defensebuild_ga, defensebuild_gg
  • defenseclear_aa, defenseclear_ag, defenseclear_ga, defenseclear_gg
  • defenseuse_aa, defenseuse_ag, defenseuse_ga, defenseuse_gg
  • do_morph
  • get_oldpeons
  • guard_all
  • guard_resources
  • place_guard
  • player_need
  • prep_down
  • tech
  • train
  • upgrade
  • wait
  • wait_finishattack
  • wait_force
  • wait_build
  • wait_buildstart
  • wait_train

Flow control commands
  • call, return (use with caution!, read info)
  • enemyowns_jump
  • enemyresources_jump
  • goto
  • groundmap_jump
  • if_owned
  • notowns_jump
  • race_jump
  • random_jump
  • resources_jump
  • rush
  • time_jump
  • try_townpoint

Multiple threads commands
  • expand
  • multirun

Miscellaneous commands
  • creep
  • debug
  • define_max
  • give_money
  • nuke_rate
  • send_suicide

List of unknown or unclear commands
  • capt_expand
  • default_min
  • defaultbuild_off, default_build
  • fake_nuke
  • max_force
  • panic
  • region_size
  • set_attacks
  • target_expansion
  • build_bunkers, wait_bunkers
  • build_turrets, wait_turrets
  • easy_attack
  • eval_harass
  • harass_factor
  • if_dif
  • implode
  • quick_attack
  • wait_secure
  • wait_upgrades

Commands not on this list should generally NOT be used in an AI script.
Heinermann
Posts: 362
Joined: Thu Apr 26, 2007 12:42 am

Re: AIScript Commands

Postby Heinermann » Sun Dec 30, 2012 8:13 am

List of commands Implemented in BWScriptEmulator
*Fully implemented (includes acceptable behavior for a script)
*Partially implemented
*Unimplemented


goto
notowns_jump
wait

start_town
start_areatown
expand
build
upgrade
tech
wait_build
wait_buildstart

attack_clear
attack_add

attack_prepare
attack_do

wait_secure
capt_expand
build_bunkers
wait_bunkers

defensebuild_gg
defensebuild_ag
defensebuild_ga
defensebuild_aa
defenseuse_gg
defenseuse_ag
defenseuse_ga
defenseuse_aa
defenseclear_gg
defenseclear_ag
defenseclear_ga
defenseclear_aa

send_suicide
player_enemy
player_ally

default_min
defaultbuild_off

stop
switch_rescue
(Allies all players)
move_dt
debug
fatal_error
(does not crash)
enter_bunker
value_area
transports_off
check_transports
nuke_rate
max_force

clear_combatdata
random_jump
time_jump

farms_notiming
farms_timing

build_turrets
wait_turrets

default_build
harass_factor
start_campaign
race_jump

region_size
get_oldpeons

groundmap_jump
place_guard
wait_force
guard_resources
call (unlimited calls)
return (unlimited calls)
eval_harass
creep
panic

player_need
do_morph
wait_upgrades

multirun
rush
scout_with (original behaviour only)
define_max
train
target_expansion

wait_train
set_attacks
set_gencmd
make_patrol
give_money
(Uses cheat codes)
prep_down
resources_jump
enter_transport
exit_transport
sharedvision_on
(reverse vision)
sharedvision_off (reverse vision)
nuke_location
harass_location (original behaviour only)
implode
guard_all

enemyowns_jump
enemyresources_jump
if_dif

easy_attack
kill_thread
killable

wait_finishattack
quick_attack

junkyard_dog
fake_nuke
disruption_web
recall_location
set_randomseed
if_owned
create_nuke
(does nothing)
create_unit (does nothing)
nuke_pos
help_iftrouble
allies_watch
try_townpoint
Heinermann
Posts: 362
Joined: Thu Apr 26, 2007 12:42 am

Re: AIScript Commands

Postby Heinermann » Sat Jan 05, 2013 9:37 am

Things to know

  • A script shouldn't only use groundmap_jump in the beginning of the script. Since groundmap_jump is dynamic, you can always check if the enemy is on a different island, even if they may have started on the same land. Additionally, it is per-thread. If an expansion is made on an island, you can have that particular island expansion behave differently than the others.
  • You can call start_campaign any time. You can call start_campaign to change the behaviour of the AI at any time. Just remember that you can't undo this process.
User avatar
Taranok
Posts: 256
Joined: Tue Sep 07, 2010 9:41 pm

Re: AIScript Commands

Postby Taranok » Mon Jan 28, 2013 8:28 am

hmmm am i supposed to post here with questions?

anyway clearly capt_expand does other strange things, like increase spider mine placements area, and widen patrol area of observers and overlords. and it doesn't expand at all? Also I noticed that it didn't really do anything unless I put it in an expansion script.
super1
Posts: 6
Joined: Sun Jan 27, 2013 11:55 pm

Re: AIScript Commands

Postby super1 » Mon Jan 28, 2013 2:47 pm

The capt_expand command is explained in more detail in the old thread - see page 5. Have in mind that the command is stackable with itself and overuse may lead to some suicidal overlords/observers.
capt_expand is also used to enable the "defenseuse_ga" and "defensebuild_ga" commands (see below).

defensebuild_aa and defenseuse_aa are specifically for enemy air units attacking the AI's base from normally unreachable (by ground units) terrain - over water, space, ridges, cliffs, base walls, etc.

The defensebuild_ga and defenseuse_ga are a bit...weird. I got them to work only when capt_expand is used. They trigger off:
1. Enemy ground units outside the AI's base attacking an air unit that is passing over unreachable terrain (see above) on it's way into the base.
2. Enemy ground units inside the AI's base attacking an air unit that is passing over unreachable terrain (see above) on it's way out of the base.

If Bunkers and Missile Turrets are build using only build_bunkers and build_turrets, they will not be rebuilt (if destroyed).

Each time a Bunker or a Missile Turret is build (or rebuild), a low priority place_guard command is run at the location of the structure, as follows:
- Missile turrets have a Ghost guard spot.
- Bunkers have a Ghost and a Siege Tank guard spot.
Since these are both very low priority there is a chance of them being ignored/delayed if the AI is busy training other units.

nuke_rate (byte) determines the time in minutes between ordering a single ghost to use Nuclear Strike, provided there are a Ghost and a Nuke available.
The AI may have more than 10 Nukes, but will still order Nuclear Strikes one at a time. Since the timer resets when the Ghost is ordered, and not when the Nuke actually launches, it is possible, with low timer to have multiple Nuclear Strikes.
Default value is "0", and fake_nuke resets the timer whenever it is entered in the script.
The Nuke is aborted if the ghost is disabled in any way during his way (not yet painting the target) - if killed,
under stasis field/maelstrom... or if the ghost must board a transport to reach the destination (Note that if a target is available when landing it may still proceed with the Nuke).

create_nuke requires a Nuclear Silo owned by the AI, or it is ignored.

There is a slight mistake in try_townpoint 's description - it will jump to %2(block) if the AI does not yet own %1 number of expansions.

It is also nice to know that wait_force orders units to be trained, and then waits for them to finish training (saw that somewhere in the forum).

And lastly (if anyone at all cares), move_dt orders all Dark Templar(Hero) to attack-move to the specified region.
User avatar
Taranok
Posts: 256
Joined: Tue Sep 07, 2010 9:41 pm

Re: AIScript Commands

Postby Taranok » Sat Feb 02, 2013 1:37 am

"It is also nice to know that wait_force orders units to be trained, and then waits for them to finish training (saw that somewhere in the forum)."
so wait_force means you don't have to use the train command?

Is it possible to find out some of the commands that might be related to unit strengths? like max_force, eval_harass, harass_factor
super1
Posts: 6
Joined: Sun Jan 27, 2013 11:55 pm

Re: AIScript Commands

Postby super1 » Thu Feb 07, 2013 8:57 pm

guard_all forces the AI to defend all defensive structures and units around the map. In Campaign scripts, where pre-placed units and building are common, if said units (or buildings) are outside the perimeter of a base
and are attacked, they will be ignored (the AI will not send units to defend them) . By using guard_all all these units will be defended if attacked. The command identifies the locations which must be defended at the moment it is run in the script. Units or structures build after that do not count. Each location (unit or structure) that must be defended is considered as potential overlord/observer patrol point and/or spider mine placement spot.

Return to “StarCraft Modding”

Who is online

Users browsing this forum: No registered users and 1 guest