---

Scenario Setup

The following documentation explains how to use the many new features of Cosmonarchy to design custom scenarios.

Creating scenarios for Cosmonarchy requires a custom SCMDraft 2 editor profile. For first-time users of custom editor profiles, refer to the mapping starter guide.

Please note that placing extended units requires setting the unit's ID manually in unit properties. You can refer to this document for unit IDs.

Veeq7 has also provided a hex-edited SCMDraft 2 executable that replaces unit properties with the new AI-related flags discussed later in this documentation.

---

General Utilities

Mineral Fields in Cosmonarchy deplete after being mined out, reducing their income per harvest. While two workers are assigned to a single node, the expected depletion rate of Mineral Fields is 100 minerals per minute. This means that a value of 1,500 minerals depletes after approximately 15 minutes of play. This default quantity can be adjusted depending on what you feel is an appropriate depletion time.

---

In upgrade settings, modifying the Mining Efficiency upgrade in the Other category will have the following effects:

• A value of 0 has no effect. AI will override this with their default multipliers!
• A range between 1 and 7 provides increasingly higher multipliers.
• 1 - 125% (default AI multiplier)
• 2 - 133%
• 3 - 150%
• 4-7 - 25% increase from previous value, for a max of 250%
• A value of 99 disables the multiplier entirely, even for AI players.

---

At the start of a map, on a per-player basis,

• Add 1 Vespene Geyser death to reveal all resources.
• Add 2 Vespene Geyser deaths to ping all start locations.
• Add 4 Vespene Geyser deaths to toggle the player's color randomization.
• If "Randomize start locations" is set in the player's force, player color randomization defaults to on. Adding 4 geyser deaths counteracts this, allowing randomized start locations and fixed colors simultaneously.
• Add 8 Vespene Geyser deaths to disable the "quasi-fog" partial terrain reveal, making your fog of war identical to vanilla conditions.

These deaths are binary flags, so adding the same death quantities multiple times or setting deaths to unlisted values may yield unexpected results.

---

DarkenedFantasies has achieved player-colored font tags, useful when player color changes mid-game or for cases where you have transmissions and may change the player's color later in development.

The new color tags use the format <1A><##>, where ## is the player number.
As an example, using the color of player 1 would require the color tag <1A><01> before the text.

---

Establishing Shots

Thanks to X405, developers can now add establishing shots directly to a map using an mpq editor!


Prepare a text file called "est.txt". Once filled in with the intended commands, open your desired map in your mpq editor of choice and import the text file with the import prefix "rez\", for a final result of "rez\est.txt". Click here for an example est.txt.

Images and font colors can be paths within Starcraft's original mpqs, or files imported directly to the map. In the above example, the latter is used, with custom files being imported with an "est\" prefix.

A list of establishing shot commands is forthcoming.

Documentation on using a custom Photoshop script from DarkenedFantasies to properly index a new establishing shot is forthcoming.

---

AI Configuration

Initial UMS setup:

• In the location layer, create a location that covers the AI's start location.
• Alternatively, you can refer to this example trigger that uses a single location to initialize all players based on their race.
• Using the trigger action 'Run AI script at location',
• Run [race] expansion custom level in a location placed over the starting town.
• Set starting resources as desired. AI assumes 100 minerals and 0 gas, but will progress quicker if given lots of resources at runtime.
• For optional AI support, leave the controller type as 'human' (in multiplayer mode, game hosts can set the player type to computer, even in Use Map Settings).

AI customization:

• For best results, the following settings should be configured at or before script runtime!
• Set disruption field deaths for core personalities and dark swarm deaths for early-game build orders.
• To establish preferences for army compositions in the early-game, set deaths of specific units above 0.
• To enable debug messages for showing AI personalities and build orders, set the computer player's start location deaths above 0.
• To check if a player slot is running AI, check for exactly 1 scanner sweep death. Higher values of scanner sweep deaths are checked for campaign configurations, and should not be used by the average developer.

Troubleshooting:

• Make sure your AI has the correct race set in map settings!
• For "random" AI, set the race to 'user select'.
• Results are not guaranteed; the AI have only been verified with melee starting conditions, but should adapt to being given more initial resources.
• For more involved map-specific configuration, see AI layouts.
• If you find a bug or run into trouble, feel free to reach out on discord!

---

---

---

---

LAYOUTS:

• Thanks to the work of Veeq7, it is now possible to define an AI's structure layouts, guard layouts, and request flow using preplaced units!
• Placing a unit will create a layout at that position for the unit's owner. By default, layouts are also requested.
• Request priority is based on the unit HP % (0-255).
• The number of times an AI replenishes a guard request is based on the unit energy % (0-255). A value of 100 will always replenish.
• Layouts are tied to the nearest resource area. If the AI does not yet own that resource area, requests for the attached layouts will not be issued until they claim it.
• Layout positions are currently not supported for:
• Choosing which structure to morph (e.g. precisely picking Cagrant Cesiants to turn into Surkith Cesiants).
• Choosing which structure to build an addon (e.g. precisely picking Fulcrums to build Palladiums).

