Placeholders

PlaceholderAPI Integration

Overview

Both Jails and JailsPlus support PlaceholderAPI, allowing you to display jail-related information in scoreboards, chat, holograms, and other plugins that support PlaceholderAPI placeholders.

Available Placeholders

All placeholders use the jails identifier. Use them in any PlaceholderAPI-compatible plugin with the format %jails_<placeholder>%.

Total Placeholders: 48

Player Status Placeholders

These placeholders require a player context and show individual player information.

Placeholder	Description	Example Output
%jails_isjailed%	Returns true/false if player is currently jailed	true or false
%jails_ishandcuffed%	Returns true/false if player is currently handcuffed	true or false
%jails_jailname%	Returns the name of the jail where player is imprisoned	Prison1 or empty if not jailed
%jails_reason%	Returns the reason for being jailed	Griefing or No reason
%jails_jailer%	Returns the name of who jailed the player	Admin123 or Unknown
%jails_jail_status%	Returns current jail status	FREE, JAILED, PERMANENT, or EXPIRED
%jails_spawn_option%	Returns where player will spawn after unjail	world_spawn or original_location

Time-based Placeholders

Display remaining jail time in various formats.

Placeholder	Description	Example Output
%jails_timeleft%	Returns formatted time remaining (human-readable)	2 days, 5 hours, 30 minutes
%jails_timeleft_seconds%	Returns time remaining in seconds	189000 or -1 for permanent
%jails_timeleft_minutes%	Returns time remaining in minutes	3150 or -1 for permanent
%jails_timeleft_hours%	Returns time remaining in hours	52 or -1 for permanent
%jails_timeleft_days%	Returns time remaining in days	2 or -1 for permanent
%jails_endtime_timestamp%	Returns Unix timestamp when jail ends	1729329600000 or 0
%jails_jailtime_percentage%	Returns percentage of jail time served	75 (0-100)

Note: Time placeholders return PERMANENT or -1 for permanent jails, and Expired or 0 for expired sentences.

Location Placeholders

Display jail and original location information.

Placeholder	Description	Example Output
%jails_jail_location%	Returns full jail location	world 100 64 200
%jails_jail_location_world%	Returns jail world name	world
%jails_jail_location_x%	Returns jail X coordinate	100
%jails_jail_location_y%	Returns jail Y coordinate	64
%jails_jail_location_z%	Returns jail Z coordinate	200
%jails_original_location%	Returns player's pre-jail location	world 500 70 -300
%jails_original_location_world%	Returns original world name	world

Bail System Placeholders

Display bail information (requires Vault and economy plugin).

Placeholder	Description	Example Output
%jails_bail%	Returns formatted bail amount	$5000.00 or No bail set
%jails_bail_raw%	Returns raw bail amount (number only)	5000.0 or 0
%jails_hasbail%	Returns true/false if bail is set	true or false

IP Jail Placeholders

Placeholder	Description	Example Output
%jails_isipjailed%	Returns true/false if player's IP is jailed	true or false

Note: This placeholder requires the player to be online.

Server Statistics Placeholders

These placeholders don't require a player context and show server-wide statistics.

Placeholder	Description	Example Output
%jails_totalcount%	Total number of currently jailed players	5
%jails_handcuffed_count%	Total number of currently handcuffed players	2
%jails_jail_count%	Total number of jail locations configured	3
%jails_flag_count%	Total number of flag zones configured	4
%jails_ipjail_count%	Total number of IP-jailed addresses	1

List Placeholders

Get lists of jails, flags, and players (newline-separated).

Placeholder	Description	Example Output
%jails_jails_list%	List of all jail names (newline-separated)	Prison1\nPrison2\nJail3
%jails_jails_list_comma%	List of all jail names (comma-separated)	Prison1, Prison2, Jail3
%jails_flags_list%	List of all flag names (newline-separated)	Flag1\nFlag2\nFlag3
%jails_flags_list_comma%	List of all flag names (comma-separated)	Flag1, Flag2, Flag3
%jails_jailed_players_list%	List of all jailed player names (newline-separated)	Player1\nPlayer2\nPlayer3
%jails_jailed_players_list_comma%	List of all jailed player names (comma-separated)	Player1, Player2, Player3
%jails_handcuffed_players_list%	List of all handcuffed player names (newline-separated)	Player1\nPlayer2
%jails_handcuffed_players_list_comma%	List of all handcuffed player names (comma-separated)	Player1, Player2

Per-Jail Statistics Placeholders

Get the count of players in a specific jail. Use the format jail_<jailname>_count.

Placeholder	Description	Example Output
%jails_jail_<jailname>_count%	Number of players in specified jail	3

Examples:

• %jails_jail_Prison1_count% - Returns count in "Prison1"

• %jails_jail_MainJail_count% - Returns count in "MainJail"

• %jails_jail_spawn_count% - Returns count in "spawn"

Usage Examples

Scoreboard (with DeluxeScoreboard, FeatherBoard, etc.)

