> 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/easter-event/configuration.md). # Configuration Every option in config/shared.lua and config/server.lua. The settings are split into two files: | File | Loaded on | Holds | | ------------------- | ----------------- | --------------------------------------- | | `config/shared.lua` | Server and client | Gameplay, zones, loot, keys, blips | | `config/server.lua` | Server only | Admin groups (ESX) and Discord webhooks | Restart the resource after changing a config file. ## General ```lua Config.Debug = false Config.Locale = 'en' ``` | Option | Default | Description | | --------------- | ------- | ------------------------------------------------------------------------------------------ | | `Config.Debug` | `false` | Prints extra information to the console: every spawn, periodic saves, failed webhooks. | | `Config.Locale` | `'en'` | Language file from `locales/`: `en`, `pl`, `de`, `cs`, `es`, `fr`, `it`, `sv` or your own. | ## Item images ```lua Config.ItemImagePath = Config.ItemFallbackImagePath = 'nui://kossek_easter/web/dist/images/' ``` | Option | Description | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Config.ItemImagePath` | Folder with item images, used in the case opening and the admin panel. Detected for ox\_inventory, qb-inventory, qs-inventory, ps-inventory, lj-inventory and ak47. Replace it with your own path if needed, or with an empty string to hide images. | | `Config.ItemFallbackImagePath` | Second folder to try when an image is not found in the first one. Put the missing images into `web/dist/images/` of this resource. An empty string turns the fallback off. | ## Items ```lua Config.Items = { egg_common = 'easter_egg_common', egg_rare = 'easter_egg_rare', eggshell = 'easter_eggshell', } ``` Change the values only if you registered the items under other names. ## Passive drop ```lua Config.PassiveDrop = { defaultChance = 15, cooldown = 300, } ``` Used by the `rollEasterDrop` export. See [Exports](/docs/scripts/easter-event/exports.md). | Option | Default | Description | | --------------- | ------- | -------------------------------------------------------- | | `defaultChance` | `15` | Chance in percent when the caller does not pass its own. | | `cooldown` | `300` | Seconds a player waits after a drop before the next one. | ## Keybinds ```lua Config.Keybinds = { tackle = 'E', basket = 'G', adminPanel = 'F10', } ``` | Option | Default | Description | | ------------ | ------- | ------------------------------------------------- | | `tackle` | `E` | Trader, egg pickup, rabbit catch and boss attack. | | `basket` | `G` | Take out or put away the basket inside a zone. | | `adminPanel` | `F10` | Open or close the admin panel. | These are default keys. A player who already joined with the old defaults keeps them until they change the binding in the GTA settings. ## Blips ```lua Config.Blips = { category = 14, categoryName = 'Easter Event', } ``` All event blips (zones, boss, trader) are grouped under one entry in the map legend. | Option | Default | Description | | -------------- | ---------------- | --------------------------------------------------------------------------- | | `category` | `14` | Blip category number. Change it if another script already uses category 14. | | `categoryName` | `'Easter Event'` | Name of the group in the map legend. | ## Basket ```lua Config.Basket = { models = { `bzzz_event_easter_basket_b` }, bone = 57005, offset = vec3(0.39, -0.005, -0.054), rotation = vec3(0.83, -85.85, -34.05), } ``` | Option | Description | | -------------------- | -------------------------------------------------------------------------- | | `models` | Basket props. One is picked at random each time a player takes the basket. | | `bone` | Ped bone the basket is attached to. 57005 is the right hand. | | `offset`, `rotation` | Position of the prop relative to the bone. | ## Spawner ```lua Config.Spawner = { enabled = true, cronSchedule = '*/30 * * * *', rabbitModel = `a_c_rabbit_01`, rabbitChance = 30, maxActive = 80, maxPerZone = 10, spawnBatch = { min = 5, max = 16 }, spawnMode = 'focused', despawnTime = 600, collectRange = 1.5, eggModels = { ... }, zoneBlips = { ... }, lateRevealBlips = { ... }, zones = { ... }, } ``` | Option | Default | Description | | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------- | | `enabled` | `true` | Turns the scheduled spawner on or off. Manual spawns from the admin panel still work when it is off. | | `cronSchedule` | every 30 min | When a spawn tick runs, in cron syntax (`minute hour day month weekday`). | | `rabbitModel` | rabbit | Ped model of the rabbits. | | `rabbitChance` | `30` | Chance in percent that a spawn is a rabbit instead of an egg. | | `maxActive` | `80` | Most eggs and rabbits that can exist at once on the whole map. A tick is skipped when the limit is reached. | | `maxPerZone` | `10` | Most eggs and rabbits in one zone. | | `spawnBatch` | 5 to 16 | How many objects one tick spawns. A random number between `min` and `max`. | | `spawnMode` | `'focused'` | How a batch is spread over the zones. See below. | | `despawnTime` | `600` | Seconds until an object that nobody collected disappears. | | `collectRange` | `1.5` | Distance in metres at which an egg can be picked up. | | `eggModels` | five egg props | Egg props. One is picked at random for every egg. | Cron examples: | Schedule | Meaning | | ------------------ | ---------------------------------------- | | `*/10 * * * *` | Every 10 minutes | | `0 * * * *` | Every hour, on the hour | | `0 */2 * * *` | Every 2 hours | | `*/15 18-23 * * *` | Every 15 minutes between 18:00 and 23:59 | The full syntax is described in the [ox\_lib cron documentation](https://coxdocs.dev/ox_lib/Modules/Cron/Server). ### Spawn mode | Value | Behaviour | | --------------- | ------------------------------------------------------------------------------------------------------------- | | `'focused'` | The whole batch goes to one zone, picked at random from the zones that are not full. One hotspot per tick. | | `'distributed'` | The batch is split evenly over all zones that are not full. With 8 zones and a batch of 16, each zone gets 2. | Keep `maxActive` at `maxPerZone` times the number of zones or higher, otherwise the global limit is hit before the zones fill up. ### Zones ```lua zones = { { label = 'Golf Course', center = vec3(-1177.15, 57.0, 54.4), radius = 70.0 }, { label = 'Skate Park', center = vec3(-920.26, -764.9, 30.0), radius = 70.0 }, -- ... }, ``` | Field | Description | | -------- | --------------------------------------------------------------------------------- | | `label` | Name shown on the map, in the notification and in the admin panel. | | `center` | Centre of the zone. Objects are placed on the ground at a random point around it. | | `radius` | Radius in metres. | Eight zones are included. Add, remove or move them freely. Pick open areas: objects are placed at random points inside the circle, so a zone that covers buildings or water gives eggs in places players cannot reach. ### Zone blips ```lua zoneBlips = { enabled = true, color = 5, alpha = 96, shortRange = true, showLabel = true, sprite = 52, scale = 0.7, }, ``` | Option | Default | Description | | ------------ | ------- | ---------------------------------------------------------- | | `enabled` | `true` | Show a blip for every zone that has objects in it. | | `color` | `5` | Blip colour of the radius and the label. | | `alpha` | `96` | Opacity of the radius, 0 to 255. | | `shortRange` | `true` | Show the blip on the minimap only when the player is near. | | `showLabel` | `true` | Add an icon with the zone name in the centre. | | `sprite` | `52` | Icon of the label blip. | | `scale` | `0.7` | Size of the label blip. | ### Late reveal blips ```lua lateRevealBlips = { enabled = true, beforeDespawn = 300, sprite = 1, color = 5, scale = 0.55, alpha = 220, shortRange = true, }, ``` Shortly before an uncollected object despawns, it is marked with a dot for players inside its zone. | Option | Default | Description | | --------------- | ------- | ---------------------------------------------------------- | | `enabled` | `true` | Turn the reveal on or off. | | `beforeDespawn` | `300` | How many seconds before the despawn the dot appears. | | `sprite` | `1` | Blip icon. | | `color` | `5` | Blip colour for eggs. Rabbits always use colour 10. | | `scale` | `0.55` | Blip size. | | `alpha` | `220` | Opacity, 0 to 255. | | `shortRange` | `true` | Show the blip on the minimap only when the player is near. | ## Egg pickup ```lua Config.EggPickup = { anim = { dict = 'pickup_object', name = 'pickup_low' }, duration = 1200, } ``` | Option | Default | Description | | ---------- | ------- | ----------------------------------------------- | | `anim` | | Animation played when a player picks up an egg. | | `duration` | `1200` | Length of the animation in milliseconds. | ## Rabbit ```lua Config.Rabbit = { fleeSpeed = 4.0, tackleRange = 2.5, tackleCooldown = 5, tackleAnim = { dict = 'missmic2ig_11', name = 'mic_2_ig_11_intro_goon' }, reward = 'easter_egg_rare', } ``` | Option | Default | Description | | ---------------- | ------------------- | --------------------------------------------------------------------- | | `fleeSpeed` | `4.0` | Movement speed multiplier of a fleeing rabbit. | | `tackleRange` | `2.5` | Distance in metres at which a rabbit can be caught. | | `tackleCooldown` | `5` | Seconds a player waits after a catch before catching the next rabbit. | | `tackleAnim` | | Animation played on a catch attempt. | | `reward` | `'easter_egg_rare'` | Item given for a caught rabbit. One piece. | ## Incubation ```lua Config.Incubation = { enabled = true, requiredTime = 60, metaKey = 'easter_incubation', minSpeed = 150.0, speedUnit = 'kmh', } ``` | Option | Default | Description | | -------------- | --------------------- | ---------------------------------------------------------------------------------------------- | | `enabled` | `true` | With `false` there is no incubation: an egg can be opened as soon as the player has it. | | `requiredTime` | `60` | Seconds above the minimum speed needed to incubate one egg. | | `metaKey` | `'easter_incubation'` | Name of the field that stores the progress in the item data. Do not change it during an event. | | `minSpeed` | `150.0` | Vehicle speed at which the timer runs. | | `speedUnit` | `'kmh'` | Unit of `minSpeed`: `'kmh'` or `'mph'`. | ## Loot `Config.EggLoot` and `Config.RarityColors` are described in [Loot Tables](/docs/scripts/easter-event/loot-tables.md). ## Boss ```lua Config.Boss = { cronSchedule = '*/30 * * * *', interval = 1800, health = 10, model = `a_c_rabbit_01`, fleeSpeed = 6.0, tackleRange = 3.0, tackleAnim = { dict = 'move_fall', name = 'fall_front' }, dropPerHit = { item = Config.Items.egg_common, count = 1 }, lastHitReward = { item = Config.Items.egg_rare, count = 3 }, spawnLocations = { { label = 'Vinewood Sign', coords = vec3(725.0, 1198.0, 326.0) }, { label = 'LSIA Runway', coords = vec3(-1336.0, -3044.0, 13.0) }, -- ... }, blip = { sprite = 442, color = 5, scale = 1.2, label = 'Boss' }, } ``` | Option | Default | Description | | ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `cronSchedule` | every 30 min | When the boss spawns, in cron syntax. Nothing happens if the previous boss is still alive. | | `interval` | `1800` | Seconds between spawns. Only used for the countdown in the admin panel and after a kill, so keep it in line with `cronSchedule`. | | `health` | `10` | Number of hits the boss takes. | | `model` | rabbit | Ped model of the boss. | | `fleeSpeed` | `6.0` | Movement speed multiplier of the boss. | | `tackleRange` | `3.0` | Distance in metres at which the boss can be hit. | | `tackleAnim` | | Animation played when a player hits the boss. | | `dropPerHit` | 1 common egg | Item and count given to the attacker for every hit. | | `lastHitReward` | 3 rare eggs | Item and count given to the player who lands the last hit. | | `spawnLocations` | four locations | Places where the boss can appear. One is picked at random. `label` is for your own reference. | | `blip` | | Icon, colour, size and name of the boss blip. | A player can hit the boss once every 2 seconds. This limit is fixed. ### Boss marker ```lua Config.BossMarker = { enabled = true, type = 0, hideRange = 10.0, offsetZ = 2.5, size = 0.8, color = { r = 56, g = 239, b = 125, a = 200 }, bobUpDown = true, faceCamera = false, rotate = true, } ``` | Option | Default | Description | | ------------ | ------- | --------------------------------------------------------- | | `enabled` | `true` | Draw a marker above the boss. | | `type` | `0` | GTA marker type. | | `hideRange` | `10.0` | The marker is hidden when the player is closer than this. | | `offsetZ` | `2.5` | Height of the marker above the boss. | | `size` | `0.8` | Marker size. | | `color` | green | Marker colour and opacity. | | `bobUpDown` | `true` | The marker moves up and down. | | `faceCamera` | `false` | The marker always faces the camera. | | `rotate` | `true` | The marker spins. | ## Eggshell trader ```lua Config.Pity = { shellsRequired = 100, reward = { item = Config.Items.egg_rare, count = 1 }, npc = { model = `cs_old_man2`, coords = vec4(2564.3425, 4680.3242, 33.1267, 47.1851), label = 'Trader', blip = { sprite = 480, color = 2, scale = 0.8, label = 'Trader' }, decorProps = { ... }, }, } ``` | Option | Default | Description | | ---------------- | ------------ | ------------------------------------------------------------------------------------------------------- | | `shellsRequired` | `100` | Eggshells taken for one exchange. | | `reward` | 1 rare egg | Item and count given for one exchange. | | `npc.model` | old man | Ped model of the trader. | | `npc.coords` | | Position and heading. The Z value is the ground level, so take about 0.95 off the Z of your own coords. | | `npc.label` | `'Trader'` | Name shown in the interaction prompt. | | `npc.blip` | | Icon, colour, size and name of the trader blip. | | `npc.decorProps` | eleven props | Decorations placed around the trader. | Each decoration has a `model`, an `offset` from the trader (right, forward, up) and a `rotation`. Empty the list to have no decorations. ## Case opening ```lua Config.CaseOpening = { stripLength = 40, winnerRange = { 30, 35 }, animDuration = 5000, } ``` | Option | Default | Description | | -------------- | ------------ | --------------------------------------------------------------------------------- | | `stripLength` | `40` | Number of items on the roulette strip. | | `winnerRange` | `{ 30, 35 }` | Positions on the strip where the prize can land. Has to stay below `stripLength`. | | `animDuration` | `5000` | Length of the spin in milliseconds. | ## Scoreboard ```lua Config.Scoreboard = { enabled = true, refreshRate = 30, renderDistance = 60.0, nameSource = 'steam', coords = vec3(2563.4021, 4679.4722, 34.4500), heading = 13.0, width = 1.4, height = 2.0, } ``` | Option | Default | Description | | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `enabled` | `true` | Show the board in the world. | | `refreshRate` | `30` | Seconds between data refreshes. | | `renderDistance` | `60.0` | The board is drawn for players closer than this, in metres. | | `nameSource` | `'steam'` | `'steam'` shows the FiveM player name. `'character'` shows the character name for players who are online; offline players keep their FiveM name. | | `coords` | | Centre of the board. | | `heading` | `13.0` | Direction the board faces, in degrees. | | `width`, `height` | 1.4 x 2.0 | Size of the board in metres. | You do not have to find the values by hand. The `/scoreboardedit` command lets an admin move the board in game and prints the result. See [Admin Panel](/docs/scripts/easter-event/admin-panel.md). ## Server config `config/server.lua` is never sent to players. ```lua Config.AdminGroups = { 'admin', 'superadmin', 'god' } Config.Webhooks = { rareDrop = '', bossKill = '', adminLog = '', } ``` | Option | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `Config.AdminGroups` | ESX groups with access to the admin panel and commands. Not used on QBCore and QBX, see [Installation](/docs/scripts/easter-event/installation.md). | | `Config.Webhooks` | Discord webhook URLs. See [Discord Webhooks](/docs/scripts/easter-event/discord-webhooks.md). |