----TABLE OF CONTENTS
    I. Introduction
   II. attack_to
  III. attack_timeout
   IV. if_attacking
    V. issue_order
   VI. idle_orders
  VII. deaths
 VIII. misc commands

----I. Introduction
This command guide is designed to allow modders to use the new aiscript commands created by Neiv. Many of these commands are staples of high-end AI in the modern era. It is my
hope that by writing this guide and shedding more light on the use cases of these new commands, more modders will pay closer heed to the designs of their AI and find more ways
to make compelling missions in SCBW. If you have any questions, feel free to contact me.
	-Pr0nogo

----II. attack_to
attack_to (X1 Y1) (X2 Y2)
"Makes the AI prepare its attack in region 1 and target region 2"

Notes:
1) Using the latest version of SCMDraft allows users to view pathfinder regions.
2) Coordinates always go to the center of the region they belong to.
3) Users can use locations with the syntax Loc.n, where n is the location ID. Location ID is zero-based, and `63` is Anywhere. Enabling the debug view in SCMDraft and deleting or
placing a location will display its accurate location ID.

Example use cases:
	Regions are taken from Rebel Yell 10 - The Hammer Falls

	attack_to (3566 1135) (3312 3535)
		The AI will prepare its attack inside the white base and target the region with the player's command center.

	attack_to (1677 1102) (3087 3312)
		The AI will prepare its attack near an empty expansion and target the region above the player's command center, where they are expected to build defenses.

	attack_to Loc.3 Loc.63
		The AI will prepare its attack in location 3 (called `Staging 1` in the editor) and targets the region in the center of the map.

----III. attack_timeout
attack_timeout timer
"Sets the max attack preparation time"

`timer` specifies the max prep time in seconds.

Example use cases:
	attack_add 6 carrier
	attack_prepare
	attack_timeout 360
	attack_do
	attack_clear
		The AI will have a higher max prep time than default, increasing the likelihood that it fulfills the attack request.

	attack_add 4 marine
	attack_prepare
	attack_timeout 30
	attack_do
	attack_clear
		The AI will have a shorter max prep time than default, forcing the AI to commit to the attack very soon. No different than using wait(720) and quick_attack().

----IV. if_attacking
if_attacking block
"Jump to the desired block if the AI is preparing an attack"

Example use cases:
	:checkAttack
	wait 25

	if_attacking checkAttack
	attack_add 3 marine
	attack_prepare
	wait 300

	quick_attack
	attack_do
	attack_clear
	wait 1440

	goto checkAttack
		The AI will prepare a small attack every 1440 frames if it's not preparing an attack elsewhere in the script. Useful for an area town that only has a barracks, for example.

	:checkAttack2
	wait 25

	if_attacking addAttack2
	goto checkAttack2

	:addAttack2
	attack_add 3 marine
	wait_finishattack
	goto checkAttack2
		If the AI is preparing an attack, it will add 3 marines to the attack force.

----V. issue_order
issue_order order count unit_id (src_x src_y ~ src_r) (tgt_x tgt_y ~ tgt_r) tgt_unit_id flags
`order` specifies the order that will be given to the unit.
`count` specifies how many units will at most be ordered. Use `9999` for all units.
`unit_id` specifies which unit type will be ordered. `229` has special meaning of "any unit".
`src_x`, `src_y` specify the point at which units to be ordered are searched, and `src_r` specifies the search radius. The search area is square shaped, like locations.
`tgt_x`, `tgt_y` specify the target point. If targeting units instead of terrain, `tgt_r` will specify the search radius for matching target units. See note 1 for more.
`tgt_unit_id` specifies the acceptable unit ID for targets, when targeting units. Again, 229 is special ID for "any unit".
`flags` specifies some extra settings. They can be combined with '|'. See note 2 for more.
	-Enemies: Target enemy units
	-Own: Target own units
	-Allied: Target allied units (neutral units are always considered allied, even if they were owned by enemy and then given to a neutral player)
	-SingleUnit: Target only a single unit, even if there are multiple matches
	-EachAtMostOnce: Target each target at most once. If there are more units in the source area than there are targets, the remaining source units will not be issued an order.

