# 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](https://github.com/AntonIT99/Flans-Mod-Ultimate-2.0/wiki/ConfigReference).

## 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:

```text
config/flansmodultimate/
```

Built-in default examples are copied to:

```text
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:

```json
{}
```

A category file with one category looks like this:

```json
{
  "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:

```text
ShortName AK47
```

Use this in a category:

```json
"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](https://github.com/AntonIT99/Flans-Mod-Ultimate-2.0/wiki/ConfigReference) 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:

```json
"RoundsPerMin": 750
```

```json
"ExplosiveMass": "0.085"
```

```json
"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:

```json
"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:

```text
AddRound AP 1 162 0 800 45
```

Category value:

```json
"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:

```text
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:

```text
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:

```text
config/flansmodultimate/default/
```

Then it loads your user categories from:

```text
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:

```text
config/flansmodultimate-content-loading.properties
```

Set:

```properties
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`

```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`

```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`

```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`

```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`

```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](https://github.com/AntonIT99/Flans-Mod-Ultimate-2.0/wiki/ConfigReference).
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](https://github.com/AntonIT99/Flans-Mod-Ultimate-2.0/wiki/ConfigReference). |
| 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`. |