> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.mrerrorx.dev/primaxbattleroyalex/llms.txt
> Use this file to discover all available pages before exploring further.

# PlaceholderAPI Integration for PrimaxBattleRoyaleX

> Use PrimaxBattleRoyaleX placeholders in any PAPI-compatible plugin — scoreboards, tab lists, chat formats, holograms, and more. Over 20 placeholders available.

<Warning>
  **Server requirements:** PrimaxBattleRoyaleX generates a fresh world for every match and deletes it once the match ends. World generation runs on the server's main thread, so a weak CPU or low RAM will cause noticeable lag. A quality managed Minecraft host or a dedicated VPS with a strong single-thread CPU and ample RAM is strongly recommended. Shared or budget hosting is not suitable.
</Warning>

PlaceholderAPI integration lets you display PrimaxBattleRoyaleX player stats anywhere on your server that supports PAPI. The expansion identifier is `primaxbr` and it registers automatically on startup — no manual download or `/papi ecloud download` command needed.

<Note>
  PlaceholderAPI must be installed **before** PrimaxBattleRoyaleX starts. Once both plugins are present, the `primaxbr` expansion registers itself with no extra steps required.
</Note>

***

## Available Placeholders

### General Statistics

| Placeholder                  | Description                        | Returns                 |
| ---------------------------- | ---------------------------------- | ----------------------- |
| `%primaxbr_kills%`           | Total kills across all game modes  | Integer (e.g., `42`)    |
| `%primaxbr_total_kills%`     | Same as `kills` (alternative)      | Integer                 |
| `%primaxbr_deaths%`          | Total deaths across all game modes | Integer                 |
| `%primaxbr_total_deaths%`    | Same as `deaths` (alternative)     | Integer                 |
| `%primaxbr_kd%`              | Kill/Death ratio                   | Decimal (e.g., `2.80`)  |
| `%primaxbr_kdr%`             | Same as `kd` (alternative)         | Decimal                 |
| `%primaxbr_killdeathsratio%` | Same as `kd` (full name)           | Decimal                 |
| `%primaxbr_total_wins%`      | Total wins (Solo + Squad combined) | Integer                 |
| `%primaxbr_total_matches%`   | Total matches played               | Integer                 |
| `%primaxbr_total_winrate%`   | Overall win rate percentage        | Decimal (e.g., `52.08`) |

### Solo Mode Statistics

| Placeholder               | Description                   | Returns |
| ------------------------- | ----------------------------- | ------- |
| `%primaxbr_solo_wins%`    | Number of Solo mode wins      | Integer |
| `%primaxbr_solo_losses%`  | Number of Solo mode losses    | Integer |
| `%primaxbr_solo_matches%` | Total Solo matches played     | Integer |
| `%primaxbr_solo_winrate%` | Solo mode win rate percentage | Decimal |

### Squad Mode Statistics

| Placeholder                | Description                    | Returns |
| -------------------------- | ------------------------------ | ------- |
| `%primaxbr_squad_wins%`    | Number of Squad mode wins      | Integer |
| `%primaxbr_squad_losses%`  | Number of Squad mode losses    | Integer |
| `%primaxbr_squad_matches%` | Total Squad matches played     | Integer |
| `%primaxbr_squad_winrate%` | Squad mode win rate percentage | Decimal |

### Deathmatch Statistics

| Placeholder                   | Description                             | Returns |
| ----------------------------- | --------------------------------------- | ------- |
| `%primaxbr_deathmatch_kills%` | Total Deathmatch kills                  | Integer |
| `%primaxbr_dm_kills%`         | Same as `deathmatch_kills` (short form) | Integer |

### Session / Status

| Placeholder                         | Description                         | Returns                                                              |
| ----------------------------------- | ----------------------------------- | -------------------------------------------------------------------- |
| `%primaxbr_in_match%`               | Is the player currently in a match? | `Yes` or `No`                                                        |
| `%primaxbr_in_match_bool%`          | Boolean version of `in_match`       | `true` or `false`                                                    |
| `%primaxbr_current_mode%`           | Current game mode (raw value)       | `SOLO`, `SQUAD`, `DEATHMATCH`, or `None`                             |
| `%primaxbr_current_mode_formatted%` | Current game mode (display name)    | `Solo Battle Royale`, `Squad Battle Royale`, `Deathmatch`, or `None` |

***

## Calculation Notes

Understanding how placeholder values are computed helps you display accurate stats and anticipate edge cases.

