Triggers/Variables And Records

From SC2Mapster Wiki
Jump to: navigation, search

If you want to create an action or function page, use this Template. If you want to create a new trigger category page, use this Template.

Trigger Elements

Ui-editoricon-general triggers.png Trigger Editor Overview Ui-editoricon-triggereditor newevent.png Events
Ui-editoricon-triggereditor newcondition.png Conditions Question.png Functions
Ui-editoricon-triggereditor newvariable.png Variables And Records Ui-editoricon-triggereditor newvariable.png Data Types
Ui-editoricon-triggereditor newpresettype.png Presets/Constants Ui-editoricon-triggereditor newaction.png Actions

Variables And Records

General

About Variable Types

Every variable must be assigned a Type. A variable may only store information appropriate for it's type. In other words, integer variables can only store Integers, and unit variables can only store Units.

Types Unique To Variables

Variables have two types that are unique.

  • - Preset: Uses a Preset enabling selected presets to be swapped as needed.
  • - Record: Enables interfacing with the variables stored in the specified Record.

Fields Description

Type

  • The Type of data stored by the variable
  • Some types have up to two additional fields enabling further specification as to what data can be stored in the variable
Sub Type List
  • Preset: Used by - Preset type variables to specify which Preset to use. Limits what preset values can be substituted.
  • Record: Used by - Record type variables to specify which Record to interface with
  • Link Type: Used by - Game Link type variables to specify what data type from the Data Editor to store information from
  • Entry Type: Used by - Game Link type variables to further specify what types within the data type used by the Link Type can be stored
  • File Type: Used by - File type variables to determine what file types can be stored (restricted range of file types supported)
    • Cutscene: Specifies storage of .SC2Cutscene format files
    • Facial Animation: Specifies storage of .fxa format files
    • Flash Animation: Specifies storage of .swf format files
    • Font Style: Specifies storage of .SC2Style format files
    • Image: Specifies storage of .dds and .tga format files
    • Layout: Specifies storage of .SC2Layout format files
    • Model: Specifies storage of .m3 and .m3a format files
    • Model Animation: Specifies storage of .m3a format files
    • Model Synchronous Data: Specifies storage of .m3h format files
    • Movie: Specifies storage of .ogv format files
    • Scene: Specifies storage of (Unknown) format files
    • Sound: Specifies storage of .ogg and .wav format files
  • Target Type: Used by Ability Command type variables to restrict what kinds of ability command can be stored
    • Any Target: Only can store ability commands that require a target
    • No Target: Only can store ability commands that do not require targets
    • Point: Only can store ability commands that target points
    • Unit: Only can store ability commands that target units
  • Type (Param): Used by Catalog Entry type variables (Unknown)
  • Scope (Param): Used by Catalog Field Name type variables (Unknown)
  • Type (Param): Used by Catalog Field Path type variables (Unknown)
  • Reference Type: Used by Catalog Reference type variables
    • Numeric Only: (Unknown)
    • Upgrade Only: (Unknown)
  • Option (Param): Used by Game Option Value type variables (Unknown)
  • Unit (Param): Used by Model Camera type variables (Unknown)
  • Entry Type: Used by Unit Type type variables (Unknown)
  • User (Param): Used by User Data Field and User Data Instance type variables (Unknown)
  • User Type: Used by User Data Field and User Data Instance type variables (Unknown)

Constant

  • (Unknown) If enabled prevents changing the variable from the initial/default value?
  • Cannot be enabled if the Array flag is enabled and vice versa

Array

  • Allows a variable to store multiple indexed values of the same type
Dimensions
  • How many dimensions the array has.
    • For example a single dimension array with a size of 4 can store 4 values while an array with 4 dimensions and a size of 4 can store 16 values.
    • Most commonly used for storing associated values along each index value eg. unit numbers of each category owned by player number
  • Maximum of 4 dimensions allowed
Size
  • Number of values able to be stored in the variable array
  • Maximum of 8192 values per dimension
    • Value: Numeric number for the size of the array
    • Constant: Integer type variable with the Constant flag enabled used to determine the array size

Defines Default Value

  • Makes all variables of the same type as this variable created after the flag is enabled inherit the default/initial value of this variable
  • Multiple variables of the same type can have this flag enabled at once but only the variable with the most recently enabled flag is used for the default/initial values

