🛠️Script Configuration

Config Settings & Explanations

Advent Calendar Script Configuration

This documentation outlines the available settings for the Advent Calendar script for your FiveM server. Follow the instructions below to configure the script to your preferences.

General Configuration

• Config.Language: Sets the language for the script. Default options are English (en) and German (de). Additional languages can be configured in language.lua.

  Config.Language = 'en'

• Config.Debug: Enables debug mode. When set to true, debug messages will be printed to the console.

  Config.Debug = false

• Config.SQL: Specifies the SQL library the script should use. Can be set to either oxmysql or mysql-async.

  Config.SQL = 'oxmysql'

• Config.Month: The month when the advent calendar is active. Typically set to December (12).

  Config.Month = 12

• Config.requiredPlaytime: The required playtime (in minutes) that a player must have on the server before they can open the advent calendar. To disable this requirement, set it to 0.

  Config.requiredPlaytime = 3

• Config.Command: The command players use to open the advent calendar UI.

  Config.Command = "advent"

• Config.missedDays: Determines whether players can open doors for missed days. Set to false to disable. This feature is great for players who not log in every day or just for new players on your server.

  Config.missedDays = true

• Config.RewardType: Defines the reward type. static assigns rewards based on the day, while random selects a reward from a list.

  Config.RewardType = "random"

Item Configuration

• Config.Item: If enabled, the advent calendar can be added as an inventory item, which players can use to open the UI.

  Config.Item = {
      enable = true,
      name = 'adventcalendar',
      label = 'Advent Calendar'
  }

Advent Calendar Locations Configuration

The Advent Calendar script allows you to set up multiple reward spots around the map. Each spot can have its own marker, blip, and NPC settings. You can add as many spots as you like by copying and modifying the configuration for each new spot.

Example Spot Configuration

Below is an example of how to configure a reward spot. Remember not to use the same spot name twice. You can copy and paste the entire block to create more spots and adjust their values accordingly.

Config.Coords = {
    ["Spot 1"] = { 
        coords = vec3(-83.93, -835.70, 39.0), -- Coords for the DAILY Rewards Spot, marker, and blip.

        marker = {
            enable = true, -- Enable or disable the marker.
            type = 1, -- Marker type (refer to FiveM documentation for marker types).
            size = {
                x = 1.0, -- Width of the marker.
                y = 1.0, -- Length of the marker.
                z = 1.0, -- Height of the marker.
            },
            color = {
                r = 255, -- Red value of the marker color.
                g = 204, -- Green value of the marker color.
                b = 0,   -- Blue value of the marker color.
                a = 100, -- Alpha (transparency) of the marker color.
            },
        },

        blip = {
            enable = true, -- Enable or disable the blip on the map.
            sprite = 781, -- Blip icon (refer to FiveM documentation for blip icons).
            color = 5, -- Blip color (refer to FiveM documentation for blip colors).
            scale = 1.0, -- Scale/size of the blip.
            name = 'DAILY REWARD', -- Name of the blip that will be shown on the map.
        },

        npc = {
            enable = true, -- Enable or disable the NPC at the spot.
            model = 'a_m_y_skater_01', -- Model for the NPC (refer to the available ped models).
            coords = vec3(-83.93, -835.70, 39.6), -- Coords for the NPC.
            heading = 150.23, -- Heading for the NPC.
        },
    },
}

To create additional spots, simply duplicate the ["Spot 1"] block within the Config.Coords table, rename it to something unique like ["Spot 2"], and adjust the coordinates and settings as needed.

Please ensure the coordinates, blip sprites, marker types, and NPC models are valid and available in your server's resources.

Rewards Configuration

The Advent Calendar script allows you to configure rewards that players can receive. These rewards can be configured to be static, based on the day, or random, where a random reward from the list will be chosen each time.

Configuring Rewards

Rewards are defined in the Config.Rewards table. Each entry corresponds to a day of the advent calendar, and the script will select rewards based on the configuration.

