All resources

rsg-weapons – Docs (v3.2.0)#

Contents#

  1. Files
  2. How it works
  3. Configuration
  4. Exports and events
  5. Commands
  6. Security
  7. Server owner how-tos
  8. Troubleshooting

1. Files#

FilePurpose
fxmanifest.luaManifest; depends on rsg-core, rsg-inventory
config.luaRepair time, wear, damage multipliers, throwable ammo types
client/client.luaEquipping, dual wield, shot tracking, repair, loadout restore
client/weaponclass.luaWeapon helper class, EquippedWeapons, RemoveWeaponFromPeds
client/dataview.luaBuffer helper for natives
server/server.luaWear, repair kit, saved loadout, validation
server/versionchecker.luaGitHub version check
locales/*.jsonen, cs, de, el, es, fr, it, ja, nl, pl, pt-br, ro, ru

2. How it works#

  • Every gun is tracked by serial number, so two of the same model keep separate wear and repair state.
  • Dual wield: right hand fills first, then left. Removing the right gun moves the left across. A third one-handed gun is refused. The off-hand holster is added automatically for male and female peds.
  • Wear: each shot lowers the gun's quality by DegradeRate. Shots are batched and sent every UpdateDegrade ms. Dual wielding shares wear. At quality 1 or less the gun breaks and is unequipped.
  • Repair: use a weapon_repair_kit on the held gun, or the most worn gun you carry. The kit is used only when the progress bar completes.
  • Saved loadout: with SaveEquippedWeapons, equipped guns and knives are re-equipped on login and after a resource restart. Broken or missing weapons are dropped from the list.
  • Throwables (tomahawks, knives, dynamite, bolas, hatchets) refill ammo through rsg-ammo after the server removes the item.
  • With Config.WeaponComponents, components are synced with rsg-weaponcomp when equipping or breaking.

3. Configuration#

config.lua:

OptionDefaultMeaning
DebugfalseDebug prints
WeaponComponentstrueSync components with rsg-weaponcomp
SaveEquippedWeaponstrueRe-equip weapons and knives on login
RepairTime30000Repair progress bar ms (also enforced server-side)
DegradeRate0.01Quality lost per shot
UpdateDegrade5000ms between shot batches sent to the server
DisableSprintWhileAimingtrueBlock sprint while aiming
DisableCriticalHitsfalseDisable critical hits
WeaponDamagelist{ Name = 'WEAPON_…', Damage = 1.0 } multiplier per weapon
ThrowableWeaponAmmoTypestablethrowable item → ammo type

Example, make the Cattleman 20% weaker:

{Name = 'WEAPON_REVOLVER_CATTLEMAN', Damage = 0.8},

4. Exports and events#

Client exports#

ExportNotes
weaponInHands()Current weapon in hands
UsedWeapons(serial)Equipped-state lookup by serial
GetUsedWeapons()All equipped weapons
CheckWeaponSerial()Serial of the held weapon
EquippedWeapons()Equipped weapon list
RemoveWeaponFromPedsRemove a weapon from the ped

Events and callbacks#

NameSideNotes
rsg-weapons:client:UseWeaponclient net eventEquip/unequip a weapon item
rsg-weapons:client:UseThrownWeaponclient net eventThrowable use
rsg-weapons:client:UseEquipmentclient net eventEquipment (e.g. torch)
rsg-weapons:client:repairweaponclient net eventStart a repair
rsg-weapons:client:weaponRepairedclient net event(serial) repair done
rsg-weapons:toggleclient net eventInfinite ammo toggle, server only
rsg-weapons:server:degradeWeaponserver net event(queue) shot batch
rsg-weapons:server:startRepaircallbackChecks kit, ownership, damage
rsg-weapons:server:finishRepairserver net eventChecks elapsed time, removes the kit
rsg-weapons:server:cancelRepairserver net eventCancel repair
rsg-weapons:server:consumeItemcallbackThrowables and torch only
rsg-weapons:server:saveEquippedWeapon / saveEquippedKnifeserver net eventsSaved loadout
rsg-weapons:server:getEquippedcallbackLoadout on login
rsg-weapons:requestToggleserver net eventInfinite ammo, admin only

5. Commands#

CommandWhoWhat
/infinityammoadmin (server checks)Toggle infinite ammo for the held weapon

6. Security#

All item and quality changes happen on the server. The client only reports shots and repair completion. The server checks the kit, weapon ownership, that the weapon is damaged and that the full repair time passed. Only whitelisted items (throwables, torch) can be consumed through the client request. The admin command is permission-checked and rate-limited.

7. How-tos#

  • Repair item: weapon_repair_kit must exist in items.lua.
  • Language: setr rsg:locale "de" in server.cfg.
  • Turn off wear: set DegradeRate = 0.

8. Troubleshooting#

ProblemFix
Weapon brokeUse a weapon_repair_kit
Third pistol refusedDual wield holds two one-handed guns
Throwable has no ammoStart rsg-ammo and check ThrowableWeaponAmmoTypes
Loadout not restoredSaveEquippedWeapons = true; the item must still be in the inventory

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

Dependencies#

rsg-core, rsg-inventory

Configuration#

OptionDefaultNotes
Config.Debugfalse
Config.WeaponComponentstruesync components with rsg-weaponcomp when equipping / breaking weapons
Config.SaveEquippedWeaponstruere-equip weapons and knives on login
Config.RepairTime30000ms the repair progress bar takes (also enforced server-side)
Config.DegradeRate0.01quality lost per shot
Config.UpdateDegrade5000ms between sending shot batches to the server
Config.DisableSprintWhileAimingtrue
Config.DisableCriticalHitsfalseDamage Weapon
Config.WeaponDamagetable
Config.ThrowableWeaponAmmoTypestable

Exports#

Client

ExportArgumentsFile
weaponInHands``client/client.lua
UsedWeaponsserialclient/client.lua
GetUsedWeapons``client/client.lua
CheckWeaponSerial``client/client.lua
EquippedWeapons``client/weaponclass.lua
RemoveWeaponFromPeds``client/weaponclass.lua
-- example
local result = exports['rsg-weapons']:weaponInHands()

Callbacks#

CallbackSideArgumentsFile
rsg-weapons:server:startRepairserversrc, cb, heldSerialserver/server.lua
rsg-weapons:server:consumeItemserversrc, cb, itemserver/server.lua
rsg-weapons:server:getEquippedserversrc, cbserver/server.lua
-- client side
RSGCore.Functions.TriggerCallback('rsg-weapons:server:startRepair', function(result)
    -- use result
end, heldSerial)

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-weapons:client:UseWeaponclientweaponDataclient/client.lua
rsg-weapons:client:UseThrownWeaponclientweaponDataclient/client.lua
rsg-weapons:client:UseEquipmentclientweaponDataclient/client.lua
rsg-weapons:client:repairweaponclient``client/client.lua
rsg-weapons:client:weaponRepairedclientserialclient/client.lua
rsg-weapons:toggleclient``client/client.lua
RSGCore:Client:OnPlayerLoadedclient``client/client.lua
RSGCore:Client:OnPlayerUnloadclient``client/client.lua
rsg-weapons:server:degradeWeaponserverqueueserver/server.lua
rsg-weapons:server:finishRepairserver``server/server.lua
rsg-weapons:server:cancelRepairserver``server/server.lua
rsg-weapons:server:saveEquippedWeaponserverserial, isEquippedserver/server.lua
rsg-weapons:server:saveEquippedKnifeserverknifeName, isEquippedserver/server.lua
rsg-weapons:requestToggleserver``server/server.lua
-- from a client script
TriggerServerEvent('rsg-weapons:server:degradeWeapon', queue)
-- from a server script
TriggerClientEvent('rsg-weapons:client:UseWeapon', source, weaponData)

Commands#

CommandNotesFile
/infinityammoclient/client.lua

Locales#

Language files in locales/: cs, de, el, en, es, fr, it, ja, nl, pl, pt-br, ro, ru. Set the language with setr rsg:locale "en".

<!-- END AUTO-REFERENCE -->