C:\Program Files (x86)\StarCraft II\Mods


Changelog

(Not all changes are listed)

2011.03.17
Open source release

See older changes



Map Information

    
    SYSTEM REQUIREMENTS:
      4 core CPU and 1GB video card for mass units games.
    
    MAP STATISTICS:
      20000+ Lines of Raw Code
      1200+ Trigger Comments
      6 Games, Multiple Modes and Features each
      Main Tools: StarCraft II Editor, Notepad++, Irfanview, Photoshop
                  SCMDraft 2, Starcraft Map Cracker
      Open source map, view triggers for more info
      Project started December 9, 2010
    
    
    FEATURES:
        Name: SC1 Greatest Hits
        Type: Compilation
        Map: 256x256 Bel'Shir, 252x252 Playable
        Subtilesets: Braxis Alpha Metal, Meinhoff White Sand, Shakuras Sand, Mar Sara Sand
        Forces: 1 "Players" or 2 "Top vs Bottom"
        Players: 6
        Difficulty: Variable
        Duration: 30 minutes to forever via remake
        
        Description:
        The most fun, the most replayable SC maps, faithfully remade into SC2's beautiful
        3D glory in one self-contained meta-map.
        
        Features:
        - Simulated SC1 lobby with detailed map panels, same host features as battle.net
        - Only host can start a game, or the most voted game will autostart
        - Host and players can choose map features and modes before game start
        - Unified yet independently modular meta-map system
        - Cross-game utility console commands
        - Remake feature to return to virtual lobby to start a new game
        
        "Looking for Players" Channel: SGH
        
        Search for this map on the US server with the keyword "greatest"
        
        
    PLANNED GAMES:
      1a2a3a Hotkey, 1000 Marines, 20001 Hydras Attack, Archon Tag, BGH God's Land, BGH Team Melee,
      Bombing Zone, Drawing Contest (Pictionary) Level F---ng Computer, Ghost Nuke Madness,
      Korean Defense, Observer Lovely, SAT Control, Sniper Paintball, Vulture Control
        
    THANKS: (Tutorial/Asset posters or testers)
      AegisRunestone  Oblivion  payne  progammer  uiasdnmb  UloseTheGame
        


Games Details


Optional features and extra modes can be selected once the menu popup appears when a game is chosen.

    Brood War Lobby (4 January 2010)
        
        Type:       Social, Chat
        Partition:  None
        Forces:     1 "Players"
        Players:    6
        Difficulty: None
        Duration:   Forever
        
        Features: 
        - Change own race
        - Change computer difficulty or en/disable them
        - Switch players to other teams
        - Choose game options as host or volunteer for roles as players
        
        Notes:
        - Press Enter any time in the lobby to show the chat lobby and player slots
        - Selecting the swap players subslot will swap that player to the other team in that # order
        - Type ?rm during a game to return to the lobby
        
        
    Big Game Hunters (22 December 2010)
        
        Type:       Melee, Skirmish, vs AI
        Partition:  128x128 Bel'Shir
        Forces:     1 "Humans" or 2 "Top vs Bottom"
        Players:    3 vs 3 or X vs X AI
        Difficulty: Players Dependent
        Duration:   0.5-1 Hour
        
        Optional Features: 
        - Resource Level
        - Fast and Free Build
        - Excess Supplies
        - Play as All Races
        
        Extra Modes:
        - Shuffled Start Positions
        - Top vs Bottom Positions
        - Humans vs Computers
        - Free for All
        
        Notes:
        - Add AIs while in battle.net lobby to play against them in melee games
        - Arrange AIs for teams by clicking their slot names, or play the mode vs All Computers
        - In Fast & Free mode, type ?kill to suicide your selected units
        
        
    BGH Phantom (8 January 2011)
        
        Type:       Backstab Melee
        Partition:  128x128 Bel'Shir
        Forces:     1 "Phantom and Slayers"
        Players:    5 slayers and 1 phantom
        Difficulty: Players Dependent
        Duration:   0.5-1 Hour
        
        Optional Features: 
        - Resource Level
        - Everyone Same Color
        - No Visioning
        - Reveal Phantom Timer
        
        Extra Modes:
        - The Mole, phantom can ally rogue computers
        
        
    SCV Football (14 January 2011)
        
        Type:       Field Sport
        Partition:  48x20 Bel'Shir
        Forces:     2 "Players"
        Players:    3 vs 3
        Difficulty: Players Dependent
        Duration:   15-30 Minutes
        
        Optional Features: 
        - Touchdown Limit
        - Round Time
        
        
    Art of Defense (17 January 2011)
        
        Type:       Base Survival
        Partition:  120x62 Braxis Alpha
        Forces:     1 "Players"
        Players:    4-6
        Difficulty: Very Hard
        Duration:   35 Minutes
        Waves:      14
        
        
    Block the Entrance (28 January 2011)
        
        Type:       Platform Control
        Partition:  38x32 Meinhoff
        Forces:     1 "Controllers"
        Players:    1-6
        Difficulty: Medium-Hard
        Duration:   15-30 Minutes
        Levels:     40, 2 Variations each
        
        Optional Features: 
        - Skip To Level
        - Level Shuffling
        - Role Shuffling
        
        Notes:
        - Type ?die if your units cannot complete the level
        
        
    Dodge the Rapierist (2 February 2011)
        
        Type:       Unit Dodge
        Partition:  128x128 Bel'Shir
        Forces:     1 "Dodgers"
        Players:    1-6
        Difficulty: Hard-Very Hard
        Duration:   0.5-1 Hour
        Levels:     20
        
        Optional Features: 
        - Dodger Unit, varying speeds
        - Shuffle Levels
        
        Extra Modes:
        - Waldo Mode, find three smaller wanderers
        - Race Mode, race against other players


