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

# Apresentação

> Conheça o Five Battle Pass, o sistema completo de passe de batalha por temporada para FiveM.

O **Five Battle Pass** é um sistema completo de passe de batalha por temporada para servidores FiveM. Os jogadores sobem de nível ganhando XP, completam missões diárias, semanais e de temporada, e resgatam recompensas em duas trilhas: a **clássica** (gratuita) e a **premium** (paga). Toda a lógica é validada no servidor, enquanto o cliente apenas exibe e pede ações. A interface é uma aplicação **React (NUI)** totalmente configurável pelo Lua.

## Funcionalidades

<CardGroup cols={2}>
  <Card title="Temporadas com reset" icon="calendar-days">
    Defina uma temporada com ID próprio. Ao trocar o ID, o progresso de todos os jogadores é reiniciado automaticamente no próximo acesso.
  </Card>

  <Card title="Trilhas Clássica e Premium" icon="layer-group">
    Cada nível tem duas recompensas: a clássica (gratuita) e a premium (liberada ao comprar o passe).
  </Card>

  <Card title="Benefícios adaptativos" icon="gift">
    Itens, dinheiro, diamantes, veículos ou lógica customizada. Crie novos tipos de recompensa adicionando um handler.
  </Card>

  <Card title="Sistema de XP e Níveis" icon="chart-line">
    Curva de XP configurável por função. O jogador sobe de nível por missões, XP por tempo online ou pelos exports.
  </Card>

  <Card title="Missões" icon="list-check">
    Tarefas diárias, semanais e de temporada com reset automático e XP de recompensa ao resgatar.
  </Card>

  <Card title="XP por tempo online" icon="clock">
    Concede XP automaticamente a cada X minutos que o jogador permanece conectado.
  </Card>

  <Card title="Loja em diamantes" icon="gem">
    Compra de níveis avulsos e desbloqueio do passe premium usando a moeda do servidor (Gemstone).
  </Card>

  <Card title="Validação no servidor" icon="shield">
    Saldo, posse, nível e resgates são sempre conferidos no servidor. O cliente nunca decide nada.
  </Card>
</CardGroup>

***

## Como funciona

<Steps>
  <Step title="O jogador abre o passe">
    Pelo comando `/battlepass`, por uma tecla, por evento ou export.
  </Step>

  <Step title="Ganha XP e sobe de nível">
    Concluindo missões, ficando online ou recebendo XP de outros scripts via [exports](/five-battlepass/api/exports). Cada nível desbloqueia as recompensas daquele degrau.
  </Step>

  <Step title="Resgata recompensas">
    A trilha clássica é gratuita; a premium exige o passe. O servidor confere nível, posse e se a recompensa já foi resgatada antes de entregar.
  </Step>

  <Step title="Compra níveis ou o premium">
    Opcionalmente, o jogador gasta diamantes para pular níveis ou liberar a trilha premium.
  </Step>
</Steps>

***

## Trilhas e Recompensas

Cada nível da temporada possui **duas recompensas**, uma por tier:

| Tier         | Liberação                    | Estado na interface                                          |
| ------------ | ---------------------------- | ------------------------------------------------------------ |
| **Clássico** | Sempre disponível (gratuito) | Bloqueado se o nível for maior que o atual; senão resgatável |
| **Premium**  | Requer o passe premium       | Exige posse do passe e nível atingido para resgatar          |

O estado de cada recompensa (bloqueado, disponível ou resgatado) é calculado pelo próprio sistema a partir do nível do jogador e da lista de resgates. Você só define **o quê** cada nível entrega.

<Tip>
  O `totalLevels` da temporada deve bater com a quantidade de níveis definidos em `globalConfig.rewards`. Cada nível precisa da sua definição de recompensa.
</Tip>

***

## Sistema de Benefícios

Cada recompensa entrega uma lista de **benefícios**. O `type` de cada benefício é resolvido em `server/class/framework.lua` (`rewardHandlers`), o que torna o sistema totalmente adaptável.

