UltimateCustomGear

UltimateCustomGear is a data-driven NeoForge mod for Minecraft 1.21.1 that allows server owners, modpack creators, and players to add fully custom armor sets, weapons, tools, food items, items, blocks, and fluids — all through simple JSON files. No coding required.

Features

Content Creation

• Armor sets with per-piece stats (durability, defense, toughness, knockback resistance)
• Weapons — swords, bows, crossbows, and shields with custom damage, durability, and charge speed
• Tools — pickaxes, axes, shovels, and hoes with mining speed, harvest tiers, and area-tilling
• Food items with nutrition, saturation, eating speed, and on-eat effects
• Blocks — including directional and gravity-affected, with per-face textures, light, sounds, and mining requirements
• Fluids with custom colors, contact effects, and burning behavior

Effects & Gameplay

• Held effects, piece effects, and full-set bonuses
• Mob drops — any item can drop from mobs with configurable chance, count, and entity filters (hot-reloadable: balance your economy live)
• fire_resistant items that survive fire and lava, like netherite — works on items, food, gear, blocks, and buckets
• Transparent armor — armor with full stats and effects that draws nothing on the body

Textures & Models

• Reference vanilla/modded textures or provide your own PNG files
• Per-face block textures, bow-pulling animations, custom armor layers

Recipes & Tags

• Native recipe system — shaped, shapeless, smelting, blasting, and smithing, defined in JSON
• Recipe ingredients support tags ("#minecraft:planks" = any plank type, including items from other mods)
• Content can belong to tags via a tags field, so your items work in other mods' recipes

Server & Multiplayer

• Content packs — distribute everything as a single .zip that players drop into packs/
• Multiplayer content verification — the server checks at login that clients have matching files, with configurable enforcement
• /customgear reload — update names, effects, recipes, and drops without restarting

Quality of Life

• Full multi-language support per item
• Informative tooltips (effects, set bonuses, harvest levels, mob drops)
• Clear validation errors that name the file and the exact problem

Installation

1. Download and install NeoForge 1.21.1
2. Place ultimatecustomgear-1.x.x.jar in your mods/ folder
3. Launch the game once to generate the ultimatecustomgear/ folder inside .minecraft/
4. Add your JSON files to .minecraft/ultimatecustomgear/ — or drop a content .zip into .minecraft/ultimatecustomgear/packs/ (see Content Packs below)
5. Restart the game

JSON syntax note: Standard JSON does not allow trailing commas. A trailing comma after the last element in an object or array will cause the file to be silently skipped on load.

JSON File Structure

All JSON files go inside .minecraft/ultimatecustomgear/. Each file defines one item, set, block, or fluid. Files can be organized in any subfolder structure you prefer.

Content can also be packaged as .zip files inside packs/ — see the Content Packs section.

Supported types

JSON Examples

Food Item — Full Example

{
  "id": "magic_apple",
  "type": "food",
  "names": {
    "en_us": "Magic Apple",
    "es_mx": "Manzana Mágica"
  },
  "nutrition": 4,
  "saturation": 1.2,
  "always_edible": true,
  "on_eat_effects": [
    { "effect": "minecraft:regeneration",    "amplifier": 1, "duration": 10,  "probability": 1.0 },
    { "effect": "minecraft:absorption",      "amplifier": 0, "duration": 120, "probability": 1.0 },
    { "effect": "minecraft:fire_resistance", "amplifier": 0, "duration": 30,  "probability": 1.0 },
    { "effect": "minecraft:resistance",      "amplifier": 0, "duration": 300, "probability": 1.0 }
  ],
  "texture": {
    "mode": "reference",
    "refs": { "item": "minecraft:item/golden_apple" }
  },
  "recipe": {
    "type": "shaped",
    "pattern": ["GGG","GAG","GGG"],
    "key": { "G": "minecraft:gold_block", "A": "minecraft:apple" }
  }
}

Instant food (eat_duration: 0) and slow food (eat_duration: 10 = 10 seconds) are also supported.

Armor Set — Full Example

