History Stages

History Stages is a global progression and gatekeeping mod built for modpack creators. Lock items, recipes, dimensions, mobs, and loot behind custom research-based eras — and let players work together to unlock them through the Research Pedestal.

Stages can unlock server-wide (global) for the whole group, or per player (individual) — giving you full control over how progression works in your pack.

✨ What makes History Stages different

Most progression mods track progress per player. History Stages lets you do both — global stages unlock for the entire server at once, perfect for collaborative packs where no one sneaks ahead. Individual stages track progress per player via UUID-based persistence, opening the door for personal quest lines, story-driven packs, or hybrid approaches.

Advancing isn't just a command either. Players physically bring Research Scrolls to the Research Pedestal and spend time researching to unlock the next era — a tangible, in-world ritual that fits any modpack theme and gives progression real weight.

On top of that, almost everything can be locked — not just items, but recipes across every mod, dimensions, mob spawning, loot tables, armor stand displays, block GUIs, enchantments, and more. And with the built-in in-game editor, you can build and tweak your entire stage setup without ever touching a config file.

If you're using FTB Quests, the integration goes even deeper — History Stages adds native stage task types and stage reward types for both global and individual stages directly into the FTB Quests editor.

🔒 What you can lock

• Items, Tags & entire Mods — lock individual items, item tags, or everything from a specific mod at once
• NBT-specific Items — lock items by exact NBT criteria (e.g. a specific enchantment or potion effect)
• Mod Exceptions — exclude specific items (with full NBT support) from mod-level locking
• Recipes — locked recipes now show a "Locked" overlay in JEI/EMI instead of being hidden, so players can see what's coming
• Dimensions — block access to the Nether, End, or any other dimension until players are ready
• Mobs — two modes: Attacklock (players can't hurt the mob) and Spawnlock (prevents spawning entirely, including spawners and commands). Spawnlocked mobs are also automatically attacklocked.
• Loot & Drops — locked items are removed or replaced in loot chests and mob drops
• Blocks — locked blocks resist breaking with a configurable slow-break multiplier
• Block GUIs — prevent players from opening chests, furnaces, and other block containers while locked
• Enchantments — prevent applying locked enchantments via the anvil and enchanting table
• Armor Stands & Item Frames — locked items displayed on armor stands or item frames can't be taken or destroyed

🔬 The Research System

Players unlock stages by using Research Scrolls at the Research Pedestal. Each stage can have its own research time — or fall back to a global default in your config.

This mod intentionally ships without default recipes for the Pedestal and Scrolls, so you as a modpack creator can decide how players obtain them — whether that's through KubeJS, CraftTweaker, a datapack, or quest rewards. To give a specific scroll via command:

/give @s historystages:research_scroll{StageResearch:"YOUR_STAGE_NAME"}

📂 Creating Stages

The easiest way is the in-game stage editor (see below). If you prefer working with files, global stage configs are stored in configs/historystages/global/ after running the game once:

{
  "display_name": "Bronze Age",
  "research_time": 60,
  "items": ["minecraft:iron_ingot"],
  "tags": ["forge:ores/iron"],
  "mods": ["mekanism"],
  "mod_exceptions": ["mekanism:osmium_ingot"],
  "recipes": ["minecraft:iron_pickaxe"],
  "dimensions": ["minecraft:the_nether"],
  "entities": {
    "attacklock": ["minecraft:zombie"],
    "spawnlock": ["minecraft:skeleton"]
  }
}

🛠️ Tools for Pack Creators

In-Game Stage Editor (v3.x.x+)

Create, edit, duplicate, and delete stages directly in-game — no file editing required. Features searchable lists for items, recipes, entities, dimensions, tags, and mods. Accessible via a button in the pause menu (OP required).

New in v4.x.x: Searchable filter bar to find stages by name or ID, NBT editor for item locking by specific NBT criteria, and a dedicated Exceptions tab for mod-level item exclusions.

In-Game Config Editor (v3.x.x+)

Tweak all mod settings without leaving the game, organized by category with a reset-to-defaults option. Accessible through the stage editor.

New in v4.x.x: Scrollable tab bar and per-stage granular toggles for block breaking, item usage, and notification settings.

Debug Logging

Two-tier logging system: load-time diagnostic reports (debug-*.log) with config validation and registry checks (now listing both global and individual stages), plus runtime event logs (runtime-*.log) tracking stage changes and blocked actions.

🎨 UI & Feedback

• Lock Icon Overlay — locked items show a padlock in inventories and JEI (auto-disabled with EMI)
• Recipe "Locked" Overlay — locked recipes show a "Locked" label in JEI/EMI instead of being hidden entirely
• Toast Notifications — an advancement-style popup notifies players when a stage unlocks (configurable per stage)
• JEI / EMI Integration — locked items are hidden or marked; locked recipes show a locked overlay
• Jade Integration — shows stage info as a tooltip on armor stands, item frames, blocks, and entity items
• Actionbar & Chat Messages — configurable per-stage feedback when players try to access locked content

⌨️ Admin Commands

🔧 For Developers & Script Authors

⚙️ Configuration

Everything is configurable via historystages-common.toml and historystages-client.toml, or through the in-game config editor (v4.x.x). You can control:

• Toast popups, achievement sounds, and actionbar messages (globally and per stage)
• Unlock message format with color codes and player/stage placeholders
• Loot replacement behavior (replacement list, tag-based, or deletion)
• Lock icon overlays and tooltip display options
• Dimension and mob lock feedback
• Block GUI and enchantment locking
• Default research time as a global fallback
• Debug logging

📦 Dependencies

• Lootr — required
• JEI — optional
• EMI — optional
• FTB Quests — optional (adds custom stage task & reward types for global and individual stages)
• Jade — optional (shows stage info on armor stands, item frames, blocks, and entity items)

❓ FAQ

Found a bug or have a question? Feel free to open an issue on GitHub — we read everything! 🙂