Configuration Helps

SS-Weapons Setup & Configuration Guide

SS-Weapons is a RedM weapon catalogue, ammo, blueprint gunsmith, weapon condition, cleaning, repair, HUD and preview system.

This guide is written for server owners who want to install, configure and test the script safely.

Features Overview

Vintage catalogue store with configurable weapon and ammo lists per location.
Ammo boxes that add bullets to the player's ammo belt.
Blueprint gunsmith editor: every editable part linked to the real weapon on the bench, options drawer, live preview, rotate / zoom / reset.
Automatic centering and framing of the preview for every weapon; per-weapon presets tuned in game.
Per-weapon part lists (only what the game accepts), bow colours, blade materials and engravings.
Gunsmith templates for saving and reusing setups.
Custom weapon serial and custom weapon name, per store.
Persistent dirt, soot, degradation, damage and permanent wear; cleaning through the native inspection flow; repair kit.
One player per bench; nearby players can watch the preview.
Optional weapon HUD, poison / tranquilizer effects.
vorp_inventory v1 and v2, server-side validation of every purchase and edit.
8 languages.

Dependencies

Required

SS-Core
ghmattimysql
vorp_inventory (v1 or v2, detected automatically)

Used By Default

@SS-Core/dataview.lua
vorp:NotifyLeft in the default NOTIFY function (config.lua).

Optional Integrations

SS-Notify, if you switch the NOTIFY function to the commented example.
SS-PlayerShops, if you use the external player shop flow supported by the client.

Installation

1. Add The Resource

resources/[scripts]/SS-Weapons

Keep the folder name exactly SS-Weapons: the script checks it and the NUI posts to it.

2. Database

Tables are created and upgraded automatically at start:

ss_weapons
ss_weaponstemp

The script also reads and updates your existing weapon loadout table.

3. Start Order

ensure ghmattimysql
ensure vorp_inventory
ensure SS-Core
ensure SS-Weapons

4. vorp_inventory v2

v2 ships its own weapon degradation and component loading. To let SS-Weapons own them, set in the inventory config:

CONFIG.USE_WEAPON_DEGRADATION = false
CONFIG.USE_WEAPON_COMPONENTS = false

then set InventoryDegradationHandled = true in SS-Weapons. Leave InventoryVersion = "auto".

5. Restart

Restart the server and test one store, one bench, one ammo box, one cleaning item and one repair item.

Main Files

config.lua: Main configuration.
cfg/weapons.lua / cfg/ammo.lua: Catalogs.
cfg/anchors.lua: Callout line positions per weapon type.
cfg/presets.json: Per-weapon camera and callout presets (saved by the server).
l/l.lua: Notification translations.
config.js: UI language and UI options.
UI/: Catalogue and gunsmith UI.

Languages

Set the same language in two files:

-- config.lua
Language = "RO"

// config.js
var Config = { Language: "RO" };

Included: EN, IT, ES, FR, DE, PT, RU, RO.

Stores

Each store can enable the catalogue, the bench, or both:

EnableStore = true
EnableGunsmith = true

What each store sells:

WichWeapons = false   -- false = all, {} = none, {"WEAPON_..."} = only listed
WichAmmo = false

Custom serial / name per store:

Serial = true          -- true = paid option, false = hidden
CustomLabel = true     -- true = paid option, false = hidden, "Text" = forced free name

Add A New Store

Copy an existing entry and change name, positions, cameras, blips and jobs:

[5] = {
    Name = "Annesburg",

    EnableStore = true,
    StoreBlip = 202506373,
    CatalogWeapon = {2946.54, 1319.93, 44.82, 246.31},
    CamStore = {2947.55, 1319.71, 45.62, -90.0, 110.0, 0.0, 50.0},
    WichWeapons = false,
    WichAmmo = false,
    Serial = true,
    CustomLabel = true,

    EnableGunsmith = true,
    GunSmithBlip = 202506373,
    ModifyWeapons = {2949.89, 1314.15, 44.91},
    ModifyPos = {2949.89, 1314.15, 44.91, 90.0, 163.0, 178.0},
    CamGunSmith = {2950.21, 1314.14, 45.41, -90.0, 200.0, 0.0, 80.0},
    Jobs = {"Armurier"},
},

Tips for the bench: ModifyPos is where the weapon lies, CamGunSmith looks straight down at it (pitch -90.0). Thanks to auto centering and auto fit you only need the camera roughly above the bench; the script centres and frames the weapon itself.

Weapon Catalog

cfg/weapons.lua controls per weapon: name / hash, label and title, description and extra text, category, price, gold value, buy jobs and grades, modify jobs and grades, type.

BuyJobs = {"police"}        -- only these jobs can buy
BuyJobsGrade = {2}
ModifyJobs = {"Armurier"}   -- only these jobs can customize it at a bench

Empty tables mean everyone.

Ammo Catalog

cfg/ammo.lua fields: Item (inventory item), Label, Category, Price per box, Type (ammo type added to the belt), MaxAmmo (belt limit), Amount (bullets per box).

Buying Flow

Player opens a store: the catalogue shows weapons and ammo by category.
Player picks an item, optionally a custom serial / name or an ammo quantity.
One server call rebuilds the price from the config, checks money and carry space, charges and gives the item.
Ammo boxes are used later to add bullets to the belt.

Gunsmith Flow

Player equips a supported weapon and walks to a bench (job checked on client and server; the bench must be free).
The weapon is put away, the preview spawns on the bench and the camera glides above it. The preview is centred and framed automatically.
Cards for every editable part appear with a line to the part on the weapon. Click a card to open the options drawer; pick tiles, watch the preview update, see the price per change.
Templates can be saved / applied / deleted; the hammer button repairs the weapon.
Confirm & pay: the server prices the difference from what is stored, charges and saves the components. Re-equip the weapon to carry the new look.