{
  "id": "my_armor",
  "type": "armor_set",
  "piece_names": {
    "en_us": {
      "helmet":     "My Armor Helmet",
      "chestplate": "My Armor Chestplate",
      "leggings":   "My Armor Leggings",
      "boots":      "My Armor Boots"
    },
    "es_mx": {
      "helmet":     "Casco de Mi Armadura",
      "chestplate": "Pechera de Mi Armadura",
      "leggings":   "Pantalones de Mi Armadura",
      "boots":      "Botas de Mi Armadura"
    }
  },
  "pieces": {
    "helmet":     { "durability": 363, "defense": 3, "toughness": 1.0, "knockback_resistance": 0.0 },
    "chestplate": { "durability": 528, "defense": 8, "toughness": 2.0, "knockback_resistance": 0.1 },
    "leggings":   { "durability": 495, "defense": 6, "toughness": 1.5, "knockback_resistance": 0.1 },
    "boots":      { "durability": 429, "defense": 3, "toughness": 1.0, "knockback_resistance": 0.0 }
  },
  "enchantable": true,
  "enchantability": 15,
  "piece_effects": {
    "helmet": [ { "effect": "minecraft:night_vision", "amplifier": 0 } ],
    "boots":  [ { "effect": "minecraft:jump_boost",   "amplifier": 0 } ]
  },
  "set_bonus": {
    "required_pieces": 4,
    "effects": [
      { "effect": "minecraft:strength",   "amplifier": 1 },
      { "effect": "minecraft:resistance", "amplifier": 0 }
    ]
  },
  "texture": {
    "mode": "reference",
    "refs": {
      "helmet":     "minecraft:item/diamond_helmet",
      "chestplate": "minecraft:item/diamond_chestplate",
      "leggings":   "minecraft:item/diamond_leggings",
      "boots":      "minecraft:item/diamond_boots"
    },
    "armor_layers": {
      "layer_1": "minecraft:models/armor/diamond_layer_1",
      "layer_2": "minecraft:models/armor/diamond_layer_2"
    }
  },
  "recipes": {
    "helmet":     { "type": "shaped", "pattern": ["GGG","G G","   "], "key": {"G": "mymod:my_gem"} },
    "chestplate": { "type": "shaped", "pattern": ["G G","GGG","GGG"], "key": {"G": "mymod:my_gem"} },
    "leggings":   { "type": "shaped", "pattern": ["GGG","G G","G G"], "key": {"G": "mymod:my_gem"} },
    "boots":      { "type": "shaped", "pattern": ["   ","G G","G G"], "key": {"G": "mymod:my_gem"} }
  }
}

Tool Set — Full Example

Note: tool_set only supports pickaxe, axe, shovel, and hoe. To add a sword alongside tools, use a separate weapon_set or individual sword file.

{
  "id": "my_tools",
  "type": "tool_set",
  "tool_names": {
    "en_us": {
      "pickaxe": "My Pickaxe",
      "axe":     "My Axe",
      "shovel":  "My Shovel",
      "hoe":     "My Hoe"
    },
    "es_mx": {
      "pickaxe": "Mi Pico",
      "axe":     "Mi Hacha",
      "shovel":  "Mi Pala",
      "hoe":     "Mi Azada"
    }
  },
  "tools": {
    "pickaxe": {
      "durability": 8000,
      "attack_damage": 5.0,
      "attack_speed": 1.2,
      "mining_speed": 20.0,
      "harvest_level": 4,
      "held_effects": [ { "effect": "minecraft:haste", "amplifier": 1 } ]
    },
    "axe": {
      "durability": 7000,
      "attack_damage": 8.0,
      "attack_speed": 0.9,
      "mining_speed": 15.0,
      "harvest_level": 4
    },
    "shovel": {
      "durability": 6000,
      "attack_damage": 4.0,
      "attack_speed": 1.0,
      "mining_speed": 18.0,
      "harvest_level": 4
    },
    "hoe": {
      "durability": 5000,
      "attack_damage": 3.0,
      "attack_speed": 1.0,
      "mining_speed": 16.0,
      "harvest_level": 4,
      "till_radius": 3
    }
  },
  "enchantable": true,
  "enchantability": 22,
  "texture": {
    "mode": "reference",
    "refs": {
      "pickaxe": "minecraft:item/netherite_pickaxe",
      "axe":     "minecraft:item/netherite_axe",
      "shovel":  "minecraft:item/netherite_shovel",
      "hoe":     "minecraft:item/netherite_hoe"
    }
  },
  "recipes": {
    "pickaxe": { "type": "smithing_transform", "template": "minecraft:netherite_upgrade_smithing_template", "base": "mymod:my_diamond_pickaxe",  "addition": "minecraft:netherite_ingot" },
    "axe":     { "type": "smithing_transform", "template": "minecraft:netherite_upgrade_smithing_template", "base": "mymod:my_diamond_axe",     "addition": "minecraft:netherite_ingot" },
    "shovel":  { "type": "smithing_transform", "template": "minecraft:netherite_upgrade_smithing_template", "base": "mymod:my_diamond_shovel",  "addition": "minecraft:netherite_ingot" },
    "hoe":     { "type": "smithing_transform", "template": "minecraft:netherite_upgrade_smithing_template", "base": "mymod:my_diamond_hoe",     "addition": "minecraft:netherite_ingot" }
  }
}