lines:
  - "&6=== Jail Status ==="
  - "&eJailed: &f%jails_isjailed%"
  - "&eJail: &f%jails_jailname%"
  - "&eTime Left: &f%jails_timeleft%"
  - "&eBail: &f%jails_bail%"
  - ""
  - "&7Total Jailed: &f%jails_totalcount%"

Chat Format (with ChatControl, EssentialsChat, etc.)

format: "[%jails_jailname%] {player}: {message}"
# Shows jail name in brackets before player's message

Tab List (with TAB plugin)

tabprefix: "%jails_isjailed% == true ? &c[JAILED] : ''"
# Shows [JAILED] prefix if player is jailed

Hologram (with HolographicDisplays, DecentHolograms)

lines:
  - "&c&lJAIL STATISTICS"
  - "&eJailed Players: &f%jails_totalcount%"
  - "&eHandcuffed: &f%jails_handcuffed_count%"
  - "&eTotal Jails: &f%jails_jail_count%"

Custom Menu (with DeluxeMenus)

items:
  jail_status:
    material: IRON_BARS
    display_name: "&cYour Jail Status"
    lore:
      - "&7Status: %jails_isjailed%"
      - "&7Jail: %jails_jailname%"
      - "&7Time Left: %jails_timeleft%"
      - "&7Bail: %jails_bail%"

Action Bar (with ActionBarAPI, CMI, etc.)

message: "&c⚠ Jailed in %jails_jailname% | Time: %jails_timeleft%"

Boss Bar

title: "&c&lJAILED: %jails_timeleft% remaining"
# Shows remaining time in boss bar

Conditional Placeholders

You can use PlaceholderAPI's conditional system with JailsPlus placeholders:

Using ParseOther

%parseother_{player}_jails_isjailed%
# Check if another player is jailed

Using Conditions (with PAPI expansion)

%jails_isjailed% == true ? &c[JAILED] : &a[FREE]
# Shows [JAILED] in red or [FREE] in green

Testing Placeholders

Use these commands to test placeholders in-game:

/papi parse me %jails_isjailed%
/papi parse me %jails_jailname%
/papi parse me %jails_timeleft%
/papi parse me %jails_totalcount%

Troubleshooting

Placeholders show as raw text

Problem: %jails_isjailed% appears literally instead of showing true/false

Solutions:

1. Verify PlaceholderAPI is installed: /papi version

2. Check expansion is registered: /papi list (look for "jails")

3. Ensure the plugin supports PlaceholderAPI

4. Try /papi reload to refresh expansions

Placeholders return empty or incorrect values

Problem: Placeholder doesn't show expected value

Solutions:

1. Verify player is actually jailed: /jails list prisoners

2. Check placeholder spelling (case-sensitive)

3. Ensure player context is available (player-specific placeholders need a player)

4. Review server logs for errors

Expansion not registering

Problem: Console shows "PlaceholderAPI not found - placeholder support disabled"

Solutions:

1. Install PlaceholderAPI from SpigotMC

2. Ensure it's version 2.11.6 or higher

3. Restart the server (don't just reload)

4. Check for startup errors in console

Time placeholders show wrong format

Problem: Time shows as seconds instead of formatted string

Solutions:

1. Use %jails_timeleft% for human-readable format

2. Use %jails_timeleft_seconds%, _minutes%, or _hours% for specific units

3. Remember: -1 means permanent jail, 0 means expired

Advanced Usage

Multiple Conditions

# Show different messages based on bail status
lore:
  - "%jails_hasbail% == true ? &eBail: %jails_bail% : &cNo bail available"

Formatted Time Display

# Custom time format in menus
lore:
  - "&7Time Left:"
  - "&f%jails_timeleft_hours% hours"
  - "&f%jails_timeleft_minutes% minutes remaining"

Server Statistics Dashboard

# Complete server overview
hologram:
  - "&6&l⚔ JAIL STATISTICS ⚔"
  - ""
  - "&e━━━━━━━━━━━━━━━━━━━━"
  - "&fJailed Players: &c%jails_totalcount%"
  - "&fHandcuffed: &6%jails_handcuffed_count%"
  - "&fJail Locations: &a%jails_jail_count%"
  - "&fFlag Zones: &b%jails_flag_count%"
  - "&e━━━━━━━━━━━━━━━━━━━━"

API for Developers

If you're a plugin developer, you can use PlaceholderAPI to get JailsPlus data programmatically:

import me.clip.placeholderapi.PlaceholderAPI;

// get placeholder value for a player
Player player = ...;
String isJailed = PlaceholderAPI.setPlaceholders(player, "%jails_isjailed%");
String jailName = PlaceholderAPI.setPlaceholders(player, "%jails_jailname%");
String timeLeft = PlaceholderAPI.setPlaceholders(player, "%jails_timeleft%");

// get server statistics, a player isnt needed here
String totalJailed = PlaceholderAPI.setPlaceholders(null, "%jails_totalcount%");

Support

If you encounter issues with placeholders:

1. Check this documentation first

2. Verify PlaceholderAPI is installed and updated

3. Review server console for errors

4. Contact plugin support with relevant logs

---