Prison

Prison Documentation

Prison Documents - Table of Contents

Setting up Prison - The Basics

This document provides a quick overview on how to install Prison and get it running.

Documented updated: 2024-08-30

Download Prison

Download Prison from one of the following sites:

These sites will have stable alpha releases published to them from time to time.

Setting up Prison is simple:

Prison’s Dependencies on Other Plugins

There may be no hard dependencies that will prevent Prison from running, but there are some core plugins that will make it easier to use, and are even required for activation of some features within Prison. This short list is just a suggestion, but alternatives do exist and may be outside of our ability to comment or assist in their usage.

Economy Plugins - Required

Prison requires an active economy in order to active the Ranks plugin. When Prison starts up, it performs many validations on the mines and ranks as they are being loaded. With Ranks, if Prison cannot find an active economy, then it will refuse to load the Ranks module due to possible server corruption (ie… what failed that there is no economy).

We say an economy is required, but it’s still optional. Without an economy, you cannot use the ranks module, but we fully understand that some servers choose to use a different ranks plugin.

Coins Engine is supported. A multi-currency economy. Need to provide more details

Gems Econommy is supported. A multi-currency economy. Need to provide more details

EdPrison Economy is supported. Need to provide more details

ESS Economy is supported. Need to provide more details

The New Economy is supported. Need to provide more details

Sane Economy is supported. Need to provide more details

Chat Prefix Plugins - Optional

These plugins are used to add rank tags to the player’s chat messages that they send.

Permission Plugins - Required

Permission plugins are not strictly required for Prison to work, but within a server environment almost everything depends upon permissions in order to make things work.

Prison actually uses bukkit’s permission interfaces. This makes it simple for Prison, but it also limits what prison can do. For example, one limitation is with permission groups; Prison is unable to resolve permission groups since that “concept” does not exist in bukkit, but is a concept that is implemented through plugins like PEX and LuckPerms.

integrations:
  prevent-economy-vault-usage: true

Placeholder Plugins

Chat related plugins are able to provides access to Prison placeholders, which can allow Prison data to be included in their content. PAPI is simple and works so well, that it usually is the default choice.

The way a placeholder works, is that it is a text based key that is used to request data. Generally the key is included with other text, such as a chat message, holographic display, or a scoreboard content, and the key is replaced with the requested data. Usually the plugins using placeholders have no idea what other plugins are supplying the requested data; they basically make a general request for information to all plugins, and the plugins that recognize that key will respond.

It should be noted that Prison’s placeholders are just text based keys. They are usually all lower case alpha numeric characters, with underscores, and maybe some colons too. The important thing to understand is that they do not include the escape characters, and that the escape characters may differ from what is required in other plugins. Placeholder escape characters are usually { } or % %, and sometimes you may have to mix the two. The plugin’s documentation should help you identify what’s the correct usage.

All prison placeholders start with prison_ and are usually all lower case. Upper case may work too, but lower case is recommended. Prison tries to ignore the case of its placeholder keys, but its the other plugins that can have issues. For example, if Prison registers all of the plugins as lower case, then the other plugins may not recognize all upper case, or mixed case, as being related to Prison, so therefore they may not send the request to Prison.

An example of a prison placeholder is prison_rank. But used in another plugin, you will need to add escape characters such that it may be either {prison_rank} or %prison_rank%. Prison only controls what the text key is; prison cannot control which escape characters are used in another plugin.

All of Prison’s placeholders have an alias. An alias is a shortened name for a placeholder. Some placeholder names can become large based upon trying to keep their names informative as to what they represent. As an example, prison_rank has an alias of prison_r. And prison_player_balance_earnings_per_minute_formatted has an alias of prison_pb_epmf which can be useful if there is limited space in the configurations. The command /prison placeholders list shows all available placeholders, along with their aliases.

NOTE: Prison no longer supports MVdWPlaceholder because it could not support all of the advanced features with placeholders that prison uses. Also, since prison generates so many possible placeholders, MVdW pollutes the console log with thousands of lines of useless information stating each variant of a placeholder has been registered. We also dropped support for this plugin because there is no way to contact the developer because they hide behind a pay-wall, and I’m not about to buy one of their other plugins to just tell them their so-called-free plugin is not working properly.

