Exec

Exec
Plugin Information
Lead Dev	bastetfurry  techkid6
Links
Bugtracker	Bugtracker

Summary

This is just a little writeup of all commands and possibilities of exec. Exec is a plugin that allows one to write external plugins written in anything they fancy,  bastetfurry for example uses it in conjunction with Perl to achieve a plethora of features.

Editor's note: A number of Exec commands have been superseded by Vanilla commands following the Sponge update. Rather than reinvent the wheel, existing Exec scripts have been modified to use the Vanilla versions of the commands instead.

Files

exec.conf - Holds the commands and their respective scripts/programs to call. Format:

Command:Program:Parameters:Description

Command     - The command a player needs to execute to call a script or program.
Program     - The script or program that is called.
Parameters  - A hint for exec which parameters to send to the called script or program.
             Parameters are environment variables that a script or program can read from the OS.
             Multiple sets of parameters may be specified by separating them with a comma.
Description - A plaintext description of the command that will be displayed in /help

All Parameters include MCEXEC_ARGS which is everything typed behind the command.

Parameters can be:
 none - No game relevant parameters get send.
  MCEXECNONE will be set to NONE, if you want to catch that.

 playercoords - Player coordinates and what he has in his active slot get send
  MCEXEC_PLAYERNAME            - The name of the calling player.
  MCEXEC_PLAYERUUID            - The Unique User ID of that player.
  MCEXEC_PLAYERX               - X Coordinates of the calling player.
  MCEXEC_PLAYERY               - Y Coordinates of the calling player.
  MCEXEC_PLAYERZ               - Z Coordinates of the calling player.
  MCEXEC_PLAYERPITCH           - The players pitch.
  MCEXEC_PLAYERROTATION        - The players rotation.
  MCEXEC_PLAYERWORLD           - A string representing the current player dimension. As of 1st April 2021 this can be "overworld", "nether" and "end"
  MCEXEC_PLAYERWORLDNAME       - The name of the current player world.
  MCEXEC_PLAYERWORLDUUID       - The Unique User ID of the current player world.

 playeritems - Items of the player in each hand
  MCEXEC_PLAYERITEMSLOT        - The slot that the player currently has selected in their primary hand.
  MCEXEC_PLAYERPITEMTYPE       - Type of the item the player is holding in their primary hand.
  MCEXEC_PLAYERPITEMAMOUNT     - Amount of the item the player is holding in their primary hand.
  MCEXEC_PLAYERPITEMDAMAGE     - Damage or data of the item the player is holding in their primary hand.
  MCEXEC_PLAYERPITEMDURABILITY - Remaining durability of the item the player is holding in their primary hand if the item has durability.
  MCEXEC_PLAYERPITEMNBT        - A JSON-encoded string representing the "unsafe" NBT values of the item the player is holding in their primary hand.
  MCEXEC_PLAYERSITEMTYPE       - Type of the item the player is holding in their off hand.
  MCEXEC_PLAYERSITEMAMOUNT     - Amount of the item the player is holding in their off hand.
  MCEXEC_PLAYERSITEMDAMAGE     - Damage or data of the item the player is holding in their off hand.
  MCEXEC_PLAYERSITEMDURABILITY - Remaining durability of the item the player is holding in their off hand if the item has durability.
  MCEXEC_PLAYERSITEMNBT        - A JSON-encoded string representing the "unsafe" NBT values of the item the player is holding in their off hand.

 playername - Just the player name.
  MCEXEC_PLAYERNAME            - The name of the calling player.
  MCEXEC_PLAYERUUID            - The Unique User ID of that player.

 playerworldedit - Bridge to WorldEdit, sends the current selected cuboid.
  MCEXEC_PLAYERNAME            - The name of the calling player.
  MCEXEC_PLAYERUUID            - The Unique User ID of that player.
  MCEXEC_PLAYERWORLD           - A string representing the current player dimension. As of 1st April 2021 this can be "overworld", "nether" and "end"
  MCEXEC_PLAYERWORLDNAME       - The name of the current player world.
  MCEXEC_PLAYERWORLDUUID       - The Unique User ID of the current player world.
  MCEXEC_WORLDEDIT_XF          - X of the first selection.  
  MCEXEC_WORLDEDIT_YF          - Y of the first selection.  
  MCEXEC_WORLDEDIT_ZF          - Z of the first selection.  
  MCEXEC_WORLDEDIT_XS          - X of the second selection.  
  MCEXEC_WORLDEDIT_YS          - Y of the second selection.  
  MCEXEC_WORLDEDIT_ZS          - Z of the second selection.  

 playerlooksat - Sends player coordinates and what the player is currently looking at.
  MCEXEC_PLAYERNAME            - The name of the calling player.
  MCEXEC_PLAYERUUID            - The Unique User ID of that player.
  MCEXEC_PLAYERX               - X Coordinates of the calling player.
  MCEXEC_PLAYERY               - Y Coordinates of the calling player.
  MCEXEC_PLAYERZ               - Z Coordinates of the calling player.
  MCEXEC_PLAYERPITCH           - The players pitch.
  MCEXEC_PLAYERROTATION        - The players rotation.
  MCEXEC_PLAYERWORLD           - A string representing the current player dimension. As of 1st April 2021 this can be "overworld", "nether" and "end"
  MCEXEC_PLAYERWORLDNAME       - The name of the current player world.
  MCEXEC_PLAYERWORLDUUID       - The Unique User ID of the current player world.
  MCEXEC_BLOCKTYPE             - The looked at block type.
  MCEXEC_BLOCKSTATE            - The looked at block state.
  MCEXEC_BLOCKID               - The looked at block legacy ID.
  MCEXEC_BLOCKDATA             - The looked at block legacy data value.
  MCEXEC_BLOCKNBT              - A JSON-encoded string representing the "unsafe" NBT values of the looked at block's "block entity" if present.
  MCEXEC_BLOCKX                - The looked at block X coordinate.
  MCEXEC_BLOCKY                - The looked at block Y coordinate.
  MCEXEC_BLOCKZ                - The looked at block Z coordinate.
  MCEXEC_BLOCKOUTOFRANGE       - "FALSE" if there was a block in range, "TRUE" if there was no block in a range of 200 blocks.

 commandblock - Sends information about the command block executing the command. Mutually exclusive with all other parameter types.
  MCEXEC_CBLOCKX               - The command block X coordinate.
  MCEXEC_CBLOCKY               - The command block Y coordinate.
  MCEXEC_CBLOCKZ               - The command block Z coordinate.
  MCEXEC_CBLOCKWORLD           - A string representing the current command block dimension. As of 1st April 2021 this can be "overworld", "nether" and "end"
  MCEXEC_CBLOCKWORLDNAME       - The name of the current command block world.
  MCEXEC_CBLOCKWORLDUUID       - The Unique User ID of the current command block world.

