Skip to content

Category System

Jump to bottom
AntonIT99 edited this page May 26, 2026 · 3 revisions

Category System

The category system lets you apply content-pack settings to groups of items without editing every item .txt file. It is useful for server balancing, modpacks, and large content packs where many guns, bullets, grenades, or other items should share the same values.

For the full list of content-pack parameters that can be used in category properties, see Config Reference.

What Categories Do

A category is a named group with:

  • items: the short names of the items affected by the category.
  • properties: content-pack parameters to apply to all of those items.

When the mod loads an item, it reads the item's normal content-pack .txt file and then applies matching category properties. For simple one-value settings, category properties usually override the value from the content-pack file. For repeatable settings, category properties add extra lines.

This means categories are a good way to:

  • rebalance many weapons at once;
  • create shared behavior for ammunition groups;
  • override built-in default tuning without editing content packs;
  • keep local/server balance changes separate from downloaded content packs.

Where Category Files Are

User-editable category files are in:

config/flansmodultimate/

Built-in default examples are copied to:

config/flansmodultimate/default/

Do not put your custom edits in the default folder. Those files are owned by the mod and may be refreshed when the built-in defaults change. Put your edits in the matching file directly inside config/flansmodultimate/.

Category Files by Type

Each item type has its own category file.

Item type Category file Content-pack folder
AA guns aagun_categories.json aaguns
Armor armor_categories.json armorFiles
Armor boxes armor_box_categories.json armorBoxes
Attachments attachment_categories.json attachments
Bullets and ammunition bullet_categories.json bullets
Gloves glove_categories.json gloves
Grenades and thrown shootables grenade_categories.json grenades
Guns gun_categories.json guns
Gun boxes gun_box_categories.json boxes
Item holders item_holder_categories.json itemHolders
Parts part_categories.json parts
Tools tool_categories.json tools

If you want to edit guns, use gun_categories.json. If you want to edit bullets or ammo, use bullet_categories.json. A gun category cannot affect a bullet, and a bullet category cannot affect a gun.

Basic JSON Format

An empty category file should contain:

{}

A category file with one category looks like this:

{
  "Category Name": {
    "properties": {
      "ConfigKey": "value",
      "AnotherConfigKey": 123
    },
    "items": [
      "item_short_name_1",
      "item_short_name_2"
    ]
  }
}

The category name is only a label for humans. Use clear names such as "Assault Rifle Tuning" or "Heavy Explosive Ammo".

Item Names

Items are matched by their content-pack ShortName, not by display name, file name, or Minecraft registry ID.

Example content-pack line:

ShortName AK47

Use this in a category:

"items": [
  "ak47"
]

Short names are sanitized by the mod, so it is best to write them in lowercase and replace spaces with underscores.

Property Names

Property names are the same settings used in content-pack .txt files. For example:

  • gun properties such as RoundsPerMin, MuzzleVelocity, Dispersion, Recoil;
  • bullet properties such as Mass, FallSpeed, ExplosiveMass, PenetrationAt100m;
  • grenade properties such as Fuse, ExplosiveMass, FragType;
  • armor properties such as Defence, DamageReduction, Durability.

Use Config Reference to find the exact property name, expected format, default value, and which type supports it.

Property Values

Category property values may be:

  • a JSON string;
  • a JSON number;
  • an array of strings or numbers.

Examples:

"RoundsPerMin": 750
"ExplosiveMass": "0.085"
"AddRound": [
  "AP 1 162 0 800 45",
  "HE 2 135 0.016 835 0"
]

Do not use raw JSON booleans inside properties. Use strings instead:

"TranslucentRendering": "true"

or use 1 / 0 where the content-pack parameter accepts boolean-style values.

For properties that normally have several values on one line, put the whole value part in one string. Do not repeat the property name inside the value.

Content-pack line:

AddRound AP 1 162 0 800 45

Category value:

"AddRound": "AP 1 162 0 800 45"

If you need several AddRound lines, use an array.

Override and Add Behavior

The category system adds property lines after the item's normal content-pack lines. Most single-value parameters use the last value, so category values override the content-pack value.

Example:

