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.
`<repeat> </repeat>`	Loop actions without recursions.
`<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.
`<schedule> </schedule>`	Adds a delay between actions.
`<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.
`<open-shop/>`	Open a shop menu when triggered.
`<replace-item> </replace-item>`	Finds and replaces certain items.
`<enchant-item> </enchant-item>`	Enchants the targeted item.
`<take-payment> </take-payment>`	Allow players to pay with items in their inventory to trigger an action.
`<team-alias/>`	Dynamically change a team's name during a match.
`<velocity/>`	A player-scoped kit that applies velocity to the player.
`<teleport/>`	Teleport a player to a specific location.
`<weather/>`	The weather to set for the map's environment.

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
`untrigger-filter`	A filter that is tested before deactivating the actions inside, similar to kit lending. Most actions do not have explicit untrigger logic and will do nothing on untrigger.	Filter	`never`
`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	Default
`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`
`observers`	Toggle if non-participant players should be included in the scope. Note: This is only relevant when `inner` scope is `player`.	true/false	false

Repeat Attributes

Attribute	Description	Value
`times`	The amount of time to repeat. Non-whole numbers will be rounded down. Negative numbers will cause no iterations.	Expression
`filter`	Filters when this loop should be active. This will be checked as many time as the loop is ran.	Filter

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

Sub-elements

Sub-element	Description	Value
`<replacements>`	A list of replacements. They can be referred to in the message text using curly braces (`{replacement-id}`).	Replacements

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

Alternative Inline Syntax: Variable assignments can be written using the := operator as variable_name := value or variable_name[index] := value for array variables.

<trigger filter="some-condition" action="player_score := player_score + 10" scope="player"/>

Schedule Attributes

Attribute	Description	Value
`after`	The time, in seconds, to wait before triggering an action. Note: The value must be between 0 and 60.	Number

<action id="schedule-action-example" scope="match">
    <!-- No delay -->
    <message text="Message one"/>
    <sound preset="alert" volume="0.75" pitch="1.5"/>
    <!-- Two seconds delay -->
    <schedule after="2s">
        <message text="Message two"/>
        <sound preset="alert" volume="0.75" pitch="1.5"/>
    </schedule>
    <!-- Five seconds delay -->
    <schedule after="5s">
        <message text="Message three"/>
        <sound preset="alert" volume="0.75" pitch="1.5"/>
    </schedule>
</action>

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
`update`	Placed blocks will update upon interaction, e.g., redstone, and invalid block placements such as floating ladders, "popping" off. May impact performance for large fills.	true/false	true

Paste-Structure Attributes

Attribute	Description	Value	Default
`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
`update`	Placed blocks will update upon interaction, e.g., redstone, and invalid block placements such as floating ladders, "popping" off. May impact performance for large fills.	true/false	true

Open-Shop Attributes

Attribute	Description	Value
`shop`	The individual shop to open.	Shop 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`	Ignore the metadata of the item when matching.	true/false
`amount`	Match for item stacks that have a certain amount of items in a range.	Range

Enchant-Item Attributes

Attribute	Description	Value
`enchantment`	An item enchantment.	Enchantment Name
`level`	The specified enchantment's level.	Expression
`ignore-metadata`	Ignore the metadata of the item when matching.	true/false

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

Team-Alias Attributes

Attribute	Description	Value
`team`	The team for the action to rename. Note: This is required if the action's scope is `match`; otherwise, the team will be assumed.	Team ID
`alias`	The new team's name.	String

Velocity & Teleport Attributes

Attribute	Description	Value
`region`	The destination region to teleport the user to. This is available only for teleport action.	Region
`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

Weather Attributes

Attribute	Description	Value
`state`	The weather type to transition into.	`clear`, `rain`, `thunder`

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	Default
`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`
`observers`	Toggle if non-participant players can activate this trigger. Note: This is only relevant when `scope` is `player`.	true/false	false

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>

Replacements

Replacement Types

Type	Description
`<decimal/>`	ScopedA numerical placeholder.
`<player/>`	A player's name placeholder.
`<switch>`	ScopedA switch-case replacement.
`<replacement>`	A reference to a replacement in the global registry.

Global Replacement Registry

Replacements can be defined globally by including them in <replacements> in the root <map> element. In that case, defining a scope for scoped replacements is required:

<map proto="1.5.1">
<replacements>
    <decimal id="example-decimal" value="points" scope="player"/>
    <switch id="example-switch" scope="team">
        <case filter="team-a" result="`9Team A"/>
        <case filter="team-b" result="`cTeam B"/>
    </switch>
</replacements>
</map>

Globally defined replacements can be accessed in message actions using the <replacement> element.

Decimal Replacement

Displays a numerical value according to the provided format.

Attributes

