All resources

rsg-deliveries — Technical Documentation#

Version 3.2.0. For installation and the full configuration tables see README.md.

Contents#

  1. Architecture
  2. Delivery flow
  3. Events and callbacks
  4. Shared helpers
  5. Data formats
  6. Security model
  7. Persistence
  8. Server owner how-tos
  9. Troubleshooting

Architecture#

FileSidePurpose
shared/config.luasharedAll settings, hubs and routes (Config)
shared/functions.luasharedGetRouteDistance, CalculateCashReward (client uses them for the UI preview, server for the payout)
client/npcs.luaclientForeman NPCs (rsg-target), NUI contract board
client/client.luaclientHub blips, wagon spawn, delivery loop (timer, marker, wagon health, arrival), /canceldelivery
server/server.luaserverStart validation, wagon registration, completion checks, rewards, webhook
server/sv_config.luaserverSvConfig.Webhook (never sent to clients)
server/versionchecker.luaserverVersion check against GitHub
html/NUIContract board
locales/*.jsonshareden, 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#

  1. Player targets a foreman → the NUI board opens with every route from that hub.
  2. NUI start → client loads the wagon model and awaits the rsg-deliveries:server:startdelivery callback with the hub and route indexes only.
  3. Server validates (see Security model), stores the active delivery and returns true.
  4. Client spawns the networked wagon, waits for it to be networked and sends its net id with rsg-deliveries:server:setwagon.
  5. 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.
  6. Client loop runs until the wagon is within Config.CompleteDistance of the drop-off (and the player within that + 5m), then sends rsg-deliveries:server:completedelivery with the wagon net id and deletes its wagon 3 seconds later.
  7. 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#

NameArgumentsReturns
rsg-deliveries:server:startdeliveryhubIndex, destIndextrue if the delivery was started, otherwise false

Server events (sent by the client)#

EventArgumentsDescription
rsg-deliveries:server:setwagonnetIdRegisters the spawned wagon for the active delivery. Accepted once per delivery.
rsg-deliveries:server:completedeliverynetIdRequests completion. The net id is only used if no wagon was registered at the start, and is fully re-validated.
rsg-deliveries:server:canceldeliverynoneCancels the active delivery (cooldown applies, wagon deleted)
rsg-deliveries:server:faildeliveryreasontimeout, 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#

CallbackDataDescription
closenoneCloses 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, CanAddItem is checked before AddItem.

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's multiplier / price, and the Config.MaxRewardAmount cap.
  • Turn off the wagon check: Config.RequireWagonAtDestination = false (for servers without OneSync).
  • Discord logs: set SvConfig.Webhook.url in server/sv_config.lua.
  • Rename a wagon in the UI: add it to Config.WagonLabels.

Troubleshooting#

ProblemCause / fix
"You need to bring the wagon to the drop-off" while in the wagon, no rewardFixed 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 registeredThe 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 givenThe item is missing from rsg-core shared items (console prints a warning), or the inventory was full
No webhook messagesSvConfig.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.

<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->

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#

OptionDefaultNotes
Config.Bliptable
Config.DistanceSpawn20.0
Config.FadeIntrue
Config.SpawnVehDistance5.0check to see if another cart has spawned
Config.DestinationMarkertrue
Config.UIPosition"top-center"rsg-core DrawText position (left, right, top-center)
Config.ShowDeliveryTimerUIfalsetoggle the rsg-core text UI for the delivery timer on/off
Config.FadeIncrement51alpha fade increment
Config.DefaultDeliveryTime30default delivery time limit in minutes
Config.MaxRewardAmount500maximum cash reward to prevent exploitation
Config.InteractionDistance2.0NPC interaction distance
Config.CompleteDistance10.0how close the wagon must be to the drop-off to complete
Config.DeliveryCooldown60seconds a player must wait between deliveries (0 = off)
Config.MaxAverageSpeed25.0m/s; deliveries finished faster than distance / this are rejected (teleport check)
Config.RequireWagonAtDestinationtrueserver checks the delivery wagon is actually at the drop-off (needs OneSync)
Config.ShowRewardImagestrueshow 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.WagonLabelstablefriendly wagon names shown in the UI (falls back to the model name)
Config.RewardPerDistance0.01Cash reward per meter traveled (e.g., 0.05 = $0.05 per meter)
Config.BaseReward0Base reward given regardless of distance
Config.DeliveryLocationstable
Config.Reputationtablersg-reputation integration (optional). Needs the rsg-reputation resource; does nothing when it is not started.
Config.Enabledtrue
Config.Action'delivery'
Config.Regionstabledelivery hub label -> rsg-reputation region that gains standing (hubs not listed give honor only)

Callbacks#

CallbackSideArgumentsFile
rsg-deliveries:server:startdeliveryserversrc, cb, hubIndex, destIndexserver/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.

EventSideArgumentsFile
rsg-deliveries:server:setwagonservernetIdserver/server.lua
rsg-deliveries:server:completedeliveryserverclientNetIdserver/server.lua
rsg-deliveries:server:canceldeliveryserver``server/server.lua
rsg-deliveries:server:faildeliveryserverreasonserver/server.lua
-- from a client script
TriggerServerEvent('rsg-deliveries:server:setwagon', netId)

Commands#

CommandNotesFile
/canceldeliveryclient/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".

<!-- END AUTO-REFERENCE -->