Weapon Presets (camera + callouts per weapon)

If a weapon sits too small, off centre, or a callout points beside its part:

Set Dev = true, equip the weapon and open a bench. The Weapon preset panel appears bottom-left.
Camera: pan left / right, pan up / down, distance, turn and FOV move the camera; Weapon turn rotates the weapon on the bench; Reset cam drops the changes.
Anchor: pick a part and nudge it Right / Forward / Up until the ring sits on the right spot. Only moved parts are stored.
Save preset writes camera + moved anchors for this weapon to cfg/presets.json and sends them to all clients. Delete preset removes them. Print table prints values and model diagnostics to F8.
Ship cfg/presets.json with the resource and set Dev = false again.

Gunsmith Prices

Prices per part category and edit type live in Config.GunSmith; payment type in WeaponEditPayment.Type (gold or money). See Configuration File for the full table.

Gunsmith Templates

Players save, apply and delete component setups. Stored in ss_weaponstemp by identifier, character ID, weapon and template name.

Weapon Cleaning

CleanWeaponItem = "leather"
RemoveAfterClean = true
CleanWeaponTime = 10000
MinCleanWeaponTime = 2500
InspectWeaponCommand = "w_inspect"

Use the clean item (or /w_inspect) with the weapon in hand: the native inspection opens, the clean prompt removes dirt / soot / degradation and adds a little permanent wear. /w_inspectstatus prints why inspection is blocked, /w_inspectreset frees a stuck interaction.

Weapon Repair

WeaponRepair = {
    Enabled = true,
    Item = "weapon_repair_kit",
    RemoveItem = true,
    RepairAmount = 0.10,
    MinRustRequired = 0.01,
}

Repair is started from the editor and lowers the permanent wear stored on the server.

Weapon Wear

ss_weapons stores per serial: weapon name, last loadout ID, dirt, soot, condition, damage and permanent wear. Wear sent by clients can only grow; only cleaning and repair lower it. With UseDegradation = true a weapon at 100% permanent wear cannot fire.

Weapon HUD

WeaponHud = { Enabled = false, Position = "top-right", UpdateInterval = 150, HideWhenUiOpen = true }

Icons: UI/img/weapons (lower-case weapon name) and UI/img/ammo_types.

Preview Sync & Bench Lock

PreviewSync = { Enabled = true, Radius = 8.0, MaxSpectators = 6, CheckInterval = 2000 }

Nearby players see the preview while someone edits. A bench in use is locked: others get "This workbench is being used by someone else" until the player leaves, pays or disconnects.

Poison & Tranquilizer

ActivePoison = false
ActiveTranq = false

Disabled by default; enable only if your server uses poison arrows or tranquilizer gameplay.

Dev Commands & Tools

With Dev = true: /dirtyweapon, /wstatus, /wdirt, /wsoot, /wdegradation, /wdamage, /wthreshold, /wwear, /wresetwear, the Weapon preset panel, and [SS-Weapons][Equip] / [SS-Weapons][Anchors] prints in F8.

Always available: /w_inspect, /w_inspectstatus, /w_inspectreset.

Troubleshooting

Store Prompt Does Not Appear

EnableStore = true, CatalogWeapon coordinates, PressKey, folder named SS-Weapons.

Bench Prompt Does Not Appear

EnableGunsmith = true, ModifyWeapons coordinates, player job in Jobs.

"Re-equip the weapon"

Equip the weapon once from the inventory so the script receives it. Weapons received at character select are dressed when drawn. On v2, draw the weapon you want to edit before pressing the prompt.

"This workbench is being used by someone else"

Another player has the bench open. Locks are released on leave / pay / disconnect and expire on their own.

Wrong Weapon On The Bench / Mods Not Applied (vorp_inventory v2)

Make sure the server runs the current c/c.lua and s/s.lua, InventoryVersion = "auto", and v2 has USE_WEAPON_DEGRADATION = false and USE_WEAPON_COMPONENTS = false.

Callout Lines In The Wrong Place

Tune the weapon in the Dev preset panel and Save preset; check SideSign / MuzzleAtPositiveEnd in cfg/anchors.lua if a whole weapon type is mirrored.

Player Cannot Buy

Money, carry limits from SS-Core, item exists in cfg/weapons.lua / cfg/ammo.lua, player stands at the counter, custom name within MinLabel / MaxLabel.

Ammo Item Does Not Add Bullets

Ammo item name matches the inventory item, Type is correct, belt not full, MaxAmmo / Amount correct.

Weapon HUD Image Is Missing

Image exists in UI/img/weapons with the lower-case weapon name; ammo icon exists in UI/img/ammo_types.

Cleaning Does Not Work

Player has CleanWeaponItem, weapon in hand, run /w_inspectstatus for the exact blocker.

Repair Does Not Work

WeaponRepair.Enabled = true, player has the repair item, weapon has at least MinRustRequired permanent wear.

Recommended Live Checklist

ghmattimysql, vorp_inventory, SS-Core start before SS-Weapons.
Resource folder named SS-Weapons.
Dev = false.
Same language in config.lua and config.js.
cfg/presets.json shipped.
Stores, benches, buying, ammo, edit / pay, templates, cleaning, repair, HUD and preview sync tested.

Editing Rules For Beginners

Strings use quotes: "text". Table entries end with a comma.
true enables a feature; false disables it or means all / everyone depending on the field.
Numbers do not use quotes. Coordinates use {x, y, z} or {x, y, z, heading}.
Do not rename the resource folder.

Bad: Dev = "false" — Good: Dev = false

PreviousConfiguration File

NextChange logs

Last updated 4 months ago