Weapon Set — Full Example

{
  "id": "my_weapons",
  "type": "weapon_set",
  "weapon_names": {
    "en_us": {
      "sword":    "My Sword",
      "bow":      "My Bow",
      "crossbow": "My Crossbow",
      "shield":   "My Shield"
    },
    "es_mx": {
      "sword":    "Mi Espada",
      "bow":      "Mi Arco",
      "crossbow": "Mi Ballesta",
      "shield":   "Mi Escudo"
    }
  },
  "weapons": {
    "sword": {
      "durability": 2031,
      "attack_damage": 8.0,
      "attack_speed": 1.6,
      "held_effects": [ { "effect": "minecraft:strength", "amplifier": 1 } ]
    },
    "bow": {
      "durability": 384,
      "arrow_damage": 8.0,
      "arrow_damage_bonus": 2.0,
      "arrow_damage_multiplier": 1.3,
      "charge_speed": 1.0
    },
    "crossbow": {
      "durability": 465,
      "arrow_damage": 11.0,
      "arrow_damage_multiplier": 1.5,
      "charge_speed": 1.0
    },
    "shield": { "durability": 336 }
  },
  "enchantable": true,
  "enchantability": 15,
  "texture": {
    "mode": "reference",
    "refs": {
      "sword":    "minecraft:item/netherite_sword",
      "bow":      "minecraft:item/bow",
      "crossbow": "minecraft:item/crossbow",
      "shield":   "minecraft:item/shield"
    }
  },
  "recipes": {
    "sword": { "type": "smithing_transform", "template": "minecraft:netherite_upgrade_smithing_template", "base": "mymod:my_diamond_sword", "addition": "minecraft:netherite_ingot" }
  }
}

Individual Sword — Full Example

{
  "id": "my_sword",
  "type": "sword",
  "names": {
    "en_us": "My Custom Sword",
    "es_mx": "Mi Espada Personalizada"
  },
  "durability": 1561,
  "attack_damage": 8.0,
  "attack_damage_bonus": 0.0,
  "attack_speed": 1.6,
  "enchantable": true,
  "enchantability": 15,
  "held_effects": [ { "effect": "minecraft:strength", "amplifier": 1 } ],
  "texture": {
    "mode": "reference",
    "refs": { "sword": "minecraft:item/diamond_sword" }
  },
  "recipe": {
    "type": "shaped",
    "pattern": [" G ", " G ", " S "],
    "key": { "G": "mymod:my_gem", "S": "minecraft:stick" }
  }
}

Individual Bow — Full Example

{
  "id": "my_bow",
  "type": "bow",
  "names": {
    "en_us": "My Custom Bow",
    "es_mx": "Mi Arco Personalizado"
  },
  "durability": 600,
  "arrow_damage": 10.0,
  "arrow_damage_bonus": 1.0,
  "arrow_damage_multiplier": 1.2,
  "charge_speed": 1.0,
  "enchantable": true,
  "enchantability": 15,
  "texture": {
    "mode": "reference",
    "refs": { "bow": "minecraft:item/bow" }
  },
  "recipe": {
    "type": "shaped",
    "pattern": [" GT", "G T", " GT"],
    "key": { "G": "mymod:my_gem", "T": "minecraft:string" }
  }
}

Individual Crossbow — Full Example

