All resources

rsg-ammo – Docs (v3.0.2)#

Contents#

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

1. Files#

FilePurpose
fxmanifest.luaManifest; depends on rsg-core, rsg-inventory, oxmysql
shared/config.luaAmmo box items, arrow items, carry limits
client/client.luaApplies saved ammo, progress bar, saves changes, GetAmmoTypes export
server/server.luaUseable items, auto database, load/save, validation
server/versionchecker.luaGitHub version check
installation/rsg-ammo.sqlManual database install (backup)
locales/*.jsonen, de, el, es, fr, ja, nl, pl, pt-br, ro, ru

2. How it works#

  • Every ammo box and arrow in Config.BoxAmmo / Config.ArrowAmmo is registered as a useable item.
  • Using a box starts a cancellable progress bar (Config.OpenAmmoBoxTime). The box is only removed when it finishes. Arrows apply instantly.
  • If the player is already at the type's maxAmmo, the item is not used and "Max Ammo Reached" is shown.
  • The server decides the item, ammo type and amount (refill). Saved values are validated and clamped to maxAmmo.
  • Ammo for every type, including throwables (dynamite, molotov, throwing knives, tomahawks, bolas, hatchets), is stored per character and restored on login.
  • Changed counts are saved every Config.SaveAmmoInterval ms and on logout or character switch.

3. Configuration#

shared/config.lua:

OptionDefaultMeaning
SaveAmmoInterval10000ms between saves of changed ammo
OpenAmmoBoxTime2000Progress bar time for boxes
BoxAmmotableitem name → ammo type (revolver, pistol, repeater, rifle, shotgun, elephant, varmint incl. express, explosive, high velocity, split point)
ArrowAmmotablearrow item → ammo type (regular, small game, fire, poison, dynamite)
AmmoTypestableammo type → { maxAmmo, refill }

Example, a new ammo box:

Config.BoxAmmo['ammo_box_rifle_custom'] = 'AMMO_RIFLE'

The item must exist in rsg-core/shared/items.lua with useable = true.

4. Exports and events#

NameSideNotes
GetAmmoTypes()client exportReturns Config.AmmoTypes; used by rsg-weapons for throwables
rsg-ammo:client:AddAmmoclient net event(ammoType, amount)
rsg-ammo:client:openAmmoBoxclient net event(ammoBoxItem) starts the progress bar
rsg-ammo:server:openAmmoBoxserver net eventFinish opening a box
rsg-ammo:server:cancelOpenserver net eventCancel; box is kept
rsg-ammo:server:initializeDbcallbackReturns the character's saved ammo
rsg-ammo:server:updateDbserver net eventSaves changed counts

5. Database#

Table player_ammo: one row per citizenid with one INT column per ammo type (e.g. ammo_revolver, ammo_rifle_express, ammo_arrow_fire), default 0. The table and any new ammo columns are created automatically on start. If the database user lacks CREATE/ALTER, import installation/rsg-ammo.sql.

6. Security#

The server picks item, type and amount; the client never sends an amount to add. Saved values are clamped to each type's maxAmmo.

7. How-tos#

  • Give ammo: /giveitem [id] ammo_box_revolver 1, or sell the items in a shop.
  • Change carry limits or refill amounts in Config.AmmoTypes.
  • Language: setr rsg:locale "de" in server.cfg.

8. Troubleshooting#

ProblemFix
Item does nothingItem must exist in items.lua with useable = true and be listed in Config.BoxAmmo/ArrowAmmo
[rsg-ammo] database errorImport installation/rsg-ammo.sql
"Max Ammo Reached"Player is at the limit for that type
Ammo lost after restartStart oxmysql, rsg-core, rsg-inventory before rsg-ammo

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

Dependencies#

rsg-core, rsg-inventory, oxmysql

Database#

Tables: player_ammo.

Tables are created automatically on start while Config.AutoDatabase = true (default). Nothing is ever dropped or overwritten. For a manual install set Config.AutoDatabase = false and import installation/rsg-ammo.sql once.

-- shared/config.lua
Config.AutoDatabase = true -- false = import the SQL file yourself

Configuration#

OptionDefaultNotes
Config.AutoDatabasetruebuild the database tables automatically on start (set false and import the SQL file for a manual install)
Config.SaveAmmoInterval10000how often (ms) changed ammo counts are saved to the database
Config.OpenAmmoBoxTime2000progress bar time (ms) when opening an ammo box
Config.BoxAmmotableammo box items (progress bar) -> ammo type
Config.ArrowAmmotablearrow items (used instantly) -> ammo type
Config.AmmoTypestablemaxAmmo = carry limit, refill = amount given per item

Exports#

Client

ExportArgumentsFile
GetAmmoTypes``client/client.lua
-- example
local result = exports['rsg-ammo']:GetAmmoTypes()

Callbacks#

CallbackSideArgumentsFile
rsg-ammo:client:CanAddAmmoclientcb, ammoType, amountclient/client.lua
rsg-ammo:server:initializeDbserversource, cbserver/server.lua
-- client side
RSGCore.Functions.TriggerCallback('rsg-ammo:client:CanAddAmmo', 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-ammo:client:AddAmmoclientammoType, amountclient/client.lua
rsg-ammo:client:openAmmoBoxclientammoBoxItemclient/client.lua
RSGCore:Client:OnPlayerLoadedclient``client/client.lua
RSGCore:Client:OnPlayerUnloadclient``client/client.lua
rsg-ammo:server:openAmmoBoxserver``server/server.lua
rsg-ammo:server:cancelOpenserver``server/server.lua
rsg-ammo:server:updateDbserverupdateserver/server.lua
-- from a client script
TriggerServerEvent('rsg-ammo:server:openAmmoBox')
-- from a server script
TriggerClientEvent('rsg-ammo:client:AddAmmo', source, ammoType, amount)

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