Attribute	Description	Value
`id`	Unique identifier used to reference this decimal placeholder 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

Player Replacement

Displays the name of a player who has an exclusive player-scoped variable assigned to them.

Attributes

Attribute	Description	Value	Default
`id`	RequiredUnique identifier used to reference this player placeholder from other places in the XML.	String
`var`	RequiredThe exclusive player-scoped variable to check for.	Variable
`style`	The style to display the player's name in.	Player Replacement Style	`verbose`
`fallback`	If no player has been assigned this variable, set the text to display instead.	String

Player Replacement Styles

Type	Description	Example	Example (server operator view)
`plain`	Displays the player name without any formatting.	username	username
`simple_color`	Displays the player name with team color formatting. Using this style is discouraged.	username	username
`color`	Displays the player name with team color, and a click-to-teleport action. Recommended for chat messages.	username	username
`fancy`	Displays the player name with team color, a click-to-teleport action, flairs (prefix, suffix, etc.), and fancy formatting.	*username	*username
`tab`	Displays the player name formatted as a tab list entry with team color, flairs, death status, self-highlighting, etc. Using this style is discouraged.	*username	*username
`verbose`	Displays the player name in a manner similar to `fancy`, along with an alternative nickname (if present) to server operators and friends of the player.	*username	*username nickname

Switch Replacement

Selects the first matching value from a list of candidate case branches.

<switch id="player-health-state" value="player.health">
    <case match="(0, 5]" result="`cAlmost dead"/>
    <case match="5..10" result="`eUnwell"/>
    <case match="10..15" result="`6Not great, not terrible"/>
    <case match="[15, 20)" result="`4OK"/>
    <case match="20" filter="blue-team" result="`aHealthy `9blue`a player"/>
    <case match="20" filter="red-team" result="`aHealthy `9red`a player"/>
</switch>

Attributes

Attribute	Description	Type
`id`	RequiredUnique identifier used to reference this switch replacement from other places in the XML.	String
`value`	PropertyAn optional value to match against in individual switch cases. Formulas are supported.	Expression

Sub-elements

Sub-element	Description	Type
`<case>`	Case branches to match against.	Case Branch
`<fallback>`	The fallback text to display if none of the `<case>` branches match. Defaults to empty text.	Formatted Text

Case Branch Properties

A case branch describes the requirements for the text to be displayed. At least one of the match and filter properties must be specified. If both are specified, the filter acts as a "case guard" – meaning that the case branch will match only if the value matches the range specified by match and the filter allows.

Property	Description	Type
`match`	PropertyThe value to match against.	Number Range
`filter`	PropertyThe filter to match against. Requiredif `value` is not specified in the parent `<switch>` element.	Filter
`result`	PropertyRequiredThe text to display when matched.	Formatted Text

Replacement Reference

Refers to a replacement in the global registry. Takes in an id attribute, which serves as the local identifier of the replacement to be used in message text, and the global replacement ID as an inner value.

<message text="{local-id}">
    <replacements>
        <replacement id="local-id">global-id</replacements>
    </replacements>
</message>

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>

Action Elements​

Action Attributes​

Switch-Scope Attributes​

Repeat Attributes​

Message​

Attributes​

Sub-elements​

Sound Attributes​

Set Attributes​

Schedule Attributes​

Kill-Entities Attributes​

Fill Attributes​

Paste-Structure Attributes​

Open-Shop Attributes​

Replace-Item​

Sub-elements​

Attributes​

Enchant-Item Attributes​

Take-Payment​

Sub-elements​

Attributes​

Team-Alias Attributes​

Velocity & Teleport Attributes​

Weather Attributes​

Trigger Element​

Trigger Attributes​

Replacements​

Replacement Types​

Global Replacement Registry​

Decimal Replacement​

Attributes​

Player Replacement​

Attributes​

Player Replacement Styles​

Switch Replacement​

Attributes​

Sub-elements​

Case Branch Properties​

Replacement Reference​

Examples​

Enabling Blitz Mode​

Action Elements

Action Attributes

Switch-Scope Attributes

Repeat Attributes

Message

Attributes

Sub-elements

Sound Attributes

Set Attributes

Schedule Attributes

Kill-Entities Attributes

Fill Attributes

Paste-Structure Attributes

Open-Shop Attributes

Replace-Item

Sub-elements

Attributes

Enchant-Item Attributes

Take-Payment

Sub-elements

Attributes

Team-Alias Attributes

Velocity & Teleport Attributes

Weather Attributes

Trigger Element

Trigger Attributes

Replacements

Replacement Types

Global Replacement Registry

Decimal Replacement

Attributes

Player Replacement

Attributes

Player Replacement Styles

Switch Replacement

Attributes

Sub-elements

Case Branch Properties

Replacement Reference

Examples

Enabling Blitz Mode