Documentazione ufficiale · MintDev

Caccia ai Regali

Grazie per aver scelto uno script MintDev! Qui trovi tutto per installare, configurare e gestire l'evento di Natale sul tuo server FiveM.

v1.0.0ESX LegacyQBCoreQboxox_inventoryqb-inventory

01Introduzione

Caccia ai Regali riempie la città di regali nascosti. I giocatori li cercano con un rilevatore "freddo / caldo", li aprono per primi e spendono i fiocchi di neve al Mercatino di Natale, dove c'è anche il calendario dell'Avvento.

Regali nascosti

Regali in punti casuali della mappa: zona sul radar, rilevatore con i campanellini, chi apre per primo vince.

Sorprese

4 sorprese: carbone, scivolone sul ghiaccio, renna impazzita e bufera di neve.

Mercatino di Natale

Dolci, bevande calde, oggetti, scambio fiocchi → soldi, calendario dell'Avvento e classifica.

Extra

Alberi con luci da posizionare, regali da donare ad altri giocatori e calza della Befana.

02Requisiti

03Contenuto del pacchetto

xm_caccia_regali/
├── config.lua              impostazioni (commentate)
├── fxmanifest.lua
├── shared/lang.lua         tutti i testi del gioco
├── bridge/server.lua       collegamento a framework, soldi e inventario
├── client/  server/        logica dello script
├── html/                   interfaccia del mercatino, rilevatore e popup
├── stream/                 10 prop 3D (.ydr) + xm_natale_props.ytyp
├── install/
│   ├── ox_inventory_items.lua
│   ├── qb-core_items.lua
│   ├── esx_items.sql
│   └── immagini_inventario/   14 icone PNG
├── data/                   dati salvati dallo script
├── DOCUMENTAZIONE.html     questa documentazione, offline
└── LICENZA.txt

Tutto è in un'unica risorsa: script, interfaccia, prop e file di installazione. Con Cfx Asset Escrow una parte dei file è protetta, mentre quelli che servono per personalizzare lo script restano aperti:

04Installazione

1. Scarica la risorsaDopo l'acquisto la trovi su portal.cfx.re → Assets → Granted Assets. Usa lo stesso account Cfx della sv_licenseKey del tuo server.
2. Copia la risorsaEstrai lo zip e metti la cartella xm_caccia_regali dentro resources/. Non rinominare le sottocartelle.
3. Avviala dopo framework e inventarioNel server.cfg l'ordine è importante: lo script riconosce il framework all'avvio.

   ensure es_extended        # oppure qb-core / qbx_core
   ensure ox_inventory       # solo se lo usi
   ensure xm_caccia_regali

4. Registra gli oggettiScegli il file giusto per il tuo inventario:
   ox_inventoryQBCore (qb-inventory)ESX (inventario base)

   Vale per ESX + ox_inventory, QBCore + ox_inventory e Qbox. Copia il contenuto di install/ox_inventory_items.lua dentro ox_inventory/data/items.lua, all'interno della tabella return { ... }:

   ['xm_fiocco'] = {
       label = 'Fiocco di Neve',
       weight = 2,
       stack = true,
       close = false,
       description = 'La moneta di Natale. Spendila al Mercatino di Natale!',
   },
   -- ...e gli altri 13 oggetti del file

   Copia le righe di install/qb-core_items.lua dentro qb-core/shared/items.lua, nella tabella QBShared.Items:

   xm_fiocco = { name = 'xm_fiocco', label = 'Fiocco di Neve', weight = 2, type = 'item', image = 'xm_fiocco.png', unique = false, useable = false, shouldClose = false, description = 'La moneta di Natale.' },
   -- ...e gli altri 13 oggetti del file

   Esegui install/esx_items.sql nel database del server (HeidiSQL, phpMyAdmin...). Fiocchi e stelle hanno peso 0, così non riempiono l'inventario.

   INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
       ('xm_fiocco', 'Fiocco di Neve', 0, 0, 1),
       -- ...
   ON DUPLICATE KEY UPDATE `label` = VALUES(`label`), `weight` = VALUES(`weight`);

5. Copia le immaginiLe 14 icone sono in install/immagini_inventario/:
   • ox_inventory → ox_inventory/web/images/
   • qb-inventory → qb-inventory/html/images/
   • altri inventari → la cartella immagini del tuo inventario
6. Dai i permessi adminAggiungi l'ace nel server.cfg (dettagli in Permessi):

   add_ace group.admin xm_regali.admin allow

