RKL Suite — Developer Docs

Overview

Each resource is independent but they share data. The forge reads and writes the equipment metadata, so equipment is the core the others build on.

Install & server.cfg

Required on every framework

ox_lib, ox_inventory, and oxmysql. No es_extended is required for QBCore/Qbox — the bridge detects the framework automatically (qbx_core → Qbox, qb-core → QBCore, es_extended → ESX Legacy).

Ensure order

server.cfgCopy
ensure oxmysql
ensure ox_lib
ensure ox_inventory

# your framework (one of)
ensure es_extended      # or qb-core / qbx_core

ensure rklequipment     # core — start first
ensure rklforge         # AFTER equipment
ensure rklcrafting
ensure rklskilltree     # class XP / skill nodes
ensure rklbinder        # card binder (uses forge_card)
ensure rklrepair        # durability repair NPC

# effects (needed for combat visuals & damage numbers)
ensure rklparticleseffect
ensure rklstatuseffect

# spell system
ensure rklgrimoire
ensure rklskillsystem
ensure rklspellmanage
ensure rklspellbook
ensure rklskillcheck

# HUD (reads skilltree + forge)
ensure rklinterface

Currency — pick what players pay with

Costs that the scripts call "awaken coin" are not hard-wired to an item. Set Config.RKLCurrency in the resource's config.lua (an open file, editable under escrow) and the bridge routes every charge and balance check for you — same behaviour on ESX Legacy, QBCore and Qbox.

config.luaCopy
Config.RKLCurrency = { type = 'item', item = 'awaken_coin' }  -- ox_inventory item
-- Config.RKLCurrency = { type = 'money' }                     -- cash
-- Config.RKLCurrency = { type = 'bank'  }                     -- bank balance
-- Config.RKLCurrency = { type = 'account', account = 'black_money' }

Resource names

Exports and cross-resource events use fixed names, and a FiveM export only resolves if the folder name matches the caller. The whole suite is branded rkl* — keep these folder names exactly:

How they connect

The resources are independent but share three things: exports (direct calls), events (one-way messages), and database tables. This is the full dependency picture.

Direct export calls

Event flow

Shared database tables

Optional integrations

Three resources outside this suite are used when present: rklzones (safe zones), rklcompanion (pet detection) and rklspawnmonster (monster lookup). rklskilltree and rklforge are optional to each other in the same way.

Every one of these calls is wrapped, so a missing resource can never throw. You can also switch them off explicitly:

config.luaCopy
Config.Integrations = {
    ['rklzones']        = true,  -- fallback: never in a safe zone
    ['rklcompanion']    = true,  -- fallback: not a companion
    ['rklspawnmonster'] = true,  -- fallback: no monster
    ['rklskilltree']    = true,  -- fallback: level 0
}

Shared state bag

LocalPlayer.state.playerClass (and playerSubclass) is how the player's class travels between resources. rklskilltree sets it; rklinterface and rklequipment read it. It is framework-independent, so it behaves the same on ESX, QBCore and Qbox.

Database & SQL

Import rkl_suite.sql once on your server database. Every statement is IF NOT EXISTS, so re-running it is safe and never deletes data.

Character class columns

The skill tree stores the class, sub-classes and rank on the character row. Run the block that matches your framework — the SQL file has both, with the QBCore/Qbox one commented out.

ESX LegacyCopy
ALTER TABLE `users`
    ADD COLUMN IF NOT EXISTS `class`       VARCHAR(64) DEFAULT NULL,
    ADD COLUMN IF NOT EXISTS `sub_classes` TEXT        DEFAULT NULL,
    ADD COLUMN IF NOT EXISTS `rank`        VARCHAR(8)  DEFAULT 'E';

QBCore / QboxCopy
ALTER TABLE `players`
    ADD COLUMN IF NOT EXISTS `class`       VARCHAR(64) DEFAULT NULL,
    ADD COLUMN IF NOT EXISTS `sub_classes` TEXT        DEFAULT NULL,
    ADD COLUMN IF NOT EXISTS `rank`        VARCHAR(8)  DEFAULT 'E';

rklequipment client exports

The core. Manages equipped gear, the stats they grant (defense, magic defense, set bonuses), durability, and the melee combo system. All of its exports run on the client.

Exports

clientCopy
if exports['rklequipment']:IsCombatMode() then
    return -- player is swinging, skip
end

clientCopy
local def   = exports['rklequipment']:GetDefense()
local final = math.max(1, incomingDamage - def)

clientCopy
local mdef  = exports['rklequipment']:ApplyMagicDefense()
local final = math.max(1, spellDamage - mdef)

clientCopy
local sets = exports['rklequipment']:GetSetBonuses()
for setId, set in pairs(sets) do
    print(setId, set.label)
end

clientCopy
local setId, set = exports['rklequipment']:GetItemSet('dragon_helm')
if setId then
    print('Part of set:', set.label)
end

Open files — combos & language

Two files ship outside the escrow so server owners can edit them with the resource still encrypted. Both are listed in escrow_ignore.

language.lua

Every player-facing string lives in a Lang table. Translate values freely; keep any %s placeholder — it's filled at runtime (for example the item name in a "broke" message).

language.luaCopy
['armor_broken_desc'] = 'Your %s broke! Its bonus stats are gone.',

The helper is called _L('key') (not _U) so it never clashes with ESX's built-in translator.

combos.lua

Each weapon type's attack animation sequence is data only — change the dictionary, clip, timing or number of stages without touching logic.

combos.luaCopy
Config.Combos.Katana = {
    [0] = {dict = 'kp_wm_gs_slash_01', anim = 'kp_wm_gs_slash_01_clip', wait = 700, next = 1},
    [1] = {dict = 'kp_wm_gs_slash_02', anim = 'kp_wm_gs_slash_02_clip', wait = 700, next = 2},
    -- last stage loops back with next = 0
}

Built-in types: BigSword, Staff, Unarmed, DualDagger, Katana, DualKatana.

Add a brand-new weapon type

The combo dispatch is data-driven: any weapon type that isn't built in is played by the generic runner — no escrowed edits needed.

1. Give the weapon item w_type = "yourtype" in config.lua.
2. Define Config.Combos.yourtype in combos.lua.

combos.lua — custom typeCopy
Config.Combos.spear = {
    [0] = {dict = 'melee@large_wpn@streamed_core', anim = 'plyr_takedown_front_attacker',
           wait = 900, flag = 1, next = 1, sound = 'hitflesh', damageRange = 2.5},
    [1] = {dict = 'melee@large_wpn@streamed_core', anim = 'plyr_takedown_rear_attacker',
           wait = 1100, flag = 1, next = 0, freeze = true,
           vfx = {dict = 'scr_sum2_hal', part = 'scr_sum2_hal_rider_weak_green',
                  attachType = 'weapon_tip', loop = true,
                  color = {r = 0.2, g = 0.6, b = 1.0}, scale = 0.5, duration = 700,
                  off = {x = 0.0, y = 1.0, z = 0.0}}},
}

Optional per-stage fields

flag, freeze, blendIn, blendOut, wait, next, sound, damageRange, and vfx (a particle table — add weapon-tip effects straight from the open file).

Optional per-type tuning

combos.luaCopy
Config.ComboSettings = {
    spear = { speedFactor = 0.03, speedCap = 0.30, minWait = 300, comboTimer = 5, slot = 'right_hand' },
}

Commands & notable events

Useful events

Most other events are internal (durability, damage sync, UI refresh) and aren't meant to be called from outside.

rklforge server exports

Upgrade, enchant and socket equipped gear. It reads and writes equipment metadata, then tells equipment to refresh. All of its exports run on the server.

Exports

serverCopy
exports['rklforge']:GiveForgeReq(src, 'protect_scroll', 1, 'Protection Scroll')

serverCopy
exports['rklforge']:GiveForgeCard(src, 'attack_card', 3)

serverCopy
local atk = exports['rklforge']:GetPlayerStatTotal(src, 'attack')

serverCopy
local luck   = exports['rklforge']:GetPlayerLuck(src)
local chance = baseChance + (luck * 0.5)

Currency & items

Ready-made export examples also live, commented, inside rklforge/ox_inventory_items.lua.

Commands & notable events

Useful events

rklcrafting events: rklcrafting:*

An XP-based crafting station. Players craft items from recipes, gaining levels and XP stored in slv_crafting_data. Internal events use the rklcrafting: prefix.

Export & callback

ox_inventory/data/items — client.exportCopy
['craft_boost'] = {
    label = 'Crafting Boost Potion',
    client = { export = 'rklcrafting.craft_boost_potion' },
}

clientCopy
local data = lib.callback.await('rklcrafting:server:getHunterData', false)
print(data.level, data.xp)

Commands & data

Config & database

Spell System

Five connected resources that add a magic / skill layer: a grimoire with spell XP and a hotbar, the skill engine that casts spells and tracks mana, spellbook items with unlocked-skill storage, a spell menu, and a cast-time skillcheck minigame. Each ships with its own framework bridge (ESX Legacy / QBCore / Qbox auto-detected) and most cast text lives in an open language.lua.

rklgrimoire XP · hotbar · upgrades

Tracks each player's spell XP and the spell hotbar, and processes spell upgrades.

Exports

serverCopy
exports['rklgrimoire']:AddGrimoireXP(src, 50)

clientCopy
local hotbar = exports['rklgrimoire']:GetHotbarData()

Callbacks & events

Command

rklskillsystem cast · mana · UI

The skill engine — casting, mana, damage indicators and the spell hotbar UI. Its exports run on the client and let other scripts disable casting or hide the UI (cutscenes, downed states, safe zones).

Exports

clientCopy
exports['rklskillsystem']:SetDisableSkills(true)   -- during a cutscene
exports['rklskillsystem']:SetDisableSkills(false)  -- restore

clientCopy
if exports['rklskillsystem']:IsSkillsDisabled() then return end

clientCopy
exports['rklskillsystem']:SetUIHidden(true)

clientCopy
local hidden = exports['rklskillsystem']:IsUIHidden()

Callback, command & events

Config highlights

Config.Mana, Config.Skills, Config.Hotbar, Config.RequireWeapon, Config.DamageIndicator, plus access gates Config.AllowedJob / Config.AllowedOrgs / Config.EnableJobLock / Config.EnableOPCrime.

rklspellmanage books · unlocks · shop

Handles spellbook items and stores which skills a player has unlocked. Includes an optional ox_inventory shop for skillbooks.

Exports

serverCopy
local skills = exports['rklspellmanage']:getUnlockedSkills(src)
for _, s in ipairs(skills) do print(s.categoryName, s.uid) end

ox_inventory/data/items — client.exportCopy
['spellbook_fire'] = {
    label = 'Fire Spellbook',
    client = { export = 'rklspellmanage.usebook' },
}

Config highlights

Config.Abilities, Config.Command, Config.DevhubSkillTree, Config.EnableOxShopforSkillbook, Config.usingSkillbook.

rklspellbook spell menu

