# Installation

Koja Fishing is a complete fishing system for FiveM: a skill-based reeling minigame, a guided tutorial, fishing spots with boosted zones, a dynamic-price shop, quests, a skill tree, tournaments with automatic prize payouts, a fishing licence exam, boat rental, diving and digging contracts, fishing parties, poaching fines and illegal electric fishing.
This page takes you from a fresh download to a working resource, and explains how to update from 1.1.0.

## Requirements

| Resource | Why it is needed |
|---|---|
| [`koja-lib`](/koja-lib/getting-started) | Framework bridge (ESX / QBCore / ox_core), inventory, money, jobs, callbacks, progress bars and notifications. |
| `oxmysql` | Database access. |
| `ox_target` | Interaction with peds, boats, placed batteries and the police "Inspect catch" option. |
| ESX, QBCore or ox_core | Any framework supported by `koja-lib`. |
| ox_inventory, qb-inventory or the ESX inventory | Items are read and given through `koja-lib`. |

Optional, only for poaching fines:

| Resource | When |
|---|---|
| `esx_billing` | `Config.Poaching.Billing = 'esx_billing'` — fines are inserted into its `billing` table. |
| `esx_addonaccount` | `Config.Poaching.Billing = 'money'` — the fine is paid into `Config.Poaching.Society` when the resource is started. |

:::hint{type="warning" title="Keep the folder name"}
The resource folder must be called `koja-fishing`.
Exports (`exports['koja-fishing']`) and the ox_inventory item hook (`koja-fishing.useItem`) use that name.
:::

::::steps

### Copy the resource

Put the `koja-fishing` folder in your `resources` directory, next to `koja-lib`.

### Import the database

Import `install.sql` into your database.

With `Config.CreateAutoTable = true` (the default) the resource also creates every missing table and column on start, so this step is optional on a fresh install.

| Table | Content |
|---|---|
| `koja-fishing-playerdata` | Level, XP, licence, exam attempts, skills, guide and digging tutorial flags, unlocks. |
| `koja-fishing-reedemcodes`, `koja-fishing-redeemcode-uses` | Redeem codes and who used them. |
| `koja-fishing-quest-progress`, `koja-fishing-quest-follow` | Quest progress and the followed board. |
| `koja-fishing-tournament-participants`, `koja-fishing-tournament-results`, `koja-fishing-tournament-rewards` | Tournament scores, settled tournaments and prizes waiting for offline winners. |
| `koja-fishing-config` | Values changed in the admin panel. |
| `koja-fishing-diving` | Scuba gear levels, air, stats and diving contracts. |
| `koja-fishing-digging` | Shovel, detector and bag levels, stats and digging contracts. |

### Register the items

The script gives and removes real inventory items, so every item from `shared/config.items.lua` and every fish from `shared/config.fish.lua` must exist in your inventory.
Ready-made definitions for all of them are in the `install/` folder:

| Inventory | Definitions | Icons |
|---|---|---|
| ox_inventory | `install/ox_inventory_items.lua` → paste into `ox_inventory/data/items.lua` | `install/inventory_images/*.png` → `ox_inventory/web/images/` |
| qb-inventory | `install/qb_items.lua` → paste into `qb-core/shared/items.lua` | `web/public/images/items/*.webp` → `qb-inventory/html/images/` |
| ESX default | `install/esx_items.sql` → import into the `items` table | Depends on your inventory. |

File names already match the item names.

:::hint{type="info" title="ox_inventory needs PNG"}
ox_inventory only serves `.png` images.
Use the files from `install/inventory_images/`, not the `.webp` files.
:::

:::hint{type="info" title="Usable items"}
`battery`, `shovel` and `fishpedia` are usable.
On ESX and QBCore the script registers them itself.
On ox_inventory the generated definitions already contain `server = { export = 'koja-fishing.useItem' }` — keep it.
:::

### Start order

Add the resources to `server.cfg` in this order:

```cfg title="server.cfg"
ensure oxmysql
ensure ox_target
ensure koja-lib
ensure koja-fishing
```

### Grant admin permissions

The admin panel (`/fishingadmin`) opens for players with the `koja-fishing.admin` ACE or a framework group listed in `Config.Admin.Groups`.

```cfg title="server.cfg"
add_ace group.admin koja-fishing.admin allow
```

See [Commands](/jobs/fishing/commands) for every command and its permission.

### Set your police jobs

