Variables

Variables are used to store information that can later be used in a filter. Values are changed using the Actions & Triggers mechanic. Afterwards, they can be used as a Filter after meeting a certain number or range. You can define as many variables as you want and all variables must have a scope defined.

Variable Element

Element	Description
`<variables> </variables>`	A node containing the variables for this map.

Sub-elements
`<variable/>`	An individual variable.
`<score/>`	A score variable, allowing direct access to competitor's score. This is automatically scoped to teams.
`<timelimit/>`	A time limit variable which starts/stops the time limit of the match.
`<maxbuildheight/>`	A variable that sets the build height of the map.
`<array/>`	A variable that represents a collection of values.
`<with-team/>`	A team-rescoping variable that allows using a specific team's value from a different team-scoped variable as a match-scoped variable.
`<player-location/>`	A variable that reads a player's location components.

Variable Attributes

Attribute	Description	Value
`id`	Unique identifier used to reference this variable from other places in the XML.	String
`exclusive`	Limits how many different instances there can be for a variable. Values between 1 and 50 are supported, higher values may lead to performance issues.	Number
`scope`	Defines what the variable will be applied to. Variables scoped to a player will give each player a unique value that will be preserved, even if they switch teams.	`player`, `team`, or `match`
`default`	Sets the initial value of the variable.	Number

Array Attributes

Attribute	Description	Value
`id`	Unique identifier used to reference this array-type variable from other places in the XML.	String
`size`	RequiredThe size of this array.	1 - 1024

With-Team Attributes

Attribute	Description	Value
`id`	Unique identifier used to reference this with-team variable from other places in the XML.	String
`var`	The variable to target.	Variable ID
`team`	The team to target.	Team ID

Player-Location Attributes

Attribute	Description	Value
`id`	Unique identifier used to reference this player-location variable from other places in the XML.	String
`component`	The player's location component to target. `XYZ`, `YAW`, and `PITCH` represents the player's position/angle, `DIR_XYZ` represents the player's direction, and `VEL_XYZ` represents the player's velocity.	`X`, `Y`, `Z`, `PITCH`, `YAW`, `DIR_X`, `DIR_Y`, `DIR_Z`, `VEL_X`, `VEL_Y`, and `VEL_Z`

Examples

Setting Variables

Setting variables are done inside the Actions & Triggers mechanic. The <set> action which changes the variables, waits to be called by a trigger after a filter activates it. The value attribute can do any basic mathematical expressions.

Example

<actions>
    <action id="increment-flag-cap" scope="team">
        <!-- increments the current value by 1 -->
        <set var="flag_captures" value="flag_captures+1">
    </action>
    <trigger filter="flag-cap-filter" action="score-points" scope="player"/>
</action>

...
<!-- Sets some_variable to 0, 1, 2, 3, or 4 randomly -->
<set var="some_variable" value="floor(random() * 5)"/>
...

In this example, the flag_captures variable will increment by 1 after a player completes flag-cap-filter.

Using a Variable In a Filter

The variable can then be used in the Variable Filter to be utilized in another Action or other module that uses filters. The variable filter can match for a single number or a range of numbers.

Example

<!-- Match if next_post has a value of 1 -->
<variable id="next_blue" var="next_post">1</variable>
<!-- Match if t_score is >= 100 -->
<variable id="reached_score" var="t_score">[100,oo)</variable>

<!-- Match if t_score is between 5 and 10 (including 5 and 10) -->
<variable id="reached_score" var="t_score">[5,10]</variable>
<!-- Match if t_score is between 5 and 10 (excluding 5 and 10) -->
<variable id="reached_score" var="t_score">(5,10)</variable>
<!-- Match if t_score is between 0 and 10 (including 0 and excluding 10) -->
<variable id="reached_score" var="t_score">[0,10)</variable>

Using Exclusive Dummy Variables

In this example, the last_scored variable would, at most, have a value for one team. This in practice means that all other teams will always be reset to default whenever a team is set. In the other example, the "last 2" updated players will be kept, while players who got in "earlier", are removed.

<variables>
    <variable id="last_scored" exclusive="1" scope="team" />
    <variable id="other" exclusive="2" scope="player" />
</variables>

In this example, we want the team which gets the on-score action to add one, but the opposite team(s) to subtract one from their score, with exclusive it looks like this:

