⚔️Battlepass

Step by step installation guide for ESX / QB / QBox, common issues & solutions, troubleshooting guide, code snippets, changelog.

Overview

XeX BattlePass is a premium daily reward and battle pass system for FiveM servers. Players claim one reward per day across a 30-day calendar. A premium VIP tier gives access to exclusive bonus rewards. The system features a dark gaming-inspired NUI, Discord webhook logging, and automatic database management.

Supported Frameworks

Framework	Version	Status
ESX Legacy	1.6.0+	✅ Full Support
QBCore	Latest	✅ Full Support
QBox	Latest	✅ Full Support

Features Summary

Category	Feature	Description
Rewards	30-Day Schedule	Configurable normal + VIP reward per day
Rewards	5 Reward Types	Items, weapons, money, vehicles, furniture
Rewards	Daily Claims	One claim per day, sequential progression
Premium	VIP Tier	Purchasable premium subscription for exclusive rewards
Premium	Renewals	Extend premium duration with configurable packages
Premium	Retroactive	VIP purchase retroactively awards missed VIP rewards
UI	Dark Theme	Modern gaming-inspired NUI with Inter font
UI	Progress Grid	Visual 30-day calendar with claim/locked/available states
System	Auto DB	Tables created automatically on first start
System	Season State	KVP-based persistence for season day tracking
System	Discord Webhooks	Log every reward claim to Discord
System	Auto Updater	Version check via GitHub Gist JSON
I18n	2 Languages	English, Spanish
Compat	loaf_housing	Furniture reward type integration
Compat	xex_lootboxes	Lootbox item integration

Installation

Requirements

• FiveM Server Build 5181+

• oxmysql

• Framework: ESX Legacy or QBCore

Optional Dependencies

Resource	Purpose
loaf_housing	Furniture reward type
Deco Items Pack	Props for furniture
xex_lootboxes	Lootbox item rewards

Quick Start

1

Place resource

Place 'xex_battlepass' in your resources/[xex]/ folder

2

Add to server.cfg

Add to server.cfg:

ensure oxmysql
ensure xex_battlepass

3

Configure

Configure config.lua

4

Restart

Restart server (database tables are created automatically)

Note: Database tables (user_battlepass, user_premium) and season state (KVP) are created automatically. No manual SQL import is required.

Configuration

General Settings

Config.ModActivated = true            -- Master on/off switch
Config.Debug = false                  -- Enable debug commands
Config.MenuCommand = 'battlepass'     -- Command to open battle pass UI
Config.PremiumCommand = 'premium'     -- Command to open premium shop
Config.ExtraDaysToEnd = 5             -- Grace days after day 30 before season resets

Option	Default	Description
Config.ModActivated	true	Master switch for the entire system
Config.Debug	false	Enables debug commands (getbpdata, restclaimedbpday, restbpday)
Config.MenuCommand	'battlepass'	Chat command to open the battle pass calendar
Config.PremiumCommand	'premium'	Chat command to open the premium shop
Config.ExtraDaysToEnd	5	Days of grace period after all 30 days have passed

Framework Settings

Config.Framework = 'esx'              -- 'esx' | 'qb'
Config.Language = 'en'                -- 'en' | 'es'
Config.CheckForUpdates = true

Premium System

Config.PremiumCoin = 'bank'           -- Account used for premium payments

Config.PremiumOptions = {
    {
        months = 1,
        price = 50000,
        label = '1 Month VIP',
        img = 'vip_1month.png',
    },
    -- ... more packages
}

Reward Schedule (Days 1-30)

Each day defines a normal reward (for all players) and a vip reward (premium only):

Config.Schedule = {
    {
        day = 1,
        items = {
            normal = {
                type = 'item',
                name = 'bread',
                label = 'Bread',
                quantity = 10,
                img = 'bread.png',
            },
            vip = {
                type = 'furniture',
                name = 'murm_dec_pack_chair_1',
                label = 'Deco Chair',
                quantity = 1,
                img = 'chair.png',
            },
        },
    },
    -- ... days 2-30
}

Reward Types

Type	Fields	Description
item	name, label, quantity, img	Inventory item (e.g., bread, bandage)
weapon	name, label, img	Weapon (quantity always 1)
money	name (account), label, quantity, img	Currency (money, bank, black_money)
vehicle	name (spawn name), label, img	Vehicle (spawned + stored in garage)
furniture	name (object hash), label, img	loaf_housing furniture piece

Discord Webhooks

Config.WebhookEnabled = true
Config.Webhook = 'https://discord.com/api/webhooks/...'
Config.BotName = 'BattlePass'
Config.WebhookServerName = 'My Server'
Config.IconUrl = 'https://i.imgur.com/...'
Config.DateFormat = '%d/%m/%Y %H:%M'

Database

Tables are automatically created on first start:

user_battlepass

Tracks player claim progress per season.

user_premium

Tracks premium subscription start/end dates.

If you need to create them manually, use the included scripts.sql file.

How It Works

Complete Flow

Player types /battlepass → Client requests data from server
→ Server checks player's claim history + premium status + current day
→ NUI shows 30-day grid:
   ├── Green: Already claimed
   ├── Gold: Available today (click to claim)
   ├── Locked: Future days
   └── VIP badge: Premium-only rewards
Player types /premium → Premium shop opens
   ├── Select package (1 month, 3 months, etc.)
   └── Purchase with bank account

Daily Claim Logic

• Server tracks global "current day" via KVP (xex_bp:state)

