Actions & Triggers

Actions are a set of features that are applied to players, teams, or matches, similiar to Kits. Multiple actions can be started by one trigger.

info

In the future, some features that are currently used in Kits may be transferred to be used as an Action instead.

Action Elements

Element	Description
<action> </action>	A group of actions running in a sequence.
<switch-scope> </switch-scope>	Changes the scope that an action applies to.
<message/>	A message that is sent to the player.
<sound/>	A sound that is played for the player.
<set/>	Sets a new value for a Variable.
<kill-entities/>	Removes entities based on a filter.
<kit/>	Applies a Kit.
<fill/>	Places blocks in a block-bounded region.
<paste-structure/>	Places a structure at a specified location when triggered.
<replace-item> </replace-item>	Finds and replaces certain items.
<take-payment> </take-payment>	Allow players to pay with items in their inventory to trigger an action.
<velocity/>	A player-scoped kit that applies velocity to the player.
<teleport/>	Teleport a player to a specific location.

Action Attributes

Attribute	Description	Value	Default
id	Unique identifier used to reference this action from other places in the XML.	String
scope	Sets the scope target an action should operate against.	player, team, or match
filter	A filter that is tested before running actions inside.	Filter
expose	Allows an action to be triggered by /action. Actions must have an ID and support the match scope for expose to work. Moderators require the GAMEPLAY permission to use the action command.	true/false	false

Switch-Scope Attributes

Attribute	Description	Value
id	Unique identifier used to reference this switch-scope from other places in the XML.	String
inner	Specify the scope of the inner action.	player, team, or match
outer	Specify the scope outside of an action. In some cases, this can be omitted as PGM will automatically infer the outer scope.	player, team, or match

Message Attributes

Attribute	Description	Value	Default
text	PropertyThe text that will be sent in the chat to a player.	Formatted Text
actionbar	PropertyThe text above the hotbar.	Formatted Text
title	PropertyThe title text that will appear in the center of the player's screen.	Formatted Text
subtitle	PropertyThe subtitle text that will appear below the title text.	Formatted Text
fade-in	How long the title and subtitle text will fade in.	Time Period	0.5s
stay	How long the title and subtitle text will display for.	Time Period	3.5s
fade-out	How long the title and subtitle text will fade out.	Time Period	1s

Replacements

Element	Description	Value
<replacements>	A list of replacements. Note: In the future, more replacements such as player names will be supported.	Replacements Sub-elements

Sub-element	Description
<decimal/>	A numerical placeholder.

Decimal Attributes

Attribute	Description	Value
id	Unique identifier used to reference this decimal from other places in the XML.	String
value	RequiredThe variable this decimal should evaluate. It can be used with formulas.	Expression
format	Customize how the decimal should be displayed, e.g. #.00.	Java DecimalFormat pattern

Sound Attributes

Attribute	Description	Value	Default
preset	Allows you to reuse a pre-existing sound with predefined volume and pitch.	Sounds Preset	CUSTOM
key	The sound type that will be played for a player.	Sound Keys
volume	How loud or quiet a sound should be.	Decimal	1.0
pitch	The tone of the sound.	Decimal	1.0

Set Attributes

Attribute	Description	Value
var	RequiredThe variable to update.	Variable
index	If setting an array-type variable, the expression to be evaluated. Required when using array-type variables.	Expression
value	RequiredSets a new value for the variable.	Expression

Kill-Entities Attributes

Attribute	Description	Value
filter	Filters which entities to remove.	Filter

Fill Attributes

Attribute	Description	Value	Default
region	PropertyRequiredThe region to fill in. Multiple regions will be treated as an union.	Region
material	RequiredThe filling material.	Single Material Pattern
filter	Filters which blocks get affected. May impact performance for large fills.	Filter
events	Calls events for block placements and removals, which will make it affected by other filters and PGM features. May impact performance for large fills.	true/false	false

Paste-Structure Attributes

Attribute	Description	Value
x	The X coordinate of the location to paste the structure, measured in east-west.	Expression
y	The Y coordinate of the location to paste the structure, measured in altitude.	Expression
z	The Z coordinate of the location to paste the structure, measured in north-south.	Expression
structure	The structure to paste.	Structure ID