Content-pack gun file: RoundsPerMin 600
Category property:     "RoundsPerMin": 750
Final value:           750

Repeatable parameters keep multiple lines. Category values are added to the existing lines.

Example:

Content-pack bullet file: AddRound Ball 1 147 0 850 30
Category property:      "AddRound": "Tracer 1 145 0 850 25"
Final result:           both rounds are available

If an item belongs to several categories that set the same single-value property, the later applied category wins. Avoid putting the same item in several categories that edit the same value unless you are deliberately overriding something.

Default Categories and User Categories

By default, the mod loads built-in categories from:

config/flansmodultimate/default/

Then it loads your user categories from:

config/flansmodultimate/

Because user categories load after default categories, your user category can override default category values for the same items.

To disable all built-in default categories, edit:

config/flansmodultimate-content-loading.properties

Set:

useDefaultCategories=false

Leave this enabled if you want the mod's built-in balancing categories. Disable it if you want category behavior to come only from your own JSON files.

Examples

Tune a Gun Group

File: config/flansmodultimate/gun_categories.json

{
  "Assault Rifle Balance": {
    "properties": {
      "RoundsPerMin": 650,
      "Dispersion": 0.28,
      "Recoil": 1.1
    },
    "items": [
      "ak47",
      "m16a4",
      "g36c"
    ]
  }
}

This applies the same rate of fire, dispersion, and recoil to all listed guns.

Override One Default Weapon Value

File: config/flansmodultimate/gun_categories.json

{
  "My AK Override": {
    "properties": {
      "Dispersion": 0.18
    },
    "items": [
      "ak47"
    ]
  }
}

If a built-in default category also changes ak47 dispersion, this user category wins because user categories load after default categories.

Create Heavy Explosive Ammo

File: config/flansmodultimate/bullet_categories.json

{
  "Heavy Explosive Ammo": {
    "properties": {
      "Mass": 42,
      "ExplosiveMass": "0.0013",
      "PenetrationAt100m": 20
    },
    "items": [
      "barrettexplosiveammo"
    ]
  }
}

This changes the physical and explosive behavior of the listed bullet item.

Add Several Rounds to Ammo

File: config/flansmodultimate/bullet_categories.json

{
  "Mixed 20mm Rounds": {
    "properties": {
      "AddRound": [
        "AP 1 162 0 800 45",
        "HE 2 135 0.016 835 0"
      ]
    },
    "items": [
      "20mmammo"
    ]
  }
}

Each array entry behaves like one extra AddRound line in the bullet config.

Tune Grenades

File: config/flansmodultimate/grenade_categories.json

{
  "Frag Grenades": {
    "properties": {
      "ExplosiveMass": "0.085",
      "FragType": "STD_FRAG",
      "Fuse": 80
    },
    "items": [
      "mk2frag",
      "44_mk2frag"
    ]
  }
}

Fuse is measured in ticks. Minecraft runs 20 ticks per second, so 80 ticks is about 4 seconds.

Recommended Workflow

  1. Start the game or server once so the category files are generated.
  2. Open the matching file in config/flansmodultimate/.
  3. Find the item's ShortName in its content-pack .txt file.
  4. Find the property you want in Config Reference.
  5. Add or edit your category JSON.
  6. Restart the game or server.
  7. Test the affected items in-game.

For multiplayer, apply gameplay categories on the server and keep clients in sync with the same content/category setup when the changes affect item behavior, models, or generated assets.

Troubleshooting

Problem What to check
The game fails to start after editing a category file Validate the JSON. Check commas, quotes, brackets, and that the file is not empty. Use {} for an empty file.
A category does not affect an item Check that the item is in the correct type file and that items uses the item's ShortName.
A property is ignored Make sure the property is valid for that item type. Use Config Reference.
A boolean property causes problems Use "true" or "false" as a string, not raw JSON true or false.
A multi-value property only partially works Put the whole right-hand side in one string, such as "AP 1 162 0 800 45".
Default category behavior still applies Override the same property in your user category, or set useDefaultCategories=false.
Your custom edits disappeared Make sure you edited config/flansmodultimate/*.json, not config/flansmodultimate/default/*.json.

Clone this wiki locally