> For the complete documentation index, see [llms.txt](https://zitemaker.gitbook.io/jails/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zitemaker.gitbook.io/jails/configuration-and-customization/placeholders.md).

# 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.)

```yaml
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.)

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

#### Tab List (with TAB plugin)

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

#### Hologram (with HolographicDisplays, DecentHolograms)

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

#### Custom Menu (with DeluxeMenus)

```yaml
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.)

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

#### Boss Bar

```yaml
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](https://www.spigotmc.org/resources/placeholderapi.6245/)
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

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

#### Formatted Time Display

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

#### Server Statistics Dashboard

```yaml
# 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:

```java
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

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://zitemaker.gitbook.io/jails/configuration-and-customization/placeholders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.