🔫 Weapons - Advanced Weapon Damage System

Welcome to NS Weapons!

NS Weapons is a comprehensive FiveM resource for fine-tuning weapon damage and behavior. Perfect for servers looking to balance PvP combat, create realistic weapon mechanics, or customize damage values for each individual weapon.

---

🎯 What is NS Weapons?

This script provides complete control over weapon damage multipliers with a modern, user-friendly interface. Admins can adjust damage for every weapon in the game, test changes in real-time with a dummy NPC, and save configurations that persist across server restarts.

Perfect for roleplay servers, PvP arenas, or any server wanting customized weapon balance.

---

✨ Core Features

🎮 Real-Time Weapon Testing

• Test Dummy System - Spawn NPC to test weapon damage

• Live Damage Display - See damage numbers in real-time

• Hit Tracking - Track head/body/limb shots

• HP Visualization - Watch dummy health decrease

• Reset Function - Instantly reset dummy HP

• Interactive Overlay - Modern damage statistics overlay

⚙️ Damage Configuration

• Per-Weapon Multipliers - Adjust each weapon individually

• Range: 0.0x - 10.0x - Full damage control

• Live Preview - See changes immediately

• Auto-Save - Settings persist across restarts

• Damage Range Editor - Set min/max damage per weapon

• Instant Apply - No server restart needed

🎨 Modern Web UI

• Weapon Selection - Searchable weapon list

• Visual Editor - Slider controls for multipliers

• Real-Time Stats - Current damage values displayed

• Test Integration - One-click weapon spawning

• Position Editor - Customize UI placement

• Responsive Design - Clean, intuitive interface

🔧 Advanced Options

• Headshot Toggle - Enable/disable instakill headshots

• Pistol Whip Control - Disable melee attacks with firearms

• Ammo Type Mapping - Configure ammo for each weapon type

• Test Ammo Amount - Set ammo given during testing

• Weapon Auto-Load - Auto-detect from ox_inventory

🌐 Framework Support

• ✅ Auto-Detection - Automatically finds your framework

• ✅ QBCore - Full support

• ✅ ESX - Full support

• ✅ QBox - Full support

• ✅ Manual Config - Force specific framework if needed

🔐 Permission System

• ACE Permission - Secure admin access

• Open Mode - Allow everyone (testing)

• Command-Based - Simple /weapondmg command

• Customizable Command - Change command name

🌍 Localization

• 🇬🇧 English - Complete translation

• 🇧🇬 Bulgarian - Complete translation

• 📝 Easy to add more languages

• JSON-based locale system

📊 Testing Features

• Hit Detection - Tracks every shot

• Damage Breakdown - Head/Body/Limb damage shown

• Totals Display - See cumulative damage

• Last Hit Info - Current hit damage and location

• HP Display - Dummy health bar

• Shot Counter - Count shots per body part

---

🎯 Use Cases

PvP Balance

• Fine-tune weapon damage for fair combat

• Nerf overpowered weapons

• Buff underused weapons

• Create balanced weapon classes

Roleplay Servers

• Realistic damage values

• Balanced cop vs. criminal combat

• Medical RP integration

• Fear RP mechanics

Event Servers

• Custom damage for arenas

• Tournament balancing

• Special event weapons

• Challenge modes

Testing & Development

• Test weapon additions

• Balance new weapons

• Debug damage issues

• Prototype mechanics

---

🔧 Technical Specifications

Dependencies

• ✅ No dependencies - Standalone script

• ✅ Framework bridge included

• ✅ Works out of the box

Performance

• 🚀 Optimized - Minimal resource usage

• 💾 Efficient - Clean code structure

• 🔄 No server lag - Client-side testing

Data Storage

• JSON File - settings.json for multipliers

• Auto-Save - Changes saved automatically

• Persistent - Survives server restarts

• Editable - Can manually edit JSON

---

💡 How It Works

For Admins

1. Open Menu

/weapondmg

2. Select Weapon

• Search or browse weapon list

• Click weapon to configure

3. Adjust Multiplier

• Use slider (0.0x - 10.0x)

• 1.0 = default damage

• 2.0 = double damage

• 0.5 = half damage

4. Test Weapon

• Click "Test" button

• Dummy spawns in front of you

• Receive weapon with ammo

• Shoot dummy to test

• See real-time damage

5. Apply Changes

• Click "Apply Changes"

• Settings saved immediately

• All players affected

---

📋 Quick Examples

Double Damage Pistol

Weapon: Pistol
Multiplier: 2.0
Result: Pistol does 2x damage

Realistic Sniper

Weapon: Heavy Sniper
Multiplier: 5.0
Headshots: Enabled
Result: One-shot headshot kills

Nerfed SMG

Weapon: SMG
Multiplier: 0.5
Result: SMG does half damage

Disabled Weapon

Weapon: RPG
Multiplier: 0.0
Result: RPG does no damage

---

🎮 Testing Workflow

1. Select Weapon → Choose from list

2. Click Test → Dummy spawns + weapon received

3. Shoot Dummy → See damage numbers

4. Review Stats:

• Head shots: X (XX damage)

• Body shots: X (XX damage)

• Limb shots: X (XX damage)

• Total: XXX damage

5. Adjust Multiplier → Fine-tune

6. Test Again → Reset HP (G key)

7. Apply Changes → Save when satisfied

---

🌟 Key Features Highlight

Damage Multipliers

• Individual weapon control

• Precise 0.1x increments

• Range: 0.0x to 10.0x

• Default: 1.0x

Headshot System

Config.Headshots = false  -- Default

• false = Normal damage multiplier applies

• true = Headshots are instakill

Pistol Whip Control

Config.DisablePistolWhip = true

• true = No melee with guns

• false = Allow pistol whip

Ammo Mapping

Config.AmmoMap = {
    AMMO_PISTOL = "pistol_ammo",
    AMMO_SMG = "smg_ammo",
    AMMO_RIFLE = "rifle_ammo",
    -- ...
}

Link weapon types to inventory ammo items.

Auto-Load Weapons

Config.LoadWeapons = 'auto'

• 'auto' = Load from ox_inventory

• 'manual' = Use Config.Weapons list

---

🎨 UI Features

Weapon List

• Searchable

• Scrollable

• Click to select

• Shows current multiplier

Damage Editor

• Slider control

• Numeric input

• Real-time preview

• Apply button

Test Overlay

• HP bar

• Damage numbers

• Shot breakdown

• Body part tracking

• Total damage

• Last hit info

Position Editor

• Drag UI anywhere

• Save position

• Reset to default

---

🔐 Permission Options

Everyone Can Use

Config.AcePermission = "none"

No restrictions - everyone has access.

Admin Only

Config.AcePermission = "ns-weapons.edit"

Add to server.cfg:

add_ace group.admin "ns-weapons.edit" allow
add_principal identifier.steam:YOUR_ID group.admin

Only admins can access.

---

💬 Support & Community

Need help or want to share feedback?

• 💬 Discord: https://discord.gg/gVMh5MfAWZ

• 🌟 Tebex Store: https://nss.tebex.io/

---

📄 License

This resource is a paid product. Redistribution or resale is strictly prohibited.

---

🚀 Ready to Balance Your Server?

NS Weapons brings professional weapon damage control to your FiveM server.

Start now: Installation Guide →