> 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/installation.md).

# Installation

Requirements, items, start order and admin access.

## Requirements

| Resource                                           | Required | Notes                                                                                                         |
| -------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| [ox\_lib](https://github.com/overextended/ox_lib)  | Yes      | UI, callbacks, zones, cron, locales                                                                           |
| [oxmysql](https://github.com/overextended/oxmysql) | Yes      | Database                                                                                                      |
| ESX, QBCore or QBX                                 | Yes      | Detected automatically on start. There is no standalone mode.                                                 |
| An inventory                                       | Yes      | ox\_inventory, qb-inventory, qs-inventory, ps-inventory, lj-inventory, ak47\_inventory or ak47\_qb\_inventory |
| OneSync                                            | Yes      | The boss rabbit is created by the server.                                                                     |

How each inventory handles incubation is described in [Framework Bridge](/docs/scripts/easter-event/framework-bridge.md).

## Install

{% stepper %}
{% step %}

### Download the resource

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

{% step %}

### Add it to your server

Put the `kossek_easter` folder into your `resources` directory. Keep the folder name: the item image fallback path in the config points at `kossek_easter`.
{% endstep %}

{% step %}

### Add the items

The event uses three items:

| Item name           | What it is                                     |
| ------------------- | ---------------------------------------------- |
| `easter_egg_common` | Common egg. Usable.                            |
| `easter_egg_rare`   | Rare egg. Usable.                              |
| `easter_eggshell`   | Eggshell, exchanged at the trader. Not usable. |

The `__INSTALL/` folder has a ready item list for each inventory. Copy the three entries from the matching file into your inventory's item list:

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

For any other inventory, register the three items the way that inventory expects.

The ready files already set what the event needs. Keep it that way if you edit the entries:

* `easter_eggshell` stacks. The trader asks for 100 of them, so the ox\_inventory file has `stack = true` for this item.
* The two egg items do not stack: `stack = false` in the ox\_inventory file, `unique = true` in the qb-inventory and qs-inventory files. This way every egg incubates on its own.

The egg items are made usable by the script itself. You do not need to register a use handler.
{% endstep %}

{% step %}

### Copy the item images

Copy the three `.png` files from `__INSTALL/images/` into the image folder of your inventory, for example `ox_inventory/web/images/` or `qb-inventory/html/images/`.
{% endstep %}

{% step %}

### Start it in the right place

Start `kossek_easter` **after** ox\_lib, oxmysql, your framework and your inventory. The script checks which of them are running at the moment it starts.

```cfg
ensure oxmysql
ensure ox_lib
ensure es_extended        # or qb-core / qbx_core
ensure ox_inventory       # or your inventory

ensure kossek_easter
```

There are no convars. Everything is set in the config files.
{% endstep %}

{% step %}

### Give your admins access

The admin panel and the admin commands check the player on the server.

**ESX**: a player is an admin when their group is listed in `config/server.lua`:

```lua
Config.AdminGroups = { 'admin', 'superadmin', 'god' }
```

**QBCore**: a player is an admin when they have the QBCore `admin` permission or the `command` ace.

**QBX**: a player is an admin when they have the `qbx_core.admin` ace or the `command` ace.

`Config.AdminGroups` is only used on ESX.
{% endstep %}

{% step %}

### Check the console

On start the server console prints which incubation mode is used, for example `ox_inventory detected — using per-item metadata for incubation.`, followed by:

```
Easter Event loaded successfully!
Spawner: ON | Boss interval: 1800s | Pity: 100 shells
```

If you see `No supported framework detected`, the script was started before your framework.
{% endstep %}

{% step %}

### Set up the event

Move the zones, the trader and the scoreboard where you want them, and replace the example loot with items that exist on your server. See [Configuration](/docs/scripts/easter-event/configuration.md) and [Loot Tables](/docs/scripts/easter-event/loot-tables.md).
{% endstep %}
{% endstepper %}

## Database

Nothing to import. The script creates its table on the first start:

| Table          | Holds                                                                                                          |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| `easter_stats` | One row per player: name, eggs collected, eggs opened, boss hits, shells exchanged and the incubation progress |

Stats are saved every 5 minutes, when a player leaves, before a txAdmin restart and when the resource stops.

To start a new edition of the event with empty stats, empty the `easter_stats` table while the resource is stopped.

## Updating

Replace the resource folder, then put back the folders you edited: `config/`, `bridge/` and `locales/`. Compare your config with the new one and add any new options. Player stats live in the database, so they are kept.