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"] } }

Fields:

• display_name — human-readable name shown in messages and tooltips
• research_time — (optional) research duration in seconds; falls back to global default if omitted or 0
• items — list of item IDs to lock (supports NBT criteria)
• tags — list of item tags to lock
• mods — list of mod IDs to lock all items from
• mod_exceptions — items to exclude from mod-level locking (supports NBT)
• recipes — list of recipe IDs to show as locked in crafting menus
• dimensions — list of dimension IDs to block access to
• entities.attacklock — entities that cannot be attacked while the stage is locked
• entities.spawnlock — entities prevented from spawning entirely (also automatically attacklocked)

Files starting with _ are ignored and can be used as templates.

🛠️ 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

Global Stages (server-wide):

• /history global unlock <stage> — unlocks a stage globally
• /history global unlock * — unlocks all global stages
• /history global lock <stage> — relocks a specific stage
• /history global lock * — resets all global stages
• /history global list — lists all global stages
• /history global info <stage> — shows details for a stage

Individual Stages (per player):

• /history individual unlock <player> <stage> — unlocks a stage for a player (supports @a, @p, etc.)
• /history individual lock <player> <stage> — relocks a stage for a player
• /history individual list <player> — lists a player's stages
• /history individual info <player> <stage> — shows stage details for a player

General:

• /history reload — reloads all configs and syncs to all clients

🔧 For Developers & Script Authors

History Stages fires custom Forge events you can hook into from KubeJS, CraftTweaker, or other mods:

• StageEvent.Unlocked — fired when a stage is unlocked (via command or Research Pedestal)
• StageEvent.Locked — fired when a stage is locked

Both events expose getStageId() and getDisplayName().

⚙️ 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

Yes! As of v4.0.0, History Stages supports both global stages (server-wide, the classic behavior) and individual stages (per player, tracked via UUID). You can mix and match both types in the same pack.

Yes. The mod ships without default recipes on purpose so you have full control over how players obtain them. You can add recipes via KubeJS, CraftTweaker, or a datapack — or simply give scrolls to players as quest rewards using the /give command.

Yes, Lootr is a hard dependency. Loot chest filtering is built entirely around Lootr's container system and can't be made optional without a major rewrite. If you're not using loot locking, Lootr still needs to be present but won't get in the way.

Yes — History Stages fires StageEvent.Unlocked and StageEvent.Locked on the Forge event bus, which both KubeJS and CraftTweaker can listen to. You can use these to trigger custom logic when a stage changes.

• 1.20.1 — Forge (v4.x.x, full feature set including individual stages and NBT locking)
• 1.19.2 — Forge (v2.x.x)

No, FTB Quests is completely optional. The integration only activates when FTB Quests is present and adds custom task and reward types for both global and individual stages — but the mod works perfectly without it.

As of v4.0.0, global stage configs have moved to configs/historystages/global/. If you're upgrading from v3.x.x, move your existing stage JSON files into that subdirectory.

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