Legacy Item Purger

Removed mods? Replace or remove their leftover items, blocks and structures in your world
banner_1200x400.png

banner_1200x400.png

Description

Legacy Item Purger

Clean up a world after you removed mods, and keep your gear instead of losing it.

You removed a few mods from your pack, or moved a world to a pack where some mods no longer exist. Now the log is full of errors about unknown items, chests show holes, and the boss weapons you fought for are gone. Legacy Item Purger repairs the saved data while the world loads, and (if you want) turns missing weapons, armor and other listed items into something you can still use.

Beta. This is the first public release. It changes saved world data. Always back up your world first and try it on a copy.

What it does

  • Finds items whose mod is no longer installed, in chests and other containers, nested mod inventories (backpacks, storage mods), player inventories, ender chests and entities, before the game tries to decode them.
  • Either replaces them or removes them, depending on the mode you choose.
  • Replaces missing blocks in saved chunks with air and removes their leftover block entities and block ticks.
  • Removes references to structures that no longer exist.
  • Removes unknown entity attributes and migrates simple old fluid data.
  • Clears invalid minecraft:air item stacks that cause "Item must not be minecraft:air" errors.
  • Reports everything with dimension, position, slot, item ID and reason.
  • Starts in preview mode. Nothing is changed until you set dryRun = false.

It has no hard-coded rules for specific mods: an item is "missing" when its ID is not in the item registry of your current installation.

The two modes

Set mode in config/legacyitempurger-common.toml, or use /legacyitempurger mode <replace|remove>.

mode = "replace" (default) mode = "remove"
Missing weapons and armor Replaced with a fitting item; name and enchantments are kept Removed
Other missing items listed in a table (food, crops, block items, misc) Replaced; count and name are kept Removed
All other missing items Removed Removed
Missing blocks, structures, attributes, fluids Cleaned Cleaned
Best for Worlds where players should keep their progress A plain, predictable cleanup

How replacement works

  1. Your own mappings from the config win.
  2. Then the bundled tables (see "Built-in replacement tables" below).
  3. Then a keyword heuristic for weapons and armor of unknown mods (..._sword, katana, battleaxe, longbow, helm, greaves, ... with tier words such as diamond or netherite).
  4. Anything without a replacement is removed.

Replaced weapons and armor keep their custom name and every enchantment that still exists. Mod-specific data and durability damage are dropped. Each replaced item gets a lore line naming the old item and a hidden marker (minecraft:custom_data with the original item ID), so it stays identifiable later.

Target chains: modded target first, vanilla as fallback

A replacement can name several targets in order. The first one that is installed wins.

{ "from": "oldmod:fire_sword", "to": ["newmod:fire_sword", "minecraft:netherite_sword"], "kind": "weapon" }
weaponReplacements = ["oldmod:fire_sword=newmod:fire_sword|minecraft:netherite_sword"]
itemReplacements = ["oldmod:cheese_wheel=newmod:cheese|minecraft:bread"]

If you want modded replacements, install the replacement mods on your world copy before you run the cleanup. Without them you get the vanilla fallback. If no target of a chain is installed, the heuristic (weapons and armor only) decides, otherwise the item is removed.

Heirlooms

Boss gear from the bundled tables receives legal vanilla enchantments as compensation for the lost special abilities, whether it becomes a modded target item or the netherite-tier vanilla fallback shown here. Existing enchantments always win, incompatible enchantments are never combined, and levels never exceed the vanilla maximum.

Old item (Cataclysm) Vanilla fallback Heirloom enchantments
The Incinerator Netherite Sword Sharpness V, Fire Aspect II, Unbreaking III, Mending
Meat Shredder Netherite Axe Sharpness V, Efficiency V, Unbreaking III, Mending
Infernal Forge Mace Density V, Fire Aspect II, Unbreaking III, Mending
Astrape Trident Impaling V, Loyalty III, Channeling, Unbreaking III, Mending
Cursed Bow Bow Power V, Flame, Unbreaking III, Mending
Ignitium Chestplate Netherite Chestplate Protection IV, Unbreaking III, Mending

