All resources

rsg-herbalist – Developer & Server Owner Docs#

Version 3.1.0 · Requires rsg-core (3.0.3+) and rsg-inventory. No ox_lib, no database tables.

Contents#

  1. Architecture
  2. Data formats
  3. Exports
  4. Events
  5. Usable items
  6. Persistence
  7. Security model
  8. Server owner how-tos
  9. Troubleshooting

Architecture#

FileSidePurpose
shared/config.luasharedGameplay config, tonic recipes, mystery box
shared/webhook_config.luasharedDiscord webhook categories
shared/zones_data.luasharedConfig.Zones – herb zones (plant rotation + coords)
shared/spawns.luasharedBuildHerbSpawns() – deterministic spawn list used by both sides; StripComposite()
client/exports.jsclientNativeCreateComposite export (needs a JS buffer arg)
client/controls.luaclientIsPickupControlPressed() shared by herbs + mystery box
client/client.luaclientHerb streaming/gathering, crafting NUI, crafting anim/camera, tonic drinking
client/mysterybox.luaclientMystery box prop, prompt (rsg-core DrawText), open flow
server/webhook.luaserverQueued Discord logger + anti-cheat violation counter (Webhook.*)
server/server.luaserverGather validation, regrowth, crafting, tonic use
server/mysterybox.luaserverBox location, loot rolls, open validation
server/versionchecker.luaserverGitHub version check (also logged to the version webhook)
html/NUITonic crafting menu (house leather & gold theme)

Herb nodes are identified on the network by their integer index from BuildHerbSpawns() (zones sorted by id, coords in file order). Client and server must run the same zones_data.lua.

Data formats#

Tonic recipe (Config.Tonics[n]):

{ id = 'tonic_healing', label = 'locale_key', description = 'locale_key', image = 'tonic_healing.png',
  durationMs = 8000, ingredients = { { item = 'herb_yarrow', amount = 2 } },
  output = { item = 'tonic_healing', amount = 1 } }

Tonic effect (Config.TonicEffects[itemName]): { healthBoost = 0.0–1.0, staminaBoost = 0.0–1.0 } – applied via ENABLE_ATTRIBUTE_OVERPOWER (0xF6A7C08DF2E28B28).

Plant → item mapping: the toItem table at the top of server/server.lua, keyed by the composite name without COMPOSITE_LOOTABLE_ / _INTERACTABLE. Mappings to unregistered items are dropped (with a console warning) on start.

Exports#

ExportSideParamsReturns
NativeCreateComposite(hash, x, y, z, onGround)clientcomposite hash, coords, boolcomposite handle (internal use)

There is intentionally no export/command to open the crafting menu – the mortarpestle item is the only entry point.

Events#

Client → server (all validated server-side):

EventArgsValidation
rsg-herbalist:server:gatheredid (number)spawn exists, not already picked, cooldown, alive, distance ≤ ScopeRangeGather, CanAddItem
rsg-herbalist:server:requestSync–throttled 10 s
rsg-herbalist:server:requestCrafttonicId (string)enabled, alive, no pending craft, cooldown, job lock, recipe exists, ingredients
rsg-herbalist:server:finishCraft–pending craft exists, recipe time elapsed, ingredients re-checked, CanAddItem
rsg-herbalist:server:cancelCraft–clears pending craft
rsg-herbalist:server:requestMysteryBox–throttled 10 s
rsg-herbalist:server:openMysteryBox–box live, cooldown, alive, distance ≤ scopeRangeGather, free weight + CanAddItem

Server → client: client:SetSuppressed(id, suppressed, newPlant), client:SyncState(ids, overrides), client:ForceReload(id), client:OpenTonicCrafting(), client:StartCraftProgress(durationMs), client:ApplyTonicEffect(itemName), client:SetMysteryBox(coord|nil).

Usable items#

  • mortarpestle – opens the crafting menu (job lock checked on the server).
  • Every key in Config.TonicEffects – drinks the tonic (shared TonicUseCooldownMs).

Persistence#

Nothing is stored in the database. Picked nodes, plant rotation and the box location live in server memory and reset on resource restart. Items are written through rsg-inventory exports (which also show the ItemBox and log with a reason: rsg-herbalist:gather|craft|craft-refund|drink-tonic|mysterybox).

Security model#

  • The client only ever sends ids; items, amounts, recipes, durations and loot are decided from server config.
  • Crafting removes ingredients only at finishCraft, after the server confirms the recipe duration elapsed – cancelling/disconnecting loses nothing and a client can't skip the timer.
  • Rejected requests call Webhook.FlagSuspicious; a Discord alert fires once a player reaches antiCheat.violationThreshold in violationWindowMs. Nobody is auto-banned (single violations are often lag).
  • Other scripts calling these events get no extra trust – the same checks apply.

