Skip to main content

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

ElementDescription
<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

AttributeDescriptionValueDefault
idUnique identifier used to reference this action from other places in the XML.String
scopeSets the scope target an action should operate against.player, team, or match
filterA filter that is tested before running actions inside.Filter
exposeAllows 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/falsefalse

Switch-Scope Attributes

AttributeDescriptionValue
idUnique identifier used to reference this switch-scope from other places in the XML.String
innerSpecify the scope of the inner action.player, team, or match
outerSpecify 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

AttributeDescriptionValueDefault
textPropertyThe text that will be sent in the chat to a player.Formatted Text
actionbarPropertyThe text above the hotbar.Formatted Text
titlePropertyThe title text that will appear in the center of the player's screen.Formatted Text
subtitlePropertyThe subtitle text that will appear below the title text.Formatted Text
fade-inHow long the title and subtitle text will fade in.Time Period0.5s
stayHow long the title and subtitle text will display for.Time Period3.5s
fade-outHow long the title and subtitle text will fade out.Time Period1s

Replacements

ElementDescriptionValue
<replacements>A list of replacements.
Note: In the future, more replacements such as player names will be supported.
Replacements Sub-elements
Sub-elementDescription
<decimal/>A numerical placeholder.
Decimal Attributes
AttributeDescriptionValue
idUnique identifier used to reference this decimal from other places in the XML.String
valueRequiredThe variable this decimal should evaluate. It can be used with formulas.Expression
formatCustomize how the decimal should be displayed, e.g. #.00.Java DecimalFormat pattern

Sound Attributes

AttributeDescriptionValueDefault
presetAllows you to reuse a pre-existing sound with predefined volume and pitch.Sounds PresetCUSTOM
keyThe sound type that will be played for a player.Sound Keys
volumeHow loud or quiet a sound should be.Decimal1.0
pitchThe tone of the sound.Decimal1.0

Set Attributes

AttributeDescriptionValue
varRequiredThe variable to update.Variable
indexIf setting an array-type variable, the expression to be evaluated.
Required when using array-type variables.
Expression
valueRequiredSets a new value for the variable.Expression

Kill-Entities Attributes

AttributeDescriptionValue
filterFilters which entities to remove.Filter

Fill Attributes

AttributeDescriptionValueDefault
regionPropertyRequiredThe region to fill in. Multiple regions will be treated as an union.Region
materialRequiredThe filling material.Single Material Pattern
filterFilters which blocks get affected. May impact performance for large fills.Filter
eventsCalls events for block placements and removals, which will make it affected by other filters and PGM features. May impact performance for large fills.true/falsefalse

Paste-Structure Attributes

AttributeDescriptionValue
xThe X coordinate of the location to paste the structure, measured in east-west.Expression
yThe Y coordinate of the location to paste the structure, measured in altitude.Expression
zThe Z coordinate of the location to paste the structure, measured in north-south.Expression
structureThe structure to paste.Structure ID

Replace Item

Sub-elements

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

Attributes

AttributeDescriptionValue
keep-amountPlayer recives the same amount of the new item as they had of the old item.true/false
keep-enchantsEnchantments on the old item will be applied to the new item.true/false
ignore-metadataFilters which entities to remove.true/false
amountMatch for item stacks that have a certain amount of items in a range.Range

Take-Payment

Sub-elements

Sub-elementsDescriptionValue
<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

AttributeDescriptionValue
materialRequiredThe item to display as an icon.Material Name
priceThe amount of a currency needed to purchase.Number
currencyThe currency needed to purchase.Filter

Velocity & Teleport Attributes

AttributeDescriptionValue
xThe X coordinate, measured in east-west.Expression
yThe Y coordinate, measured in altitude.Expression
zThe Z coordinate, measured in north-south.Expression
yawThe horizontal angle a user looks to.Expression
pitchThe 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

AttributeDescriptionValue
filterPropertyA dynamic filter that activates the trigger.Dynamic Filter
actionPropertySets the action to run when the filter allows.Action
scopeSpecify 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>