<variables>
    <score id="team_score" scope="team"/>
    <variable id="last_scored" exclusive="1" scope="team"/>
</variables>
<actions>
    <action id="on-score" scope="team">
        <set var="team_score" value="team_score+1"/>
        <set var="last_scored" value="1"/>
        <switch-scope inner="match">
            <switch-scope inner="team" filter="last_scored=0">
                <set var="team_score" value="team_score-1"/>
            </switch-scope>
        </switch-scope>
    </action>
</actions>

Timelimit Variables

When the time limit variable is given a value, it will start a timelimit for the match. The time limit can be cancelled by setting the value to a negative number, or the match can be ended by setting the value to 0.

<variables>
    <timelimit id="tl_1"/>
</variables>
<actions>
    <action id="on-score" scope="team">
        <switch-scope inner="match">
            <!-- Sets/starts the timelimit to 60 seconds -->
            <set var="tl_1" value="60"/>
        </switch-scope>
    </action>
    <action id="on-capture" scope="team">
        <switch-scope inner="match">
            <!-- Instantly ends the match -->
            <set var="tl_1" value="0"/>
        </switch-scope>
    </action>
    <action id="on-overtime" scope="team">
        <switch-scope inner="match">
            <!-- Removes the timelimit -->
            <set var="tl_1" value="-10"/>
        </switch-scope>
    </action>
</actions>

Maxbuildheight Variable

The maxbuildheight variable will give a height limit for placing blocks after being set to a certain value.

<variables>
    <maxbuildheight id="build-limit"/>
</variable>
<actions>
    <action id="increase-buildheight" scope="match" expose="true">
        <!-- Adds 1 to the current height, up to a maximum of 55 -->
        <set var="build-limit" value="min(55,whatever+1"/>
    </action>
</actions>

Team-Rescoping Variables

Whenever some-filter matches for a player (e.g. entering a region), it will trigger an action that sets red team's score to exactly 10, then adds 5 to the score of the team the player is in. In short, if a player in red team triggers some-filter, red is reset to 10 + 5 = 15, no other scores are affected. If a player in blue team triggers some-filter, red is reset to 10, and blue wins 5 points.

<variables>
    <score id="team_score"/>
    <with-team id="red_team_score" var="team_score" team="red"/>

    <variable id="other" scope="team"/> <!-- A dummy team variable -->
    <!-- A match-scoped variable for the value of other for red team -->
    <with-team id="other_red" var="other" team="red"/>
    <!-- A match-scoped variable for the value of other for blue team -->
    <with-team id="other_blue" var="other" team="blue"/>
</variables>

<actions>
    <trigger scope="player" filter="some-filter">
        <action>
            <set var="red_team_score" value="10"/>
            <set var="team_score" value="team_score+5"/>
        <action>
    </trigger>
</actions>

General Example

In this example, when a player first enters region-a, the team score and later the player score is increased by 5. The second time the same player enters, the team will score an additional 10 points, with the player score continuing to increment by 5. Once the team gets 100 points or higher, a message indicating this will be sent.

<variables>
    <!-- Initializes the variables -->
    <variable id="team_score" scope="team"/>
    <variable id="player_score" scope="player" default="5"/>
</variables>
<actions>
    <action id="score-points" scope="player"/>
        <!-- team_score = team_score + player_score -->
        <!-- Adds the player's score to the team score -->
        <set var="team_score" value="team_score+player_score"/>
        <!-- Adds 5 points to the player's score -->
        <set var="player_score" value="player_score+5"/>
    </action>
    <!-- Triggers the above score-points action when a player enters region-a -->
    <trigger filter="region-a" action="score-points" scope="player"/>
    <!-- Sends a message to the team once the filter reached-score passes Allow -->
    <trigger filter="reached-score" action="completed" scope="team"/>
    <message id="completed" text="The team reached 100 points!"/>
</action>
<filters>
    <!-- Allows when the t_score variable is greater than or equal to 100 -->
    <variable id="reached-score" var="t_score">[100,oo)</variable>
</filters>

Variable Element​

Variable Attributes​

Array Attributes​

With-Team Attributes​

Player-Location Attributes​

Examples​

Setting Variables​

Using a Variable In a Filter​

Using Exclusive Dummy Variables​

Timelimit Variables​

Maxbuildheight Variable​

Team-Rescoping Variables​

General Example​