• Player can only claim the current day if all previous days are claimed

• Each claim is recorded in user_battlepass table

• Normal rewards given to all players

• VIP rewards given only to premium subscribers

Premium VIP System

• Players purchase VIP through /premium command

• VIP subscription has start and end dates stored in user_premium

• VIP unlocks exclusive vip tier rewards on each day

• Multiple package durations can be configured (1 month, 3 months, etc.)

• Renewal extends the existing end date

Season Lifecycle

1. Season starts at day 1

2. Each real day advances the season by 1

3. After day 30, grace period of Config.ExtraDaysToEnd days

4. After grace period, season resets (KVP cleared, new season begins)

Retroactive VIP Rewards

When a player purchases VIP mid-season, they retroactively receive all VIP rewards for previously claimed days. This ensures no VIP content is missed.

NUI Interface

Battle Pass Grid

• 30-day calendar grid layout

• Visual states: Claimed (green check), Available (golden glow), Locked (grey)

• Normal reward icon on left, VIP reward icon on right

• Claim button for available days

• VIP badge for premium rewards

Premium Shop

• Package cards with duration, price, and image

• Purchase confirmation

• Active subscription status display

• Renewal option for existing subscribers

Exports & Events

Client Exports

-- Check if current player has active premium
local hasPremium = exports['xex_battlepass']:isPremium()
-- Returns: boolean

Server Exports

-- Check if a specific player has active premium
local hasPremium = exports['xex_battlepass']:isPremium(playerId)
-- Returns: boolean

-- Trigger manual update check
exports['xex_battlepass']:CheckForUpdates()

Server Callbacks

Callback	Parameters	Returns	Description
xex_battlePass:canClaim	—	boolean	Check if player can claim today
xex_battlePass:claimDayRewards	—	result	Process and deliver today's reward
xex_battlePass:buy	packageIndex	result	Purchase premium subscription
xex_battlePass:renew	packageIndex	result	Renew premium subscription

Net Events

Event	Direction	Description
xex_battlePass:loadData	Server → Client	Send battle pass state to client
xex_battlePass:rewardVehicle	Server → Client	Spawn rewarded vehicle client-side

NUI Callbacks

Callback	Description
claimDay	Claim the current available day's reward
closeButton	Close the battle pass UI

Commands

Command	Context	Description
/battlepass	Client	Opens the battle pass calendar
/premium	Client	Opens the premium shop
battlepass_update	Server Console	Force update check

Debug Commands

Only available when Config.Debug = true

Command	Description
/getbpdata	Reload your battle pass data from server
/restclaimedbpday	Roll back your last claimed day
/restbpday	Roll back the global battle pass day counter

Localization

Supported Languages

Code	Language
en	English
es	Español

Adding Languages

Add a new entry in locales.lua:

Locales['fr'] = {
    ['received'] = 'Reçu',
    ['daily_limit'] = 'Déjà réclamé aujourd\'hui',
    -- ... all keys
}

Then set Config.Language = 'fr' in config.lua.

File Structure

xex_battlepass/
├── client/
│   ├── esx.lua               # ESX client logic
│   ├── qb.lua                # QBCore client logic
│   └── scrow.lua             # Shared NUI bridge (escrow)
├── server/
│   ├── esx.lua               # ESX server — rewards, premium, claims
│   ├── qb.lua                # QBCore server mirror
│   ├── scrow.lua             # Auto DB creation, KVP helpers (escrow)
│   └── updater.lua           # Version checker
├── ui/
│   ├── ui.html               # NUI markup
│   ├── style.css             # Dark themed styles
│   ├── script.js             # NUI logic (vanilla JS)
│   └── img/                  # Reward images
├── config.lua                # Full configuration (563 lines)
├── locales.lua               # Translations (en/es)
├── scripts.sql               # Database schema (optional manual import)
├── fxmanifest.lua            # Resource manifest
├── readme.md                 # Quick start readme
└── DOCS.md                   # This documentation

Troubleshooting

Issue	Solution
UI doesn't open	Verify Config.ModActivated = true and resource is started
"Missing locale key" in console	Add the missing key to locales.lua
Rewards not given	Check Config.Schedule — reward name must match your inventory items
Webhook not working	Verify Config.WebhookEnabled = true and URL is valid
oxmysql errors	Ensure oxmysql is started before xex_battlepass in server.cfg
Premium purchase fails	Check Config.PremiumCoin matches a valid account type (bank, money)
Vehicle reward doesn't spawn	Check vehicle model name in Config.Schedule is valid
Furniture reward fails	Requires loaf_housing resource installed and running
Season not advancing	Check KVP state — use debug commands to inspect/reset
Day counter stuck	Use /restbpday (debug mode) to correct the global counter

Changelog

v2.0.0

• Migrated UI from jQuery to vanilla JavaScript

• Redesigned UI with dark gaming aesthetic (Inter font, CSS custom properties)

• Migrated from mysql-async to oxmysql

• Added centralized XeX updater system

• Fixed critical bugs: undefined variables, typos, exposed webhook URLs

• Fixed security: removed exploitable net event for notifications

• Modernized ESX/QB init patterns (exports instead of events)

• Improved identifier matching (prefix-based instead of loose string.find)

• Added nil guards throughout server logic

• Cleaned up duplicate NUI callbacks

• Removed debug prints from production code

• Added proper database indexes and column types

• Full code cleanup and section organization

v1.x

• Initial release with ESX + QBCore support

Support

Channel	Link
Discord	discord.gg/9yY3Jxnhh8