Layout modifiers and notes:

• Use Veeq7's hex-edited SCMDraft 2 executable to see what each unit property does with this new system.
• Cloaked layouts are removed at the beginning of each game and do not spawn initial creep.
• Cloaked layouts owned by player 12 will apply for all players.
• Hallucinated structure layouts will not be requested, but their positions will still be logged and used when the AI receives corresponding requests.
• Hallucinating has no effect on unit layouts.
• Invincible layouts will be assigned to the AI's main town instead of the nearest resource area.
• Invincibility is toggled at runtime.
• If you want to make a unit invincible, you must now use a trigger to toggle invincibility after 1 ms.
• Requests are processed only if they could actually be satisfied (e.g. tech requirements are active).
• If two structures with equivalent IDs (such as Hachirosk and Caphrolosk) occupy the same space, only the highest-tier layout will be processed.
• Requesting a morphed structure (e.g. Surkith Cesiant) will also request the ancestor (e.g. Cagrant Cesiant) at the same priority.
• Placing a Town Center Marker (under Neutral -> Special) will add positions for Ministry, Nexus, and Hachirosk, but will not request them.

Disabling default build orders

• You can disable default AI build orders by setting a player's dark swarm deaths to a value of 99.
• For expansions, if there is more than one layout attached to the resource area, the default expansion build order will also be ignored.
• This allows you to place town center layouts without needing to place units and structures for every expansion.
• While default build orders are disabled,
• Setting mineral field (type 2) deaths will set a custom delay, in seconds, for the AI's first expansion.
• Setting mineral field (type 3) deaths will set a custom delay, in seconds, for the AI's first attack wave.
• Values of 0 will use preset values based on the AI's build order type and starting resources.
• Under no circumstances will AI take longer than 300 seconds (5 minutes) to start all of the above actions.

---

Acknowledgments:

• Modern AI work would not be possible without the contributions of Neiv, iquare, and Veeq7. Special thanks to them all!
• An additional special thanks goes out to Keyan and Connor5620, who have tested and contributed to several of the AI's build orders.

---

Trigger Comments

Triggers in Cosmonarchy have been extended using a trigger comment interpreter. Comments can now embed various commands, allowing mapmakers to call new functionality via conventional triggers with all the features they provide, without modifying SCMDraft 2.

To use trigger comments, write the respective keywords in a comment with all the arguments they require. These commands will execute according to the trigger's owners, and only after all trigger conditions are satisfied. A comment can have both commands and plaintext. Refer to examples within existing maps where necessary.

There is no automatic error checking for these extended triggers. Supplying an incorrect number of arguments will likely result in issues, such as other trigger comments not running or having arguments with unexpected values.

---

When a command has an area parameter, it can be (x y width height) for precise map coordinates, a location ID, or a location name.
width and height require operators, which can be + for positive, - for negative, and ~ for both directions.
Location IDs start from 0, but SCMDraft 2 doesn't tell you the precise location ID anywhere other than the output console, which you may not have visible.

• e.g. (4000 5024 ~128 ~128) - a 128x128 pixel box at x coordinate 4000 and y coordinate 5024.
• e.g. 63 - the "anywhere" location, which covers the entire map.
• e.g. 3 or "Main base", a location with a matching ID or name.

---

When a command has a pos or position parameter, it's the same as area, except there is no width and height. If supplied with a location, the center of that location will be used.

• e.g. (4000 5024) - the exact coordinates.

---

When a command has a bool parameter, it can be formatted as true or false. A value of 0 will be false, and any other value will be true.

---

When a command has a time parameter, it can be formatted in hours, minutes, seconds, milliseconds, and ticks. These can also be combined.

• e.g. 3s - 3 seconds.
• e.g. 3h3m3s - 3 hours, 3 minutes, and 3 seconds.

---

When a command has a min_visibility parameter, it can be one of the following:

• visible accepts the area if it is currently revealed to the player.
• explored accepts the area if it is currently revealed to the player, or has been previously revealed to the player.
• unexplored accepts the area regardless of vision status.

---

When a command has a quota or time_quota parameter, it can be compared using the following operators:

Operators and values can be formatted with or without spaces.

• e.g. == 3 or ==3 - is equal to 3 seconds
• e.g. < 3m - less than 3 minutes

---

When a command has a player parameter, it can be one of the following:

If the parameter is plural, as in players, it can have multiple elements combined.

• e.g. 1&2&3 - valid for players 1, 2, and 3
• e.g. 1&14&!20 - not valid for force 3; valid for player 1 and the trigger owner's allies

---

When a command has a unit_id parameter, it can be unit names (not case-sensitive, race not required), and the following:

If the parameter is plural, as in unit_ids, it can have multiple elements combined.

