All resources

rsg-ambush – Docs (v3.0.1)#

Contents#

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

1. Files#

FilePurpose
fxmanifest.luaManifest; depends on rsg-core, rsg-inventory, rsg-target
shared/config.luaTriggering, spawning, gangs, loot
client/client.luaRolls, spawning gang peds, blips, loot targets, cleanup
server/server.luaAmbush approval, cooldowns, loot rewards
server/logs.lua, server/sv_config.luaLogging and webhook settings
server/versionchecker.luaGitHub version check
locales/*.jsonen, de, el, es, fr, ja, nl, pl, pt-br, ro, ru

2. How it works#

  • While a player rides outside towns, every CheckInterval seconds there is a TriggerChance% roll. If it hits and the server cooldown allows, a gang ambushes them.
  • Gangs: O'Driscolls, Lemoyne Raiders, Murfree Brood and Skinner Brothers (weighted random). Models, relationship groups, weapons, horses and accuracy/shoot rates follow the single-player ambush_* scripts.
  • The ambush spawns ahead of the player (SpawnDistance), with red enemy blips. It ends when the bandits are dead, the player rides DespawnDistance away, or MaxDuration passes.
  • Bodies stay for CorpseTime seconds. Loot them with rsg-target for cash and items.

3. Configuration#

shared/config.lua:

OptionDefaultMeaning
DebugfalseEnables /testambush and forces 100% chance
CheckInterval60Seconds between rolls
TriggerChance6% per roll
RequireMountedtrueOnly ambush riders
BlockInTownstrueNo ambushes in towns
PlayerCooldown1800Seconds per player (server enforced)
MinPlayerSpeed2.0m/s needed to be ambushed
SpawnDistance{60, 90}m ahead of the player
SpawnSpread12.0m between bandits
DespawnDistance350.0Ambush ends beyond this
MaxDuration600Seconds before cleanup
CorpseTime240Seconds bodies stay
UseBlipstrueEnemy blips
HorseslistBandit horse models
GangstablePer gang: weight, relGroup, models, weapons, accuracy, shoot rate (display names are locale gang_<key>)
LootDistance / LootTime3.0 / 3000Loot range and progress bar
LootCash{1, 8}Dollars per body
LootItemslistItem drops with chances

4. Events and commands#

NameSideNotes
rsg-ambush:server:requestAmbushcallbackServer approves a roll (cooldown, limits)
rsg-ambush:server:registerPedsserver event(id, netIds)
rsg-ambush:server:finishserver event(id)
rsg-ambush:server:lootcallback(id, netId) pays loot once per body
rsg-ambush:client:forceclient eventForce an ambush (debug)
CommandWhoWhat
/testambushadmin, only with Config.DebugTrigger an ambush now

5. Security#

The server enforces the per-player cooldown, tracks the ambush and its peds, and pays loot only for registered bodies, once each, within LootDistance. Inventory space is checked before items are given.

6. How-tos#

  • Make ambushes rarer: lower TriggerChance or raise PlayerCooldown.
  • Test: set Debug = true, then /testambush.
  • Tune gang odds with each gang's weight.

7. Troubleshooting#

ProblemFix
Never ambushedMust be mounted, moving, outside towns and off cooldown
Peds don't fightCheck relGroup for the gang
Can't lootMove within LootDistance; each body pays once
Bandits lingerThey clean up after MaxDuration or DespawnDistance

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-ambush 3.0.1. Names, arguments and defaults below are read straight from the code.

Dependencies#

rsg-core, rsg-inventory, rsg-target

Configuration#

OptionDefaultNotes
Config.Debugfalsetrue = /testambush command + chance forced to 100
Config.CheckInterval60seconds between ambush rolls
Config.TriggerChance6% chance per roll
Config.RequireMountedtrueonly ambush riders (like the SP ambush_* scripts)
Config.BlockInTownstrueno ambushes inside town zones
Config.PlayerCooldown1800seconds (server enforced) between ambushes per player
Config.MinPlayerSpeed2.0m/s, player must be travelling
Config.SpawnDistance{ min = 60.0, max = 90.0 }ahead of the player
Config.SpawnSpread12.0metres between bandits
Config.DespawnDistance350.0player rides this far away = ambush ends
Config.MaxDuration600seconds before a running ambush is cleaned up
Config.CorpseTime240seconds bodies stay for looting after the fight
Config.UseBlipstruered enemy blips (BLIP_STYLE_ENEMY, as in ambush_* scripts)
Config.HorsestableHorse models used by the SP ambush scripts (ambush_*.c, build 1436)
Config.Gangstable
Config.LootDistance3.0
Config.LootTime3000ms progress bar
Config.LootCash{ min = 1, max = 8 }dollars, paid with AddMoney('cash')
Config.LootItemstable

Callbacks#

CallbackSideArgumentsFile
rsg-ambush:server:requestAmbushserversrc, cbserver/server.lua
rsg-ambush:server:lootserversrc, cb, id, netIdserver/server.lua
-- client side
RSGCore.Functions.TriggerCallback('rsg-ambush:server:requestAmbush', 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-ambush:client:forceclient``client/client.lua
RSGCore:Client:OnPlayerUnloadclient``client/client.lua
rsg-ambush:server:registerPedsserverid, netIdsserver/server.lua
rsg-ambush:server:finishserveridserver/server.lua
-- from a client script
TriggerServerEvent('rsg-ambush:server:registerPeds', id, netIds)
-- from a server script
TriggerClientEvent('rsg-ambush:client:force', source)

Commands#

CommandNotesFile
/testambushlocale('cmd_testambush_help')server/server.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 -->