One Magazine Per Weapon

This system introduces the most realistic and complex reloading mechanics available, faithfully inspired by real-life firearm handling. It is designed for players who want immersion, depth, and full control over how weapons and magazines behave inside the game.

---

🔧 How It Works

1. Inventory Requirement

   • Reloading requires a magazine item in the player’s inventory.

   • Each magazine is linked to specific weapon types and contains a defined maximum bullet capacity.

2. Reloading Process

   • When reloading, the weapon consumes the magazine and transfers its bullets to the firearm.

   • The used magazine does not disappear permanently; instead, it becomes an empty magazine, virtually stored inside the weapon.

3. Empty Magazines

   • Once the weapon is reloaded again, the empty magazine is automatically returned to the player’s inventory.

   • If all magazines are depleted, the system still keeps track of them, ensuring players can refill or craft new ones later.

4. Refilling Empty Magazines

   • The player can use empty magazines to create new full ones.

   • The system checks if the player has enough bullets in their inventory.

   • If the condition is met, the empty magazine is refilled and becomes usable again.

This cycle ensures that reloading feels like a complete process, not just a button press. Players must manage both ammunition and magazines, adding a tactical layer to gameplay.

---

🎬 Immersive Reloading Features

• Detailed Animations: Reloading is not instant. Players will see a dedicated animation supported by a progress bar, simulating the real effort of loading rounds into a magazine.

• Seven Animation Options: The system provides 7 animation options in total, with one specific animation assigned to each magazine model. This ensures that every magazine type feels unique, while keeping the setup simple and consistent.

• Customizable Parameters: Animations and magazine objects can be modified in multiple ways to achieve unique reloading behaviors.

---

🔥 New Function – Partial Magazine Reloading

• Emergency Ammo Top-Up: Allows players to add remaining bullets directly to the weapon’s current magazine when they don’t have enough to create a full magazine.

• Menu Selection: Players can choose how many bullets to insert through a dedicated menu. (optional)

• Progress & Animation: A progress bar shows loading time, while a custom animation plays and props (bullets, magazine, hands) appear for realism.

• Full Customization:

  • Props and Animations can be configured in the settings.

  • Optional Variables: Enable or disable the feature, and define multiple configurations for different weapons or play styles.

  • Weapon Save & Get Animations: Customize how weapons appear when saving, retrieving, or interacting with magazines.

• Tactical Flexibility: Lets players quickly top up a magazine with limited ammo, maintaining combat readiness without needing a full reload.

---

⚙️ Deep Customization Options

This system gives full control over how magazines and animations behave. Customization is divided into two major categories:

1. Object Settings

• Object Model: Defines the 3D model of the magazine.

• Player Bone Attachment: Determines where the magazine attaches on the character model (e.g., hand, belt, or chest).

• Coordinates: Fine-tunes the exact position of the magazine during animations.

• Rotation: Sets the magazine’s orientation in 3D space for perfect visual alignment.

2. Animation Settings

• Animation Dictionary: The library of animations to be used.

• Animation Name: The exact animation to play during the reloading sequence.

With these options, creators can tailor the reloading experience to match any weapon style, from fast tactical reloads to slow, dramatic ones.

---

📦 Magazine Types and Customization

Magazines can be adapted to reflect realistic physical characteristics:

• Normal Magazines: Standard bullet capacity.

• Extended Magazines: Increased ammo capacity for longer engagements.

• Drum Magazines: Maximum bullet storage, designed for heavy firepower.

For each magazine type, you can configure:

• Maximum Ammo Capacity – Define how many bullets each type can hold.

• Reloading Rules – Specify how empty magazines are handled when refilled.

• Item Naming System:

  • Unique names for full magazines.

  • Unique names for empty magazines.

  • Names for individual bullets.

⚠️ Important Rule:

• Bullet names may be repeated across different setups.

• Magazine names must be unique for every variant to avoid confusion in gameplay and inventory management.

This structure ensures that every magazine is clearly identifiable and behaves consistently within the system.

---

🔫 Weapons Without Detachable Magazines

Not all weapons use magazines. For added realism, this system allows you to exclude specific firearms from the magazine mechanic.

• Examples: Shotguns, revolvers, muskets and other weapons that load directly into the chamber or an internal magazine.

• Setup is simple: Add the weapon name to a special exclusion list.

• Result: The weapon bypasses the magazine system and reloads using loose ammunition or cartridges instead.

This makes the system flexible enough to handle both modern firearms and historical or exotic weapon types.

---

🌟 Why This System Stands Out

• Realistic Gameplay: Players must manage not just bullets, but also magazines — adding strategy and immersion.

• Manual Bullet Loading: New function that allows partial refills of empty magazines, bullet by bullet.

• Customizable Animations & Props: Everything from loading styles to objects and weapon interactions can be adjusted.

• Flexible Setup: Works with normal, extended, and drum magazines, each with unique parameters.

