Nucleus is no longer updated and this site is frozen in time. Some links may be broken.
Welcome to the new docs site for Nucleus v2! Still on Nucleus v1? Visit the old site here.

Jail Module

Introduction

The Jail module allows for server staff to punish players by warping them to a specific place in the game world, and disabling their ability to interact with the world around them, both through commands and physical interaction. Typically, a “jail” will be a room with no means of escape.

The jail module can jail players temporarily or permanently. Server admins can set the location of jails on the game server, and server owners can define commands that the players are allowed to run, along with whether jailed players are also muted, within main.conf.

Jailings are usually intended for minor punishments and often have an expiry on them, but their use is completely up to server owners.

The jail module defines three main commands, /jail which contains commands to punish players, /checkjail to see if a player is actually jailed for how long, and why, and /jails which contains commands that defines and displays the actual location of jails.

Defining and Removing Jails

In order to be able to use the jail module effectively, at least one jail must be defined with a name. To do this, stand in the spot that you wish to create a jail, and run /jails set [name], where [name] is the alphanumeric name of the jail you wish to set.

To remove a jail, run the command /jails remove [name]. The jail will be removed.

The list of defined jails can be obtained by running /jails, and information on a specific jail can be found by running /jails info [name].

Jailing Players

Once a jail has been defined, a player can be jailed by running the command

/jail <player> <jail> [time] [reason]

The player and jail arguments are required, where <jail> is the name of the jail you wish to send the player to.

The reason argument is optional, but if specified, will be displayed to the jailed player

The time argument is optional, but if specified, is of the Timespan Argument format. For example: if you want to jail Notch in the grief jail for 3 hours, 45 minutes, the command would be:

/jail Notch grief 3h45m Jailed by example!

If a timed jail is given to a player who is not currently logged on, their time in jail will start when they next log in. By default, time towards their jail sentence will include both time where the player is online AND offline, unless jail-time-counts-online-only is set to true in main.conf.

Unjailing Players

To unjail a player, simply run /jail <player>.

Permission Contexts

When players are jailed, Nucleus adds permission contexts to the player permission set, so that you can change a player’s permissions when they are jailed. This is useful to be able to prevent the player from performing additional tasks, though Nucleus automatically blocks most commands and actions anyway.

Nucleus applies two contexts:

  • nucleus_jailed will simply have the value “true” if the player is jailed.
  • nucleus_jail will contain the name of the jail the player is jailed in.

Refer to your permission plugin documentation on how to set permissions on contexts.

Configuration

The jail module has several entries in main.conf:

  • allowed-commands specifies the commands that players are allowed to run whilst in jail. By default, the commands are primarily chat and message based commands.
  • mute-when-jailed, if set to true, will also mute players (in global chat only) that are in jail. This defaults to false.
  • jail-time-counts-online-only, if true, a player’s time in jail will only be counted when they are online.

The following are incompatibilities that may occur with this module, along with how to resolve the problem. For the full mod/plugin incompatibility list, see the compatibility page.

No plugin incompatibilities have been reported.

/checkjail
Module: jail
Checks if a player is jailed.

Aliases: /checkjail

Usage: /checkjail <user/UUID>|<user/UUID>

Default Role: MOD

Basic Command Permission: nucleus.jail.checkjail.base

Permissions

  • nucleus.jail.checkjail.base - Default Role: MOD
    Allows the user to run the command /checkjail
/checkjailed
Module: jail
Returns a list of currently jailed players, optionally in the specified jail.

Aliases: /checkjailed

Usage: /checkjailed [<jail>]

Default Role: ADMIN

Basic Command Permission: nucleus.checkjailed.base

Permissions

  • nucleus.checkjailed.base - Default Role: ADMIN
    Allows the user to run the command /checkjailed
/jail
Module: jail
Jails a player.

Aliases: /jail

Usage: /jail <user> [<jail>] [<duration>] [<reason…>]

Default Role: MOD

Basic Command Permission: nucleus.jail.base

Permissions

  • nucleus.jail.teleportjailed - Default Role: ADMIN
    Allows the player to teleport jailed players.
  • nucleus.jail.base - Default Role: MOD
    Allows the user to run the command /jail
  • nucleus.jail.offline - Default Role: MOD
    Allows the user to jail offline users.
  • nucleus.jail.teleporttojailed - Default Role: ADMIN
    Allows the player to teleport to jailed players.
  • nucleus.jail.notify - Default Role: MOD
    Notifies the user about jails when they occur.
  • nucleus.jail.exempt.target - Default Role: ADMIN
    Exempts the user from being jailed.

