> ## Documentation Index
> Fetch the complete documentation index at: https://jppmc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# JPPrison PlaceholderAPI Variables: Complete Reference

> Every %jpprison_% PlaceholderAPI variable: stats, economies, enchants, momentum, boosts, armor, autominer, minions, and server tops with examples.

JPPrison exposes its data through PlaceholderAPI under the fixed identifier `jpprison`. Use `%jpprison_<variable>%` in scoreboards, chat, holograms, menus, MOTDs, and tablists. All placeholders are read-only.

> [!NOTE]
>
> Requires PlaceholderAPI installed on the server. Without it, placeholders render as literal text. If the player is `null` or the placeholder does not exist, the return is an empty string.

## Format Conventions

```text Placeholder anatomy theme={null}
%jpprison_blocks_mined%
 ^^^^^^^^ ^^^^^^^^^^^^^
 |        |
 |        +- variable name
 +- fixed expansion identifier ("jpprison")
```

> [!NOTE]
>
> **Abbreviated numbers.** Suffixes `_raw` and `_formatted` use short format (1.25K, 3.4M, 2B). Values without a suffix (`blocks_mined`, `pickaxe_xp`) are exact. Economy balances (`%jpprison_tokens%`) use `Economy.format()`: symbol + decimals per `economies/<id>.yml`.

## 1. Player Stats (Mining / Pickaxe)

| Placeholder | Returns | Example |
| - | - | - |
| `%jpprison_blocks_mined%` | Total blocks mined (exact). | `15234` |
| `%jpprison_blocks_mined_formatted%` | Same, abbreviated. | `15.23K` |
| `%jpprison_pickaxe_level%` | Current pickaxe level. | `27` |
| `%jpprison_pickaxe_xp%` | Current pickaxe XP (exact). | `89350` |
| `%jpprison_pickaxe_xp_formatted%` | Abbreviated. | `89.35K` |
| `%jpprison_pickaxe_xp_needed%` | Total XP threshold for next level (exact). | `102400` |
| `%jpprison_pickaxe_xp_needed_formatted%` | Abbreviated. | `102.4K` |
| `%jpprison_pickaxe_progress%` | Progress bar to next level. Respects `pickaxe.progress-bar.length/filled/empty` and player theme colors. At max level shows full bar. | `‖‖‖‖‖‖‖‖‖‖‖‖‖‖‖‖‖‖‖‖` |
| `%jpprison_pickaxe_progress_percent%` | Percent of progress. At max level returns `100%`. | `63%` |
| `%jpprison_pickaxe_color%` | Pickaxe theme/color ID (DB value from `getLoreColor`). | `default`, `red` |
| `%jpprison_pickaxe_color_name%` | Display name of the theme (colors translated, no `&`). | `Red` (in red) |
| `%jpprison_pickaxe_prestige%` | Global pickaxe prestige. | `3` |

> [!WARNING]
>
> `xp_needed` is the **threshold**, not the delta. For the amount remaining, compute `xp_needed - xp` yourself.

## 2. Economies (Dynamic per `/economies/*.yml`)

Default IDs: `tokens`, `gems` (plus `money` if Vault is present). Adding `economies/keys.yml` automatically enables `%jpprison_keys%`, etc. IDs are lowercase.

For each `<eco>` (example with `tokens`):

**%jpprison\_tokens%** `string`

Formatted balance (symbol + decimals per its YAML). Example: `1,250 Tokens`.

**%jpprison\_tokens\_formatted%** `string`

Exact alias of the above.

**%jpprison\_tokens\_raw%** `string`

Abbreviated balance without symbol. Example: `1250000` → `1.25M`.

**%jpprison\_tokens\_symbol%** `string`

Economy symbol (`symbol` field in YAML). Example: `$`, `T`.

**%jpprison\_tokens\_name%** `string`

Display name (`name` field in YAML). Example: `Tokens`, `Gems`.

**%jpprison\_tokens\_boost\_active%** `boolean`

`true` while an economy boost is active and paying above x1 for that player and that eco. Otherwise `false`. Activated by `/tokens <player|global> <mult> <time>`.

```text Economy examples theme={null}
Tokens: %jpprison_tokens% (%jpprison_tokens_raw%)
Gems: %jpprison_gems% | Active x2: %jpprison_gems_boost_active%
Money: %jpprison_money%
```

### Vault Special Case

For money handled by other plugins (Essentials, CMI, ...):

| Placeholder | Returns |
| - | - |
| `%jpprison_vault_name%` | Vault currency name. Defaults to `Money` without Vault. |
| `%jpprison_vault_money%` | Formatted Vault balance. Alias: `%jpprison_vault_money_formatted%`. Returns `0` without Vault. |
| `%jpprison_vault_money_raw%` | Abbreviated Vault balance (`1.5K`, `2M`). `0` without Vault. |

### Autosell State

**%jpprison\_autosell%** `boolean`

`true` if the player has `/autosell` enabled, `false` otherwise.

## 3. Enchantments (Dynamic per `/enchants/*.yml`)

