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.
<replace-item> </replace-item>Finds and replaces certain items.

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

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
valueRequiredSets a new value for the variable.String

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 preformace for large fills.Filter
eventsCalls events for block placements and removals, which will make it affected by other filters and PGM features. May impact preformace for large fills.true/falsefalse

Replace Item Attributes/Elements

AttributeDescriptionValue
<find />The item to find.Item Attributes
<replace/>The new item to replace with.Item Attributes
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

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>