The heirloom bonus can be switched off (heirloomBonusEnchantments = false).

Built-in replacement tables

Version 1.0.0 ships tables for 613 items of these removed mods, plus 129 items that are deliberately removed (structure and boss-arena blocks, creative-only items and similar):

Removed mod Entries Recommended target mods Without them
L_Ender's Cataclysm 220 World Bosses, Remnants (needs Jauml), The Graveyard Vanilla gear and materials; boss gear with heirloom enchantments
Bosses of Mass Destruction 19 World Bosses, Remnants Vanilla
Supplementaries / Amendments 211 / 2 Signpost (way signs only) Vanilla blocks and items
Cultural Delights 160 Croptopia Vanilla food and crops
Ragdollified Player Corpses 1 none Recovery Compass

161 entries prefer a modded target. Targets fall back to vanilla when those mods are not installed, so the target mods are optional. The server log shows at startup how many entries resolve to their first choice and how many use a later target of the chain. Stats and abilities of the target items were not balanced against the originals in game; treat the tables as a sensible default and override entries in the config where you disagree. Contents of replaced containers (sacks, quivers, jars, safes) are not carried over.

Typical workflow: migrating a world after removing mods

  1. Stop the server and make a full backup. Work on a copy of the world.
  2. Remove the mods you no longer want. Put Legacy Item Purger into mods. Optional: install the mods that should provide modded replacement targets.
  3. Preview. Start the server with the default dryRun = true. Load the affected areas and read the log lines starting with [LegacyItemPurger]. Planned replacements look like old -> new | REPLACED_WEAPON (dry-run: would replace).
  4. Choose your mode (replace or remove) and add your own mappings if you want.
  5. Apply. Set dryRun = false and restart. Chunks are cleaned when they load; players and their ender chests are cleaned when they log in.
  6. To clean the whole world, load all existing chunks once, for example with a pre-generator such as Chunky that can force-load existing chunks.
  7. Check the result, then move the cleaned world to your real server.

Commands

Permission level 2 (operators or the server console). Switching the mode needs level 3.

Command Effect
/legacyitempurger status Shows mode, automatic, dry-run and the number of queued chunks
/legacyitempurger mode Shows the active mode
/legacyitempurger mode replace / mode remove Switches the mode and saves it to the config
/legacyitempurger scan [radius] Previews loaded block inventories around you (radius 0 to 8 chunks, default 4)
/legacyitempurger apply [radius] Cleans loaded block inventories around you, even while dryRun = true

scan and apply never load additional chunks.

Configuration overview

config/legacyitempurger-common.toml

Key Default Meaning
mode "replace" "replace" or "remove"
dryRun true Preview only. Set false to change data
automatic true Inspect data while it loads
removeMissingItems, removeAirEntries true Item cleanup switches
removeMissingBlocks, removeMissingStructures true Chunk cleanup switches
removeUnknownAttributes, migrateLegacyFluids, cleanDistantHorizons true Other legacy data
blockedItemIds, blockedNamespaces, allowedItemIds empty Force removal or protect specific items
replaceMissingWeapons, replaceMissingArmor, replaceMissingOtherItems true What may be replaced (replace mode only)
weaponReplacements, armorReplacements, itemReplacements empty Your own mappings, "old:item=first:target|second:target" (replace mode only)
weaponFallback, armorFallback true Keyword heuristic (replace mode only)
addReplacementLore, heirloomBonusEnchantments true Lore line and heirloom bonus (replace mode only)
loreLanguage "en" Language of the lore line: "en" or "de" (replace mode only)
blockInventoriesPerTick, slotsPerTick, detailsPerReport 8 / 256 / 20 Performance and log limits

Compatibility

  • Minecraft 1.21.1, NeoForge 21.1.264 or newer 21.1.x, Java 21.
  • Server and client. The same JAR works on a dedicated server, in singleplayer and on clients. A server-only installation is enough to clean a server world: clients do not need the mod to join. Installing it on the client as well additionally cleans data the client decodes locally.
  • Optional Distant Horizons support (built against the NeoForge version of DH 3.3.3): missing block IDs in LOD data are normalized while they are read. Without Distant Horizons this part stays inactive.
  • No dependencies besides NeoForge.