7. Riavvia e controlla la consoleAll'avvio deve comparire una riga come questa:

   [xm_regali] Caccia ai Regali by MintDev.eu | framework: esx | inventario: ox_inventory

   Se leggi Nessun framework trovato, la risorsa parte prima del framework: sistema l'ordine degli ensure.

05Primo avvio

Lo script è subito utilizzabile, ma i nascondigli dei regali e la posizione del mercatino li decidi tu. In 5 minuti:

1. Posiziona il MercatinoVai dove vuoi il punto di scambio, guarda nella direzione in cui deve guardare il venditore e scrivi /xmmercatino. Di base è a Legion Square.
2. Crea i nascondigliVai in un punto all'aperto (dietro una panchina, in un vicolo, su un tetto raggiungibile...) e scrivi /xmregalo aggiungi Nome del posto. Ripeti in giro per la città.
3. ControllaCon /xmregalo debug vedi tutti i punti: verdi quelli con un regalo nascosto in questo momento. /xmregalo rigenera rimescola i regali.
4. Avvia l'evento/xmevento on avvisa tutti i giocatori. A fine evento usa /xmevento off.

06Configurazione · Generale

Tutte le impostazioni sono in config.lua, commentate. Dopo una modifica riavvia la risorsa con ensure xm_caccia_regali.

Config.Framework = 'auto'   -- 'auto' | 'esx' | 'qb' | 'qbx'
Config.Inventory = 'auto'   -- 'auto' | 'ox' | 'framework'

Config.AdminAce = 'xm_regali.admin'
Config.AdminGroups = { 'admin', 'superadmin', 'god' }

Config.InteractKey = 38         -- E
Config.CancelKey = 73           -- X
Config.SoundVolume = 0.35
Config.Notifications = 'auto'   -- 'auto' | 'esx' | 'qb' | 'qbx' | 'ox' | 'nui' | 'custom'
Config.CustomNotify = function(msg, kind)
    TriggerEvent('chat:addMessage', { args = { 'Caccia ai Regali', msg } })
end
Config.PreferCustomProps = true

Config.FlakeItem = 'xm_fiocco'
Config.StarItem = 'xm_stella'
Config.CoalItem = 'xm_carbone'
Config.StarScore = 10

07Configurazione · Caccia ai regali

Config.Hunt = {
    MaxActive = 8,              -- regali nascosti contemporaneamente
    RespawnTime = 90,           -- secondi prima che ne compaia uno nuovo
    OpenTime = 3500,
    InteractDistance = 1.8,
    PlayerCooldown = 15,        -- secondi tra due regali aperti dallo stesso giocatore

    AreaBlips = true,           -- cerchio sulla mappa (non il punto esatto)
    AreaRadius = 80.0,
    HotCold = true,             -- rilevatore freddo / caldo con i campanellini
    HotColdRange = 120.0,

    Chances = { gift = 62, rare = 8, surprise = 30 },   -- la somma deve fare 100
    Gift = { min = 3, max = 8 },
    Rare = { star = 1, flakes = { min = 5, max = 10 } },

    Surprises = {
        { id = 'carbone',   weight = 30 },
        { id = 'scivolone', weight = 25 },
        { id = 'renna',     weight = 25 },
        { id = 'bufera',    weight = 20 },
    },
    -- ...
}

08Configurazione · Punti dei regali

Il modo consigliato è crearli in gioco con /xmregalo aggiungi: vengono salvati in data/luoghi.json e funzionano subito. Puoi anche scriverli nel config:

Config.Spots = {
    { x = 185.5, y = -955.0, z = 30.1, label = 'Legion Square' },
    { x = 501.0, y = 5604.0, z = 797.9, label = 'Vetta del Chiliad' },
}

• Il punto è dove appare il regalo, a terra. L'altezza viene corretta da sola sul terreno.
• I punti del config hanno ID c1, c2...; quelli creati in gioco s1, s2.... I primi si rimuovono dal config, i secondi con /xmregalo rimuovi.
• I punti nel config sono solo d'esempio: crea i tuoi, anche in posti difficili da trovare.

09Configurazione · Mercatino di Natale

Config.Shop = {
    Name = 'Mercatino di Natale',
    Coords = vec4(176.5, -967.5, 29.6, 230.0),   -- oppure /xmmercatino in gioco
    Ped = 's_m_m_strvend_01',
    Distance = 2.2,
    MaxQuantity = 50,
    MoneyAccount = 'cash',                       -- 'cash' oppure 'bank'
    Blip = { Enabled = true, Sprite = 52, Color = 1, Scale = 0.9 },
    Decorations = true,                          -- albero illuminato e regali attorno al banco
    -- ...
}