• e.g. hydralisk&bactalisk - valid for Zerg Hydralisk and Zerg Bactalisk
• e.g. zethrokor|terran&men - valid for Zerg Zethrokor or any Terran non-building

---

When a command has an animation_type parameter, it can be one of the following:

---

When a command has a filepath parameter, it must be an explicit filepath to a sound imported into an mpq archive.

• Filepaths can be user-defined if they are imported using an mpq tool as opposed to a map editor.
• Paths to files embedded within game mpqs are also accepted.
• File extensions are required. Only backlashes - \ - are supported.
• e.g. staredit\wav\zzz_devGUN-02.wav

---

Gameplay Commands

spawn %count %unit_id %player %spawn_type %delay %stagger %source_pos %move_pos

• Spawns %count %unit_ids for %player at %source_pos.
• %spawn_type can be:
• None - the unit pops into existence with no fanfare
• Augur - a cosmic explosion welcomes the unit
• AugurDamage - same as above, but with a defensive missile to punish spawn-campers
• Zerg - the unit arrives in a bloody mess, with rubble of the drop-pod to boot
• If %delay is above 0, the spawn will wait to start until after %delay time has elapsed.
• If %stagger is above 0 and %count is above 1, each subsequent spawn will wait until %stagger time has elapsed.
• %source_pos and %move_pos can be (x y) coordinates, location IDs, or location names.
• If %move_pos is specified, units are given an attack attack-move order targeting %move_pos.
• e.g. spawn 3 maverick 13 none 0 3s "spawn here" "move here"
• Spawn 3 Mavericks at the matching spawn location for current player with no effects and a 3 second delay between each spawn. Once spawned, order the Mavericks to attack-move towards the matching move location.

clear_creep %area

• Clears all creep at %area.
• %area can be (x y width height), a location id, or a location name.
• e.g. clear_creep 8 or clear_creep "Remove Creep Here" or clear_creep (4000 5024 ~128 ~128)

move_unit %area_init %players %unit_ids %area_dest %count %effect

• Instantly teleport %count %unit_ids in %area_init owned by %players to %area_dest
• If %effect is specified and not zero, the unit will have a small teleportation overlay appear on its initial and destination positions.
• e.g. move_unit "entrance 1" 1 * "exit 1" 1 true
• Teleport 1 unit (regardless of unit id) owned by player 1 from the first location to the second location, and use the overlay effect.

give_unit %area %source_players %unit_ids %count %dest_player

• Gives %count %unit_ids owned by %source_players in %area to %dest_player.
• e.g. give_unit "TyrantHall" * mason 3 1
• Give up to 3 Masons owned by any player at the specified location to player 1.

kill %area %player %unit_id %count %remove

• Kills %count %unit_ids owned by %player in %area.
• If %remove is specified and not zero, the unit will be removed silently and without creating a corpse.
• e.g. kill "No Fly Zone" 1|2 * 1 true
• Silently kill 1 unit of any ID owned by players 1 or 2 within the location.

issue_order %source_area %players %unit_ids %dest_area %target_players %target_unit_ids %count %order_id [order_unit_id]

• Issues %order_id to %count unit_ids owned by %players at %source_area, targeting %dest_area.
• If %order_id accepts unit targets, allow targeting only %target_unit_ids owned by %target_players, within %dest_area.
• If %order_id is a train, morph, or build order id, %order_unit_id indicates the unit to make, and %target_unit_ids are ignored.
• e.g. issue_order "Droleth" (384 2800 ~128 ~128) 3 droleth 1 25 131
• Issue a "Zerg build" (order id 25) Hachirosk (unit id 131) order to 1 Droleth owned by player 3 at the specified location, targeting the specified area.

rescue_unit %area %source_players %unit_ids %count %target_player

• Rescues %count %unit_ids owned by source_players in %area, giving them to target_player.
• Plays customary audiovisuals, just like rescuing in campaigns!
• e.g. rescue_unit "Intro Area" * maverick|harakan 20 1
• Rescue up to 20 Mavericks and Harakans owned by all players at the specified location, giving them to player 1.

---

Game State Commands

set_mineral_yields %depleted_yield %yield

• Sets the resource yields of Mineral Fields to %yield (default 4), changing to %depleted_yield (default 2) when depleted.

set_gas_yields %ridge %geyser %tier2 %tier3

• Sets the resource yields of Vespene nodes. Defaults are 2, 4, 5, 6.

set_unit_stat %area %players %unit_ids %cap %stat_type %stat_amount

• Sets %stat_type of %count %unit_ids owned by %players in %area to %stat_amount.
• %stat_type currently supports the following stats (in-game status tooltips listed in quotations):
• armor ("Decided Armor")
• range ("Decided Range") | 32 is 1 range
• armor_pen ("Decided Piercing")
• damage ("Decided Damage")
• splash_inner ("Decided Collateral (Inner)") 32 is 1 range
• splash_medium ("Decided Collateral (Medium)") 32 is 1 range
• splash_outer ("Decided Collateral (Outer)") 32 is 1 range
• timed_life | uses standard time syntax, e.g. 1m1s1ms is one minute, 1 second, and 1 millisecond
• e.g. set_unit_stat "Divine Bulwark" 13 maverick|madcap 5 armor 3
• Set the base armor of 5 Mavericks and/or Madcaps owned by the current player within the location to 3.

