Weapon Mechanics

Core Inventory features a full simulated weapon system with magazine-based reloading, weapon attachments, holster animations, durability, and serial numbers.

Ammo System

When UseMagazineSystem = true (default), weapons use a realistic magazine workflow:

Get Ammo & Magazines

Drag Ammo onto Magazine

Equip Magazine to Weapon

Press R to Reload

1. Magazines are items — each weapon type has clip items (standard, extended, drum) that exist in your inventory
2. Loading ammo into magazines — drag ammo onto a magazine item to fill it
3. Equipping magazines — attach a loaded magazine to your weapon via the attachments menu
4. Reloading — pressing R swaps the current magazine with the next compatible loaded magazine from your inventory
5. Unloading — right-click a weapon and select "Unload Ammo" to remove the current magazine

-- config_weapons.lua
UseMagazineSystem = true,

How Magazine Reload Works

When the player reloads:

• The script searches inventory for a compatible magazine with ammo
• The old magazine (with remaining ammo) goes back to inventory
• The new magazine is attached to the weapon
• If no compatible magazine is found, a notification is shown

INFO

Magazine capacity is determined by the clip component. Extended clips hold more rounds than standard clips, and drum magazines hold the most.

When UseMagazineSystem = false, weapons use simple direct ammo loading:

Get Ammo

Equip Weapon

Press R to Reload

1. Ammo items go directly into the weapon — no magazines needed
2. Press R to reload — ammo is consumed from your inventory automatically

This mode is simpler but less realistic. Good for servers that prefer arcade-style gameplay.

-- config_weapons.lua
UseMagazineSystem = false,

Ammunition Types

Ammo is defined in config_weapons.lua. Each ammo item maps to the magazine components and/or weapon models it's compatible with:

Ammunition = {
    ['pistol_ammo'] = {
        -- Magazine components this ammo fits
        'COMPONENT_PISTOL_CLIP_01',
        'COMPONENT_PISTOL_CLIP_02',
        'COMPONENT_COMBATPISTOL_CLIP_01',
        -- ...

        -- Weapon models for simple ammo reload
        'WEAPON_PISTOL',
        'WEAPON_COMBATPISTOL',
        -- ...
    },
}

Default Ammo Categories

Ammo Item	Weapons
pistol_ammo	All pistols and revolvers
smg_ammo	Micro SMG, SMG, Assault SMG, Combat PDW, etc.
mg_ammo	MG, Combat MG, Gusenberg Sweeper, Minigun
rifle_ammo	All assault and battle rifles
sniper_ammo	Sniper Rifle, Heavy Sniper, Marksman Rifle
shotgun_ammo	All shotguns

Weapon Attachments

Attachments are physical items that players drag onto weapons. The system supports three configuration modes:

One attachment item per weapon category — e.g., at_clip_extended_pistol works on all pistols, at_clip_extended_rifle works on all rifles.

UniqueComponentByWeaponCategory = true, -- Default

ComponentsByCategory = {
    ['at_clip_extended_pistol'] = {
        'COMPONENT_PISTOL_CLIP_02',
        'COMPONENT_COMBATPISTOL_CLIP_02',
        'COMPONENT_HEAVYPISTOL_CLIP_02',
        -- ...
    },
    ['at_suppressor_light'] = {
        'COMPONENT_AT_PI_SUPP',
        'COMPONENT_AT_PI_SUPP_02',
        -- ...
    },
}

Best for balanced gameplay — fewer items to manage while still having weapon-class variety.

One attachment item per specific weapon — maximum realism, each weapon has unique attachment items.

UniqueComponent = true,

Import the attachments.lua (QB) or equivalent SQL from the [items] folder. This creates many more items but provides the most granular control.

One attachment item works on all weapons — e.g., a single at_suppressor item works on any weapon that supports a suppressor.

SharedComponentForAllWeapons = true,

Simplest setup — fewest items, easiest for players. Good for casual servers.

Attachment Categories

Scopes

Macro, small, medium, holo, NV, thermal, and advanced scopes.

Suppressors

Light (pistol) and heavy (rifle/sniper) suppressors.

Grips

Foregrip attachments for reduced recoil.

Flashlights

Weapon-mounted flashlights for pistols and rifles.

Clips

Standard, extended, and drum magazines.

Barrels & Muzzles

Heavy barrels, flat, tactical, slanted, and more muzzle brakes.

Weapon Holstering

Weapons have equip/holster animations that play when switching weapons:

WeaponHolsterAnimation = true,

-- Jobs with special holster animation for pistols
JobWeaponHaveHolsterAnimation = {
    ['police'] = true,
    ['fbi'] = true,
    ['bcso'] = true
},

Custom Holster Animations

Each weapon group can have custom intro (equip) and outro (holster) animations:

HolsterAnimations = {
    ['GROUP_PISTOL'] = {
        intro = { dict = 'reaction@intimidation@cop@unarmed',
                  anim = 'intro', sleep = 400  },
        outro = { dict = 'reaction@intimidation@cop@unarmed',
                  anim = 'outro', sleep = 450  }
    },
    ['GROUP_MELEE'] = {
        intro = { dict = 'melee@holster',
                  anim = 'unholster', sleep = 200  },
        outro = { dict = 'melee@holster',
                  anim = 'holster', sleep = 400  }
    },
    ['DEFAULT'] = {
        intro = { dict = 'reaction@intimidation@1h',
                  anim = 'intro', sleep = 1200 },
        outro = { dict = 'reaction@intimidation@1h',
                  anim = 'outro', sleep = 1400 }
    }
},

The sleep value controls how long (ms) to wait during the animation before the weapon appears/disappears.

Weapon Durability

Weapons have durability that degrades with use:

ShootingDurabilityDegradation = 0.1, -- Per-shot degradation

• Weapons in the weapons category automatically get durability tracking
• Broken weapons (0 durability) display with the BrokenItemColor
• Durability can be set via metadata or the setDurability export

Serial Numbers

All weapons automatically receive a unique serial number:

ItemCategories = {
    ["weapons"] = {
        serial = true,  -- Auto-generate serial numbers
        durability = true,
    },
}

Serial numbers are visible in the item info panel and persist through trades, drops, and storage.

Weapon Slots

The inventory provides dedicated weapon holder slots:

Slot	Purpose	Default Key
primary	Primary weapon (rifles, shotguns, etc.)	1
secondry	Secondary weapon (pistols, SMGs)	2
melee	Melee weapon	3

EnableSecondaryWeaponSlot = true,    -- Enable the secondary slot
EnableMeleeWeaponSlot = true,        -- Enable the melee slot

Quick-switch between weapon slots using the number keys 1, 2, 3.