Additionally, the following unit building orders are supported, and they take the unit type to be built in `tgt_unit_id`. See note 3 for more.
	-25: Drone build
	-30: SCV build
	-31: Probe build
	-36: Place addon
	-42: Unit morph
	-43: Building morph

Notes:
1) Users can use locations with the syntax Loc.n, where n is the location ID. Location ID is zero-based, and `63` is Anywhere. Enabling the debug view in SCMDraft and deleting or
placing a location will display its accurate location ID. If using a location, `src_r` can still be used as a square radius around the location.
2) Enabling any of the first 3 flags makes the ordered units to target units instead of ground. If no valid targets can be found in the area, then the command will not do anything.
There is also a bug that may be fixed eventually where units can target themselves (which will not do anything) if the unit matches both source and target filters, and "target own
units" is enabled. Avoid doing that or be ready for unpredictable results.
3) When using any order that places buildings, such as 'SCV Build' or 'Land', the coordinates will not automatically be snapped to the building tile grid. The correct coordinates
for placement are in the middle of unit's placement box. For example, building a command center at the top-left corner of the map would use coordinates 64, 48, as the placement box
is 4x3 tiles (128x96 pixels). Locations appear to work correctly, as long as they've been snapped to the tile grid and have not moved through triggers.

Example use cases:
	issue_order BuildingMorph 4 creep_colony Loc.39 Loc.39 sunken_colony 0
		4 creep colonies at Location 39 will morph to sunken colonies if the player has enough resources.

	issue_order Land 1 command_center Loc.5 Loc.2 Any 0
		1 command center at Location 5 will land at Location 2 if there is sufficient space to land.

	issue_order MoveToInfest 2 queen Loc.9 Loc.63 command_center Enemies|SingleUnit
		2 queens at Location 9 will infest a command center at Anywhere if it is infestable.

----VI. idle_orders
idle_orders order rate max_per_target user_unit_id radius target_unit_id priority flags
"Adds an idle order to the idle order list for the player"

`order` specifies the order that will be given to the unit.
`user_unit_id` specifies the unit that will receive the order.
`target_unit_id` specifies the unit that will be targeted by the user unit. Can also be `Any`, `Group_Men`, `Group_Buildings`, or `Group_Factories`. See note 3 for more.
`rate` specifies how often the AI will (try to) send a unit to use the order. Specified in frames.
`max_per_target` specifies how many units may simultaneously target a same unit with a idle order.
`radius` is the maximum distance in pixels for which the AI will send its units from their idle position.
`priority` specifies the priority. Higher priority is more important. Does not compete with stock AI commands such as `build` and `train`.
`flags` specifies various targeting flags. They can be combined with '|'.
	-NotEnemies: Will not accept enemies as targets. Targeting enemies is enabled unless disabled with this.
	-Own: Will accept own units as targets
	-Allied: Will accept own units as targets
	-Unseen: Will accept unseen targets (i.e. uses maphacks instead of targeting only things that are visible to the player)
	-Invisible: Will accept undetected targets, and use the order on the ground near target.
	-Remove: Instead of adding an idle order, removes one that matches the current declaration completely (excluding the `Remove` flag itself). Shows a warning if unsuccessful.
	-RemoveSilentFail: Like Remove, but won't show any warnings if nothing gets removed.
	-SpellEffects(effects): Target must have all of selected spell effects:
		`ensnare`, `plague`, `lockdown`, `irradiate`, `parasite`, `blind`, `matrix`, `maelstrom`
	-WithoutSpellEffects(effects): Target may not have any of selected spell effects
	-InCombat: Will accept targets that are targeting an enemy with an attacking order.
	-Hp: Will compare hit point values for acceptable targets.
	-Shields: Will compare shield values for acceptable targets.
	-Health: Will compare the sum of hit point and shield values for acceptable targets.
	-Energy: Will compare energy values for acceptable targets.
	-Deathrattle: Will only receive the order when brought to 25% of max health (hp + shields) or 50% of health at the time the script executes the command, whichever value is smaller.
	Does not use the `count` or `rate` fields. Only executes if the unit was amidst executing a non-Deathrattle idle order. See note 5 for more.