Catalogo

Ogni voce è un oggetto acquistabile con i fiocchi di neve. category decide la scheda: 'dolci', 'bevande' o 'oggetti'.

Catalog = {
    { item = 'xm_panettone',  price = 10, category = 'dolci' },
    { item = 'xm_cioccolata', price = 6,  category = 'bevande' },
    { item = 'xm_albero',     price = 25, category = 'oggetti' },
},

Scambi

Exchanges = {
    { id = 'fiocchi_soldi',   give = 'xm_fiocco',  giveAmount = 1, money = 20 },
    { id = 'stella_soldi',    give = 'xm_stella',  giveAmount = 1, money = 300 },
    { id = 'stella_fiocchi',  give = 'xm_stella',  giveAmount = 1, item = 'xm_fiocco', itemAmount = 12 },
    { id = 'carbone_fiocchi', give = 'xm_carbone', giveAmount = 5, item = 'xm_fiocco', itemAmount = 1 },
},

give è l'oggetto che il giocatore consegna. Con money riceve soldi sul conto MoneyAccount, con item + itemAmount riceve un oggetto. Il pulsante "Tutti" scambia tutto in una volta (fino a MaxQuantity).

10Configurazione · Calendario dell'Avvento

Il calendario è una scheda del mercatino con 24 porte. Ogni giocatore apre una porta al giorno.

Config.Advent = {
    Enabled = true,
    Mode = 'december',      -- 'december' oppure 'daily'
    Rewards = {
        [1]  = { flakes = 5 },
        [2]  = { item = 'xm_cioccolata', amount = 2 },
        [3]  = { money = 250 },
        [8]  = { stars = 1 },
        [24] = { stars = 3, item = 'xm_albero', amount = 1 },
        -- ...una riga per ogni porta da 1 a 24
    },
}

11Configurazione · Oggetti e cibo

xm_cioccolata = {
    label = 'Cioccolata Calda',
    description = 'Con panna e marshmallow.',
    type = 'drink',         -- 'food' | 'drink' | 'currency' | 'placeable' | 'gift' | 'box'
    anim = 'mug',           -- 'food' | 'drink' | 'mug' (tazza)
    time = 5000,
    thirst = 35, heal = 10, effect = 'calore',
    prop = { custom = 'xm_prop_cioccolata', base = 'p_amb_coffeecup_01' },
},

12Configurazione · Animazioni ed effetti

Config.Effects = {
    SugarMultiplier = 1.15,  -- Bastoncino di Zucchero (massimo 1.49)
    SugarTime = 30,
    TipsyTime = 30,          -- Vin Brulè
}

In Config.Anims trovi le tre animazioni (food, drink, mug) con osso della mano e posizione del prop.

13Alberi, regali da donare e calza della Befana

Config.Trees = {
    Item = 'xm_albero',
    MaxPerPlayer = 2,
    Persist = true,          -- restano dopo un riavvio (data/alberi.json)
    Lights = true,           -- luci colorate che lampeggiano
}

Config.GiftGiving = {
    Item = 'xm_regalo',
    Distance = 3.0,
    Rewards = {
        { type = 'flakes', weight = 45, min = 5, max = 12 },
        { type = 'food',   weight = 35 },
        { type = 'star',   weight = 8,  amount = 1 },
        { type = 'money',  weight = 12, min = 200, max = 600 },
    },
}

Config.Stocking = {
    Item = 'xm_calza',
    OpenTime = 3000,
    Rewards = { ... },       -- flakes, star, food, money, coal
}

Il Regalo da Donare si usa vicino a un altro giocatore: chi lo riceve vede "Un regalo per te!" con il nome di chi l'ha mandato. La Calza della Befana funziona come una scatola a sorpresa, carbone compreso.

14Come si gioca

Caccia ai regali

Sulla mappa compaiono cerchi rossi: in ognuno c'è un regalo nascosto. Avvicinandosi parte il rilevatore in alto ("Gelido", "Freddo", "Tiepido", "Caldo", "Bollente!") con i campanellini sempre più veloci. Il regalo gira su sé stesso ed è illuminato. A meno di 2 metri appare [E] Apri il regalo: si scarta in ginocchio per qualche secondo (X annulla).

Sorprese

Mercatino, cibo e oggetti

