Configuration

All options are in config.lua.

Below is a structured overview of the main sections.

---

Locale & Notifications

Config.Locale

• Type: string

• Default: 'hr'

• Description: Current language key used for Locales[...].

  • Provided: en, hr

  • You can add more by creating locales/<lang>.lua and adding Locales['<lang>'] = { ... }.

---

Config.Notify

Config.Notify = {
    provider = 'okok' -- 'esx', 'qb', 'ox', 'wasabi', 'okok'
}

• Selects which notify system Notify() will use.

• See Developer API for details: https://3mstudio.github.io/3MStudioDocs/3M_Christmas/Developers.html#notify-export

---

Debug

Config.Debug = {
    present     = true,
    ForceActive = false
}

• present

  • When true, daily limits for Santa spot rewards are disabled. Helpful for testing spots & drops.

• ForceActive

  • When true, event is considered active regardless of Config.TimeWindow. Use this for testing outside the configured date range.

---

Event Window & Calendar

Config.CalendarKeyItem

Config.CalendarKeyItem = 'xmas_key'

• Name of the inventory item that unlocks the calendar window for the current day.

---

Config.TimeWindow

Config.TimeWindow = {
    start  = { month = 11, day = 1 },
    finish = { month = 11, day = 25 }
}

• Controls which real-world dates count as “event days” (1..N).

• Used for:

  • Advent Calendar day index

  • Per-day quest completion

  • Key reward uniqueness

---

Weather Lock

Config.ChangeWeather = {
    enabled        = true,
    provider       = 'auto',  -- 'auto' | 'cd_easytime' | 'qb-weathersync' | 'none'

    weatherType    = 'XMAS',  -- GTA weather type

    freezeTime     = false,
    dynamicWeather = false,
    blackout       = false,

    pollInterval   = 30000,   -- server: check event active
    clientReapply  = 30000    -- client: reapply weather/time
}

• enabled: master on/off for weather lock.

• provider:

  • auto – auto-detect cd_easytime or qb-weathersync, otherwise internal fallback.

  • cd_easytime – force that provider.

  • qb-weathersync – force that provider.

  • none – no automatic weather control.

• weatherType: weather name set during event (e.g. XMAS, SNOW).

• freezeTime, dynamicWeather, blackout: passed to provider when supported.

• pollInterval: how often the server re-checks whether the event should be active.

• clientReapply: how often clients reapply weather/time locally.

---

Vehicle Keys for Quest Van

Config.Keys = {
    provider = 'wasabi',      -- 'none' | 'wasabi' | 'qs' | 'qb' | 'brutal'
    label    = 'Christmas Van'
}

• provider:

  • none – no external key system is used.

  • wasabi – wasabi_carlock.

  • qs – qs-vehiclekeys.

  • qb – qb-vehiclekeys.

  • brutal – brutal_keys.

• label: used only for some key systems (e.g. brutal_keys) as display name.

---

Global Tree

Config.Tree = {
    coords = vector4(159.9889, -1005.0620, 29.4178, 0.0),

    stages = {
        { xp = 0,    model = 'borcina' },
        { xp = 250,  model = 'borcina' },
        { xp = 500,  model = 'borcina' },
        { xp = 750,  model = 'borcina' },
        { xp = 1000, model = 'xmas_tree_stage5' }
    }
}

• coords: position and heading of the main tree.

• stages: list of XP thresholds and tree models.

  • The highest xp that is <= current tree XP defines the active stage.

  • You can use different models for each stage.

---

Donations & Santa Spots

Config.DonationsPerDay      = 2
Config.SantaSpotDailyLimit  = 5
Config.CarryGiftModel       = '3m_xmas_gift'

• Config.DonationsPerDay: Max donation actions per player per day at the main tree.

• Config.SantaSpotDailyLimit: Max number of items rewarded per player per day from Santa spots.

• Config.CarryGiftModel: Prop model used when carrying gifts picked from Santa spots.

---

Config.SantaSpots

Config.SantaSpots = {
    {
        id   = 'legion_square',
        tree = {
            coords = vector4(133.0702, -988.5129, 29.3581, 0.0),
            model  = 'prop_xmas_tree_int'
        },
        gifts = {
            { coords = vector4(131.0391, -977.5129, 29.3582, 0.9), model = '3m_xmas_gift' },
            -- more gifts...
        }
    },
    -- more spots...
}

