All resources

rsg-bountyhunter – Docs (v3.3.0)#

Contents#

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

1. Files#

FilePurpose
fxmanifest.luaManifest; depends on rsg-core, rsg-target, oxmysql
shared/config.luaBoard, timers, distances, offices, tiers
client/client.luaClerks, NUI board, hideout and outlaw spawning, blips
server/server.luaBoard, contracts, turn-in, stats, leaderboard
server/sv_config.lua, server/webhooks.luaWebhook settings and Discord embeds
server/versionchecker.luaGitHub version check
html/NUI wanted board (leather and gold style)
install.sqlManual database install
locales/*.jsonen, de, el, es, fr, ja, nl, pl, pt-br, ro, ru

2. How it works#

  1. Talk to the clerk NPC (rsg-target) at a sheriff's office: View Bounties or Turn In Bounty.
  2. 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.
  3. 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.
  4. A bounty-target blip shows when you are close, and is marked incapacitated once the target is dead or hogtied.
  5. Bring the target to any office. Alive pays the full reward; dead pays deadMultiplier of it.
  6. Contracts have a time limit with a warning, an abandon option (NUI or /abandonbounty) and a cooldown before the next one.
  7. Personal stats and a Top Hunters leaderboard (cached).
  8. 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:

OptionDefaultMeaning
DebugfalsePrint distance checks
RequiredJobnilJob lock for contracts (server checked)
MoneyType'cash'Reward account
BoardSize6Posters on the board
RefreshMinutes30Board re-roll interval
ContractMinutes30Time to bring the target in
WarnMinutes5Warning before expiry
AcceptCooldown120Seconds before another contract after abandon/fail/expiry
MinHuntSeconds60Anti-exploit minimum between finding and turning in
AbandonCommand'abandonbounty'false to disable
InteractDistance / ServerCheckDistance / DeliverRadius3.0 / 10.0 / 12.0Distances
ClerkSpawnDistance60.0Clerk spawn range
SpawnDistance150.0Outlaws spawn when you are this close
SearchRadius120.0Search area blip size
TargetBlipDistance60.0Target blip range
LeaderboardSize / LeaderboardCache5 / 60Leaderboard
ClerkModels_m_m_valdeputy_01Clerk ped
OfficeslistValentine, Rhodes, Blackwater, Saint Denis: id, label (locale key), coords, blip
TierstablePer 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#

NameSideNotes
rsg-bountyhunter:server:getBoardcallback(officeId)
rsg-bountyhunter:server:acceptcallback(officeId, posterId)
rsg-bountyhunter:server:abandoncallbackAbandon the current contract
rsg-bountyhunter:server:registerTargetserver event(netId) the spawned outlaw
rsg-bountyhunter:server:turnIncallback(officeId)
rsg-bountyhunter:client:startContractclient event(data)
rsg-bountyhunter:client:endContractclient event(reason) ('cancelled' = reputation poster closed, no cooldown)
rsg-bountyhunter:client:startPlayerContractclient event(data) { name }, contract on a real player
rsg-bountyhunter:client:trackAreaclient event(area) { x, y, z, radius }, moves the search-area blip
rsg-bountyhunter:client:isRestrainedclient callbackServer asks the target's client if they are hogtied
rsg-reputation:server:honorChangedserver event (listened to)(src, new, old, reason) fired by rsg-reputation, re-checks the player
CommandWhoWhat
/abandonbountyeveryoneAbandon your current contract
/bountywebhooktestadminSend 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 Offices entry with a unique id and a locale label.
  • Make tiers harder: raise accuracy or the gang range.

8. Troubleshooting#

ProblemFix
Clerk missingMove within ClerkSpawnDistance; check coords
Can't acceptCooldown after abandon/fail, or a job lock
Turn-in refusedTarget must be within DeliverRadius of the office and the hunt long enough
Poster goneAnother hunter took it, or the board re-rolled
Player never gets a posterrsg-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

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 <= Threshold and eligible: a sponsored poster (tier 3, character name, crime crime_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 through rsg-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#

OptionDefaultNotes
Config.AutoDatabasetruebuild the database tables automatically on start (set false and import the SQL file for a manual install)
Config.Debugfalseprints distance checks to the server console
Config.RequiredJobnile.g. 'bountyhunter' to job-lock contracts (checked on the server), nil = anyone
Config.MoneyType'cash'paid with Player.Functions.AddMoney
Config.BoardSize6posters shown on the board at once
Config.RefreshMinutes30board re-rolls unclaimed posters this often
Config.ContractMinutes30time to bring the target in before the contract expires
Config.WarnMinutes5warn the hunter when this many minutes are left
Config.AcceptCooldown120seconds before another contract can be taken after abandon/fail/expiry
Config.MinHuntSeconds60anti-exploit: minimum time between finding the target and turning it in
Config.AbandonCommand'abandonbounty'abandon the current contract from anywhere, false to disable
Config.InteractDistance3.0rsg-target reach to the clerk
Config.ServerCheckDistance10.0server-side radius around the office coords (keep larger than InteractDistance)
Config.DeliverRadius12.0target must be within this distance of the office to turn in
Config.ClerkSpawnDistance60.0clerk peds only exist while a player is this close
Config.SpawnDistance150.0outlaws spawn when the hunter gets this close to the hideout
Config.SearchRadius120.0size of the search area blip (hideout is somewhere inside)
Config.TargetBlipDistance60.0target gets a bounty blip when the hunter is this close
Config.LeaderboardSize5
Config.LeaderboardCache60seconds to cache the leaderboard query
Config.ClerkModel's_m_m_valdeputy_01'data/rdr3_discoveries/peds/peds_list.lua
Config.Officestable
Config.OfficeBlipSprite-693644997blip sprite hash: blip_ambient_sheriff (data/rdr3_discoveries/useful_info_from_rpfs/textures/blips/README.md)
Config.Hideoutstable
Config.Tierstable
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.Crimestable
Config.ReputationBountytableReputation bounties (optional): auto-post players whose honor is low; every option is listed in the README
Config.Reputationtablersg-reputation integration (optional). Needs the rsg-reputation resource; does nothing when it is not started.
Config.Enabledtrue
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#

CallbackSideArgumentsFile
rsg-bountyhunter:server:getBoardserversrc, cb, officeIdserver/server.lua
rsg-bountyhunter:server:acceptserversrc, cb, officeId, posterIdserver/server.lua
rsg-bountyhunter:server:abandonserversrc, cbserver/server.lua
rsg-bountyhunter:server:turnInserversrc, cb, officeIdserver/server.lua
rsg-bountyhunter:client:isRestrainedclientcbclient/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.

EventSideArgumentsFile
rsg-bountyhunter:client:startContractclientdataclient/client.lua
rsg-bountyhunter:client:endContractclientreasonclient/client.lua
rsg-bountyhunter:client:startPlayerContractclientdataclient/client.lua
rsg-bountyhunter:client:trackAreaclientareaclient/client.lua
RSGCore:Client:OnPlayerUnloadclient``client/client.lua
rsg-bountyhunter:server:registerTargetservernetIdserver/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".

<!-- END AUTO-REFERENCE -->