{
  "id": "my_crossbow",
  "type": "crossbow",
  "names": {
    "en_us": "My Custom Crossbow",
    "es_mx": "Mi Ballesta Personalizada"
  },
  "durability": 465,
  "arrow_damage": 12.0,
  "arrow_damage_multiplier": 1.5,
  "charge_speed": 1.0,
  "enchantable": true,
  "enchantability": 15,
  "texture": {
    "mode": "reference",
    "refs": { "crossbow": "minecraft:item/crossbow" }
  }
}

Fluid with Contact Effects — Full Example

{
  "id": "poison_lake",
  "type": "fluid",
  "names": {
    "en_us": "Poison Lake",
    "es_mx": "Lago Venenoso"
  },
  "bucket_names": {
    "en_us": "{fluid_name} Bucket",
    "es_mx": "Cubeta de {fluid_name}"
  },
  "light_level": 3,
  "color": "0xFF4CAF50",
  "tick_rate": 10,
  "spread_distance": 6,
  "burns_entities": false,
  "contact_effect_interval": 2.0,
  "contact_effects": [
    { "effect": "minecraft:poison",   "amplifier": 0, "duration": 3 },
    { "effect": "minecraft:slowness", "amplifier": 1, "duration": 3 }
  ],
  "texture": {
    "mode": "default"
  }
}

Lava-like Fluid — Full Example

{
  "id": "magma_fluid",
  "type": "fluid",
  "names": {
    "en_us": "Magma Flow",
    "es_mx": "Flujo de Magma"
  },
  "bucket_names": {
    "en_us": "{fluid_name} Bucket",
    "es_mx": "Cubeta de {fluid_name}"
  },
  "light_level": 15,
  "color": "0xFFFF6600",
  "tick_rate": 30,
  "spread_distance": 4,
  "burns_entities": true,
  "burn_duration": 8,
  "contact_effect_interval": 1.0,
  "contact_effects": [
    { "effect": "minecraft:weakness",       "amplifier": 1, "duration": 5 },
    { "effect": "minecraft:mining_fatigue", "amplifier": 0, "duration": 5 }
  ],
  "texture": {
    "mode": "default"
  }
}

Block — Simple Example

{
  "id": "my_ore",
  "type": "block",
  "names": {
    "en_us": "My Ore",
    "es_mx": "Mi Mineral"
  },
  "light_level": 3,
  "destroy_time": 3.0,
  "explosion_resistance": 3.0,
  "map_color": "deepslate",
  "required_tool": "pickaxe",
  "harvest_level": 2,
  "sound": "stone",
  "texture": {
    "mode": "reference",
    "refs": {
      "block": "minecraft:block/diamond_ore"
    }
  }
}

Block with Per-Face Textures — Example

{
  "id": "multi_ore",
  "type": "block",
  "names": {
    "en_us": "Multi Ore",
    "es_mx": "Mineral Multi"
  },
  "texture": {
    "mode": "reference",
    "faces": {
      "top":    "minecraft:block/coal_ore",
      "bottom": "minecraft:block/iron_ore",
      "north":  "minecraft:block/gold_ore",
      "south":  "minecraft:block/redstone_ore",
      "east":   "minecraft:block/emerald_ore",
      "west":   "minecraft:block/diamond_ore"
    }
  }
}

Use "side" as a shortcut to apply the same texture to all 4 horizontal faces.

Directional Block — Example

{
  "id": "directional_block",
  "type": "block",
  "directional": true,
  "names": {
    "en_us": "My Machine",
    "es_mx": "Mi Máquina"
  },
  "texture": {
    "mode": "reference",
    "faces": {
      "top":    "minecraft:block/stone",
      "bottom": "minecraft:block/stone",
      "side":   "minecraft:block/stone",
      "north":  "minecraft:block/furnace_front_on"
    }
  }
}

The "north" face is the front face — it points toward the player when the block is placed.

Falling Block — Example

{
  "id": "my_falling_block",
  "type": "block",
  "gravity": true,
  "names": {
    "en_us": "My Falling Block",
    "es_mx": "Mi Bloque con Caída"
  },
  "sound": "sand",
  "destroy_time": 0.5,
  "explosion_resistance": 0.5,
  "texture": {
    "mode": "reference",
    "refs": { "block": "minecraft:block/sand" }
  }
}

Recipes

CustomGear supports native crafting recipes defined directly in JSON. No external mods are required.

Recipe types

Tags as ingredients

Any ingredient slot accepts a tag with the # prefix — the recipe will accept any item in that tag:

