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:

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:

1. Ammo items go directly into the weapon — no magazines needed
2. Drag ammo onto the weapon to load it
3. Press reload to use ammo from 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.