Replace Item

Sub-elements

Sub-elements	Description	Value
<find/>	The item to find in a player's inventory.	Item Attributes
<replace/>	The new item to replace with.	Item Attributes

Attributes

Attribute	Description	Value
keep-amount	Player recives the same amount of the new item as they had of the old item.	true/false
keep-enchants	Enchantments on the old item will be applied to the new item.	true/false
ignore-metadata	Filters which entities to remove.	true/false
amount	Match for item stacks that have a certain amount of items in a range.	Range

Take-Payment

Sub-elements

Sub-elements	Description	Value
<payment/>	PropertyRequiredAn individual payment.	Item Attributes
<success-action/>	PropertyThe action to trigger upon a successful payment.	Action
<fail-action/>	PropertyThe action to trigger upon a failed payment.	Action

Attributes

Attribute	Description	Value
material	RequiredThe item to display as an icon.	Material Name
price	The amount of a currency needed to purchase.	Number
currency	The currency needed to purchase.	Filter

Velocity & Teleport Attributes

Attribute	Description	Value
x	The X coordinate, measured in east-west.	Expression
y	The Y coordinate, measured in altitude.	Expression
z	The Z coordinate, measured in north-south.	Expression
yaw	The horizontal angle a user looks to.	Expression
pitch	The vertical angle a user looks to.	Expression

Trigger Element

The trigger element waits for a dynamic filter to activate it, and afterwards it will trigger an action.

Trigger Attributes

Attribute	Description	Value
filter	PropertyA dynamic filter that activates the trigger.	Dynamic Filter
action	PropertySets the action to run when the filter allows.	Action
scope	Specify the scope for which to test the filter.	player, team, or match

Example

<kits>
    <kit id="spawn">
        <item slot="0" unbreakable="true" material="stone sword"/>
        <action>
            <message text="You were given a kit!"/>
        </action>
    </kit>
</kits>
<actions>
    <action id="do-stuff" scope="player">
        <!-- Gives the player who activated the trigger a diamond -->
        <message text="You've been given a diamond!"/>
        <kit>
            <item material="diamond"/>
        </kit>
        <!-- Sends a message to the player's team -->
        <switch-scope outer="player" inner="team">
            <message text="Your team has been given the spawn kit!"/>
            <!-- Gives each player in the team a kit (Kits are applied per player) -->
            <switch-scope outer="team" inner="player">
                <kit id="spawn"/>
            </switch-scope>
        </switch-scope>
    </action>
    <trigger filter="some-dynamic-filter" action="do-stuff" scope="player"/>
    <message id="standalone-text" text="This is a standalone text trigger"/>
    <trigger filter="another-dynamic-filter" action="standalone-text" scope="player"/>
</actions>

Examples

Enabling Blitz Mode

This example uses the expose attribute in Action to allow moderators to enable a "Blitz Mode" using the /action command. Moderators must have the GAMEPLAY permissions in order to use /action. See Commands for more details.

<actions>
    <!-- Moderator uses "/action trigger start-blitz" to start this Action -->
    <action id="start-blitz" expose="true" scope="match">
        <!-- Sends notification to chat -->
        <message text="Blitz mode has been enabled!"/>
        <!-- Sets blitz_enabled to 1 -->
        <set var="blitz_enabled" value="1"/>
    </action>

    <!-- Moderator uses "/action trigger end-blitz" to start this Action -->
    <action id="end-blitz" expose="true" scope="match">
        <message text="Blitz mode has been disabled!"/>
        <set var="blitz_enabled" value="0"/>
    </action>
</actions>
<!-- Creates the blitz_enabled variable -->
<variables>
    <variable id="blitz_enabled" scope="match"/>
</variables>
<blitz>
  <!-- Matches for a condition where a player loses a life -->
  <filter>
      <!-- If a player dies when blitz_enabled is 1, they lose a life -->
      <variable var="blitz_enabled">1</variable>
  </filter>
</blitz>