set_unit_behavior %area %players %unit_ids %cap %behavior %enable

• Sets %behavior of %count %unit_ids owned by %players in %area.
• If %enable is specified and not zero, the behavior is toggled on; else, it is toggled off.
• %behavior currently supports the following behaviors
• hallucination (deals half damage, cannot cast abilities or build structures)
• e.g. set_unit_behavior "Haze Field" 1 * 2 hallucination true
• Enables the Hallucination behavior for up to 2 units owned by player 1 within the location.

blissful_embrace %area %players %unit_ids [infesting_player]

• Infests all %unit_ids owned by %players in %area.
• If specified, %infesting_player will gain command of the infested units.
• e.g. blissful_embrace "Zerg House" 2 * 1
• Infest any units owned by player 2 within the location, and give them to player 1.

---

Player Commands

set_faction %player %faction

• Sets %player's faction to %faction, enabling and disabling various techtree options.
• Note that this feature is very new and few options are currently available! More documentation will arrive when this system is more developed.

neutral_hostile %bool

• Determines whether to consider the current player a "neutral hostile" player. This feature is a work in progress.

witness_mode %witness_type

• Enables or disables "witness mode" for the trigger owner based on the value of %witness_type. Witness mode enables resource counters for non-witness players.
• %witness_type can be one of the following:
• 1 for a "true" witness, who should not be shown in the score screen after the match completes
• 2 for converting a player into a witness, so they are still shown in the score screen

set_start_location %player %position

• Changes %player's start location to %position. Commonly used to reset AI home positions.
• e.g. set_start_location 3 "Base 12btw"

set_race %player %race

• Changes %player's race to %race. Commonly used to prepare for AI arrivals of a different race.
• %race can be terran, protoss, or zerg, and is case-insensitive.
• e.g. set_race 3 terran

convert_to_ai %player

• Converts %player's type to computer. Not very useful.

set_advisor %players %advisor

• Sets the advisor for %players to %advisor.
• A list of available advisors can be found in config.yml.
• e.g. set_advisor 13 furen
• Sets current player's advisor to Furen.

set_omnipresence_state %players %state

• Sets Omnipresence state for %players. Usually used to enable all racial functions from the Omnivale, for a particular player.
• %state can be:
• all
• terranprotoss
• protosszerg
• zergterran

set_player_build_multiplier %players %multiplier

• Sets build multiplier for %players to %multiplier. Debug's multiplier is 32, for reference.

set_liftoff_disabled %players %true/false

• Sets wither structures owned by %players can lift off. Useful for UMS maps.

set_burrow_disabled %players %true/false

• Sets whether units owned by %players can burrow. Useful for UMS maps.

set_units_disabled %players %unit_ids

• Toggles availability of %unit_ids for %players.

---

AI Commands

set_ai_personality %personality not yet implemented

• Sets the trigger owner's personality to %personality. See AI configuration for a list of personalities.
• e.g. set_ai_personality air
• Sets the personality to Orbital, Skylord, or Sunblot, depending on their race.
• e.g. set_ai_personality raider
• Sets the personality to Raider (Terran only).

set_ai_build_order_type %type not yet implemented

• Sets the trigger owner's build order type to %type.
• %type can by timing, rush, or greed. It can also be a combination, which will result in a random selection between the specified types.
• e.g. set_ai_build_order_type timing|rush
• Randomizes the build order type between timing and rush.

set_ai_build_order %build_order not yet implemented

• Sets the trigger owner's build order type to %build_order. See AI configuration for a list of build orders.
• e.g. set_ai_build_order "Lunatic Legion"
• Sets the build order to Lunatic Legion (Protoss with Templar personality only).

layouts_enable %area %players %unit_ids %bool

• Based on %bool, enables or disables all layouts of %players in %area that match %unit_ids.
• e.g. layouts_enable 63 3 bunker|watchdog|"ion cannon" true
• Enable all layouts with matching unit ids for player 3 across the entire map.

layouts_assign %area %players %unit_ids %resarea_pos

• Assigns layouts owned by %players and matching %unit_ids in %area to the closest resarea of %resarea_pos.
• If %resarea_pos is not specified, the closest resarea to the center of %area is used.
• e.g. layouts_assign P2-NaturalForwardDefenses 2 bunker|watchdog|sentinel|phalanx P2-NaturalCenter
• Assign all matching layouts owned by player 2 in the first location to the closest resarea to the center of the second location.

layouts_priority_add %area %players %unit_ids %delta