**K/D Ratio** (`%primaxbr_kd%` / `%primaxbr_kdr%` / `%primaxbr_killdeathsratio%`)

* If the player has **0 deaths**, the placeholder returns their total kill count (no division by zero).
* Otherwise: **Kills ÷ Deaths**, formatted to 2 decimal places (e.g., `2.80`).

**Win Rate** (`%primaxbr_total_winrate%` / `%primaxbr_solo_winrate%` / `%primaxbr_squad_winrate%`)

* Calculated as **(Wins ÷ Total Matches) × 100**, formatted to 2 decimal places.
* Returns `0.00` if the player has played no matches in that category.

**Missing or Offline Players**

* If a player has **no stored data** (never played), all placeholders return `"0"`.
* If a player is **offline**, all placeholders return an empty string `""`.

***

## Usage Examples

The examples below show how to wire `primaxbr` placeholders into common PAPI-compatible plugins.

<CodeGroup>
  ```yaml Scoreboard (FeatherBoard / similar) theme={null}
  board:
    title: '&6&lBattle Royale Stats'
    lines:
      - ''
      - '&eKills: &f%primaxbr_kills%'
      - '&eDeaths: &f%primaxbr_deaths%'
      - '&eK/D Ratio: &f%primaxbr_kd%'
      - ''
      - '&6Solo Stats'
      - '&eWins: &f%primaxbr_solo_wins%'
      - '&eWinrate: &f%primaxbr_solo_winrate%%'
      - ''
      - '&cSquad Stats'
      - '&eWins: &f%primaxbr_squad_wins%'
      - '&eWinrate: &f%primaxbr_squad_winrate%%'
      - ''
  ```

  ```yaml Tab List Plugin theme={null}
  header:
    - '&6&lBattle Royale Server'
    - '&7Kills: &f%primaxbr_kills% &8| &7Deaths: &f%primaxbr_deaths%'
    - '&7K/D: &f%primaxbr_kd%'
  ```

  ```yaml Chat Format Plugin theme={null}
  format: '&7[&e%primaxbr_solo_wins%&7W] &f%player_name%&7: &f%message%'
  ```
</CodeGroup>

<Tip>
  You can combine `%primaxbr_current_mode_formatted%` and `%primaxbr_in_match%` in scoreboards to show a live match status line that updates while the player is in a game.
</Tip>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Placeholders are showing as literal text (e.g., %primaxbr_kills%)">
    The placeholder is not being parsed. Work through these checks in order:

    1. **Confirm PlaceholderAPI is installed** — run `/plugins` in-game and look for `PlaceholderAPI` highlighted in green.
    2. **Check the expansion is registered** — run `/papi list` and look for `primaxbr` in the output. If it is missing, see the next accordion.
    3. **Test parsing directly** — run `/papi parse me %primaxbr_kills%`. If this returns a number, the placeholder itself works and the issue is with your other plugin's PAPI hook.
    4. **Verify the other plugin supports PAPI** — not every plugin that accepts text also parses PAPI placeholders. Check that plugin's documentation for PAPI support.
  </Accordion>

  <Accordion title="All placeholders return 0">
    The expansion is registered correctly but no data is being found for the player.

    1. **Player data may not be loaded yet** — this can happen on fresh joins. Ask the player to fully disconnect and reconnect, then retest.
    2. **Verify the data file exists** — check that `plugins/PrimaxBattleRoyaleX/data.yml` is present on your server. If it is missing, the plugin may not have initialised correctly; check your console for errors on startup.
    3. **New players** — a brand-new player who has never played a match will legitimately return `0` for all stat placeholders. This is expected behaviour.
  </Accordion>

  <Accordion title="Expansion not registering (missing from /papi list)">
    The `primaxbr` expansion registers during PrimaxBattleRoyaleX's startup sequence. If it is absent:

    1. **Load order** — PlaceholderAPI **must** be present and fully enabled before PrimaxBattleRoyaleX initialises. Check your startup log to confirm PlaceholderAPI loads first.
    2. **Check the console** — a successful registration prints `✓ PlaceholderAPI expansion registered` to the console. Search your latest log for this line.
    3. **Reload PlaceholderAPI** — run `/papi reload` to force re-registration, then check `/papi list` again.
    4. **Restart the server** — a full server restart (not `/reload`) is the most reliable way to ensure correct plugin load order.
  </Accordion>
</AccordionGroup>