Documentazione ufficiale · MintDev

Dolcetto o Scherzetto

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

v1.0.0ESX LegacyQBCoreQboxox_inventoryqb-inventory

01Introduzione

Dolcetto o Scherzetto trasforma il tuo server in un quartiere di Halloween. I giocatori bussano alle porte, raccolgono caramelle e le scambiano alla Bottega delle Caramelle con soldi, cibo a tema, pozioni e oggetti.

Dolcetto

Un residente apre la porta e regala 2–5 caramelle. A volte esce la rarissima Caramella d'Oro.

Scherzetto

5 scherzetti: spavento, allucinazione, maledizione, inseguimento di uno zombie e furto di caramelle.

Bottega delle Caramelle

Interfaccia a tema con cibo, pozioni, oggetti, scambio caramelle → soldi e classifica dei giocatori.

Cibo con effetti

11 cibi e bevande con fame, sete ed effetti speciali, più zucche posizionabili e scatola misteriosa.

02Requisiti

03Contenuto del pacchetto

hw_dolcetto_scherzetto/
├── 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 della bottega e popup
├── stream/                 11 prop 3D (.ydr) + hw_halloween_props.ytyp
├── install/
│   ├── ox_inventory_items.lua
│   ├── qb-core_items.lua
│   ├── esx_items.sql
│   └── immagini_inventario/   16 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 hw_dolcetto_scherzetto 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 hw_dolcetto_scherzetto

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 { ... }:

   ['hw_caramella'] = {
       label = 'Caramella di Halloween',
       weight = 5,
       stack = true,
       close = true,
       description = 'La moneta di Halloween. Scambiala alla Bottega delle Caramelle!',
   },
   -- ...e gli altri 15 oggetti del file

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

   hw_caramella = { name = 'hw_caramella', label = 'Caramella di Halloween', weight = 5, type = 'item', image = 'hw_caramella.png', unique = false, useable = true, shouldClose = true, description = 'La moneta di Halloween.' },
   -- ...e gli altri 15 oggetti del file

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

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

5. Copia le immaginiLe 16 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 hw_dolcetto.admin allow

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

   [hw_dolcetto] Dolcetto o Scherzetto 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 le case e la posizione della bottega le decidi tu. In 5 minuti:

1. Posiziona la BottegaVai dove vuoi il punto di scambio, guarda nella direzione in cui deve guardare il venditore e scrivi /hwnegozio. Di base è a Legion Square.
2. Crea il quartiereMettiti davanti a una porta, a circa 1,5 metri, guardando la porta, e scrivi /hwcasa aggiungi Via delle Zucche 1. Ripeti per tutte le case dell'evento.
3. ControllaCon /hwcasa debug vedi tutte le case con il loro ID. Accanto alle porte compare una zucca illuminata.
4. Avvia l'evento/hwevento on avvisa tutti i giocatori. A fine evento usa /hwevento off.

06Configurazione · Generale

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

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

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

Config.InteractKey = 38         -- E
Config.InteractKeyLabel = '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 = { 'Dolcetto o Scherzetto', msg } })
end
Config.PreferCustomProps = true

Config.CandyItem = 'hw_caramella'
Config.GoldCandyItem = 'hw_caramella_oro'
Config.GoldScore = 10

07Configurazione · Evento

Config.Event = {
    ActiveOnStart = true,   -- l'evento parte già attivo
    OnlyAtNight = false,    -- true = si bussa solo di notte (ora di gioco)
    NightStart = 19,
    NightEnd = 6,
}

Con ActiveOnStart = false l'evento resta spento finché un admin non scrive /hwevento on. Utile per lanciarlo a un orario preciso con un annuncio.

08Configurazione · Dolcetto o scherzetto

