rsg-deliveries — Technical Documentation#
Version 3.2.0. For installation and the full configuration tables see README.md.
Contents#
- Architecture
- Delivery flow
- Events and callbacks
- Shared helpers
- Data formats
- Security model
- Persistence
- Server owner how-tos
- Troubleshooting
Architecture#
| File | Side | Purpose |
|---|---|---|
shared/config.lua | shared | All settings, hubs and routes (Config) |
shared/functions.lua | shared | GetRouteDistance, CalculateCashReward (client uses them for the UI preview, server for the payout) |
client/npcs.lua | client | Foreman NPCs (rsg-target), NUI contract board |
client/client.lua | client | Hub blips, wagon spawn, delivery loop (timer, marker, wagon health, arrival), /canceldelivery |
server/server.lua | server | Start validation, wagon registration, completion checks, rewards, webhook |
server/sv_config.lua | server | SvConfig.Webhook (never sent to clients) |
server/versionchecker.lua | server | Version check against GitHub |
html/ | NUI | Contract board |
locales/*.json | shared | en, de, el, es, fr, ja, nl, pl, pt-br, ro, ru (loaded by rsg-core) |
The resource has no database tables and no exports.
Delivery flow#
- Player targets a foreman → the NUI board opens with every route from that hub.
- NUI
start→ client loads the wagon model and awaits thersg-deliveries:server:startdeliverycallback with the hub and route indexes only. - Server validates (see Security model), stores the active delivery and returns
true. - Client spawns the networked wagon, waits for it to be networked and sends its net id with
rsg-deliveries:server:setwagon. - Server waits up to 10 seconds for that entity to exist server-side, checks its model and distance to the player, and stores the net id.
- Client loop runs until the wagon is within
Config.CompleteDistanceof the drop-off (and the player within that + 5m), then sendsrsg-deliveries:server:completedeliverywith the wagon net id and deletes its wagon 3 seconds later. - Server checks expiry, player position, travel time and the wagon, then pays cash, rolls the item reward and deletes the wagon.
The client fails the contract itself (faildelivery) on timeout, lost wagon, death or an undriveable wagon.
Events and callbacks#
Server callback#
| Name | Arguments | Returns |
|---|---|---|
rsg-deliveries:server:startdelivery | hubIndex, destIndex | true if the delivery was started, otherwise false |
Server events (sent by the client)#
| Event | Arguments | Description |
|---|---|---|
rsg-deliveries:server:setwagon | netId | Registers the spawned wagon for the active delivery. Accepted once per delivery. |
rsg-deliveries:server:completedelivery | netId | Requests completion. The net id is only used if no wagon was registered at the start, and is fully re-validated. |
rsg-deliveries:server:canceldelivery | none | Cancels the active delivery (cooldown applies, wagon deleted) |
rsg-deliveries:server:faildelivery | reason | timeout, damaged_wagon, wagon_lost or player_died (cooldown applies, wagon deleted) |
There are no client net events; the server only sends RSGCore:Client:Notify.
NUI callbacks#
| Callback | Data | Description |
|---|---|---|
close | none | Closes the board |
start | { index } | Starts the route at that index for the hub that was opened |
Shared helpers#
-- distance in metres from the hub's cart spawn to the drop-off (straight line)
local distance = GetRouteDistance(location, destination)
-- cash reward for a route and whether it hit Config.MaxRewardAmount
local cash, capped = CalculateCashReward(location, destination)
These are globals inside the resource only, not exports.
Data formats#
Active delivery (server memory, keyed by player source):
{
destination = <route table from Config>,
cash = 120, -- worked out at the start
distance = 2150.4, -- metres
startedAt = os.time(),
expiry = os.time() + Config.DefaultDeliveryTime * 60,
netId = 1234, -- set once the wagon is registered
}
Hub and route tables are described in the README under Delivery Locations.
Security model#
What the server checks:
- Start: valid indexes, no active delivery, cooldown (
Config.DeliveryCooldown), player within 30m of the hub's cart spawn. - Wagon registration: entity exists on the server, model matches the route's
wagonModel, within 30m of the player. - Completion:
- the delivery is consumed on the first call, so the event cannot be replayed
- not expired
- player within 20m of the drop-off
- elapsed time at least
distance / Config.MaxAverageSpeed(teleport check) - with
Config.RequireWagonAtDestination: the registered wagon exists and is within 20m of the drop-off. If no wagon was registered, the net id sent with the completion is accepted only if the entity has the route's model, was created by that player and is within 20m of the drop-off.
- Rewards: cash and items come from the config on the server, cash is capped at
Config.MaxRewardAmount,CanAddItemis checked beforeAddItem.
Every rejected completion prints a line to the server console with the reason.
Persistence#
Nothing is saved. Active deliveries and cooldowns live in server memory and are cleared when the player drops or the resource restarts. Restarting the resource deletes all delivery wagons.
Server owner how-tos#
- Add a route or hub: copy an existing entry in
Config.DeliveryLocations(README has the field list). - Change payouts:
Config.RewardPerDistance,Config.BaseReward, each route'smultiplier/price, and theConfig.MaxRewardAmountcap. - Turn off the wagon check:
Config.RequireWagonAtDestination = false(for servers without OneSync). - Discord logs: set
SvConfig.Webhook.urlinserver/sv_config.lua. - Rename a wagon in the UI: add it to
Config.WagonLabels.
Troubleshooting#
| Problem | Cause / fix |
|---|---|
| "You need to bring the wagon to the drop-off" while in the wagon, no reward | Fixed in 3.1.1 (the wagon was never registered with the server). If it still happens, the server console prints delivery rejected, wagon check failed (<reason>); check OneSync is on. |
Console: delivery wagon ... was not registered | The wagon never synced to the server within 10 seconds. The delivery can still complete through the arrival check. |
| Delivery silently does nothing at the drop-off, console says "possible teleport" | Completed faster than distance / Config.MaxAverageSpeed. Raise Config.MaxAverageSpeed. |
| "Something is blocking the wagon spawn!" | A vehicle is within Config.SpawnVehDistance of the hub's cartSpawn |
| "The wagon could not be prepared" | The route's wagonModel failed to load or spawn |
| Item reward never given | The item is missing from rsg-core shared items (console prints a warning), or the inventory was full |
| No webhook messages | SvConfig.Webhook.url is empty |
Support#
https://buymeacoffee.com/rexshack
rsg-reputation integration#
Config.Reputation = { Enabled, Action, Regions }. When a delivery starts, the hub's region is looked up by hub label and stored on the active delivery. On completion (wagon validated, cash paid) the server calls ApplyAction(src, 'delivery', region). A hub that is not listed (for example Macfarlanes Ranch) passes no region, so nothing changes because the default delivery action has no honor. Skipped when rsg-reputation is not started.
Technical reference#
Generated from the source of rsg-deliveries 3.2.0. Names, arguments and defaults below are read straight from the code.
Dependencies#
rsg-core, rsg-target, rsg-inventory
Configuration#
| Option | Default | Notes |
|---|---|---|
Config.Blip | table | |
Config.DistanceSpawn | 20.0 | |
Config.FadeIn | true | |
Config.SpawnVehDistance | 5.0 | check to see if another cart has spawned |
Config.DestinationMarker | true | |
Config.UIPosition | "top-center" | rsg-core DrawText position (left, right, top-center) |
Config.ShowDeliveryTimerUI | false | toggle the rsg-core text UI for the delivery timer on/off |
Config.FadeIncrement | 51 | alpha fade increment |
Config.DefaultDeliveryTime | 30 | default delivery time limit in minutes |
Config.MaxRewardAmount | 500 | maximum cash reward to prevent exploitation |
Config.InteractionDistance | 2.0 | NPC interaction distance |
Config.CompleteDistance | 10.0 | how close the wagon must be to the drop-off to complete |
Config.DeliveryCooldown | 60 | seconds a player must wait between deliveries (0 = off) |
Config.MaxAverageSpeed | 25.0 | m/s; deliveries finished faster than distance / this are rejected (teleport check) |
Config.RequireWagonAtDestination | true | server checks the delivery wagon is actually at the drop-off (needs OneSync) |
Config.ShowRewardImages | true | show reward item images in the delivery UI |
Config.ImagePath | 'nui://rsg-inventory/html/images/' | where item images live (uses the item's image from rsg-core shared items) |
Config.WagonLabels | table | friendly wagon names shown in the UI (falls back to the model name) |
Config.RewardPerDistance | 0.01 | Cash reward per meter traveled (e.g., 0.05 = $0.05 per meter) |
Config.BaseReward | 0 | Base reward given regardless of distance |
Config.DeliveryLocations | table | |
Config.Reputation | table | rsg-reputation integration (optional). Needs the rsg-reputation resource; does nothing when it is not started. |
Config.Enabled | true | |
Config.Action | 'delivery' | |
Config.Regions | table | delivery hub label -> rsg-reputation region that gains standing (hubs not listed give honor only) |
Callbacks#
| Callback | Side | Arguments | File |
|---|---|---|---|
rsg-deliveries:server:startdelivery | server | src, cb, hubIndex, destIndex | server/server.lua |
-- client side
RSGCore.Functions.TriggerCallback('rsg-deliveries:server:startdelivery', function(result)
-- use result
end, hubIndex, destIndex)
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-deliveries:server:setwagon | server | netId | server/server.lua |
rsg-deliveries:server:completedelivery | server | clientNetId | server/server.lua |
rsg-deliveries:server:canceldelivery | server | `` | server/server.lua |
rsg-deliveries:server:faildelivery | server | reason | server/server.lua |
-- from a client script
TriggerServerEvent('rsg-deliveries:server:setwagon', netId)
Commands#
| Command | Notes | File |
|---|---|---|
/canceldelivery | client/client.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".