Apresentação

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

Temporadas com reset

Defina uma temporada com ID próprio. Ao trocar o ID, o progresso de todos os jogadores é reiniciado automaticamente no próximo acesso.

Trilhas Clássica e Premium

Cada nível tem duas recompensas: a clássica (gratuita) e a premium (liberada ao comprar o passe).

Benefícios adaptativos

Itens, dinheiro, diamantes, veículos ou lógica customizada. Crie novos tipos de recompensa adicionando um handler.

Sistema de XP e Níveis

Curva de XP configurável por função. O jogador sobe de nível por missões, XP por tempo online ou pelos exports.

Missões

Tarefas diárias, semanais e de temporada com reset automático e XP de recompensa ao resgatar.

XP por tempo online

Concede XP automaticamente a cada X minutos que o jogador permanece conectado.

Loja em diamantes

Compra de níveis avulsos e desbloqueio do passe premium usando a moeda do servidor (Gemstone).

Validação no servidor

Saldo, posse, nível e resgates são sempre conferidos no servidor. O cliente nunca decide nada.

Como funciona

O jogador abre o passe

Pelo comando /battlepass, por uma tecla, por evento ou export.

Ganha XP e sobe de nível

Concluindo missões, ficando online ou recebendo XP de outros scripts via exports. Cada nível desbloqueia as recompensas daquele degrau.

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.

Compra níveis ou o premium

Opcionalmente, o jogador gasta diamantes para pular níveis ou liberar a trilha premium.

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.

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.

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.

Tipos de benefício prontos

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

benefits = {
    { type = "item",     item = "backpack", amount = 1 },
    { type = "money",    amount = 12000 },
    { type = "currency", amount = 25 },
    { type = "vehicle",  model = "sultanrs" },
}

Criando um tipo novo de benefício

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

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

No config.lua:

{ type = "xp_boost", minutes = 60 }

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.

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:

Missões

Ao resgatar uma missão concluída, o XP dela é creditado.

Tempo online

A cada intervalo configurado, todos os conectados recebem XP.

Exports

Outros scripts concedem XP ou níveis via exports.

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. Ao atingir a meta, o jogador resgata o XP pela interface.

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.

Economia

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

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.

Comece por aqui!

Nossos produtos

Funcionalidades

Temporadas com reset

Trilhas Clássica e Premium

Benefícios adaptativos

Sistema de XP e Níveis

Missões

XP por tempo online

Loja em diamantes

Validação no servidor

Como funciona

Trilhas e Recompensas

Sistema de Benefícios

Sistema de XP e Níveis

Missões

Tempo online

Exports

Missões

Economia

​Funcionalidades

Temporadas com reset

Trilhas Clássica e Premium

Benefícios adaptativos

Sistema de XP e Níveis

Missões

XP por tempo online

Loja em diamantes

Validação no servidor

​Como funciona

​Trilhas e Recompensas

​Sistema de Benefícios

​Sistema de XP e Níveis

Missões

Tempo online

Exports

​Missões

​Economia

Funcionalidades

Como funciona

Trilhas e Recompensas

Sistema de Benefícios

Sistema de XP e Níveis

Missões

Economia