• Al mercatino premi E: compra con i fiocchi, scambia nella scheda Scambio, apri la porta del giorno nella scheda Calendario. ESC per chiudere.
• Dolci e bevande si usano dall'inventario: animazione con il prop in mano, poi fame/sete ed eventuali effetti.
• Albero di Natale: usalo per posizionarlo davanti a te. Per raccoglierlo avvicinati e premi E (solo il proprietario o un admin).
• Regalo da Donare: usalo vicino a un amico. Calza della Befana: usala per aprirla.

15Comandi admin

/xmevento, /xmdai e /xmreset funzionano anche dalla console del server (senza la /).

16Permessi

Un giocatore è admin per lo script se vale almeno una di queste condizioni:

• ha l'ace xm_regali.admin (o il permesso generale command);
• su ESX il suo gruppo è in Config.AdminGroups;
• su QBCore ha uno dei permessi in Config.AdminGroups;
• su Qbox ha l'ace group.<gruppo> di uno dei gruppi in Config.AdminGroups.

add_ace group.admin xm_regali.admin allow
# oppure per un singolo giocatore:
add_principal identifier.license:xxxxxxxx group.admin

17Prop 3D

Lo script include 10 prop 3D originali, già pronti nella cartella stream/ e caricati in automatico: non devi convertire o installare nulla.

Il file xm_natale_props.ytyp viene caricato da fxmanifest.lua con la riga data_file 'DLC_ITYP_REQUEST'. Puoi usare i prop anche in altri script con il loro nome (es. `xm_prop_albero`), finché xm_caccia_regali è avviato.

• Per usare i prop originali di GTA al posto di questi metti Config.PreferCustomProps = false.
• Con /xmprova xm_panettone controlli come il prop sta in mano; se serve, correggi customPlacement in Config.Items o Config.Anims.

18Testi e traduzioni

Tutti i testi del gioco (notifiche, suggerimenti, popup, rilevatore) sono in shared/lang.lua. Per tradurre basta cambiare i valori, lasciando uguali le chiavi e i segnaposto %s / %d:

Lang = {
    prompt_open    = 'Open the gift',
    hot_4          = 'Burning hot!',
    res_gift_text  = 'There were %d snowflakes inside',
    -- ...
}

I nomi e le descrizioni degli oggetti sono in Config.Items, i testi fissi del mercatino in html/index.html e html/script.js.

19Dati salvati

Per azzerare classifica o calendario a fine evento: ferma la risorsa, cancella il file e riavviala (oppure usa /xmreset per il calendario).

20Compatibilità e integrazioni

• Fame e sete: su ESX con esx_status; su QBCore/Qbox con i metadata del giocatore e l'evento hud:client:UpdateNeeds, compatibile con gli HUD più diffusi.
• Oggetti usabili: registrati tramite il framework, funzionano sia con ox_inventory sia con l'inventario del framework.
• Altri framework o inventari: tutta la parte che parla con framework e inventario è in bridge/server.lua.
• Insieme a Dolcetto o Scherzetto: i due eventi MintDev usano nomi, comandi e oggetti diversi e possono stare sullo stesso server.
• Prestazioni: regali, alberi e mercatino vengono creati solo vicino al giocatore; i cicli si fermano quando non c'è niente intorno.

21Risoluzione problemi

22Supporto

Hai un problema o vuoi una modifica su misura? Apri un ticket sul Discord di MintDev. Indica la versione dello script, il framework e l'inventario che usi e, se c'è, l'errore della console F8 o del server.

23Changelog

v1.0.0 · Prima versione

• Caccia ai regali condivisa con zone sulla mappa, rilevatore freddo / caldo e campanellini
• Stella d'Oro e 4 sorprese: carbone, scivolone, renna impazzita e bufera
• Mercatino di Natale con dolci, bevande calde, oggetti, scambio in soldi e classifica
• Calendario dell'Avvento con 24 porte (dicembre o una al giorno)
• Alberi di Natale con luci, regali da donare e calza della Befana
• Supporto ESX, QBCore, Qbox, ox_inventory e inventari dei framework
• 14 icone per l'inventario e 10 prop 3D originali

24Licenza

© 2026 MintDev.eu — Tutti i diritti riservati. Lo script è concesso in licenza per l'uso sul server dell'acquirente. Non è consentito rivenderlo, ridistribuirlo o ripubblicarlo, in tutto o in parte, né rimuovere le indicazioni di copyright. I termini completi sono nel file LICENZA.txt incluso nello script.