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

# Plugin Minecraft Altis

> Aprende a instalar y configurar el plugin Altis en tu servidor Minecraft para entregar productos automáticamente.

## ¿Qué es el Plugin Altis?

**Altis** es el plugin oficial de caBRAPI para servidores Minecraft Spigot/Paper. Conecta automáticamente las compras realizadas en tu tienda caBRAPI al servidor, entregando productos de forma automatizada, sin necesidad de intervención manual.

### Funcionalidades

* Entrega automática de productos al jugador al entrar al servidor
* Ejecución de comandos personalizados en la consola o como jugador
* Verificación de inventario lleno antes de la entrega de ítems físicos
* Soporte a **nLogin** para servidores con autenticación
* Notificaciones mediante **Webhook de Discord**
* Verificación periódica de pagos pendientes (modo consola)
* Prevención de duplicidad con registro de pagos procesados
* Soporte de las versiones `1.16.x` a `1.21.x` y `26.x`

## 📦 Requisitos

| Requisito | Descripción |
| - | - |
| Servidor | Spigot o Paper (versiones 1.16.x a 1.21.x, 26.x) |
| Java | 8 o superior |
| Cuenta caBRAPI | Tienda creada y activa en el panel |
| API Key + Store ID | Generados en el panel de tu tienda |
| nLogin | Opcional — detectado automáticamente |

## Descarga del Plugin