• Each entry defines one Santa spot:

  • id: unique identifier (string). If omitted, auto-generated.

  • tree: small decorative tree:

    • coords: position/heading.

    • model: object name.

  • gifts: list of gift props around the tree:

    • coords: where each gift sits.

    • model: usually 3m_xmas_gift.

Players can pick up these gifts and carry them to the main tree to receive a random ornament.

---

Toys (placeable props)

Config.Toys = {
    ['snowball'] = {
        prop          = 'xm3_prop_xm3_snowman_01b',
        spawnDistance = 1.0,
        faceAway      = true,
        headingOffset = 0.0,
        zOffset       = 0.0,
        interactive   = true
    }
}

• Map inventory item names to world props.

• Fields:

  • prop: model name to spawn.

  • spawnDistance: distance in front of player to spawn.

  • faceAway: if true, prop faces away from player.

  • headingOffset: rotation offset.

  • zOffset: vertical offset.

  • interactive:

    • true – use preview/placement mode (arrows + Q/R + PageUp/PageDown).

    • false – spawn directly.

You can add as many entries as you want.

---

Ped Toys (shoulder plushes)

Config.PedToys = {
    ['xmas_plush_elf'] = {
        prop     = 'sum_prop_sum_arcade_plush_01a',
        bone     = 10706,
        offset   = vector3(0.08, -0.02, 0.05),
        rotation = vector3(0.0, 0.0, 190.0)
    },
    ['xmas_plush_elf2'] = { ... },
    ['xmas_plush_elf3'] = { ... },
    ['xmas_plush_elf5'] = { ... },
    ['xmas_plush_elf7'] = { ... }
}

• Each key is an item name which toggles a plush on the player’s shoulder.

• Fields:

  • prop: model name.

  • bone: ped bone index (e.g. 10706 = shoulder).

  • offset: vector3 position offset.

  • rotation: vector3 rotation.

Logic:

• No toy → use item → attach.

• Same toy active → use item → detach.

• Different toy active → show notification (no swap).

---

Santa Delivery Quest

Config.Quest = {
    enabled = true,

    NPC = {
        model  = 's_m_m_mariachi_01',
        coords = vector4(160.7701, -1009.3114, 28.5505, 158.7634)
    },

    Vehicle = {
        model        = 'burrito3',
        coords       = vector4(159.5688, -1012.4126, 29.3917, 66.7903),
        returnCoords = vector4(159.5688, -1012.4126, 29.3917, 66.7903),
        returnRadius = 5.0
    },

    TreeXP = 20,

    RewardItems = {
        { item = 'xmas_star',    min = 1, max = 3 },
        { item = 'snowball',     min = 1, max = 2 },
        { item = 'santa_cookie', min = 1, max = 1 }
    },

    KeyReward = {
        item   = 'xmas_key',
        chance = 100
    },

    Deliveries = {
        { coords = vector3(125.0, -1045.0, 29.2), radius = 25.0 },
        -- ...
    }
}

• enabled: master on/off.

• NPC: quest giver ped.

• Vehicle:

  • model: van model.

  • coords: spawn position.

  • returnCoords, returnRadius: where the player must return the van.

• TreeXP: how much global tree XP to add when quest is completed.

• RewardItems: random item rewards for the player.

• KeyReward:

  • item: calendar key item.

  • chance: % chance to also give a key on completion.

• Deliveries: positions and radius for each drop-off.

---

Donation Items

Config.DonationItems = {
    xmas_ball           = { xp = 2 },
    xmas_garland        = { xp = 4 },
    xmas_star           = { xp = 6 },
    santa_cookie        = { xp = 8 },
    snowball            = { xp = 10 },
    candy_cane          = { xp = 12 },
    exclusive_xmas_hat  = { xp = 16 }
}

• Keys are item names, values define how much XP they give to the global tree.

• Used when the player chooses Donate ornaments on the main tree.

• You can modify, add or remove entries freely.

---

Calendar Rewards

Config.CalendarRewards = {
    [1]  = { items = { { name = 'xmas_plush_elf2', count = 2  } } },
    [2]  = { items = { { name = 'snowball',        count = 10 } } },
    [3]  = { items = { { name = 'candy_cane',      count = 3  } } },
    -- ...
    [24] = { items = { { name = 'xmas_star',       count = 1  } } },
    [25] = { items = { { name = 'money',           count = 24000 } } }
}

• Indexed by event day (1 = first day of Config.TimeWindow.start).

• Each entry:

  • items – array of { name = <itemName>, count = <number> }

  • The special "money" name pays cash (through Framework.AddMoney).

You can fully customize this table to match your economy and item set.

---