Documentation & Tutorials

Sections


Foreword

Introduction

From the beginning, SC1 Greatest Hits (SGH) was made not just to be played by fans of the original StarCraft custom maps (UMS), but like most of the maps it ported from, SGH is meant to be opened and studied by novice and curious map makers, following the free and open tradition of the hosting and map distribution system of classic battle.net. The map itself contains expansive trigger notes on how things were done, but the documentation here is an extension to help prospective map makers to learn by imitation and experimentation using SGH as a template.

SC1 Greatest Hits and this documentation are released as public domain, you may copy and modify without asking permission or giving credit. Note that the map uses Blizzard's assets and--it being a SC2 map--is Blizzard's property. As the author, I wish that you do not republish a duplicate of this map in the North American (NA/US) server or plagiarize. Instead, copy the desired parts of the map and improve them in your own map or version. If you have questions or need further assistance, post them in the forum.

Reusing Map Parts

Have both SGH and the target map opened. To switch between the two maps, click Window on the editor's menu bar and choose the map (X:/.../TargetMap.SC2Map). Each documentation sections below will prelude with the copying instructions.

Playing SGH in Single Player (Offline)

Open the map with the C:\Program Files (x86)\StarCraft II\StarCraft II Editor.exe, open the Triggers Module (F6) and select the trigger Main\Initializations\ini_trgSetup, then on the right pane right click the action Variable - Set lob.bol_isPlayingOffline = true and enable it; this will turn on debug hotkeys and allow proper arrangement of teams (which differ when playing on battle.net). To play the map, menu bar: File > Test Document (Ctrl+F9) or click the "SC" with arrow icon top right.


Import Module

Download SGH Assets and Source Files (April 2011)

To copy assets: open the Import Module (F9), shift or ctrl select the desired files then Ctrl+E to export to a directory, then switch to the other map and with the Import Module open, Ctrl+I to browse to the extracted directory and reimport the files.

Files

SGH uses mainly two filetypes, images (dds) and sounds (ogg), which are mostly used for SC1 dialog emulation and map previews. Files are accessed by variables instead of directly by their addresses for ease of maintenance. Filesize is conserved by using only SC2's native assets when outside of designing the SC1 lobby. Choosing a SC2 image asset is done in Irfanview Thumbnails by viewing an Explorer folder with all the assets extracted by Ladik's MPQ Editor from the file StarCraft II\Mods\Core.SC2Mod\base.SC2Assets.

Custom Text Styles

SGH's imported styles.xml file contains custom font style definitions with varying size and alignment. It is used by referring it in the Data Editor > Game UI Data (section) > Dflt (object) > UI (tab) > CGameUI_FontStyleFileArray (field). An example definition in the xml file:

<Style name="SGH_Level" template="HeaderExtendedTemplate" height="42" hjustify="Center" vjustify="Middle"/>

Attributes are the attribute= keywords. Values are those inside quotes.

  • name - string name of the style, as in <s val="mystyle">test</s> in the editor's text input
  • template - variable name of the fonts
  • font - native font files of SC2, not configurable
  • height - font size, accepts: 1...65 points, >66 will only increase the line height
  • hjustify - horizontal alignment, accepts: Left Center Right
  • vjustify - vertical alignment, accepts: Top Middle Bottom
  • fontflags - unused
  • styleflags - font effects, accepts: !Shadow Shadow
  • textcolor - font color, accepts hexadecimal color; should use trigger to set the color instead
  • disabledcolor - font color when dialog item is disabled
  • highlightcolor - font color when dialog item is hovered
  • hotkeycolor - color of letters prefixed with <h/> in the editor's text input
  • hyperlinkcolor - unused
  • shadowcolor - color of shadow
  • shadowoffset - offset the text top left and its shadow bottom right, accepts: 0... pixels
Template                   Weight   Stretch   Font
BulletTemplate             bold     normal    Eurostile-Bol.otf
HeaderTemplate             bold     normal    Eurostile-Bol.otf
StandardTemplate           normal   normal    Eurostile-Reg.otf
HeaderExtendedTemplate     bold     wide      EurostileExt-Med.otf
StandardExtendedTemplate   normal   wide      EurostileExt-Reg.otf
InternationalTemplate      normal   normal    bl.ttf
CustomTemplate             normal   normal    bl.ttf

Note: BulletTemplate and HeaderTemplate are identical and of the Eurostile typeface. InternationalTemplate and CustomTemplate are identical, except CustomTemplate does not have shadows like all others.

File Formatting

