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

# Altis Minecraft Plugin

> Learn how to install and configure the Altis plugin on your Minecraft server to deliver products automatically.

## What is the Altis Plugin?

**Altis** is caBRAPI's official plugin for Spigot/Paper Minecraft servers. It automatically connects purchases made in your caBRAPI store to the server, delivering products automatically — with no manual intervention required.

### Features

* Automatic product delivery to the player when they join the server
* Execution of custom commands in the console or as a player
* Inventory full check before delivering physical items
* **nLogin** support for servers with authentication
* Notifications via **Discord Webhook**
* Periodic check of pending payments (console mode)
* Duplicate prevention with processed payment records
* Support for versions `1.16.x` through `1.21.x` and `26.x`

## 📦 Requirements

| Requirement | Description |
| - | - |
| Server | Spigot or Paper (versions 1.16.x to 1.21.x, 26.x) |
| Java | 8 or higher |
| caBRAPI account | Store created and active in the panel |
| API Key + Store ID | Generated in your store's panel |
| nLogin | Optional — detected automatically |

## Plugin Download

1. Go to the [Altis Releases page on GitHub](https://github.com/caBRAPI/cabrapi-minecraft/releases).
2. Download the `.jar` file of the latest version.

## 🚀 Installation

1. Place the downloaded `.jar` file in your server's `plugins/` folder.
2. Start or restart the server.
3. The plugin will automatically create the following structure:

```
plugins/
  altis.jar
  altis/
    config.yml
```

4. Check the console to confirm the plugin loaded correctly — you will see the **ALTIS by caBRAPI** banner and the configuration status.

***

## ⚙️ Configuration

Edit the `plugins/altis/config.yml` file with your store's data:

```yaml theme={null}
api-key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
store-id: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
check-interval: 5
check-update: true
```

### Full config.yml reference

| Field | Type | Default | Description |
| - | - | - | - |
| `api-key` | `string` | `""` | Secret API key (required) |
| `store-id` | `string` | `""` | Your store ID (required) |
| `check-interval` | `integer` | `5` | Interval in minutes to check pending payments |
| `check-update` | `boolean` | `true` | Automatically check for plugin updates |
| `webhook.enable` | `boolean` | `false` | Enable Discord notifications |
| `webhook.url` | `string` | `""` | Discord webhook URL |
| `webhook.message` | `string` | `"{player} comprou {products} na loja!"` | Message template |

### Getting your credentials

1. Access the [caBRAPI panel](https://www.cabrapi.com.br/dashboard).
2. Navigate to **Store Settings**.
3. Copy the **Store ID** and **API Key**.
4. Paste the values into the plugin's `config.yml`.
5. Run `/cabrapi reload` in-game or restart the server.

## 🎮 Commands and Permissions

| Command | Permission | Description |
| - | - | - |
| `/cabrapi reload` | `cabrapi.admin` | Reloads config.yml without restarting |

> The `cabrapi.admin` permission is automatically granted to **OPs** (`default: op`).

## 🧩 Configuring Products in the Panel

For the plugin to deliver items automatically, each product needs metadata in the `minecraft` format. This is configured in the caBRAPI panel, in the product edit section, **MetaData** field.

### Basic example

```json theme={null}
{
  "minecraft": {
    "command": [
      "give {player} diamond 1",
      "say {player} comprou um diamante!"
    ],
    "message": "&a&lOBRIGADO! &aVocê recebeu seu item.",
    "run": "console"
  }
}
```

### Available fields

| Field | Type | Required | Description |
| - | - | - | - |
| `command` | `string[]` | ✅ | List of commands executed on delivery |
| `message` | `string` | ❌ | Message sent to the player (supports `&` colors) |
| `run` | `string` | ✅ | `console` (executes in console) or `player` (when the player authenticates) |
| `inventory.enable` | `boolean` | ❌ | Enables inventory space check (**`player` mode only**) |
| `inventory.slot` | `number` | ❌ | Number of empty slots required (**`player` mode only**) |

> 💡 **Tip:** Use `{player}` in commands and in the message — it will be automatically replaced by the player's nickname at activation time.

## Execution Modes

### Console Mode (`run: console`)

Commands are executed directly in the **server console** (OP level). Ideal for:

* Any action that **does not depend** on the player being online

> Console mode **does not support** inventory checks. Products in console mode are processed both on player authentication and during the periodic background check.

### Player Mode (`run: player`)

Activation occurs **when the player authenticates on the server** (on join or on nLogin login). Useful for:

* Item delivery with inventory check
* Any action that **depends** on the player being online

## 🔄 Pending Payment Check

The plugin checks for pending payments in **two scenarios**:

1. **On server join** — processes all pending payments for that player automatically.
2. **Periodically** (every `check-interval` minutes) — processes payments for products configured as `run: console`, even if the player is offline.

> Processed payments are stored in `plugins/altis/data/processed.yml` to prevent duplicates.

## 🔐 nLogin Support

If your server uses the **nLogin** plugin for authentication, Altis detects it automatically and waits for the player to log in (`NLoginLoginEvent`) before processing pending payments.

If nLogin is **not present**, the plugin uses the default `PlayerJoinEvent`.

> No additional configuration is needed — detection is fully automatic.

## 🌐 Discord Webhook (optional)

To receive Discord notifications whenever a player buys something:

```yaml theme={null}
webhook:
  enable: true
  url: "https://discord.com/api/webhooks/1234567890/abcdef"
  message: "{player} comprou {products} na loja!"
```

### Available placeholders

| Variable | Description | Example |
| - | - | - |
| `{player}` | Player name | `Steve` |
| `{products}` | Product name(s) | `5x Vip Diamante` |

## 🎨 Available Colors in Messages

| Code | Color | Code | Color |
| - | - | - | - |
| `&0` | Black | `&8` | Dark Gray |
| `&1` | Dark Blue | `&9` | Blue |
| `&2` | Dark Green | `&a` | Green |
| `&3` | Dark Cyan | `&b` | Cyan |
| `&4` | Red | `&c` | Light Red |
| `&5` | Purple | `&d` | Magenta |
| `&6` | Gold | `&e` | Yellow |
| `&7` | Light Gray | `&f` | White |

Combine with formatting: `&l` (bold), `&n` (underline), `&o` (italic), `&k` (magic), `&m` (strikethrough).

## 📘 Practical Examples

### Example 1: Starter kit with physical items

```json theme={null}
{
  "minecraft": {
    "command": [
      "give {player} diamond_pickaxe 1",
      "give {player} diamond_sword 1",
      "give {player} cooked_beef 32",
      "give {player} oak_planks 64"
    ],
    "message": "&a&lKIT INICIANTE! &fConfira seu inventário.",
    "run": "player",
    "inventory": {
      "enable": true,
      "slot": 4
    }
  }
}
```

> The plugin checks if the player has **4 empty slots** before delivering. If the inventory is full, a warning message is sent. Inventory check works only in `player` mode.

### Example 2: VIP rank with LuckPerms

```json theme={null}
{
  "minecraft": {
    "command": [
      "lp user {player} parent add vip",
      "eco give {player} 1000",
      "broadcast &6&l{player} &eacabou de se tornar &b&lVIP!"
    ],
    "message": "&b&lVOCÊ É VIP! &fAproveite seus benefícios.",
    "run": "console"
  }
}
```

### Example 3: Command executed as an authenticated player

```json theme={null}
{
  "minecraft": {
    "command": [
      "warp spawn",
      "kit vip"
    ],
    "message": "&eTeleportado ao spawn!",
    "run": "player"
  }
}
```

> The player needs to be **authenticated on the server** to receive it, since the commands are executed as them. Activation occurs at login/join time.

## 🔧 Troubleshooting

| Problem | Probable cause | Solution |
| - | - | - |
| Plugin does not load | Incompatible Java or server version | Check you are using Java 8+ and Spigot/Paper 1.16+ |
| "API Key not configured" in console | Empty or invalid `api-key` | Configure the key in `config.yml` |
| "Store ID not configured" | Empty or incorrect `store-id` | Copy the exact Store ID from the panel |
| Payments are not processed | Incorrect Store ID or different nickname | Check that the player nickname is correct |
| Commands do not execute | Missing `minecraft` metadata | Add the `minecraft` field to the product in the panel |
| Player does not receive on join | `player` mode and no nLogin | Use `run: console` or install nLogin |
| "Inventory full" even with space | `inventory.slot` too high | Reduce the value or disable the check |
| Duplicate delivery | Old plugin version | Update to the latest version |
| Discord Webhook does not work | Invalid URL or webhook disabled | Test the URL in Discord and enable `webhook.enable: true` |

## 🔗 Useful links

* [Altis repository on GitHub](https://github.com/caBRAPI/cabrapi-minecraft)
* [Altis Releases](https://github.com/caBRAPI/cabrapi-minecraft/releases)
* [caBRAPI Panel](https://www.cabrapi.com.br/dashboard)
* [Java/Kotlin SDK](https://github.com/caBRAPI/cabrapi-sdk-java-kotlin)
* [caBRAPI Discord](https://discord.gg/crs43kV4mm)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.