Built-in Commands

As you surely want to interact with the world from your script or program, there are a plethora of built-in just for that.

getblockat

getblockat - Returns the block at a given coordinate.
 Syntax: getblockat X Y Z [WorldString]
  X - X coordinate of the block to be retrived.
  Y - Y coordinate of the block to be retrived.
  Z - Z coordinate of the block to be retrived.
  [WorldString] - Optionaly the name of the world this will happen. For Freedonia, options are "freedonia", "dim-1", and "dim1"  

 Return Value:
  "getblockat response:BlockType:X:Y:Z:WorldString" - The BlockType asked for.

getplayerinfo

getplayerinfo - Returns a players information.
 Syntax: getplayerinfo playername
  playername - The name of the player the information is wanted from.
 
 Return Value:
  "[exec] Player playername not found." - The player is not online.
  "[exec] Player playername seemed to have left before getplayerinfo execution." - If the player somehow vanishes before his information is gathered, this is outputted.
  "[exec] getplayerinfo response:X:Y:Z:Rotation:Pitch:WorldString:Health:ItemIDOfItemInHand" - The player has been found and his info is returned.
   X - Players X coordinate.
   Y - Players Y coordinate.
   Z - Players Z coordinate.
   Rotation - Players current rotation (left-right).
   Pitch - Players current pitch (up-down).
   WorldString - The dimension as a string the player currently is in. Can be "normal", "nether" and "end" currently.
   Health - His current health status. Remember, one hearth is equal to 2 hitpoints.
   ItemIDOfItemInHand - The item he currently has in his hand.

setplayerhealth

setplayerhealth - Sets the health of a player.
 Syntax: setplayerhealth playername [--r] health
  playername - The players name you want to set the health of.
  r - Optional flag to tell exec to set the health relative to the old one.
  health - The health the player should have now.

 Return Value:
  "[exec] Player playername not found." - The player is not online.
  "[exec] Player playername seemed to have left before setplayerhealth execution." - If the player somehow vanishes before his health is modified, this is outputted.
  "[exec] setplayerhealth response:num" - The players new health.

setplayerfood

setplayerfood - Sets the food level of a player. ''Note, this does not set "saturation".''
 Syntax: setplayerfood playername [--r] food
  playername - The players name you want to set the food level of.
  r - Optional parameter to tell exec to set the food level relative to the old one.
  food - The food level the player should have now.

 Return Value:
  "[exec] Player playername not found." - The player is not online.
  "[exec] Player playername seemed to have left before setplayerhealth execution." - If the player somehow vanishes before his health is modified, this is outputted.
  "[exec] setplayerfood response:num" - The players new health.

sendmsgtoplayer

sendmsgtoplayer - Sends a message to a player if he is online.
 Syntax: sendmsgtoplayer playername message
  playername - The name of the player that will receive the message
  message - The message that this player will receive.

 Return Value:
  "[exec] Player playername not found." - The player is not online.
  "[exec] Player playername seemed to have left before sendmsgtoplayer execution." - If the player somehow vanishes before he could receive the message, this is outputted.
  "[exec] Message to player playername successfully sent." - All went well, the message is out.

sendmsgtogroup

sendmsgtogroup - Sends a message to all players that are in given group.
 Syntax: sendmsgtogroup group message
  group - The name of the group that will receive the message
  message - The message that the group player will receive.

 Return Values:
  "Message to group group successfully sent." - All went well.

 This command does not produce an error!

sendmsgtoall

sendmsgtoall - Broadcast a message to all players.
 Syntax: sendmsgtoall message
  message - The message that all players will receive.

 Return Values:
  "Message to all successfully sent." - All went well.

 (Yep, that command is quite unnecessary... saw that much later too. Its still in for compatibility.)

savetolog

savetolog - Just saves something to the logfile.
 Syntax: savetolog [info|severe|warning] logstring
  info|severe|warning - Optional parameter for the severity of the log message, use only one of these three.
  logstring - The string that gets output to the logfile.

 Return Values:
  None

remotecommand

remotecommand - Executes a command as a given player. No permission checking here.

 Syntax: remotecommand playername command
  playername - The players name the command is executed as.
  command - Any command the player should execute. Any means what it says on the tin, the player gets that command while he needs it.

Usage

Examples

• https://gist.github.com/slowriot/ff3a5e4db1cb0189b33f - minimal hello world program with error handling