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

# Installation

Asteroid is made of two plugins that must both be installed:

1. **Asteroid** (the main plugin).
2. **AsteroidLibs** (the required library). Asteroid will not start without it.

## Step 1: Download both plugins

* Asteroid: from your purchase page.
* AsteroidLibs: <https://builtbybit.com/resources/asteroidlibs-asteroid-dependency.35035/>

## Step 2: Drop them in your plugins folder

Place both `Asteroid.jar` and `AsteroidLibs.jar` into your server's `plugins/` folder. Do not put them in a subfolder. Both jars go directly inside `plugins/`.

## Step 3: Start the server

Start (or restart) the server once so Asteroid can generate its config files. You should see Asteroid load in the console. After the first start, you will have `plugins/Asteroid/config.yml` and `plugins/Asteroid/addons/`.

## Step 4: Give yourself access

By default, nobody can use Asteroid commands until their UUID is on the allowed list. There are two ways to add yourself.

### Option A: Instant setup (easiest)

1. Open `plugins/Asteroid/config.yml`.
2. Find the `instant-setup-uuid` value near the top.
3. Join your server as a normal player.
4. Run the command shown, which is your UUID as a slash command, for example:

```
/3fd954a8-c1b2-4b80-b163-96f3aa666a44
```

This automatically adds your UUID to the allowed list. Run it in game, not from console.

### Option B: Manual

Open `config.yml` and add your UUID under `access.allowed_uuids`:

```yaml
access:
  main_command: 'asteroid'
  allowed_uuids:
    - '3fd954a8-c1b2-4b80-b163-96f3aa666a44'
```

You can find your UUID on sites like namemc.com.

## Step 5: Confirm it works

Run `/asteroid` in game. If you see the Asteroid command menu, you are ready.

## Compatibility

| Item               | Details                                              |
| ------------------ | ---------------------------------------------------- |
| Minecraft versions | 1.8.8 through 26.x                                   |
| Server software    | Spigot, Paper, Purpur, Folia, and compatible forks   |
| Folia              | Supported                                            |
| Java               | Use the Java version your Minecraft version requires |

## Optional integrations (soft dependencies)

Asteroid works without these, but will use them if present:

| Plugin         | What it adds                                 |
| -------------- | -------------------------------------------- |
| PlaceholderAPI | Placeholders for counts and AI formatting    |
| ProtocolLib    | Extra packet-level features on some versions |
| LuckPerms      | Used by the Ranks addon                      |
| NBTAPI         | Item and metadata handling                   |
| TAB            | Tab list integration                         |
| PacketEvents   | Packet handling on some setups               |

## License key

If your copy of Asteroid uses a license, set `license-key: 'YOUR-KEY-HERE'` in `config.yml`. If unsure, leave it as `NONE` and start the server. If a license is required, the console will tell you.

## Updating

1. Stop the server.
2. Replace the old `Asteroid.jar` (and `AsteroidLibs.jar` if a new version is provided).
3. Start the server.

Your `config.yml` is kept between updates.