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

# BattleRoyaleX PlaceholderAPI Integration and Reference

> Full reference for all %primaxbr_*% PlaceholderAPI placeholders — stats, session info, and usage examples for scoreboards, tab lists, and holograms.

PrimaxBattleRoyaleX automatically registers a PlaceholderAPI expansion using the identifier `primaxbr`. Once registered, you can drop any `%primaxbr_*%` placeholder into any PAPI-compatible plugin — scoreboards, tab lists, holograms, chat formatters, and more — and it will display live player data without any additional configuration.

***

## Installation

<Steps>
  <Step title="Install PlaceholderAPI">
    Download and place PlaceholderAPI on your server. Make sure it loads successfully before proceeding.
  </Step>

  <Step title="Install PrimaxBattleRoyaleX">
    Add the BattleRoyaleX jar to your plugins folder. It **must** load after PlaceholderAPI — place it after PAPI is confirmed working.
  </Step>

  <Step title="Start the server">
    On startup, BattleRoyaleX detects PlaceholderAPI and registers its `primaxbr` expansion automatically. No commands or downloads are required.
  </Step>

  <Step title="Verify the expansion">
    Run `/papi list` in-game or in the console. You should see `primaxbr` in the list of active expansions.
  </Step>
</Steps>

***

## Available Placeholders

### General Statistics

These placeholders reflect a player's cumulative stats across all game modes.

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

### Solo Mode Statistics

| Placeholder               | Description                   | Return Type |
| ------------------------- | ----------------------------- | ----------- |
| `%primaxbr_solo_wins%`    | Solo mode wins                | Integer     |
| `%primaxbr_solo_losses%`  | Solo mode losses              | Integer     |
| `%primaxbr_solo_matches%` | Solo matches played           | Integer     |
| `%primaxbr_solo_winrate%` | Solo win rate as a percentage | Decimal     |

### Squad Mode Statistics

| Placeholder                | Description                    | Return Type |
| -------------------------- | ------------------------------ | ----------- |
| `%primaxbr_squad_wins%`    | Squad mode wins                | Integer     |
| `%primaxbr_squad_losses%`  | Squad mode losses              | Integer     |
| `%primaxbr_squad_matches%` | Squad matches played           | Integer     |
| `%primaxbr_squad_winrate%` | Squad win rate as a percentage | Decimal     |

### Deathmatch Statistics

| Placeholder                   | Description                             | Return Type |
| ----------------------------- | --------------------------------------- | ----------- |
| `%primaxbr_deathmatch_kills%` | Total kills in Deathmatch mode          | Integer     |
| `%primaxbr_dm_kills%`         | Same as `deathmatch_kills` (short name) | Integer     |

### Session / Status

These placeholders reflect a player's current in-game state and update in real time.

| Placeholder                         | Description                        | Return Type                                                          |
| ----------------------------------- | ---------------------------------- | -------------------------------------------------------------------- |
| `%primaxbr_in_match%`               | Whether the player is in a match   | `Yes` or `No`                                                        |
| `%primaxbr_in_match_bool%`          | Boolean version of in-match status | `true` or `false`                                                    |
| `%primaxbr_current_mode%`           | Raw current game mode              | `SOLO`, `SQUAD`, `DEATHMATCH`, or `None`                             |
| `%primaxbr_current_mode_formatted%` | Human-readable current game mode   | `Solo Battle Royale`, `Squad Battle Royale`, `Deathmatch`, or `None` |

***

## Usage Examples

<CodeGroup>
  ```yaml Scoreboard (FeatherBoard) 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%%'
  ```

  ```yaml Tab List (TAB 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 (ChatControl) theme={null}
  format: '&7[&e%primaxbr_solo_wins%&7W] &f%player_name%&7: &f%message%'
  ```
</CodeGroup>

***

## Special Notes

* **K/D Ratio** — If a player has zero deaths, the placeholder returns their total kill count instead of dividing by zero. Otherwise, it returns kills ÷ deaths formatted to two decimal places (e.g. `2.80`).
* **Win Rate** — Calculated as (wins ÷ total matches) × 100. Returns `0.00` if the player has not completed any matches yet.
* **No player data** — Returns `"0"` for any stat placeholder when no data exists for that player.
* **Offline player** — Returns an empty string (`""`) when the target player is offline.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Placeholders showing as text (e.g., %primaxbr_kills%)">
    This means PlaceholderAPI is not parsing the placeholder. Work through these steps:

    1. Confirm PlaceholderAPI is installed and enabled — run `/papi info` to check.
    2. Run `/papi list` and look for `primaxbr` in the output. If it is missing, the expansion did not register.
    3. Test directly with `/papi parse me %primaxbr_kills%`. If this returns a number, the issue is with the third-party plugin's PAPI integration, not BattleRoyaleX.
    4. Ensure the plugin or config you are editing actually supports PlaceholderAPI.
  </Accordion>

  <Accordion title="All placeholders returning '0'">
    Player data may not have loaded yet, or may not exist. Try the following:

    1. Have the affected player leave the server and rejoin — this triggers a fresh data load.
    2. Check that `data.yml` exists in the BattleRoyaleX plugin folder and is not empty.
    3. Review the console for any errors logged by BattleRoyaleX during startup.
    4. Confirm the player has actually completed at least one match — brand new players will legitimately return `0` for all stats.
  </Accordion>

  <Accordion title="Expansion not registering">
    If `/papi list` does not show `primaxbr`, the expansion failed to register at startup.

    1. Verify that PlaceholderAPI loaded **before** BattleRoyaleX. If plugin load order is uncertain, restart the server with only PAPI active first, then add BattleRoyaleX.
    2. Run `/papi reload` after both plugins are loaded to force a re-registration attempt.
    3. Check the server console for a line confirming `[BattleRoyaleX] Registered PlaceholderAPI expansion`. If it is absent, look for an error in the startup log.
    4. Confirm you are running a supported version of PlaceholderAPI (2.x or later).
  </Accordion>
</AccordionGroup>