SC1 assets were extracted from the Starcraft CD's StarDat.mpq and images were edited in Photoshop with shaded Alpha channel then flattened and exported using NVIDIA DDS plug-in with the settings DXT5 ARGB 8 bpp | interpolated alpha; 2D Texture; No MIP maps. The Targa (tga) format is used for the battle.net map preview image (Menu bar: Map > Map Info > Preview Image) with the settings 32 bits/pixel; Compress (RLE). Ogg files were converted using Foobar2000 with Level 6 Quality (160kbps).


Terrain Module

To copy terrain: open the Terrain Module (F5), tap T to load the terrain layer, tap Space until the broken line brush is gone, then drag-select the desired terrain area to be copied. After releasing the mouse button, the selected area will appear green on the minimap. Ctrl+C to copy the selection and switch to the target map to Ctrl+V paste the terrain.

Terrain and Pathing

The base tileset and lighting is Bel'Shir, with textures Dirt Light, Dirt Dark, Grass Light, and Bricks Small to emulate the Jungle and Badlands tilesets in SC1 (Data Editor > Terrain Texture Sets > Terrain Textures). Extra textures used are Braxis Alpha Metal (Space), Meinhoff White Sand (Ice), Shakuras Sand (Twilight), and Mar Sara Sand (Desert) with lighting adjusted to the respective tileset (Map > Map Textures).

Most games' terrain was generated using the File > Convert Legacy Map editor feature and then copied into the appropriate map partition. Heightened terrain with painted pathing blocker is used instead of cliffs in reuseable partitions, as cliffs cannot be hidden by the Hide Terrain action. The only custom water is Shakuras used in BGH, which is also the only partition with foliage.

Units and Doodads

The only preplaced units are resource nodes, which are automatically hidden to be recycled by trigger when nearing exhaustion. Doodads are used sparingly and are hidden using the SetVisibility actor message.

Points and Regions

Point and Region names are prefixed with a game's abbreviation, affixed with its type, and finally its scope. For example, the bgh_sel_expansion region is used for selecting all the expansion resources in BGH. Read the comments in the Meta trigger folder for all the abbreviations. Most regions are hidden for tidiness, to view them, open the Terrain Module and tap R to see the left pane listing all the regions, right click a region to show or view it. Tap P to view the points layer. No point is hidden since they are too small to clutter. Points that are only used once are not placed in the terrain, but used directly as XY coordinates in triggers.


Data Module

To copy data: open the Data Module (F7), choose the Data Type from the dropdown list (e.g. Behaviors) of the target object, for the Data Source dropdown list choose the map's filename, which will show all the modified data objects for the map in green. Click an object in the top left pane and Ctrl+C to copy the object, then switch to other map and paste in the same section's pane. Note that most data were modified from the default, so it is better to read the procedure described in triggers' comments and repeat it than to copy a new object.

To see all the modified data, on the top left pane of the Data Editor, choose for Data Source the selection /.../SC1 Greatest Hits.SC2Map (All text in green are custom data). Since all games share the same data, data editing is avoided and instead delegated to the Set Catalog Field trigger action, which can be reverted at every game reset. For specific data edit procedures, read the comments of the relevant trigger. The procedures below assume the Data Editor's View options are:

 _View__Data__Map__Modules__Window__Help_________
|[X]| View Raw Data                       Ctrl+D |  Variables in ID data name / Descriptive name
|---|--------------------------------------------|
|   | Display Object List As Tree   Ctrl+Shift+O |  Sort objects into folders / Continuous list
|   | Display All Object Sources    Ctrl+Shift+W |  Show default objects along with modified / Hide
|[X]| Show Object Explorer          Ctrl+Shift+E |  Show pane of object associations / Hide
|   |--------------------------------------------|
|   | Show Table View                     Ctrl+T |  Name-value view of properties pane / GUI view
|[X]| Show Default Values                 Ctrl+E |  Show gray properties / Hide
|[X]| Show Advanced Values          Ctrl+Shift+H |  Show uncommon properties / Hide
|[X]| Show Field Type Names         Ctrl+Shift+F |  No known effect, show it anyway
|[X]| Combine Structure Values      Ctrl+Shift+N |  Sort properties into deep lists / All lists
|   |--------------------------------------------|
|   | Reset Table Column Widths     Ctrl+Shift+R |  Reset width of columns in table view
|   |--------------------------------------------|
|   | Close Tab                     Ctrl+Shift+A |  Close view of current section
|   | Close All Other Tabs      Ctrl+Shift+Alt+A |  Close all nonviewed sections
 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

Tech Tree

SGH uses campaign units by having custom Document Dependencies (File > Dependencies...) with the standard mods added in exact order: Liberty (Mod), Liberty Multi (Mod), Liberty (Campaign).

Train Ability

Campaign units were added to the tech tree by first going to the Abilities section and editing the Train ability of the trainer building (e.g. BarracksTrain is the train ability of the unit Barracks).

  1. With the ability object selected, look at the right pane and click the Ability tab
  2. Under the Ability Commands - Train field, double click a blank e_abilTrainCmdTrain# item
  3. Change Info - Button - Default Button to the proper Train/Warp/Morph button
  4. Change Info - Button - Requirements to the proper tech requirement
  5. Change Info - Time to the proper training time
  6. Change Info - Unit to the proper trained unit

