Weapons in stash with colors from Color Converter API

Difference between normal and the same built Meta Variant weapon

Variant weapons in Fence

Variant weapons in Flea Market

Blicky Rifle Grenade Launcher!

AK-101 World War II Variant in Hideout

Colored names!

Installation Steps

1. Download the Mod: Obtain the mod by clicking blue “Download Latest Version” button

2. Unpack the Mod: Extract the contents of the downloaded file to a suitable location

3. Move the User Folder:

• Locate the “SPT” folder within the extracted mod files
• Transfer this folder into the main SPT directory

Configuration Steps

The configuration file is located in the following path:

• Path: SPT 4.0\SPT\user\mods\DefinitiveWeaponVariants\config

1. Copy the Default Config File:

• Make a copy of the “defaultConfig.jsonc” file
• Rename the copied file to “config.jsonc”
• or…
• Run server once and it will do it for you!

2. Modify Configuration Settings:

• Open the newly renamed “config.jsonc” file for editing
• Adjust the settings as needed according to your preferences
• Do not touch the “defaultConfig.jsonc”!

This manual can help you create your own variants.

You should have at least basic JSON knowledge or at least some pattern recognition skills.
Please use Notepad++ or a better text editor.
If you need help, you can message me on Discord.

Terminology

• MongoID – A 24-character hexadecimal number that represents any item in the game.
  Example: AK-74N → "5644bd2b4bdc2d3b4c8b4572" (https://db.sp-tarkov.com/search/5644bd2b4bdc2d3b4c8b4572)

• Preset – A set of items added to a weapon, creating a complete build.

• Filter – A list of MongoIDs representing which items can be used in a slot/chamber.

• ShortName – The name displayed on the item’s miniature in equipment.

• Variant ShortName – Weapon shortname + variant shortname.

• Slots – Places on a weapon where items can be attached.
  Example: slot "mod_magazine" has a filter listing all allowed magazines.

• Chambers – Most weapons have a chamber slot for a single round.
  The filter determines which ammo the weapon can fire.
  Weapons without a chamber will accept any ammo allowed by the magazine filter.

• Cartridges – (Magazine only) The filter that determines which ammo can be loaded into a magazine.

• FilterSlotConfiguration – Custom config used by this mod that makes creating or editing filters easier. You can replace existing filter, add new allowed items, or copy filters from other items.

• Key – A name for a piece of data in a JSON file.

• Keyed object – Means data stored under a specific key. When you edit a JSON file, you are changing values belonging to these keys.

Mod Paths

Do NOT edit existing files! You will lose your changes in every mod update.
All files in each folder are loaded automatically, so you can safely create new ones.

• db/01_Variants – Variant configuration — keyed by variant full name
• db/02_Items – Item configuration — keyed by item full name
• db/03_Shortnames – Weapon shortnames — keyed by weapon short name and containing MongoIDs as values
• db/04_Presets – Presets for variant weapons or base weapons — keyed by variant shortname or base weapon shortname
• db/99_Ids – Contains IDs of all created items — keyed by their text identifiers

Adding a Weapon from the Mod to the Database

This is not required, but it helps a lot when creating variants.

In db/03_Shortnames, create a new .json file:

• Weapon ShortName – The name used in db/01_Variants
• MongoID – The exact ID of the weapon

For easier ID search, I recommend:
https://forge.sp-tarkov.com/mod/1617/give-ui
You can find IDs by searching the item name.

Adding a Weapon to an Existing Variant

In db/01_Variants, create a new .json file:

• Variant full name – e.g. "Meta", "Buckshot Launcher", etc.
• List of weapon shortnames or MongoIDs – from db/03_Shortnames

You can optionally include "IndividualChanges" to apply changes only to certain weapons in this variant (details later).

Editing an Existing Variant

Coming in version 4.1!

Adding a New Variant Type

In db/01_Variants, create a new .json file.
Check existing variants for reference.

• key: "variant full name" – Full name of the variant (should not be changed after creation)

• Description – Flavor text

• Explanation – What this variant does

• ShortName – Shorter name of the variant full name (should not be changed after creation)

• Properties – List of properties to modify
  Types must match the original exactly (check db.sp-tarkov).
  For number values you may use:

  • +number%
  • -number%
  • +number
  • -number
    These modify the base value of the weapon.

• Changes

  • Parent – Change the weapon’s category by replacing its parent MongoID
  • AddToInventorySlots – Added weapon can be equipped additionally in: "FirstPrimaryWeapon", "SecondPrimaryWeapon", "Holster"
  • Minimum – Ensures a property has at least this value before applying modifications
    • For example: Useful for single fire mode weapons with extremely low BFireRate
  • Slots – Keyed by slot name
    Uses FilterSlotConfiguration, replaces or modifies filters
  • Chambers – Same as above, but for chambers
  • FilterSlotConfiguration details:
    • All lists can contain weapon shortnames, MongoIDs, or item full names
      • Filter – completely replaces the filter (empty [] removes the slot if it is only one)
      • FromWeapons – copies the filter from another item\
      • Add – keeps the current filter and adds to it

• IndividualChanges – Keyed by weapon shortname
  Can contain:

  • "Slots"
  • "Chambers"
  • "Properties"
    Use this to modify only certain weapons, not the entire variant.

• Barter

  • TraderId – Uppercase vanilla trader name
  • LoyalLevel – Required trader LL
  • UnlimitedCount – Whether stock is infinite
  • StackObjectsCount – Amount per restock
  • Price – What it costs
  • Barter – ID of item to barter for (omit for roubles)

• Weapons – List of weapon shortnames or MongoIDs the variant applies to

• WeaponIdToUseAs – Changes which weapon ID kill quests count as (omit to use base weapon)

• Rarity – One of the following:
  Unique, Ultimate, Superior, Advanced, Niche, Baseline, Flawed, Meme
  (Do NOT use other values)

Adding New Items

Some variants require custom attachments or magazines.
You can create them similarly to variant types.

In db/02_Items, create a new .json file:

• key: "full name of the item" – to reference it in FilterSlotConfiguration
• Description – Item description
• ShortName – Shorter item name
• ItemTplToClone – MongoID of the item to clone
• Properties – Same rules as for variants
• Changes
  • Slots – Same as variants
  • Cartridges – (magazines only) FilterSlotConfiguration
    • Add "Count" property to define ammo capacity
• Barter – Same as variants
• HandbookPriceRoubles – Base rouble value
• VariantType – Full name of the variant this item belongs to
• Rarity – Same as variants – should match VariantType

Adding a Preset

Presets allow the weapon variant to start with custom attachments.

You can create a preset in game and export it via:
https://forge.sp-tarkov.com/mod/106/spt-aki-profile-editor
Then remove all properties except " _items ".

In db/04_Presets, create a new .json file:

• Add a key using the Variant ShortName
• Include the "_items" list inside it

To replace an item with one created by this mod, add this to the correct slot:

"desc": "full name of the item"

This tells the preset to use the MongoID of your custom item.

You can also use a preset keyed by weapon shortname to replace base presets, e.g. to add a default scope to all variants of certain weapon.

Notes

• When you create a new variant or item, a file will appear in db/99_Ids.
  This file contains all IDs for the variants/items you created.
  Do NOT delete it — you will lose your custom items from your inventory after server restart.

• When creating addons, make sure you did not forget any file you created and files generated in db/99_Ids.
  Check the “Mod paths” section and verify every folder has the needed file(s).

“Extended” Compatibility:

Please note as of version 4.0 of this mod, extended compatibility for mods listed below are not yet available, so this information is only for SPT 3.11 users!

- AcidPhantasm - Progressive Bot System (APBS): blacklists.json file can be generated based on config file (APBS 1.7.2+ is required)

- Hood - The Gambler: Weapons.ts file can be generated based on config file (will use original Weapons.ts from mod installation as base)

“Works well with” Compatibility: (recommended mods!)

- Lacyway - Hands Are Not Busy: some unintended interactions between mods can cause your character to stop responding to any input, but if you have this mod, just use “End” to get rid of this issue!

- Tyfon - Weapon Customizer: allows moving changed magazines to better position

Full Compatibility:

- GhostFenixx - Server Value Modifier (SVM)

- Fika: Tested and confirmed to work

- Mods that introduce new attachments/magazines/ammo should be loaded before Weapon Variants

Partial Compatibility:

- BALIST0N - Kalashnikov Enhanced Modding - will work with this mod, but will disable a few variants

- AcidPhantasm - Item Valuation: will remove quality colors and item colors from variants and items introduced by this mod

- DrunkGeko - Geko’s Better Progression: will move 12.7x108mm B-32 ammo from Skier LL1 to LL4

- Valens - Make Marked Room Loot Great Again: will change odds of variants in marked room

Not Compatible:

- Fontaine - SPT Realism Mod - my mod is the furthest from realism you can get. Realism patch can be made, but I didn’t look into it yet

- Mods altering weapon handling may cause issues, potentially breaking some weapons

Suggestions

Don’t see your favourite weapon in your favourite variant?

Some weapon variant handles strange? Or is broken in some way?

You have experience in modding weapons and can help me balance or change further some variants?

Reach me out on discord, at “Szonszczyk”, and tell me all about it!

Credits

About half of the weapon variants were suggested by Amidorak

Play tested by Amidorak

Honorable mentions

GroovypenguinX - first versions of this mod was based on code from his mods

Hood - this mod was created to simply add new weapons to loot boxes. Oh well…

AcidPhantasm - for easy adding variants to enemies via APBS. Bots shooting Fullburst variant are the best

DeadLeaves - I found your code for text colors in Fika discord and added them to this mod

Valens - I based my Marked room code on your mod, sorry and thank you