• Add or subtract %delta from the priority of all layouts of %players in %area that match %unit_ids.
• e.g. layouts_priority_add "Zerg base here" 5 "alaszil arbor" -12
• Subtract 12 priority btw from any Alaszil Arbor layouts owned by player 5 at the matching location.

layouts_priority_set %area %players %unit_ids %value

• Set priority to %value for all layouts of %players in %area that match %unit_ids.
• e.g. layouts_priority_set 6 * * 120
• Set the priority of all layouts owned by all players at location 6 to 120.

show_player_layouts %players %bool

• Enables or disables logging of requests from the AI layout system.
• This also visualizes layouts, using the following color key:
• Green - requested
• Black - disabled via triggers
• Brown - should not request yet
• White - active
• Purple - expanding
• Yellow - locking other requests until started
• e.g. show_player_layouts 3|5 true
• Enable layout logging for players 3 and 5.
• e.g. show_player_layouts 15 false
• Disable layout logging for foes.

create_town %player %pos %worker_count %attach_to_nearest_resarea_bool %claim_layouts_area %unit_ids

• Creates an AI town for %player at %pos, requesting %worker_count (and transferring workers from other towns, if available).
• %attach_to_nearest_resarea_bool defaults to true. If set to false, the new town will not attach to any resarea, and workers will not harvest resources.
• If specified and valid, %claim_layouts_area will take ownership of all layouts matching %unit_ids inside %claim_layouts_area.
• e.g. create_town 8 "P8 bunker east" 2 false "P8 bunker east"
• Creates a town for player 8 at the location without attaching to any resarea. Transfers 2 workers from other bases to the new town. Claim layouts at the location.

---

Audio Commands

play_sound %filepath %players %position %min_visibility

• Plays %sound at %position.
• %position defaults to global if not set. You can also use () for a global sound.
• %min_visibility can be visible (default), explored, or unexplored.

unit_sound %players %unit_ids %animation_type %old_sound_id %new_sound_filepath %bool_replace

• Every time units with %unit_ids owned by %players attempt to play %old_sound_id while using %animation_type, play %new_sound instead.
• %animation_type uses the list defined at the top of the trigger comments section.
• %old_sound_id can be * for any sound. To replace specific sounds by their ID, you should consult sfxdata.dat inside the executable's mpq.
• If multiple unit_sound triggers are defined with the same characteristics but different sounds, a random sound from the defined sounds will play each time.
• %bool_replace defaults to true and dictates whether to replace the original sound, or to simply add the new sound instead.

play_music %filepath

• Plays music located at %filepath.

stop_music

• Stops the current music, and skips to the next music if applicable.

pause_music

• Pauses any music from playing until resumed.

resume_music

• If music is paused, resume play.

music_fade_in %time

• Sets music fade in to %time.
• Music fades in when affected by play_music, stop_music, or resume_music, and applies to the next track.

music_fade_out %time

• Sets music fade out to %time.
• Music fades out when affected by play_music, stop_music, or pause_music, and applies to the previous track.

music_volume %volume %time

• Sets music volume to %volume (where 0.0 muted - 1.0 max) over %seconds.
• If %time is 0, the volume will be adjusted immediately, instead of fading to the new volume.
• If %time is not 0, a volume fade will occur.
• There can only be one volume fade at any given time, and newer fades will interrupt previous fades by fading to the new volume value.
• Volume only applies to custom music.

playlist_clear

• Removes all tracks from the playlist, and sets shuffle to false if it was true.
• This does not interrupt the current music.

playlist_add %path

• Adds music located at %path to the playlist.
• The playlist plays tracks on a loop while no other tracks are playing.

playlist_shuffle %shuffle (0 - false, 1 - true)

• If %shuffle true, shuffle the playlist when it first plays and when it loops back.
• Shuffle will never swap the first and last tracks, which means the playlist's final track will never be the first track after shuffling.

Regarding original music:

• If no music is specified and music is not paused, the game will default to original music.
• To play original music again, you will need to call playlist_clear and then stop_music.
• To have no music at all, you can call pause_music.

---

Visual Commands

recolor (%r %g %b %gamma %saturation) (%r %g %b %gamma %saturation) (%r %g %b %gamma %saturation) %time

• Applies color grading over %time.
• %r, %g, %b, %gamma, and %saturation are scalars, e.g. 0.5 = half and 2 = double.
• The number of blocks determines the kind of recolor:
• With one block, you have a uniform recolor.
• With only two blocks, you have shadows and highlights.
• With only three blocks, you have shadows, midtones, and highlights.
• With more than three blocks and up to sixteen blocks, you create a gradient map with even spacing between the blocks.
• Arguments default to 1 if not specified. You can default a block's values with a blank block: ().
• The last arguments in a block can be skipped.
• For example, if you only want to edit RGB values, you can omit %gamma and %saturation from the block.
• e.g. recolor (1.8 0 2.4 0.9 1.25) (0 3.33 0 1 2) 0