This command is similar to the following command(s) found in Essentials: /togglejail, /tjail, /jail

Essentials Migration Notes: This command is not a toggle.

/jails
Module: jail
Lists all jails.

Aliases: /jails

Usage: /jails

Default Role: MOD

Basic Command Permission: nucleus.jail.list.base

Permissions

  • nucleus.jail.list.base - Default Role: MOD
    Allows the user to run the command /jails list

This command is an equivalent to the following command(s) in Essentials: /jails

/jails delete
Module: jail
Deletes a jail.

Aliases: /jails delete, /jails del, /jails remove

Root command aliases: /deljail /ndeljail /rmjail /nrmjail /deletejail /ndeletejail

Usage: /jails delete <jail>

Default Role: ADMIN

Basic Command Permission: nucleus.jail.delete.base

Permissions

  • nucleus.jail.delete.base - Default Role: ADMIN
    Allows the user to run the command /jails delete

This command is an equivalent to the following command(s) in Essentials: /deljail, /remjail, /rmjail

/jails set
Module: jail
Creates a jail.

Aliases: /jails set

Root command aliases: /setjail /nsetjail /createjail /ncreatejail

Usage: /jails set <jail>

Default Role: ADMIN

Basic Command Permission: nucleus.jail.set.base

Permissions

  • nucleus.jail.set.base - Default Role: ADMIN
    Allows the user to run the command /jails set

This command is an equivalent to the following command(s) in Essentials: /setjail, /createjail

/jails tp
Module: jail
Warp to a jail.

Aliases: /jails tp

Usage: /jails tp <jail>

Default Role: MOD

Basic Command Permission: nucleus.jail.tp.base

Permissions

  • nucleus.jail.tp.base - Default Role: MOD
    Allows the user to run the command /jails tp
/unjail
Module: jail
Unjails a player.

Aliases: /unjail

Usage: /unjail <user>

Default Role: MOD

Basic Command Permission: nucleus.jail.unjail.base

Permissions

  • nucleus.jail.unjail - Default Role: MOD
    If set in config, this permission is required to unjail players.

This command is similar to the following command(s) found in Essentials: /unjail

Essentials Migration Notes: Not a toggle.

Permission Suggested Role Description
nucleus.checkjailed.base ADMIN Allows the user to run the command /checkjailed
nucleus.jail.base MOD Allows the user to run the command /jail
nucleus.jail.checkjail.base MOD Allows the user to run the command /checkjail
nucleus.jail.delete.base ADMIN Allows the user to run the command /jails delete
nucleus.jail.exempt.target ADMIN Exempts the user from being jailed.
nucleus.jail.list.base MOD Allows the user to run the command /jails list
nucleus.jail.notify MOD Notifies the user about jails when they occur.
nucleus.jail.offline MOD Allows the user to jail offline users.
nucleus.jail.set.base ADMIN Allows the user to run the command /jails set
nucleus.jail.teleportjailed ADMIN Allows the player to teleport jailed players.
nucleus.jail.teleporttojailed ADMIN Allows the player to teleport to jailed players.
nucleus.jail.tp.base MOD Allows the user to run the command /jails tp
nucleus.jail.unjail MOD If set in config, this permission is required to unjail players.
The following configuration is the default for this module:
                            # The commands that players are allowed to execute in jail. Do not include the slash.
allowed-commands=[
    m,
    msg,
    r,
    mail,
    rules,
    info
]
# If "use-permission-level" is true, players can only jail/unjail players that have a lower permission level than themselves.
# 
# The permission level for jailing is specified by adding the "nucleus.jail.level" permission option/meta to a player. Default level is 0 for players without the specified command permission, 1 with the permission.
jail-permission-levels {
    # If true, a player can affect another player that has the same level as them (that is, if both havea permission level of 1, they can act on each other). If false, then a higher level is necessary (someone with a level 1 canonly act upon a player with level 0 or below). 
    can-affect-same-level=false
    # If true, checks player level options as specified in the parent node.
    use-permission-level=false
}
# If true, jail time will only tick down when players are online.
jail-time-counts-online-only=false
# If true, the player will be muted when in jail.
mute-when-jailed=false
# If true, Nucleus will try much harder to disable player teleportation for players who are jailed.
prevent-teleport-when-jailed-aggressively=true
# If true, then the permission "nucleus.jail.unjail" is required to unjail players.
require-separate-unjail-permission=false

                        
Search

Downloading search database, this won't take long...