"key": {
  "P": "#minecraft:planks",
  "I": "#c:ingots/iron",
  "S": "minecraft:stick"
}

Works in shaped, shapeless, smelting, blasting, and smithing recipes. Recipes with structural errors (uneven pattern rows, undefined pattern symbols, unused keys, malformed IDs) are skipped with a detailed message in the log naming the item and the exact problem.

Individual item recipe

"recipe": {
  "type": "shaped",
  "pattern": [" G ", " G ", " S "],
  "key": { "G": "mymod:my_gem", "S": "minecraft:stick" }
}

For multiple recipes, use an array:

"recipe": [
  { "type": "shaped", ... },
  { "type": "smelting", "ingredient": "mymod:my_ore", "experience": 1.0, "cooking_time": 200 }
]

Set recipe (armor, tools, weapons)

"recipes": {
  "helmet":     { "type": "shaped", "pattern": ["GGG","G G","   "], "key": {"G": "mymod:my_gem"} },
  "chestplate": { "type": "shaped", "pattern": ["G G","GGG","GGG"], "key": {"G": "mymod:my_gem"} },
  "leggings":   { "type": "shaped", "pattern": ["GGG","G G","G G"], "key": {"G": "mymod:my_gem"} },
  "boots":      { "type": "shaped", "pattern": ["   ","G G","G G"], "key": {"G": "mymod:my_gem"} }
}

Smithing table recipe

"recipe": {
  "type": "smithing_transform",
  "template": "minecraft:netherite_upgrade_smithing_template",
  "base": "mymod:my_diamond_sword",
  "addition": "minecraft:netherite_ingot"
}

Ingredients support any item from any installed mod via resource location (e.g. "othermod:special_ingot").

Tags

Two sides of the same system:

• Consuming a tag in a recipe uses the # prefix: "#minecraft:planks" accepts any item in that tag (see Recipes → Tags as ingredients).
• Belonging to a tag uses the tags field on your content, WITHOUT #, so other mods' recipes — and your own — accept your item/block/fluid.

{
  "id": "ruby_ingot",
  "type": "item",
  "tags": ["c:ingots", "c:ingots/ruby"]
}

A tag is just the sum of everything that declares it — you can use vanilla tags, convention (c:) tags shared across mods, or invent your own (customgear:magic_gems). Your tags merge with existing ones of the same name.

Blocks are added to both the block and item tag registries (so recipes, which consume the item form, accept your block). Fluids tag the fluid and their bucket item. Armor/tool/weapon sets are not supported yet (their IDs are derived per piece).

Common tags

Vanilla tags (minecraft:) — make your content count as a vanilla material:

Convention tags (c:) — the cross-mod interoperability standard (most useful):

Tip: use the general tag AND the material subtag (c:ingots and c:ingots/ruby) for maximum compatibility — the first for "any ingot", the second for "ruby ingot specifically".

Textures

Three texture modes are available:

Reference mode example

"texture": {
  "mode": "reference",
  "refs": { "sword": "minecraft:item/netherite_sword" }
}

For bows and crossbows, you can optionally include custom pulling/loading frame models:

"texture": {
  "mode": "reference",
  "refs": {
    "bow":           "othermod:item/epic_bow",
    "bow_pulling_0": "othermod:item/epic_bow_pulling_0",
    "bow_pulling_1": "othermod:item/epic_bow_pulling_1",
    "bow_pulling_2": "othermod:item/epic_bow_pulling_2"
  }
}

Content Packs

You can distribute your content as a single .zip file instead of loose files. Drop the zip into:

.minecraft/ultimatecustomgear/packs/your-content.zip

JSONs and textures inside the zip load exactly like loose files — subfolders inside the zip are fine. This is the recommended way for server owners to share content with players: one file, impossible to half-extract or edit by accident.

Rules:

• Zips are only loaded from the packs/ subfolder. A zip anywhere else is ignored (with a log message telling you where to move it).
• Only .zip is supported. If you have a .rar or .7z, re-compress it as zip: on Windows, select the files → right-click → Send to → Compressed folder.
• Loose files win over zips. If a loose JSON defines the same id as one inside a zip, the loose file is used entirely (stats, textures, recipes), and the zip entry is skipped with a log message. You can use this to locally override a single item from a pack without touching the zip.
• Multiple zips are allowed; they load in alphabetical order.
• /customgear reload picks up added or updated zips without restarting.

