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

> Aprenda a instalar e configurar o plugin Altis no seu servidor Minecraft para entregar produtos automaticamente.

## O que é o Plugin Altis?

O **Altis** é o plugin oficial da caBRAPI para servidores Minecraft Spigot/Paper. Ele conecta automaticamente as compras realizadas na sua loja caBRAPI ao servidor, entregando produtos de forma automatizada — sem precisar de intervenção manual.

### Funcionalidades

* Entrega automática de produtos ao jogador ao entrar no servidor
* Execução de comandos personalizados no console ou como jogador
* Verificação de inventário cheio antes da entrega de itens físicos
* Suporte ao **nLogin** para servidores com autenticação
* Notificações via **Webhook do Discord**
* Verificação periódica de pagamentos pendentes (modo console)
* Prevenção de duplicidade com registro de pagamentos processados
* Suporte das versões `1.16.x` até `1.21.x` e `26.x`

## 📦 Requisitos

| Requisito | Descrição |
| - | - |
| Servidor | Spigot ou Paper (versões 1.16.x a 1.21.x, 26.x) |
| Java | 8 ou superior |
| Conta caBRAPI | Loja criada e ativa no painel |
| API Key + Store ID | Gerados no painel da sua loja |
| nLogin | Opcional — detectado automaticamente |

## Download do Plugin

