History Stages

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

Stages can unlock server-wide (global) for the whole group, per player (individual), or even use a dual-phase approach — 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 it all:

• 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 or story-driven packs.
• Dual-Phase stages automatically trigger when an item is in both a global and individual stage. The item is locked globally until the server reaches the era, and then remains locked per-player until they personally catch up.

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. With the Dependency System, you can require players to reach specific XP levels, kill certain mobs, achieve statistics, or deposit items directly into the pedestal before a stage can be researched.

On top of that, almost everything can be locked — not just items, but recipes across every mod, dimensions, structures, 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 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
• Structures — prevent players from entering specific structures (e.g. Strongholds or Villages via tags), optionally dealing damage and blocking container interactions inside
• 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.

If a stage has Dependencies, the Pedestal GUI dynamically expands to show a checklist of all required conditions. Players can deposit required items and XP directly into the pedestal to fulfill these requirements incrementally.

This mod intentionally ships without default recipes for the Pedestal and Scrolls, so you as a modpack creator can decide how players obtain them. To give a specific scroll via command:

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

For full details on scroll types and the Research Pedestal, see the Research System wiki page.

📂 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/ and individual stages in configs/historystages/individual/.

For a full field reference and examples, see the Stage Configuration and Stage Examples wiki pages.

{
  "display_name": "Bronze Age",
  "research_time": 60,
  "icon": "minecraft:iron_ingot",
  "items": ["minecraft:iron_ingot"],
  "tags": ["forge:ores/iron"],
  "mods": ["mekanism"],
  "mod_exceptions": ["mekanism:osmium_ingot"],
  "recipes": ["minecraft:iron_pickaxe"],
  "dimensions": ["minecraft:the_nether"],
  "structures": ["minecraft:stronghold", "#minecraft:village"],
  "entities": {
    "attacklock": ["minecraft:zombie"],
    "spawnlock": ["minecraft:skeleton"]
  },
  "dependencies": [
    {"type": "xp_level", "level": 10},
    {"type": "entity_kills", "entity": "minecraft:zombie", "count": 20}
  ]
}

🛠️ 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, structures, tags, and mods. Includes a Dependency Editor, an NBT editor, and a dedicated Exceptions tab. The editor also warns about overlaps between global and individual stages, marking dual-phase entries with a [Dual] badge. Accessible via a button in the pause menu (OP required).

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.

For a full overview, see the In-Game Editor wiki page.

Debug Commands

New debug commands help you find the exact IDs and NBT data you need for your configs:

• /history debug structure — lists structure IDs and tags at your current position
• /history debug nbt preset|custom — lists NBT data for your held item

For a complete command reference, see the Commands & Permissions wiki page.

🎨 UI & Feedback

• Lock Icon Overlay — locked items show a padlock in inventories and JEI (auto-disabled with EMI). Dual-phase items get a dedicated lock icon during Phase 1.
• 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, with support for custom per-stage icons
• 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

All commands use the /history prefix and require Permission Level 2 (OP). They cover unlocking and locking stages globally or per player, reloading configs, and debug utilities for structure IDs and item NBT data.

For a full command reference, see the Commands & Permissions wiki page.

🔧 For Developers & Script Authors

History Stages fires StageEvent.Unlocked and StageEvent.Locked on the Forge event bus, which KubeJS, CraftTweaker, and other mods can listen to. For details and examples, see the Integrations & API wiki page.

⚙️ Configuration

Everything is configurable via historystages-common.toml and historystages-client.toml, or through the in-game config editor. For a full list of all settings, see the Configuration wiki page.

📦 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! 🙂