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

# Installation

## Requirements

| Dependency                                                                                                     | Required           | Notes                                                                |
| -------------------------------------------------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------- |
| [`es_extended`](https://github.com/esx-framework/esx_core)                                                     | ✅ Yes              | Declared in `fxmanifest.lua` and used on both client and server.     |
| An ESX-compatible inventory (`items` DB table)                                                                 | ✅ Yes              | Recyclable items must exist as usable/removable items.               |
| [`ox_target`](https://github.com/overextended/ox_target) or [`qtarget`](https://github.com/BennyDeezy/qtarget) | ⛔ Optional         | Only if `Config.UseTarget = true`. Auto-detected.                    |
| The stream asset `mr_recyclingmachine`                                                                         | ✅ For custom props | Provides the `mr_recyclingmachine` model + `.ytyp` used by machines. |

> **Framework note:** This resource targets **ESX Legacy**. It relies on `exports["es_extended"]:getSharedObject()`, `ESX.RegisterServerCallback`, `ESX.TriggerServerCallback`, and `xPlayer` inventory/money methods (`getInventoryItem`, `addInventoryItem`, `removeInventoryItem`, `addMoney`).

***

## 1. Install the resource files

Drop the `mr_recycling` folder into your server `resources` directory, then add it to your `server.cfg`:

```cfg
ensure es_extended
# ensure ox_target   # only if you enable target mode
ensure mr_recycling
```

> ⚠️ Make sure `es_extended` (and your target resource, if used) start **before** `mr_recycling`.

***

## 2. What's inside `fxmanifest.lua`

The manifest defines how the resource is loaded. Key entries:

```lua
fx_version 'cerulean'
lua54 'yes'
games { 'gta5' }

this_is_a_map "yes"          -- loads world objects/props as a map resource

shared_scripts { 'config.lua' }               -- Config table, shared client+server

files {                                        -- NUI assets exposed to the game
    "html/index.html",
    "html/style.css",
    "html/script.js",
}
escrow_ignore { 'config.lua' }                 -- config stays editable under escrow
ui_page "html/index.html"                      -- the mini-game NUI

client_scripts { 'client.lua' }
server_scripts { 'server.lua' }                -- '@oxmysql/lib/MySQL.lua' is commented out

dependencies { 'es_extended' }

-- registers the custom machine model's type request
data_file 'DLC_ITYP_REQUEST' '@mr_recyclingmachine/stream/mr_recyclingmachine.ytyp'
```

| Directive                    | Purpose                                                                                                     |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `shared_scripts`             | Loads `config.lua` on both sides so `Config` is available everywhere.                                       |
| `files`                      | Whitelists the three NUI files so the game can serve them.                                                  |
| `ui_page`                    | Registers `html/index.html` as the NUI page (the key mini-game).                                            |
| `escrow_ignore`              | Keeps `config.lua` readable/editable even when the rest is escrow-protected.                                |
| `data_file DLC_ITYP_REQUEST` | Requests the custom `mr_recyclingmachine` prop typ from the separate `mr_recyclingmachine` stream resource. |

> **Important:** the `data_file` line points to `@mr_recyclingmachine/...`. The custom machine model lives in a **separate** stream resource named `mr_recyclingmachine`. If you do not have it, either install it or change the machine models in `Config.RecyclingLocations` to a base-game prop.

> **oxmysql note:** `@oxmysql/lib/MySQL.lua` is present but **commented out** in the manifest. The current build stores cooldowns/busy state **in memory** (see the [Configuration → Server API](broken://pages/1f8c151f135d0a78c1c31482bb8a7ef03077bc12#server-side-serverlua) page). No SQL tables are required for cooldowns.

***

## 3. Add the items to your database

Recyclable items must exist in your inventory's `items` table. A starter SQL file (`recycling_items.sql`) is included but only covers four items:

```sql
INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES ('plastic_bottle', 'Plastic Bottle', 1, 0, 1);
INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES ('can', 'Can', 1, 0, 1);
INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES ('glass_bottle', 'Glass Bottle', 2, 0, 1);
INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES ('aluminum_can', 'Aluminum Can', 1, 0, 1);
```

> ⚠️ **The provided SQL is incomplete.** The config references many more items (`cardboard`, `paper`, `scrap_metal`, `copper_wire`, `electronic_parts`, `old_phone`, `battery`, `gold_watch`, `plastic_bag`, `bottle_cap`, `cloth`, `rubber`, `old_cd`, `money`). Every item that appears in `Config.Bins`, `Config.RecyclingBinItems`, or `Config.RecyclingMachineItems` **must exist as an item in your database** — otherwise `addInventoryItem` will silently fail for the missing ones. `money` is not an item; it is handled via `xPlayer.addMoney`.

You can generate the full list from the labels defined in `Config.RecyclingBinItems` and `Config.RecyclingMachineItems` (see [Configuration](broken://pages/1f8c151f135d0a78c1c31482bb8a7ef03077bc12#items--pricing)).

If you use **ox\_inventory**, add the items to `ox_inventory/data/items.lua` instead of the `items` SQL table, and provide matching `.png` icons.

***

## 4. Item images (inventory icons)

Provide an icon for every recyclable item in your inventory's image folder (e.g. `ox_inventory/web/images/` or `esx_inventoryhud` images). Icon filenames must match the item `name`, e.g. `plastic_bottle.png`.

***

## 5. First start & verification

1. Start the resource: `ensure mr_recycling` (or `refresh; ensure mr_recycling`).
2. On start, the client spawns the props and blips defined in `Config.RecyclingLocations` (after ESX player data is available).
3. Walk to a machine/bin blip. You should see either an `ox_target`/`qtarget` option or a `Press E` help notification, depending on `Config.UseTarget`.
4. If `Config.DiscordLogs.enabled` and a `system` webhook is set, a **"🚀 Recycling System Started"** embed is posted.

If nothing spawns, check the server console for ESX errors and confirm your player has loaded (`esx:playerLoaded`) — object spawning waits for player data.

> **Known caveat:** the server start log reads `Config.DevMode` which is **not defined** in the shipped `config.lua`. This is harmless (it resolves to `nil` → "Disabled"), but you can add `Config.DevMode = false` to `config.lua` to make it explicit.