Poaching inspections and fines are available to the jobs in `Config.Poaching.PoliceJobs` (default `police` and `sheriff`).
Pick how fines are paid with `Config.Poaching.Billing` — see [Configuration](/jobs/fishing/configuration#configpoachinglua).

### Check the release settings

Before going live, open `shared/config.main.lua` and make sure `Config.Debug = false`.
Debug mode enables test commands that place free batteries and open test UIs.

::::

## Updating from 1.1.0

1.2.0 changes the way players fish, adds five config files and new items.
Back up your database and your `shared/` folder first.

:::steps

### Replace the files

Replace every file, including `fxmanifest.lua` — it loads the new config files.
Koja Fishing no longer needs `ox_lib`; keep it in `server.cfg` only if other resources use it.
Take the new `locales/*.json` (1.2.0 adds many keys) and re-apply your own text changes.
Keep your edited configs aside and merge them in the next step.

### Merge your configs

The new files `config.minigame.lua`, `config.tutorial.lua`, `config.admin.lua`, `config.poaching.lua` and `config.party.lua` work as shipped.
In the files you edited, add the new options:

- `config.main.lua` — `Config.FishingDui` is gone; the indicator is set with `Config.Minigame.DuiHeight` and `DuiSize`. `Config.Locale` now defaults to `en`.
- `config.hotbar.lua` — the hotbar command is now `kf_hotbar_open` on `Q` (was `fishinghotbar` on `F6`). An old file keeps the old command.
- `config.items.lua` — `requiredLevel` on equipment, and the new items listed below.
- `config.fish.lua` — `protected` on the four swamp species, and the new fish.
- `config.spots.lua` — `requireLicense`, `minRodTier`, `unlockFlag`, `protected`, `blip.minLevel` and the new spots.
- `config.peds.lua` — new peds (`kuba`, `marek`, `stefan`, `hank`, `tom`, `gustaw`), second zones on Chumash Pier, `scenario`, `shop` multipliers, `info` and `hermit` blocks.
- `config.quests.lua` — `independent` boards and `money` / `items` rewards.
- `config.test.lua` — `Lessons`.
- `config.boatrent.lua` — `AnchorKey` and the Chumash Pier parking spots.
- `config.diving.lua` — `Gear`, `Tutorial` and `Contracts`.
- `config.digging.lua` — `Intro`, `Bike`, `Gear`, `Contracts` and the treasure `Drops`.

### Add the new items

Register these items in your inventory (definitions in `install/`) and copy their icons:

`fishpedia`, `swamp_catfish`, `bowfin`, `swamp_eel`, `alligator_gar`, `mackerel`, `cod`, `sea_bream`, `flounder`, `pearl`, `ancient_coin`, `sunken_compass`, `ship_bell`, `pirate_doubloon`, `rusty_key`, `fossil_shell`, `amber_chunk`.

On ox_inventory copy all of `install/inventory_images/` — every icon now ships as PNG.

### Update the database

With `Config.CreateAutoTable = true` nothing is needed: the new tables and columns are created on start.
Otherwise create the new tables from `install.sql` and add the new columns yourself:

```sql title="update-1.2.0.sql"
ALTER TABLE `koja-fishing-playerdata`
    ADD COLUMN `tutorial_done` TINYINT(1) NOT NULL DEFAULT 0,
    ADD COLUMN `tutorial_kit` TINYINT(1) NOT NULL DEFAULT 0,
    ADD COLUMN `digging_intro` TINYINT(1) NOT NULL DEFAULT 0,
    ADD COLUMN `digging_kit` TINYINT(1) NOT NULL DEFAULT 0,
    ADD COLUMN `unlocks` LONGTEXT NULL;
```

### Tell your players

There is no `/fishing` command any more.
Players cast with **E** when the prompt appears on a fishing spot and stop with **X**.
The hotbar opens with **Q** and the party window with **F7**.

:::

## Troubleshooting

| Symptom | Cause |
|---|---|
| Peds do not appear | `ox_target` is not started, or `koja-fishing` starts before `koja-lib`. |
| No cast prompt on a spot | The player is not facing water, is moving, swimming or in a non-boat vehicle. |
| "Missing item" when starting to fish | The item is missing from your inventory's item list, or nothing is equipped in the hotbar. |
| Shop, exam or tournament says the request failed | You are standing more than `Config.Security.PedInteractDistance` metres from the ped. |
| Paying by bank fails on ox_core | `koja-lib` supports only cash on ox_core. Use cash, or set `EntryMoneyType = 'cash'` for tournaments. |
| Item icons missing in ox_inventory | `.webp` files were copied. Copy the PNG files from `install/inventory_images/`. |
| Item icons missing in the UI | The bundled UI in `web/build` was not uploaded. Never delete `web/build`. |
| `/fishingadmin` says no permission | The player has neither the `koja-fishing.admin` ACE nor a group from `Config.Admin.Groups`. |
| Police do not see "Inspect catch" | The job is not in `Config.Poaching.PoliceJobs`, the grade is below `MinPoliceGrade`, or `RequireOnDuty` is on and the officer is off duty. |
| A config edit has no effect | The value was changed in the admin panel. Panel values override the file — reset it to default in the panel. |