Prison Documentation

Prison Documents - Table of Contents


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.

BlockEvent Sub-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.

BlockEvent Sub-Commands

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

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.

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:

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.

-{locationX} The X coordinates for the broken block. This is an integer value.

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 **** key on your keyboard and it will show last entered command. Then just hit **** then enter the row number and press ****. For our example, let's pretend we want to add a block to the third row:

/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