But perhaps the biggest reason why I dropped support for MVdW is because it’s 100% pointless from Prison’s perspective. PlaceholderAPI works flawlessly with MVdW installed too, so there is absolutely no reason why prison needs to support MVdW anymore since everything works perfectly through PlaceholderAPI. If you need to use MVdW, then please keep using it, it works great with their other plugins. But you can use PlaceholderAPI along with it too. So there are zero reasons why you cannot use PlaceholderAPI, and everyone is happy.

Suggested to Avoid - Prison does support this plugin, but since it is used mostly with premium plugins, we have no way to fully test this plugin to ensure it actually works correctly. We’ve heard very few people have used this plugin, but we’ve heard it does work well. Use at your own risk.

With this plugin, all placeholders are registered with it automatically when prison starts up, and all placeholders should be used as all lower case. Because prison has so many placeholders, with many that are expanded based upon ladders, ranks, and mine names, a modest prison server could generate and register well over 1000 placeholders. MVdWPlaceholder appears to be very verbose so you will see a lot of logging in the console when it starts up.

It should also be noted that because of some of the limitations of MVdW, not all features of Prison’s placeholder support will be supported. For example, you may not be able to reload placeholders, or use placeholder attributes to customize how placeholders are used. Also the numerical sequence placeholders may not work either.

Like it was said earlier, there is no way to contact the developers. If we could make just one suggestion, and that would be to allow setting up placeholders by specifying a prefix that’s used. This is how PlaceholderAPI works, so with just registering once, a value of “prison_” that ensures all of prison’s placeholders are routed to us. Also, make sure the allowable placeholders are not limited by length. Prison use placeholder attributes that can customize how the results are modified which gives an almost limitless opportunity to customize placeholders as desired to match the server’s design standards. The third suggestion for changes is to allow the reloading of placeholders with a simple command, such as reregistering them. As admins add ranks, ladders, or mines, or even change their names, then all of the placeholders must be reregistered so the new entries are included.

World Protection Plugins

/rg flag __global__ -w world passthrough deny

Enchantment Plugins

NOTE: this section needs more work. It’s not up to date, and does not list all of the various features.

To use RevEnchant’s block break handling, prison needs to just monitor the events so it can update the block counts. This is an example of what settings are needed if you are using Prison’s Block Events.

    blockBreakEventPriority: ACCESSBLOCKEVENTS

    RevEnchantsExplosiveEventPriority: BLOCKSEVENTS
    RevEnchantsJackHammerEventPriority: BLOCKEVENTS

Or if you are not using Prison Block Events, then just MONITOR should be used for better performance.

    blockBreakEventPriority: ACCESSMONITOR

    RevEnchantsExplosiveEventPriority: MONITOR
    RevEnchantsJackHammerEventPriority: MONITOR

Please note: These settings may also apply to the other enchantment plugins if you do not want to use Prison’s block handling.

Please Note: There is another plugin by the same name “Tokens” that strictly deals with tokens and not enchantments, which works just fine with prison. I have even personally contributed to that plugin to provide caching of the player’s data to resolve an issue with ultra fast mining in prison. Basically it used to be that if you give players tokens too quickly, it would lockup the server trying to update the save files. Now it easily supports 100’s, if not 1000’s of transactions per second without any impact to the TPS.

Enchantment Plugin Features Supported

This table of supported Enchantment Plugins are plugins that have an event that Prison is able to hook in to for the purpose of communicating multiple block breakage. It should be noted that all of these events are related to block breakage, and originate from the original bukkit’s BlockBreakEvent, but the other plugins takes the single block, then applies “effects” that expands the one block breakage to multiple blocks. These events are the mechanism for conveying the list of included blocks to Prison so Prison can do what it needs to do with the blocks.

Plugin Event Settings ID Cancel
Events		 Cancel
Drops		 External
Hooks		 ACCESS
Priority
Supported
Bukkit/Spigot BlockBreakEvent blockBreakEventPriority Yes Yes Yes Yes
Prison ExplosiveBlockBreakEvent ProcessPrisons_ExplosiveBlockBreakEventsPriority Yes No No No
TokenEnchant TEBlockExplodeEvent TokenEnchantBlockExplodeEventPriority Yes No No No
CrazyEnchants BlastUseEvent CrazyEnchantsBlastUseEventPriority Yes No No No
PrisonEnchants PEExplosionEvent PrisonEnchantsExplosiveEventPriority Yes No No No
RevEnchants ExplosiveEvent RevEnchantsExplosiveEventPriority Yes No No No
RevEnchants JackHammerEvent RevEnchantsJackHammerEventPriority Yes No No No
Zenchantments BlockShredEvent ZenchantmentsBlockShredEventPriority Yes Yes Yes No