Command Card

Finally, the training building must be modified so players can click a button to train the unit. Go to the Units section and select the training building object (or larva if zerg).

  1. Click the Ability tab to see the command card with unit icons
  2. Click a command card button with no icon and under the Buttons field, click the green +X icon
  3. Choose the Train/Warp/Morph button associated with the unit
  4. With the button added, choose Command Type as Ability Command, choose Ability as THETRAINER - Train, and the Ability Command as Train THEUNIT, then the unit is successfully added to the tech tree

Upgrades

Upgrades must also be updated for the added units to be use them. Go to the Upgrades section and for every upgrade of every level (e.g. TerranInfantryWeaponsLevel1-3):

  1. Look at the right pane and click the Upgrade tab
  2. Add the unit to the CUpgrade_AffectedUnitArray field
  3. Under Upgrade Effects field, duplicate an effect and for Object choose the unit's damage effect and change the Amount's Operation to Add and Value to the proper.
  4. Duplicate the Weapon level icon and Weapon upgrade level number and set them to the proper .dds files and Add value

Wanderer Behavior

In SC1, the AI Script Set Unit Order To: Junk Yard Dog set all units in a region to wander sporadic distances. The closest and most efficient way to replicate this is SC2's CritterWander behavior, though the rate and distance is fixed instead of random as in SC1. To compensate, multiple wander behaviors were duplicated; under the Stats tab, the CBehaviorWanderer_Delay and CBehaviorWander_Range were set respectively to 1.0 and 2, 2.0 and 4, 3.0 and 8, and so on totalling eight behaviors. These behaviors were then referenced in an array so they can be randomly added to masses of units as in dodge games.

Look at the triggers ini_lnkInitializeWandererBehavior, $utl_untAddWandererBehavior, and $dtr_ugrCreateWanderersInRegion for more information.

Touch of Death Behavior

