🎄ADVENT CALENDAR

📅 Advent Calendar - AdvCalendar

📋 Description

AdvCalendar is a FiveM script that allows players to collect daily rewards during the Christmas period. The script displays an interactive advent calendar with a modern user interface and festive visual effects.

✨ Features

  • 🎁 Daily reward system : Players can open one box per day

  • 🎄 Festive user interface : Modern design with snow effects and animations

  • 👤 Interactive NPC : A Christmas vendor appears at a configurable location

  • 💾 Database saving : Tracks rewards collected per player

  • 🔄 Multi-framework support : Compatible with ESX and QBCore

  • 🎁 Various reward types : Items, cash, weapons

  • 🌍 Translation system : Customizable messages

📦 Prerequisites

  • Framework : ESX Legacy or QBCore

  • Database : MySQL (mysql-async)

  • FiveM Version : Recommended (fx_version cerulean)

  • Lua 5.4 : Enabled

🚀 Installation

1. Download

Download the script and place it in your resources folder.

2. Database

Execute the provided SQL file in your database :

CREATE TABLE IF NOT EXISTS `advcalendar` (
  `id` int NOT NULL AUTO_INCREMENT,
  `identifier` varchar(255) DEFAULT NULL,
  `date` int DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb3;

3. Configuration

Add the script to your server.cfg :

ensure advcalendar

4. Dependencies

Make sure the following dependencies are loaded before the script :

  • mysql-async

  • Your framework (ESX or QBCore)

⚙️ Configuration

All settings are configurable in the shared/config.lua file.

Framework

Chrismas.framework = "esx" -- "esx" or "qb" for QBCore

NPC Location

Chrismas.Coords = vec4(244.509888, -871.727478, 30.290894, 2.834646)
-- Format : vec4(x, y, z, heading)

NPC Model

Chrismas.Vendor = "mp_m_freemode_01"
-- Note : Use an "mp_" model to keep Christmas clothing

Translations

Customize all messages in Chrismas.Translate :

Chrismas.Translate = {
    Open                = "Press ~o~E~w~ to open ~o~Advent Calendar",
    Receive             = "You have received",
    Wishes              = "WISHING YOU A",
    MerryChristmas      = "Merry<br>Christmas",
    AlerteMessage       = "Recover your previous rewards",
    AlreadyRetrieved    = "You have already retrieved your reward",
    OpenReward          = "You have opened your reward"
}

Rewards

Configure rewards for each day (0-25) in Chrismas.Item :

Chrismas.Item = {
    [0]     = {}, -- Day 0 (no reward)
    [1]     = {object="item", label="Bread", name="bread", count=3},
    [2]     = {object="cash", label="Cash", name="", count=15000},
    [3]     = {object="weapon", label="Pistol", name="WEAPON_PISTOL", count=1},
    -- ... up to day 25
}

Available reward types :

  • item : Inventory item

  • cash : Cash money

  • weapon : Weapon

Parameters :

  • object : Reward type ("item", "cash", "weapon")

  • label : Display name of the reward

  • name : Item/weapon name (empty for cash)

  • count : Quantity

Logs

Enable or disable database logs :

Chrismas.Log = true -- true to enable logs

🎮 Usage

For players

  1. Go to the configured advent calendar location

  2. Approach the NPC (Christmas vendor)

  3. Press E to open the calendar

  4. Click on the corresponding day's box to collect your reward

  5. You can only open one box per day

Progression system

  • Players can only open the current day's box

  • If a player has already collected their reward for the day, they cannot collect it again

  • The system automatically tracks each player's progression

📁 File Structure

advcalendar/
├── client/
│   ├── client.lua          # Main client script
│   └── function.lua        # Utility functions
├── server/
│   └── server.lua          # Main server script
├── shared/
│   └── config.lua          # Shared configuration
├── ui/
│   ├── index.html          # User interface
│   ├── css/                # CSS styles
│   ├── js/                 # JavaScript scripts
│   ├── images/             # Images and textures
│   ├── fonts/              # Custom fonts
│   └── sound/              # Sounds and music
├── fxmanifest.lua          # FiveM manifest
└── create-advcalendar.sql  # SQL table creation script

🔧 Framework Support

ESX

The script uses standard ESX exports :

  • ESX.GetPlayerFromId()

  • xPlayer.addMoney()

  • xPlayer.addInventoryItem()

  • xPlayer.addWeapon()

QBCore

The script uses standard QBCore exports :

  • QBCore.Functions.GetPlayer()

  • xPlayer.Functions.AddMoney()

  • xPlayer.Functions.AddItem()

🐛 Troubleshooting

NPC doesn't appear

  • Check that coordinates in config.lua are correct

  • Make sure the NPC model is valid

  • Check server logs for any errors

Rewards are not given

  • Verify that the database is properly configured

  • Make sure item/weapon names are correct

  • Check server logs for MySQL errors

Interface doesn't open

  • Verify that all UI files are present

  • Make sure ui_page is properly configured in fxmanifest.lua

  • Check F8 console for JavaScript errors

📝 Important Notes

  • ⚠️ The NPC must use an "mp_" model to keep Christmas clothing

  • ⚠️ Players can only open one box per day

  • ⚠️ The system automatically checks if a reward has already been collected

  • ⚠️ Make sure mysql-async is loaded before this script

Merry Christmas ! 🎄🎁

PreviousGUIDEBOOKNextEMOTE UI

Last updated