Notes:

  1. A value of No for Cancel Drops will always use Cancel Event instead.
  2. Cancel Drops was added in Spigot 1.12.x so older versions of Spigot must use Cancel Events
  3. External Hooks refers to custom hooks in to mcMMO, EZBlock, and Quests. See config settings within AutoFeaturesConfig.yml. It’s strongly suggested to use Cancel Drops instead so you won’t have to enable these features. These provides a hacky-fix for the limitations when using Cancel Events and may not be perfect.
  4. Zenchantments is flexible in how it’s BlockShredEvent works, mostly because it extends the bukkit BlockBreakEvent. The events can possibly mix with normal BlockBreakEvents.
  5. It may take some effort to find the ideal priorities to use for your environment to ensure everything works as you envision it.
  6. ACCESS Priority Supported* only the BlockBreakEvent should be used with the ACCESS, ACCESSBLOCKEVENTS, or ACCESSMONITOR. All events supports the use of ACCESS, but only the first block in their list is check. Therefore it really won’t be ideal. Plus all of these events originate through the BlockBreakEvent so if that is checking ACCESS then it should be sufficient.

Event Listener Priorities

The above listed supported Events are assigned one of the available Prison Event Priorities. This table illustrates what features are associated with each priority, which can be somewhat complex and confusing.

Priority Actual
Event
Priority		 Access In
Mine		 In
World		 Ignores
Canceled
Events		 Block
Break		 Block
Count		 Reset
Threshold		 Block
Events		 Mine
Sweeper		 AutoSell
DISABLED -note1- No No No No No No No No No No
ACCESS LOWEST Yes Yes No No No No No No No No
ACCESSBLOCKEVENTS -note1- Yes Yes No NoYes No Yes Yes Yes Yes Yes
ACCESSMONITOR -note1- Yes Yes No NoYes No Yes Yes No Yes No
LOWEST LOWEST Yes Yes No No Yes Yes Yes Yes Yes Yes
LOW LOW Yes Yes No No Yes Yes Yes Yes Yes Yes
NORMAL NORMAL Yes Yes No No Yes Yes Yes Yes Yes Yes
HIGH HIGH Yes Yes No No Yes Yes Yes Yes Yes Yes
HIGHEST HIGHEST Yes Yes No No Yes Yes Yes Yes Yes Yes
BLOCKEVENTS MONITOR No Yes No Yes No Yes Yes Yes Yes Yes
MONITOR MONITOR No Yes No Yes No Yes Yes No Yes No
headers EvntPri Access In Mine IN Wrld IgCanEv Blk Brk Blk Cnt ResetTh BlkEvnt MineSwp AutoSel

Notes:

  1. ACCESSBLOCKEVENTS and ACCESSMONITOR will run two events. One of which will be ACCESS which will have an actual bukkit priority of LOWEST. And the other listener will run a BLOCKEVENTS or MONITOR Prison priority which both will have an actual bukkit priority of MONITOR.
  2. DISABLED will not have an actual event priority. ACCESSBLOCKEVENTS will have two processes; see actual priorities for ACCESS and BLOCKEVENTS. ACCESSMONITOR will have two processes; see actual priorities for ACCESS and MONITOR.
  3. DISABLED will prevent a listener from starting, and it will prevent any processing of that event.
  4. Access managed by Prison requires the use of Access by Rank (preferred) or Access by Perms. It also will vary in effectives based upon the priority level in relation to other plugins, where any plugin that has a lower priority than Prison will bypass Prison’s attempts to control access.
  5. ACCESSBLOCKEVENTS and ACCESSMONITOR are able to have a duel behavior because these priorities will create two different listeners, each at a different priority, and each having a different purpose.
  6. Block Break refers to Prison handling the whole block break processing and drops.
  7. Mine Sweeper should never be used unless there is no other way to count all the broken blocks.
  8. Support for outside of the mine for auto features maybe added soon. The way it will probably be supported would be through a list of worlds in which it should be active, plus the use of WG regions too.
  9. The MONITOR priority, including *BLOCKEVENTS will ignore all events that have been canceled and will process them anyway. Therefore ACCESSBLOCKEVENTS and ACCESSMONITOR will fail on the “access” part if the event is canceled when Prison gets a hold of it the first time, which will deny access to the mines, but it will also still process the event under the priority of MONITOR or BLOCKEVENTS.

