Skip to main content

Tags — Tag API

Phase: Startup (startup_scripts/)

Adds, removes, or replaces entries in vanilla and modded data-pack tags. Tag files are written to:

<gameDir>/atomicoffe/data/<namespace>/tags/<path>.json

Because the atomicoffe/ directory is automatically injected as both a client resource pack and a server data pack, these files are picked up on the next data-pack reload (world startup or /reload).

Tag ID Format​

Tag IDs use the format "namespace:path/subpath", which maps to the file data/<namespace>/tags/<path/subpath>.json.

"minecraft:items/swords"           → data/minecraft/tags/items/swords.json
"minecraft:blocks/mineable/pickaxe" → data/minecraft/tags/blocks/mineable/pickaxe.json

Tags.add(tagId, item1 [, item2, ...])​

Appends items to an existing tag without overwriting vanilla entries. Duplicate entries are automatically deduplicated.

-- Add a custom sword to the vanilla swords tag
Tags.add("minecraft:items/swords", "mymod:cool_sword")

-- Add multiple blocks at once
Tags.add("minecraft:blocks/mineable/pickaxe", "mymod:my_ore", "mymod:my_block")

Tags.replace(tagId, item1 [, item2, ...])​

Replaces the entire tag with only the specified items (replace: true). Vanilla entries are removed.

-- Override the planks tag to only include oak planks
Tags.replace("minecraft:items/planks", "minecraft:oak_planks")

Tags.remove(tagId, item1 [, item2, ...])​

Generates a replace: true tag that excludes the listed items from any previously Tags.add-ed entries.

Limitation

Tags.remove can only remove entries that were added via Tags.add in the same session. It cannot remove vanilla entries from the original data pack. Use Tags.replace for full control.

Tags.remove("minecraft:items/planks", "minecraft:oak_planks")

Full Example​

-- startup_scripts/tags.lua

-- Make our custom ore mine-able with a pickaxe
Tags.add("minecraft:blocks/mineable/pickaxe", "mymod:ruby_ore")

-- Make our ingot a valid beacon payment
Tags.add("minecraft:items/beacon_payment_items", "mymod:ruby_ingot")

-- Override the stone tool materials tag entirely
Tags.replace("minecraft:items/stone_tool_materials",
  "minecraft:cobblestone",
  "minecraft:blackstone",
  "mymod:ruby"
)