Tags

Groups of blocks or items you can name: which tool mines what, how good it has to be, and the "is this any kind of copper ore" question that mods have been solving separately since forever.

A tag is a named set. RetroAPI ships the two families modern Minecraft uses for mining, lets you declare your own for anything else, and reads both from code and from data files, unioning whatever it finds.

The two built-in families

Tag	Means
`mineable/pickaxe`, `mineable/axe`, `mineable/shovel`, `mineable/hoe`, `mineable/sword`, `mineable/shears`	this kind of tool mines the block at tool speed
`needs_stone_tool`, `needs_iron_tool`, `needs_diamond_tool`	the tool must be at least this tier for the block to drop anything

They are deliberately independent, exactly as in modern Minecraft. A mineable tag grants speed. Whether a block needs a tool at all comes from its material (beta's own stone/metal rule) or from a needs_*_tool tag. So a hand-breakable block in mineable/axe still drops by hand and merely mines faster with an axe, while a stone-material block in mineable/pickaxe drops only for a pickaxe.

initRetro()

RUBY_ORE = RetroBlockAccess.create(Material.STONE)
    .strength(3.0F)
    .mineable(RetroTool.PICKAXE)          // speed: pickaxes
    .needsTool(RetroToolTier.IRON)        // drops: iron or better
    .tag(RetroTagKey.block("ore_dictionary/ruby"))
    .texture(id("ruby_ore"))
    .register(id("ruby_ore"));

Everything in one chain, next to the rest of the block's definition.

data/example_mod/tags/block/mineable/pickaxe.json

{
  "replace": false,
  "values": [
    "example_mod:ruby_ore",
    "minecraft:glass"
  ]
}

data/example_mod/tags/block/needs_iron_tool.json

{ "values": [ "example_mod:ruby_ore" ] }

Vanilla blocks can be named too (minecraft:glass), which is how you make a vanilla block respect your tool rules.

The two are a union, not a conflict: a block listed in code and in a file is simply in the tag once. That is what lets a pack author add blocks to your tag without touching your jar.

Blocks you never tagged

Leaving a block untagged is fine, and it is what most blocks do. RetroAPI infers the obvious default from the block's material:

Material	Inferred
`STONE`, `METAL`, `ICE`, `PISTON`	`mineable/pickaxe`
`WOOD`, `PUMPKIN`	`mineable/axe`
`SOIL`, `SAND`, `CLAY`, `SOLID_ORGANIC`, snow	`mineable/shovel`
`LEAVES`	`mineable/shears`, `sword`, `hoe`
`WOOL`, `COBWEB`	`mineable/shears`

This inference is not a nicety, it is what stops a whole class of "my block is unbreakable" reports. Beta decides whether a tool is effective from hardcoded block lists inside each vanilla tool item, and no modded block is in those lists. Without a tag or an inferred default, a stone-material modded block drops nothing for any tool, vanilla or modded. An explicit .mineable(...) or a data file always wins over the inference.

Vanilla blocks come pre-tagged with beta-accurate membership (stone and ores are pickaxe blocks, iron ore needs stone tier, gold/diamond need iron, and so on), generated from beta's own tool tables. That is what makes a custom tool work on vanilla blocks and not only on your own.

Your own tags

A tag key is just a name. Use them for anything you would otherwise express as a long if:

arbitrary tags, blocks and items

static final RetroTagKey ORE_RUBY  = RetroTagKey.block("ore_dictionary/ruby");
static final RetroTagKey GEMS      = RetroTagKey.item("ore_dictionary/gems");

RetroTags.addToTag(ORE_RUBY, RUBY_ORE, DEEP_RUBY_ORE);
RetroTags.addToTag(GEMS, RUBY, SAPPHIRE);

if (RetroTags.isIn(stack.getItem(), GEMS)) { … }
for (Block b : RetroTags.blocksIn(ORE_RUBY)) { … }
RetroTags.removeFromTag(GEMS, SAPPHIRE);

RetroAPI's code tags stay live and mutable: adding to one after the game has started takes effect immediately, which is how two mods can agree on an "ore dictionary" at runtime without either one owning it.

Where tags are read

Data files are picked up from all of these layouts, so a mod written for another library's conventions usually needs no changes:

data/<namespace>/tags/block/… and tags/blocks/…
data/<namespace>/tags/item/… and tags/items/…
StationAPI's data/<namespace>/stationapi/tags/… layout

Entries may be namespace:path or a bare vanilla name (minecraft:stone); vanilla names resolve through RetroAPI's flattening tables, so you can write the modern name for a beta block and it lands on the right one.

Tools read these tags from the other side: see Tools, food & armor for tool kinds, tiers, and how a tool with no ToolMaterial declares what it is good at.