Notes:
1) The target picking isn't perfect. It prefers the closest unit it can find, and the logic works fine when the all order users/targets are roughly in same area, but if there are
two or more separate groups of both, it may ignore one of the groups completely.
2) To disable the default AI behavior for the player, you can use DisableBuiltIn in `order` parameter (And leave everything else 0)
3) If `target_unit_id` is set to `Any`, the units just try to target anything they can even if its impossible, like trying to cast hallucination on buildings.
4) Comparisons for Hp, Shields, Health, and Energy can be `LessThan`, `GreaterThan`, `LessThanPercent`, or `GreaterThanPercent`. Comparing shields will never be true if the unit
has no shields.
5) Deathrattle piggybacks off of previously-executed idle_orders commands and does nothing by itself. Think of it as a built-in retaliatory system for idle_orders spellcasts.

Example use cases:
	idle_orders dark_swarm 64 1 defiler 1200 zergling 60 Own|Allied
		every 64 frames, 1 idle defiler will attempt to dark swarm own or allied zerglings within 1200 pixels of the idle defiler.

	idle_orders attack 64 3 infested_terran 1200 Group_Buildings 60 SpellEffects(Plague)
		every 64 frames, up to 3 idle infested terrans will attempt to attack any enemy unit afflicted with plague within 1200 pixels of the idle infested terran.

	idle_orders MoveToInfest 64 1 h_queen 2400 command_center 99 Hp(LessThanPercent 49)
		every 64 frames, 1 matriarch will attempt to infest enemy command centers that have less than 49% health within 2400 pixels of the idle matriarch.

	idle_orders PsiStorm 0 0 high_templar 5000 Group_Men, 99 Deathrattle
		any high templar executing an idle order will attempt to retaliate if brought below the hp threshold by casting psi storm on enemy men within 5000 pixels.

	idle_orders Feedback 480 2 dark_archon 1280 high_templar 70 Order(PsiStorm)
		every 480 frames, up to 2 idle dark archons will attempt to feedback hostile high templar that have been ordered to cast psi storm within 1280 pixels.

	idle_orders DisableBuiltin 0 0 0 0 0 0 0
		all standard idle (not retaliatory) spellcasts are disabled

----VII. deaths
deaths player comparison quantity unit block
"Reads or writes data from the death table, and jumps if reading a true comparison"

`player` is zero-based, e.g. a value of `0` is player 1. `13` is current player.
`comparison` is used to read or write from the death table. For reading, it can be AtLeast, AtMost, or Exactly. For writing, it can be Add, Subtract, or Set.
`quantity` specifies the number of death data to read or write.
`unit` specifies which unit's death data to interact with.
`block` specifies the block in the aiscript to jump to if the comparison is true. Not used if writing data.

Example use cases:
	deaths 0 Exactly 1 probe phaseTwo
		if player 1 has suffered exactly 1 death of probe, jump to block phaseTwo

	deaths 13 Set 119 arbiter phaseOne
		set current player's deaths of arbiter to 119

----VIII. misc commands
unstart_campaign
"Sets the script class to melee regardless of game type"

under_attack value
"Determines how aggressively the AI prioritizes defending"

`value` has three valid parameters.
	-0: AI will never take units from attack forces to defend.
	-1: AI will take units from attack forces to defend. Default behavior.
	-2: AI will almost never attack and keep all of its active units available for defense.

max_workers value
"Sets the max number of workers a town can request"

`value` can go up to 255. Does not request workers, only allows/disallows them. Most often used with a value of `0` to stop area towns from requesting workers. A value of `0` will not prevent
an AI from building gas structures on nearby geysers.

aicontrol value
"Sets AI control behavior"

`value` can be one of the following:
	-dont_wait_request_resources: the AI will not wait for resources to fulfill a request, recycling them as it would any other request.