recolor_loop_add (shadows: %r %g %b %gamma %saturation) (midtones: %r %g %b %gamma %saturation) (highlights: %r %g %b %gamma %saturation) %seconds

• Adds a color grading to the recolor loop. When a previous recolor's %seconds have passed, it is considered "finished", and the loop's next recolor will apply.

recolor_loop_clear

• Stops any active recolor loop. Does not change the color grading. Works for both standard and advanced versions of the recolor commands.

set_player_color %player %color

• Changes %player's color to %color. Affects current and new units.
• %color is the name of the player color. Consult the color list for color names and previews.
• e.g. set_player_color 6 sienna
• e.g. set_player_color 6 "b'dazzled blue"

unit_sprite %players %unit_ids %id_type %value

• Replaces the sprite of %unit_ids owned by %players with %value.
• %id_type can be sprite_id or unit_id.
• If %id_type is sprite_id, %value will be a sprite ID.
• If %id_type is unit_id, %value will be converted from a unit ID to a sprite ID.
• e.g. sprite_id 235 and unit_id maverick are identical to each other.
• e.g. unit_sprite * maverick unit_id madcap
• Replaces the sprite of all current and future Mavericks owned by any player with the Madcap sprite.

clear_unit_sprite %players %unit_ids %id_type %value

• Clears any sprite replacement that exactly matches %value for %unit_ids owned by %players.
• To make sure your sprite replacement is cleared correctly, make sure the %players and %unit_ids fields are identical to a previous replacement.
• e.g. If you replaced unit IDs harakan&cyprian for players 1&2&3, you can't clear it with harakan or 1&2.
• e.g. clear_unit_sprite * maverick unit_id madcap
• Clears the previous sprite replacement.

set_celebration %celebration_type

• Sets the celebration type for the map.
• celebration_type can be:
• auto for allowing celebrations based on the system date (default)
• none for forbidding celebrations regardless of system date
• christmas for forcing Christmas celebrations regardless of system date
• april_fools for forcing April Fools celebrations regardless of system date

---

UI Commands

set_player_unit_name %player %unit_id %name

• Sets all units of %unit_id owned by %player to %name.
• %unit_id parsing is not case-sensitive and does not require the race prefix.
• %name overwrites the unit's full name, including the default race prefixes.
• Use quotation marks for strings that contain spaces.
• e.g. set_player_unit_name 3 zoryusthaleth "Zerg Tiny Tony"
• e.g. set_player_unit_name 6 "hydralisk den" "Project: HYDRA Server"

set_player_race_name %player %old_race %new_race %unit_ids

• Sets all units matching %unit_ids owned by %player with matching %old_race to display %new_race as their prefix.
• %unit_ids can be * for all units.
• e.g. set_player_race_name 3 Zerg Zerghere *

set_player_name %player %name %ignore_human_name_bool

• Sets %player name to %name.
• Like other triggers, this change is only local to the trigger's owners.
• When %ignore_human_name_bool is false, the player's profile name will be visible, wrapped in parenthesis.
• e.g. set_player_name 1 "Polish Powerhouse"

set_force_name %player %name

• Sets %player faction name to %name.
• Like other triggers, this change is only local to the trigger's owners.
• e.g. set_force_name 1 "GoodCode Incorporated"

objective_set %key %text

• Defines objective display text that is visible beneath the game timer and APM counter.
• %key is used to refer back to an objective. The objective with the lowest key will be sorted first in the list. Values can be negative.
• e.g. objective_set 1 "Destroy all enemy factories."

objective_text %key %text

• Modifies objective text, which is displayed in-game.
• e.g. objective_text 1 "Destroy all enemy Hatcheries."

objective_desc %key %text not yet implemented

• Modifies objective description, which is displayed in the objectives menu.
• e.g. objective_desc 1 "There are Zerghere, and they must not be here any longer!"

objective_show %key %bool

• If %bool is false, hide the objective. Otherwise, show the objective.
• e.g. objective_show 1 true will show the objective.

objective_score %key %score %max_score

• Set objective score to %score out of %max_score, represented as %score/%max_score.
• %score will be clamped between 0 and max_score.
• e.g. objective_score 1 0 10 will display 0/10 score accrued.

objective_score_add %key %score %max_score

• Adds %score to the objective's score value, and %max_score to the objective's max_score value.
• e.g. objective_score_add 1 0 1 will add 1 to the maximum score.

objective_score_subtract %key %score %max_score

• Subtracts %score from the objective's score value, and %max_score from the objective's max_score value.
• e.g. objective_score_add 1 1 0 will subtract 1 from the score.

objective_timer %key %timer

• Set a timer for objective matching %key to %timer.
• e.g. objective_timer 3 3m will initiate a 3-minute countdown timer next to the matching objective.

objective_remove %key

• Removes an objective with a matching %key.
• e.g. objective_remove 1