Config.TrickOrTreat = {
    RequireBucket = false,      -- serve il Secchiello Zucca per bussare
    KnockTime = 3500,           -- durata del "toc toc" (ms)
    InteractDistance = 1.6,
    HouseCooldown = 30 * 60,    -- secondi prima di ribussare alla stessa casa
    KnockSpam = 6,              -- secondi minimi tra due bussate

    DecorateDoors = true,
    DoorMarker = true,
    ShowBlips = false,

    Chances = { treat = 62, rare = 8, trick = 30 },   -- la somma deve fare 100
    Treat = { min = 2, max = 5 },
    Rare = { gold = 1, candies = { min = 4, max = 8 } },

    Tricks = {
        { id = 'spavento',      weight = 30 },
        { id = 'allucinazione', weight = 20 },
        { id = 'maledizione',   weight = 20 },
        { id = 'inseguimento',  weight = 18 },
        { id = 'furto',         weight = 12, steal = { min = 1, max = 3 } },
    },
    -- ...
}

09Configurazione · Case

Il modo consigliato è crearle in gioco con /hwcasa aggiungi: vengono salvate in data/luoghi.json e funzionano subito, senza riavvio. Puoi anche scriverle nel config:

Config.Houses = {
    { x = -14.87, y = -1441.18, z = 31.19, label = 'Forum Drive' },          -- punto = porta
    { x = 123.45, y = -678.90, z = 30.10, h = 90.0, label = 'La mia casa' },  -- punto = chi bussa (esempio)
}

• h (heading) è la direzione in cui guarda chi bussa. Con h il punto è "dove sta il giocatore" e accanto alla porta compare la zucca decorativa.
• Senza h il punto è considerato la porta stessa e la zucca non viene messa.
• Le case del config hanno ID c1, c2...; quelle create in gioco h1, h2.... Le prime si rimuovono dal config, le seconde con /hwcasa rimuovi.

10Configurazione · Bottega delle Caramelle

Config.Shop = {
    Name = 'Bottega delle Caramelle',
    Coords = vec4(195.17, -933.77, 29.7, 144.5),   -- oppure /hwnegozio in gioco
    Ped = 'u_m_y_zombie_01',
    PedScenario = 'WORLD_HUMAN_STAND_IMPATIENT',
    Distance = 2.2,
    MaxQuantity = 50,
    MoneyAccount = 'cash',                         -- 'cash' oppure 'bank'
    Blip = { Enabled = true, Sprite = 52, Color = 17, Scale = 0.9 },
    Decorations = true,
    -- ...
}

Catalogo

Ogni voce è un oggetto acquistabile con le caramelle. category decide la scheda: 'cibo', 'bevande' o 'oggetti'.

Catalog = {
    { item = 'hw_burger_mostro',  price = 10, category = 'cibo' },
    { item = 'hw_pozione_strega', price = 12, category = 'bevande' },
    { item = 'hw_zucca_lanterna', price = 15, category = 'oggetti' },
    -- puoi vendere anche oggetti di altri script:
    { item = 'lockpick',          price = 30, category = 'oggetti' },
},

Scambi

Exchanges = {
    { id = 'caramelle_soldi', give = 'hw_caramella',     giveAmount = 1, money = 25 },
    { id = 'oro_soldi',       give = 'hw_caramella_oro', giveAmount = 1, money = 350 },
    { id = 'oro_caramelle',   give = 'hw_caramella_oro', giveAmount = 1, item = 'hw_caramella', itemAmount = 12 },
},

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

11Configurazione · Oggetti e cibo

hw_torta_zucca = {
    label = 'Torta di Zucca',
    description = 'Una fetta di torta di zucca con panna montata.',
    type = 'food',          -- 'food' | 'drink' | 'currency' | 'placeable' | 'bucket' | 'box'
    time = 5000,            -- durata dell'animazione (ms)
    hunger = 35,            -- 0-100
    -- thirst = 10, stress = -15, heal = 25, effect = 'velocita'
    prop = { custom = 'hw_prop_torta_zucca', base = 'prop_sandwich_01' },
},

Aggiungere un nuovo cibo

1. Registra l'oggetto nel tuo inventario (come in Installazione) e aggiungi la sua icona.
2. Aggiungilo in Config.Items con type = 'food' o 'drink': diventa usabile da solo.
3. Se vuoi venderlo, aggiungilo a Config.Shop.Catalog e metti l'icona anche in html/img/.

12Configurazione · Animazioni ed effetti

