Prison
Prison Documentation
Prison Documents - Table of Contents
BlockEvents
Prison’s BlockEvents provides a way to fire commands when a block is broken by a player. Every BlockEvent must have a chance which can range from 0.0000 percent to 100.0 percent. Optionally, you can tie the block event to a permission, to an event type, and for Token Enchant explosions you can filter on the enchantment type that triggered that explosion. You can also filter on a Crazy Enchant blast too. BlockEvents can even filter on block types so you can only trigger an even on a specific block type.
A single BlockEvent can consist of more than one command that is ran together with each command separated by a semi-colon. “;”
BlockEvents have a taskMode that defines how the specified commands are to be ran.
Documented updated: 2022-08-06
BlockEvent Commands
BlockEvents can be access through the command prefixes of:
/mines blockEvent
/mines blockEvent block
There are 10 sub-commands (two under blocks), which includes add and list, which are probably the most important of the commands.
In the above screen print, the sub-commands have as a parameter named row. See the next section in this document for more information.
The BlockEvent listings can also be included in the following command by including the keyword all:
/mines info <mineName> all
Use of Row Numbers In The BlockEvent Commands:
Due to the complexity of the blockEvent commands being deeply nested, and there could be so many of them, many of the blockEvent commands uses a Row identifier to select the blockEvent of interest. This row identifier is based upon the order of the commands as listed under the /mines blockEvent list command.
All of the blockEvent commands now supports displaying the current list of rows by completing the blockEvent command up to the required mine name. When pressing enter to submit the incomplete command, it will then show the list of rows.
A number of examples of a few different blockEvets is as follows. Emphasis is on the row numbers.
Starting with BlockEvents - Add a new BlockEvent
It is strongly suggested that you first review the help on the following command:
/mines blockEvent add help
That will show the current information on blockEvents. It’s also important to understand that the list of placeholders is also critical since it provides a great deal of power and flexibility in what commands can be crafted. See the next section on BlockEvents Placeholders.
The first step of creating blockEvents, is to add them. There are a lot of options that can be used for customizing them and they can become rather complicated, so the add function only requires a percentage value since all other options are optional, and some may not be used.
BlockEvents Placeholders
Within the BlockEvents commands you can use placeholders and Prison will substitute the correct values within the commands.
For a current list of all blockEvent commands use placeholders keyword with the add command:
/mines blockEvent add help
/mines blockEvent add placeholders
{player} {player_uid} {msg} {broadcast} {title} {actionBar} {inline} {inlinePlayer} {sync} {syncPlayer} {blockName} {mineName} {locationWorld} {locationX} {locationY} {locationZ} {coordinates} {worldCoordinates} {blockCoordinates} {blockChance} {blockIsAir} {blocksPlaced} {blockRemaining} {blocksMinedTotal} {mineBlocksRemaining} {mineBlocksRemainingPercent} {mineBlocksTotalMined} {mineBlocksSize} {blockMinedName} {blockMinedNameFormal} {blockMinedBlockType} {eventType} {eventTriggered} {utilsDecay}
Some examples showing how to use placeholders in the blockEvents.
/mines blockEvent add a 100 {utilsDecay} rainbow {blockCoordinates} AIR 40 {mineName}
/mines blockevent add A 0.075 prison utils repairAll {player};{actionBar}Your items have been repaired!
/mines blockevent add A 1 prison utils smelt {player}
/mines blockEvent add A 5.0 prison utils potionEffect speed 90 2;prison utils potionEffect night_vision 300 1
Placeholders Explained
-
{player} Provides the player’s name.
-
{player_uid} Provides the player’s UUID.
Prison’s BlockEvents also supports more advanced placeholders that can help simplify some basic tasks. Over time this list will be expanded to include more useful features.
-
{msg} Send a message to the player. This is a shortcut for the prison command:
/prison utils msg. Example:{msg} Congrats! You found a token!. -
{broadcast} Sends a broadcast message to all players on the server. Just use this placeholder followed by the message. This is a shortcut for the prison command:
/prison utils broadcast. Example:{broadcast} {player} found a treasure trove of 100 voter keys!. -
{actionBar} Sends a message to the “actionBar” on the player’s screen. Just use this placeholder followed by the message. This is a shortcut for the prison command:
\prison utils titles actionBar <player>. Example:{actionBar}You Found Tokens! -
{title} Sends a message to the “title” on the player’s screen. Just use this placeholder followed by the message. This is a shortcut for the prison command:
\prison utils titles title <player>. Example:{title}You Found Tokens!
How the command runs:
Note: Due to overall performance issues when commands are used that cannot support a rapid turn around time, which will contribute to lag, the option to run commands {inline} no longer exists. The placeholders are still there, but all blockEvents are preprocessed, then ran together in one blocked-unit in another thread. If the running on any single command takes a while (too long), then the remaining commands will be resubmitted to prevent lag, or at least greatly reduce it. But also submitting the task of running the commands, it will also help Timings better identify it as being related to a command that is being ran. If prison is in debug mode, then high level stats on all of the commands that are ran with the blockEvents will be logged within the console.
There are four taskModes on how BlockEvent commands run. The taskModes can be setup through the command /mines blockEvent taskMode help, or they can be specified as placeholders. There are 4 taskModes, and the placeholder versions are listed here:
-
{inline} This is the default taskMode if not specified. {inline} runs the commands in the same thread that in which Prison is handling the Block Break Events within Auto Features, and runs them as console (OP). If the command you use with BlockEvents is “slow” to run, then it could cause significant lag on the server.
-
{inlinePlayer} This placeholder is similar to the {inline} placeholder, but it is ran as the player who is mining. This too can cause significant lag if the command is not fast.
-
{sync} This placeholder uses the taskMode of synchronous task submission. The command specified will be submitted to run in the bukkit’s synchronous thread, and is ran as console (OP). Since all block break events are ran in the same bukkit synchronous thread, the specified command will run after prison is finished processing the broken block. Long running commands will not cause lag through the handling of the block break events, but they could still cause lag.
-
{syncPlayer} This placeholder is similar to the {sync} placeholder, with the exception the commands are ran as the player, so the player must have access to those commands.
NOTE: It is impossible to run a command asynchronously, since the execution of a command must always be in a synchronous thread. Hence you can submit an async task, but then when you run the command, it does so in a sync thread. This explanation may not make a lot of sense, but it creates an additional task, but fails to run in asynchronous mode since it’s impossible so it’s not even worth using it.
-
{blockName} The name of the block that was placed in the mine during the last mine reset. The same name as used and provided within the command
/mines block search. -
{mineName} The name of the mine. If outside of a mine it will be blank.
-
{locationWorld} Provides the world name in which the block was mined.
-{locationX} The X coordinates for the broken block. This is an integer value.
-
{locationY} The Y coordinates for the broken block. This is an integer value.
-
{locationZ} The Z coordinates for the broken block. This is an integer value.
-
{coordinates} This provides the X, Y, and Z coordinates for the broken block. These are double values, surrounded by parenthesis and separated by commas. Format: (X,Y,Z) Example:
(183.2,88.3792,-3828.248) -
{blockCoordinates} This is similar to the {coordinates} placeholder, except for the use of integer values. Format: (blockName,world,X,Y,Z) Example:
(,prisonWorld,183,88,-3828) -
{worldCoordinates} This combines both the {locationWorld} and {blockCoordinates} placeholder in to one placeholder. The coordinates are integer values. Format: (world,X,Y,Z) Example:
(prisonWorld,183,88,-3828) -
{blockChance} The blockEvent’s percent chance as defined when setting up the command.
-
{blockIsAir} A boolean value of either TRUE or FALSE as to if the block was originally set to AIR during the last mine reset. Technically, if the block is set to AIR, then it is ignored in all block events that prison processes through the auto features. Therefore this should always return FALSE.
-
{blocksPlaced} This is the number of blocks placed in the mine during the last Mine reset. This value should be equal to the mine’s total block size, minus the number of AIR blocks that were placed during the reset.
-
{blockRemaining} The current number of blocks remaining in the mine, until there would be zero blocks left to mine. Note that this is a dynamic and changing value, especially if many other players are mining at the same time. There is even a chance that this value may be non-zero with another player’s block break handling triggering a mine reset event, or zero blocks remaining.
-
{blocksMinedTotal} The total number of blocks mined of the same type that was just broke since the last mine reset.
-
{mineBlocksRemaining} The total number of block remaining of the same type that was just broke. See {blockName} for the block name.
-
{mineBlocksRemainingPercent} The percent number of blocks remaining in the mine.
-
{mineBlocksTotalMined} This is the total number of all blocks mined since the stats were first enabled.
-
{mineBlocksSize} This is the total block count of all blocks mined.
-
{blockMinedName} This is the name of the block that was mined. It may not be identical to the {blockName} placeholder, especially if another process replaced it with another block.
-
{blockMinedNameFormal} This is the formal name of the block that was mined. The formal nature is the namespace prefixed to the block name, with a colon between the two. For example a block name may be “cobblestone” and then the formal name being “minecraft:cobblestone”. This is more useful for custom blocks, such that their namespace is not “minecraft”, which an example being “customitems:compressed_cobblestone”.
-
{blockMinedBlockType} This is the bukkit Material name for the block. It may not match the block name, especially on older versions of spigot.
-
{eventType} This is the event type that Prison listened to that initiated the block break handling.
-
{eventTriggered} A few enchantment plugins identify the enchantment that triggered the event. If it is available, then that value will be provided by this placeholder. One plugin that provides this value is TokenEnchant.
-
{utilsDecay} This is a shortcut for
/prison utils decay.
BlockEvents Commands
The BlockEvent command that is used must be be runnable from the console. It is suggested that you use the console to figure out the correct structure of the command that you are interested in running. If it works from the console, then it should work as a BlockEvent command.
The structure of the command should be the same as within the console. Do not include a a leading /. Do not quote the command. Use the placeholders mentioned above for referring to the players.
Move than one command can be chained together by using a semi-colon between the commands. The commands do not need to end with a semi-colon. No space needs to follow a semi-colon before the next command. There is no limit imposed upon the length of a command, or commands, but the max length may be controlled by outside factors such as in-game text message constraints. Hence why it may be advisable to enter long commands through the console.
See the above examples on how to enter the commands when setting up a BlockEvent.
BlockEvents Percent Chance
The chance that is tied to a block event can range from 100 percent to as low as 0.0001 percent.
A chance of 100 percent ensures the block event will always run if all the other filters pass.
Please be aware that there are no validations for the lowest setting for chance. What this means is that you “could” enter a value lower than 0.0001 percent and it could be accepted and it will work, but the displaying of that value will be cut off at four decimals and no rounding will apply so it could appear as if it is the same as zero. Also a value of 0 could be entered which would imply that the BlockEvent will never be ran.
Block Event chances are all independent from each other. Each block even setup in a mine will have a chance to be ran on each event. So if you have three block events, 70%, 20%, and 10%, all three can be ran on the same event since each block event rolls their own chance. This means you cannot setup block events where you want to apply only one of a number of actions, since all actions will have a chance to be applied.
BlockEvents Permission
If a permission is added to a BlockEvent then the player must have that permission before the BlockEvent is even considered. There can only be one permission per block event.
When adding a block event, to bypass the permissions, enter the value of none.
BlockEvents TaskMode
TaskMode identifies how a block event is ran. There are two major modes, with two ways to run the command, with the TaskMode combining these two components to define 4 possible TaskModes.
The actual values are: inline, inlinePlayer, sync, and syncPlayer.
The two major modes that defines how tasks are ran are inline and sync.
Inline runs the commands in the same thread as the block break event is processed. Inline tasks should be simple and fast so they do not produce lag with holding up each block break event. The inline mode is ran as console.
Sync submits the task to run right away, but it does so on the bukkit’s synchronous thread. It can produce lag if it takes a long time to run, but it will also allow the block break event to complete right away. The Sync mode is ran as console.
InlinePlayer runs the task inline, but as the player. It will not have any escalated permissions and the task can fail if it does not have access to the commands that are being ran.
SyncPlayer submits the task as the player. It will not have any escalated permissions and the task can fail if it does not have access to the commands that are being ran.
Asynchronously submitted tasks are not an option since commands cannot be submitted asynchronously; only code, or functions, can be submitted to be ran in an asynchronous thread. There isn’t an option to run commands this way, and if a task is submitted to be ran asynchorously to then run a command, then it drops in to synchronous mode to run the command.
BlockEvents EventType
The EventType defines what kind of event is being monitored.
By default, all is used. This applies to all event types.
BlockBreak This is the standard event type. It is used to identify when a single block is broken.
TEXplosion is a Token Enchant Explosion event, and generally includes more than one block. This filters only on the TE Explosion event. With this event type the Triggered option can be applied.
CEXplosion is a Crazy Enchant explosion event and generally includes more than one block. Unlike the BlockBreak event or the TE Explosion event, the CEExplosion event does NOT identify which block was actually hit by the player.
BlockEvents Triggered
Only the Token Enchant Explosion events provides information on which enchantment triggered the explosive event. This allows different BlockEvents to be fired for different enchantments that use explosions.
You must enter the correct value for this triggered command as used by Token Enchant and provided by Token Enchant. There is no way prison can validate this value when entered.
BlockEvents Blocks
You can filter blockEvents by block types. You have to already have setup a block command to add a block filter.
For example if you only want a specific blockEvent to be fired when redstone is broken.
The following shows the available commands:
/mines blockEvent block
You can only add and remove blocks. The commands will help step you through selecting the correct values.
First, if using the block add command, only enter the mine name and press enter. Let’s assume we are working with mine A:
/mines blockEvent block add a
This incomplete block add command will show you all of the existing block events for mine A. From the list, it will show the row number for each blockEvent.
>mines blockEvent block add a
--- < Add blocks to a BlockEvent for [A] > ------ (3.3.0-alpha.12e)
Hover over values for more information and clickable actions.
* Row: 1 75.00000% [] all (sync) 'say How's it going?'
* Blocks: [cobblestone iron_ore]
* Row: 2 5.00000% [] all (inline) 'prison utils potionEffect {player} night_vision 600 2'
* Row: 3 25.00000% [] all (inline) '{msg} night vision!;prison utils potionEffect {player} night_vision 600 2'
* Row: 4 0.01000% [] all (inline) '{msg}Hey this is a test Message!'
* Row: 5 100.00000% [] all (inline) '{utilsDecay} obby {blockCoordinates} AIR 40 {mineName}'
* Blocks: [cobblestone]
Select a BlockEvent by row number to add a block
/mines blockEvent block add A [rowBlockEvent] [rowBlockName]
Press the **
/mines blockEvent block add a 3
This incomplete block add command will then show the list of blocks in the mine. You select them by choosing the row number for the desired block. So in this example, let’s choose Andesite which is row 1.
>mines blockEvent block add a 3
--- < Add blocks to a BlockEvent for [A] > ------ (3.3.0-alpha.12e)
Select a block from this mine by using the block's row number:
/mines blockEvent block add A 3 [rowBlockName]
Row: 1 andesite 5.00000
Row: 2 cobblestone 95.00000
/mines blockEvent block add a 3 1
[22:02:32] [Server thread/INFO]: Block has been added to BlockEvent
So if we list the block events it will now include the newly added block:
/mines blockEvent list a
--- < Add blocks to a BlockEvent for [A] > ------ (3.3.0-alpha.12e)
Hover over values for more information and clickable actions.
* Row: 1 75.00000% [] all (sync) 'say How's it going?'
* Blocks: [cobblestone iron_ore]
* Row: 2 5.00000% [] all (inline) 'prison utils potionEffect {player} night_vision 600 2'
* Row: 3 25.00000% [] all (inline) '{msg} night vision!;prison utils potionEffect {player} night_vision 600 2'
* Blocks: [andesite]
* Row: 4 0.01000% [] all (inline) '{msg}Hey this is a test Message!'
* Row: 5 100.00000% [] all (inline) '{utilsDecay} obby {blockCoordinates} AIR 40 {mineName}'
* Blocks: [cobblestone]
You can add more than one block to each block event. Please note that in row 1 that blockEvent has two blocks tied to that filter. Please ignore the fact that iron_ore is not in this mine (oops).
BlockEvents ect…
More to be added