Default 35 enchants: `efficiency`, `fortune`, `speed`, `haste`, `night-vision`, `jump`, `token-finder`, `gem-finder`, `xp-finder`, `lucky`, `greed`, `greed-money`, `overflow`, `blessed`, `key-finder`, `key-all`, `token-merchant`, `explosive`, `jackhammer`, `layer`, `nuke`, `thunder`, `meteor`, `cross`, `solar`, `frost-nova`, `geyser`, `soul-spiral`, `comet`, `volcano`, `blackhole`, `aurora`, `sandstorm`, `apocalypse`, `momentum`.

For each `<id>` (example with `fortune`):

| Placeholder | Returns |
| - | - |
| `%jpprison_fortune_level%` | Player's current level (0 = not purchased). |
| `%jpprison_fortune_max_level%` | Base max level from YAML (no prestige). |
| `%jpprison_fortune_effective_max_level%` | Real max with prestige (`max-level-bonus`). |
| `%jpprison_fortune_prestige%` | Prestige of that enchant. |
| `%jpprison_fortune_activations%` | Activation counter. |
| `%jpprison_fortune_disabled%` | `true`/`false`: player toggled it off. |
| `%jpprison_fortune_virtual%` | `true` if in virtual mode (does not break blocks). |
| `%jpprison_fortune_muted%` | `true` if messages are muted. |
| `%jpprison_fortune_chance%` | Real activation chance at current level (with prestige). One decimal, no `%`. Example: `12.5`. Add `%` yourself in the text. |
| `%jpprison_fortune_next_cost%` | Exact cost of the next level (shards/cost discount and prestige applied). `0` at max. |
| `%jpprison_fortune_next_cost_formatted%` | Abbreviated (`13K`). |
| `%jpprison_fortune_upgrade_economy%` | Economy used for upgrades (`upgrade-economy` in YAML). Destructive enchants usually use `gems`. |

> [!WARNING]
>
> IDs with a hyphen (`token-finder`, `frost-nova`, ...) are written with the hyphen: `%jpprison_token-finder_level%`. Do not swap `-` for `_`.

```text Enchant examples theme={null}
Fortune: %jpprison_fortune_level%/%jpprison_fortune_max_level% (real max %jpprison_fortune_effective_max_level%)
Explosive: level %jpprison_explosive_level% | chance %jpprison_explosive_chance%% | prestige %jpprison_explosive_prestige%
Upgrade Lucky: %jpprison_lucky_next_cost_formatted% %jpprison_lucky_upgrade_economy%
Token Finder off: %jpprison_token-finder_disabled%
```

## 4. Enchant Summary Counters

| Placeholder | Returns |
| - | - |
| `%jpprison_enchant_count%` | How many enchants are at level > 0. |
| `%jpprison_total_levels%` | Sum of ALL enchant levels. |
| `%jpprison_maxed_count%` | How many enchants are at base max. |

## 5. Momentum (Mining Combo)

| Placeholder | Returns |
| - | - |
| `%jpprison_momentum_multiplier%` | Current multiplier with `x` prefix. Example: `x2.50`. Reading it does not extend the combo. |
| `%jpprison_momentum_multiplier_raw%` | Same without the `x`. Example: `2.50`. |
| `%jpprison_momentum_active%` | `true` if the combo is alive, `false` if expired. |

## 6. XP Boost

Activated by `/xpboost <player|global> <mult> <time>`.

| Placeholder | Returns |
| - | - |
| `%jpprison_xpboost_multiplier%` | Multiplier with `x`. Without a boost: `x1.00`. |
| `%jpprison_xpboost_remaining%` | Remaining minutes (integer). |
| `%jpprison_xpboost_active%` | `true` only while paying above x1. Use it to hide the line when no boost is active (avoids a dead `x1.00`). |

## 7. Armor Sets (`/armor`)

| Placeholder | Returns |
| - | - |
| `%jpprison_armor%` | Equipped set ID. Empty if none. |
| `%jpprison_armor_name%` | Display name without color codes. Empty if none. |
| `%jpprison_armor_level%` | Level of the equipped set (`0` if none). |
| `%jpprison_armor_count%` | How many sets are unlocked. |

## 8. Autominer

| Placeholder | Returns |
| - | - |
| `%jpprison_autominer_active%` | `true` if your clone is mining. |
| `%jpprison_autominer_time%` | Stored time formatted (`1h 2m`, `45s`, `0s`). |
| `%jpprison_autominer_time_seconds%` | Same in exact seconds. |

## 9. Minions (Dynamic per `/minions/*.yml`)

Default IDs: `zombie`, `pigman`, `villager`.

| Placeholder | Returns |
| - | - |
| `%jpprison_minions_active%` | How many mobs are deployed. |
| `%jpprison_minion_active_<id>%` | `true` if that mob is deployed. |
| `%jpprison_minion_time_<id>%` | Stored time formatted (`30m`, `45s`). |
| `%jpprison_minion_time_seconds_<id>%` | Time in exact seconds. |

