> For the complete documentation index, see [llms.txt](https://buildsystem.eintosti.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://buildsystem.eintosti.de/getting-started/installing-buildsystem.md).

# Installing BuildSystem

Requirements, setup, and what the first startup creates.

## Requirements

Ensure your server meets the following version requirements before installation:

* **Java Version**: **Java 25** minimum. The plugin will not load on older runtimes and will throw unsupported class version errors.
* **Minecraft Version**: Supports **Minecraft 26.1** and newer, tested up to 26.3.
* **Server Software**: Spigot, Paper, or a fork of either.

### Optional Integrations

None of these are required. BuildSystem detects each at startup and simply skips the integration when it is absent.

| Plugin                                 | What it adds                                                        |
| -------------------------------------- | ------------------------------------------------------------------- |
| **LuckPerms**                          | A `buildsystem:build-mode` context you can key permissions off.     |
| **PlaceholderAPI**                     | `%buildsystem_...%` placeholders for other plugins and scoreboards. |
| **WorldEdit** / **FastAsyncWorldEdit** | World edits respect BuildSystem's per-world protection.             |
| **AxiomPaper**                         | Axiom edits respect the same protection.                            |
| **EssentialsX**                        | `/warp` into an unloaded build world loads the world first.         |

***

## Installation Steps

1. Download the `BuildSystem.jar` file from SpigotMC, [Modrinth](https://modrinth.com/plugin/buildsystem) or the [GitHub releases](https://github.com/thomasmny/BuildSystem/releases).
2. Place the `.jar` file into the server's `plugins/` directory.
3. Start the server to generate default configuration directories and files.
4. Stop the server by running the `stop` command in the console.
5. Modify `plugins/BuildSystem/config.yml` and `messages.yml` as needed.
6. Restart the server.

***

## What the First Startup Creates

Inside `plugins/BuildSystem/`:

| File             | Contents                                                                                                                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config.yml`     | Global settings. Versioned and migrated automatically on later upgrades.                                                                                                                                |
| `messages.yml`   | Every player-facing string.                                                                                                                                                                             |
| `storage.db`     | The SQLite database with the world registry, folders and player settings. Only with the default `storage.type: sqlite`; see [Data Storage](https://buildsystem.eintosti.de/getting-started/storage.md). |
| `worlds.yml`     | The world registry: status, visibility, builders, and per-world data. Only with `storage.type: yaml`.                                                                                                   |
| `folders.yml`    | Folder definitions and their world membership. Only with `storage.type: yaml`.                                                                                                                          |
| `statuses.yml`   | The world statuses, seeded with the six built-ins.                                                                                                                                                      |
| `categories.yml` | The navigator categories, seeded with the built-ins.                                                                                                                                                    |
| `players.yml`    | Each player's `/settings` choices and logout location, and while they are in an archive world, the inventory they had before. Only with `storage.type: yaml`.                                           |
| `spawn.yml`      | The spawn set with `/spawn set`. Empty until one is set.                                                                                                                                                |
| `setup.yml`      | Default world-type icons changed in `/setup`. Empty until you change one.                                                                                                                               |
| `templates/`     | Drop world folders here to offer them as creation templates.                                                                                                                                            |

***

## Verifying the Install

Run `/worlds` in-game. The navigator should open with the default categories. If the command is not found, check the console for a startup error; if it opens but is empty, no worlds have been created or imported yet.

{% hint style="info" %}
**Upgrading rather than installing fresh?** Read the [Migration Guide](https://buildsystem.eintosti.de/getting-started/migration-guide.md) first. The plugin converts its data on first boot and the conversion is one-way.
{% endhint %}
