Map commands to game events using a simple config

Event Command

Triggers commands based on events.


Put all scripts into the config/eventcommand folder. Scripts have to end with the extension .ec (Save as any file *.* if your system is hiding file extensions).

You can have any amount of files in that folder.

Lines that start with -- are ignored. Indentation throughout the file has to be consistently either tabs or spaces. The whole script (with exception to event names and mappers) is case-insensitive, although it is recommended to use consistent case for readability.

There are 4 types of statements: Triggers, ‘with’-chains, mathematics and filters/actions. ‘With’-chains are optional, as are mathematics. If you want to do any mathematics, they have to be after ‘with’-chains.


Listen to an event with @ Event. The event has to be the fully qualified name. For example$Join You can look up all sponge events on but note that dots in class names (nested classes) have to be replaced with dollar signs (ClientConnectionEvent.Join -> ClientConnectionEvent$Join).


Following the listener declaration you can extract information from the event using ‘with’-chains. The syntax is with NAME as MAPPERS where NAME is any label (without spaces). MAPPERS is a chain of one or more elements from this list:

  • &classname searches the cause stack for the first occurance of this type. Requires a fully qualified name, like event class names.
  • #key tries to get a Key value from the ValueContainer. Supports field names of Keys. For other Keys you have to use the Key’s id.
  • numbers to index into arrays, Lists or Iterables
  • method names to get values. Methods may not be static or void return.

The following variables are available by default but can be overwritten on event basis:

  • GAME contains Sponge.getGame()
  • SERVER contains Sponge.getServer()


All calculations are done as double. The syntax for it is let NAME be MATH EXPRESSION. If you don’t like to use the keyword be you can also use a simple = or :=. The MATH EXPRESSION supports variables in the ${NAME} format. Multiplication, division, addition, subtraction, powers(^), modulo(%) and grouping(()) are supported.


If you don’t want an action to run every time, you can filter them as well. The syntax is:

  actions/nested filters
  actions/nested filters

The otherwise block is optional, but cannot be the only block. Actions blocks are grouped by indentation, this means that every case (you can have more than one for block) has to be written on the same indentation level, and all actions have to be placed deeper. Every condition can specify an arbitrary amount of CONDITIONS, but the otherwise block has to go without.


On Strings: String Literals are enclosed in double-quotes("). Supported escape sequences are: \n, \t, \\ and \"

  • global every DURATION
    ${PLAYER} every DURATION
    This filter restricts execution on a time base. DURATION can be things like 10m, 1h, 30s or in the format mm:ss or hh:mm:ss. Cooldowns per player require a variable that represents a Player object, player name or player uuid.
  • ${PLAYER} hasPermission "PERMISSION" For some actions you might want to check player permissions. This condition requires PERMISSION to be quoted. The player variable again has to represent a Player object, player name or player uuid.
  • Comparisons
    You can compare two values, where at lease one has to be a variable. The comparing type has to be numeric or plain text.
    For numbers the comparators <, >, <=, >=, == (or =), != (or <>) are available.
    For strings the comparators <, >, <=, >=, ===, != (or <>) make case-sensitive lexicographic comparisons. Case-insensitive comparison can be done with = and ==. The special comparator matches compiles a right hand string literal into a regex and matches the left hand against it.
    Any condition can be inverted once by prefixing it with the word not


Lastly you can specify actions your trigger should take. Actions are command that are either executed as the player triggering the event, or as console if you prefix the command with an exclamation point (!) instead of a slash (/). Leading slashes for commands are optional. You can insert the values from ‘with’-chains with ${NAME}. Please also keep in mind that not every event has a player as cause, so you might use something like !execute as ${PLAYER} run ....

After running a action the following variables will be updated or removed automatically, based on the command:

  • successCount the commands’ success count, if applicable. Usually > 0 on success, 0 otherwise.
  • queryResult the commands’ result count, if applicable.
  • affectedBlocks the number of affected blocks, if applicable.
  • affectedEntities the number of affected entities, if applicable.
  • affectedItems the number of affected items, if applicable.

Cancelling Events

You can also cancel cancellable events with the special action cancel.

This is not a command! Do not prefix this action with / or !.

Plugin Support

Event Command also supports LuckPerms events. For a list of LP Events, see the LuckPerms SourceCode (make sure the classes extend LuckPermsEvent).


-- Sponge event
@ org.spongepowered.api.event.entity.TameEntityEvent
  -- player should be this most of the time:
  with player as & getName
  with entity as getTargetEntity getType getName
  !tell ${player} You tamed this ${entity}

  with player as getTargetEntity getName
  with world as getTargetEntity getLocation getExtent getName
  for ${world} != "overworld"
    -- teleport to spawn if no /spawn command is available
    !execute in "overworld" run tp ${player} 0 60 0 

-- Event for other Plugins
@ de.dosmike.sponge.minesweeper.MinesweeperGameEvent$Victory
  with player as getTargetEntity getName
  for ${player} every 5m
    !effect ${player} luck 30 1
    !tellraw ${player} {"text":"Sorry, but you've already received the luck effect recently","color":"red"}

@ de.dosmike.sponge.minesweeper.MinesweeperGameEvent$Defeat
  with player as getTargetEntity getName
  for ${player} every 5min
    !effect ${player} unluck 30 1

Need Help?

Join my Discord

Category: Admin Tools

Published on Jul 6, 2020




total downloads

Licensed under MIT

Promoted Versions