The spell menu — shows the spells a player is permitted to use and supports targeting other players. Driven by callbacks and an open event; it has no exports.

client — open the menuCopy
TriggerEvent('rkl_spellbook:client:openSpellbook')

Open command is configurable via Config.SpellMenuCommand.

rklskillcheck cast minigame

A cast-time skillcheck minigame. Other spell resources start it during a cast; the result decides whether the spell succeeds. No exports — it's event-driven.

Effects & FX

Two shared layers used across combat and magic: a status-effect system (poison, burn, slow, blind, stun, freeze) with screen and world VFX, and a particle / damage-number layer that other resources fire to show hits and effects.

rklstatuseffect poison · burn · stun…

Applies timed status effects with optional damage-over-time plus screen and world particles. Built-in statuses: burn, poison, slow, blind, stun, freeze — add your own in Config.Statuses.

Server exports

serverCopy
-- burn for 8 seconds, 5 damage per tick
exports['rklstatuseffect']:GiveStatus(src, 'burn', 8, 5)

serverCopy
exports['rklstatuseffect']:TakeStatus(src, 'burn')

Client exports

clientCopy
exports['rklstatuseffect']:ApplyStatus('poison', 10, 3)

clientCopy
if exports['rklstatuseffect']:HasStatus('freeze') then return end

clientCopy
exports['rklstatuseffect']:RemoveStatus('poison')

Event & config

You can also apply a status client-side via event — handy from another client script:

clientCopy
TriggerEvent('rklstatuseffect:status', 'slow', 6)   -- name + duration, config damage
TriggerEvent('rklstatuseffect:status', 'blind')     -- name only, all config defaults

Add or tune statuses in Config.Statuses (each entry has duration, damage, screen FX and optional worldPtfx). Other config: Config.RenderDistance, Config.WaitStatus, Config.IdleWait, and a built-in test command via Config.CommandTest.

rklparticleseffect particles · damage numbers

The shared visual layer: plays attached particle effects on peds and shows floating damage numbers. It's event-driven (no exports) — other resources fire its events. Events use the rklcharfx: and rkldamgeshow: prefixes, plus the ped-damage handler.

Dealing ped damage (same call the combos use)

client → server eventCopy
TriggerServerEvent('rkldamageped:victim', 'rklequipment:victim',
    hitCoords, range, enemyNetId, damage)

rklinterface HUD · class build · skill bar

The player HUD: health, mana and stamina bars, the class/subclass build (max HP, MP, sprint speed), the equipped-skill bar, and a drag-to-move edit mode. Class comes from the playerClass state bag, and skills are read from the skill-tree tables.

Export

clientCopy
if exports['rklinterface']:isSpellActive() then return end

Callbacks

clientCopy
local jobData = lib.callback.await('rklinterface:getJobData', false)
print(jobData.level, jobData.currentClass)

Events

server → clientCopy
TriggerClientEvent('rklinterface:updatelvlxp', src, 12, 340, 500)

Commands & config

Class stats live in Config.BaseStatus (base health, HP per level, and per-class modifiers for mage, priest, ranger, and more) and Config.Abilities. Database tables: slv_player_job_points, slv_player_skills, slv_skills, slv_skill_trees.

rklskilltree class XP · skill nodes

Class progression and the skill tree itself: XP and levels per class, skill points, node unlocking with rank-ups, sub-classes, and an in-game tree editor for admins. It feeds the HUD (rklinterface) and gates gear in rklequipment.

Server exports

serverCopy
exports['rklskilltree']:AddJobXP(src, 250)

serverCopy
local lvl = exports['rklskilltree']:GetJobLevel(src) or 0
if lvl < item.required_lvl then return end

serverCopy
local s = exports['rklskilltree']:GetJobStats(src)
print(s.level, s.xp .. '/' .. s.nextXp, s.points)

serverCopy
exports['rklskilltree']:AddJobPoints(src, 3)

Callbacks & events

Commands

Config & data

Config.XPTable sets the XP curve per level; Config.RankLimits caps level by character rank (E, D, C…). Tables: slv_player_job_points, slv_skill_trees, slv_skills, slv_player_skills, plus the class columns on users / players.

rklbinder card album

A full-screen card binder. Players drag forge_card items out of their inventory into album pages, and drag them back out again. It reuses the forge's card item, so there's no extra item to register. Custom NUI, no ox_lib.

Exports

serverCopy
local n = exports['rklbinder']:GetBinderCount(src)

serverCopy
local binder = exports['rklbinder']:GetBinder(src)
for slot, card in pairs(binder) do
    print(slot, card.cardType, card.level)
end

Events

All of them are server-validated — slot range, card presence and free bag space are checked before anything is written.

Config

rklrepair durability NPC

Repair NPCs that restore durability on equipment items. Each NPC accepts certain categories and only lists gear below its damage threshold. No database, no exports — it works directly on ox_inventory metadata.

How it meets rklequipment