```text Minion examples theme={null}
Minions out: %jpprison_minions_active%/3
Zombie: %jpprison_minion_time_zombie% (%jpprison_minion_active_zombie%)
```

## 10. Your Rank (Includes Offline, Direct SQL)

Returns your 1-based rank. If you have no data, your position still counts.

| Placeholder | Returns |
| - | - |
| `%jpprison_top_blocks%` | Rank in blocks mined. |
| `%jpprison_top_xp%` | Rank in pickaxe XP. |
| `%jpprison_top_<eco-id>%` | Rank in that economy (`top_tokens`, `top_gems`, `top_money`, `top_keys`, ...). |

## 11. Server Tops (Name + Value, Top 1-10, 30s Cache)

Format: `%jpprison_top_<what>_<n>_name%` and `%jpprison_top_<what>_<n>_value%`.

* `<what>` = `blocks` | `xp` | `<eco-id>` (`tokens`, `gems`, `money`, ...)
* `<n>` = 1 to 10 (outside the range returns empty)
* Refreshed every 30 seconds (cache). Empty if no data.
* `_name` = player name (or truncated UUID if unresolved).
* `_value` = formatted value (abbreviated for blocks/xp, `Economy.format` for economies).

```text Top examples theme={null}
#1 Blocks: %jpprison_top_blocks_1_name% (%jpprison_top_blocks_1_value%)
#1 XP: %jpprison_top_xp_1_name% (%jpprison_top_xp_1_value%)
#1 Tokens: %jpprison_top_tokens_1_name% (%jpprison_top_tokens_1_value%)
#3 Gems: %jpprison_top_gems_3_name% (%jpprison_top_gems_3_value%)
```

Ready-to-paste top-tokens hologram:

```text Top Tokens hologram theme={null}
&6&lTOP TOKENS
&e#1 &f%jpprison_top_tokens_1_name% &7- &b%jpprison_top_tokens_1_value%
&e#2 &f%jpprison_top_tokens_2_name% &7- &b%jpprison_top_tokens_2_value%
&e#3 &f%jpprison_top_tokens_3_name% &7- &b%jpprison_top_tokens_3_value%
&e#4 &f%jpprison_top_tokens_4_name% &7- &b%jpprison_top_tokens_4_value%
&e#5 &f%jpprison_top_tokens_5_name% &7- &b%jpprison_top_tokens_5_value%
```

## 12. Ready-to-Use Examples

**Scoreboard**

```text Scoreboard lines theme={null}
&7Blocks: &f%jpprison_blocks_mined_formatted% (#%jpprison_top_blocks%)
&7Level: &d%jpprison_pickaxe_level% &8(%jpprison_pickaxe_progress_percent%)
%jpprison_pickaxe_progress%
&bTokens: &f%jpprison_tokens%
&aGems: &f%jpprison_gems%
&6Money: &f%jpprison_vault_money%
&eCombo: &f%jpprison_momentum_multiplier%
&bXP Boost: &f%jpprison_xpboost_multiplier%
```

**Welcome / Profile**

```text Chat profile theme={null}
Level %jpprison_pickaxe_level% | %jpprison_total_levels% levels across %jpprison_enchant_count% enchants
Prestige %jpprison_pickaxe_prestige% | Theme %jpprison_pickaxe_color_name%
Fortune %jpprison_fortune_level%/%jpprison_fortune_max_level% - next: %jpprison_fortune_next_cost_formatted%
```

**Tablist (TAB plugin)**

```yaml TAB header/footer theme={null}
header:
  - "&d&lJPPRISON"
  - "&7Tokens: &b%jpprison_tokens% &8| &7Gems: &a%jpprison_gems%"
footer:
  - "&7Blocks #%jpprison_top_blocks% | Combo %jpprison_momentum_multiplier%"
```

**Hologram (DecentHolograms)**

```text Stats hologram theme={null}
&d&lYOUR PICKAXE
&7Level: &f%jpprison_pickaxe_level% &8(%jpprison_pickaxe_progress_percent%)
&7Tokens: &b%jpprison_tokens% &8(#%jpprison_top_tokens%)
&7Combo: &e%jpprison_momentum_multiplier%
```

## 13. Common Errors

> **I see `%jpprison_tokens%` as literal text**
>
> PlaceholderAPI is not installed, or the ID is misspelled. Check `/economies/*.yml` and `/enchants/*.yml` — everything is lowercase.

> **Returns empty string**
>
> The enchant/economy does not exist, `n = 0` or `11+` in tops, or the player is offline for a player-scoped placeholder (server tops work without an online player).

> **The top does not update instantly**
>
> Expected. Server tops cache for 30 seconds.

> **I want `%` after chance**
>
> The chance placeholder does not include `%` (returns `12.5`). Add it yourself: `%jpprison_lucky_chance%%` renders as `12.5%`.

> **IDs with hyphens**
>
> Write them with the hyphen exactly: `%jpprison_token-finder_level%` (never with `_`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.