1. Acesse a página de [Releases do Altis no GitHub](https://github.com/caBRAPI/cabrapi-minecraft/releases).
2. Baixe o arquivo `.jar` da versão mais recente.

## 🚀 Instalação

1. Coloque o arquivo `.jar` baixado na pasta `plugins/` do seu servidor.
2. Inicie ou reinicie o servidor.
3. O plugin criará automaticamente a estrutura:

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

4. Verifique no console se o plugin carregou corretamente — você verá o banner **ALTIS by caBRAPI** e o status das configurações.

***

## ⚙️ Configuração

Edite o arquivo `plugins/altis/config.yml` com os dados da sua loja:

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

### Referência completa do config.yml

| Campo | Tipo | Padrão | Descrição |
| - | - | - | - |
| `api-key` | `string` | `""` | Chave secreta da API (obrigatório) |
| `store-id` | `string` | `""` | ID da sua loja (obrigatório) |
| `check-interval` | `integer` | `5` | Intervalo em minutos para verificar pagamentos pendentes |
| `check-update` | `boolean` | `true` | Verificar atualizações do plugin automaticamente |
| `webhook.enable` | `boolean` | `false` | Ativar notificações no Discord |
| `webhook.url` | `string` | `""` | URL do webhook do Discord |
| `webhook.message` | `string` | `"{player} comprou {products} na loja!"` | Template da mensagem |

### Obtendo suas credenciais

1. Acesse o [painel da caBRAPI](https://www.cabrapi.com.br/dashboard).
2. Navegue até **Configurações da Loja**.
3. Copie o **Store ID** e a **API Key**.
4. Cole os valores no `config.yml` do plugin.
5. Execute `/cabrapi reload` no jogo ou reinicie o servidor.

## 🎮 Comandos e Permissões

| Comando | Permissão | Descrição |
| - | - | - |
| `/cabrapi reload` | `cabrapi.admin` | Recarrega o config.yml sem reiniciar |

> A permissão `cabrapi.admin` é concedida automaticamente para **OPs** (`default: op`).

## 🧩 Configurando Produtos no Painel

Para que o plugin entregue itens automaticamente, cada produto precisa de metadados no formato `minecraft`. Essa configuração é feita no painel da caBRAPI, na seção de edição do produto, campo **MetaData**.

### Exemplo 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 disponíveis

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `command` | `string[]` | ✅ | Lista de comandos executados na entrega |
| `message` | `string` | ❌ | Mensagem enviada ao jogador (aceita cores `&`) |
| `run` | `string` | ✅ | `console` (executa no console em x tempo) ou `player` (quando jogador se autentica) |
| `inventory.enable` | `boolean` | ❌ | Ativa verificação de espaço no inventário (**apenas modo `player`**) |
| `inventory.slot` | `number` | ❌ | Quantidade de slots vagos necessários (**apenas modo `player`**) |

> 💡 **Dica:** Use `{player}` nos comandos e na mensagem — ele será substituído automaticamente pelo nickname do jogador no momento da ativação.

## Modos de Execução

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

Os comandos são executados diretamente no **console do servidor** (nível de OP). Ideal para:

* Qualquer ação que **não dependa** do jogador estar online

> O modo console **não suporta** verificação de inventário. Produtos em modo console são processados tanto na autenticação do jogador quanto na verificação periódica de fundo.

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

A ativação ocorre **quando o jogador se autentica no servidor** (ao entrar ou ao fazer login no nLogin). Útil para:

* Entrega de itens com verificação de inventário
* Qualquer ação que **dependa** do jogador estar online

## 🔄 Verificação de Pagamentos Pendentes

O plugin verifica pagamentos pendentes em **dois cenários**:

1. **Ao entrar no servidor** — processa todos os pagamentos pendentes daquele jogador automaticamente.
2. **Periodicamente** (a cada `check-interval` minutos) — processa pagamentos de produtos configurados como `run: console`, mesmo que o jogador esteja offline.

> Os pagamentos já processados são armazenados em `plugins/altis/data/processed.yml` para evitar duplicidade.

## 🔐 Suporte a nLogin

Se o seu servidor utiliza o plugin **nLogin** para autenticação, o Altis detecta automaticamente e aguarda o jogador fazer login (`NLoginLoginEvent`) antes de processar os pagamentos pendentes.

Se o nLogin **não estiver presente**, o plugin usa o evento padrão `PlayerJoinEvent`.

> Nenhuma configuração adicional é necessária — a detecção é totalmente automática.

## 🌐 Discord Webhook (opcional)

Para receber notificações no Discord sempre que um jogador comprar algo:

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

### Placeholders disponíveis

| Variável | Descrição | Exemplo |
| - | - | - |
| `{player}` | Nome do jogador | `Steve` |
| `{products}` | Nome(s) do(s) produto(s) | `5x Vip Diamante` |

## 🎨 Cores Disponíveis nas Mensagens

| Código | Cor | Código | Cor |
| - | - | - | - |
| `&0` | Preto | `&8` | Cinza Escuro |
| `&1` | Azul Escuro | `&9` | Azul |
| `&2` | Verde Escuro | `&a` | Verde |
| `&3` | Ciano Escuro | `&b` | Ciano |
| `&4` | Vermelho | `&c` | Vermelho Claro |
| `&5` | Roxo | `&d` | Magenta |
| `&6` | Dourado | `&e` | Amarelo |
| `&7` | Cinza Claro | `&f` | Branco |

Combine com formatação: `&l` (negrito), `&n` (sublinhado), `&o` (itálico), `&k` (mágico), `&m` (riscado).

## 📘 Exemplos Práticos

### Exemplo 1: Kit inicial com itens 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
    }
  }
}
```

> O plugin verifica se o jogador tem **4 slots vagos** antes de entregar. Se o inventário estiver cheio, uma mensagem de aviso é enviada. A verificação de inventário funciona apenas no modo `player`.

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

### Exemplo 3: Comando executado como jogador autenticado

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

> O jogador precisa estar **autenticado no servidor** para receber, pois os comandos são executados como ele. A ativação ocorre no momento do login/join.

## 🔧 Solução de Problemas

| Problema | Causa provável | Solução |
| - | - | - |
| Plugin não carrega | Java ou versão do servidor incompatível | Verifique se usa Java 8+ e Spigot/Paper 1.16+ |
| "API Key não configurada" no console | `api-key` vazia ou inválida | Configure a chave no `config.yml` |
| "Store ID não configurado" | `store-id` vazio ou incorreto | Copie o Store ID exato do painel |
| Pagamentos não são processados | Store ID incorreto ou nickname diferente | Verifique se o nickname do jogador está correto |
| Comandos não executam | Metadados `minecraft` ausentes | Adicione o campo `minecraft` ao produto no painel |
| Jogador não recebe ao entrar | Modo `player` e sem nLogin | Use `run: console` ou instale o nLogin |
| "Inventário cheio" mesmo com espaço | `inventory.slot` muito alto | Reduza o valor ou desabilite a verificação |
| Duplicidade na entrega | Versão antiga do plugin | Atualize para a versão mais recente |
| Webhook do Discord não funciona | URL inválida ou webhook desabilitado | Teste a URL no Discord e ative `webhook.enable: true` |

## 🔗 Links úteis

* [Repositório do Altis no GitHub](https://github.com/caBRAPI/cabrapi-minecraft)
* [Releases do Altis](https://github.com/caBRAPI/cabrapi-minecraft/releases)
* [Painel da caBRAPI](https://www.cabrapi.com.br/dashboard)
* [SDK Java/Kotlin](https://github.com/caBRAPI/cabrapi-sdk-java-kotlin)
* [Discord da caBRAPI](https://discord.gg/crs43kV4mm)


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