Both resources use the same ox_inventory item, equipment, and the same durability fields. Repairing writes metadata.stats.durability (the equipment system's source of truth) and mirrors it to metadata.durability so the ox_inventory bar agrees.

Callbacks

Both are server-validated — the item is re-read server-side and the cost recomputed from config, so a tampered UI can't repair for free.

Config

rklhalloween seasonal event

Hallowed Night is a free fantasy Halloween event pack in one resource: a soul-lantern hunt, trick-or-treat doors with curses, a witch's cauldron with ingredient gathering, and a scheduled Haunted Night boss event. Everything uses a custom Halloween UI (prompt, progress ring, toasts, Grimoire menu, cauldron, boss bar). It's standalone: no other RKL resource is needed.

Hallowed Night — Quick start

From download to your first in-game test in about five minutes. This is the short path: Install has the full steps for every framework and inventory, and Troubleshooting covers anything that doesn't show up.

Before you start

• OneSync must be enabled. It is the only hard requirement (dependencies { '/onesync' } in fxmanifest.lua).
• No database, no ox_lib and no oxmysql. Souls, stats, milestones and the built-in satchel are saved in server KVP.
• A framework, an inventory and a target script are all optional. The pack detects your framework and inventory when it starts. Target scripts are only used if you change Config.Interaction (the default is the pack's own 'prompt').

1. Drop the folder in

Unzip the download (from your keymaster Granted Assets if you claimed it on Tebex) and put the folder in your server's resources directory. The folder must be named exactly rklhalloween. If it extracted as something like rklhalloween-1.0.0, rename it.

2. Add it to server.cfg

Start it after your framework, inventory and target script, then give your admins the hallowed.admin ace:

server.cfgCopy
# framework (pick yours, or nothing for standalone)
ensure qbx_core            # or qb-core / es_extended
# inventory (or nothing: the built-in Halloween Satchel is used)
ensure ox_inventory        # or qb-inventory / ps-inventory / lj-inventory
# target (optional, only used if you change Config.Interaction)
ensure ox_target           # or qb-target

# Hallowed Night: always after the lines above
ensure rklhalloween

# admin commands: /hnhaunt, /hnsouls, /hnlanterns
add_ace group.admin hallowed.admin allow

3. Register the items and copy the images

4. Turn the season on (only if you test outside the dates)

By default the event runs from 15 October to 3 November on the server's local date. Inside those dates you can skip this step. Outside them, lanterns, trick-or-treat doors, cauldrons and gathering nodes don't appear, and the season chip in the Grimoire reads "The veil is closed". For testing, set Config.Season.AlwaysOn = true in config/config.lua:

config/config.luaCopy
Config.Season = {
    AlwaysOn = true,                            -- TESTING: ignore the dates below
    Start  = { month = 10, day = 15 },          -- server local date
    Finish = { month = 11, day = 3 },
    Id = '2026',                                -- change every year to start a fresh leaderboard/progress
}

Two optional testing helpers:

• Config.Lanterns.Blips.Enabled = true (config/lanterns.lua) puts a small blip on every active lantern so you can find one quickly.
• Config.Debug = true (config/config.lua) prints every rewarded action in the server console (through Hooks.Log) and draws the trick-or-treat door zones when you use ox_target or qb-target.

5. Restart the server

Do a full server restart the first time, so your inventory picks up the new items and the custom props in stream/ (with hn_props.ytyp) load. When the resource starts, the console prints the setup it detected:

server consoleCopy
[rklhalloween] framework: qbx | inventory: ox_inventory

Your values will match your server (qbx, qb, esx or standalone, and ox_inventory, qb-inventory, esx or internal). If it says standalone or internal while you run a framework or inventory, rklhalloween started too early: move its ensure line further down. After later config edits, restart rklhalloween is enough, because the config files load when the resource starts.

6. Test in game

7. Before you go live

• Set Config.Season.AlwaysOn back to false (unless you want the event all year), and turn Config.Lanterns.Blips.Enabled and Config.Debug off again.
• Take back test Souls with a negative amount: /hnsouls [id] -25. Souls never go below 0. Milestones you already claimed stay claimed for that character (that license on standalone) until Config.Season.Id changes.
• The included trick-or-treat doors are samples. Walk to the doors you want and add them with /hncoords to Config.TrickOrTreat.Doors.
• For a completely fresh start (everyone's Souls, stats, milestones and satchels), change Config.Season.Id.

What you should see

• The [rklhalloween] framework: … | inventory: … line in the server console, and no red [rklhalloween] errors.
• Three Witch's Cauldron blips on the map: Pacific Bluffs cemetery, Grapeseed and Paleto Bay.
• At a cauldron: the custom cauldron with a green glow, a witch NPC next to it, and the prompt "Use Witch's Cauldron" (or a target option with a flask icon).
• Soul lanterns that spawn once you are within 80 m (Config.Lanterns.RenderDistance) and glow orange (cursed ones purple, with an aura). "Collect Soul Lantern" → hold for 2.5 seconds (CollectTime = 2500) → a reward popup with +1 Soul (+3 for a cursed lantern, followed by a curse).
• Gathering nodes with "Gather Mandrake" / "Gather Bone Pile". Moonpetal only shows between 20:00 and 06:00 in-game time.
• Trick-or-treat doors (for example on Grove Street or Forum Drive) with a "Trick or Treat" prompt, and a costumed NPC answering after the knock.
• Custom models, not plain pumpkins, barrels or bin bags. If you see those, the stream didn't load and the vanilla fallbacks are showing (see Custom props).
• Rewards landing in your inventory with their images, or in the Grimoire's Satchel tab on standalone.
• During Haunted Night: the announce banner for every player, then inside the zone fog, the HALLOWEEN weather, decorative tombstones and the wave counter.

Hallowed Night — Install

The full setup for every supported framework and inventory. Pick your setup below and follow its steps, then choose how players interact (prompt or target). The pack detects your framework and inventory by itself, so in most setups you only paste the items and copy the images. A target script is only used if you set Config.Interaction.

Requirements

What's in the folder

How the pack detects your setup

Config.Framework and Config.Inventory both default to 'auto' in config/config.lua. Config.Interaction is not auto-detected unless you set it to 'auto': by default it is 'prompt' (see Interaction below).

config/config.luaCopy
-- 'auto' detects the running resource. Force one if you run more than one by accident.
Config.Framework = 'auto'           -- 'auto' | 'qbx' | 'qb' | 'esx' | 'standalone'
Config.Inventory = 'auto'           -- 'auto' | 'ox_inventory' | 'qb-inventory' | 'esx' | 'internal'
                                    -- 'internal' = built-in Halloween Satchel (no inventory needed, shown in the Grimoire)
Config.Interaction = 'prompt'       -- 'prompt' (custom Halloween prompt + key) | 'ox_target' | 'qb-target' | 'auto'

A resource counts as running when its state is started or starting. The check happens once, when rklhalloween starts, and the result is printed in the server console:

server consoleCopy
[rklhalloween] framework: esx | inventory: ox_inventory

server.cfg

server.cfgCopy
# OneSync is required (skip this line if your host or txAdmin already turns it on)
set onesync on

# 1. framework (one of these, or none for standalone)
ensure qbx_core            # Qbox
# ensure qb-core           # QBCore
# ensure es_extended       # ESX Legacy

# 2. inventory (one of these, or none: the built-in satchel is used)
ensure ox_inventory
# ensure qb-inventory      # or ps-inventory / lj-inventory

# 3. target (optional, only if Config.Interaction uses it)
ensure ox_target
# ensure qb-target

# 4. Hallowed Night, after everything above
ensure rklhalloween

# 5. admin permission for /hnhaunt, /hnsouls and /hnlanterns
add_ace group.admin hallowed.admin allow
# if your account isn't in group.admin yet:
# add_principal identifier.license:YOUR_LICENSE group.admin

The ace name comes from Config.Admin.Ace (default 'hallowed.admin'). If you change it, change the add_ace line too. Admin commands also work from the server console. /halloween and /hncoords are open to everyone.

Choose your setup

Qbox (ox_inventory)

1. Open install/items/ox_inventory.lua and copy the 16 item lines (everything below the two comment lines).
2. Paste them inside the return { ... } table in ox_inventory/data/items.lua, before its closing brace.
3. Copy every PNG from install/images/ into ox_inventory/web/images/.
4. In server.cfg: ensure qbx_core, ensure ox_inventory, optionally ensure ox_target, then ensure rklhalloween.
5. Restart the server and check for framework: qbx | inventory: ox_inventory in the console.

ox_inventory/data/items.luaCopy
return {
    -- ... your existing items ...

    ["hn_mandrake_root"] = { label = "Mandrake Root", weight = 50, stack = true, close = false, description = "A gnarled root that screams when pulled. Hums with earthy magic." },
    ["hn_potion_seer"] = { label = "Seer's Draught", weight = 150, stack = true, close = true, server = { export = 'rklhalloween.useItem' }, description = "Reveals nearby soul lanterns on your map." },
    -- ... plus the other 14 lines from install/items/ox_inventory.lua
}

Usable items: the 9 usable items (Hallowed Candy, the 7 potions and Cauldron Sludge) carry server = { export = 'rklhalloween.useItem' }. When a player uses one, ox_inventory asks the pack first (it only accepts items listed in Config.Potions), removes one item itself, and the pack then plays the animation and runs the effect without removing a second one. Nothing is registered through qbx_core. Progress is saved per character (citizenid), and money rewards go to the player's cash or bank.

QBCore + qb-inventory (ps-inventory, lj-inventory)

1. Open install/items/qb-core.lua and copy the 16 item lines.
2. Paste them inside the QBShared.Items = { ... } table in qb-core/shared/items.lua, before its closing brace.
3. Copy every PNG from install/images/ into qb-inventory/html/images/. On a fork, use that inventory's html/images/ folder (ps-inventory/html/images/, lj-inventory/html/images/).
4. In server.cfg: ensure qb-core, your inventory, optionally ensure qb-target, then ensure rklhalloween.
5. Restart the server and check for framework: qb | inventory: qb-inventory.

qb-core/shared/items.luaCopy
QBShared.Items = {
    -- ... your existing items ...

    hn_mandrake_root = { name = 'hn_mandrake_root', label = "Mandrake Root", weight = 50, type = 'item', image = 'hn_mandrake_root.png', unique = false, useable = false, shouldClose = true, description = "A gnarled root that screams when pulled. Hums with earthy magic." },
    hn_potion_seer = { name = 'hn_potion_seer', label = "Seer's Draught", weight = 150, type = 'item', image = 'hn_potion_seer.png', unique = false, useable = true, shouldClose = true, description = "Reveals nearby soul lanterns on your map." },
    -- ... plus the other 14 lines from install/items/qb-core.lua
}

Usable items: the pack registers every item in Config.Potions with QBCore.Functions.CreateUseableItem (those items have useable = true in the install file). On use, the pack removes one item itself, then runs the effect.

Forks: ps-inventory and lj-inventory are handled as qb-inventory, because the pack works through the QBCore player functions (AddItem, RemoveItem, GetItemsByName) rather than the inventory resource. The carry check uses exports['qb-inventory']:CanAddItem on qb-inventory 2.x and falls back to a weight check against QBCore.Config.Player.MaxWeight on older versions and forks. The item box popup is sent with both qb-inventory:client:ItemBox and inventory:client:ItemBox, so forks show it too. Removing items walks split stacks and is all-or-nothing.

QBCore + ox_inventory

1. Paste the 16 lines of install/items/ox_inventory.lua into ox_inventory/data/items.lua (same as Qbox above).
2. Copy install/images/*.png into ox_inventory/web/images/.
3. In server.cfg: ensure qb-core, ensure ox_inventory, optionally a target script, then ensure rklhalloween.
4. Restart and check for framework: qb | inventory: ox_inventory.

ox_inventory wins the detection whenever it is running, so the pack adds, removes and counts items only through ox_inventory here. install/items/qb-core.lua isn't needed. Usable items work through the ox export exactly like on Qbox, and the pack skips CreateUseableItem. Progress is saved per character (citizenid).

ESX Legacy (default inventory)

1. Run install/items/esx.sql on your ESX database (HeidiSQL, phpMyAdmin or similar). It uses INSERT IGNORE, so running it twice is safe.
2. Images: if your inventory UI shows item images, copy install/images/*.png into its image folder. The pack's own UI already has its icons.
3. In server.cfg: ensure es_extended, then ensure rklhalloween.
4. Restart the server, so ESX loads the new items, and check for framework: esx | inventory: esx.

install/items/esx.sqlCopy
-- ESX Legacy (default inventory). Skip this if you use ox_inventory.
INSERT IGNORE INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
    ('hn_mandrake_root', 'Mandrake Root', 1, 0, 1),
    ('hn_moonpetal', 'Moonpetal', 1, 0, 1),
    ('hn_bone_dust', 'Bone Dust', 1, 0, 1),
    ('hn_ghost_essence', 'Ghost Essence', 1, 0, 1),
    ('hn_pumpkin_seeds', 'Pumpkin Seeds', 1, 0, 1),
    ('hn_raven_feather', 'Raven Feather', 1, 0, 1),
    ('hn_candy', 'Hallowed Candy', 1, 0, 1),
    ('hn_candy_bucket', 'Candy Bucket', 6, 0, 1),
    ('hn_potion_owl', 'Owl''s Eye Elixir', 3, 0, 1),
    ('hn_potion_swift', 'Swiftfoot Draught', 3, 0, 1),
    ('hn_potion_feather', 'Featherfall Tonic', 3, 0, 1),
    ('hn_potion_phantom', 'Phantom Veil', 3, 0, 1),
    ('hn_potion_vigor', 'Elixir of Vigor', 3, 0, 1),
    ('hn_potion_purify', 'Purifying Elixir', 3, 0, 1),
    ('hn_potion_seer', 'Seer''s Draught', 3, 0, 1),
    ('hn_sludge', 'Cauldron Sludge', 3, 0, 1);

Usable items: registered with ESX.RegisterUsableItem for every item in Config.Potions. On use, the pack removes one item with removeInventoryItem and runs the effect. Rewards respect xPlayer.canCarryItem. Cash rewards go to the ESX money account and bank rewards to bank. Progress is saved per character (xPlayer.identifier) and written when a character logs out (esx:playerLogout), so multicharacter works. The client reads death from esx:onPlayerDeath / esx:onPlayerSpawn.

ESX Legacy + ox_inventory

1. Paste the 16 lines of install/items/ox_inventory.lua into ox_inventory/data/items.lua.
2. Copy install/images/*.png into ox_inventory/web/images/.
3. Skip install/items/esx.sql (its own header says so).
4. In server.cfg: ensure es_extended, ensure ox_inventory, optionally ensure ox_target, then ensure rklhalloween.
5. Restart and check for framework: esx | inventory: ox_inventory.

Items go through ox_inventory and usable items through the rklhalloween.useItem export, so ESX.RegisterUsableItem isn't used. Identifier, money and death detection still come from ESX, as in the section above.

Standalone (built-in satchel)

1. Nothing to paste and no images to copy. The pack's UI already ships its item icons in html/assets/items/.
2. Add ensure rklhalloween to server.cfg (plus a target script if you want one).
3. Restart and check for framework: standalone | inventory: internal.

The satchel: every item reward goes into a built-in Halloween Satchel saved with the player's progress in KVP. Players open it from the Grimoire (/halloween or F7) → Satchel. The tab only appears when the inventory resolves to internal. Usable items (everything in Config.Potions) get a Use button that removes one and runs the effect. The satchel has no weight limit.

Identifier: progress is saved per Rockstar license (license: identifier), so it's per account, not per character. The client detects death with the native dead / fatally-injured checks only, and the "player loaded" moment is the playerSpawned event.

Money: standalone has no money system, so cash and bank rewards (lantern loot, treats, milestones, the boss) go through Hooks.StandaloneAddMoney in editable/server/hooks.lua. By default it returns false and the money is simply not given. Connect your own economy there and return true only when you actually paid:

editable/server/hooks.lua (example comments added)Copy
---Standalone servers have no money system. Return true if you gave the money yourself.
function Hooks.StandaloneAddMoney(src, account, amount)
    -- account is 'cash' or 'bank'
    -- example: call your own economy script here, then
    -- return true
    return false
end

How usable items work

The 9 usable items are the keys of Config.Potions in config/potions.lua. Here is how each setup connects them:

bridge/server.luaCopy
---Register an item as usable. `cb(src)` runs when the player uses it.
---ox_inventory calls exports.rklhalloween:useItem instead (see install/items/ox_inventory.lua).
function Bridge.RegisterUsable(item, cb)
    local inv = Bridge.Inventory
    if inv == 'ox_inventory' or inv == 'internal' then
        return
    end
    if Bridge.Framework == 'qb' then
        QBCore.Functions.CreateUseableItem(item, function(source) cb(source) end)
    elseif Bridge.Framework == 'qbx' then
        exports.qbx_core:CreateUseableItem(item, function(source) cb(source) end)
    elseif Bridge.Framework == 'esx' then
        ESX.RegisterUsableItem(item, function(source) cb(source) end)
    end
end

Interaction: prompt or target

config/config.luaCopy
Config.Interaction = 'prompt'       -- 'prompt' (custom Halloween prompt + key) | 'ox_target' | 'qb-target' | 'auto'
Config.InteractKey = { control = 38, label = 'E' } -- used by the prompt mode
Config.CancelKey = { control = 73, label = 'X' }   -- cancels hold actions

In every mode, ClientHooks.CanInteract() in editable/client/hooks.lua decides whether an option is shown. By default it blocks players who are dead or downed (when Config.DisableWhileDead is on) and players in a vehicle. Add your own checks there (cuffed, in jail, on a call). Hold actions such as collecting or gathering show the progress ring and can be cancelled with Config.CancelKey (X) in every mode. Target option names start with rklhalloween:.

Item list

All 16 items, with the weights from the install files. ox_inventory and qb-core use the same numbers. Every item is stackable (stack = true on ox, unique = false on qb).

On ox_inventory the usable items have close = true (the inventory closes on use) and the rest close = false. On qb-core every item has shouldClose = true and image = '<item>.png'. On ESX every row has rare = 0 and can_remove = 1. Effects and durations are set in config/potions.lua.

Hallowed Night — Config reference

Every setting lives in config/. The files load as shared scripts (server and client) in the order below, and they stay readable and editable after escrow (escrow_ignore 'config/*.lua'). Restart the resource after you change a value.

This page goes key by key through config.lua, items.lua, curses.lua and potions.lua. Lantern, trick-or-treat, gathering, cauldron and Haunted Night settings are explained in Features & balancing, and the full item and recipe lists are in Items, potions & recipes. Text that isn't in a config (prompts, toasts, Grimoire labels) lives in locales/en.lua and locales/tl.lua.

config/config.lua

General

Season

Grimoire, Souls & leaderboard

Where Souls come from

Admins can add or remove Souls with /hnsouls, and other scripts with the AddSouls export. A total never goes below 0.

Milestones

Rewards unlocked by a player's total Souls and claimed from the Grimoire. Each entry has a Souls threshold, a label, and a list of rewards. A reward is either an item or money ('cash' or 'bank').

config/config.luaCopy
Config.Milestones = {
    { souls = 25, label = 'Wandering Spirit', rewards = {
        { type = 'item', name = 'hn_candy', amount = 5 },
        { type = 'money', account = 'cash', amount = 500 },
    } },
    -- { souls = ..., label = '...', rewards = { ... } },
}

• A milestone can be claimed once per season (Config.Season.Id), as soon as the player's total reaches souls.
• Before paying, the server checks that the player can carry every item reward. If an item still fails to fit, the items already given are taken back and the claim is undone, so nothing is lost.
• Items are given first, then money. On ESX, 'cash' goes into the money account. On standalone, money goes through Hooks.StandaloneAddMoney, which pays nothing until you edit it.

Admin

Death rules

Particle effects

Each entry is { dict, name, scale }. Where a use below shows a scale in brackets, that fixed scale replaces scale.

config/items.lua

Config.Items holds what the Halloween UI shows for each item: the Grimoire, cauldron, satchel, reward popups and toasts. Items without an entry show their raw name. It's display only. Your inventory still needs the items from install/items/ and the pictures from install/images/.

config/items.luaCopy
Config.Items = {
    hn_moonpetal = { label = 'Moonpetal', description = 'A pale flower that only blooms under moonlight.' },

    -- optional: your own picture instead of html/assets/items/hn_candy.png
    hn_candy = {
        label = 'Hallowed Candy',
        description = 'Sweet, sticky and slightly enchanted. A small sugar rush.',
        image = 'assets/items/my_candy.png',
    },
}

config/curses.lua

Curses come from tricks (1.8 seconds after the knock), cursed lanterns (1.2 seconds after collecting) and the ApplyCurse export. Every curse shares these keys:

Default values per curse

Chance on foot = weight ÷ 90 (the sum of all default weights). In a vehicle only pumpkin_head can land, because it's the only curse with vehicle = true.

Extra keys

Immunity

• Only one curse lands at a time. While a curse plus its immunity window is running, a new curse is resisted and the player sees the "curse resisted" toast ("Your purification repelled a curse.").
• The block is based on the curse's full duration. A curse lifted early by death still keeps new curses away until duration + CurseImmunityAfterCurse has passed.
• The Purifying Elixir lifts all curses and replaces the block with its own Config.Potions.hn_potion_purify.immunity (180 seconds).
• If no enabled curse is allowed (for example, every curse is disabled), no curse lands. A trick still pays its Souls.

config/potions.lua

Config.Potions decides what happens when a player uses an item. Every key in this table becomes usable: the pack registers it as a usable item on QBCore, Qbox and ESX, the internal satchel shows a Use button for it, and on ox_inventory the rklhalloween.useItem export accepts it (the item still needs server = { export = 'rklhalloween.useItem' } in ox_inventory/data/items.lua). Durations are in seconds.

The effect names are fixed: nightvision, swift, featherfall, phantom, vigor, purify, seer, candy, sludge. What each one does in game is described in Items, potions & recipes.

Use animations

Config.CandyAnim plays for items with the candy effect, and Config.PotionAnim plays for every other effect except sludge, which has its own vomit animation. Both play on the upper body only, so the player can keep moving. No animation plays while the player is in a vehicle.

Add your own consumable

Any item can reuse an existing effect with its own numbers:

config/potions.luaCopy
Config.Potions.my_herbal_tea = { effect = 'vigor', heal = 25, armor = 0 }

1. Register my_herbal_tea in your inventory. On ox_inventory, give it server = { export = 'rklhalloween.useItem' }. On QBCore, Qbox and ESX the pack registers it as usable on start.
2. Optional: add a Config.Items entry so the Halloween UI shows a proper name.

Timed effects are tracked per effect name, so two items with the same timed effect share one timer.

Hallowed Night — Module config

A key-by-key reference for the five activity files in config/: lanterns.lua, trickortreat.lua, cauldron.lua, gathering.lua and haunted.lua. Every default below is the value that ships in the file. All of them stay editable after escrow.

Before you edit

• The config files load as shared scripts (server and client) when the resource starts, so restart the resource after you change them.
• Each module has its own Enabled switch. Setting it to false turns that module off on both server and client.
• Lanterns, doors, gathering nodes and cauldrons only exist while the season is active (Config.Season in config/config.lua). Scheduled Haunted Nights also wait for the season. An admin start (/hnhaunt start or the StartHaunt export) works at any time.
• Every timed action (collect, knock, gather) is checked on the server: the player must start it there, stay close, and let the progress ring run for the full time (500 ms tolerance). One press of the interact key starts it; the key doesn't have to be held. The server also allows a little extra distance on top of each InteractDistance, because client-side ground snapping can shift positions slightly.

Units

Loot tables vs. weighted treats

Two reward formats are used across the modules, and they behave differently:

entry formatCopy
-- Loot entry: rolled on its own
{ chance = 45, item = 'hn_pumpkin_seeds', min = 1, max = 2 },   -- 45%: 1-2 seeds
{ chance = 10, money = 'cash', min = 50, max = 150 },            -- 10%: $50-150 cash

-- Treat entry: one of the list is picked by weight
{ weight = 50, item = 'hn_candy', min = 1, max = 3 },
{ weight = 10, money = 'cash', min = 25, max = 120 },

• item gives an inventory item. money pays an account: 'cash' or 'bank' (on ESX, cash maps to the money account).
• The amount is random between min and max. You can write amount = 3 instead for a fixed amount.
• If an item doesn't fit in the inventory, it isn't given and the player sees a "can't carry" notice.

Coordinates

/hncoords always copies vec4(x, y, z, heading). Lists that use vec3 (Lanterns.Locations, gathering points, Haunted center) need the 4th value removed. Lists that use vec4 (TrickOrTreat.Doors, Cauldron.Locations) keep it. Lantern, node, cauldron and tombstone props snap to the ground, so the exact z is not critical.

config/lanterns.lua — Soul Lantern Hunt

Glowing lanterns spawn around the map. Pressing E on one starts a short collect (the progress ring fills by itself) and gives Souls and loot. Cursed lanterns give more Souls and extra loot, but also put a random curse on the player.

Default lantern loot

• Cursed lantern: Souls.cursed + Loot + CursedLoot, then a random curse about 1.2 s later. Curse immunity and the vehicle rules from config/curses.lua still apply. It also counts toward the cursed stat.
• Personal mode: collected spots are saved in each player's progress for the current Config.Season.Id. ActiveCount and RespawnSeconds are not used. Every location the player hasn't collected yet is shown.
• Admin: /hnlanterns respawn clears every global lantern and its cooldown, then rolls a fresh set.

config/lanterns.lua — adding a spotCopy
Locations = {
    vec3(195.17, -933.77, 30.69),      -- Legion Square
    -- /hncoords gave vec4(412.10, -1001.30, 29.30, 90.0) -> drop the heading:
    vec3(412.10, -1001.30, 29.30),     -- your new spot
},

config/trickortreat.lua — Trick-or-Treat

Players knock on configured doors. A costumed NPC opens up and hands out a Treat (one weighted pick) or plays a Trick (a random curse).

Default treat odds

The weights add up to 100 here, so each weight reads as a percentage. They don't have to: with weights 2 and 1, the odds are 2/3 and 1/3.

What the four vec4 values mean

config/cauldron.lua — Witch's Cauldron

Cauldrons turn gathered ingredients into potions. Players pick a recipe in the cauldron UI, pass a stirring skill-check, and get the potion (or sludge).

Recipe format

config/cauldron.luaCopy
Recipes = {
    -- id = { result item, amount, ingredients }
    owl = {
        item = 'hn_potion_owl',            -- item given on success
        amount = 1,                        -- how many
        color = '#f5b942',                 -- potion accent colour in the cauldron UI and recipe book
        ingredients = {
            { item = 'hn_moonpetal',     amount = 2 },
            { item = 'hn_raven_feather', amount = 1 },
        },
    },
},
RecipeOrder = { 'owl', 'swift', 'feather', 'vigor', 'purify', 'seer', 'phantom' },

Default recipes

How a brew resolves

1. Opening the cauldron asks the server for the recipe list. The server checks the season, Hooks.CanParticipate and that the player is at a cauldron, then sends each recipe with the player's ingredient counts.
2. With Minigame.Enabled, the stir ring opens. Players press SPACE (or click anywhere in the stir window) while the marker is inside the glowing zone. Pressing Esc during the stir cancels it, and nothing is brewed or used up.
3. The server checks the ingredients again. Success: the ingredients are removed, the player gets the result item and Souls. Fail: the player gets Fail.Item, and the ingredients are removed only if Fail.LoseIngredients is on.
4. If the result item doesn't fit in the inventory, every removed ingredient is given back.

config/gathering.lua — Ingredient gathering

Gathering nodes are shared. Once someone gathers a point, it disappears for everyone until its respawn time has passed. Ghost Essence doesn't come from nodes: it drops from Haunted Night spirits (and the boss reward), the Specter curse and cursed lanterns. Pumpkin Seeds and Raven Feathers come from lanterns and trick-or-treat.

Node fields

Default nodes

Mandrake and Moonpetal use the gardening animation, and Bone Pile uses a kneel animation. If the player's inventory is full, the gather fails and the node stays up for someone else. Gathered points are tracked in server memory, so every node comes back after a resource restart.

config/gathering.lua — example extra node typeCopy
Nodes = {
    -- ...mandrake, moonpetal, bones...
    grave_bones = {
        label = 'Grave Bones',
        model = 'hn_bone_pile', fallbackModel = 'prop_rub_binbag_01',
        item = 'hn_bone_dust', min = 1, max = 1,
        time = 3500, respawn = 900,
        nightOnly = true,
        anim = { dict = 'amb@medic@standing@kneel@base', clip = 'base' },
        souls = 1,                        -- also pays 1 Soul per gather
        light = { 150, 60, 255 },         -- optional glow
        points = {
            vec3(-1740.00, -230.00, 55.50),
        },
    },
},

config/haunted.lua — Haunted Night event

The veil thins over one zone: fog and blood-moon visuals, waves of spirits, and then The Hollow King. The spirits are created by the server. The player nearest the zone centre (the "host") only supplies ground positions, and whoever owns each spirit runs its AI.

Event & schedule

Visuals

A player counts as inside once they're within the zone radius, and leaves only after moving 25 m past it, so the visuals don't flicker at the edge. The event HUD (wave, spirits left, timer, boss bar) is shown only to players inside the zone.

Spirits & waves

Boss

Boss HP by participants (defaults)

The boss doesn't take critical hits and can't be ragdolled. If his entity disappears (for example, when nobody is close enough to own him), the server spawns him again.

Rewards

To be eligible for the boss reward, a player must be a participant, still be online, be within radius + 2 × ParticipantRadius at the moment of victory, and pass Hooks.CanParticipate. The final list is passed to Hooks.OnBossDefeated(list).

Zones & blip

config/haunted.lua — adding a zoneCopy
Zones = {
    -- ...the three default zones...
    {
        label = 'My Graveyard',
        center = vec3(0.0, 0.0, 0.0),   -- /hncoords without the heading, on the ground
        radius = 80.0,
    },
},

Event phases

The status is published in GlobalState.hnHaunt and returned by exports['rklhalloween']:GetHauntState(). The announce banner reaches every player. The start, boss, victory and defeat banners only reach players within the zone radius + 600 m, and wave notices within the zone radius + 400 m.

Hallowed Night — Items, potions & recipes

The pack uses 16 items: 6 ingredients, a treat, a tool, 7 potions and the sludge from a failed brew. Item definitions for each inventory are in install/items/ (ox_inventory.lua, qb-core.lua, esx.sql) and the pictures are in install/images/. The Halloween UI has its own copy in html/assets/items/ and takes its labels from Config.Items.

All items

Weight is the value in install/items/ox_inventory.lua and qb-core.lua. esx.sql uses 1 for ingredients and candy, 6 for the bucket and 3 for potions and sludge.

• Lantern loot (Config.Lanterns.Loot): every entry rolls on its own, so one lantern can give several items. Lanterns can also give $50–150 cash (10%). A cursed lantern rolls Loot first, then CursedLoot as well.
• Treats (Config.TrickOrTreat.Treats): one weighted pick per treat. The default weights add up to 100, so each weight is also the percent chance. Cash ($25–120) has weight 10.
• Full inventory: loot that doesn't fit is skipped with a "You can't carry that." toast. A gathering node stays up when its item doesn't fit, so the player can come back.

Potion effects

What each effect does in game (client/modules/potions.lua), with the default numbers from Config.Potions:

How using an item works

1. The player uses the item. On ox_inventory the item calls the rklhalloween.useItem export, and ox removes the item itself. On QBCore, Qbox and ESX, the pack registers every Config.Potions item as usable. With the internal satchel, the player presses Use in the Grimoire.
2. The server removes one item (unless ox already did), applies the server side of the Purifying Elixir, logs the use with Hooks.Log(src, 'consume', ...) and tells the client to run the effect.
3. The client plays the use animation (see Config.PotionAnim / Config.CandyAnim), shows a toast, then runs the effect.

Cauldron recipes

From Config.Cauldron.Recipes, in the order of Config.Cauldron.RecipeOrder (the order the Grimoire recipe book and the cauldron use). Every recipe makes 1 potion.

• The player needs every ingredient. A successful brew (stirring minigame passed, or Minigame.Enabled = false) takes the ingredients, gives the potion and pays Config.Cauldron.Souls (2).
• A failed brew gives Fail.Item (hn_sludge ×1). It also takes the ingredients while Fail.LoseIngredients = true (the default). Set Fail.Item = false to give nothing.
• If the result doesn't fit in the inventory, the ingredients are given back.
• The server allows one brew per player every Config.Cauldron.BrewTime ms (3500).
• color is the accent of the recipe card in the UI (#rgb or #rrggbb).

Add a recipe

config/cauldron.lua (inside Config.Cauldron)Copy
Recipes = {
    -- ...the 7 default recipes...
    big_vigor = { item = 'hn_potion_vigor', amount = 2, color = '#ff3b4e', ingredients = {
        { item = 'hn_mandrake_root', amount = 3 },
        { item = 'hn_bone_dust', amount = 1 },
    } },
},
-- a recipe only shows up if its id is in this list
RecipeOrder = { 'owl', 'swift', 'feather', 'vigor', 'big_vigor', 'purify', 'seer', 'phantom' },

The result can be any item your inventory knows. If you brew a new item, add it to Config.Items for its label and description, and to Config.Potions if it should be usable.

Hallowed Night — Features & balancing

Soul Lantern Hunt

Mode = 'global' keeps ActiveCount shared lanterns on the map. The first player to collect one wins it, and a new one appears elsewhere after RespawnSeconds. Mode = 'personal' turns every location into a collectible that each player can claim once per season.

Anti-exploit: the server starts a timed action when the player presses E and only pays out if the full collect time has passed, the player is still close, and the lantern still exists.

Trick-or-Treat

Each door is a vec4, and the heading is the direction the NPC faces. The included doors are samples, so add your own with /hncoords. Per-door cooldown and a daily limit stop farming.

Curses

Only one curse at a time, followed by Config.CurseImmunityAfterCurse seconds of immunity. Curses flagged vehicle = false never land on players who are driving. The Purifying Elixir lifts all curses and grants immunity.

Witch's Cauldron & gathering

Brewing opens the cauldron UI. With Minigame.Enabled, players stir by pressing SPACE when the marker is in the glowing zone. Rounds, Speed, ZoneSize and MaxMisses set the difficulty. A failed brew gives Fail.Item (sludge) and, if Fail.LoseIngredients is on, uses up the ingredients.

Gathering nodes are shared: once someone gathers one it disappears for everyone until respawn seconds pass. Moonpetal is nightOnly (20:00–06:00 in-game).

Haunted Night

1. Announce: a banner for everyone, plus a flashing blip and radius on the map for AnnounceSeconds.
2. Waves: spirits spawn inside the zone. Each kill pays Souls and has a chance at Ghost Essence. The next wave starts WaveDelay seconds after the last spirit falls.
3. Boss: The Hollow King (pumpkin head, battle axe) with a boss bar. A Soul Nova knocks back nearby players every Nova.interval seconds, and he summons spirits at 66% and 33% health. His HP grows with each extra participant, up to 8000 (GTA syncs ped health in 13 bits, so higher values would break).
4. Victory: every participant still near the zone gets Rewards.Boss. If TimeLimit runs out first, the spirits retreat.

Start it on a schedule (Schedule, real server time) or with /hnhaunt start [zone]. Inside the zone, players get a client-side HALLOWEEN weather override, a fog timecycle and decorative tombstones.

Hallowed Night — Player guide

What a player sees and does in every activity, step by step. It's written so you can copy it into your own server guide or Discord. All numbers are the defaults from the config files, so if you change a value, update the matching line here too.

Getting started

• When: the event runs during the Halloween season, by default from 15 October to 3 November (server date). Outside the season the lanterns, doors, gathering spots and cauldrons are gone, and actions answer with "The veil is closed. Come back during the Halloween season."
• Your menu: type /halloween or press F7 to open the Grimoire (profile, leaderboard, rewards, recipes, curses).
• Souls are the event score, and every activity gives some. Each time your Souls change, a small pill in the lower right of the screen shows your new total and how many you just gained.
• Interacting: walk up to a lantern, door, plant or cauldron. A glowing prompt appears at the bottom of the screen (for example E Collect Soul Lantern). Press E. On servers that use a target eye (ox_target or qb-target), pick the option from the target menu instead.
• Timed actions: collecting, knocking and gathering show a flaming progress ring that fills on its own. You stand still while it runs. Press X to cancel. Dying, getting ragdolled or entering a vehicle also cancels it.
• You can't interact from inside a vehicle or while you're dead.

Where Souls come from

1. The Soul Lantern Hunt

1. Find a lantern. Glowing soul lanterns are spread across the whole map: the city, the beaches, Sandy Shores, Grapeseed, Paleto Bay, even Mount Chiliad. By default 20 are out at the same time. They appear when you're within 80 m and give off a warm orange glow.
2. Spot the cursed ones. A lantern with a purple glow and a crackling aura is cursed, and its prompt reads Collect Cursed Lantern. It gives more Souls and extra loot, but it also curses you. (Some servers hide which lanterns are cursed, so any lantern could be one.)
3. Collect it. Get within 2 m and press E. Your character kneels while the ring fills for 2.5 seconds ("Drawing out the lantern's soul..."). Press X to stop.
4. Get your reward. The lantern bursts into light and a reward card pops up in the middle of the screen with your Souls, items and cash.
5. Cursed? About a second later the curse lands. See Curses below.
6. Then it's gone. The lantern disappears for everyone, and a new one appears at a random spot about 4 minutes later. If another player finishes first, you get "Someone else claimed this lantern first."

Every line is rolled on its own, so one lantern can give several items, or none at all. A cursed lantern rolls the normal loot and the cursed loot.

2. Trick-or-Treat

1. Find a door. Doors are set by the server owner and have no marker by default. The sample doors are houses on Forum Drive, Grove Street, Mirror Park, the Vespucci Canals, Rockford Hills, Richman, Sandy Shores and Paleto Bay. Stand within about 2 m of the door and the Trick or Treat prompt appears.
2. Knock. Press E. Your character turns to the door and knocks for 2.2 seconds ("Knocking...").
3. Someone answers. A costumed neighbour appears in a puff of smoke, holding a candy bucket.
4. Treat (70%): the neighbour hands something over and a "Treat!" card shows +1 Soul and one treat.
5. Trick (30%): the neighbour laughs at you, a "Trick!" message appears, you get +2 Souls, and a moment later a curse lands.
6. The neighbour vanishes again after 3.5 seconds.

Limits

• Same door: 30 minutes between knocks. Too early and you get "Nobody answers... try again in 12m 30s."
• Per day: 40 knocks per real day (server date). After that: "You've trick-or-treated enough for today."
• Candy Bucket: some servers require a Candy Bucket to knock ("You need a Candy Bucket."). The bucket is the 500 Souls milestone reward.

3. Curses

Curses come from tricks and cursed lanterns. When one lands you get a "Cursed!" message with its name, and it appears in the effects list on the left side of the screen with its icon, a ring timer and the seconds left. Active potion buffs show up in the same list.

How a curse ends

• The timer runs out: you get "<curse> has faded."
• You die: dying lifts every curse (when Config.ClearCursesOnDeath is on, the default).
• Purifying Elixir: drink it to lift every curse at once ("All curses have been lifted.") and resist new ones for 3 minutes.

You can only carry one curse at a time. After a curse lands, new ones are resisted until its full time plus 20 seconds has passed, even if it ended early. A resisted curse shows "Your purification repelled a curse." Tricks and cursed lanterns still give their Souls when the curse is resisted.

4. Gathering ingredients

1. Find a plant or bone pile. Walk within about 2 m and the prompt reads Gather Mandrake, Gather Moonpetal or Gather Bone Pile.
2. Press E. Your character kneels or plants while the ring fills ("Gathering Mandrake...").
3. A "Gathered" message shows what you got, for example 2x Mandrake Root.
4. The spot disappears for everyone until it grows back. If someone else got there first: "This has already been gathered."

Where every ingredient comes from

5. Brewing at the Witch's Cauldron

1. Find a cauldron. Look for the Witch's Cauldron blip on the map. Each one glows green and has a witch waiting beside it. The default cauldrons are at the Pacific Bluffs cemetery, in Grapeseed and in Paleto Bay.
2. Open it. Press E on Use Witch's Cauldron.
3. Pick a recipe. The list on the left shows every potion. A green dot means you have everything for it right now. The right side shows the potion, its description and each ingredient as have / need. Missing ones are marked in red.
4. Brew. Click Brew (if you're missing something, the button reads Missing ingredients instead).
5. Stir the brew. A white marker runs around a ring with a glowing green zone on it. Press SPACE (or click on the stirring window) while the marker is inside the zone. You need 3 perfect stirs. Every perfect stir moves the zone and speeds the marker up. Your third miss ruins the brew. Press Escape to stop stirring without brewing: nothing is used up.
6. Wait. A bubbling pot shows "Brewing..." for 3.5 seconds while your character stirs.
7. Result. Success gives the potion and +2 Souls, with a burst of magic from the cauldron. A failed brew gives Cauldron Sludge, and the ingredients are lost.

The ingredient counts refresh after every brew, so you can brew again straight away. Close the window with the X button or Escape (not while a brew is in progress).

Recipes

Other usable items

Drinking potions

• Use the potion from your inventory. On servers without an inventory, open the Grimoire's Satchel tab and click Use.
• Your character drinks for about 2 seconds (no animation inside a vehicle), then "You drank the <potion>." appears.
• Timed potions show up in the effects list on the left with a ring timer. When one runs out: "<potion> wore off."
• Drinking the same potion again while it's active restarts its timer. The effects don't stack.

6. Haunted Night

A server-wide event. By default it starts at 20:00 and 23:30 server time during the season (when at least one player is online), or whenever an admin starts it. The Grimoire's profile tab shows when the next one is due.

1. The warning. Everyone gets a banner, "The Veil Thins: Spirits gather at Pacific Bluffs Cemetery in 2m 00s", with a deep bell. A flashing blip and a coloured circle mark the zone on the map.
2. Head to the zone. Inside the circle the weather turns to Halloween with heavy fog, a low drone plays and tombstones rise around the area. A panel on the right side of the screen shows the zone name, Wave, Spirits left and Time left (during the warning, that's the countdown to the start).
3. It begins. Banner: "Haunted Night: Defend <zone> from the restless dead!" The blip stops flashing and you have 15 minutes. (Only the warning banner goes to everyone. This one and the later banners show for players within about 600 m of the zone, and the wave messages within about 400 m.)
4. Three waves of spirits. A "Wave 1 / 3" message, then 6, 9 and 12 ghostly, staggering spirits attack. Whoever lands the killing blow gets "Spirit banished", +2 Souls and a 35% chance of Ghost Essence. The next wave starts 10 seconds after the last spirit falls. Spirits only spawn while at least one player is in or near the zone, but the clock keeps running.
5. The Hollow King. Banner: "The Hollow King Rises: Banish him before the veil tears!" A boss bar with his name and health appears at the top of the screen for players inside the zone. He has a pumpkin head, a battle axe and armour, and he doesn't ragdoll. His health grows with the crowd: 4000, plus 1200 for every participant after the first, up to 8000.
   • Soul Nova: every 18 seconds he releases a shockwave. Anyone within 7 m is knocked over and takes 15 damage. Within 60 m you get a warning, "The Hollow King unleashes a Soul Nova!" Fight from range or keep your distance after you strike.
   • Summons: at 66% and at 33% health he calls 4 more spirits around himself.
6. Victory. Banner: "The Veil Is Sealed: The Hollow King has fallen." Every eligible participant (see the box below) gets a reward card.
7. Defeat. If the 15 minutes run out first: "The Spirits Retreat: The veil closes... for now." There are no boss rewards, but you keep what you earned from spirit kills.

7. The Grimoire

Open it with /halloween or F7. Your Souls total is always shown in the header. Close it with the X button or Escape.

Milestones

Each milestone can be claimed once per season, as soon as your Souls total reaches it. If your inventory can't hold the items you get "You can't carry that." and nothing is given, so make room and claim again. A "Milestone Claimed" card shows what you received.

The screen at a glance

Player FAQ

• I can't find anything, and the Grimoire says "The veil is closed". The Halloween season isn't active on the server right now.
• The prompt doesn't show up. Get out of your vehicle, and make sure you aren't dead or already doing something. Prompts are hidden while a menu is open.
• Moonpetal is nowhere to be found. It only blooms between 20:00 and 06:00 in-game. Come back at night.
• "You can't carry that." Your inventory is full or too heavy. Make room and try again.
• The door won't open. You knocked there in the last 30 minutes, or you reached today's 40 knocks. The message tells you which.
• I didn't get Haunted Night rewards. You have to be near the zone when the Hollow King falls, and you must have been inside it during the fight.

Hallowed Night — Customization tutorials

Practical recipes for the most common changes. Everything here happens in files that stay open after escrow: config/, locales/, editable/, bridge/ and html/ (tutorial 8 also adds one line to fxmanifest.lua). Config files are read when the resource starts, so run restart rklhalloween (or restart the server) after every change. New or changed streamed files need a full server restart.

1. Add your own lantern, door, node and cauldron spots

1. Go to the spot in game. Stand on the ground there (don't save a spot while flying or in noclip).
2. Type /hncoords. It copies vec4(x, y, z, heading) to your clipboard, prints the same line in the F8 console and shows "Coordinates copied to clipboard."
3. Paste it into the right list below, in the format that list uses.

config/lanterns.luaCopy
Locations = {
    vec3(195.17, -933.77, 30.69),      -- Legion Square
    -- ... the existing spots ...
    -- /hncoords gave vec4(-1150.25, -1525.10, 4.35, 212.4): keep x, y, z only
    vec3(-1150.25, -1525.10, 4.35),    -- my new spot
},

Ground snapping

Lanterns, gathering nodes, cauldrons and tombstones are props. The pack looks for the ground just above the saved height (2 m, then 10 m, then 50 m higher) and settles the prop on it, so standing on the spot is enough. The server still checks the player's distance against the saved position (it allows the interact distance plus a little extra sideways, and roughly 15 m more than that up or down), so a spot saved far above or below where players stand ends in "You are too far away." Doors and zone centres aren't props: they use the height exactly as copied.

Door heading

When a player knocks, they're turned to face heading + 180 (towards the door), and the neighbour appears 1.15 m in front of them, facing back at them. The easy way: stand on the doorstep with your back to the door, facing where the neighbour should look, and run /hncoords. If you copied it while facing the door, add 180 to the heading (subtract 360 if the result is above 360).

config/trickortreat.luaCopy
Doors = {
    vec4(-14.30, -1441.20, 31.10, 180.0),     -- Forum Drive
    -- ... the existing doors ...
    vec4(-1150.25, -1525.10, 4.35, 212.4),    -- copied with my back to the door
},

A whole new gathering node type

Every entry in Config.Gathering.Nodes becomes a node type, so you can add your own from the config alone. It needs the same keys as the built-in ones. Any vanilla prop works as the model.

config/gathering.lua — inside NodesCopy
pumpkins = {
    label = 'Pumpkin Patch',                 -- prompt: "Gather Pumpkin Patch"
    model = 'prop_veg_crop_03_pump', fallbackModel = 'prop_veg_crop_03_pump',
    item = 'hn_pumpkin_seeds', min = 2, max = 3,
    time = 3000,                             -- ms
    respawn = 300,                           -- seconds
    nightOnly = false,
    anim = { dict = 'amb@world_human_gardener_plant@male@base', clip = 'base' },
    souls = 0,
    -- light = { 255, 140, 40 },             -- optional glow colour
    points = {
        vec3(-1150.25, -1525.10, 4.35),
    },
},

2. Change rewards and loot tables

There are two kinds of loot table:

• Rolled (chance): every line is rolled on its own, chance is a percentage from 0 to 100 (100 if you leave it out). Used by Config.Lanterns.Loot, Config.Lanterns.CursedLoot and the Haunted Night items lists.
• Weighted (weight): exactly one line is picked, with odds equal to its weight divided by the total. Used by Config.TrickOrTreat.Treats.

Each line gives either an item or money ('cash' or 'bank') with a random amount from min to max. A fixed amount works too.

config/lanterns.luaCopy
Loot = {
    { chance = 45, item = 'hn_pumpkin_seeds', min = 1, max = 2 },
    { chance = 25, item = 'hn_raven_feather', min = 1, max = 1 },
    { chance = 30, item = 'hn_candy',         min = 1, max = 2 },
    { chance = 10, money = 'cash',            min = 50, max = 150 },
    { chance = 5,  item = 'hn_mandrake_root', min = 1, max = 1 },   -- new: rare Mandrake
},
CursedLoot = {
    { chance = 70, item = 'hn_ghost_essence', min = 1, max = 1 },
    { chance = 40, item = 'hn_bone_dust',     min = 1, max = 2 },
    { chance = 15, money = 'bank',            min = 250, max = 500 }, -- new
},

config/trickortreat.luaCopy
Treats = {
    { weight = 50, item = 'hn_candy',         min = 1, max = 3 },
    { weight = 20, item = 'hn_pumpkin_seeds', min = 1, max = 2 },
    { weight = 15, item = 'hn_raven_feather', min = 1, max = 1 },
    { weight = 5,  item = 'hn_moonpetal',     min = 1, max = 1 },
    { weight = 10, money = 'cash',            min = 25, max = 120 },
    { weight = 2,  item = 'hn_potion_swift',  amount = 1 },         -- new: about 2 in every 102 treats
},

config/haunted.luaCopy
Rewards = {
    Kill = { souls = 2, items = { { chance = 35, item = 'hn_ghost_essence', min = 1, max = 1 } } },
    Boss = {
        souls = 25,
        items = {
            { chance = 100, item = 'hn_ghost_essence', min = 2, max = 3 },
            { chance = 60,  item = 'hn_potion_phantom', min = 1, max = 1 },
            { chance = 50,  item = 'hn_candy', min = 3, max = 6 },
        },
        money = { account = 'cash', min = 1500, max = 3500 },   -- remove the line for no money
    },
},

Every reward key

3. Add or edit a milestone

Milestones live in Config.Milestones (config/config.lua). Each one has the Souls needed, a title and a list of rewards: { type = 'item', name = 'x', amount = 1 } or { type = 'money', account = 'cash' | 'bank', amount = 100 }.

config/config.luaCopy
Config.Milestones = {
    { souls = 25,  label = 'Wandering Spirit', rewards = { { type = 'item', name = 'hn_candy', amount = 5 }, { type = 'money', account = 'cash', amount = 500 } } },
    { souls = 75,  label = 'Lantern Keeper',   rewards = { { type = 'item', name = 'hn_potion_swift', amount = 2 }, { type = 'money', account = 'cash', amount = 1500 } } },
    { souls = 150, label = 'Hex Weaver',       rewards = { { type = 'item', name = 'hn_potion_purify', amount = 2 }, { type = 'item', name = 'hn_potion_seer', amount = 2 } } },
    { souls = 300, label = 'Veil Walker',      rewards = { { type = 'item', name = 'hn_potion_phantom', amount = 2 }, { type = 'money', account = 'bank', amount = 5000 } } },
    { souls = 500, label = 'Hollow Sovereign', rewards = { { type = 'item', name = 'hn_candy_bucket', amount = 1 }, { type = 'money', account = 'bank', amount = 15000 } } },
    -- new 6th tier
    { souls = 750, label = 'Lord of the Veil', rewards = {
        { type = 'item', name = 'hn_potion_purify', amount = 5 },
        { type = 'item', name = 'hn_potion_vigor', amount = 5 },
        { type = 'money', account = 'bank', amount = 25000 },
    } },
}

• Keep them in ascending order. The Grimoire's progress bar runs up to the last milestone's Souls.
• Add new tiers at the end. Claims are saved by position (1st, 2nd, ...). Inserting a tier in the middle of a season shifts every claim after it, so players could claim a tier twice or lose one.
• Items are checked first. If any item doesn't fit, the player gets "You can't carry that." and nothing is given (items already given are taken back). Money is paid after the items.
• Milestones use the player's current Souls total. Removing Souls with /hnsouls doesn't undo claims that were already made.

4. Add a new potion recipe

A new potion needs four things: a UI label, an inventory item, an effect and a recipe. The effect must use one of the existing effect types in Config.Potions. New effect types need code in the escrowed client, so they can't be added from the config.

Example: a Greater Vigor potion that heals more than the normal one.

Step 1: label and description for the Halloween UI

config/items.lua — inside Config.ItemsCopy
hn_potion_greater_vigor = { label = 'Greater Vigor', description = 'A thick red draught that knits bones in seconds.' },

Step 2: register the item in your inventory

ox_inventory/data/items.luaCopy
["hn_potion_greater_vigor"] = { label = "Greater Vigor", weight = 150, stack = true, close = true, server = { export = 'rklhalloween.useItem' }, description = "A thick red draught that knits bones in seconds." },

qb-core/shared/items.luaCopy
hn_potion_greater_vigor = { name = 'hn_potion_greater_vigor', label = "Greater Vigor", weight = 150, type = 'item', image = 'hn_potion_greater_vigor.png', unique = false, useable = true, shouldClose = true, description = "A thick red draught that knits bones in seconds." },

ESX — SQLCopy
INSERT IGNORE INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
    ('hn_potion_greater_vigor', 'Greater Vigor', 3, 0, 1);

With the built-in satchel (Config.Inventory = 'internal') there's nothing to register. Add an image named hn_potion_greater_vigor.png to html/assets/items/ for the Halloween UI (or set image in Config.Items), and to your inventory's image folder.

Step 3: the effect

config/potions.lua — inside Config.PotionsCopy
hn_potion_greater_vigor = { effect = 'vigor', heal = 100, armor = 50 },

With qb-inventory (on QBCore or Qbox) or the ESX default inventory, every key in Config.Potions is registered as a usable item automatically through the framework. ox_inventory calls the pack through the server = { export = 'rklhalloween.useItem' } line from step 2, and the satchel shows a Use button for it.

Step 4: the recipe

config/cauldron.luaCopy
Recipes = {
    -- ... the existing recipes ...
    greatervigor = { item = 'hn_potion_greater_vigor', amount = 1, color = '#ff7a1a', ingredients = {
        { item = 'hn_mandrake_root', amount = 2 },
        { item = 'hn_ghost_essence', amount = 1 },
        { item = 'hn_bone_dust',     amount = 1 },
    } },
},
RecipeOrder = { 'owl', 'swift', 'feather', 'vigor', 'greatervigor', 'purify', 'seer', 'phantom' },

Only recipes listed in RecipeOrder show up in the cauldron and in the Grimoire's Recipes tab. color tints the recipe card and the potion's glow in the UI. Timed buffs are tracked per effect type, so two potions with the same effect share one timer: drinking one while the other is active only restarts the timer.

5. Disable or tune curses

Each curse in Config.Curses (config/curses.lua) has the same base keys:

config/curses.luaCopy
levitate = {
    enabled = false,                    -- never picked
    weight = 10, duration = 12, vehicle = false,
    -- ... keep the other keys ...
},
blackout = {
    enabled = true, weight = 4, duration = 10, vehicle = false,   -- rarer and shorter
    label = 'Shroud of Night',
    description = 'Darkness closes in from every side.',
    icon = 'moon',
},

-- below Config.Curses
Config.CurseImmunityAfterCurse = 60   -- default 20: longer break between curses

• No curses at all: set every curse to enabled = false. Tricks still pay their Souls, and cursed lanterns their Souls and loot. For no tricks at all, set Config.TrickOrTreat.TrickChance = 0.0; for no cursed lanterns, Config.Lanterns.CursedChance = 0.0.
• Keep curses after death: Config.ClearCursesOnDeath = false in config/config.lua.
• New curse types can't be added from the config: each curse name needs its own client code. A new name in Config.Curses would be picked by the server but do nothing in game.

6. Add a Haunted Night zone and change the schedule

Zones are a list in Config.Haunted.Zones. The first zone is 1, so a fourth zone starts with /hnhaunt start 4. Scheduled starts pick a random zone.

config/haunted.luaCopy
Schedule = {
    { hour = 21, minute = 0 },          -- real server time, 24h
},
MinPlayers = 4,                         -- online players needed for a scheduled start
AnnounceSeconds = 180,                  -- warning before it starts
TimeLimit = 20 * 60,                    -- seconds before the spirits retreat

Zones = {
    { label = 'Pacific Bluffs Cemetery', center = vec3(-1735.00, -220.00, 56.00), radius = 80.0 },
    { label = 'Grapeseed Fields',        center = vec3(2010.00, 4890.00, 42.80),  radius = 90.0 },
    { label = 'Sandy Shores Outskirts',  center = vec3(1600.00, 3600.00, 35.00),  radius = 90.0 },
    -- zone 4: x, y, z from /hncoords (drop the heading). Test it with /hnhaunt start 4
    { label = 'Marlowe Vineyard',        center = vec3(-1890.00, 2070.00, 140.50), radius = 80.0 },
},

• Admin-only: Schedule = {}. Then only /hnhaunt start [zone] or the StartHaunt export starts it.
• Scheduled starts only happen during the season, when nothing else is running and at least MinPlayers are online. Admin starts work any time, even out of season.
• Pick open, flat ground on land. Spirits spawn on ground points inside 80% of the radius, 5 to 90 m from the host player (the player nearest the centre), within 25 m of the centre's height and never in water. The zone check uses the centre's height too, so save it standing at ground level.

Waves, spirits and boss

your event script — serverCopy
-- start zone 4 from your own scheduler
local ok, msg = exports['rklhalloween']:StartHaunt(4)
if not ok then print(msg) end   -- e.g. 'A Haunted Night is already running.'

7. Run the lantern hunt in personal (collectible) mode

In 'personal' mode every location in Locations is a collectible: each player can claim each spot once per season, at their own pace, with no race. Lanterns a player already took stay hidden for that player only.

config/lanterns.luaCopy
Config.Lanterns = {
    Enabled = true,
    Mode = 'personal',
    -- ActiveCount and RespawnSeconds are ignored in personal mode
    CursedChance = 0.15,
    CursedLooksDifferent = true,
    Blips = {
        Enabled = true,             -- optional: a map blip on every lantern the player still needs
        Sprite = 484, Color = 47, Scale = 0.6,
    },
    -- ... the rest of the file unchanged ...
}

• Which lanterns are cursed is fixed per location in personal mode (worked out from the spot's number and CursedChance), so the same spots are cursed for everyone.
• Progress is saved with the player's season data. A new Config.Season.Id resets the collection.
• /hnlanterns respawn is meant for global mode. In personal mode every location is always listed anyway.
• Add plenty of locations: with 32 spots, a dedicated player finishes quickly. Remember to add new spots at the end of the list (see tutorial 1).

8. Add a new language

1. Copy locales/en.lua to a new file, for example locales/de.lua.
2. Change the first table name from Locales['en'] to Locales['de'], and translate every value. Keep the keys and the %s / %d placeholders, in the same order.
3. Add the file to shared_scripts in fxmanifest.lua. Locale files are listed one by one there, not with a wildcard.
4. Set Config.Locale = 'de' in config/config.lua.

locales/de.luaCopy
Locales = Locales or {}

Locales['de'] = {
    too_far = 'Du bist zu weit weg.',          -- was: 'You are too far away.'
    door_cooldown = 'Niemand macht auf... versuche es in %s erneut.',
    -- ... every other key ...

    ui = {
        grimoire_title = 'Grimoire der Geweihten Nacht',
        -- ... every key of the ui block ...
    },
}

fxmanifest.luaCopy
shared_scripts {
    -- ... the config files ...
    'locales/en.lua',
    'locales/tl.lua',
    'locales/de.lua',      -- new
    'shared/_init.lua',
}

Some player-facing text lives in the config files instead of the locale: item labels and descriptions (Config.Items), curse labels and descriptions (Config.Curses), milestone titles, gathering node labels, zone labels, Config.Haunted.Boss.Label, Config.Cauldron.Blip.Label and Config.Souls.Label. Translate those too.

9. Restyle the UI

The UI is plain HTML, CSS and JavaScript in html/, never encrypted. Most colours come from CSS variables at the top of html/style.css:

html/style.cssCopy
:root {
    --gold: #7fe0ff;        /* icy blue instead of gold */
    --gold-2: #c9f3ff;
    --ember: #3fa9ff;
    --ember-2: #7cc6ff;
    --radius: 8px;
}

/* move the notifications down, e.g. below your own HUD */
#toasts { top: 120px; }

• Panel frame and background: the Grimoire and cauldron use gradients written directly in the .panel and .panel::before rules. --night, --night-2 and --night-3 are defined but the current rules don't use them.
• Positions: #prompt and #progress (bottom centre), #toasts (top right), #souls-pill (lower right), #effects (left), #banner and #boss (top centre), #haunt (right), #reward (centre).
• Progress ring colours: the <linearGradient id="flame"> in html/index.html.
• Item images: html/assets/items/<item>.png, or set image on the item in Config.Items.
• Potion colours: color on each recipe in Config.Cauldron.Recipes.

10. Change commands, keys and the admin permission

config/config.luaCopy
Config.InteractKey = { control = 38, label = 'E' }   -- prompt mode only; label is what the prompt shows
Config.CancelKey = { control = 73, label = 'X' }     -- cancels timed actions

Config.Menu = {
    Command = 'grimoire',      -- /grimoire instead of /halloween
    Key = 'F6',                -- default keybind, '' = no keybind
}

Config.Admin = {
    Ace = 'hallowed.admin',
    Commands = {
        haunt = 'hnhaunt',     -- /hnhaunt start [zone] | /hnhaunt stop
        souls = 'hnsouls',     -- /hnsouls [playerId] [amount]
        coords = 'hncoords',   -- copies your position as vec4(...)
        lanterns = 'hnlanterns', -- /hnlanterns respawn
    },
}

• control is a GTA control index and label is only the text on screen, so change both together.
• Players can rebind the Grimoire key in Settings → Key Bindings → FiveM (Hallowed Night - Grimoire). FiveM keeps a player's binding once it exists, so a new default Key mainly reaches players who never had one.
• Admin commands need the ace in Config.Admin.Ace (the server console is always allowed). If you rename the ace, rename it in server.cfg too. /hncoords is a client command and works for everyone.
• Stirring always uses SPACE (or a click). That key lives in html/app.js, and its hint text is the stir_hint locale string.

server.cfgCopy
add_ace group.admin hallowed.admin allow
# or give it to a single moderator group
add_ace group.mod hallowed.admin allow

11. Switch to ox_target or qb-target

config/config.luaCopy
Config.Interaction = 'ox_target'   -- 'prompt' | 'ox_target' | 'qb-target' | 'auto'

'auto' uses ox_target if it's running, then qb-target, and otherwise the Halloween prompt. Detection happens when the resource starts, so ensure your target resource before rklhalloween in server.cfg.

Target options use the same labels as the prompt (from the locale) and the same checks: nothing shows while the player is busy, dead or in a vehicle, or while ClientHooks.CanInteract() returns false. The progress ring and the X cancel key still work. Set Config.Debug = true to see the door spheres while you test.

12. Start a fresh season

config/config.luaCopy
Config.Season = {
    AlwaysOn = false,
    Start  = { month = 10, day = 15 },   -- server local date
    Finish = { month = 11, day = 3 },
    Id = '2027',                          -- was '2026': new leaderboard and progress
}

All progress is stored in server KVP under the season id: hn:<Id>:p:<identifier> (the player record) and hn:<Id>:s:<identifier> (the leaderboard summary). A new Id starts everyone from zero. The old data stays where it is, so switching back to the old id brings it back.

• Satchel warning: with Config.Inventory = 'internal' the satchel is part of the player record, so a new season id also empties it.
• The dates use the server's local date. A season can cross New Year (for example December to January). The season state is re-checked every 5 minutes.
• AlwaysOn = true ignores the dates, handy for testing.
• Progress is saved per character on Qbox, QBCore and ESX, and per license on standalone.

13. Make brewing easier or harder

config/cauldron.luaCopy
BrewTime = 3500,              -- ms animation after the minigame
Souls = 2,                    -- souls per successful brew

Minigame = {
    Enabled = true,           -- false = no minigame, every brew succeeds
    Rounds = 3,               -- perfect stirs needed
    Speed = 1.0,              -- marker speed multiplier
    ZoneSize = 0.18,          -- share of the ring that counts (0.05 - 0.5)
    MaxMisses = 2,            -- the brew fails on miss number MaxMisses + 1
},

Fail = {
    LoseIngredients = true,   -- false = keep the ingredients on a failed brew
    Item = 'hn_sludge', Amount = 1, -- Item = false gives nothing
},

• The marker goes round at 150 degrees per second times Speed, and each perfect stir makes it 14% faster and moves the zone.
• ZoneSize = 0.18 is about 65 degrees of the ring. The UI clamps it between 18 and 180 degrees.
• With LoseIngredients = false the player keeps the ingredients and still gets Fail.Item, so set Item = false too if you don't want free sludge.

14. Turn modules and helpers on or off

15. Plug the pack into your server with hooks

The hook files stay open after escrow. A few common uses:

editable/server/hooks.luaCopy
-- Discord logs for every rewarded action ('' = off)
Hooks.Webhook = 'YOUR_DISCORD_WEBHOOK_URL'

-- Block players from every Halloween activity
function Hooks.CanParticipate(src)
    if Player(src).state.jailed then return false end   -- example: a state bag your jail script sets
    return true
end

-- Bonus for everyone who helped kill the Hollow King
function Hooks.OnBossDefeated(participants)
    for _, src in ipairs(participants) do
        Bridge.AddItem(src, 'hn_potion_purify', 1)
    end
end

-- Mirror Souls into another system
function Hooks.OnSoulsChanged(src, identifier, total, delta, reason)
    -- reason: 'lantern', 'treat', 'trick', 'brew', 'gather', 'specter', 'spirit', 'boss', 'admin', or the reason given to the AddSouls export ('export' if none)
    TriggerEvent('my_battlepass:addPoints', src, delta)   -- example: your own event
end

editable/client/hooks.luaCopy
-- Block interactions in your own states
function ClientHooks.CanInteract()
    if Config.DisableWhileDead and Bridge.IsDead() then return false end
    if IsPedInAnyVehicle(PlayerPedId(), false) then return false end
    if LocalPlayer.state.handcuffed then return false end   -- example: your own state bag
    return true
end

-- Send the pack's messages to your own notify script
function ClientHooks.Notify(data)
    -- data: { type, title, message, icon, item, souls, items }
    -- type: 'success' | 'error' | 'info' | 'curse' | 'souls' | 'haunt' | 'item'
    exports['your_notify']:Show(data.title or 'Hallowed Night', data.message, data.type)   -- replace with your script's export
end

ClientHooks.Notify replaces the small messages (only the "Cancelled." toast always uses the Halloween UI). Reward cards, banners, the effects list and the Haunted Night HUD always use the Halloween UI. Hooks.Log(src, action, details) receives these actions: lantern, trick_or_treat, curse, specter_killed, consume, gather, brew, boss_defeated, milestone and admin_souls.

Hallowed Night — Commands & keybinds

Admin = add_ace group.admin hallowed.admin allow. Every command name can be changed in Config.Admin.Commands. All admin commands also work from the server console.

Hallowed Night — Exports, state & hooks

You can connect Hallowed Night to the rest of your server in three ways. Exports can be called from any other resource. State bags let any script read the live season and event state. Hooks and the bridge are small open Lua files inside rklhalloween that stay editable after escrow. You edit them to plug the pack into your framework, logs, notifications and weather script. Always call exports as exports['rklhalloween'], which is why the folder name must stay rklhalloween.

Server exports

serverCopy
exports['rklhalloween']:AddSouls(src, 5, 'quest_complete')

-- spending: check the balance first, because removing more than the player has just stops at 0
if exports['rklhalloween']:GetSouls(src) >= 50 then
    exports['rklhalloween']:AddSouls(src, -50, 'souls_shop')
end

serverCopy
local souls = exports['rklhalloween']:GetSouls(src)
local stats = exports['rklhalloween']:GetStats(src)
if stats and stats.bosses > 0 then
    -- this character has helped defeat the Hollow King this season
end

serverCopy
local curse = exports['rklhalloween']:ApplyCurse(src)
if curse then
    print(('%s was cursed with %s'):format(GetPlayerName(src), curse))
end

serverCopy
local ok, msg = exports['rklhalloween']:StartHaunt(2)
print(msg)
print(exports['rklhalloween']:GetHauntState().status) -- idle | announce | active | boss | ended

ox_inventory/data/items.luaCopy
["hn_potion_vigor"] = {
    label = "Elixir of Vigor", weight = 150, stack = true, close = true,
    server = { export = 'rklhalloween.useItem' },
    description = "Mends wounds and hardens the skin.",
},

Client exports

clientCopy
exports['rklhalloween']:OpenGrimoire()
local curses = exports['rklhalloween']:GetActiveCurses() -- { 'pumpkin_head', ... }

State bags

The pack publishes its shared state in state bags, so any resource on the server or client can read it without an export. Treat these as read-only: the pack overwrites them, and writing to them yourself breaks the sync.

GlobalState.hnHaunt fields

any resource (server or client)Copy
if GlobalState.hnSeason then
    -- Halloween content is live
end

local haunt = GlobalState.hnHaunt
if haunt and haunt.status ~= 'idle' then
    print(('Haunted Night at %s, wave %d/%d'):format(haunt.label, haunt.wave or 0, haunt.waves or 0))
end

-- fires on every update (each new wave too), so compare with the last status
local last = 'idle'
AddStateBagChangeHandler('hnHaunt', 'global', function(_, _, value)
    local status = value and value.status or 'idle'
    if status ~= last then
        last = status
        print('Haunted Night is now ' .. status)
    end
end)

Client events (listen only)

The server sends these net events to the player's client. Another client resource can listen to them with RegisterNetEvent to react, for example to update your own HUD. Never trigger them yourself. The callback events (rklhalloween:cb:*, rklhalloween:ccb:*) are internal.

Server hooks

editable/server/hooks.lua is the first server script to load (right after the shared scripts: the config files, the locales and shared/_init.lua) and stays open after escrow. Hooks are plain functions that run inside rklhalloween, so edit the file itself (another resource can't replace them). Inside a hook you can use Config, Bridge and any other resource's exports.

editable/server/hooks.luaCopy
-- Discord webhook for logs ('' = off)
Hooks.Webhook = 'https://discord.com/api/webhooks/your-id/your-token'

Client hooks

editable/client/hooks.lua loads right after bridge/client.lua and stays open after escrow.

Bridge: custom frameworks & inventories

Everything the pack needs from your server goes through bridge/server.lua and bridge/client.lua. Both stay open after escrow. On a framework or inventory that isn't supported, these are the only files you need to touch. Replace the function bodies, but keep the names, arguments and return types. At start, the server console prints which modes were picked: [rklhalloween] framework: … | inventory: ….

bridge/server.lua

bridge/client.lua