Configuration

Where you edit

configs/config.lua — one file.

Labels: locales/en.json. Restart after config or item changes.

Item names

Carriers (Config.VestItems):

pegasus_carrier, merryweather_carrier, fib_carrier, noose_carrier, armstrong_carrier.

Plates (Config.RepairPlates) — keep these names on upgrade; they are also the modular plate names:

pegasus_light_repair_plate, merryweather_standard_repair_plate, fib_tactical_repair_plate, noose_heavy_repair_plate, armstrong_elite_repair_plate.

Helmet, broken plate, and repair material — names already in shipped config. Add the inventory defs if you want the features. No PNGs ship for them.

Carrier fields

Shipped compatibility: Pegasus light only; Merryweather light+standard; FIB through tactical; NOOSE through heavy; Armstrong all five types.

Plate fields

Helmet fields

Strength, Condition, Resist, Clothing, optional Jobs. Max condition is Strength * 10. Condition > 0 disables critical hits (SetPedSuffersCriticalHits). Head hits apply helmet loss through Resist.

Clothing component IDs

The clothing table is drawable / texture per gender, not the component index. Those IDs are hardcoded:

Shipped drawables: every carrier male = 11, female = 1; tactical_helmet male = 39, female = 38. Textures are 0. Change the drawable numbers to match your clothing pack.

Config.Settings.DisableVestClothing skips both vest and helmet appearance. Freemode peds only (mp_m_freemode_01 / mp_f_freemode_01).

Metadata

SchemaVersion = 2. Older items migrate the first time they are handled. You do not need to rewrite every inventory row on install.

On normalize: SerialNumber is preserved (or generated). Strength, Clothing, SlotCount, and PlateCarrier come from the current config. A missing Plates table is filled from legacy Condition using DefaultPlate. Condition becomes the sum of plate conditions (capped at Strength * 10). description is rewritten.

Carrier (NormalizeCarrierMetadata)

{
    SchemaVersion = 2,
    PlateCarrier = true,
    SerialNumber = '...',
    Strength = 6,
    SlotCount = 2,
    Clothing = { drawable = { male = 11, female = 1 }, texture = { male = 0, female = 0 } },
    Plates = {
        [1] = {
            slot = 1,
            item = 'merryweather_standard_repair_plate',
            condition = 30,
            max = 30,
            max0 = 30,
            serial = '...',
            material = 'ceramic',
            priority = 2,
        },
    },
    PlateWeight = 700,
    Condition = 30, -- sum of plate conditions
    description = '...',
}

Loose plate (after remove / swap)

PlateCondition, PlateMax, PlateMax0, PlateSerial.

Broken plate

material, originalItem, serial.

Helmet (NormalizeHelmetMetadata)

{
    SchemaVersion = 2,
    PlateHelmet = true,
    SerialNumber = '...',
    Strength = 5,
    Condition = 50,
    MaxCondition = 50,
    Clothing = { drawable = { male = 39, female = 38 }, texture = { male = 0, female = 0 } },
    description = '...',
}

Equipped gear is stored on player metadata keys PlateCarrier and PlateHelmet as { name, metadata }.

Repair / insert / remove

Equip — use a carrier item. Progress Durations.Equip. Swapping returns the old carrier to inventory.

Insert — use a plate while wearing a compatible carrier → first empty slot. If every slot is filled, slot 1 is replaced. Use a plate with no vest equipped → menu of carriers in inventory. With EnableOxExclusiveFeatures, dragging a plate onto a carrier in ox_inventory inserts with no progress bar.

Remove plate — /inspectvest or OpenPlateCarrierMenu on the equipped carrier. Condition > 0 returns the plate item; 0 returns broken_armor_plate.

Field repair — use armor_repair_material while wearing a vest. Repairs the lowest-percent plate by RepairMaterialValue. If DiminishingRepairs.Enabled, that plate’s max drops by Percent (0.03) down to max0 * Minimum (0.5).

Station repair — equipped vest only. Pays station.repairCost (default one armor_repair_material) and fills each damaged plate to its diminished max.

Station salvage — one broken_armor_plate → salvageYield of armor_repair_material (default 1).

Unequip — /removevest (key Config.RegisteredKeyMapping) or ForceRemovePlayerVest. Helmet: /removehelmet.

Gates (InVehicle, Swimming, Dead, Cuffed) block the progress callback when true.

Stations

Config.Stations ships empty. Uncomment and set your own coords:

['mission_row_armory'] = {
    coords = vector4(452.6, -980.0, 30.7, 90.0),
    model = `prop_tool_bench02`,
    jobs = { police = 0 },
    repairCost = { [Config.RepairMaterialItem] = 1 },
    salvageYield = 1,
    radius = 50.0,
},

Must be within Config.Settings.ActionDistance (3.0). Recipes are validated server-side.

Optional Buckshot_Crafting JSON: [INSTALL]/crafting/README.md.

State bags

Replicated, read-only snapshots. Do not write these from another resource.

plates[slot] is { item, condition, max, material } or false for an empty slot.