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:

Section	Field	Meaning
Root	id	Unique tier id (required)
	inherit	Copy display/assignment/behavior/effects from parent tier, then merge overrides
display	name, tooltip	Shown in tooltip
	baseColor, shadowColor	Hex colors for tooltip text
assignment	allowItems	Exact item ids (minecraft:diamond_sword)
	allowMods	All items from a mod namespace (aquaculture)
	allowTags	Item tags (#minecraft:pickaxes)
behavior	always	If true, always wins over weighted roll in its group
	weight	Roll weight (higher = more common)
	exclusiveGroup	Only one tier from this group per item
	triggers	When this tier can be rolled (see table below)
	conditions	Must be true at roll time or tier is skipped
	specialConditions	Extra weight multipliers when sub-conditions match
effects	attributeModifiers	Stat bonuses on the item
	enchantments	Applied enchantments
	visual.glint	Enchantment glint on item
	custom	Payload for script/addon hooks

{
  "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.

Trigger	When it fires	Example use
ITEM_CRAFTED	Crafting table	Crafted gear
ITEM_FISHED	Fishing rod catch	Fishing loot
ITEM_SMELTED	Furnace / blast furnace output	Smelted ingots
ITEM_ANVIL	Anvil combine/repair output	Repaired/enchanted tools
ITEM_SMITHING	Smithing table output	Netherite upgrade
ITEM_LOOTED	Chest / structure loot tables	Dungeon loot
ENTITY_DROP	Mob death drops	Mob farming
BLOCK_BREAK	Block break loot (with tool)	Ore drops
COMMAND	/tiermod roll <trigger>	Testing / admin

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.

Command	Description
/tiermod get	Show tier on held item
/tiermod set <tierId>	Force-set tier (legendary or tiermod:legendary)
/tiermod roll <trigger>	Roll tier using trigger (e.g. ITEM_CRAFTED)
/tiermod reload	Reload datapacks + config, rebuild registry, sync clients
/tiermod list	List all loaded tiers
/tiermod triggers	Show which triggers have tiers
/tiermod info <tierId>	Detailed tier debug view
/tiermod groups	List tier groups

---

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

Problem	Fix
Tier not rolling	Check triggers, assignment (item/tag/mod), and conditions
Fish tier ignores rod	Player must hold the rod in main hand while fishing; set rod tier with /tiermod set rod_tN
Tier never appears in Nether	Condition may require Overworld — check conditions.dimension
Changes not applied	Run /tiermod reload after editing JSON
No config folder	Start game once; defaults copy if createDefaultsOnFirstRun=true
Need debug details	Set debugLogging=true in Forge config for tiermod

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:

Addon	Mod id	Purpose
KubeJS	tiermod_kubejs	Script events & API bindings
CraftTweaker	tiermod_crafttweaker	ZenScript helpers
LootJS	tiermod_lootjs	Loot script tier helper
Apotheosis	tiermod_apotheosis	Affix conditions
FTB Quests	tiermod_ftbquests	tiermod:tier_item quest task

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:

Seção	Campo	Significado
Raiz	id	Id único do tier (obrigatório)
	inherit	Herda display/assignment/behavior/effects do pai e mescla overrides
display	name, tooltip	Texto no tooltip
	baseColor, shadowColor	Cores hex do tooltip
assignment	allowItems	Ids exatos de item
	allowMods	Todos os itens de um mod (aquaculture)
	allowTags	Tags de item (#minecraft:pickaxes)
behavior	always	Se true, sempre vence o sorteio no grupo
	weight	Peso no sorteio (maior = mais comum)
	exclusiveGroup	Só um tier deste grupo por item
	triggers	Quando o tier pode ser sorteado
	conditions	Deve ser verdadeiro no momento do roll
	specialConditions	Multiplicadores extras de peso
effects	attributeModifiers	Bônus de atributo no item
	enchantments	Encantamentos aplicados
	visual.glint	Brilho de encantamento
	custom	Payload para scripts/addons

{
  "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.

Trigger	Quando dispara	Exemplo
ITEM_CRAFTED	Mesa de craft	Ferramentas craftadas
ITEM_FISHED	Pesca	Peixes / loot de pesca
ITEM_SMELTED	Saída da fornalha	Lingotes fundidos
ITEM_ANVIL	Saída da bigorna	Reparo/combine
ITEM_SMITHING	Mesa de ferraria	Upgrade netherite
ITEM_LOOTED	Loot de baús	Dungeons
ENTITY_DROP	Drop de mobs	Farm de mobs
BLOCK_BREAK	Quebra de bloco	Minérios
COMMAND	/tiermod roll	Testes / admin

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.

Comando	Descrição
/tiermod get	Mostra tier do item
/tiermod set <tierId>	Define tier (legendary ou tiermod:legendary)
/tiermod roll <trigger>	Sorteia tier (ex.: ITEM_CRAFTED)
/tiermod reload	Recarrega datapacks + config, reconstrói registry, sincroniza clientes
/tiermod list	Lista tiers carregados
/tiermod triggers	Cobertura de triggers
/tiermod info <tierId>	Detalhes de um tier
/tiermod groups	Lista grupos

---

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

Problema	Solução
Tier não sorteia	Verifique triggers, assignment e conditions
Peixe ignora tier da vara	Vara na mão principal ao pescar; use /tiermod set rod_tN na vara
Tier nunca no Nether	conditions.dimension pode exigir Overworld
Mudanças não aplicam	/tiermod reload após editar JSON
Pasta config não existe	Inicie o jogo; defaults copiam se createDefaultsOnFirstRun=true
Precisa de debug	debugLogging=true na config Forge do tiermod

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

Addon	Mod id	Função
KubeJS	tiermod_kubejs	Eventos e bindings
CraftTweaker	tiermod_crafttweaker	Helpers ZenScript
LootJS	tiermod_lootjs	Helper em loot scripts
Apotheosis	tiermod_apotheosis	Condições de affix
FTB Quests	tiermod_ftbquests	Task tiermod:tier_item

---

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