rsg-bountyhunter – Docs (v3.3.0)#
Contents#
- Files
- How it works
- Configuration
- Events and commands
- Database
- Security
- Server owner how-tos
- Troubleshooting
1. Files#
| File | Purpose |
|---|---|
fxmanifest.lua | Manifest; depends on rsg-core, rsg-target, oxmysql |
shared/config.lua | Board, timers, distances, offices, tiers |
client/client.lua | Clerks, NUI board, hideout and outlaw spawning, blips |
server/server.lua | Board, contracts, turn-in, stats, leaderboard |
server/sv_config.lua, server/webhooks.lua | Webhook settings and Discord embeds |
server/versionchecker.lua | GitHub version check |
html/ | NUI wanted board (leather and gold style) |
install.sql | Manual database install |
locales/*.json | en, de, el, es, fr, ja, nl, pl, pt-br, ro, ru |
2. How it works#
- Talk to the clerk NPC (rsg-target) at a sheriff's office: View Bounties or Turn In Bounty.
- The NUI wanted board shows tiered posters (Petty / Wanted / Notorious) with random names, crimes and rewards. The board re-rolls on a timer, and a poster someone has taken disappears for everyone else.
- Accept a poster: a search-area blip appears. The outlaw and their gang spawn when you get close. Petty outlaws flee; higher tiers fight back with their gang.
- A bounty-target blip shows when you are close, and is marked incapacitated once the target is dead or hogtied.
- Bring the target to any office. Alive pays the full reward; dead pays
deadMultiplierof it. - Contracts have a time limit with a warning, an abandon option (NUI or
/abandonbounty) and a cooldown before the next one. - Personal stats and a Top Hunters leaderboard (cached).
- With rsg-reputation started, players whose honor falls to the threshold are posted automatically and hunted as real players (see "Reputation bounties").
3. Configuration#
shared/config.lua:
| Option | Default | Meaning |
|---|---|---|
Debug | false | Print distance checks |
RequiredJob | nil | Job lock for contracts (server checked) |
MoneyType | 'cash' | Reward account |
BoardSize | 6 | Posters on the board |
RefreshMinutes | 30 | Board re-roll interval |
ContractMinutes | 30 | Time to bring the target in |
WarnMinutes | 5 | Warning before expiry |
AcceptCooldown | 120 | Seconds before another contract after abandon/fail/expiry |
MinHuntSeconds | 60 | Anti-exploit minimum between finding and turning in |
AbandonCommand | 'abandonbounty' | false to disable |
InteractDistance / ServerCheckDistance / DeliverRadius | 3.0 / 10.0 / 12.0 | Distances |
ClerkSpawnDistance | 60.0 | Clerk spawn range |
SpawnDistance | 150.0 | Outlaws spawn when you are this close |
SearchRadius | 120.0 | Search area blip size |
TargetBlipDistance | 60.0 | Target blip range |
LeaderboardSize / LeaderboardCache | 5 / 60 | Leaderboard |
ClerkModel | s_m_m_valdeputy_01 | Clerk ped |
Offices | list | Valentine, Rhodes, Blackwater, Saint Denis: id, label (locale key), coords, blip |
Tiers | table | Per tier: label, rewardAlive {min,max}, deadMultiplier, gang {min,max}, behaviour (flee/fight), accuracy, models, weapons |
Webhook URLs and the test command are in server/sv_config.lua.
4. Events and commands#
| Name | Side | Notes |
|---|---|---|
rsg-bountyhunter:server:getBoard | callback | (officeId) |
rsg-bountyhunter:server:accept | callback | (officeId, posterId) |
rsg-bountyhunter:server:abandon | callback | Abandon the current contract |
rsg-bountyhunter:server:registerTarget | server event | (netId) the spawned outlaw |
rsg-bountyhunter:server:turnIn | callback | (officeId) |
rsg-bountyhunter:client:startContract | client event | (data) |
rsg-bountyhunter:client:endContract | client event | (reason) ('cancelled' = reputation poster closed, no cooldown) |
rsg-bountyhunter:client:startPlayerContract | client event | (data) { name }, contract on a real player |
rsg-bountyhunter:client:trackArea | client event | (area) { x, y, z, radius }, moves the search-area blip |
rsg-bountyhunter:client:isRestrained | client callback | Server asks the target's client if they are hogtied |
rsg-reputation:server:honorChanged | server event (listened to) | (src, new, old, reason) fired by rsg-reputation, re-checks the player |
| Command | Who | What |
|---|---|---|
/abandonbounty | everyone | Abandon your current contract |
/bountywebhooktest | admin | Send a test Discord embed (name from sv_config.lua, false disables) |
5. Database#
CREATE TABLE IF NOT EXISTS `rsg_bountyhunter` (
`citizenid` VARCHAR(50) NOT NULL,
`name` VARCHAR(100) NOT NULL DEFAULT '',
`completed` INT NOT NULL DEFAULT 0,
`alive` INT NOT NULL DEFAULT 0,
`dead` INT NOT NULL DEFAULT 0,
`earned` INT NOT NULL DEFAULT 0,
PRIMARY KEY (`citizenid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
Created automatically on first start; install.sql is the manual option.
6. Security#
The server owns the board and contracts. It checks distance to the clerk, the job lock, that the target is the registered entity within DeliverRadius, the minimum hunt time, contract expiry and cooldowns, and computes the payout itself.
7. How-tos#
- Job-lock the script:
RequiredJob = 'bountyhunter'. - Add an office: add an
Officesentry with a uniqueidand a locale label. - Make tiers harder: raise
accuracyor thegangrange.
8. Troubleshooting#
| Problem | Fix |
|---|---|
| Clerk missing | Move within ClerkSpawnDistance; check coords |
| Can't accept | Cooldown after abandon/fail, or a job lock |
| Turn-in refused | Target must be within DeliverRadius of the office and the hunt long enough |
| Poster gone | Another hunter took it, or the board re-rolled |
| Player never gets a poster | rsg-reputation not started, honor above Threshold, lawman job type, jailed, or on the repost cooldown |
| "The target must be dead, hogtied or cuffed" | Hogtie or cuff the target (or kill them) and keep them at the office; a dead player must not have respawned yet |
Sponsored posters (server export)#
exports['rsg-bountyhunter']:PostBounty(opts) lets another resource (rsg-gangs uses it) put a poster on every board. opts = { ref, reward, sponsor, expireMinutes, targetCitizenid, targetGang, targetName, sponsorGang }: ref is any unique value the caller uses to settle it, reward is the alive reward (dead pays the tier's deadMultiplier), sponsor is shown next to the crime, expireMinutes defaults to 360. Without a target the poster is a normal NPC contract. With targetCitizenid the hunter must bring in that player; with targetGang (an rsg-gangs gang name) any online member of that gang counts. Both follow a moving search area on the hunter's map and are turned in dead, hogtied or cuffed at an office, like reputation bounties. targetName is the name shown on the board and sponsorGang is the gang that cannot take its own bounty; hunters can never take a bounty on their own gang or on themselves. Gang membership is read from rsg-gangs (GetPlayerGang, GetGangOnlineSources). Returns the poster id or nil.
The caller holds the money in escrow. When the poster ends the server fires rsg-bountyhunter:server:posterClosed(ref, reason, paid) (server-only, not callable by clients) with reason 'completed' (hunter was paid paid) or 'expired' (nobody delivered it). A sponsored poster that is abandoned or failed goes back on the board; sponsored posters are never re-rolled.
Reputation bounties#
Needs rsg-reputation (optional). Config in Config.ReputationBounty, see the README table for every option.
Posting. evaluateRep(src) runs when rsg-reputation fires rsg-reputation:server:honorChanged, 5 seconds after a character loads, and for every online player each SweepSeconds (jail, honor decay and cooldown expiry raise no honor event). It reads exports['rsg-reputation']:GetHonor(src):
- no poster and honor <=
Thresholdand eligible: a sponsored poster (tier 3, character name, crimecrime_reputation,playerTarget = citizenid) is added to the board - poster exists and honor <=
ClearAbove: an untaken poster's reward is updated - poster exists and honor >
ClearAbove, or the player became ineligible (exempt job, jailed): the poster is removed and a hunter holding it is released without a cooldown
Eligibility: not an ExemptJobTypes job type, not jailed (metadata.injail, when SkipJailed), not on the RepostCooldownMinutes cooldown. The poster is also removed when the character logs out or disconnects. Reputation posters are kept in memory only, so no database table is added; they are re-created from honor after a restart.
Hunting. accept rejects your own poster, a target who is no longer online and (with BlockSameGang) a member of your own gang. No outlaw is spawned. Every TrackSeconds the server sends client:trackArea with the target's position plus a fixed random offset inside TrackRadius.
Turn-in. turnIn runs turnInPlayer: the target must be online and not jailed, within DeliverRadius of the office, the hunt must have lasted MinHuntSeconds, and the target must be secured:
- dead:
metadata.isdead(set by rsg-medic) - alive:
metadata.ishandcuffed(rsg-lawman), or hogtied as reported by the target's own client throughrsg-bountyhunter:client:isRestrained
The contract and poster are removed before the money is paid. The target gets the repost cooldown, the hunter's stats are updated and the normal rsg-reputation bounty_delivered action is applied to the hunter.
Export. exports['rsg-bountyhunter']:IsReputationWanted(citizenid) returns true while that character has a reputation poster on the board.
Trust model. Everything is decided on the server. The only client-reported fact is "hogtied", asked of the target's own client: a target can only lose by lying, and the hunter cannot influence the answer.
rsg-reputation integration#
Config.Reputation = { Enabled, Action, Regions }. After the server has paid the reward in turnIn, it calls exports['rsg-reputation']:ApplyAction(src, Action, region) where region = Regions[office.id] or office.id. The default saintdenis office id is mapped to saint_denis. The honor and standing amounts live in rsg-reputation's Config.Actions. Skipped when rsg-reputation is not started.
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-bountyhunter 3.1.0. Names, arguments and defaults below are read straight from the code.
Dependencies#
rsg-core, rsg-target, oxmysql
Database#
Tables: rsg_bountyhunter.
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#
| Option | Default | Notes |
|---|---|---|
Config.AutoDatabase | true | build the database tables automatically on start (set false and import the SQL file for a manual install) |
Config.Debug | false | prints distance checks to the server console |
Config.RequiredJob | nil | e.g. 'bountyhunter' to job-lock contracts (checked on the server), nil = anyone |
Config.MoneyType | 'cash' | paid with Player.Functions.AddMoney |
Config.BoardSize | 6 | posters shown on the board at once |
Config.RefreshMinutes | 30 | board re-rolls unclaimed posters this often |
Config.ContractMinutes | 30 | time to bring the target in before the contract expires |
Config.WarnMinutes | 5 | warn the hunter when this many minutes are left |
Config.AcceptCooldown | 120 | seconds before another contract can be taken after abandon/fail/expiry |
Config.MinHuntSeconds | 60 | anti-exploit: minimum time between finding the target and turning it in |
Config.AbandonCommand | 'abandonbounty' | abandon the current contract from anywhere, false to disable |
Config.InteractDistance | 3.0 | rsg-target reach to the clerk |
Config.ServerCheckDistance | 10.0 | server-side radius around the office coords (keep larger than InteractDistance) |
Config.DeliverRadius | 12.0 | target must be within this distance of the office to turn in |
Config.ClerkSpawnDistance | 60.0 | clerk peds only exist while a player is this close |
Config.SpawnDistance | 150.0 | outlaws spawn when the hunter gets this close to the hideout |
Config.SearchRadius | 120.0 | size of the search area blip (hideout is somewhere inside) |
Config.TargetBlipDistance | 60.0 | target gets a bounty blip when the hunter is this close |
Config.LeaderboardSize | 5 | |
Config.LeaderboardCache | 60 | seconds to cache the leaderboard query |
Config.ClerkModel | 's_m_m_valdeputy_01' | data/rdr3_discoveries/peds/peds_list.lua |
Config.Offices | table | |
Config.OfficeBlipSprite | -693644997 | blip sprite hash: blip_ambient_sheriff (data/rdr3_discoveries/useful_info_from_rpfs/textures/blips/README.md) |
Config.Hideouts | table | |
Config.Tiers | table | |
Config.FirstNames | { 'Jebediah', 'Silas', 'Amos', 'Cletus', 'Ezra', 'Horace', 'Virgil', ' | random poster names (proper nouns, not translated) and crimes (locale keys in locales/*.json) |
Config.LastNames | { 'Crane', 'Hollister', 'McCready', 'Thorne', 'Pike', 'Vance', 'Dutton | |
Config.Crimes | table | |
Config.ReputationBounty | table | Reputation bounties (optional): auto-post players whose honor is low; every option is listed in the README |
Config.Reputation | table | rsg-reputation integration (optional). Needs the rsg-reputation resource; does nothing when it is not started. |
Config.Enabled | true | |
Config.Action | 'bounty_delivered' | |
Config.Regions | { saintdenis = 'saint_denis' } | office id -> rsg-reputation region id (an id that is not listed here is used as it is) |
Callbacks#
| Callback | Side | Arguments | File |
|---|---|---|---|
rsg-bountyhunter:server:getBoard | server | src, cb, officeId | server/server.lua |
rsg-bountyhunter:server:accept | server | src, cb, officeId, posterId | server/server.lua |
rsg-bountyhunter:server:abandon | server | src, cb | server/server.lua |
rsg-bountyhunter:server:turnIn | server | src, cb, officeId | server/server.lua |
rsg-bountyhunter:client:isRestrained | client | cb | client/client.lua |
-- client side
RSGCore.Functions.TriggerCallback('rsg-bountyhunter:server:getBoard', function(result)
-- use result
end, officeId)
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.
| Event | Side | Arguments | File |
|---|---|---|---|
rsg-bountyhunter:client:startContract | client | data | client/client.lua |
rsg-bountyhunter:client:endContract | client | reason | client/client.lua |
rsg-bountyhunter:client:startPlayerContract | client | data | client/client.lua |
rsg-bountyhunter:client:trackArea | client | area | client/client.lua |
RSGCore:Client:OnPlayerUnload | client | `` | client/client.lua |
rsg-bountyhunter:server:registerTarget | server | netId | server/server.lua |
-- from a client script
TriggerServerEvent('rsg-bountyhunter:server:registerTarget', netId)
-- from a server script
TriggerClientEvent('rsg-bountyhunter:client:startContract', source, data)
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".