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

# Exports

> Funções exportadas pelo Five Battle Pass para integração com outros scripts do servidor.

Os exports do Five Battle Pass permitem que outros recursos concedam XP, subam níveis, avancem missões e controlem o passe premium dos jogadores. Todos os exports são **server-side**.

<Note>
  Todos os exports recebem o `source` (server ID) de um jogador **online**, não o Passport. Internamente o `source` é resolvido para o identificador permanente.
</Note>

***

## addMissionProgress

Avança o progresso de uma missão. O valor é somado ao progresso atual, respeitando o total da missão. Missões já resgatadas são ignoradas.

```lua theme={null}
local ok, current = exports["core-battlepass"]:addMissionProgress(source, missionId, amount)
```

**Parâmetros**

| Nome        | Tipo     | Descrição                                          |
| ----------- | -------- | -------------------------------------------------- |
| `source`    | `number` | Server ID do jogador                               |
| `missionId` | `number` | `id` da missão em `globalConfig.tasks`             |
| `amount`    | `number` | Quantidade de progresso a somar (inteiro positivo) |

**Retorno**

| Valor     | Tipo      | Descrição                                                                                                      |
| --------- | --------- | -------------------------------------------------------------------------------------------------------------- |
| `ok`      | `boolean` | `true` se a chamada foi processada; `false` em parâmetro inválido, missão inexistente ou jogador não carregado |
| `current` | `number`  | Progresso atual após a soma (limitado ao total da missão)                                                      |

**Exemplo**

```lua theme={null}
-- Ao jogador eliminar alguém, avança a missão de id 1 em 1 ponto
RegisterNetEvent("meuPvp:kill", function()
    local src = source
    exports["core-battlepass"]:addMissionProgress(src, 1, 1)
end)
```

<Info>
  Avançar o progresso **não** concede o XP automaticamente; o jogador resgata a missão concluída pela interface. Para creditar XP diretamente, use [`addUserXP`](#adduserxp).
</Info>

***

## addUserXP

Credita XP ao jogador, subindo de nível automaticamente quando o XP acumulado ultrapassa o necessário (respeitando o nível máximo da temporada).

```lua theme={null}
local ok, level = exports["core-battlepass"]:addUserXP(source, amount)
```

**Parâmetros**

| Nome     | Tipo     | Descrição                   |
| -------- | -------- | --------------------------- |
| `source` | `number` | Server ID do jogador        |
| `amount` | `number` | Quantidade de XP a conceder |

**Retorno**

| Valor   | Tipo      | Descrição                                    |
| ------- | --------- | -------------------------------------------- |
| `ok`    | `boolean` | `true` se processado; `false` se sem jogador |
| `level` | `number`  | Nível do jogador após o ganho de XP          |

**Exemplo**

```lua theme={null}
local ok, level = exports["core-battlepass"]:addUserXP(source, 250)
```

***

## addUserLevel

Sobe o jogador um ou mais níveis diretamente, **sem** custo e **sem** XP, respeitando o nível máximo da temporada.

```lua theme={null}
local ok, level = exports["core-battlepass"]:addUserLevel(source, amount)
```

**Parâmetros**

| Nome     | Tipo     | Descrição                        |
| -------- | -------- | -------------------------------- |
| `source` | `number` | Server ID do jogador             |
| `amount` | `number` | Quantidade de níveis a adicionar |

**Retorno**

| Valor   | Tipo      | Descrição                                    |
| ------- | --------- | -------------------------------------------- |
| `ok`    | `boolean` | `true` se processado; `false` se sem jogador |
| `level` | `number`  | Nível do jogador após a adição               |

**Exemplo**

```lua theme={null}
-- Recompensa de loja: +2 níveis no passe
exports["core-battlepass"]:addUserLevel(source, 2)
```

***

## setUserPremiumPass

Define a posse do passe premium do jogador. Use `true` para liberar a trilha premium ou `false` para remover.

```lua theme={null}
local ok = exports["core-battlepass"]:setUserPremiumPass(source, value)
```

**Parâmetros**

| Nome     | Tipo      | Descrição                                |
| -------- | --------- | ---------------------------------------- |
| `source` | `number`  | Server ID do jogador                     |
| `value`  | `boolean` | `true` concede o premium, `false` remove |

**Retorno:** `boolean`. `true` se processado; `false` se o jogador não foi encontrado.

**Exemplo**

```lua theme={null}
-- Liberar o passe premium ao confirmar uma compra externa
exports["core-battlepass"]:setUserPremiumPass(source, true)
```

<Tip>
  Combine com `showBuyPremium = false` no `config.lua` para esconder o botão de compra e liberar o premium **apenas** por este export (ex: pacote VIP, loja web).
</Tip>

***

## removeUserPremium

Remove o passe premium do jogador. Atalho para `setUserPremiumPass(source, false)`.

```lua theme={null}
local ok = exports["core-battlepass"]:removeUserPremium(source)
```

**Parâmetros**

| Nome     | Tipo     | Descrição            |
| -------- | -------- | -------------------- |
| `source` | `number` | Server ID do jogador |

**Retorno:** `boolean`. `true` se processado; `false` se o jogador não foi encontrado.

**Exemplo**

```lua theme={null}
-- Ao expirar uma assinatura, remove o premium
exports["core-battlepass"]:removeUserPremium(source)
```

***

## Exemplo de integração

Avança uma missão, concede XP e libera o premium ao concluir um objetivo no servidor.

```lua theme={null}
-- server-side, em outro script
local battlepass = exports["core-battlepass"]

RegisterNetEvent("meuEvento:objetivoConcluido", function()
    local src = source

    -- Avança a missão diária de id 2
    battlepass:addMissionProgress(src, 2, 1)

    -- Credita 150 de XP no passe (pode subir de nível)
    local _, level = battlepass:addUserXP(src, 150)

    -- Recompensa especial: libera a trilha premium
    if level >= 10 then
        battlepass:setUserPremiumPass(src, true)
    end
end)
```