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.

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

Hold a wooden sword
/tiermod set starter — force-assign the tier
/tiermod get — confirm tier on item
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:

Hold a fishing rod → /tiermod set rod_t4
Go to Deep Dark at night
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):

Segure uma espada de madeira
/tiermod set starter — força o tier no item
/tiermod get — confirma o tier
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:

Segure uma vara de pesca → /tiermod set rod_t4
Vá ao Deep Dark à noite
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.

Tier Engine (tiermod) — Developer Guide

English

What is this?

Where tier JSON lives

Hello world — your first tier

Full annotated example (every field)

How tiers are obtained — one example per trigger

Craft (ITEM_CRAFTED)

Fishing (ITEM_FISHED)

Furnace / smelting (ITEM_SMELTED)

Anvil (ITEM_ANVIL)

Smithing table (ITEM_SMITHING)

Loot chests (ITEM_LOOTED)

Mob drops (ENTITY_DROP)

Block break (BLOCK_BREAK)

Command / testing (COMMAND)

All tier “types” (mechanics)

1. Rarity group (weighted exclusive)

2. Always tier (guaranteed)

3. Inheritance (inherit)

4. Conditional tier (gate)

5. Weight boost (specialConditions)

6. Tier with effects

In-game commands

Fishing modpack example (v0.6.0 — heldItemTier)

Troubleshooting

Optional integration addons (v0.5.0)

Português

O que é?

Onde ficam os arquivos de config

Hello world — seu primeiro tier

Exemplo completo anotado (todos os campos)

Como o tier é obtido — um exemplo por trigger

Craft (ITEM_CRAFTED)

Pesca (ITEM_FISHED)

Fornalha (ITEM_SMELTED)

Bigorna (ITEM_ANVIL)

Mesa de ferraria (ITEM_SMITHING)

Loot de baú (ITEM_LOOTED)

Drop de mob (ENTITY_DROP)

Quebra de bloco (BLOCK_BREAK)

Comando / teste (COMMAND)

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

1. Grupo de raridade (exclusivo com peso)

2. Tier always (garantido)

3. Herança (inherit)

4. Tier condicional

5. Boost de peso (specialConditions)

6. Tier com efeitos

Comandos in-game

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

Solução de problemas

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

Craft (`ITEM_CRAFTED`)

Fishing (`ITEM_FISHED`)

Furnace / smelting (`ITEM_SMELTED`)

Anvil (`ITEM_ANVIL`)

Smithing table (`ITEM_SMITHING`)

Loot chests (`ITEM_LOOTED`)

Mob drops (`ENTITY_DROP`)

Block break (`BLOCK_BREAK`)

Command / testing (`COMMAND`)

3. Inheritance (`inherit`)

5. Weight boost (`specialConditions`)

Fishing modpack example (v0.6.0 — `heldItemTier`)

Craft (`ITEM_CRAFTED`)

Pesca (`ITEM_FISHED`)

Fornalha (`ITEM_SMELTED`)

Bigorna (`ITEM_ANVIL`)

Mesa de ferraria (`ITEM_SMITHING`)

Loot de baú (`ITEM_LOOTED`)

Drop de mob (`ENTITY_DROP`)

Quebra de bloco (`BLOCK_BREAK`)

Comando / teste (`COMMAND`)

2. Tier `always` (garantido)

3. Herança (`inherit`)

5. Boost de peso (`specialConditions`)

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

Tiermod - Core