A distributable pack should be self-contained: every texture a JSON references must live inside the same zip. Referencing a loose texture from a zipped JSON works locally, but players who only receive the zip won't have the loose file. (Loose files still override zip contents of the same path — handy for local tweaks.)

Field Reference

Common Fields

Food Fields

Armor Fields

Tool Fields

Weapon Fields

Individual Weapon/Tool Fields

Individual items (type: "sword", type: "bow", etc.) use the same fields as above but at the root level instead of nested inside weapons or tools.

Attack Damage Reference

Effect Object

Texture Fields

refs vs faces: refs handles everything — a single texture with the all key ("refs": { "all": "..." }), or per-face textures with the face keys (top, bottom, north, south, east, west, side). faces is a legacy alias that only works for per-face textures. Use refs. (The block key is a legacy alias of all.) Note: all/block only work inside refs, never inside faces.

Recipe Fields

Fluid Fields

contact_effects[].duration should be at least ~2 seconds longer than contact_effect_interval, or damage-over-time effects (poison, wither) won't get the chance to tick. The defaults (duration 3, interval 1.0) are safe.

⚠️ Dropped items inside a fluid with burns_entities: true catch fire and are destroyed, exactly like in lava — players who die in it will lose their drops. Design accordingly.

Block Fields

With harvest_level ≥ 1, the block behaves like vanilla ore: the wrong tool or a lower tier is slow AND drops nothing. With level 0 (or omitted), required_tool only grants mining speed — the block drops with anything, like sand. Works with modded tools that follow vanilla tiers. Note: switching harvest_level between 0 and ≥1 requires a restart (the drop requirement is baked at startup); adjusting it between 1–4, or changing required_tool, applies with /customgear reload.

Mob Drops

Items and food can drop from mobs on death via the mob_drops object:

"mob_drops": {
  "chance": 0.10,
  "min": 1,
  "max": 3,
  "requires_player_kill": true,
  "entities": ["all"]
}

Players, armor stands, boats, and minecarts never drop items. Changes apply live with /customgear reload — you can tune your server's economy without restarting.

Items with mob_drops show a "Dropped by" section in their tooltip, with the source mobs and the drop chance.

Commands

What the reload command updates

• Item names
• Held effects (weapons and tools)
• Piece effects and set bonuses (armor)
• Fluid contact effects and burning behavior
• Recipes (the command reloads data packs automatically)
• Block mining tags — required_tool changes and harvest_level adjustments (1–4)
• Durability display
• Textures and models — after pressing F3+T (the game only reloads client resources on demand)
• Mob drop settings (chance, min/max, entities)

What requires a full game restart

• Attack damage and attack speed
• Armor defense, toughness, and knockback resistance
• Tool mining speed and tool tier (tool sets)
• Enabling/disabling a block's drop requirement (harvest_level 0 ↔ ≥1)
• Adding or removing items (new or deleted JSON files)
• Changing item IDs
• fire_resistant changes
• Switching an armor layer between mechanisms (reference ↔ custom ↔ transparent)

Multiplayer

Client and server must have the same content files. Item stats are baked in when the game starts, so differing files cause invisible desyncs (your tooltip says one damage value, the server applies another). To prevent this, the mod verifies content at login by comparing content hashes — packaging doesn't matter: a server using a zip matches clients using the same JSONs loose, and vice versa.

What happens on a mismatch is configured on the server in config/ultimatecustomgear-common.toml:

Only the server's setting matters — a client's local config has no effect when joining a server.

Distributing content: pack your ultimatecustomgear JSONs (and textures) into a zip, share it, and have players drop it into their.minecraft/ultimatecustomgear/packs/ folder.

Both sides must run the same mod version: 1.3.0 clients cannot join older servers and vice versa (network protocol change).

Item ID Reference

Compatibility

• Minecraft 1.21.1
• NeoForge 21.1.x
• JEI (optional, recommended) — recipes are fully visible
• Modded enchantments work automatically on enchantable items
• Models from any installed mod can be referenced with reference mode
• Ingredients from any installed mod can be used in recipes
• Multiplayer: server and clients must run the same mod version and matching content files (verified automatically at login)

License

MIT License — see LICENSE file for details.