objectives_sync not yet implemented

• Syncs all current objectives to the mission objectives menu.

objectives_clear

• Clears all current objectives from the in-game display.

set_player_team_ui %players %state

• Sets team UI for %players. Set to false to show and true to hide. Useful for allies that arrive during the level.

show_button %id %display_name %priority

• Initializes a var named id to a value of 0.
• Creates a custom button to be clicked by the local player. Clicking the button will set var named id to 1.
• Custom buttons are ordered by %priority.
• e.g. show_button donate "Donate on ko-fi"

hide_button %id

• Hides a custom button with a matching id.

---

Control Flow Actions

These commands allow for developers to track in-game events and create complex conditions for their triggers.

print %text

• Prints %text onscreen for the trigger owner. Mostly useful for quickly debugging custom trigger actions.

wait %time

• Waits for %time without blocking normal trigger execution.

var %name %operator %value

• Sets an internal variable for usage in custom triggers.
• %name can be up to 32 characters long.
• %operator can be =, +=, -=, *=, /=, %=, toggle, unset.
• Normally, variables must be set with the = operator before any mathematical operators can be used.
• Suffixing %operator with an additional = sets the variable to 0 if it wasn't already set, and then performs the operation.
• e.g. +== 5 sets the variable value to 0 if it is unset, and adds 5 to the subsequent value is.
• The toggle operator sets the variable to a value of true if currently false or unset, or to a value of false if currently true.
• The unset operator removes the variable matching %name.

• value can be an integer, or random followed by two integers.
• Caveat: random only accepts positive values.
• value can also be a variable name, prefixed with $.
• e.g. var men_copy = $men assigns the value of variable men to the new variable men_copy.
• e.g. var reinforcement_count = 5
• Set a variable with a value of 5.
• e.g. var reinforcement_count +== 3
• Increase a variable's value by 3. Set the variable if it hasn't been set already.
• e.g. var switchtastic toggle
• Toggles the variable's boolean state.
• e.g. var clowns_to_spawn += random 3 33
• Add a random value between 3 and 33 to the variable, if it has already been set.

timer %name %operator %value

• %name and %operator are identical to the var command.
• Once set, %value is decremented until it reaches 0 (unless the game is paused).
• e.g. timer reinforcement_timer = 333s
• Set a timer with an initial time of 333 seconds.
• e.g. timer reinforcement_timer -= 3s
• Decrease a timer's value by 3 seconds, if it has already been set.

bank_link_var %bank %var %default_value

• Tracks %var in %bank, synchronizing changes to it automatically.
• %default_value will be 0 if not specified.
• e.g. bank_link_var terran01 bonus_objective_completed 0

bank_clear %bank

• Clears all vars from %bank.

---

Conditions

Custom conditions are read at the same time as normal trigger conditions, even though they are defined through the trigger comment action. They are always prefixed with the identifier condition, and it is recommended to keep custom conditions at the top of your trigger action list, for organizational purposes.

Conditions use bitwise comparisons between unit ids and player numbers. This allows for flexible combinations, such as the following:

• And:
• zerg&men - unit id must be a Zerg non-building.
• Or:
• 1|2 - player must be either 1 or 2.
• mason|maverick - unit id must be a Mason or a Maverick.
• All:
• * - all players or unit ids are accepted.
• Negation:
• !1&!2 - player must not be 1 or 2.
• *&!building - all non-buildings are accepted.

condition combat %area %source_players %source_unit_ids %target_players %target_unit_ids %time_quota %scouting_player

• Waits to execute trigger actions until %scouting_player has seen %source_unit_ids owned by %source_players doing combat with %target_unit_ids owned by %target_players for %time_quota.
• A %scouting_player value of 0 ignores the scouting requirement.
• Combat is defined as dealing or receiving damage.
• e.g. condition combat * 4 zethrokor|quazilisk 2|3 terran&buildings|zerg&buildings 5s
• Wait until player 4's Zethrokors or Quazilisks have attacked Terran buildings or Zerg buildings owned by players 2 or 3 anywhere on the map within the last 5 seconds.

condition kills %area %source_players %source_unit_ids %target_players %target_unit_ids %quota %time_quota %scouting_player

• Waits to execute trigger actions until %scouting_player has witnessed %source_unit_ids owned by %source_players kill %quota %target_unit_ids owned by %target_players.
• Not specifying a %scouting_player, or specifying a value of 0, ignores the scouting requirement.
• e.g. condition kills * 16 * 17 ministry|nexus|hachirosk|caphrolosk|gathtelosk 3
• Wait until force 1 has killed at least 3 of the above unit ids owned by force 2 anywhere on the map.
• e.g. condition kills 5 16 * 17 ministry|nexus|hachirosk|caphrolosk|gathtelosk 3 60s 1
• Wait until force 1 has killed at least 3 of the above unit ids owned by force 2 in location 5. Only return true if player 1 had vision of a matching event in the last 60 seconds.