Config.Anims = {
    food  = { dict = 'mp_player_inteat@burger', anim = 'mp_player_int_eat_burger', flag = 49, bone = 18905,
              placement = { 0.13, 0.05, 0.02, -50.0, 16.0, 60.0 } },
    drink = { dict = 'mp_player_intdrink', anim = 'loop_bottle', flag = 49, bone = 18905,
              placement = { 0.12, 0.008, 0.03, 240.0, -60.0, 0.0 } },
}

Config.Effects = {
    SpeedMultiplier = 1.25,  -- Pozione della Strega (massimo 1.49)
    SpeedTime = 60,
    GhostAlpha = 110,        -- Cupcake Fantasma (0 invisibile, 255 normale)
    GhostTime = 45,
    HypnosisTime = 8,        -- Lecca-Lecca Ipnotico
}

13Zucche, secchiello e scatola misteriosa

Config.Pumpkins = {
    Item = 'hw_zucca_lanterna',
    MaxPerPlayer = 3,
    Persist = true,          -- restano dopo un riavvio (data/zucche.json)
    Light = { color = { 255, 110, 20 }, range = 3.5, intensity = 5.0, height = 0.35, flicker = true },
}

Config.MysteryBox = {
    Item = 'hw_scatola_misteriosa',
    OpenTime = 3000,
    Rewards = {
        { type = 'candies', weight = 35, min = 4, max = 12 },
        { type = 'gold',    weight = 10, amount = 1 },
        { type = 'food',    weight = 30 },                 -- un cibo a caso del catalogo
        { type = 'money',   weight = 15, min = 200, max = 800 },
        { type = 'trick',   weight = 10 },
    },
}

Il secchiello (Config.Bucket) si prende in mano usandolo dall'inventario. Con Bone e BasePlacement / CustomPlacement puoi spostarlo nell'altra mano o correggerne la posizione.

14Come si gioca

Bussare alle porte

Vicino a una casa dell'evento compare una freccia arancione sopra la porta. A meno di 1,6 metri appare il suggerimento [E] Bussa: parte l'animazione e dopo il "toc toc" qualcuno apre. Con X si annulla.

Scherzetti

Bottega, cibo e oggetti

• Alla bottega premi E: scegli la quantità e compra, oppure scambia le caramelle nella scheda Scambio. ESC per chiudere.
• Cibo e bevande si usano dall'inventario: animazione con il prop in mano, poi fame/sete ed eventuali effetti.
• Zucca Intagliata: usala per posizionarla davanti a te. Per raccoglierla avvicinati e premi E (solo il proprietario o un admin).
• Secchiello Zucca: usalo per prenderlo o metterlo via.
• Scatola Misteriosa: usala per aprirla e scoprire il premio... o lo scherzetto.

15Comandi admin

/hwevento, /hwdai e /hwreset 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 hw_dolcetto.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 hw_dolcetto.admin allow
# oppure per un singolo giocatore:
add_principal identifier.license:xxxxxxxx group.admin

17Prop 3D

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

Il file hw_halloween_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. `hw_prop_zucca_lanterna`), finché hw_dolcetto_scherzetto è avviato.

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

18Testi e traduzioni

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

Lang = {
    prompt_knock    = 'Knock: trick or treat?',
    res_treat_title = 'TREAT!',
    res_treat_text  = 'You got %d candies',
    -- ...
}

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

19Dati salvati

Per azzerare la classifica a fine evento: ferma la risorsa, cancella classifica.json e riavviala. I cooldown delle case sono in memoria e si azzerano al riavvio (o con /hwreset).

20Compatibilità e integrazioni

• Fame e sete: su ESX vengono aggiornate 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: vengono registrati tramite il framework, quindi 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. Adattando quelle funzioni puoi usare lo script anche con sistemi personalizzati.
• Prestazioni: i cicli si "addormentano" quando non ci sono case o zucche vicine; personaggi e decorazioni vengono creati solo vicino al giocatore.

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

• Dolcetto o scherzetto con NPC alla porta, dolcetto d'oro e 5 scherzetti
• Bottega delle Caramelle con cibo, pozioni, oggetti, scambio in soldi e classifica
• 11 cibi e bevande a tema con effetti, zucche posizionabili, secchiello e scatola misteriosa
• Supporto ESX, QBCore, Qbox, ox_inventory e inventari dei framework
• 16 icone per l'inventario e 11 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.