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

# Pepper Hunting

Hunting for every player – living wildlife, stalking with wind and tracks, hunting license with closed seasons and poaching, levels 1–50, tablet, hunting dog, legendary animals and competitions.

> ✅ **Get Pepper Hunting:** <https://pepper-scripts.tebex.store/package/7765749>

> 🧪 **Tested on our dev server:** Of course we test all scripts continuously on our own dev server “Pepper Scripts”.

> 🎬 **Tutorial video:** <https://youtu.be/jJqXrXnOWpE>

### Overview

Pepper Hunting turns hunting into a leisure activity for **every player** – no job and no business required. A real **wildlife population** lives in the **hunting zones**: the server knows which animals are where, they only spawn near hunters, and harvested game repopulates over time. Outside the zones, the city stays quiet.

Players hunt with **dedicated hunting weapons** that can only be drawn inside a hunting zone. Animals **hear, see and smell**: wind, noise and camouflage decide whether you get close enough. **Tracks**, **binoculars**, **calls**, **bait** and **hunting stands** help along the way. Shot placement determines the **quality** of the loot; wounded game flees and leaves a **blood trail**.

To hunt legally, players get a **hunting license** (theory quiz + shooting range) and respect **closed seasons** and **daily quotas** – otherwise it's **poaching**: the loot becomes illegal and the police can be called. A **hunter level 1–50** (about 60 hours) unlocks endorsements, weapons and zones; the **hunting tablet** shows the collection, trophies, leaderboards and the map. On top of that there are a **hunting dog**, **traps**, **legendary animals**, **hunting parties with drive hunts** and **competitions**. Venison can be butchered for **Pepper Eats**.

### Features

* **Hunting zones:** 6 presets (Paleto Forest, Mount Chiliad, Raton Canyon, Grapeseed fields, Tongva Hills, Great Chaparral) and as many more as you like – mark them out in-game with `/huntadmin` (walk the outline), species, population, minimum level, blip
* **Living wildlife population** per zone on the server, spawns only near hunters, repopulates over time – deer, boar, mountain lion, coyote, rabbit, hawk
* **Dedicated hunting weapons** (hunting rifle, shotgun, hunting knife) as items, can only be drawn inside a hunting zone, spent ammo is deducted
* **Hit zones and quality:** head/heart-lung = clean, body, haunch, leg – plus the right weapon, multiple hits and freshness → quality 0–100 and 1–5 stars
* **Stalking:** game hears you (crouching is quieter), sees you (field of view, line of sight) and smells you (wind per zone, changes every 10 minutes); predators attack
* **Tracks** (footprints, droppings, feeding spots, bedding areas) lead to game up to 450 m away; inspecting them shows species, age and direction
* **Tracking wounded game:** wounded animals flee, bleed and die – follow the blood trail, the shooter gets the animal
* **Binoculars** (species, sex, weight, achievable stars, wind), **wind and noise indicator**, **camouflage clothing**
* **Calls** for deer, boar and predators (calling too often scares them off), **bait** and **salt licks**
* **Hunting stands:** placeable (item) and fixed (admin) – from above, game sees and smells you less easily
* **Field dressing** with a hunting knife: meat, hides, pelts, antlers, boar tusks, claws and feathers as ox\_inventory items with quality, hunter and "legal/illegal"
* **Game dealer** buys by quality with daily price fluctuation, the **fence** buys poached loot for a pittance
* **Hunting license:** theory exam (22 questions DE/EN, answers only on the server) and shooting range test, ID item, endorsements for big game, predators and night hunting
* **Rules:** closed seasons per species and weekday, daily quotas, night hunting – violations = poaching with a police alert (ps-, cd-, qs-, rcore-, core\_dispatch or built-in)
* **Hunting shop** with 17 products; weapons and ammo only with the matching license and level
* **Hunter level 1–50** (≈ 60 hours) with unlocks: endorsements, shop products, zones, more hunting stands, bait and traps
* **Collection** per species with milestones (XP + money); the **taxidermist** turns loot into **trophies** with points
* **Hunting tablet** (item or `/hunttablet`): overview, level, collection, trophies, leaderboards, map, dog, party, competition, legends
* **Hunting dog** (retriever, shepherd, husky) with name, feeding, affection and dog level: heel, sit, search (finds wounded game first), fetch
* **Traps** for small game (snare, box trap) – set them up, check them later
* **Legendary animals** (White Stag, Old Tusker, Shadow Stalker, Ghost Coyote) with rumors, hall of fame and special trophies
* **Hunting parties** of up to 6 hunters: field dress loot immediately, XP share, **drive hunt**
* **Competitions** (biggest deer, boar hunt, rabbit sprint, cleanest shot) on a schedule or started by admins, with prizes
* **Pepper Eats integration:** butcher venison at the game dealer for the restaurant kitchen
* **Admin menu** with zones, places (dealer, fence, license office, shooting range, hunting shop, taxidermist, kennel, hunting stands), overview, set license/level, competitions
* 3 Discord webhooks, server and client exports, German & English; config, locale files, bridges and install files are open

