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

# PrimaxBattleRoyaleX Migration Guide: v1.x to v2.0.0

> Step-by-step migration guide from PrimaxBattleRoyaleX v1.x to v2.0.0. Covers config changes, preserved player stats, and required reconfiguration steps.

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

PrimaxBattleRoyaleX v2.0.0 is a complete rewrite and is **NOT backwards compatible** with v1.x. Config files, folder structure, and settings have all changed significantly. Follow this guide to migrate safely while preserving your players' statistics.

<Warning>
  **v2.0.0 is NOT backwards compatible.** Do not drop the new JAR over your existing v1.x installation without following this guide — your old configuration will not work and may cause errors on startup.
</Warning>

## Before You Start

Review what changes and what carries over before you begin.

**What changes in v2.0:**

* **Config structure** — the single `config.yml` from v1.x has been split into four dedicated files: `config.yml`, `messages.yml`, `game-settings.yml`, and `world-settings.yml`
* **Queue system** — the queue has been rebuilt with improvements and new options
* **Spawn and lobby locations** — stored location data does not transfer and must be re-set

**What is preserved:**

* **Player statistics** — `data.yml` player stats are automatically migrated by v2.0 on first startup

**Downtime required:**

* Yes — a full server restart is required to complete the migration

***

## Migration Steps

<Steps>
  <Step title="Back up your server">
    Copy your entire `plugins/PrimaxBattleRoyaleX/` folder to a safe location **before making any changes**. Pay special attention to `data.yml` — this file holds all player statistics.

    ```text theme={null}
    plugins/
    └── PrimaxBattleRoyaleX/   ← copy this entire folder
        ├── config.yml
        ├── data.yml            ← especially this file
        └── ...
    ```
  </Step>

  <Step title="Remove the old JAR">
    Delete the v1.x `PrimaxBattleRoyaleX` JAR file from your `/plugins` directory. Do **not** start the server until the new JAR is in place.
  </Step>

  <Step title="Install the v2.0.0 JAR">
    Place `PrimaxBattleRoyaleX-2.0.0.jar` into your `/plugins` directory. Do not start the server yet.
  </Step>

  <Step title="Restart the server">
    Start (or restart) your server. PrimaxBattleRoyaleX v2.0 will automatically generate all new config files with default values and handle the migration of `data.yml` player statistics.

    Confirm in the console that you see:

    ```text theme={null}
    ✓ PlaceholderAPI expansion registered
    ```
  </Step>

  <Step title="Reconfigure your settings">
    Your v1.x settings **will not carry over** — you must recreate them in the new config files. The v1.x `config.yml` has been split into four files:

    | File                 | Contents                             |
    | -------------------- | ------------------------------------ |
    | `config.yml`         | Core plugin settings                 |
    | `messages.yml`       | All player-facing messages           |
    | `game-settings.yml`  | Game mode, squad, and match settings |
    | `world-settings.yml` | World generation and border settings |

    Open each file and configure it to match your previous v1.x setup.
  </Step>

  <Step title="Set spawn and lobby locations">
    Location data does not transfer automatically. Stand at your desired positions and run the commands to re-register them:

    * **`/brsetspawn`** — sets the in-game spawn point
    * **`/brsetlobby`** — sets the lobby location players return to after a match
  </Step>

  <Step title="Verify player data">
    Confirm that player statistics migrated correctly by running:

    ```text theme={null}
    /papi parse me %primaxbr_total_wins%
    ```

    This should return the player's win count. If it returns `0` unexpectedly, check the server console for data migration errors.
  </Step>
</Steps>

***

## What's New in v2.0.0

v2.0.0 is a complete ground-up rewrite. Here's a summary of what's improved:

* **New config structure** — settings are split across four focused files for easier management
* **Improved queue system** — rebuilt queue with better handling of edge cases and new configuration options
* **Faster world operations** — world creation and deletion are handled more efficiently, reducing server lag during match transitions
* **Improved performance** — the rewrite is leaner and faster across the board
* **All known v1.x bugs fixed** — the rewrite resolves every reported bug from the v1.x series

<Tip>
  If anything goes wrong during migration, restore the backup you made in Step 1 and place the v1.x JAR back in `/plugins` to roll back safely. Your server will return to its previous working state after a restart.
</Tip>