Config.Rewards = {
    [1] = { -- Day 1 reward example
        type = 'item', -- Type of reward (item, money, weapon, vehicle)
        name = 'bread', -- Name of the item, weapon, or vehicle
        amount = 1, -- Amount of the item, money, or weapon ammo
        label = 'Bread', -- Label to be shown in the UI
    },
    [2] = { -- Day 2 reward example
        type = 'money', 
        name = 'cash', -- Type of money (cash, bank, black_money)
        amount = 1000, -- Amount of money
        label = '1000$ Cash', -- Label to be shown in the UI
    },
    [3] = { -- Day 3 reward example
        type = 'weapon', 
        name = 'WEAPON_PISTOL', -- Name of the weapon
        amount = 50, -- Amount of ammo 
        label = '50 AMMO PISTOL', -- Label to be shown in the UI
    },
    [4] = { -- Day 4 reward example
        type = 'vehicle',  
        name = 'adder', -- Name of the vehicle
        amount = 1, -- Number of vehicles (usually 1)
        label = 'ADDER', -- Label to be shown in the UI
    },
    // ... Add more rewards for each day as needed
}

When setting the type of the reward, ensure that the name corresponds correctly to an item, currency type, weapon, or vehicle available in your game. The amount should reflect a reasonable value for the reward type. For example, for money, it could be the dollar amount, and for weapons, it could be the number of bullets.

Random vs. Static Rewards

• Static: The reward for each day is predetermined. For example, on day 1, players will always receive the item "bread".

• Random: Each day, a random reward from the provided list is chosen.

To set the type of reward distribution, adjust the Config.RewardType variable at the beginning of your config file.

Feel free to add more rewards and customize them to fit the needs of your server and players. The above examples are just a starting point, and you can create a rewarding experience that keeps players engaged throughout the holiday season.

Vehicle Database Configuration

The Advent Calendar script interacts with the vehicle database to manage vehicle rewards. To ensure compatibility with your server's database structure, you need to configure the database table and column names that the script will use.

Configuration Details

The configuration is done within the Config.vehicleSQL table in your config file. Here's what each option means:

Config.vehicleSQL = {
    tableName = 'owned_vehicles', -- The name of the table in the database where vehicle information is stored.
    plateColumn = 'plate', -- The name of the column in the table that stores the vehicle's plate number.
    ownerColumn = 'owner', -- The name of the column in the table that stores the identifier of the vehicle's owner.
}

Make sure to replace 'owned_vehicles', 'plate', and 'owner' with the actual names of the table and columns used in your server's database. This will allow the script to correctly identify which vehicles are owned by which players and manage the distribution of vehicle rewards.

Handling Vehicle Rewards

When a player receives a vehicle as a reward, the script will create an entry in the specified database table with the player's identifier and the vehicle's details. It is important to ensure that the column names match your database schema to prevent any issues.

Customize the database configuration to match your server's setup, and the Advent Calendar script will handle the rest, providing vehicle rewards smoothly to your players.

Custom Trigger Events Configuration

The Advent Calendar script provides functionality to notify clients and servers about various events. These notifications are essential for the script to function correctly and to provide feedback to players. The script is set up to work with ESX by default, but you can change the trigger events to match your framework or script.

Notification Functions

-- Client-side notification
function clientNotify(message)
    TriggerEvent("esx:showNotification", message)
end

-- Server-side notification
function serverNotify(source, message)
    TriggerClientEvent("esx:showNotification", source, message)
end

These functions are used throughout the script to send notifications to players. The clientNotify function triggers an event that can be listened to on the client side, whereas the serverNotify function sends a message from the server to a specific client.

Debug Function

function debug(msg)
    if Config.Debug then
        print(('^3[NKN-ADVENT]^0 %s'):format(msg))
    end
end

The debug function is a utility function that prints debug messages to the console. It will only print messages if debug mode is enabled in the configuration (Config.Debug set to true).

Trigger Event Configuration

Config.Triggers = {
    playerLoaded = 'esx:playerLoaded', -- Event triggered when a player has finished loading
    playerDropped = 'playerDropped', -- Event triggered when a player has disconnected
}

The Config.Triggers table contains the events that the Advent Calendar script listens for. By default, these are set to common ESX events. If your server uses a different framework or if you have custom events for player loading and dropping, you should update these event names accordingly.

Ensure that the trigger events match those used by your server's framework to allow the Advent Calendar script to integrate seamlessly with your existing setup. This will enable the script to respond to player connections and disconnections, as well as provide timely notifications.