Server owner how-tos#

  • Add a tonic: add a recipe to Config.Tonics, its item to rsg-core items, an icon to the inventory images, label/description keys to all 11 locales, and optionally an entry in Config.TonicEffects.
  • Add herb spots: add coords to a zone in shared/zones_data.lua (restart the resource; ids are rebuilt).
  • Job-lock crafting: create herbalist via /jobadmin, set Config.LockTonicCraftingToJob = true.
  • Change language: setr rsg:locale de in server.cfg.

Troubleshooting#

SymptomFix
warning: item "x" ... is not registeredAdd the item to rsg-core items or fix the toItem mapping
no item mapping for plant ...Add the composite to toItem in server/server.lua
Crafting icons missingCopy installation/images into rsg-inventory images or change Config.InventoryImagePath
Webhooks silentSet Config.Webhook.enabled, the category enabled and its url
Mystery box never appearsConfig.MysteryBox.enabled and at least one entry in coords

rsg-skills integration#

Config.Skills = { Enabled, Skill, GatherXP, ExtraYield }. In rsg-herbalist:server:gathered, after the herb is added and the node suppressed, the server calls AddXP(src, 'herbalism', GatherXP, ...) and, when ExtraYield is on, rolls the extra_yield perk for one more herb (only if CanCarry). Server side only; skipped when rsg-skills 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-herbalist 3.2.0. Names, arguments and defaults below are read straight from the code.

Dependencies#

rsg-core, rsg-inventory

Configuration#

OptionDefaultNotes
Config.Debugfalseleave off in production; verbose per-gather/per-craft tracing
Config.InventoryImagePath'nui://rsg-inventory/html/images/'Where the crafting UI loads item icons from (rsg-inventory's image folder).
Config.ScopeRangeLoad100.0distance at which a herb node starts streaming in
Config.ScopeRangeUnload120.0distance at which a loaded node streams back out
Config.NearbyRange15.0radius refreshed once/sec for interaction checks
Config.PickupRange3.0client-side distance within which a node can be picked
Config.CompositeLoadTimeoutMs10000max time to wait for a composite asset to stream in
Config.GatherDurationMs3000length of the gather progress bar
Config.GatherProgressBarEnabledfalsecancellable.
Config.GatherCooldownMs2500server-side minimum time between gather attempts per player
Config.ScopeRangeGather3.5server-side distance check before a gather is accepted
Config.SuppressionWearoffSeconds10 * 60how long a gathered node stays empty before it regrows
Config.TonicCraftingEnabledtruemaster switch for the tonic crafting system
Config.TonicCraftCooldownMs1500server-side minimum time between craft requests per player
Config.TonicCraftProgressBarEnabledfalsealways completes once that time passes.
Config.TonicCraftAnimtablealways use the generic standing scenario instead.
Config.TonicCraftCameratablethe player is facing or where they are.
Config.TonicAttributeIndextablechanges that ordering. value is 0.0-1.0 (fraction of the core topped up).
Config.TonicDrinkAnimtableDeleted automatically once the clips finish.
Config.TonicEffectstabletonic. Tonics not listed here do nothing extra when consumed.
Config.TonicUseCooldownMs5 * 60 * 10005 minutes
Config.LockTonicCraftingToJobfalsethe database via rsg-core's /jobadmin (see installation/shared_jobs.lua for grades).
Config.TonicCraftingJobName'herbalist'
Config.MysteryBoxtable
Config.Tonicstableoutput { item = <inventory item name>, amount = <amount granted> }
Config.Skillstablersg-skills integration (optional). Needs the rsg-skills resource; does nothing when it is not started.
Config.Enabledtrue
Config.Skill'herbalism'
Config.GatherXP5
Config.ExtraYieldtrue
Config.Webhooktable
Config.Zonestable

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-herbalist:client:SetSuppressedclientid, suppress, newPlantclient/client.lua
rsg-herbalist:client:SyncStateclientsuppressedIds, plantOverridesclient/client.lua
rsg-herbalist:client:ForceReloadclientidclient/client.lua
RSGCore:Player:SetPlayerDataclientdataclient/client.lua
rsg-herbalist:client:OpenTonicCraftingclient``client/client.lua
rsg-herbalist:client:StartCraftProgressclientdurationMsclient/client.lua
rsg-herbalist:client:ApplyTonicEffectclientitemNameclient/client.lua
rsg-herbalist:client:SetMysteryBoxclientcoordclient/mysterybox.lua
rsg-herbalist:server:requestMysteryBoxserver``server/mysterybox.lua
rsg-herbalist:server:openMysteryBoxserver``server/mysterybox.lua
rsg-herbalist:server:gatheredserveridserver/server.lua
rsg-herbalist:server:requestSyncserver``server/server.lua
rsg-herbalist:server:requestCraftservertonicIdserver/server.lua
rsg-herbalist:server:finishCraftserver``server/server.lua
rsg-herbalist:server:cancelCraftserver``server/server.lua
-- from a client script
TriggerServerEvent('rsg-herbalist:server:requestMysteryBox')
-- from a server script
TriggerClientEvent('rsg-herbalist:client:SetSuppressed', source, id, suppress, newPlant)

Useable items#

mortarpestle

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