Contraband

Contraband

Server-side item banning for NeoForge modpacks. No KubeJS. No scripts. Just hold the item and run a command.

---

What is Contraband?

Modpack balance is hard. Every update, every new mod, every gameplay decision can introduce items that break progression, trivialise challenges, or just don't belong. The usual answer is KubeJS — a powerful tool, but one that requires scripting knowledge, careful reload management, and a non-trivial setup just to remove a single item.

Contraband does one thing and does it well: it lets server operators ban items from existence with a single command, no scripts required.

---

Features

Item Removal — Four Layers Deep

Banned items are removed through multiple enforcement layers to ensure nothing slips through:

• Ground entities — Banned items that would spawn on the ground (mob drops, thrown items, etc.) are cancelled before they ever exist.
• Inventory sweep — Every player's inventory is scanned once per second. Banned items obtained through /give, creative mode, trades, container interactions, or any other means are removed automatically.
• Login scan — A full inventory sweep runs the moment a player connects, so nothing carries over from another server or session.
• Crafting — The crafting output for banned items is voided. Players cannot craft their way around the ban.
• Loot tables — Banned items are stripped from all loot tables globally: mob drops, chest loot, fishing rewards, and anything else driven by the loot table system.

Nested Container Support

The inventory sweep doesn't stop at the top level. Banned items are hunted down inside:

• Modded backpacks — Any backpack or container mod that exposes NeoForge's IItemHandler capability is covered. This includes Sophisticated Backpacks, Iron Backpacks, Traveler's Backpack, and most others.
• Shulker boxes — Shulker boxes carried in a player's inventory are scanned and cleaned in-place.
• Bundles — If a bundle contains a banned item, the bundle is cleared.
• Ender chest — The vanilla ender chest inventory is scanned as part of every sweep and login check.
• Nested containers — Containers inside containers are recursively scanned up to four levels deep.

JEI / REI / EMI Integration

Banned items are automatically hidden from recipe viewer mods. Contraband maintains a datapack (datapacks/contraband_jei_hide.zip) that sets the c:hidden_from_recipe_viewers item tag for all currently banned items. This tag is respected by JEI, REI, and EMI out of the box.

The datapack is regenerated silently every time an item is banned, unbanned, or the list is reloaded. Run /reload once after any changes to push the update into JEI/REI/EMI.

In-Game Management — No Config Editing Required

Operators can manage the ban list entirely in-game without ever touching a file:

Command	Description	Permission
/contraband banhand	Ban the item you are currently holding	OP
/contraband ban hand	Same as above	OP
/contraband ban <id>	Ban by item ID — full tab-complete from all registered items	OP
/contraband unbanhand	Unban the item you are currently holding	OP
/contraband unban hand	Same as above	OP
/contraband unban <id>	Unban by item ID — tab-complete shows only currently banned items	OP
/contraband list [page]	Paginated list of all banned items	Any player
/contraband check <id>	Check whether a specific item is currently banned	Any player
/contraband reload	Reload the ban list from disk without restarting	OP
/contraband export	Manually regenerate the JEI hide datapack	OP

Most commands require operator permission level 2 (configurable). list and check are intentionally open to all players — useful for modpack documentation and player transparency.

---

Configuration

Contraband uses a standard NeoForge server config (serverconfig/contraband-server.toml), generated automatically on first launch.

[features]
# Delete banned items when a player picks them up from the ground.
deleteOnPickup = true

# Scan and clean player inventories on login.
deleteOnLogin = true

# Void the crafting result for banned items.
removeRecipes = true

# Strip banned items from all loot tables.
modifyLoot = true

[permissions]
# Require operator permission level 2 to use /contraband commands.
requireOp = true

# Send a chat message to players when a banned item is removed from their inventory.
notifyPlayer = true

The ban list itself lives in config/contraband_banlist.json — a plain sorted JSON array of item IDs, easy to diff, version control, and copy between packs.

---

Server-Side Only

Contraband is a server-side mod. It does not need to be installed on the client. Players connecting with a vanilla client or a different mod list will be subject to all enforcement rules the moment they join.

---

Compatibility

• NeoForge 1.21.1
• Works alongside KubeJS — use whichever tool is appropriate for each job
• Compatible with any mod that follows NeoForge's IItemHandler capability contract for container items
• Loot table enforcement is applied globally via NeoForge's Global Loot Modifier system and respects the modifyLoot toggle
• Optional Curios API integration via reflection — Curios is not a required dependency

---

Why Not KubeJS?

KubeJS is excellent for complex scripting. Contraband is for the operator who wants to quickly remove a problematic item — right now, in-game, without writing a script, without a reload cycle, and without reading documentation. It's the right tool when the job is simply: this item should not exist on this server.

---

Contraband is open source. Issues and contributions welcome.