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

# Halloween

Documentation for RTX Halloween, the FiveM Halloween Script & Map for ESX, QBCore and QBox: installation, configuration, commands, exports and FAQ.

##

{% embed url="<https://www.youtube.com/watch?v=2hcJSSqKgG8>" %}

## Purchase

[Purchase this resource](https://rtx.tebex.io/package/5972997)

**RTX Halloween** brings the whole Halloween night to your FiveM server. Take your bucket out and go trick or treating door to door - a neighbour opens every door, the candy you get lands in the bucket in your hand and everybody around you sees it fill up. Pick pumpkins on the hill, carve a face into them with your own knife, and decorate any house in the city with 35 custom decorations. And watch out - some doors play a trick on you.

## Requirements

| Resource                              | Required                                                                                       |
| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `rtx_halloween`                       | Yes - the script, all models and animations are inside it                                      |
| `oxmysql`                             | Only with `Config.Decorations.storage = "mysql"` and with ESX / QBCore items from the sql file |
| `ox_inventory` / `qb-inventory`       | No - any inventory works, see [Inventory](#2-framework-and-inventory)                          |
| `ox_target` / `qb-target` / `qtarget` | No - only if you want target instead of the key prompt                                         |

## Installation

{% stepper %}
{% step %}

### Add the resource

Place `rtx_halloween` into your resources folder and add it to your `server.cfg`, after your framework, `oxmysql` and your inventory:

```
ensure rtx_halloween
```

{% hint style="warning" %}
Keep the `stream` folder and the `data` folder. The `stream` folder holds every model of the script, the `data` folder is where decorations are saved with the JSON storage.
{% endhint %}
{% endstep %}

{% step %}

### Framework and inventory

Open `config.lua`, section 1:

```lua
Config.Framework = "esx" -- "esx", "qbcore" or "standalone"

Config.Inventory = "auto" -- "auto", "qb-inventory", "ox_inventory", "framework" or "none"

Config.MoneyAccount = "money" -- "money" (cash) or "bank"
```

| Framework          | Value          |
| ------------------ | -------------- |
| ESX                | `"esx"`        |
| QBCore / QBox      | `"qbcore"`     |
| Standalone / other | `"standalone"` |

| `Inventory`      | What it uses                                                                                                                                                           |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"auto"`         | Picks it on its own - ox\_inventory when it runs, the new qb-inventory on QBCore, otherwise the framework inventory. Standalone without ox\_inventory becomes `"none"` |
| `"qb-inventory"` | The **new** QBCore inventory (qb-inventory 2.0 and newer)                                                                                                              |
| `"ox_inventory"` | ox\_inventory on ESX, QBCore, QBox or standalone                                                                                                                       |
| `"framework"`    | ESX xPlayer or the **old** QBCore `Player.Functions` (old qb-inventory, lj-inventory, ps-inventory and most others)                                                    |
| `"none"`         | No items at all - players use the commands instead, see [Without an inventory](#without-an-inventory)                                                                  |

{% hint style="info" %}
Every item function is open in `server/other.lua`. Any other inventory is a few lines to add there.
{% endhint %}
{% endstep %}

{% step %}

### Items

| Server        | What to do                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------- |
| ESX           | Import `sql_ESX.sql` - the items and the decoration table                                         |
| QBCore        | Add the items to `qb-core/shared/items.lua` - the new and the old format are both in `Readme.txt` |
| ox\_inventory | Add the items to `ox_inventory/data/items.lua` - they are in `Readme.txt`                         |

Then copy the pictures from the `icons` folder into your inventory's image folder.

| Item                                                    | What it is                             |
| ------------------------------------------------------- | -------------------------------------- |
| `trickortreatsbucket`                                   | The trick or treat bucket              |
| `pumpkin`                                               | A picked pumpkin, ready to carve       |
| `flet` `lars` `papi` `picolo` `skiiles` `sneck` `cyrny` | The 7 candies                          |
| 35 decoration items                                     | See [Decorations](#the-35-decorations) |
| {% endstep %}                                           |                                        |

{% step %}

### Database

| `Config.Decorations.storage` | What it needs                                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------------------------ |
| `"mysql"`                    | `oxmysql` and the `halloweendecorations` table - in `sql_ESX.sql` or `sql_STANDALONE-QBCORE.sql` |
| `"json"`                     | Nothing - decorations are saved in `data/decorations.json`                                       |
| `false`                      | Nothing - decorations are gone after a restart                                                   |
| {% endstep %}                |                                                                                                  |

{% step %}

### Admins

The admin commands belong to whoever your `server.cfg` gives `halloween.admin` to:

```
add_ace group.admin halloween.admin allow
```

ESX groups, QBCore permissions and single players by identifier can be allowed too, see [Permissions](#permissions).
{% endstep %}
{% endstepper %}

## Trick or Treat

Use the bucket item and the bucket is in your hand. Every door is marked on the map - walk up to one and press `E` to knock. The neighbour opens the door and hands the candy over, and it lands in your bucket. Doors you already visited disappear from the map.

| Key         | Action                                                   |
| ----------- | -------------------------------------------------------- |
| `E`         | Knock on a marked door                                   |
| `BACKSPACE` | Put the bucket away - using the item again does the same |
| `X`         | Cancel                                                   |

### The bucket

The candy is physically added to the bucket in your hand - every candy has its own model, and every player around sees your bucket fill up. While the bucket is out, a card in the corner shows the candy in your bucket, how many houses are left and the key to put the bucket away.

```lua
Config.BucketHud = {
	enabled = true,
	position = "top-left" -- "top-left", "top-right", "bottom-left" or "bottom-right"
}
```

### Settings

```lua
Config.TrickOrTreat = {
	enabled = true,
	item = "trickortreatsbucket",
	distance = 2.5, -- How close to the door a player has to stand
	oneuse = false, -- true = every door gives candy only once for the whole server until a restart
	cooldown = 60, -- Minutes before the same player can knock on the same door again. 0 = once until a restart
	trickchance = 12, -- Percent chance the door plays a trick instead of giving candy. 0 = no tricks
	time = {
		enabled = false, -- true = only at the in-game hours below
		from = 18,
		to = 6
	}
}
```

### Tricks

With `trickchance` above 0, some doors play a trick - instead of candy the player gets a jumpscare and the bucket stays empty.

### Rewards

```lua
Config.TrickOrTreatRewards = {
	{type = "item", name = "flet", amount = 1, label = "Flet (Candy)", chance = 20},
	{type = "money", amount = 50, label = "$50", chance = 5},
	{type = "vip", label = "VIP for a day", chance = 1}
}
```

One reward is picked at random, `chance` is its weight - higher is more often.

| `type`        | What it gives                                                                            |
| ------------- | ---------------------------------------------------------------------------------------- |
| `"item"`      | `amount` of the item `name`                                                              |
| `"money"`     | `amount` of money to `Config.MoneyAccount`                                               |
| anything else | Fires `rtx_halloween:server:customReward` - give anything you like in `server/other.lua` |

### Doors

142 doors are in the config. Add your own - stand in a doorway, look out of the house and copy your position and heading:

```lua
Config.TrickOrTreatLocations = {
	{coords = vector3(1205.15, -557.82, 69.44), heading = 90.0}
}
```

The neighbour who opens the door is picked at random from `Config.TrickOrTreatPeds`.

## Pumpkins

61 pumpkins grow around the world. Walk up to one and press `E` to pick it up - you get the `pumpkin` item. A picked pumpkin grows back after a while.

```lua
Config.Pumpkins = {
	enabled = true,
	item = "pumpkin",
	time = 5, -- Seconds it takes to pick a pumpkin up
	distance = 2.5,
	respawn = 30, -- Minutes until a picked pumpkin grows back. 0 = never until a restart
	spawndistance = 80.0 -- Pumpkins are only spawned for players closer than this
}
```

Add your own spots to `Config.PumpkinLocations` - put them on the ground, they are placed on it on their own.

## Pumpkin Carving

Use the `pumpkin` item and pick a face - **Grin**, **Fangs** or **Spooky**.

### The minigame

The pumpkin appears right in front of you with the face drawn on it as a dotted stencil. Hold the left mouse button and run the knife along the dots - eyes, nose, mouth - and every finished part falls out of the real pumpkin. Carve clean for **3 stars**.

| Key   | Action                                       |
| ----- | -------------------------------------------- |
| `LMB` | Hold and run the knife along the dotted line |
| `ESC` | Cancel                                       |

```lua
Config.Carving = {
	enabled = true,
	minigame = {
		enabled = true, -- false = only a progress bar
		tolerance = 35, -- How far from the line the knife can be. 20 hard, 35 normal, 50 very easy
		time = 0, -- Seconds for the whole face. 0 = no limit
		breakable = false, -- true = too many slips or running out of time breaks the pumpkin
		slips = 3 -- How many slips before the pumpkin breaks
	},
	time = 10 -- Seconds the carving takes without the minigame
}
```

### The carved pumpkin

The carved pumpkin is a decoration item - place it anywhere in the world like any other decoration.

## Decorations

Decorate the outside of any house with our special object placement system.

### The decoration menu

```
/decorate
```

Opens a menu with a picture of every decoration you have and how many. Pick one and the placer opens. Using a decoration item from the inventory opens the placer straight away.

### The placer

A free camera opens - fly around the spot, move and turn the decoration with the gizmo, put it on the ground and place it.

| Key               | Action                               |
| ----------------- | ------------------------------------ |
| `RMB`             | Hold to look around and fly          |
| `W` `A` `S` `D`   | Fly                                  |
| `SPACE` / `SHIFT` | Up / down                            |
| **Move / Rotate** | Switch what the gizmo does           |
| **World / Local** | The axis of the gizmo                |
| **On the ground** | Drops the decoration onto the ground |
| **Place**         | Places the decoration                |

Fly speed, look speed and move and rotation snapping are sliders right in the placer.

### Settings

```lua
Config.Decorations = {
	enabled = true,
	storage = "mysql", -- "mysql", "json" or false
	limit = 30, -- Most decorations one player can have placed. 0 = no limit
	placedistance = 25.0, -- How far from the player a decoration can be placed
	renderdistance = 150.0, -- Decorations are only spawned for players closer than this
	returnitem = true, -- true = picking a decoration up gives the item back
	pickupdistance = 5.0
}
```

Decorations are kept after a restart - or, with `storage = false`, only until the restart. The owner picks his own back up with `/removedecoration` or the target option.

### The free decoration menu

`/decorate` with **every** decoration, and placing one costs no item. Made for standalone servers without an inventory, and it can be turned on for any server.

```lua
freemenu = {
	enabled = "auto", -- "auto" = only without an inventory, true = on any server, false = never
	access = "everyone", -- "everyone" or "permission"
	ace = "halloween.decorate",
	groups = {}, -- ESX groups / QBCore permissions, e.g. {"vip", "mod"}
	identifiers = {} -- Single players, by any identifier
}
```

With `access = "permission"` only the players you allow - and admins - get the free menu. Everybody else still gets the normal menu with their own items.

```
add_ace group.vip halloween.decorate allow
```

{% hint style="info" %}
Decorations placed from the free menu never give an item back when they are picked up.
{% endhint %}

### The 35 decorations

| Decoration                                     | Items                                                   |
| ---------------------------------------------- | ------------------------------------------------------- |
| Bats                                           | `bat_b` `bat_g` `bat_w`                                 |
| Cats                                           | `cat_b` `cat_g` `cat_w`                                 |
| Crows                                          | `crown_b` `crown_g` `crown_w`                           |
| Ghosts                                         | `ghost_b` `ghost_g` `ghost_w`                           |
| Crosses                                        | `krucifix_b` `krucifix_g` `krucifix_w`                  |
| Spiders                                        | `spider_b` `spider_g` `spider_w`                        |
| Witches                                        | `witch_b` `witch_g` `witch_w`                           |
| Carved pumpkins                                | `pumpkin_1` Grin, `pumpkin_2` Fangs, `pumpkin_3` Spooky |
| Cauldron, candy basket, hanging pot, pot stand | `bucket_1` `bucket_2` `bucket_3` `pot_handler`          |
| Coffin and coffin lid                          | `coffin` `coffin_door`                                  |
| Gravestone and skeleton grave                  | `grave` `skeleton_grave`                                |
| Skull and skull pile                           | `skull_1` `skull_2`                                     |
| Mummy                                          | `mumie`                                                 |

`_b` is dark, `_g` green, `_w` white.

{% hint style="warning" %}
The order of `Config.DecorationItems` is saved with every placed decoration. Never reorder or remove lines, only add new ones at the end.
{% endhint %}

### Your own decorations

Add a line to the end of `Config.DecorationItems` with your own prop:

```lua
{item = "my_decoration", label = "My Decoration", model = "prop_name", image = "my_decoration.png"}
```

## Candy

The 7 candies from the doors can be eaten - use one and the player eats it.

```lua
Config.Candy = {
	enabled = true,
	items = {"flet", "lars", "papi", "picolo", "skiiles", "sneck", "cyrny"},
	time = 4, -- Seconds eating takes
	hunger = 8, -- Percent of hunger one candy fills
	stress = 4 -- Percent of stress one candy takes away
}
```

Hunger works with ESX `esx_status` and QBCore metadata, stress with QBCore metadata. For any other status or HUD script, change `EatCandyRTX` in `server/other.lua`.

## Jumpscares

Scare your players during gameplay - a ghost with red eyes rushes at the camera with a scream.

```lua
Config.JumpScares = {
	random = true, -- Random jumpscares for every player
	interval = 90, -- Every this many seconds a jumpscare is rolled
	chance = 3, -- Percent chance on every roll. 0.5 is one in two hundred
	nightonly = false, -- true = only between 20:00 and 5:00 in-game
	vehicle = false, -- true = also while driving
	volume = 0.8
}
```

Admins scare a single player by id:

```
/scareplayer 12
```

## Interface & Interaction

```lua
Config.InterfaceStyle = "modern" -- "modern" = the new RTX style, "classic" = the look of the older versions
Config.InterfaceColor = "#ff6b1a" -- Accent colour of the whole interface
Config.InteractionSystem = 1
Config.PromptPosition = "right" -- "right", "center" or "left"
Config.Notifications = "rtx"
```

| `InteractionSystem` | Prompt                                         |
| ------------------- | ---------------------------------------------- |
| `1`                 | RTX prompt, matching the rest of the interface |
| `2`                 | 3D text                                        |
| `3`                 | GTA Online style help                          |
| `4`                 | Floating help text above the spot              |

`Config.Notifications = "rtx"` uses the built-in notifications. Anything else calls `Notify()` in `client/other.lua`, where your own notification system goes.

### Keys

```lua
Config.Keys = {
	interact = "E", -- Knock on a door, pick up a pumpkin
	putaway = "BACK" -- Put the bucket away
}

Config.Controls = {
	cancel = {id = 73, label = "X"} -- Stop picking up, carving or eating
}
```

{% hint style="info" %}
`E` and `BACKSPACE` are key mappings. Every player can rebind them in **Settings > Key Bindings > FiveM**.
{% endhint %}

### Target

```lua
Config.Target = true
Config.Targettype = "oxtarget" -- "oxtarget", "qbtarget" or "qtarget"
```

Doors, pumpkins and your own decorations get target options instead of the `E` prompt - decorations can then be picked up right from the target menu. The registering is in `client/other.lua`, open source.

## Sounds

```lua
Config.Sounds = {
	enabled = true,
	volume = 0.7,
	files = {
		knock = "cushion1",
		reward = "win",
		cut = "click",
		cutpart = "turn"
	}
}
```

Knocking, candy, pumpkins, carving, decorations and the whole interface. Every sound is a file in `html/sounds` - put your own `.ogg` files there and change the names.

## Player Checks

Nothing can be started while the player is dead or down, cuffed, in a vehicle, swimming, falling, ragdolled or in the pause menu.

```lua
Config.Checks = {
	cancelondeath = true, -- Dying or going down stops what the player is doing
	maxmove = 1.5, -- Moving further than this from where an action started cancels it
	servercheck = true -- The server checks the distance of every door, pumpkin and decoration on its own (OneSync)
}
```

How death and cuffs are detected is in `IsPlayerDeadRTX()` and `IsPlayerCuffedRTX()` in `client/other.lua`, open for your own ambulance and police scripts.

## Synchronization

The server owns everything - which doors a player already knocked on, which pumpkins are gone and when they grow back, every placed decoration and what is in every bucket. Every reward is checked on the server: distance, time, items and limits. Nothing a client sends is trusted.

No prop, pumpkin, decoration or neighbour is a networked entity, so the script runs on servers with `sv_entityLockdown "strict"` without any extra setup. Pumpkins and decorations are only spawned for players nearby.

## Without an Inventory

With `Config.Inventory = "none"`, standalone servers use commands instead of the items, and every door gives only money or custom rewards:

| Command         | What it does                                   |
| --------------- | ---------------------------------------------- |
| `/trickortreat` | Take the bucket out / put it away              |
| `/pumpkin`      | Carve a pumpkin                                |
| `/decorate`     | The free decoration menu with every decoration |

## Commands

| Command                            | Who       | What it does                                                   |
| ---------------------------------- | --------- | -------------------------------------------------------------- |
| `/decorate`                        | Everybody | The decoration menu                                            |
| `/removedecoration`                | Everybody | Pick up your own decoration closest to you                     |
| `/scareplayer [id]`                | Admins    | Scare a player                                                 |
| `/givedecorations [id] [amount]`   | Admins    | Every decoration item - without an id to yourself, one of each |
| `/clearnearbydecorations [metres]` | Admins    | Remove the decorations around you                              |
| `/cleardecorations`                | Admins    | Remove every decoration on the server                          |

```lua
Config.Commands = {
	removedecoration = "removedecoration",
	scare = "scareplayer",
	cleardecorations = "cleardecorations",
	clearnearby = "clearnearbydecorations",
	givedecorations = "givedecorations",
	decorate = "decorate",
	trickortreat = "trickortreat",
	carve = "pumpkin"
}
```

Rename any of them, or set it to `""` and it is never registered.

## Permissions

```lua
Config.AdminAce = "halloween.admin"

Config.Admins = {
	groups = {"admin", "superadmin", "god"}, -- ESX groups / QBCore permissions
	identifiers = {} -- Single players, by any identifier
}
```

A player can use the admin commands if **any** of these is true:

* he has the ACE `halloween.admin`
* his ESX group / QBCore permission is in `groups`
* one of his identifiers is in `identifiers`

Identifiers can be the ESX identifier, the QBCore citizenid, `license:`, `steam:`, `discord:` - or just the part after the colon.

## Language

Every line of text - notifications and the whole interface - is in `language/en.lua`, open source. Czech is included in `language/cs.lua`.

To add a language, copy `en.lua` (for example to `de.lua`), rename the block inside to `Language["German"]`, add the file to `fxmanifest.lua` and set:

```lua
Config.Language = "German"
```

## Open-Source Files

This product is protected by the Escrow System. You can still configure almost everything:

| File                                | What is in it                                                                        |
| ----------------------------------- | ------------------------------------------------------------------------------------ |
| `config.lua`                        | Everything configurable, fully commented                                             |
| `language/en.lua` `language/cs.lua` | Every text                                                                           |
| `client/other.lua`                  | Notifications, prompts, target, death and cuffed checks                              |
| `server/other.lua`                  | Items for every inventory, money, rewards, candy effects, admin checks, Discord logs |
| `html`                              | The interface and the sounds                                                         |

### Discord logs

Switched on in `server/other.lua`, in `LogsRTX`. The webhook lives there too - never put it in `config.lua`, that file is sent to every player.

## Exports & Events

### Client exports

```lua
exports.rtx_halloween:IsTrickOrTreating() -- true while the bucket is out
exports.rtx_halloween:IsHalloweenBusy() -- true while the player knocks, picks, carves, eats, places or has a Halloween menu open
exports.rtx_halloween:ScarePlayer() -- scares the player
```

### Server exports

```lua
exports.rtx_halloween:ScarePlayer(source) -- scares the player
exports.rtx_halloween:GetPlayerDecorationCount(source) -- how many decorations the player has placed
```

### Server events

```lua
AddEventHandler("rtx_halloween:server:treated", function(source, door, reward) end)
AddEventHandler("rtx_halloween:server:tricked", function(source, door) end)
AddEventHandler("rtx_halloween:server:candyEaten", function(source, item) end)
AddEventHandler("rtx_halloween:server:customReward", function(source, reward) end)
```

## Updating from 10.x

{% stepper %}
{% step %}

### Back up and replace

Back up your `config.lua`, then replace the whole `rtx_halloween` folder.
{% endstep %}

{% step %}

### Set your settings

Set your settings again in the new `config.lua` - it is sorted into sections now.
{% endstep %}

{% step %}

### Keep placed decorations

Your placed decorations stay, the database table is the same.
{% endstep %}

{% step %}

### Delete old files

Delete the old files `language/main.lua`, `html/howler.core.js` and `html/debounce.min.js`, they are not used anymore.
{% endstep %}

{% step %}

### oxmysql

`oxmysql` is used directly, there is no MySQL line to edit in `fxmanifest.lua` anymore.
{% endstep %}
{% endstepper %}

## Troubleshooting

<details>

<summary>Items are not given or taken on QBCore</summary>

Your QBCore uses the new qb-inventory. Leave `Config.Inventory = "auto"` or set it to `"qb-inventory"`.

</details>

<details>

<summary>The decorations are gone after a restart</summary>

Check `Config.Decorations.storage`. With `"mysql"` the `halloweendecorations` table has to be imported, with `"json"` keep the `data` folder when you update the resource. `false` never saves them.

</details>

<details>

<summary>/decorate says I have no decorations</summary>

With an inventory the menu shows only the decoration items you have. Get them with `/givedecorations`, or turn on the free menu with `Config.Decorations.freemenu.enabled = true`.

</details>

<details>

<summary>The admin commands say I am not allowed</summary>

Check the ACE in `server.cfg`, `Config.Admins.groups` and `Config.Admins.identifiers`. Any one of them is enough.

</details>

<details>

<summary>Nothing happens at a door</summary>

Take the bucket out first. The door may also be on cooldown for you (`Config.TrickOrTreat.cooldown`), or trick or treating is limited to certain hours (`Config.TrickOrTreat.time`).

</details>

<details>

<summary>The models do not show up</summary>

The `stream` folder is missing or was renamed. Put it back and restart the server - streamed models are only picked up by players who connect after the restart.

</details>

<details>

<summary>Target does not work</summary>

`Config.Target = true` needs the target resource running. If it is not, the console says so at startup.

</details>

<details>

<summary>A player who died can still knock or carve</summary>

Your ambulance script uses a death state the script does not know yet. Add it to `IsPlayerDeadRTX()` in `client/other.lua`.

</details>

## Support

If you need help with installation, configuration or have any questions regarding this resource, feel free to contact us on our Discord server:

[Join our Discord](https://discord.gg/rtxdev)