• Universal Compatibility: Supports both magazine-fed weapons and those that use loose ammunition.

• Immersive Experience: Progress bars, props, and animations make every reload feel authentic.

---

✅ Final Notes

This advanced reloading system is perfect for anyone seeking realism, immersion, and full control in their gameplay. By combining customizable magazines, realistic animations, manual bullet loading, and flexible weapon handling, it transforms reloading into a strategic and tactile experience rather than a simple mechanic.

Whether you’re building a realistic military scenario, a survival game with resource management, or a historically accurate setting, this system adapts to your needs and delivers unmatched depth.

---

ACTIVATING FEATURES

1. Firstly

• Navigate to the boolean variable VALUE and set it to true to enable the feature.

• Go to the WEAPONS table.

• Add the weapon you want to configure inside the table, ensuring its key is enclosed in square brackets and backticks.

• Optionally, include a descriptive string next to the weapon to label the configuration.

---

2. SPECIFIED_ITEMS

• Check the example table and locate the first sub-table DEFAULT_CLIP.

  • This represents the default magazine all weapons have without attachments.

• MAX_AMMO:

  • Set the maximum number of bullets for each weapon.

  • Example: WEAPON_PISTOL → 12 bullets.

  • You can repeat weapons with the same max ammo, but you cannot mix weapons whose max ammo is lower than configured (e.g., WEAPON_VINTAGEPISTOL or WEAPON_SNSPISTOL must be separate categories).

• LOAD_TYPE:

  • Configures animation and props for reloading from empty to full.

  • Requires the player to have at least the maximum number of loose bullets configured in inventory.

• Items Table:

  • CLIP: Full magazine.

  • EMPTY_CLIP: Empty magazine.

  • SINGLE_AMMO: Loose bullets.

• EXTENDED_CLIP:

  • Works only if the weapon has an extended magazine attachment.

  • You cannot reload with a default magazine if the weapon has an extended attachment and no extended magazines are available in inventory.

• DRUM_CLIP:

  • Primarily for long guns but can be used for other weapons with external attachments (ATTACHMENTS).

---

3. LOAD_CATEGORIES

• Used to define positions of objects and animations during reload.

• Types:

  • FULL: Reload using empty magazine item.

  • SINGLE: Reload using loose bullets when the weapon has few bullets.

• Important values:

  • AMMO: Bullet prop.

  • MAGAZINE: Magazine prop.

  • MODEL: 3D model of the prop.

  • BONE: Ped bone for attachment.

  • COORDS / ROTATION: Position and rotation of the prop.

  • ANIMATION: Animation executed along with the progress bar.

    • DICT_NAME: Animation dictionary.

    • NAME: Animation name according to weapon type.

• Categories correspond to weapon types:

  • PISTOL: Pistol magazine

  • SHOTGUN: Shotgun magazine

  • SNIPER: Sniper magazine

  • DRUM: Drum magazine

• You can add custom tables and then assign them to LOAD_TYPE of a configured magazine.

---

4. WEAPONS_WITHOUT_PHYSICAL_MAGAZINE ⚠

• Add weapons that do not use a physical magazine.

• Each weapon must be enclosed in backticks (``) and use a previously registered loose ammo type.

---

5. LOAD_BULLETS Function

• Allows adding loose bullets to a weapon with few bullets in its magazine.

• VALUE: Set to true to enable.

• SHOW_INPUT (optional boolean):

  • True: Player can choose how many bullets to add at once.

  • False: Adds bullets one at a time per item use.

• WEAPONS_ANIMATIONS (optional):

  • Uses animations and weapon positions for realism.

  • Default: activated.

  • Can be disabled by setting VALUE to false.

---

6. SET_WEAPON Function

• Handles temporarily removing the weapon from the ped.

• Fully customizable:

  • Add your own animations.

  • Use the weapon hash to target specific weapons.

  • WAIT parameter extends delay between animation and progress bar.

• POSITIONS:

  • Define weapon attachment positions during reload:

    • LONG: Long weapons.

    • SHORT: Short weapons/pistols.

  • Includes BONE, COORDS (x,y,z), and ROTATION (x,y,z).

• ANIMATIONS:

  • INTRO: When retrieving weapon.

  • OUTRO: When storing weapon.

  • Uses native TaskPlayAnim (Fivem Docs).

---

7. Additional ANIMATIONS Table

• Includes sub-tables for detailed reload animations:

  • MAGAZINE: Removing and inserting magazine; playback speed controlled by PLAY_BACK_RATE.

  • GET_BULLET: Simulates taking bullets from pocket/inventory.

  • LOAD_BULLET: Simulates inserting bullets into removed magazine.

---

8. WEAPONS Table 🔫

• Lists all weapons compatible with this system.

• Default weapons pre-configured.

• MODEL: Weapon object.

• CATEGORY:

  • LONG for rifles, shotguns, etc.

  • SHORT for pistols.

• Can be expanded for custom weapons if needed.