Initial Value

  • The default/initial value this variable starts with before being modified by other trigger actions
  • Only accepts a single value so different array indexes cannot be given different default values. Use Preset type variables if multiple default values are required or have a list of Set Variable trigger actions on game initialization.

Using And Modifying Variables

  • Variables are used to store information that is situation dependent or needs to be utilised by multiple different triggers such as the number of ticks occurred for a timer, the individual units in a unit group, the distance between two locations or specific buttons created in a dialog. The values stored in variables can then be used to define the Parameters of Events, Conditions, Functions or Actions. Having default/initial values for variables is only necessary if triggers that utilise the variable for parameters can occur before triggers that set values for the variable. Variables of the Integer and Real types can have their numeric values directly modified using Math functions while other types need to be set using the return of a function or values of a preset or another variable. The trigger actions used to change variable values are all found under the Variable category.

Variables (Local)

Local Variables are a sub-element created within Triggers and Definitions that store information for a single execution of the element. Local variables are deleted when the script thread finishes running and are created and linked in parallel for each thread created meaning multiple copies of the same variable with different stored values can exist at a given time. This has advantages if executing the same trigger multiple times on multiple targets transiently (eg. displaying damage taken on a cluster of units hit several times by a multicastable area of effect ability with damage over time) or if the stored values become no longer needed. Having the correct Type of local variable in the trigger is required for some Functions and Actions to appear as options.

Variables (Global)

Global variables are elements that store information able to be modified and accessed across different Triggers and Definitions and are preserved after the modifying thread finishes execution. Only a single copy of the global variable will exist at any given time irrespective of the number of threads that are using it at once. This means the stored value will be that of the most recent modification and will be used by all threads even if a thread assigned a different value previously while being executed. Use these for stuff used for multiple triggers or threads and for values that will have long periods between being used eg. dialog buttons and objective progression states.

Records

Records are elements that can hold an array of Global Variables and unlike the arrays of individual variables that are limited to 4 dimensions of the same type, Records can have up to (Unknown) dimensions of different Types. To modify and access values stored on a record requires a variable (global or local) outside of the record set to the - Record type specifying the individual record under the Record field. In the GUI the variable held within the record appears after the - Record variable name separated by a period. Commonly used for convenience when loading and saving with Banks or when the variable size index values represent the same object.

Example Usage

PC_DebugProgressAddMissionButton

An Action Definition found under the Progress file of the Campaign (Void) trigger library responsible for creating the dialog UI associated with using the PROGRESS debug cheat code. The Integer type local variables are used to convert the simple column and row number values defined by the parameters of triggers using this action definition into the pixel numbers used by dialogs and to specify size and border constants for dialog items placed in the dialog. the values stored in these variables are then used to create, position and size the associated dialog items. In this instance the created dialog items are stored using a Save Data Table Value (Dialog Item) action however the buttons could equally be stored using Dialog Item variables. Similar systems linked to a For Each integer actions can be used for the automated assemble of clickable elements for UIs.

PC_PrepareLoadingScreen

An Action Definition found under the Transition file of the Campaign (Void) trigger library responsible for setting up the loading screen text position between missions during the LOTV campaign. Using the OffsetString local variable the game link values of the Loading Screen Text Offset field from the Maps data type for the next map are converted into a string and stored. After a search based modification the string is then converted into integers and the X/Y values stored under two separate local variables called OffsetX and OffsetY which are then modified with a constant before being used to determine the coordinates used by a [[Triggers/Set Next Loading Screen Text Position|Set Next Loading Screen Text Position action. Local variables are used in this situation because the coordinates are no longer relevant after the loading screen has showed.

Tick Value

A global variable array of the Real type found in the Lock & Load co-op map that has a value assigned to it by the Init 08 Difficulties trigger with an increasing numeric value assigned with increasing index, a value associated with the numbers of locks owned by the opponent. The values of this variable are then used by the Tick Counter trigger to periodically add a value based on how many locks the opponent controls onto the value of the Current Ticks global variable which is used by the Defeat Primary Objective Failed trigger for one of the loss conditions for the map.