Remap File Reference

Everything RemapIDs does is driven by JSON files in config/remapids/remaps/. This page documents the full format.

File layout

• Directoryconfig

  • Directoryremapids

    • Directoryremaps/ drop remap JSON files here

      • create_compat.json
      • iceandfire_removal.json
      • …
    • numerical_ids.json optional, custom pre-1.13 ID mappings

You can keep everything in one file or split remaps across many. Files are loaded alphabetically and merged, so organizing by mod or by purpose works well and the file names double as documentation.

File shape

Every file contains a single remaps array:

{
  "remaps": [
    {
      "source": "iceandfire:silver_ingot",
      "target": "othermod:silver_ingot",
      "types": ["item", "recipe", "loot_table", "tag"]
    }
  ]
}

Entry fields

Field	Required	Description
source	Yes	The ID to remap from, e.g. iceandfire:silver_ingot. Also accepts wildcards, #-prefixed tags, and pre-1.13 numerical IDs.
target	Yes	The ID to remap to, e.g. othermod:silver_ingot. Must exist in the relevant registry.
types	No	Which systems the remap applies to. When omitted, the entry applies to every type where the target actually exists.

Omitting types

A typeless entry is the convenient default: RemapIDs checks which registries contain the target and applies the remap there, plus recipes, loot tables, and tags. It skips registries where the target does not exist, so an item-only target will not generate pointless block or fluid remaps. If the target exists in no registry at all you get a single warning in the log.

Remap types

There are seven types in two groups. The difference matters for when changes take effect.

Registry types

Applied while registries are being set up at startup. Changing these requires a full game restart.

Type	What it affects
block	The block registry: placed blocks in the world
item	The item registry: items in inventories, chests, and entities
fluid	The fluid registry
entity_type	The entity type registry: spawned and saved entities

Reloadable types

Applied when datapacks load. These can be refreshed in a running game with /reload.

Type	What it affects
recipe	Rewrites recipe JSON: ingredient and result item IDs
loot_table	Rewrites loot table JSON: item and block references
tag	Rewrites tag entries: redirects tag membership

Tip

When remapping an item that also exists as a block (an ore, a storage block), include both item and block in types, or just omit types and let RemapIDs figure it out.

Wildcards

Remap a whole family of IDs in one entry. Both source and target must contain a *:

{
  "remaps": [
    {
      "source": "iceandfire:silver_*",
      "target": "othermod:silver_*",
      "types": ["item", "block", "recipe", "loot_table", "tag"]
    }
  ]
}

The * captures whatever it matched in the source and substitutes it into the target. Here iceandfire:silver_ore becomes othermod:silver_ore, iceandfire:silver_block becomes othermod:silver_block, and so on. A pattern only produces a remap when the substituted target actually exists, so mismatched families fail safe: nothing is remapped to a missing ID.

Tags

Prefix a tag ID with # to remap tag references:

{
  "remaps": [
    {
      "source": "#forge:ores/silver",
      "target": "#forge:ores/tin",
      "types": ["tag"]
    }
  ]
}

With type tag, anything that referenced #forge:ores/silver now resolves #forge:ores/tin instead.

A #-prefixed source can also target a plain item under the recipe type. RemapIDs then rewrites tag ingredients in recipes into item ingredients. See tag to item conversion in the examples.

Numerical IDs

Pre-1.13 numerical IDs work as sources, in id or id:metadata form:

{
  "remaps": [
    {
      "source": "35:14",
      "target": "minecraft:red_wool",
      "types": ["block"]
    }
  ]
}

35:14 is red wool in pre-flattening Minecraft. RemapIDs resolves the number through a built-in flattening table and remaps from the resolved string ID. A bare number like 35 is tried as-is, then as 35:0. Custom mappings for modded numerical IDs go in config/remapids/numerical_ids.json; the format is covered in Advanced.

Multiple files and load order

All files in config/remapids/remaps/ are loaded in alphabetical order and merged into a single remap set. If two files remap the same source for the same type, the later (alphabetically) file wins, so keep each source in one place.

Entries that chain across files are flattened automatically: if one file maps A to B and another maps B to C, then A resolves straight to C. Details in chain resolution.