Other Plugins

Important Prison Information

Upon starting up, Prison will display a lot of information in the server’s console. This information is intended to help you configure and confirm that prison started correctly with all of the related resources that it is using. It also provides you with valuable information that is needed to help troubleshoot issues, if you should happen to encounter any.

Some of the important details that are listed:

Server Start Up Script

If you are leasing a server from a hosting service you may not be able to customize the startup script. But if you have control over it, then the following information may help.

java -Xms2g -Xmx4g -jar spigot-1.16.5.jar -nogui

Example of enabling debug hooks for the server. This is used with Eclipse, and may work with other IDEs since it’s a java directive.

java -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005 -Xms2g -Xmx8g -jar spigot-1.16.5.jar -nogui --log-strip-color

Note: The use of --log-strip-color may or may not work within your environment.

Setting up an Eclipse Debugging Session

To go along with the above settings for debugging on port 5005, you need to setup in Eclipse the correct remote debug configuration using a Remote Java Application.

Detailed settings can be found here:

https://www.spigotmc.org/wiki/eclipse-debug-your-plugin/

Basically, under “Debug Configurations…”, add a new “Remote Java Application”. Select a name, such as “Spigot Debugger - Local”, with port 5005, and localhost for the host.

With the spigot server already running, then set a break point in the code, then start the debugger.

If the Eclipse debugger breaks on the selected breakpoint, but yet does not show any source, click on the button in the empty source window to select the correct source. From the popup window, then choose to select an existing Java Project, then select all listed projects associated with your plugin(s), including all sub-projects. The debugger should then select the correct source.

Getting Help

If you should run in to any questions or issues, please first review all online documentation first.

If you cannot find what you need within the documentation, please visit our Discord server to get the quickest responses there.
Prison Discord Server

In order to provide the best support, the prison startup screen provides most of the information that is needed to help trouble shoot your issues. Please take a screen print and provide on discord with a detailed explanation of the issue.

If you do encounter an issue, and the startup information is requested, please include everything from the first line to the last. Please take a screen print and provide on discord with a detailed explanation of the issue. Include everything from:

	[16:21:30 INFO]: [Prison] Enabling Prison v3.2.5

through:

	[16:21:31 INFO]: | Prison | Prison - Finished loading.

Prison Support Submit Information

Prison now has a built in way to share your configurations and settings with support personnel.

More information will be documented in the future, but for now, here are the basics on how to use it.

When requested by the Prison support team, you would first enter the following command to set your name that will be included on all reports to help identify who the are related to. It doesn’t have to be your full discord name, but enough characters to allow us to identify who you are.

These commands will collect all of the related information from your Prison setup, and send it to the website https://paste.helpch.at. It will provide you with an URL. All you need to do is to copy and paste that URL in to the discord chat so the Prison support team can help with your issue.

/prison support setSupportName <yourName>

Once entered, it will enable the following submit tools:

/prison support submit - Show the available tools.

/prison support submit version
/prison support submit configs
/prison support submit latestLogs
/prison support submit mines
/prison support submit ranks

Here is an example that I generated from one of my test servers on 2021-12-03. I have no idea how long the content remains available, but for support purposes, we only need this information for a few hours. It appears like this information is never deleted? As such, here are two different versions which shows you how much more information has been addeed. https://paste.helpch.at/silihuxaja From Prison v3.3.0-alpha.15a https://paste.helpch.at/itejovejeh From Prison v3.2.11-alpha.9

Prison Commands

On the startup screen, prison shows all of the base commands that are active. From these commands, they will provide you with sub-listings of all the other commands.

If you use the command /prison it will not only display all of the sub commands available for /prison, but it will also include a list of all the other root commands and aliases that have been setup.

Prison Commands

These commands are intended to run in game, but most can be ran from the system console. Sometimes the system console is easier to displays longer listings, such as /mines list. Also the console is better with wider text, and with easier to read text since it’s not trying to display over a mc world.

Getting Started

There is a lot to do get your server up and running. But here are some ideas on what to get started on first. It may even be a good idea to create a couple of small mines in an area that you have not spent much time with your final builds. Plan on creating a couple of test mines and ranks, then deleting them. You can quickly get a good understanding of how prison can be setup by playing around with a lot of the setting within a few minutes.

Remember that the command /prison version will show all the available root level commands by the modules. Entering those commands will show all of the related sub commands.

This site is open source. Improve this page.