# Easter Egg Hunt

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

## Download

[Download this resource](https://rtx.tebex.io/package/7372909)

## Installation

{% hint style="info" %}
**Framework compatibility**

This resource is **standalone** and works on any FiveM server.

Compatible with **ESX**, **QBCore**, **QBox**, **vRP**, and other frameworks.

If you are using a framework other than ESX, QBCore, or QBox, follow the **Standalone** installation instructions.
{% endhint %}

### Standalone

{% stepper %}
{% step %}

### Standalone installation

* Put the `rtx_easter` folder into your `resources`.
* Open `config.lua`.
* Configure your `config.lua` to your preferences.
* Add `rtx_easter` to your `server.cfg`.
  {% endstep %}
  {% endstepper %}

### QBCore

{% stepper %}
{% step %}

### QBCore installation

* Put the `rtx_easter` folder into your `resources`.
* Open `config.lua`.
* Replace `Config.Framework = "standalone"` with `Config.Framework = "qbcore"`.
* Configure your `config.lua` to your preferences.
* Add `rtx_easter` to your `server.cfg`.
  {% endstep %}
  {% endstepper %}

### ESX

{% stepper %}
{% step %}

### ESX installation

* Put the `rtx_easter` folder into your `resources`.
* Open `config.lua`.
* Replace `Config.Framework = "standalone"` with `Config.Framework = "esx"`.
* Configure your `config.lua` to your preferences.
* Add `rtx_easter` to your `server.cfg`.
  {% endstep %}
  {% endstepper %}

### Items Setup

Navigate to the `[Items]` folder located in the main package and install the items based on your framework.

***

#### QBCore / OX Inventory

Copy the provided item definitions into your inventory items file.

{% hint style="info" %}
Make sure to restart your server after adding the items
{% endhint %}

***

#### ESX

Import the included SQL file into your database.

{% hint style="info" %}
This will automatically register all required items.
{% endhint %}

***

## Config Preview

<details>

<summary>Show Config</summary>

```lua
Config = {}

Config.Framework = "standalone"  -- Supported frameworks: standalone, qbcore, esx

Config.ESXFramework = {
	newversion = true, -- Set true if using newer ESX version (export-based instead of getSharedObject event)
	getsharedobject = "esx:getSharedObject", -- Event name for getting ESX object (only for old ESX)
	resourcename = "es_extended" -- Name of ESX resource
}

Config.QBCoreFrameworkResourceName = "qb-core" -- Name of qb-core resource (change if renamed)

Config.OxInventory = false -- Enable this if you are using ox_inventory instead of default inventory system

Config.InterfaceColor = "#ff66ff" -- UI theme color in HEX format (e.g. #ff66ff)

Config.Language = "English" -- UI language used by the script (English)

Config.Target = false -- Enable target-based interaction (true/false)

Config.Targettype = "oxtarget" -- Target system type: qtarget, qbtarget, oxtarget

Config.TargetSystemsNames = {qtarget = "qtarget", qbtarget = "qb-target", oxtarget = "ox_target"} -- target resource names

Config.TargetIcons = {sellicon = "fa-solid fa-bars-progress", eggicon = "fa-solid fa-bowling-ball"} 

Config.EasterInteractionSystem = 1 -- Interaction style: 1 = Custom interaction, 2 = 3D Text, 3 = GTA Online style, 4 = Floating Text Box Style

Config.TakeEggKey = "e" -- Key used to pick up eggs

Config.EggRenderDistance = 500.0 -- Maximum distance at which eggs are rendered

Config.EggInteractDistance = 2.5 -- Distance required to interact with an egg

Config.RewardDuration = 5000 -- Duration (ms) for showing reward notification

Config.SoundEffects = true -- Enable or disable UI/action sound effects

Config.SoundEffectsVolume = 0.1 -- Volume of sound effects (0.0 - 1.0)

Config.LeaderBoard = true -- Enable or disable leaderboard system

Config.LeaderBoardCommand = "easter" -- Command to open leaderboard

Config.LeaderBoardLimit = 50 -- Maximum number of players shown in leaderboard

Config.EggShop = true -- Enable or disable egg shop system

Config.EggShopByCommand = true -- Allow opening egg shop via command

Config.EggShopCommand = "eggshop" -- Command to open egg shop

Config.EggShopSellLocation = true -- Enable physical sell locations for eggs

Config.EggShopTraderPed = true -- Spawn NPC trader at sell locations

Config.SellEggKey = "e" -- Key used to sell eggs at trader

Config.EggShopBlipSetttings = {
	enabled = true, -- Show egg buyer locations on map
	blipiconid = 52, -- Blip icon ID
	blipdisplay = 4, -- Blip display type
	blipcolor = 2, -- Blip color ID
	blipshortrange = true, -- Only show blip when nearby
	blipscale = 1.0, -- Blip size scale
	bliptext = "Easter Buyer", -- Blip name displayed on map
}

Config.EggBlipSetttings = {
	enabled = true, -- Show eggs on map
	blipiconid = 1, -- Blip icon ID
	blipdisplay = 4, -- Blip display type
	blipcolor = 2, -- Blip color ID
	blipshortrange = true, -- Only show blip when nearby
	blipscale = 0.75, -- Blip size scale
	bliptext = "Egg", -- Blip name displayed on map
}

Config.EggTraderLocations = { 	
	[1] = { 
		pedmodel = "ig_cletus", -- NPC model name
		coords = vector3(-41.15, -226.55, 44.79), -- NPC spawn position
		heading = 77.0, -- NPC facing direction
		npchandler = nil, -- Runtime handler (do not edit)
		anim = {dict = "missclothing", name = "idle_storeclerk"}, -- NPC idle animation
	},
}

Config.RarityWeights = {
	common = 40, -- Most common eggs (highest spawn chance)
	uncommon = 25, -- Slightly rarer eggs
	rare = 15, -- Rare eggs
	epic = 10, -- Very rare eggs
	legendary = 7, -- Extremely rare eggs
	mythic = 3, -- Ultra rare eggs (lowest chance)
}

Config.EggsTypes = {
	["meadow"] = { 
		object = "rtx_easter_egg01", -- World object model for this egg
		itemname = "easter_egg_1", -- Inventory item name
		label = "Meadow Nest Egg", -- Display name in UI
		price = 10, -- Sell price per egg
		rarity = "common", -- Egg rarity (used for spawn chance & sorting)
	},

	["sunrise"] = { 
		object = "rtx_easter_egg02", -- World object model for this egg
		itemname = "easter_egg_2", -- Inventory item name
		label = "Sunrise Blossom Egg", -- Display name in UI
		price = 25, -- Sell price per egg
		rarity = "uncommon", -- Egg rarity (used for spawn chance & sorting)
	},

	["royal_blue"] = { 
		object = "rtx_easter_egg03", -- World object model for this egg
		itemname = "easter_egg_3", -- Inventory item name
		label = "Royal Garden Egg", -- Display name in UI
		price = 50, -- Sell price per egg
		rarity = "rare", -- Egg rarity (used for spawn chance & sorting)
	},

	["spring_bloom"] = { 
		object = "rtx_easter_egg04", -- World object model for this egg
		itemname = "easter_egg_4", -- Inventory item name
		label = "Spring Bloom Egg", -- Display name in UI
		price = 75, -- Sell price per egg
		rarity = "rare", -- Egg rarity (used for spawn chance & sorting)
	},

	["bunny_nest"] = { 
		object = "rtx_easter_egg05", -- World object model for this egg
		itemname = "easter_egg_5", -- Inventory item name
		label = "Bunny Nest Egg", -- Display name in UI
		price = 120, -- Sell price per egg
		rarity = "epic", -- Egg rarity (used for spawn chance & sorting)
	},

	["floral_delight"] = { 
		object = "rtx_easter_egg06", -- World object model for this egg
		itemname = "easter_egg_6", -- Inventory item name
		label = "Floral Delight Egg", -- Display name in UI
		price = 180, -- Sell price per egg
		rarity = "epic", -- Egg rarity (used for spawn chance & sorting)
	},

	["golden_garden"] = { 
		object = "rtx_easter_egg07", -- World object model for this egg
		itemname = "easter_egg_7", -- Inventory item name
		label = "Golden Garden Egg", -- Display name in UI
		price = 300, -- Sell price per egg
		rarity = "legendary", -- Egg rarity (used for spawn chance & sorting)
	},

	["forest_song"] = { 
		object = "rtx_easter_egg08", -- World object model for this egg
		itemname = "easter_egg_8", -- Inventory item name
		label = "Forest Song Egg", -- Display name in UI
		price = 450, -- Sell price per egg
		rarity = "mythic", -- Egg rarity (used for spawn chance & sorting)
	},
}

Config.EggsLocations = {
	-- Egg spawn locations
	-- Each entry represents a possible spawn point for an egg in the world.
	-- The system will randomly assign an egg type (based on rarity) to each location.
	-- "coords" defines the exact world position where the egg will spawn.
	-- "rotation" defines the object rotation (usually keep 0.0 unless needed).
	-- You can add/remove locations freely to control spawn density and map coverage.
	{coords = vector3(256.81, -828.36,28.63), rotation = vector3(0.0, 0.0, 0.0)},
	{coords = vector3(179.45, -941.72,29.09), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(181.61, -968.99,28.57), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(206.57, -1005.51,28.29), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(186.13, -1049.46,29.6), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(181.63, -1047.63,31.22), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(152.73, -1046.78,28.27), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(46.85, -1073.34,29.46), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(42.03, -998.3,28.36), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-21.59, -1002.39,28.5), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-32.42, -1166.76,25.06), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-74.3, -1203.55,26.66), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-43.48, -1238.48,28.33), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(15.8, -1208.47,30.05), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(2.57, -1215.15,26.05), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(20.0, -1314.36,28.57), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-27.49, -1307.25,28.6), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-52.54, -1332.72,28.62), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(11.95, -1405.77,33.53), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(68.86, -1391.07,33.95), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(263.23, -1332.6,32.48), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(335.15, -1432.19,45.59), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(401.24, -1349.12,44.15), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(467.15, -1186.94,28.22), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(339.26, -1188.23,28.51), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(247.04, -1204.35,28.42), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-1042.6, -2772.4,3.63), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-984.34, -2640.8,13.96), rotation = vector3(0.0, 0.0, 0.0)},  
	{coords = vector3(-928.71, -2544.0,14.53), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-697.77, -2112.89,5.21), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-491.22, -1029.85,51.49), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-480.86, -1041.86,28.12), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-275.27, -777.16,52.27), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-143.23, -845.02,29.81), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(37.62, -904.21,29.55), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(301.82, -671.11,47.21), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(468.75, -662.78,23.75), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(499.24, -656.81,23.89), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(847.5, -1142.47,23.44), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(833.33, -1170.47,24.26), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(175.51, -1114.52,28.3), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(180.4, -1122.7,28.29), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(281.8, -1020.13,50.38), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(303.43, -964.71,43.98), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(269.48, -1101.83,88.57), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(577.35, -1255.14,9.28), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(623.41, -649.02,12.94), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(583.93, -417.65,23.72), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(363.69, -314.49,45.72), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(282.35, -218.73,60.78), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-199.87, 182.23,79.31), rotation = vector3(0.0, 0.0, 0.0)},	
	{coords = vector3(-50.52, -1660.98,28.29), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-45.92, -1667.3,35.62), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(64.22, -1852.37,21.84), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(105.24, -1900.11,20.07), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(182.69, -1918.69,21.36), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(241.03, -1858.24,25.83), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(284.91, -1772.62,27.06), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(556.28, -1639.37,27.15), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(943.31, -1721.48,29.52), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(1007.24, -1739.31,46.49), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(1001.2, -1572.92,29.75), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(1125.64, -799.51,57.13), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(101.33, 185.11,115.54), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-50.5, 78.75,70.58), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-119.46, -438.61,35.43), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-157.88, -739.84,43.46), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-171.59, -1003.72,295.2), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-1430.59, -1508.6,2.71), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-1701.67, -1126.14,12.98), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-1652.34, -1138.98,13.17), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-1632.23, -1039.48,12.12), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-153.34, -1099.15,12.19), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-130.8, -993.86,72.37), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(286.9, -1022.38,85.98), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(480.16, -566.41,27.91), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(530.21, -452.24,23.91), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(756.22, -558.06,32.67), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(942.49, -143.99,26.17), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(623.41, -394.22,4.79), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(147.72, -587.91,16.81), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-183.68, -659.43,33.0), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-1785.59, 3000.51,31.89), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(501.72, 5603.83,796.91), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(454.42, 5571.63,780.47), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-757.61, 5594.37,35.82), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-552.41, -1683.12,18.49), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(-606.39, -1630.3,40.04), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(71.56, -361.2,101.55), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(562.82, -3120.91,17.76), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(503.02, -3336.96,25.96), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(155.79, -3142.32,5.98), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(694.83, -2698.84,5.05), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(704.28, -1254.81,25.35), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(884.83, -952.38,43.11), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(1250.95, -1113.87,30.15), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(1511.87, -1019.33,50.77), rotation = vector3(0.0, 0.0, 0.0)}, 
	{coords = vector3(1280.68, -1605.21,53.82), rotation = vector3(0.0, 0.0, 0.0)},
	{coords = vector3(479.38, -1301.58,28.32), rotation = vector3(0.0, 0.0, 0.0)},
}
function Notify(text)
	exports["rtx_notify"]:Notify("Easter", text, 5000, "info") -- if you get error in this line its because you dont use our notify system buy it here https://rtx.tebex.io/package/5402098 or you can use some other notify system just replace this notify line with your notify system
	--exports["mythic_notify"]:SendAlert("inform", text, 5000)
end
```

</details>

***

## Tips

#### Interaction System

You can choose between multiple interaction styles:

```lua
Config.EasterInteractionSystem = 1
```

* `1` = Custom interaction
* `2` = 3D Text
* `3` = GTA Online style
* `4` = Floating text U

***

#### Egg Spawn System

Eggs are automatically generated based on rarity weights:

```lua
Config.RarityWeights = {
	common = 40,
	uncommon = 25,
	rare = 15,
	epic = 10,
	legendary = 7,
	mythic = 3,
}
```

{% hint style="info" %}
Higher value = higher spawn chance. You can add custom rarities if needed
{% endhint %}

***

#### Egg Locations

Eggs spawn at defined coordinates:

```lua
Config.EggsLocations = { ... }
```

{% hint style="info" %}
Add more locations to increase spawn density \
Spread locations across the map for better gameplay
{% endhint %}

***

#### Leaderboard System

```lua
Config.LeaderBoard = true
```

* Tracks collected eggs
* Displays top players

***

#### Egg Shop & Selling

```lua
Config.EggShop = true
```

Players can sell eggs:

* Via NPC trader
* Via command

{% hint style="info" %}
Disable NPC if you want command-only system
{% endhint %}

***

## Notes

The script is designed to be highly flexible and fully customizable. All framework-related functions are editable, allowing you to easily adapt the script to your own server logic.

Most core systems can be modified, and you are free to implement your own logic, interaction system, target system, or any other custom features based on your needs.

The script also includes a language file, making it easy to translate and customize all texts.

## 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)