1. Accede a la página de [Releases de Altis en GitHub](https://github.com/caBRAPI/cabrapi-minecraft/releases).
2. Descarga el archivo `.jar` de la versión más reciente.

## 🚀 Instalación

1. Coloca el archivo `.jar` descargado en la carpeta `plugins/` de tu servidor.
2. Inicia o reinicia el servidor.
3. El plugin creará automáticamente la estructura:

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

4. Verifica en la consola si el plugin se cargó correctamente — verás el banner **ALTIS by caBRAPI** y el estado de las configuraciones.

***

## ⚙️ Configuración

Edita el archivo `plugins/altis/config.yml` con los datos de tu tienda:

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

### Referencia completa del config.yml

| Campo | Tipo | Predeterminado | Descripción |
| - | - | - | - |
| `api-key` | `string` | `""` | Clave secreta de la API (obligatorio) |
| `store-id` | `string` | `""` | ID de tu tienda (obligatorio) |
| `check-interval` | `integer` | `5` | Intervalo en minutos para verificar pagos pendientes |
| `check-update` | `boolean` | `true` | Verificar actualizaciones del plugin automáticamente |
| `webhook.enable` | `boolean` | `false` | Activar notificaciones en Discord |
| `webhook.url` | `string` | `""` | URL del webhook de Discord |
| `webhook.message` | `string` | `"{player} comprou {products} na loja!"` | Plantilla del mensaje |

### Obteniendo tus credenciales

1. Accede al [panel de caBRAPI](https://www.cabrapi.com.br/dashboard).
2. Navega a **Configuraciones de la Tienda**.
3. Copia el **Store ID** y la **API Key**.
4. Pega los valores en el `config.yml` del plugin.
5. Ejecuta `/cabrapi reload` en el juego o reinicia el servidor.

## 🎮 Comandos y Permisos

| Comando | Permiso | Descripción |
| - | - | - |
| `/cabrapi reload` | `cabrapi.admin` | Recarga el config.yml sin reiniciar |

> El permiso `cabrapi.admin` se concede automáticamente a los **OPs** (`default: op`).

## 🧩 Configurando Productos en el Panel

Para que el plugin entregue ítems automáticamente, cada producto necesita metadatos en formato `minecraft`. Esta configuración se realiza en el panel de caBRAPI, en la sección de edición del producto, campo **MetaData**.

### Ejemplo básico

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

### Campos disponibles

| Campo | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `command` | `string[]` | ✅ | Lista de comandos ejecutados en la entrega |
| `message` | `string` | ❌ | Mensaje enviado al jugador (acepta colores `&`) |
| `run` | `string` | ✅ | `console` (ejecuta en la consola en x tiempo) o `player` (cuando el jugador se autentica) |
| `inventory.enable` | `boolean` | ❌ | Activa la verificación de espacio en el inventario (**solo modo `player`**) |
| `inventory.slot` | `number` | ❌ | Cantidad de slots vacíos necesarios (**solo modo `player`**) |

> 💡 **Consejo:** Usa `{player}` en los comandos y en el mensaje — se sustituirá automáticamente por el nickname del jugador en el momento de la activación.

## Modos de Ejecución

### Modo Consola (`run: console`)

Los comandos se ejecutan directamente en la **consola del servidor** (nivel de OP). Ideal para:

* Cualquier acción que **no dependa** de que el jugador esté en línea

> El modo consola **no admite** verificación de inventario. Los productos en modo consola se procesan tanto en la autenticación del jugador como en la verificación periódica en segundo plano.

### Modo Jugador (`run: player`)

La activación ocurre **cuando el jugador se autentica en el servidor** (al entrar o al iniciar sesión en nLogin). Útil para:

* Entrega de ítems con verificación de inventario
* Cualquier acción que **dependa** de que el jugador esté en línea

## 🔄 Verificación de Pagos Pendientes

El plugin verifica pagos pendientes en **dos escenarios**:

1. **Al entrar al servidor** — procesa todos los pagos pendientes de ese jugador automáticamente.
2. **Periódicamente** (cada `check-interval` minutos) — procesa pagos de productos configurados como `run: console`, incluso si el jugador está desconectado.

> Los pagos ya procesados se almacenan en `plugins/altis/data/processed.yml` para evitar duplicidad.

## 🔐 Soporte a nLogin

Si tu servidor utiliza el plugin **nLogin** para autenticación, Altis lo detecta automáticamente y espera a que el jugador inicie sesión (`NLoginLoginEvent`) antes de procesar los pagos pendientes.

Si **nLogin** no está presente, el plugin usa el evento estándar `PlayerJoinEvent`.

> No se requiere ninguna configuración adicional — la detección es totalmente automática.

## 🌐 Discord Webhook (opcional)

Para recibir notificaciones en Discord cada vez que un jugador compre algo:

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

### Placeholders disponibles

| Variable | Descripción | Ejemplo |
| - | - | - |
| `{player}` | Nombre del jugador | `Steve` |
| `{products}` | Nombre(s) del(los) producto(s) | `5x Vip Diamante` |

## 🎨 Colores Disponibles en los Mensajes

| Código | Color | Código | Color |
| - | - | - | - |
| `&0` | Negro | `&8` | Gris Oscuro |
| `&1` | Azul Oscuro | `&9` | Azul |
| `&2` | Verde Oscuro | `&a` | Verde |
| `&3` | Cian Oscuro | `&b` | Cian |
| `&4` | Rojo | `&c` | Rojo Claro |
| `&5` | Violeta | `&d` | Magenta |
| `&6` | Dorado | `&e` | Amarillo |
| `&7` | Gris Claro | `&f` | Blanco |

Combina con formato: `&l` (negrita), `&n` (subrayado), `&o` (cursiva), `&k` (mágico), `&m` (tachado).

## 📘 Ejemplos Prácticos

### Ejemplo 1: Kit inicial con ítems físicos

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

> El plugin verifica si el jugador tiene **4 slots vacíos** antes de entregar. Si el inventario está lleno, se envía un mensaje de aviso. La verificación de inventario solo funciona en modo `player`.

### Ejemplo 2: Cargo VIP con 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"
  }
}
```

### Ejemplo 3: Comando ejecutado como jugador autenticado

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

> El jugador debe estar **autenticado en el servidor** para recibir, ya que los comandos se ejecutan como él. La activación ocurre en el momento del login/join.

## 🔧 Solución de Problemas

| Problema | Causa probable | Solución |
| - | - | - |
| El plugin no se carga | Java o versión del servidor incompatible | Verifica que uses Java 8+ y Spigot/Paper 1.16+ |
| "API Key não configurada" en la consola | `api-key` vacía o inválida | Configura la clave en el `config.yml` |
| "Store ID não configurado" | `store-id` vacío o incorrecto | Copia el Store ID exacto del panel |
| Los pagos no se procesan | Store ID incorrecto o nickname diferente | Verifica que el nickname del jugador sea correcto |
| Los comandos no se ejecutan | Metadatos `minecraft` ausentes | Agrega el campo `minecraft` al producto en el panel |
| El jugador no recibe al entrar | Modo `player` y sin nLogin | Usa `run: console` o instala nLogin |
| "Inventário cheio" aunque hay espacio | `inventory.slot` muy alto | Reduce el valor o desactiva la verificación |
| Duplicidad en la entrega | Versión antigua del plugin | Actualiza a la versión más reciente |
| El webhook de Discord no funciona | URL inválida o webhook deshabilitado | Prueba la URL en Discord y activa `webhook.enable: true` |

## 🔗 Enlaces útiles

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


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