All resources

rsg-treasure – Developer Docs#

Flow#

  1. Player uses Config.MapItem → server picks a free location, stores hunts[citizenid] = { idx, centre }, sends rsg-treasure:client:startHunt(loc, centre).
  2. Client draws the search circle and, while the detector is held inside it, drives the detector blackboard value, the NUI signal meter and the bleep.
  3. At Config.PinpointDistance the [J] dig prompt appears (within Config.DigDistance).
  4. Pressing [J] → callback rsg-treasure:server:digStart (checks hunt, distance, map, detector, tool; starts the server dig timer). Only on true does the anim scene play.
  5. After the anim → callback rsg-treasure:server:dig pays out, then rsg-treasure:client:endHunt.

Server security#

  • All rewards are rolled and given server-side; the client sends no arguments.
  • Payout needs a digStart at least Config.DigTime - 1500 ms earlier, a server-side distance check, and a per-player Config.Cooldown.
  • Loot is rolled and CanAddItem-checked before the map is removed. If any item won't fit, nothing is taken.
  • The map is removed before cash/items are given, so a payout can't be claimed twice.
  • Known limitation: the client receives the exact dig coords (the detector needs them for distance). Cheaters could read them, but they still need the map, the detector, the full dig time and to be in range.

Events / callbacks#

NameSidePurpose
rsg-treasure:client:startHuntclient(loc, centre) start/redisplay a hunt
rsg-treasure:client:endHuntclientclean up blips, chest, NUI
rsg-treasure:server:resumeserverresend the active hunt (on player loaded / resource start)
rsg-treasure:server:digStartcallbackpre-dig validation + timer → bool
rsg-treasure:server:digcallbackpayout → bool

Exports#

  • exports['rsg-treasure']:SendLog(channel, title, description, color, src?, fields?) (server)

Config#

See shared/config.lua (gameplay) and server/sv_config.lua (webhooks, server only).

Changelog#

3.1.0#

  • Removed ox_lib: rsg-core locales, notify and callbacks.
  • Dig is validated before the animation (no more full dig then refusal).
  • A full inventory no longer destroys loot: nothing is consumed and the player can retry.
  • Hunts resume after relog / resource restart.
  • Detector native only called when the value changes.
  • Removed unused locale keys (log_inv_full, log_loot_lost, log_no) and the inventory-full log field.
<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->

Technical reference#

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

Dependencies#

rsg-core, rsg-inventory

Configuration#

OptionDefaultNotes
Config.MapItem'treasure_map'usable item that starts a hunt
Config.RequiredItemnile.g. 'shovel' to require a tool, nil = none
Config.DetectorWEAPON_KIT_METAL_DETECTORfemga weapons/weapons.lua
Config.DetectorItem'weapon_kit_metal_detector'inventory item name (server check)
Config.DetectRange40.0detector starts picking up signal at this distance
Config.PinpointDistance2.5signal maxes out & strongbox can be dug here
Config.BleeptableBleep (played via NUI so volume can scale with distance)
Config.SearchRadius120.0size of the search circle on the map
Config.DigKey0xF3830D8E[J] INPUT_OPEN_JOURNAL
Config.DigDistance3.0server-checked max distance to dig
Config.DigTime10000ms (length of the dig-up-chest anim scene)
Config.ChestRevealDelay3000ms into the dig before the strongbox becomes visible
Config.Cooldown10seconds between digs per player (anti-spam)
Config.ChestModelp_strongbox_muddy_01xfemga objects/object_list.lua
Config.DigAnim{ dict = 'script@mech@treasure_hunting@chest', playlist = 'PBL_CHEST_0anim scene (old rsg-treasure)
Config.BlipSpriteBLIP_RC_TREASURE_HUNTER1491.50 treasure_hunter.c
Config.Cash{ min = 15, max = 60 }Cash reward (server rolls this)
Config.RewardstableItem rewards: each has its own chance (0-100)
Config.LocationstablePossible treasure spots (exact dig points; the blip circle is offset so it isn't given away)

Exports#

Server

ExportArgumentsFile
SendLog``server/webhook.lua
-- example
local result = exports['rsg-treasure']:SendLog()

Callbacks#

CallbackSideArgumentsFile
rsg-treasure:server:digStartserversrc, cbserver/server.lua
rsg-treasure:server:digserversrc, cbserver/server.lua
-- client side
RSGCore.Functions.TriggerCallback('rsg-treasure:server:digStart', 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-treasure:client:startHuntclientloc, centreclient/client.lua
rsg-treasure:client:endHuntclient``client/client.lua
RSGCore:Client:OnPlayerLoadedclient``client/client.lua
RSGCore:Client:OnPlayerUnloadclient``client/client.lua
rsg-treasure:server:resumeserver``server/server.lua
-- from a client script
TriggerServerEvent('rsg-treasure:server:resume')
-- from a server script
TriggerClientEvent('rsg-treasure:client:startHunt', source, loc, centre)

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