### Requirements

| Requirement        | Version                   |
| ------------------ | ------------------------- |
| FiveM server build | ≥ 7290                    |
| OneSync            | required                  |
| Framework          | ESX, QBCore or Qbox       |
| Database           | MySQL 8 or MariaDB ≥ 10.6 |

### Dependencies

* [ox\_lib](https://github.com/overextended/ox_lib)
* [oxmysql](https://github.com/overextended/oxmysql)
* [ox\_inventory](https://github.com/overextended/ox_inventory) – loot with quality, hunting weapons, tools
* optional: [ox\_target](https://github.com/overextended/ox_target) or qb-target – otherwise a hint text "\[E] …"
* optional: a dispatch script (ps-dispatch, cd\_dispatch, qs-dispatch, rcore\_dispatch, core\_dispatch)
* optional: [Pepper Eats](https://pepper-scripts.tebex.store) – venison as a restaurant ingredient

### Installation

1. Copy the folder to `resources/[pepper]/pepper_hunting` – **do not rename**.
2. Items: add the contents of `install/ox_items_en.lua` (English) or `install/ox_items.lua` (German) to `ox_inventory/data/items.lua` – **before** the last `}` of the file.
3. Copy all images from `install/images/` to `ox_inventory/web/images/` (32 images).
4. **Important:** ox\_inventory takes away weapons that were not drawn from the inventory. Add the three game weapons used by the hunting weapons to your `server.cfg` (Pepper Hunting checks this on start and warns you):

```
# hunting rifle, shotgun, knife – exactly like this, no spaces, before ensure ox_inventory
setr inventory:ignoreweapons [100416529,487013001,-1716189206]
```

5. `server.cfg`:

```
ensure oxmysql
ensure ox_lib
ensure ox_inventory
# ensure ox_target        # optional – or qb-target
# your framework (es_extended / qb-core / qbx_core) before it as usual
ensure pepper_hunting

add_ace group.admin pepper_hunting.admin allow
```

6. The script creates its 12 database tables on start. Only if your database user isn't allowed to do that, import `install/pepper_hunting.sql`.
7. Start the server. The console shows `Pepper Hunting 1.0.0 started (…, 6 hunting zones)` (with `Config.Locale = 'en'`).
8. In-game, open `/huntadmin` and **check the preset places**: the coordinates of the zones, dealers, license office, shooting range, hunting shop, taxidermist and kennel are good approximations – on custom maps or with MLOs, please take a look once and set them again if needed.

### Configuration

All settings are open in `config/`:

| File              | Contents                                                                                                                                                                            |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config.lua`      | Language, framework, command, keys, zones, spawning, shooting, loot, **stalking** (perception, wind, tracks, tracking wounded game, binoculars, calls, bait, hunting stands), trade |
| `animals.lua`     | Species: models, size, suitable weapons, weight, loot, XP, senses, attack; hit zones                                                                                                |
| `zones.lua`       | Preset hunting zones (only used for an empty database)                                                                                                                              |
| `weapons.lua`     | Hunting weapon items → game weapon + ammo, knife, "zone only"                                                                                                                       |
| `items.lua`       | All items with price/weight (`install/ox_items.lua` is generated from it)                                                                                                           |
| `places.lua`      | Preset places and place types, NPC models, blips                                                                                                                                    |
| `license.lua`     | Hunting license, fees, endorsements, license per species, closed seasons, quotas, poaching/police, shooting range, quiz, hunting shop                                               |
| `progression.lua` | Level curve, XP sources, unlocks, collection milestones, taxidermist, tablet, leaderboards                                                                                          |
| `extras.lua`      | Hunting dog, traps, legendary animals, hunting parties + drive hunt, competitions, Pepper Eats                                                                                      |
| `server.lua`      | Webhooks, admin ACE, quiz answers (never sent to clients)                                                                                                                           |

Common adjustments:

* **Stalking difficulty:** `Config.Perception.Difficulty` (0.6 = easy, 1.0 = challenging)
* **Playtime to level 50:** `Config.Level.XpCurve` (1.25 ≈ 60 hours), event weekend: `Config.Level.XpMultiplier = 2.0`
* **Without hunting license rules** (everything legal): `Config.License.Enabled = false`
* **Prices:** `Config.Items` (selling), `Config.Shop.Items` (hunting shop), `Config.Trade.StarFactor`

### Permissions

| Permission              | How                                                             |
| ----------------------- | --------------------------------------------------------------- |
| Admin menu `/huntadmin` | ACE `pepper_hunting.admin` or a group from `Config.AdminGroups` |
| Hunting                 | all players – legal with a hunting license, otherwise poaching  |
| Police alerts           | jobs from `Config.Poaching.PoliceJobs` (minimum grade)          |

### Creating hunting zones

1. `/huntadmin` → **Zones** → "New hunting zone", enter a name.
2. **Mark the outline:** walk, drive or fly along the border and press **E** at every corner – **X** removes the last point, **Enter** closes the outline, **ESC** cancels. Glowing walls show the outline.
3. Weight the **species** with sliders, choose the **population** (animals at the same time) and optionally **From hunter level**.
4. **Create.** The population is there immediately; "Redistribute population" resets it.

**Locations** (game dealer, fence, license office, shooting range, hunting shop, taxidermist, kennel, fixed hunting stand): `/huntadmin` → **Locations** → "New location" → choose type and name → "Set" → stand at the spot, turn to face the right direction, **E**. For the shooting range, the position is the shooting position; the targets are placed in the direction you're facing.

### How hunting works

* **Gear up:** hunting shop (knife, binoculars, calls, bait; shotgun and rifle with a license). **Use** a hunting weapon item = draw it, use it again = holster it. If you leave the zone, it is holstered automatically.
* **Stalking:** at the bottom right, **wind** (arrow relative to your viewing direction) and **noise** show how well you're doing. Upwind and crouched, you get closest.
* **Tracks** become visible from 30 m – inspect them with **E**: species, age, direction to the next track.
* **Shooting:** heart-lung or head = full quality. A hit in the haunch or leg: the animal flees – follow the blood trail.
* **Field dress** the animal (hunting knife), then go to the **game dealer** (legal loot) or the **taxidermist** (trophy).
* Party members may field dress your kills immediately; others only after 90 seconds.

### Hunting license and rules

1. **License office:** theory exam – 10 random questions, 8 must be correct (fee per attempt).
2. **Shooting range:** you are placed at the shooting position and get a loaner rifle – hit 4 of 6 targets within 120 seconds. Afterwards the **hunting license** (ID with a number) is in your inventory.
3. **Endorsements** at the office: big game (deer, boar, from level 5), night hunting (from level 8), predators (coyote, mountain lion, from level 12).
4. **Poaching:** without the matching license, during the closed season, above the daily quota or at night without the endorsement. The loot is illegal (only the **fence** buys it), gives no XP, and with a 60 % chance a witness calls the police – with an approximate location on the map.

### Levels, collection and trophies

* **Level 1–50:** XP from legal kills (more for clean shots), field dressing, exams, trophies, the first sighting of a species, traps and milestones. Level 10 ≈ 4 h, 20 ≈ 11 h, 30 ≈ 22 h, 50 ≈ 60 h.
* **Unlocks** are shown in the tablet: endorsements, shop products, zones (Mount Chiliad from 10, Raton Canyon from 15, Great Chaparral from 20), more hunting stands, bait and traps.
* **Collection:** every species with count, best quality and heaviest animal; milestones at 1/10/50/100 kills.
* **Taxidermist:** antlers, boar tusks, coyote and mountain lion pelts (legal, from 40 % quality) become a **trophy** with points based on weight and quality – visible on the trophy wall and in the leaderboard.

### Hunting dog

At the **kennel** (from level 8): retriever (fetches better), shepherd (tracks farther) or husky. The **dog whistle** calls it / sends it home. Commands in the tablet or with `/huntdog call|follow|sit|search|fetch|home`. **Search** shows the direction and distance to the nearest animal – your own wounded game first, then the dog follows the blood trail. **Fetch** brings small game without a knife. Feeding (dog food item) and petting keep it happy; if it dies in-game, it is injured for 20 minutes or the vet can help.

### Traps, legends, parties, competitions

* **Traps:** set a snare (rabbits) or box trap (rabbits, birds) inside a zone and check it after 20–30 minutes. The same rules apply as for hunting.
* **Legendary animals** appear rarely (rumors for hunters from level 15), are tougher and heavier and move on after 40 minutes. Whoever takes one down first enters the **hall of fame**.
* **Hunting parties:** invite players by server ID in the tablet. Together: field dress loot immediately, 25 % XP share when nearby, **drive hunt** (leader in the zone, from 3 hunters): for 8 minutes, game is driven towards the line of shooters.
* **Competitions** start on a schedule (`Config.Events.Schedule`) or via `/huntadmin` → "Competitions …". Sign-up and live leaderboard in the tablet, prizes for places 1–3.

### Pepper Eats

If **Pepper Eats** is running (with the game recipes), the game dealer shows "Butcher for the kitchen (Pepper Eats)": deer, boar and rabbit meat become restaurant ingredients. Without Pepper Eats, this section is hidden – Hunting works unchanged.

### Commands

| Command              | Who        | Purpose                                                  |
| -------------------- | ---------- | -------------------------------------------------------- |
| `/huntadmin`         | Admins     | Zones, places, overview, set license/level, competitions |
| `/hunttablet`        | everyone   | Hunting tablet (also as an item)                         |
| `/huntdog <command>` | Dog owners | call, follow, sit, search, fetch, home                   |

### Webhooks

In `config/server.lua` (`ServerConfig.Webhooks`):

| Key        | Contents                                                                    |
| ---------- | --------------------------------------------------------------------------- |
| `admin`    | Zones/places created, changed, deleted; hunting license/level set by admins |
| `hunting`  | Poaching, legendary animals (sighted, killed), competitions                 |
| `security` | Suspected cases from the plausibility check                                 |

### Exports

**Server**

```lua
exports.pepper_hunting:getZones()                 -- all hunting zones
exports.pepper_hunting:getZoneAt(x, y)            -- zone at a position or nil
exports.pepper_hunting:getPlayerZone(src)         -- zone the player stands in, or nil
exports.pepper_hunting:getHunter(src)             -- level, XP, statistics, collection
exports.pepper_hunting:getLevel(src)              -- hunter level
exports.pepper_hunting:addXp(src, amount)         -- add XP
exports.pepper_hunting:getLicense(src)            -- hunting license with extensions
exports.pepper_hunting:hasLicense(src)            -- true/false
exports.pepper_hunting:giveLoot(src, species, quality, weight) -- give loot items
exports.pepper_hunting:startEvent(template)       -- start a competition
exports.pepper_hunting:getDog(src)                -- hunting dog or nil
```

**Client**

```lua
exports.pepper_hunting:isInHuntingZone()
exports.pepper_hunting:getCurrentZone()
exports.pepper_hunting:openTablet()
```

### Framework integration

The bridges in `bridge/` (open) detect ESX, QBCore and Qbox automatically (`Config.Framework = 'auto'`). Money is handled by the framework, items by ox\_inventory, police alerts by `bridge/server/dispatch.lua`.

### Troubleshooting

| Problem                              | Solution                                                                                                                                                         |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hunting weapon disappears right away | Add `setr inventory:ignoreweapons [...]` without spaces and before `ensure ox_inventory` (see Installation); the server console prints the correct line on start |
| No animals in the zone               | Zone active? Minimum level reached? `Config.Debug = true` shows output in F8                                                                                     |
| Dealers/places in the wrong spot     | `/huntadmin` → Locations → set them again                                                                                                                        |
| Items without images                 | Copy the images from `install/images/` to `ox_inventory/web/images/`                                                                                             |
| Police get no alert                  | Is a dispatch script running? Otherwise the built-in alert for `Config.Poaching.PoliceJobs` is used                                                              |
| "Butcher for the kitchen" is missing | Pepper Eats with the game recipes must be running                                                                                                                |

### Changelog

**1.0.0 (2026-10-25)** – first release. All changes are listed in `CHANGELOG.md` inside the resource.

### Support

Open a ticket in our [Discord](https://discord.gg/6NaFJWKDYu) (category “Script Support”) and link your purchase with `/verify` first.