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. |
<replace-item> </replace-item> | Finds and replaces certain items. |
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 |
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 |
value | RequiredSets a new value for the variable. | String |
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 preformace 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 preformace for large fills. | true/false | false |
Replace Item Attributes/Elements
Attribute | Description | Value |
---|---|---|
<find /> | The item to find. | Item Attributes |
<replace/> | The new item to replace with. | Item Attributes |
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 |
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>