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

   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

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

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.