In Dodge the Rapierist, each wanderer was added a TouchOfDeath custom behavior. If the wandering unit touches an enemy unit (the player's dodger), the enemy unit automatically dies. To create this behavior, go to the Effects section and create (Ctrl+=) two helper effects:

  1. [Kill Effect TouchOfDeathEffect] Create a new effect with Effect Type: CEffectDamage
    With the effect selected, look at the right pane and go to Effects tab, look at CEffectDamage_Flags field and checkmark e_damageFlagKill
    Go to the Search tab, scroll down to find the CEffectEnumArea_SearchFilters list and double click e_targetFilterSelf to set it to Excluded. Uncheckmark the Ally and Player boxes.
  2. [Search Effect TouchOfDeathSearch] Create another effect with Effect Type: CEffectEnumArea
    With the effect selected, look at the right pane and go to Search tab, look at CEffectEnumArea_AreaArray field and click the green X icon, a new search area is created; set its Arc field as 360 (kill touching units from all directions) and in Effect field choose the kill effect previously created. Set the Radius field to the desired cell length (suggestion 1).
    Scroll down to find the CEffectEnumArea_SearchFilters list and double click e_targetFilterSelf to set it to Excluded. Uncheckmark the Ally and Player boxes.
  3. [Behavior TouchOfDeath] Create a new behavior with Behavior Type: CBehaviorBuff.
    With the behavior selected, look at the right pane and go to Stats tab, scroll down to find CBehaviorBuff_Period and set it to 0.01 (checks for units near the buffed unit every 0.01 seconds). Go to the Effects tab and under CBehaviorBuff_PeriodicEffect select the search effect previously created.
  4. To add the behavior to a unit in the Data Editor, go to the Units section and select the unit object, then on the right pane go the Behavior tab. Under field CUnit_BehaviorArray click the green X button, change the newly added behavior to the behavior previously created.

To add the behavior dynamically with triggers, use the action Add Behavior (Player). Set the casting player as the owner of the unit or else the search effect will detect it as an enemy and kill it.

Carryable Football Unit

SC1 has powerups, non-controllable item units that are automatically picked up by a touching worker, and dropped if the worker dies. In SC2's Tal'Darim terrazine collection mission, the terrazine canisters act like SC1 powerups, but they are actually resource nodes (like mineral fields) that require manual mining and is destroyed the moment it is mined (though its model still appears on the worker). To replicate the SC1 powerup way, the TerrazineCanister unit data was duplicated (Ctrl+U) along with:

  1. Actor CarryTerrazineNode: Art tab, CActorModel_Model field linked to the modified model (when the worker is carrying it)
  2. Actor TerrazineCanister: Art tab, CActorModel_Model, CActorUnit_BuildModel, CActorUnit_PlacementModel fields automatically linked to the modified model (when it is dropped)
  3. Behavior CarryTerrazineNode automatically linked with its actor
  4. Behavior TerrazineNodeHarvestB: Stats tab, CBehaviorResource_HarvestTime field changed to 0.0 so workers "pick it up" instantly (since it has to be mined)
  5. Model TerrazineCanister: CModel_Name field changed to the football model

Blizzard used triggers to cover these three conditions: worker picks up the powerup, worker dies and drop the powerup, worker brings the powerup home.

Pick Up Powerup

To make the worker automatically pick up (harvest) the powerup when touched, Attach Region To Unit a small region to the powerup unit and use the event Unit Enters Region to fire the action Order Targeting Unit with the ability SCV - Gather.

The worker must be memorized using the trigger action Set Unit Custom Value and recalled using the function Custom Value Of Unit. The set action has the grammar:

Set UNIT custom value INDEX to VALUE

The unit custom value system is an array of reals with index 0-63 that allows any unit to have 64 identifiable values. For this occasion, the index 0 is reserved to "mark" the unit with the arbitrary value 1.0. So when the worker such as an SCV triggers the event Unit Uses Ability with ability SCV - Gather and stage Harvest3 - Harvest, the action is run:

Set (Triggering unit) custom value to 0 to 1.0

Dropping or Returning Powerup

Using the event Unit Dies, check if it is the marked unit using the condition:

Custom value 0 of (Triggering unit) == 1.0

And if so fire the action Create Units Facing Angle to "drop" the powerup where the unit died:

Create 1 POWERUP for player NEUTRAL at (Position of (Triggering unit)) facing (Random angle) degrees (No Options)

For the returning situation, use the event Unit Enters Region and fire any desired actions such as killing the returning worker. The only known way of destroying the powerup actor that the worker is carrying is by having the worker Return Cargo to a resource center.

Alternatively, instead of the unit custom value system, use the action Add Behavior/Remove Behavior and the function Unit Has Behavior with marking behavior Carry Terrazine Node.

Skybox Background

The easiest way to change the map's background is with the trigger action Set Background Model. Note that not all available skybox models are listed in the Data Editor, so duplicate an existing skybox in the Models section and change its CModel_Model field by browse selecting any of the m3 files in the Skyboxes folder. The model BraxisAlphaSkyParallax_Low is a stars-only background model appropriate for space themes.

To change the map's default skybox, go to the Terrain Texture Sets section and view the set that is used by the map. The CTerrain_NonFixedSkyboxModel field is for backgrounds that will move along with the panning game camera, and CTerrain_FixedSkyboxModel is stationary; two backgrounds can be used simultaneously.

Sound and Music

Change the Sound_Set field of a duplicated sound in the Sounds section to add a sound. Add a sound to the CSoundtrack_CueArray field of a duplicated soundtrack in the Soundtracks section to add a soundtrack. Use the trigger actions Play Sound and Play Soundtrack respectively.

Tileset and Texture

Non-matching textures were added to the Bel'Shir Texture Set by viewing it in the Terrain Texture Sets section and removing unused textures from the Terrain_Textures field's Texture Set list and replacing them with other textures from the Texture Library list; the CTerrain_CliffSets array was also modified with additional cliffs. Then by the menu bar Map > Map Textures, each texture button was updated with the replaced textures and cliffs. The map must be reloaded to use the new textures.


Triggers Module

View full list of triggers (March 2011)

To copy triggers: open the Triggers Module (F6), click to view the trigger in the left pane and make sure it does not use global variables (prefixed with a 3-letter abbreviation and a period), if it does, copy the record and record variable first (green disc icon and x= icon) in the left pane and paste them in the other map, then click the trigger (white page icon) or custom action (1s and 0s icon) or function (? icon) or preset (lowercase 'a' icon) and Ctrl+C and paste them in the other map, or copy an entire folder (green folder icon) for completeness.

To find out what custom action or function is being used in the actions list (top right pane), click the action and look at the bottom right pane in white, any entry prefixed with $ is custom. To find out a variable/custom action/function's (a trigger object) associations, click it and press Delete to read the Objects In Use window, then press Cancel; Ctrl+Z to undo accidental deletes.

Conventions and Methodology

  • All variables are prefixed with the abbreviation of their data type for clarity of purpose.
  • Global variables and constants are stored in records (special folders for variables) for organization.
  • Triggers and variables are named with different letter cases depending on their scope and usage for distinction.
  • Local variables are prefixed with "_" and custom actions and functions are prefixed with "$" so they appear on top of the list for accessibility.
  • All triggers are labeled (Right Click a trigger on the left pane > Label > TYPE) for organization.
  • Any folder has a max depth of two subfolder levels for simplicity.
  • Single line comments are used to divide triggers into subsections, and subfolders are only used for homogenous lists of triggers such as level setups.
  • Often used builtin actions/functions are combined into custom actions/functions with fewer parameters for conservation and maintainability.

Names

Type                Format                         Example
Record variables    (record).(type)_(object)       utc.int_maxplayers
Local variables     _(type)_(object)               _int_i
1D/2D Arrays        _(type)[]_(object) or [][]     _poi[]_startlocation
Triggers            (module)_(type)(Verb)(Object)  bgh_melAssignBases
Functions           (module)_(return)(Object)      $utl_reaMinutesToSeconds
 
Parameter and presets in FirstCaps.
Variables in lowercase. Triggers, booleans, and modes in camelCase.

Conditionals

Action              Usage
If Then Else        general condition checking
If Then Else-If     chain of varying conditions
Switch              chain of single-condition cases

Loops

Action              Usage
Pick Each Integer   1-increment iterations for setting variables
For Each Integer    negative or greater than 1 increment iterations
Repeat              multiple same action calls
Repeat Forever      alternative to Periodic Event; used with Wait
While               special conditions iterations

Dialog and Dialog Item

SGH uses dialogs extensively; below is a companion dialog manual for learning and reference.

Dialog Actions

Dialogs are windows for SC2, they can be created and modified using these common actions:

  • Create Dialog - create a dialog of specified size, offset, anchored at a side or corner
  • Set Variable - assuming a global variable was created, set that to the Last Created Dialog
  • Set Dialog Background - dialogs by default have frames colored based on the player's race, use this to change to another texture file that has the word "frame" in the filename
  • Show/Hide Dialog Background - a dialog may act as an invisible corkboard for posting dialog items by hiding its background
  • Show/Hide Dialog - dialogs are hidden for all players when created, use this to show for specific players
  • Set Dialog Fullscreen - expand the dialog so it takes up the whole screen; does not change its size property
  • Set Dialog Item Size to Parent - expand the dialog item so it takes up the whole dialog; does not change its size property
  • Create Dialog Item - create widgets attached to a dialog
  • Destroy Dialog - destroy the dialog and all its dialog items

Dialog Items

Dialog Items are graphical user interface elements to add to dialogs:

  • Achievement - an achievement image, used by Blizzard maps
  • Button - a button that changes its image when hovered
  • Check Box - a 2-state checkbox like an On/Off switch
  • Edit Box - a box for typing strings, a separate enter/confirm button must be created
  • Flash - an Adobe Flash animation or video, used by Blizzard maps
  • Image - an image from a formatted texture, or a tintable blendable layer from a plain texture
  • Label - a colorable stylable text, use custom styles for larger font size
  • List Box - a single column of selectable rows
  • Panel - an invisible container of dialog items
  • Progress Bar - a bar with fullness set by trigger
  • Pulldown - a button that shows selectable options below it
  • Slider - a horizontal scale with a cursor to set real numbers

Any dialog item can be Enable/Disable Dialog Item so players cannot interact with them. Interactive dialog items are functionalized by adding dialog events (Dialog Item Is Used) and actions:

Dialog Item   Event Type          Associated Function                Associated Action
Button        Clicked             Used Dialog Item (Dialog Item)     Set Dialog Item Click On Down
Check Box     Checked             Dialog Item Is Checked (Boolean)   Set Dialog Item Checked
Edit Box      Changed Text        Dialog Item Edit Value (String)    Set Dialog Item Edit Value
List Box      Changed Selection   Selected List Item (Integer)       Select List Item
Pulldown      Changed Selection   Selected List Item (Integer)       Select List Item
Slider        Changed Value       Dialog Item Current Value (Real)   Set Dialog Item Current Value

Dialog Item Actions

Common dialog item actions:

  • Create Dialog Item - create any dialog item attached to a dialog, its properties need to be assigned
  • Set Variable - assuming a global variable was created, set that to the Last Created Dialog Item
  • Set Dialog Item Size - resize the dialog item
  • Move Dialog Item - assign the dialog item new offsets and anchor
  • Destroy Dialog Item - destroy a single dialog item
  • Enable/Disable Dialog Item - turn the dialog item gray or more translucent, interactive ones will not respond to specified player
  • Set Dialog Item Render Priority - set the stack order of dialog items, those assigned with lower priority value will be stacked (appear) in front of others
  • Set Dialog Item Click On Down - the specified Button will fire the Dialog Item Is Used Clicked when pressed (instead of pressed and released)
  • Set Dialog Item Checked - turn the state of a Check Box as checked or unchecked
  • Set Dialog Item Edit Value - set the editable text of an Edit Box
  • Add List Item - add an option to a list-type dialog item (LDI), that is, List Box or Pulldown
  • Remove List Item - remove an option from a LDI
  • Select List Item - makes the player select a list item of a LDI, this will trigger the event Dialog Item Is Used Changed Selection
  • Set Dialog Item Current Value - set the real value of a quantity-type dialog item (QDI), that is, Progress Bar or Slider
  • Set Dialog Item Max/Minimum Value - set the max/minimum value of a QDI, this must be done after creating one

Notes: Dialogs are preferred over panels since there is clear distinction between the two types. Screen Button and Screen Image are Blizzard's specialized dialogs that are always shown to All Players and are not customizable as regular dialog items.

Some dialog item actions can be used by multiple dialog item types, and some are only useable by one:

                    Achiv Buttn Chkbx EdiBx Flash Image Label LisBx Panel PrBar PulDw Slide
Set Dialog Item... |¯¯¯¯¯|¯¯¯¯¯|¯¯¯¯¯|¯¯¯¯¯|¯¯¯¯¯|¯¯¯¯¯|¯¯¯¯¯|¯¯¯¯¯|¯¯¯¯¯|¯¯¯¯¯|¯¯¯¯¯|¯¯¯¯¯|
Achievement        |  X  |     |     |     |     |     |     |     |     |     |     |     |
Blend Mode         |     |     |     |     |     |  X  |     |     |     |     |     |     |
Checked            |     |     |  X  |     |     |     |     |     |     |     |     |     |
Click On Down      |     |  X  |     |     |     |     |     |     |     |     |     |     |
Color              |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |     |  X  |  X  |  X  |
Current Value      |     |     |     |     |     |     |     |     |     |  X  |     |  X  |
Edit Value         |     |     |     |  X  |     |     |     |     |     |     |     |     |
Flash              |     |     |     |     |  X  |     |     |     |     |     |     |     |
Hover Image        |     |  X  |     |     |     |     |     |     |     |     |     |     |
Image              |     |  X  |     |     |     |  X  |     |  X  |     |  X  |  X  |     |
Image Type         |     |  X  |     |     |     |  X  |     |  X  |     |     |  X  |     |
Maximum Value      |     |     |     |     |     |     |     |     |     |  X  |     |  X  |
Minimum Value      |     |     |     |     |     |     |     |     |     |  X  |     |  X  |
Render Priority    |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |
Rotation           |     |     |     |     |     |  X  |     |     |     |     |     |     |
Size               |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |
Size to Parent     |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |  X  |
Style              |     |  X  |     |  X  |     |     |  X  |  X  |     |     |  X  |     |
Text               |     |  X  |     |     |     |     |  X  |     |     |     |     |     |
Text Writeout      |     |     |     |     |     |     |  X  |     |     |     |     |     |
Text Writeout Dura |     |     |     |     |     |     |  X  |     |     |     |     |     |
Tiled              |     |     |     |     |     |  X  |     |     |     |     |     |     |
Tooltip            |     |  X  |  X  |  X  |     |  X  |  X  |  X  |     |  X  |  X  |  X  |
                    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

Notes: Check Box and Slider resizing changes clickable area, their texture does not stretch. Only labels are text-colored by set color, coloring other dialog items will tint their texture. Image rotation only works with Normal image type. Flash only works with Blizzard maps.

Image Dialog Item

The Create Dialog Item (Image) action is a macro action (custom action) that calls various Set Dialog Item... actions taking the numerous parameters. Hover over the underdotted words below for the associated action:

Create an image for dialog (Dialog) with the dimensions (Width, Height) anchored to Anchor with an offset of (Offset X, Offset Y) setting the tooltip to Tooltip using the image Image as a Image Type type with tiled set to Tiled tint color Tint Color and blend mode Blend Mode

Image Type and Textures

UI textures that image dialog items use are divided in slices which SC2 will rearrange according to the image type. Use Set Dialog Item Image Type to format the image after setting its texture, or right when creating it using Create Dialog Item (Image). When browsing for a texture, notice its filename, the keyword frame usually indicate it will work with images and button usually work with buttons. The texture appearance note below tells what a texture file of that type usually looks like:

Type            SizeReq   Texture Appearance    Result Image
Border             Any    top slice is 2 U's    UI-frame or button with background
EndCap             Hor    2|4 vertical slices   Button-frame or button
HorizontalBorder   Any    4 horizontal slices   UI-frame without background
None               None                         Image reset to white32.dds
Normal             Same   single image          Cropped if texture is too large, tiled if too small

Image Blending Effects

Set Dialog Item Blend Mode will make an image dialog item transparent and change its colors (the foreground layer) based on the graphics behind it (the background layer). Read Wikipedia article on blend modes. Below, the White, Black, and Color columns tell what those colors of the texture become:

Mode       White->     Black->     Color         Effect
Add        White       Invisible   Brighter      Add the image's colors to the background
Alpha      Invisible   Invisible   Invisible     Make the image invisible
Darken     Invisible   Black       Darker        Darkest color of the layers is dominant
Lighten    White       Invisible   Near-Opaque   Lightest color of the layers is dominant
Multiply   Invisible   Black       Transparent   Combine the layers' colors becoming darker
Subtract   Black       Invisible   Subtracted    Subtract the image's colors from the background
Normal                                           No blending

Library Triggers

Introduction

The Utility folder contains custom actions and functions reused by multiple games; the documentation below note the more general triggers (which are not in an actual SC2 library file). To use them in another map, copy the Utility Constants record and its reference variable utc first, then copy the desired object or entire trigger subfolder to the target map.

Set Tech Upgrades and Edit Melee Cost

The folder Reset contains triggers and custom actions used at the start and completion of a game, with the general ones allowing for mass revertible setting of tech and editing of catalog data. Read their inline comments for how they work.

  • $res_tecSetTechForPlayer - toggle all melee unit abilities and upgrades to researched/unresearched
  • $res_tecSetUpgradeForPlayer - set a player's weapon/armor/shield upgrade level from 0 to 100
  • $res_catEditMeleeTime - edit by percentage (ebp) the time to build/research specific or all (soa) units/upgrades
  • $res_catEditMeleeResource - ebp the mineral and vespene cost of soa units/upgrades
  • $res_catEditAbilityCost - ebp the energy/cooldown/health cost of soa abilities
  • $res_catEditRepairTime - ebp the time for SCVs to repair soa Terran units

Change Unit Damage and Armor

The builtin action Set Unit Property allows setting a unit's life and current life along with other properties, but Blizzard did not include changing of damage and armor by trigger. In the subfolder Utility\Unit Modification, the custom action $utl_untAddUnitBuff is a workaround by giving a specified unit an amount of damage or armor behavior buffs. Behaviors are data objects added (builtin action Add Behavior (Player)) to units to change their properties or give effects. In this case, multiple "buff" type behaviors were created in the Data Editor such that they can be cumulatively added to a unit for the desired armor or damage amount. Read the trigger ini_lnkInitializeBuffArrays in the folder Main\Initializations for more details.

SC1 Leaderboard with Score Sort

The overall appearance of the standard SC2 leaderboard is not configurable. In recreating the SC1 leaderboard, which is a simple list of player colors and their single score, dialog items were used instead. In the folder Utility\Dialog and Interface, the custom actions under SC1 Leaderboard create and update a single-instance leaderboard. They use a global integer array to store player numbers which are sorted by their scores, then by looping the array, colored squares (image) and points (label) are created downward in the container dialog. Read the inline comments for how the sorting and updating works.

  • $utl_diaInitializeLBSC1 - initialize associated variables, copy the specified player group to a tracker group, and activate the leaving player update trigger
  • $utl_diaRenewLBSC1 - destroy the previous dialog and create a newly sorted one; a separate update trigger to call this custom action must be created based on a desired event, such as when a unit dies
  • utl_diaAutoremovePlayerLBSC1 - automatically removes players from the tracker group and reinitializes the player numbers array when they leave

Custom Alliance Menu

SC2's alliance menu lacks the visioning and un/ally all players features useful in a war game like Phantom. In the game folder Modules\Phantom the custom action and triggers under Alliance Menu overall creates a button over the console (near the Battle.net friends button) that when clicked, provides the same functionality as the standard alliance menu, with confirmation and cancel buttons. Note that the menu was designed with a specific max amount of players, so increase the _int_height variable of the custom action $pha_diaDesignAllianceMenu to accomodate more players.

Dialog Animators

These custom actions use time looped Move Dialog or Set Dialog Size actions to animate dialogs and dialog items. They are organized in the folder Utility\Dialog Animators. For general use, the animators with 2D or Double suffixes allow animations on both axes and has additional parameters.

Dialog Item animators are basically copies of the Dialog animators with dialog item type implementation. The shake and whirl actions always move the dialog back to its original position after animation; in contrast, using slide/morph with the From direction will permanently change the dialog's position/size. Different animators may be called in harmony if their actions are not the same.

        To   From  By   Hori  Vert  Diag   Action
Fade    Yes  Yes   Yes  No    No    No     Transparency
Spin    No   No    No   No    No    No     Rotate
Slide   Yes  Yes   No   Yes   Yes   No     Move
Morph   Yes  Yes   No   Yes   Yes   No     Resize
Shake   Yes  Yes   Yes  Yes   Yes   Yes    Move
Whirl   Yes  Yes   Yes  No    No    No     Move

To   - animate the dialog toward its current position using the specified offsets/size
From - animate the dialog away from its current position using the specified offsets/size
By   - animate the dialog around its current position using the specified distances/radiuses
Horizontal - animate the dialog left and right only
Vertical   - animate the dialog up and down only
Diagonal   - animate the dialog in 2 dimensions

-OffsetX = Left | +OffsetX = Right | -OffsetY = Down | +OffsetY = Up
    -Revolution = Counterclockwise | +Revolution = Clockwise

Dialog animators are primarily used for occasional special effects, such as a new level message with transition animation. They all have a specifiable lasting duration (which determines the animation rate), but it is not exact because of SC2's very slow wait limit between looping actions, and the fact that real numbers used in calculations can only hold 4 decimal digits. Use these animators judiciously and diversely to spice the map with a vibrant feel.

  • $utl_diaFadeDialog - change the transparency by fading in or out
  • $utl_dtmSpinImageDouble - rotate an image dialog item for a specified number of revolutions
  • $utl_diaSlideDialog2D - move a distance over an amount of time
  • $utl_diaMorphDialog2D - shrink or grow over an amount of time
  • $utl_diaShakeDialogDouble - ricochet to random distances around a fixed point
  • $utl_diaWhirlDialogDouble - fly in circle or spiral around a fixed point


Further Development

Creating your own SGH game

Modularity is the mantra of SC1 Greatest Hits, as its purpose is to contain as many classic SC1 maps as allowed by the SC2's limitations. If you are interested in independently developing a game using the SGH meta-map system, first familiarize yourself with the triggers of each game's folder, as triggers themselves being modular represent the vast majority of the map's editing.

Basically, a game needs a partition of terrain space, some regions and points, setup triggers to compartmentalize it, and the mechanics triggers to functionalize it. Follow the trigger layout of the many games in SGH as example in creating your own game. To add and access a game with the virtual lobby system, review the folder Modules\Lobby, notably the triggers under Game Inclusion which simply needs to reference an integer variable representing your game.

For assistance in fork development or questions about the map's methods, inquire the SGH forum.