<AccordionGroup>
  <Accordion title="Tipos de benefício prontos" icon="gift">
    | Tipo       | Campos                        | Descrição                                     |
    | ---------- | ----------------------------- | --------------------------------------------- |
    | `item`     | `item`, `amount`              | Entrega um item do inventário                 |
    | `money`    | `amount`                      | Deposita dinheiro no banco                    |
    | `currency` | `amount`                      | Credita diamantes (Gemstone)                  |
    | `vehicle`  | `model`                       | Entrega um veículo na garagem (five-vehicles) |
    | `custom`   | `handler = function(ctx) end` | Lógica livre definida no próprio benefício    |

    ```lua theme={null}
    benefits = {
        { type = "item",     item = "backpack", amount = 1 },
        { type = "money",    amount = 12000 },
        { type = "currency", amount = 25 },
        { type = "vehicle",  model = "sultanrs" },
    }
    ```
  </Accordion>

  <Accordion title="Criando um tipo novo de benefício" icon="wand-magic-sparkles">
    Basta registrar um handler em `framework.rewardHandlers`. O `ctx` recebe `{ source, passport, identifier, level, tier, spec }`. Retorne `true` em sucesso (retornar `false` aborta e o resgate não é registrado).

    ```lua theme={null}
    framework.rewardHandlers["xp_boost"] = function(ctx)
        local minutes = ctx.spec.minutes or 30
        -- sua lógica de boost...
        return true
    end
    ```

    No `config.lua`:

    ```lua theme={null}
    { type = "xp_boost", minutes = 60 }
    ```
  </Accordion>
</AccordionGroup>

***

## Sistema de XP e Níveis

O XP necessário para avançar de nível é definido por uma função em `globalConfig.progression.xpForLevel(level)`, permitindo curva plana ou progressiva.

```lua theme={null}
globalConfig.progression = {
    xpForLevel = function(level)
        return 1000            -- plano: 1000 XP por nível
        -- return 800 + level * 200   -- exemplo de curva progressiva
    end,
}
```

O jogador ganha XP de três formas:

<CardGroup cols={3}>
  <Card title="Missões" icon="list-check">
    Ao resgatar uma missão concluída, o XP dela é creditado.
  </Card>

  <Card title="Tempo online" icon="clock">
    A cada intervalo configurado, todos os conectados recebem XP.
  </Card>

  <Card title="Exports" icon="code">
    Outros scripts concedem XP ou níveis via [exports](/five-battlepass/api/exports).
  </Card>
</CardGroup>

***

## Missões

As missões são divididas em três grupos, cada um com sua janela de reset:

| Grupo         | `reset`  | Quando zera                                  |
| ------------- | -------- | -------------------------------------------- |
| **Diárias**   | `daily`  | Na virada do dia (no próximo carregamento)   |
| **Semanais**  | `weekly` | Na virada da semana                          |
| **Temporada** | `season` | Apenas quando a temporada (`season.id`) muda |

O progresso de cada missão é avançado por outros scripts via o export [`addMissionProgress`](/five-battlepass/api/exports#addmissionprogress). Ao atingir a meta, o jogador resgata o XP pela interface.

<Info>
  O reset de missões diárias e semanais é aplicado no carregamento dos dados do jogador (ao entrar ou abrir o passe). Um jogador que permanece online atravessando a virada só tem as missões zeradas no próximo carregamento.
</Info>

***

## Economia

O passe usa a moeda do servidor (diamantes / Gemstone) para duas compras opcionais:

```lua theme={null}
globalConfig.economy = {
    pricePerLevel  = 5,    -- custo em diamantes de 1 nível
    premiumPrice   = 75,   -- custo do passe premium
    maxBuyAmount   = 50,   -- máximo de níveis por compra
    showBuyLevels  = true, -- false esconde o botão (libera só por exports)
    showBuyPremium = true, -- false esconde o botão (libera só por exports)
}
```

Definir `showBuyLevels` ou `showBuyPremium` como `false` esconde os botões na interface, útil quando você quer liberar níveis ou o premium apenas por outros sistemas (loja, VIP, recompensas) usando os exports.