> For the complete documentation index, see [llms.txt](https://k0ssek-scripts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k0ssek-scripts.gitbook.io/docs/scripts/halloween/installation.md).

# Installation

Requirements, the five items, start order, admin access and the places to check before opening.

## Requirements

| Resource                                                                                                              | Required | Notes                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| OneSync                                                                                                               | Yes      | On by default with txAdmin. The server checks every pass, hit and knock against where players really stand.                             |
| [ox\_lib](https://github.com/overextended/ox_lib)                                                                     | Yes      | UI, callbacks, zones, locales, key bindings                                                                                             |
| [oxmysql](https://github.com/overextended/oxmysql)                                                                    | Yes      | The tables are created on the first start                                                                                               |
| ESX, QBCore or QBX                                                                                                    | Yes      | Characters, items, money and admin checks                                                                                               |
| An inventory                                                                                                          | Yes      | ox\_inventory, qb-inventory, ps-inventory, lj-inventory, qs-inventory, or ESX's own                                                     |
| [ox\_target](https://github.com/overextended/ox_target) or [qb-target](https://github.com/qbcore-framework/qb-target) | Optional | Without one, players use keys with a line on screen                                                                                     |
| A weather script                                                                                                      | Optional | Bridges for cd\_easytime, qb-weathersync, vSync and Renewed-Weathersync. See [Compatibility](/docs/scripts/halloween/compatibility.md). |

Game build 2699 or newer is recommended (`sv_enforceGameBuild 2699`), or 3258 for Rockstar's own zombies. Older builds work: models and effects that need a newer build fall back to the base game's.

## Install

{% stepper %}
{% step %}

### Download the resource

After purchase, the script is in your [Cfx.re Portal](https://portal.cfx.re/assets/granted-assets). See [Download & Updates](/docs/getting-started/download-and-updates.md).
{% endstep %}

{% step %}

### Add the five items to your inventory

The `__INSTALL` folder has the item definitions for each inventory and a picture for each item. Copy the entries from the file that matches your inventory, and the pictures into its image folder.

| Item                | Label                 | What it is                                                          |
| ------------------- | --------------------- | ------------------------------------------------------------------- |
| `halloween_candy`   | Candy                 | Candy a player carries. It can be lost until it is banked.          |
| `halloween_pumpkin` | Cursed Pumpkin        | Brewed at the cauldron. Using it opens the roulette.                |
| `halloween_relic`   | Phantom Relic         | The rare one: from the Phantom, milestones and the brew. Opens too. |
| `halloween_ash`     | Ash                   | Left by a miss in the roulette. Enough ash trades for a Relic.      |
| `halloween_trophy`  | Halloween 2026 Trophy | One per character, a keepsake.                                      |

| File               | Inventory     | Where the items go                 |
| ------------------ | ------------- | ---------------------------------- |
| `ox_inventory.lua` | ox\_inventory | `ox_inventory/data/items.lua`      |
| `qb-inventory.lua` | qb-inventory  | `qb-core/shared/items.lua`         |
| `ps-inventory.lua` | ps-inventory  | `qb-core/shared/items.lua`         |
| `lj-inventory.lua` | lj-inventory  | `qb-core/shared/items.lua`         |
| `qs-inventory.lua` | qs-inventory  | The item list of your qs-inventory |

On ESX without ox\_inventory, add the items to the `items` table of your database:

```sql
INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
    ('halloween_candy', 'Candy', 1, 0, 1),
    ('halloween_pumpkin', 'Cursed Pumpkin', 1, 0, 1),
    ('halloween_relic', 'Phantom Relic', 1, 1, 1),
    ('halloween_ash', 'Ash', 1, 0, 1),
    ('halloween_trophy', 'Halloween 2026 Trophy', 1, 1, 0);
```

{% hint style="info" %}
The names can be changed in the config (`Config.Candy.item` in `config/shared.lua`, `Config.Items` in `config/rewards.lua`). Change them in your inventory too. The loot tables and the shop also name ordinary items (burger, water, sprunk, scrapmetal): any item your inventory does not have is left out, and the server console says which one at start.
{% endhint %}
{% endstep %}

{% step %}

### Start it in the right place

Start it **after** ox\_lib, oxmysql, your framework, your inventory and your target resource.

```cfg
ensure oxmysql
ensure ox_lib
ensure es_extended        # or qb-core / qbx_core
ensure ox_inventory       # your inventory
ensure ox_target          # or qb-target, if you use one

ensure kossek_halloween
```

{% endstep %}

{% step %}

### Restart the server

The event streams five models of its own (the cauldron, the candy pail, the ritual circle, the notice board and the lectern). A new model needs a full server restart, `ensure` on a running server is not enough.
{% endstep %}

{% step %}

### Give your admins access

| Framework     | Who is an admin                                                                                |
| ------------- | ---------------------------------------------------------------------------------------------- |
| ESX           | The groups in `Config.AdminGroups` (`config/server.lua`), by default admin, superadmin and god |
| QBCore        | The admin permission of qb-core, or the command ace                                            |
| QBX           | The admin ace, or the command ace                                                              |
| {% endstep %} |                                                                                                |

{% step %}

### Check the places before you open the event

The places come with defaults on open, flat ground of the standard map. A server with its own map edits around them walks them once. Every change is saved in the database.

* **Altars** (`/hwaltar list`, `/hwaltar goto <id>`): five defaults. Fix one with `/hwaltar move <id>`, add your own with `/hwaltar add`.
* **Graves** (`/hwgrave list`, `/hwgrave goto <id>`): three defaults, for the bears and for digging.
* **The cauldron** (`/hwcauldron goto legion_square`): one default on Legion Square.
* **Houses**: 349 houses, at the front door (254 of them) or at the letterbox by the street. `/hwdoor show` puts them on your map.

All commands are on [Admin Tools](/docs/scripts/halloween/admin-tools.md).
{% endstep %}
{% endstepper %}

## Database

Nothing to import. The script creates its tables on the first start, all named `kossek_halloween_*`:

| Table                                                        | Holds                                                       |
| ------------------------------------------------------------ | ----------------------------------------------------------- |
| `kossek_halloween_players`                                   | Per character: taking part, banked candy, stats             |
| `kossek_halloween_state`                                     | The server's brew, records, the Book of the Bear            |
| `kossek_halloween_altars`, `_graves`, `_cauldrons`, `_doors` | Places added or changed in game                             |
| `kossek_halloween_door_visits`                               | Knocks and digs of the day                                  |
| `kossek_halloween_earnings`                                  | Daily limits per source                                     |
| `kossek_halloween_owed`                                      | Rewards waiting for a player who was offline or had no room |
| `kossek_halloween_decorations`                               | Decorations placed with `/hwdecor`                          |

## Updating

Replace the folder with the one from the new download, then put back what you changed: `config/`, `locales/`, `bridge/`. Compare your config with the new one and add any new options. Everything players earned lives in the database, so it is kept.

## Next year

The event is not tied to 2026. To run it again, empty the tables (or keep them for the records), and change the trophy's title in `Config.Trophy` and its label in your inventory.