condition deaths %area %players %unit_ids %quota %time_quota %scouting_player

• Waits to execute trigger actions until scouting_player has witnessed %quota %unit_ids owned by %players die in %area within the last %time_quota seconds.
• Not specifying a %scouting_player, or specifying a value of 0, ignores the scouting requirement.
• e.g. condition deaths (1234 1234 333 333) * terran&men 333 * 1
• Wait until player 1 witnesses 333 Terran men owned by any player to die at the coordinates.
• e.g. condition deaths "sacrificial pit" 3 combatants <5 60s
• Wait until less than 5 combatants owned by player 3 have died at the location in the last 60 seconds.

condition unit_count %area %players %unit_ids %quota %scouting_player %scouting_time_quota

• Waits to execute trigger actions until %players own %quota %unit_ids.
• If %scouting_player is specified, %scouting_player must have seen %quota %unit_ids owned by %players.
• A value of 0 is ignored.
• Scouted units have their last seen position tracked, as opposed to their true position.
• If %scouting_time_quota is specified and not 0, %scouting_player must have seen %quota %unit_ids owned by %players within the last %scouting_time_quota.
• e.g. condition unit_count * 15 "mutath spire"|"tosvrol haunt" 1 5
• Wait until player 5 has scouted at least 1 Mutath Spire or Tosvrol Haunt owned by enemies and located anywhere on the map.
• e.g. condition unit_count "Depot" 13 supply_depot =0
• Wait until current player has exactly 0 Supply Depots in the location.

condition local_camera %area %min_visibility

• Waits to execute trigger actions until camera is detected at %area.
• Caveat: This command is not synchronized in multiplayer, and as such will lead to desyncs if used as a condition for a trigger that alters gameplay.
• local_camera will eventually be replaced with a version of the command that is synchronized in multiplayer.
• The central point of the camera must be within %area within the gameplay view. UI does not count.
• In a similar vein, AI do not have cameras, so this should only be used for human players.
• %min_visibility can be visible (default), explored, or unexplored.
• e.g. condition local_camera "tikimon's house" visible

condition var %name %operator %quota

• Waits to execute trigger actions until a variable matching %name reaches %quota.
• %operator defaults to == and can be anything from the "quota operators" section.
• This condition will never be true if a variable was never initialized, or if the variable was manually cleared.
• e.g. condition var hatcheries_killed_by_p1 > 5
• Wait for the value of variable hatcheries_killed_by_p1 to be greater than 5.
• e.g. condition var bias_aggressive >= $bias_conservative
• Wait for the value of variable bias_aggressive to be greater than or equal to the value of variable bias_conservative.

condition timer %name %operator %quota

• Waits to execute trigger actions until a timer matching %name reaches %quota.
• e.g. condition timer reinforcement_timer == 0
• Wait for timer reinforcement_timer to equal 0.

condition unit_color %area %players %unit_ids %quota %color_id

• Waits to execute trigger actions until %quota %unit_ids with %color_id player color owned by %players exist within %area.
• See possible pcolors for a list of colors, complete with their IDs.
• e.g. condition unit_color * 1 maverick 3 0
• Wait for at least 3 Mavericks owned by player 1 with color Red to exist anywhere.

condition player_race %player %operator %race

• Waits to execute trigger actions until %player's race is or is not %race.
• %operator can be == or !=.
• %race can be terran, protoss, or zerg.
• e.g. condition player_is_race 13 == zerg
• Wait until the trigger owner's race is Zerg.
• e.g. exit_if player_is_race 1 != protoss
• Exit the trigger if player 1's race is not Protoss.

---

Control Flow Conditions

The following functions have the same syntax as condition, but act as actions that change the control flow of triggers in the midst of trigger execution.

exit_if %condition

• If %condition is true, exit the trigger without completing subsequent actions.

exit_preserve_if %condition

• Same as exit_if, but preserves the trigger.

wait_if %condition

• Pause trigger execution until %condition is false.

wait_until %condition

• Pause trigger execution until %condition is true.

---

Custom Game Modes

---

Threshold

The ruleset for the survival game mode Threshold, first featured in "One for the Future - The Cosmonarch", can be implemented in any map which has at least seven players.

Players:

• Player 1 must be a human player.
• Players 2 through 7 must be computer players.
• Player 8 can be an optional coop player, witness, or anything else.

Setup:

• All players must have their scanner sweep deaths set to 7, and their right pit door deaths set to either 1 or 2.
• A right pit door death of 1 summons a new enemy every 3 minutes and supports 1 human player.
• A right pit door death of 2 summons a new enemy every 1.5 minutes and supports 2 human players.
• For handling AI spawning, place the following units for player 12 near desired resource areas.
• Ministry:" location of spawned town center.
• Pylon: location of spawned units.
• Maverick: rally point of spawned units.
• Refer to "One for the Future - The Cosmonarch" or "Fraudscendance" for working examples.