# Hunting — documentation

> Bait hunting where the server decides what spawns, who owns it and what it pays.

- URL: https://xexstudio.com/docs/hunting
- Version: 1.0.0
- Product page: https://xexstudio.com/scripts/hunting
Bait hunting where the server decides everything. Every animal belongs to the hunter who baited it, and every
pelt is checked for owner, distance, health and cause of death before it is paid. Hunter levels, a hunting
license with a theory exam, a hunter journal and a mountain lion from level 5. ESX, QBCore and Qbox.

## Requirements

- [ox_lib](https://github.com/overextended/ox_lib) and [oxmysql](https://github.com/overextended/oxmysql)
- OneSync
- One framework: **ESX** (with `esx_license` for the hunting license), **QBCore** or **Qbox**
- One inventory: **ox_inventory**, **qb-inventory** (or a fork with the same exports) or the ESX inventory
- Optional: **ox_target** or **qb-target** (without one, the lodge uses a marker and an `[E]` prompt)
- Optional: [Weapon Licenses](https://xexstudio.com/scripts/weapon-licenses) to require a weapon license before the hunting license

## Install

1. Drop `xex_hunting` into your resources folder.
2. Add the items:
   - **ox_inventory:** copy `install/ox_inventory.lua` into `ox_inventory/data/items.lua`. Keep bait and knife
     without `consume`: xex_hunting removes the bait itself, on the server.
   - **qb-inventory:** copy `install/qb-inventory.lua` into `qb-core/shared/items.lua`, and in `config.lua` use
     `weapon_musket` and `shotgun_ammo` in `Config.Shop`.
   - **ESX inventory:** run the items part of `install/esx.sql`.
   - **Item pictures:** copy `install/images/*.png` to `ox_inventory/web/images/` (or `qb-inventory/html/images/`).
3. **ESX only:** run the license line of `install/esx.sql` (adds the `hunting` license type).
4. Add to `server.cfg` after your framework, inventory, ox_lib and oxmysql:
   ```cfg
   ensure xex_hunting
   ```
5. Language: `setr ox:locale en` (or `es`).

The progress table (`xex_hunting_progress`) is created on the first start.

## How it plays

1. Pass the license exam, then buy bait, a knife and a hunting weapon at the lodge (by default near Paleto Forest,
   on the way to Mount Chiliad). The journal shows a checklist of what you still need.
2. Use the bait inside a hunting area and wait close to it. The server rolls for an animal every few seconds.
3. The animal walks to the bait. Get too close and it flees; the mountain lion attacks instead.
4. Take it with a hunting weapon (musket, precision rifle or sniper rifle by default) and use the knife next to it.
5. Sell pelts, tusks and meat at the lodge. Every level adds a bonus to the price.

The journal (talk to the hunter) shows the hunter's level, XP, hunts, the checklist, sale prices and equipment
(with your inventory's item pictures), the animals, the allowed weapons and the level table.

## Configure

Everything lives in `config.lua`:

| Setting | What it does |
| --- | --- |
| `Config.Framework` / `Config.Inventory` / `Config.Target` | `auto`, or force one |
| `Config.Account` | Account for sales, rewards and purchases |
| `Config.Items` | Bait and knife item names |
| `Config.Weapons` | Weapons that count as a clean kill (a species can override it) |
| `Config.Hunt` | Zones and who sees them on the map, times, spawn chance and distances, limits, blip, bait animation, tool and prop |
| `Config.Species` | Animals: model, XP, spawn weight, level, zones, rewards, journal picture |
| `Config.Levels` | XP per level and sale bonus |
| `Config.License` | Hunting license: on/off, price, theory exam (questions, answers needed), weapon license requirement |
| `Config.Lodge` | Lodge position, NPC, blip and what it buys |
| `Config.Shop` | Equipment sold at the lodge and which items need a license |
| `Config.Buyers` | Extra places that buy items (a butcher, a fence...) |
| `Config.UI` | Journal title, subtitle, accent colour and item pictures |
| `Config.Hooks` | Functions called by the server (see below) |

Hunting areas are drawn on the map for players with the hunting license by default
(`Config.Hunt.zoneBlips.show`: `'license'`, `'always'` or `'never'`). The journal lists them too, and clicking one
sets the GPS.

Texts are in `locales/*.json`, including animal names, descriptions and level titles. Exam questions are in
`questions/<locale>.lua` (loaded only on the server; answers are shuffled for every exam). Hunting zones are GTA zone
codes; their bounds are in `data/zones.lua` (checked on the server).

### Adding an animal

Add an entry to `Config.Species` with its ped model, then `species_<name>` and `species_<name>_desc` in the
locales. A picture is optional: put it in `ui/art/` and set `image`.

### Weapons

`WEAPON_PRECISIONRIFLE` needs game build 2699 or newer (`sv_enforceGameBuild 2699`). On older builds remove it from
`Config.Weapons` and `Config.Shop`.

### ESX without ox_inventory

Weapons go to the loadout. The musket ammo item does not exist there: remove it from `Config.Shop` or replace it
with the ammo item your server uses.

## For developers

```lua
-- server
exports.xex_hunting:GetProfile(source)        -- { xp, hunts, level, title, bonus, species = { deer = 4, ... } }
exports.xex_hunting:GetLevel(source)          -- 1..10
exports.xex_hunting:HasHuntingLicense(source) -- boolean
exports.xex_hunting:IsHunting(source)         -- boolean
exports.xex_hunting:AddXp(source, amount)     -- reward hunting XP from another script

AddEventHandler('xex_hunting:huntCompleted', function(source, data)
    -- data = { species = 'deer', xp = 100, level = 3, leveledUp = false, zone = 'MTCHIL' }
end)
```

`Config.Hooks` lets you plug other resources in without editing the code:

```lua
Config.Hooks.canSpawnPrey = function(source, modelHash, species)
    return true -- false = skip this species (e.g. an anti-cheat that blocks networked peds)
end

Config.Hooks.onHuntCompleted = function(source, data)
    -- battle pass, daily missions, analytics...
end
```

`bridge/server.lua`, `bridge/inventory.lua` and `bridge/client.lua` are open: adapt them if you use another
framework, license system, inventory, target or notification resource.

## Security

- The server opens the hunt when the bait is used, measures how long it takes to place and only then removes it.
- The server picks the species and the spot. The hunter's client creates the animal (so its AI and its corpse
  match what the hunter sees) and the server accepts it only if the model, owner, position and world match.
- Butchering checks, on the server: the hunt is yours, the animal is the one assigned to it, it is dead, it was
  killed with an allowed weapon, you are next to it and you have the knife. Time is measured on the server.
- Rewards are delivered one by one and marked: a full inventory or a failed save can be retried without
  getting anything twice. XP is stored once per hunt.
- The license exam is picked, shuffled and graded on the server; the client never receives the right answers, the
  fee is charged when it starts and leaving mid-exam spends the attempt.
- Prices, items and licenses come from the server config. Buying, selling and the license check that you are at
  the lodge. Nothing the client sends decides a price or an amount.
- Leaving, dying, logging out or switching characters ends your hunts and removes their animals.