FAQ

Does it delete things on its own after installing? No. The default is dryRun = true, which only reports. You have to switch it off yourself.

Can I get removed or replaced items back? Only from your backup. That is why the preview exists.

I switched from replace to remove. Do replaced items disappear? No. A replaced item is a normal item. The mode only decides what happens to items that are still missing.

My mod is not in the bundled table. Weapons and armor are usually caught by the keyword heuristic. For everything else add your own mappings to the config.

Does it scan the whole world? It cleans data when it is loaded. Chunks nobody loads stay untouched until they load. Use a tool that loads all existing chunks to clean everything in one go.

Does it hide errors from the log? No. It repairs the data that causes them. Messages from other mods that are not caused by missing items, blocks or structures stay as they are.

Is the item removed if something goes wrong? No. If inspecting an inventory fails, the original data is kept and the problem is logged.

Warnings

  • Make a backup before you set dryRun = false. Removal and replacement cannot be undone.
  • This is a beta. It was tested with automated regression tests and on test servers, not on every modpack.
  • Replacements are approximations. Special abilities of modded items are lost.
  • The lore line ("Heirloom: The Incinerator (Cataclysm)" / "Replaced: Avocado (Cultural Delights)") is written into the item when it is replaced. Choose loreLanguage (en or de) or switch it off with addReplacementLore = false before you apply.
  • Items of mods that are still installed are never touched, unless you list them in blockedItemIds or blockedNamespaces.

License and credits

MIT License, Copyright (c) 2026 Raffman180. The license text is included in the JAR.

This mod was made with AI assistance (vibecoded) by Raffman180.

Legacy Item Purger Team

profile avatar
  • 10
    Projects
  • 3.4K
    Downloads

My wish was always to make my ideas come reality, I always had many ideas for mods but no know how, so I started "vibecoding" and I know people care about it a lot if its Ai made or not, thats why this is my Bio│I'm an honest guy!

More from Raffman180View all

  • Pretty Announcer project image

    Pretty Announcer

    Pretty announcements at the top of the screen: automatic server restart countdowns, repeating announcements, pictures, an in-game design menu and /announce. Players without the mod still see a boss bar.

    • 87
    • November 16, 2026
  • Raffman’s Excavator project image

    Raffman’s Excavator

    Mine one block, get the whole shape: ore veins, 3x3 tunnels, staircases and flat areas with a live preview. Drops go straight into your inventory.

    • 61
    • November 16, 2026
  • Raffman's Detailed Map project image

    Raffman's Detailed Map

    A detailed diorama-style map and minimap with team-shared fog of war, waypoints, teams, diplomacy and chunk claims.

    • 2.2K
    • November 15, 2026
  • Jurgens Shader project image

    Jurgens Shader

    Colourful, realistic Iris shader: physical sky, volumetric clouds with soft light, a clean night sky, calm water, soft shadows and coloured light - fast on HIGH at 1440p.

    • 83
    • November 15, 2026
  • Pretty Announcer project image

    Pretty Announcer

    Pretty announcements at the top of the screen: automatic server restart countdowns, repeating announcements, pictures, an in-game design menu and /announce. Players without the mod still see a boss bar.

    • 87
    • November 16, 2026
  • Raffman’s Excavator project image

    Raffman’s Excavator

    Mine one block, get the whole shape: ore veins, 3x3 tunnels, staircases and flat areas with a live preview. Drops go straight into your inventory.

    • 61
    • November 16, 2026
  • Raffman's Detailed Map project image

    Raffman's Detailed Map

    A detailed diorama-style map and minimap with team-shared fog of war, waypoints, teams, diplomacy and chunk claims.

    • 2.2K
    • November 15, 2026
  • Jurgens Shader project image

    Jurgens Shader

    Colourful, realistic Iris shader: physical sky, volumetric clouds with soft light, a clean night sky, calm water, soft shadows and coloured light - fast on HIGH at 1440p.

    • 83
    • November 15, 2026