All resources

rsg-hunting – Docs (v3.4.0)#

Contents#

  1. Files
  2. How it works
  3. Configuration
  4. Exports, events and commands
  5. Database
  6. Security
  7. Server owner how-tos
  8. Troubleshooting

1. Files#

FilePurpose
fxmanifest.luaManifest; depends on oxmysql, rsg-core, rsg-target, rsg-inventory
config.luaAnimals, trappers, butchers, XP, bounties, leaderboard
client/client.luaSkinning hook
client/vendor.luaTrapper NPCs and NUI sell screen
client/butcher.lua, client/npcs.luaButcher NPCs, prompts/targets
client/leaderboard.lua, client/main.jsLeaderboard UI
server/server.luaSkin rewards
server/vendor.luaTrapper selling, stock
server/butcher.luaCarcass selling
server/xp.luaHunting XP, levels, weekly leaderboard
server/bounty.luaDaily bounties
server/sv_config.lua, server/webhooks.luaWebhook settings and Discord logs
server/versionchecker.luaGitHub version check
html/NUI (sell screen, leaderboard)
install.sqlManual database install
installation/shared_items.luaItems to add to your items file
stream/annesburg.ymapMap streaming file
locales/*.jsonen, de, el, es, fr, ja, nl, pl, pt-br, ro, ru

2. How it works#

  • Skinning: hooks the game's native skinning event (no minigame). Up to 5 reward items per animal, 90+ animals in Config.Animals. The client only sends the carcass network id; the server checks it exists, is dead, is close, is skinnable and was not skinned before. Config.DeleteCarcass removes the carcass afterwards.
  • Trappers: 5 NPCs with blips and an NUI sell screen (search, owned-only filter, quantity, basket). Stock-based pricing per trapper: 1.25x below 50% of maxStock, 1.5x below 25%. Stock decays over time (StockDecayMinutes, StockDecayPercent) so prices recover. Stock is saved to vendor_stock.json.
  • Butchers: 12 NPCs (rsg-target or prompt). Sell the carried carcass, or one on your horse (SellFromHorse), for cash and meat scaled by pelt quality (poor, good, perfect).
  • Daily bounties: Config.Bounty picks animals per UTC day that pay extra at the butcher and give extra XP.
  • Hunting XP: XP for skinning and butcher sales, levels with perks (trapperBonus, butcherBonus, extraSkinChance), clean-kill multiplier for perfect pelts.
  • Weekly leaderboard: weeks start Monday 00:00 UTC; top ranks collect cash at any trapper.

3. Configuration#

config.lua (main options):

OptionMeaning
DeleteCarcassRemove the carcass after skinning
ImageItem image folder
AllowPushToTalkWhileOpen, PushToTalkControlsKeep push-to-talk working while NUI is open
BlipSprite, BlipScaleTrapper blips
StockDecayMinutes / StockDecayPercentTrapper stock recovery (30 min / 10%)
BountyEnabled, Count, ButcherBonus, XPMultiplier, MinReward, Animals
VendorsTrappers: pedModel, coords, blip, items (name, sellPrice, maxStock, canSell, stockBasedPrice)
SellFromHorseButcher buys carcasses on your horse
KeyBind / EnableTarget'J' prompt, or rsg-target on butcher NPCs
HuntingXPEnabled, RepName, DefaultXP, Notify, ButcherXP, ButcherQualityMultiplier, Levels, CleanKillMultiplier, Weekly, Leaderboard, per-animal Animals

Perks are not cumulative: each level lists its full perk set. Webhook URLs are in server/sv_config.lua.

4. Exports, events and commands#

NameSideNotes
GetDailyBounties()server exportToday's bounty animals
AwardHuntingXP(...)server exportGive hunting XP
GetHuntingXP(...) / GetHuntingLevel(src)server exportsRead XP and level
SendWebhook(...)server exportSend a hunting webhook
rsg-hunting:server:giverewardsserver event(netId, quality) skin rewards
rsg-hunting:server:getSellDatacallback(vendorIndex)
rsg-hunting:server:sellBasketcallback(vendorIndex, basket)
rsg-hunting:server:sellCarcasscallback(netId, quality)
rsg-hunting:server:getBountiescallbackDaily bounties
rsg-hunting:server:getLeaderboardcallback(mode)
rsg-hunting:server:claimWeeklycallbackCollect last week's reward
rsg-hunting:client:butcher:mainmenuclient eventOpen the butcher menu
CommandWhoWhat
/huntingboardeveryoneOpen the leaderboard (name from Leaderboard.Command, '' disables)
/resetvendorstockserver console onlyReset trapper stock
/huntingwebhooktestadminSend a test webhook

5. Database#

install.sql (created automatically on start):

  • hunting_weekly: citizenid, week, name, xp (primary key citizenid, week).
  • hunting_weekly_rewards: id, citizenid, week, rank, cash, claimed.
  • hunting_weekly_state: key (primary key, lastPaidWeek), value (INT, last week that was paid out). Kept in MySQL instead of resource KVP so the server creates no db folder.

Trapper stock is saved in vendor_stock.json.

6. Security#

The server validates every skinning and sale: carcass exists, is dead, is close and unskinned; distance to the vendor, accepted items, ownership, cooldown. The server removes carried carcasses itself so sales can't be faked or repeated, and rolls back if an item removal fails.

7. How-tos#

  • Add an animal: add it to Config.Animals with its rewards, and to HuntingXP.Animals for XP.
  • Add items to your items file from installation/shared_items.lua.
  • Turn XP off: HuntingXP.Enabled = false.

8. Troubleshooting#

ProblemFix
Nothing from skinningAnimal missing in Config.Animals, or carcass already skinned
Trapper prices lowStock is full; wait for decay or /resetvendorstock
No leaderboardCheck Leaderboard.Command and HuntingXP.Weekly.Enabled
Missing item imagesCheck Config.Image

rsg-skills integration#

Config.Skills = { Enabled, Skill, MirrorXP, SellBonus, ExtraYield }, plus the global helpers SkillsActive() and SkillPerk(src, perk) defined at the end of config.lua.

  • HuntingXP.Award calls exports['rsg-skills']:AddXP(src, 'hunting', amount, 'hunting', { raw = true }) after the rep is added (raw so the two totals stay equal).
  • The butcher adds GetPerk(src, 'hunting', 'sell_bonus') / 100 to its bonus before computing the cash.
  • Skinning adds GetPerk(src, 'hunting', 'extra_yield') to the existing extraSkinChance.
  • The trapper vendor sale is not changed, because its prices are shown in the shop UI.
  • rsg-skills imports the old hunting rep value once per character (repImport), so existing levels carry over.

rsg-reputation integration#

Config.Reputation = { Enabled, StandingPerSale, StandingCooldown, PayoutModifier, PayoutMin, PayoutMax }, plus the global helpers ReputationActive(), ReputationPayoutFactor(src, region) and ReputationSale(src, region) defined at the end of config.lua. Optional: everything is skipped when rsg-reputation is not started.

  • Every entry in Config.ButcherLocations has a region (an id from rsg-reputation's Config.Regions, a town or a state). nearButcher now returns the butcher the player is standing at, so the server knows the region.
  • Payout: ReputationPayoutFactor reads GetPriceModifier(src, region) and pays 1 - modifier, kept between PayoutMin and PayoutMax (hated 0.75, disliked 0.90, neutral 1.0, liked 1.05, respected 1.10, celebrated 1.15 with rsg-reputation's default tiers). The factor multiplies the final cash, after the quality multiplier and the perk bonuses. Set PayoutModifier = false to switch it off.
  • Standing: after a successful sale ReputationSale calls AddStanding(src, region, StandingPerSale, 'hunting butcher sale'), at most once per player and region every StandingCooldown seconds, so spamming sales cannot farm it. Set StandingPerSale = 0 to switch it off.
  • Honor is never changed: hunting is legal. The trapper vendor is not affected, because its prices are shown in the shop UI.
  • All values come from the server config. The client only sends the carcass network id, as before.

Support the Project : https://rexshack.tebex.store/

<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->

Technical reference#

Generated from the source of rsg-hunting 3.4.0. Names, arguments and defaults below are read straight from the code.

Dependencies#

oxmysql, rsg-core, rsg-target, rsg-inventory

Database#

Tables: hunting_weekly, hunting_weekly_rewards, hunting_weekly_state.

Tables are created automatically on start while Config.AutoDatabase = true (default). Nothing is ever dropped or overwritten. For a manual install set Config.AutoDatabase = false and import install.sql once.

-- shared/config.lua
Config.AutoDatabase = true -- false = import the SQL file yourself

Configuration#

OptionDefaultNotes
Config.AutoDatabasetruebuild the database tables automatically on start (set false and import the SQL file for a manual install)
Config.DeleteCarcassfalsethis will ensure the carcass is removed if true
Config.Image'rsg-inventory/html/images/'location where your item images are stored
Config.AllowPushToTalkWhileOpentrueWhile NUI is open, block game controls but allow push-to-talk.
Config.PushToTalkControlstable
Config.BlipSprite'blip_shop_animal_trapper'
Config.BlipScale0.2
Config.StockDecayMinutes30trapper stock sells on every X minutes (0 = never, prices stay low once stocked)
Config.StockDecayPercent10% of each item's stock removed each time (each trapper has its own stock)
Config.Bountytable
Config.Enabledtrue
Config.Count2
Config.ButcherBonus50
Config.XPMultiplier2
Config.MinReward3
Config.Animals{}
Config.Vendorstable
Config.HuntingXPtable
Config.RepName'hunting'
Config.DefaultXP1
Config.Notifytrue
Config.ButcherXPtruebutcher sales also give xp (base xp x quality multiplier below)
Config.ButcherQualityMultiplier{ poor = 1, good = 2, perfect = 3 }
Config.LevelstableextraSkinChance = % chance to get a 2nd copy of the main skinning reward
Config.CleanKillMultiplier1.5clean kill: skinning a perfect-quality animal multiplies its skinning xp (max 3)
Config.Weeklytableweekly leaderboard (needs install.sql). weeks start Monday 00:00 UTC
Config.Leaderboardtable
Config.Debugfalse
Config.SellTime10000butcher sell progress bar (ms)
Config.SellFromHorsetruebutcher also buys a carcass strapped to your horse
Config.HorseCarcassRange6.0max distance (m) between you and the carcass/horse
Config.PoorMultiplier1butcher cash/item multipliers by carcass quality
Config.GoodMultiplier2
Config.PerfectMultiplier3
Config.KeyBind'J'prompt key when Config.EnableTarget = false
Config.EnableTargettruersg-target on butcher NPCs instead of prompts
Config.ServerCooldown2000per-player cooldown on skinning/butcher rewards (ms)
Config.EnableLoggingtruesend butcher sales to rsg-log
Config.WebhookName'rsghunting'
Config.WebhookTitle'RSG Hunting - Butcher'
Config.WebhookColour'default'
Config.DistanceSpawn20.0distance before spawning/despawning the butcher ped
Config.FadeIntruefade butcher peds in/out
Config.Bliptable
Config.ButcherLocationstable
Config.Animaltable
Config.SkillstableThe hunting XP, levels and leaderboard above keep working; this adds the shared rsg-skills 'hunting' skill on
Config.Reputationtablersg-reputation integration (optional): town standing and payout factor for butcher sales
Config.Skill'hunting'
Config.MirrorXPtrue
Config.SellBonustrue
Config.ExtraYieldtrue

Exports#

Server

ExportArgumentsFile
GetDailyBounties``server/bounty.lua
SendWebhook``server/webhooks.lua
AwardHuntingXP``server/xp.lua
GetHuntingXP``server/xp.lua
GetHuntingLevelsrcserver/xp.lua
-- example
local result = exports['rsg-hunting']:GetDailyBounties()

Callbacks#

CallbackSideArgumentsFile
rsg-hunting:server:getBountiesserversrc, cbserver/bounty.lua
rsg-hunting:server:sellCarcassserversrc, cb, netId, qualityserver/butcher.lua
rsg-hunting:server:getSellDataserversrc, cb, vendorIndexserver/vendor.lua
rsg-hunting:server:sellBasketserversrc, cb, vendorIndex, basketserver/vendor.lua
rsg-hunting:server:claimWeeklyserversrc, cbserver/xp.lua
rsg-hunting:server:getLeaderboardserversrc, cb, modeserver/xp.lua
-- client side
RSGCore.Functions.TriggerCallback('rsg-hunting:server:getBounties', function(result)
    -- use result
end)

Events#

Server events can be fired by any client, so every handler re-validates the player, the arguments and any permission, distance or cooldown on the server. Never add a reward to a handler without those checks.

EventSideArgumentsFile
rsg-hunting:server:giverewardsservernetId, qualityserver/server.lua
-- from a client script
TriggerServerEvent('rsg-hunting:server:giverewards', netId, quality)

Commands#

CommandNotesFile
/resetvendorstockserver/vendor.lua
/huntingwebhooktestlocale('wh_test_help')server/webhooks.lua

Locales#

Language files in locales/: de, el, en, es, fr, ja, nl, pl, pt-br, ro, ru. Set the language with setr rsg:locale "en".

<!-- END AUTO-REFERENCE -->