Tier Engine (tiermod) — Developer Guide

Data-driven item tier system for Minecraft 1.20.1 / Forge. No Java required to configure tiers — only JSON files.

Languages: English · Português

English

What is this?

Tier Engine assigns classification labels (tiers) to items — like Common, Rare, Epic, Legendary. When a player crafts, fishes, smelts, uses an anvil, loots a chest, etc., the mod can roll a tier and store it on the item (NBT + tooltip).

You define tiers in datapacks and/or config/tiermod/ (config overrides datapack by id).

Where tier JSON lives

Datapack (base, ship with modpack):

data/<namespace>/tiermod/tiers/*.json
data/<namespace>/tiermod/groups/*.json

Config override (per server / local tweaks):

<game instance>/
└── config/
    └── tiermod/
        ├── tiers/          ← one or more *.json files (tier definitions)
        └── groups/         ← one or more *.json files (tier groups)

• Single-player / dev: usually run/config/tiermod/ when using ./gradlew runClient
• Server: <server folder>/config/tiermod/
• First run: if config folders are empty and createDefaultsOnFirstRun=true (default), the mod copies built-in examples from defaults/tiers/ and defaults/groups/
• Datapack defaults: the mod jar includes data/tiermod/tiers/global_tiers.json and data/tiermod/groups/rarity.json
• Reload: vanilla /reload or /tiermod reload rebuilds tiers; multiplayer clients receive display sync for tooltips (S2C)

Each tier file accepts any of these shapes:

{ "id": "my_tier", "display": { ... }, "behavior": { ... } }

[ { "id": "tier_a", ... }, { "id": "tier_b", ... } ]

{ "tiers": [ { "id": "tier_a", ... } ] }

Tier ids default to namespace tiermod (e.g. "common" → tiermod:common).

Hello world — your first tier

Create config/tiermod/tiers/my_first_tier.json:

{
  "id": "starter",
  "display": {
    "name": "Starter",
    "tooltip": "Your first custom tier!",
    "baseColor": "#55FF55",
    "shadowColor": "#228822"
  },
  "assignment": {
    "allowItems": ["minecraft:wooden_sword"]
  },
  "behavior": {
    "weight": 100,
    "triggers": ["COMMAND"]
  }
}

Test in-game (OP level 2):

1. Hold a wooden sword
2. /tiermod set starter — force-assign the tier
3. /tiermod get — confirm tier on item
4. After editing JSON: /tiermod reload

Full annotated example (every field)

Below is one test object showing every major mechanism. Field guide:

{
  "id": "masterwork_pickaxe",
  "inherit": "legendary",
  "display": {
    "name": "Masterwork Pickaxe Tier",
    "tooltip": "Forged by a veteran miner.",
    "baseColor": "#FFD700",
    "shadowColor": "#996600"
  },
  "assignment": {
    "allowItems": ["minecraft:diamond_pickaxe"],
    "allowMods": ["create"],
    "allowTags": ["#minecraft:pickaxes"]
  },
  "behavior": {
    "always": false,
    "weight": 5,
    "exclusiveGroup": "rarity",
    "triggers": [
      "ITEM_CRAFTED",
      "ITEM_LOOTED",
      "ITEM_FISHED",
      "ITEM_SMELTED",
      "ITEM_SMITHING",
      "ITEM_ANVIL",
      "ENTITY_DROP",
      "BLOCK_BREAK",
      "COMMAND"
    ],
    "conditions": {
      "and": [
        { "dimension": "minecraft:overworld" },
        { "player_level": { "greater_or_equal": 20 } }
      ]
    },
    "specialConditions": [
      {
        "condition": { "isNight": true },
        "weightMultiplier": 2.0
      },
      {
        "condition": { "biome": "minecraft:deep_dark" },
        "weightMultiplier": 3.0
      }
    ]
  },
  "effects": {
    "attributeModifiers": [
      {
        "attribute": "minecraft:generic.attack_damage",
        "amount": 1.0,
        "operation": "add",
        "slot": "mainhand"
      }
    ],
    "enchantments": [
      { "id": "minecraft:efficiency", "level": 3, "allowUnsafe": false }
    ],
    "visual": {
      "glint": true,
      "particles": ["minecraft:enchant"]
    },
    "custom": [
      { "id": "tiermod:example_hook", "payload": { "bonus": "mining" } }
    ]
  }
}

How tiers are obtained — one example per trigger

Each tier only rolls when its triggers list includes that event and the item matches assignment.

Craft (ITEM_CRAFTED)

config/tiermod/tiers/craft_tiers.json:

{
  "id": "crafted_fine",
  "display": {
    "name": "Fine Craft",
    "baseColor": "#88CCFF",
    "shadowColor": "#446688"
  },
  "assignment": {
    "allowTags": ["#minecraft:tools"]
  },
  "behavior": {
    "weight": 30,
    "exclusiveGroup": "rarity",
    "triggers": ["ITEM_CRAFTED"]
  }
}

Try it: Craft any tool at a crafting table (tier rolls automatically if other tiers in the group also match).

Fishing (ITEM_FISHED)

{
  "id": "anglers_prize",
  "display": {
    "name": "Angler's Prize",
    "tooltip": "A lucky catch.",
    "baseColor": "#00AAAA",
    "shadowColor": "#005555"
  },
  "assignment": {
    "allowMods": ["minecraft"],
    "allowTags": ["#minecraft:fishes"]
  },
  "behavior": {
    "weight": 10,
    "exclusiveGroup": "rarity",
    "triggers": ["ITEM_FISHED"],
    "conditions": { "biome": "#minecraft:is_ocean" }
  }
}

Try it: Fish in an ocean biome.

Furnace / smelting (ITEM_SMELTED)

{
  "id": "refined_ingot",
  "display": {
    "name": "Refined",
    "tooltip": "Purified by heat.",
    "baseColor": "#FFAA00",
    "shadowColor": "#884400"
  },
  "assignment": {
    "allowItems": ["minecraft:iron_ingot", "minecraft:gold_ingot", "minecraft:copper_ingot"]
  },
  "behavior": {
    "weight": 25,
    "triggers": ["ITEM_SMELTED"]
  }
}

Try it: Smelt raw ore in a furnace.

Anvil (ITEM_ANVIL)

{
  "id": "reinforced",
  "display": {
    "name": "Reinforced",
    "tooltip": "Hammered into perfection.",
    "baseColor": "#CCCCCC",
    "shadowColor": "#666666"
  },
  "assignment": {
    "allowTags": ["#minecraft:tools", "#minecraft:weapon"]
  },
  "behavior": {
    "weight": 15,
    "exclusiveGroup": "rarity",
    "triggers": ["ITEM_ANVIL"]
  }
}

Try it: Combine or repair a tool at an anvil.

Smithing table (ITEM_SMITHING)

{
  "id": "netherforged",
  "display": {
    "name": "Netherforged",
    "baseColor": "#4A0808",
    "shadowColor": "#220404"
  },
  "assignment": {
    "allowItems": ["minecraft:netherite_sword", "minecraft:netherite_pickaxe"]
  },
  "behavior": {
    "weight": 50,
    "triggers": ["ITEM_SMITHING"],
    "conditions": { "dimension": "minecraft:the_nether" }
  }
}

Loot chests (ITEM_LOOTED)

{
  "id": "dungeon_spoil",
  "display": {
    "name": "Dungeon Spoil",
    "baseColor": "#AA55FF",
    "shadowColor": "#552288"
  },
  "assignment": {
    "allowTags": ["#minecraft:swords"]
  },
  "behavior": {
    "weight": 20,
    "exclusiveGroup": "rarity",
    "triggers": ["ITEM_LOOTED"]
  }
}

Mob drops (ENTITY_DROP)

{
  "id": "hunter_mark",
  "display": {
    "name": "Hunter's Mark",
    "baseColor": "#FF5555",
    "shadowColor": "#882222"
  },
  "assignment": {
    "allowItems": ["minecraft:bone", "minecraft:rotten_flesh"]
  },
  "behavior": {
    "weight": 40,
    "triggers": ["ENTITY_DROP"]
  }
}

Block break (BLOCK_BREAK)

{
  "id": "vein_lucky",
  "display": {
    "name": "Vein Lucky",
    "baseColor": "#55FFAA",
    "shadowColor": "#228855"
  },
  "assignment": {
    "allowItems": ["minecraft:coal", "minecraft:raw_iron"]
  },
  "behavior": {
    "weight": 12,
    "triggers": ["BLOCK_BREAK"]
  }
}

Command / testing (COMMAND)

{
  "id": "debug_tier",
  "display": {
    "name": "Debug Tier",
    "baseColor": "#FFFFFF",
    "shadowColor": "#888888"
  },
  "assignment": {
    "allowTags": ["#minecraft:tools"]
  },
  "behavior": {
    "weight": 100,
    "triggers": ["COMMAND"]
  }
}

Try it: Hold a tool → /tiermod roll COMMAND

All tier “types” (mechanics)

1. Rarity group (weighted exclusive)

Only one tier from the group applies per item. Higher weight = more likely.

config/tiermod/groups/rarity.json:

{
  "id": "rarity",
  "exclusive": true,
  "tiers": ["common", "rare", "epic", "legendary"]
}

Each tier sets "exclusiveGroup": "rarity" and different weight values (e.g. 100 / 50 / 15 / 1).

2. Always tier (guaranteed)

"behavior": {
  "always": true,
  "weight": 0,
  "triggers": ["ITEM_CRAFTED"]
}

When eligible, this tier always wins over weighted rolls in the same exclusive group.

3. Inheritance (inherit)

Child tier reuses parent fields and overrides only what you specify:

{
  "id": "legendary_nether",
  "inherit": "legendary",
  "display": {
    "name": "Nether Legendary",
    "baseColor": "#FF4500",
    "shadowColor": "#662200"
  },
  "effects": {
    "visual": { "glint": true }
  }
}

4. Conditional tier (gate)

Tier only enters the roll pool if conditions pass:

"conditions": { "dimension": "minecraft:the_nether" }

"conditions": {
  "and": [
    { "biome": "minecraft:swamp" },
    { "isNight": true }
  ]
}

"conditions": { "player_level": { "greater_than": 30 } }

Condition keys: biome, dimension, isNight, player_level — combine with and, or, not.

5. Weight boost (specialConditions)

Does not block the tier — multiplies weight when extra conditions match:

"specialConditions": [
  {
    "condition": { "dimension": "minecraft:the_nether" },
    "weightMultiplier": 3.0
  }
]

Effective weight = baseWeight × (product of matching multipliers).

6. Tier with effects

When tier is assigned, effects apply to the item:

• Attributes: damage, speed, armor, etc.
• Enchantments: e.g. Unbreaking III
• Visual glint: shiny item without visible enchant text
• Custom payload: for KubeJS / addon hooks (see integrations spec)

In-game commands

All commands require OP level 2. Hold the target item in your main hand unless noted.

Fishing modpack example (v0.6.0 — heldItemTier)

Full scenario: 4 rod tiers affect 7 fish tier roll chances; legendary fish guaranteed in Deep Dark at night with the best rod.

Copy from examples/fishing/ into config/tiermod/ (see examples/fishing/README.md), then /tiermod reload.

Quick test:

1. Hold a fishing rod → /tiermod set rod_t4
2. Go to Deep Dark at night
3. Fish — every catch should be Sculk Legend Catch (fish_tier_7)

How rod quality affects fish: fish tiers use specialConditions with heldItemTier:

"specialConditions": [
  { "condition": { "heldItemTier": "rod_t4" }, "weightMultiplier": 5.0 }
]

Legendary gate (always wins when eligible):

"conditions": {
  "and": [
    { "biome": "minecraft:deep_dark" },
    { "isNight": true },
    { "heldItemTier": "rod_t4" }
  ]
}

Automated tests: FishingScenarioTest in the project test suite.

Troubleshooting

Fail-closed: If a condition needs player position/biome but context is missing, it evaluates to false (tier skipped).

Optional integration addons (v0.5.0)

Separate jars — install only what you need:

Details: .cursor/specs/integrations.md

Português

O que é?

O Tier Engine atribui rótulos de classificação (tiers) aos itens — como Comum, Raro, Épico, Lendário. Quando o jogador crafta, pesca, funde na fornalha, usa a bigorna, abre baús, etc., o mod pode sortear um tier e gravá-lo no item (NBT + tooltip).

Tudo é configurado em JSON dentro de config/tiermod/. Não precisa de Java.

Onde ficam os arquivos de config

<instância do jogo>/
└── config/
    └── tiermod/
        ├── tiers/          ← um ou mais arquivos *.json (definições de tier)
        └── groups/         ← um ou mais arquivos *.json (grupos de tier)

• Single-player / dev: geralmente run/config/tiermod/ ao usar ./gradlew runClient
• Servidor: <pasta do servidor>/config/tiermod/
• Primeira execução: se config/tiermod/ estiver vazio e createDefaultsOnFirstRun=true (padrão), o mod copia exemplos para config
• Defaults em datapack: o jar inclui data/tiermod/tiers/global_tiers.json e data/tiermod/groups/rarity.json
• Reload: /reload vanilla ou /tiermod reload; em multiplayer, clientes recebem sync S2C para tooltips

Cada arquivo de tier aceita qualquer destes formatos:

{ "id": "meu_tier", "display": { ... }, "behavior": { ... } }

[ { "id": "tier_a", ... }, { "id": "tier_b", ... } ]

{ "tiers": [ { "id": "tier_a", ... } ] }

Ids de tier usam namespace tiermod por padrão ("common" → tiermod:common).

Hello world — seu primeiro tier

Crie config/tiermod/tiers/meu_primeiro_tier.json:

{
  "id": "starter",
  "display": {
    "name": "Iniciante",
    "tooltip": "Seu primeiro tier customizado!",
    "baseColor": "#55FF55",
    "shadowColor": "#228822"
  },
  "assignment": {
    "allowItems": ["minecraft:wooden_sword"]
  },
  "behavior": {
    "weight": 100,
    "triggers": ["COMMAND"]
  }
}

Teste no jogo (OP nível 2):

1. Segure uma espada de madeira
2. /tiermod set starter — força o tier no item
3. /tiermod get — confirma o tier
4. Depois de editar JSON: /tiermod reload

Exemplo completo anotado (todos os campos)

Objeto de teste com cada mecanismo. Guia de campos:

{
  "id": "masterwork_pickaxe",
  "inherit": "legendary",
  "display": {
    "name": "Tier Picareta Obra-prima",
    "tooltip": "Forjada por um minerador veterano.",
    "baseColor": "#FFD700",
    "shadowColor": "#996600"
  },
  "assignment": {
    "allowItems": ["minecraft:diamond_pickaxe"],
    "allowMods": ["create"],
    "allowTags": ["#minecraft:pickaxes"]
  },
  "behavior": {
    "always": false,
    "weight": 5,
    "exclusiveGroup": "rarity",
    "triggers": [
      "ITEM_CRAFTED",
      "ITEM_LOOTED",
      "ITEM_FISHED",
      "ITEM_SMELTED",
      "ITEM_SMITHING",
      "ITEM_ANVIL",
      "ENTITY_DROP",
      "BLOCK_BREAK",
      "COMMAND"
    ],
    "conditions": {
      "and": [
        { "dimension": "minecraft:overworld" },
        { "player_level": { "greater_or_equal": 20 } }
      ]
    },
    "specialConditions": [
      {
        "condition": { "isNight": true },
        "weightMultiplier": 2.0
      },
      {
        "condition": { "biome": "minecraft:deep_dark" },
        "weightMultiplier": 3.0
      }
    ]
  },
  "effects": {
    "attributeModifiers": [
      {
        "attribute": "minecraft:generic.attack_damage",
        "amount": 1.0,
        "operation": "add",
        "slot": "mainhand"
      }
    ],
    "enchantments": [
      { "id": "minecraft:efficiency", "level": 3, "allowUnsafe": false }
    ],
    "visual": {
      "glint": true,
      "particles": ["minecraft:enchant"]
    },
    "custom": [
      { "id": "tiermod:example_hook", "payload": { "bonus": "mining" } }
    ]
  }
}

Como o tier é obtido — um exemplo por trigger

O tier só entra no sorteio se triggers incluir o evento e o item bater com assignment.

Craft (ITEM_CRAFTED)

{
  "id": "crafted_fine",
  "display": {
    "name": "Craft Fino",
    "baseColor": "#88CCFF",
    "shadowColor": "#446688"
  },
  "assignment": {
    "allowTags": ["#minecraft:tools"]
  },
  "behavior": {
    "weight": 30,
    "exclusiveGroup": "rarity",
    "triggers": ["ITEM_CRAFTED"]
  }
}

Teste: Crafte qualquer ferramenta na mesa de craft.

Pesca (ITEM_FISHED)

{
  "id": "anglers_prize",
  "display": {
    "name": "Prêmio do Pescador",
    "tooltip": "Uma pesca de sorte.",
    "baseColor": "#00AAAA",
    "shadowColor": "#005555"
  },
  "assignment": {
    "allowMods": ["minecraft"],
    "allowTags": ["#minecraft:fishes"]
  },
  "behavior": {
    "weight": 10,
    "exclusiveGroup": "rarity",
    "triggers": ["ITEM_FISHED"],
    "conditions": { "biome": "#minecraft:is_ocean" }
  }
}

Teste: Pesque em bioma oceânico.

Fornalha (ITEM_SMELTED)

{
  "id": "refined_ingot",
  "display": {
    "name": "Refinado",
    "tooltip": "Purificado pelo calor.",
    "baseColor": "#FFAA00",
    "shadowColor": "#884400"
  },
  "assignment": {
    "allowItems": ["minecraft:iron_ingot", "minecraft:gold_ingot", "minecraft:copper_ingot"]
  },
  "behavior": {
    "weight": 25,
    "triggers": ["ITEM_SMELTED"]
  }
}

Teste: Funda minério cru na fornalha.

Bigorna (ITEM_ANVIL)

{
  "id": "reinforced",
  "display": {
    "name": "Reforçado",
    "tooltip": "Martelado à perfeição.",
    "baseColor": "#CCCCCC",
    "shadowColor": "#666666"
  },
  "assignment": {
    "allowTags": ["#minecraft:tools", "#minecraft:weapon"]
  },
  "behavior": {
    "weight": 15,
    "exclusiveGroup": "rarity",
    "triggers": ["ITEM_ANVIL"]
  }
}

Teste: Combine ou repare uma ferramenta na bigorna.

Mesa de ferraria (ITEM_SMITHING)

{
  "id": "netherforged",
  "display": {
    "name": "Forjado no Nether",
    "baseColor": "#4A0808",
    "shadowColor": "#220404"
  },
  "assignment": {
    "allowItems": ["minecraft:netherite_sword", "minecraft:netherite_pickaxe"]
  },
  "behavior": {
    "weight": 50,
    "triggers": ["ITEM_SMITHING"],
    "conditions": { "dimension": "minecraft:the_nether" }
  }
}

Loot de baú (ITEM_LOOTED)

{
  "id": "dungeon_spoil",
  "display": {
    "name": "Espólio de Dungeon",
    "baseColor": "#AA55FF",
    "shadowColor": "#552288"
  },
  "assignment": {
    "allowTags": ["#minecraft:swords"]
  },
  "behavior": {
    "weight": 20,
    "exclusiveGroup": "rarity",
    "triggers": ["ITEM_LOOTED"]
  }
}

Drop de mob (ENTITY_DROP)

{
  "id": "hunter_mark",
  "display": {
    "name": "Marca do Caçador",
    "baseColor": "#FF5555",
    "shadowColor": "#882222"
  },
  "assignment": {
    "allowItems": ["minecraft:bone", "minecraft:rotten_flesh"]
  },
  "behavior": {
    "weight": 40,
    "triggers": ["ENTITY_DROP"]
  }
}

Quebra de bloco (BLOCK_BREAK)

{
  "id": "vein_lucky",
  "display": {
    "name": "Veio Sortudo",
    "baseColor": "#55FFAA",
    "shadowColor": "#228855"
  },
  "assignment": {
    "allowItems": ["minecraft:coal", "minecraft:raw_iron"]
  },
  "behavior": {
    "weight": 12,
    "triggers": ["BLOCK_BREAK"]
  }
}

Comando / teste (COMMAND)

{
  "id": "debug_tier",
  "display": {
    "name": "Tier Debug",
    "baseColor": "#FFFFFF",
    "shadowColor": "#888888"
  },
  "assignment": {
    "allowTags": ["#minecraft:tools"]
  },
  "behavior": {
    "weight": 100,
    "triggers": ["COMMAND"]
  }
}

Teste: Segure uma ferramenta → /tiermod roll COMMAND

Todos os “tipos” de tier (mecânicas)

1. Grupo de raridade (exclusivo com peso)

Só um tier do grupo por item. weight maior = mais provável.

config/tiermod/groups/rarity.json:

{
  "id": "rarity",
  "exclusive": true,
  "tiers": ["common", "rare", "epic", "legendary"]
}

2. Tier always (garantido)

"behavior": {
  "always": true,
  "weight": 0,
  "triggers": ["ITEM_CRAFTED"]
}

Quando elegível, sempre vence o sorteio no mesmo grupo exclusivo.

3. Herança (inherit)

{
  "id": "legendary_nether",
  "inherit": "legendary",
  "display": {
    "name": "Lendário do Nether",
    "baseColor": "#FF4500",
    "shadowColor": "#662200"
  },
  "effects": {
    "visual": { "glint": true }
  }
}

4. Tier condicional

"conditions": { "dimension": "minecraft:the_nether" }

"conditions": {
  "and": [
    { "biome": "minecraft:swamp" },
    { "isNight": true }
  ]
}

Chaves: biome, dimension, isNight, player_level — combine com and, or, not.

5. Boost de peso (specialConditions)

"specialConditions": [
  {
    "condition": { "dimension": "minecraft:the_nether" },
    "weightMultiplier": 3.0
  }
]

Peso efetivo = pesoBase × (produto dos multiplicadores que bateram).

6. Tier com efeitos

Atributos, encantamentos, brilho visual e payload custom para integrações — ver integrations.md.

Comandos in-game

Todos exigem OP nível 2. Item na mão principal.

Exemplo de modpack: pescaria (v0.6.0 — heldItemTier)

Cenário completo: 4 tiers de vara influenciam as chances dos 7 tiers de peixe; peixe lendário garantido no Deep Dark à noite com a melhor vara.

Copie de examples/fishing/ para config/tiermod/ (veja examples/fishing/README.md), depois /tiermod reload.

Teste rápido:

1. Segure uma vara de pesca → /tiermod set rod_t4
2. Vá ao Deep Dark à noite
3. Pesque — todo peixe deve ser Sculk Legend Catch (fish_tier_7)

Vara melhora o peixe: specialConditions com heldItemTier:

"specialConditions": [
  { "condition": { "heldItemTier": "rod_t4" }, "weightMultiplier": 5.0 }
]

Peixe lendário (sempre vence quando elegível):

"conditions": {
  "and": [
    { "biome": "minecraft:deep_dark" },
    { "isNight": true },
    { "heldItemTier": "rod_t4" }
  ]
}

Testes automatizados: FishingScenarioTest na suíte de testes do projeto.

Solução de problemas

Fail-closed: condição sem contexto (bioma, dimensão, etc.) = false (tier ignorado).

Addons de integração opcionais (v0.5.0)

Jars separados — instale só o que precisar. Detalhes: .cursor/specs/integrations.md

For AI agents: see AGENTS.md for machine-readable schema, decision rules, and validation checklists.