Cosmonarchy BW

---

Mod Setup

---

Cosmonarchy BW is built on version 1.16.1 of Starcraft. You can follow this installation guide to install version 1.16.1.

Cosmonarchy BW can be downloaded in the following locations:

• Public release
• Prerelease builds (frequently updated!)

Once you have version 1.16.1 installed and Cosmonarchy BW downloaded, place the mod's custom maps in your Starcraft maps directory (usually C:\Program Files\Starcraft\maps).

Place Cosmonarchy's exe in the same directory as the included plugins folder. Without the plugins folder being in the same directory, the exe will not run! If it still fails to run despite this, try placing the plugins in your Starcraft installation directory (the same place as Starcraft.exe).

Please note: it is exceedingly common for Windows Defender to flag all Starcraft mods as viruses. This is because Starcraft mods use code injection to apply their changes to the game. Cosmonarchy BW is safe for your PC, and many users have played the mod without issue.

To update:

• Simply download the whole package from gitlab to update everything.
• Alternatively, Gitlab supports downloading individual files, if you only wish to update specific files.

Community games are organized using Radmin VPN, a free and seemingly lightweight network utility.

• Download Radmin VPN
• Join the No Frauds Club network with the following credentials:
• Network name: FRAUDSCLUB
• Password: toddad69
• Create and join Starcraft games by launching Starcraft, selecting Multiplayer, and selecting Local Area Network (UDP)
• Join the No Frauds Club discord server to organize community games in real time

---

Scenario Setup

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

For first-time users of custom editor mpqs, refer to the mapping starter guide.

---

General Utilities

Randomizing a force's start location will randomize player colors for all players in that force.

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% (Protoss AI default)
• 2 - 133% (Terran AI default)
• 3 - 150% (Zerg AI default)
• 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, they will also randomize their color by default.
• Setting 4 Vespene Geyser deaths counteracts this, allowing randomized start locations and fixed colors simultaneously.
• Add 8 Vespene Geyser deaths to disable the "quasifog" 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.

---

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 adapt if given lots of resources at runtime.
• For optional AI support, leave the controller type as 'human' (in multiplayer mode, Cosmonarchy BW converts empty human slots to computers).

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 to above 0.
• To enable debug messages for showing AI personalities and build orders, set the computer player's start location deaths above 0.
• To override the AI's resource multiplier, set upgrade 58 to above 0. See general configuration for more info.
• 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 base layouts.
• If you find a bug or run into trouble, feel free to reach out on discord!

---

---

---

---

Base layouts and guards:

• Thanks to the work of Veeq7, it is now possible to define an AI's base layout, guards, and request flow using hallucinated placeholders!
• Placing a unit will create a request at that position for the unit's owner.
• 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.
• Requests are tied to the nearest resource area. If the AI does not yet own that resource area, the requests will not be issued until they claim it.
• Layout positions are currently not supported for:
• Choosing which structure to morph (e.g. precisely picking Creep Colonies to turn into Sunken Colonies).
• Choosing which structure to build an addon (e.g. precisely picking a Factory to build a Machine Shop).

Layout modifiers and notes:

• Hallucinated placeholders are removed at the beginning of each game and do not spawn initial creep.
• Hallucinated placeholders owned by player 12 will apply for all players.
• Cloaked structure placeholders will not be requested, but their layouts will still be logged.
• Cloaking has no effect on units, because units are always requested.
• Invincible placeholders will be assigned to the AI's main town instead of the nearest resource area.
• Invincibility is toggled at runtime after logging base layouts.
• If you want to make a unit invincible, you must now use a trigger to toggle invincibility after a brief delay.
• If two structures with equivalent IDs (such as Lair and Hive) occupy the same space, only the highest-tier placeholder will be processed.
• Placing a hallucinated Control Node (under Neutral -> Special) will add layouts for Command Center, Nexus, and Hatchery, 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 placeholder, the default expansion build order will also be ignored.
• This allows you to place town center placeholders without needing to place units and structures for every expansion.
• While default build orders are disabled,
• Setting mineral field (type 1) deaths will set a custom delay, in seconds, for the AI's first gas structure request
• 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 BW 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. 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\zzzdevGUN-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
• 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.

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

clear_creep %area

• Clears all creep at %area.
• %area can be (x y width height), a location id, or a location name.
• Caveat: Creep will not begin to re-spread until a new creep generator is constructed nearby. This is a low-priority fix, but it will eventually be corrected.
• e.g. clear_creep 8 or clear_creep "Remove Creep Here"
• e.g. clear_creep (4000 5024 128 128)

---

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).

placeholders_enable %area %players %unit_ids %bool

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

placeholders_priority_add %area %players %unit_ids %delta

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

placeholders_priority_set %area %players %unit_ids %value

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

log_placeholder_requests %player %bool

• Enables or disables logging of requests from the AI placeholder system. %player starts at 0 for player 1.
• e.g. log_placeholder_requests 2 true
• Enable placeholder logging for player 3.

create_town %player %pos %worker_count %attach_to_nearest_resarea_bool %claim_placeholders_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_placeholders_area will take ownership of all AI placeholders matching %unit_ids inside %claim_placeholders_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 placeholders at the location.

---

Audio Commands

play_sound %filepath %players %min_visibility %position

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

replace_sound %players %unit_ids %animation_type %old_sound_id %new_sound_filepath %bool_replace

• Every time %player's units with %image_id 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.
• %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.

fade_in %seconds

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

fade_out %seconds

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

volume %volume %seconds

• Sets music volume to %volume (where 0.0 muted - 1.0 max) over %seconds.
• If %seconds is 0, the volume will be adjusted immediately, instead of fading to the new volume.
• If %seconds 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.
• 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 set to 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) %seconds

• Applies color grading over %seconds (can be decimals).
• %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.

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"

---

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 timer and APM counter.
• Players can disable ingame displays in their config.
• %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.
• %score and %max_score can be negative.
• e.g. objective_score_add 1 0 1 will add 1 to the maximum score.

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.

---

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 %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 0
• Wait until player 4's zethrokors or quazilisks have attacked terran buildings or zerg buildings owned by players 2 or 3 within the last 5 seconds.

condition kills %source_players %source_unit_ids %target_players %target_unit_ids %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 "command center"|nexus|hatchery|lair|hive|sire 3
• Wait until force 1 has killed at least 3 of the above unit ids owned by force 2.

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

• Waits to execute trigger actions until %players own %quota %unit_ids.
• %area can be (x y width height), a location id, or a location name.
• 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 63 15 "muthrok spire"|"vithrath haunt" 1 5
• Wait until player 5 has scouted at least 1 Muthrok Spire or Vithrath Haunt owned by enemies and located anywhere on the map.

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.
• %area can be (x y width height), a location id, or a location name.
• %min_visibility can be visible (default), explored, or unexplored.
• e.g. condition local_camera "tikimon's house" visible

---

Custom Game Modes

---

Threshold

The ruleset for the survival game mode Threshold, first featured in "One for the Future #9 - 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
• Players 2 and 5 must be Terran
• Players 3 and 6 must be Protoss
• Players 4 and 7 must be Zerg
• Player 8 can be an optional coop player, observer, 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
• Command Center:" location of spawned town center
• Pylon: location of spawned units
• Maverick: rally point of spawned units
• Refer to "One for the Future #9 - The Cosmonarch" or "Fraudscendance" for a working example