History Stages

• 📖 Wiki — full documentation, config fields, JSON examples & developer API
• 💬 Discord — support, questions & sneak peeks
• 🐛 Issue Tracker — bug reports & feature requests

History Stages is a progression and gatekeeping mod for modpack creators. Lock items, recipes, dimensions, structures, biomes, mobs, enchantments, and loot behind custom eras — and let players unlock them however you want: research, in-game triggers, quests, or commands.

Stages can unlock server-wide (global), per player (individual), or as Dual-Phase — locked globally first, then per-player once the era is reached. You decide how progression works in your pack.

🔒 What You Can Lock

Almost everything — not just item usage:

• Items & Tags (incl. NBT criteria), entire Mods, Specific Recipes
• Dimensions, Structures & Biomes — with force-field zones, damage, potion effects & a red screen overlay
• World Generation — keep locked structures out of the world entirely, or cap how many may generate (while locked, or after the stage is unlocked)
• Mobs — spawnlock, attacklock & interaction lock: breeding, mounting, trading, leashing, shearing, milking, naming and equipping, each toggleable per entry and filterable by held item
• Loot — chests & mob drops, removed or replaced
• Blocks — breaking, GUIs & container access
• Enchantments — anvil & enchanting table
• Armor Stands & Item Frames — displayed locked items are protected

On top of that, locked items can hide or replace their names and tooltips, and per-entry unlock_actions let you allow specific interactions (e.g. pickup or crafting) while everything else stays locked.

🔓 Unlock It Your Way

The Research Pedestal is just the default, not a requirement — every stage has a mode that defines how it unlocks:

• Default — classic research with Scrolls at the Pedestal
• Auto — unlocks via in-game triggers: item pickup, entering a biome/dimension/structure, entity kill/interact, block place/break, advancements, playtime (any/all combinable)
• External — unlock only via /history, KubeJS/CraftTweaker, or as FTB Quests reward
• Temporary — unlocks and re-locks on a timer, with cooldowns & trigger limits

Mix all of these freely in the same pack — research-driven eras, exploration-based unlocks, and quest rewards can live side by side. Individual stages can also be set to be lost on death, dropping the items they gated.

🔬 Research System

Players physically bring Research Scrolls to the Research Pedestal and spend time researching the next era. Four pedestal tiers (I–IV), placeable Research Boosters, and per-stage research times let you tune the pacing. With the Dependency System, stages can additionally require XP levels, mob kills, statistics, advancements, scoreboard objectives, or items deposited directly into the pedestal.

What happens to the scroll when the research finishes is up to you, per stage:

• Consumed — the scroll is used up
• Replaced — a fresh scroll for the same stage goes back into the pedestal, so the next player needs no second copy
• Opened — an open scroll stays behind as a readable keepsake

📜 The Research Record

An opened scroll is a real, readable document — chapters for Items, Creatures and World (dimensions, structures, biomes), with a searchable overview of everything the stage gates. Lay it on a lectern and it stays there to be read by anyone who walks up.

Set it to Visible and it reads as a plain record; set it to Obscured and locked entries become silhouettes with their names written in enchanting glyphs. Chapters and overview blocks are re-orderable, so the document says exactly what you want it to say.

🗺️ Stage Graph

A progression map players can open from the pause menu: stages as nodes, dependencies as edges, colour-coded into Unlocked, Reachable and Locked.

• Four visibility modes — from the whole map down to unlocked only, so you decide how much of the pack's structure players get to see
• Hand-authorable — drag nodes where you want them, or leave the layout to compute itself
• Per-stage node styles — fill, border, label colour and corner radius, each editable per lock state
• Info texts & a detail window — describe an era and show exactly what it requires and what it unlocks

It's off by default (the map reveals how a pack is built); admins always reach it through the editor. Colours, title and layout live in a Graph tab in the in-game config editor.

🛠️ In-Game Editor

Build and tweak your entire stage setup without ever touching a config file — straight from the pause menu (OP required):

• Searchable multi-select lists, folders for your stages and an organize mode to drag them around
• Dedicated editors for Dependencies, NBT & Lock-Actions — Ctrl-click any inventory slot to import its NBT
• Unlock or re-lock individual stages per player right from the overview
• Design the Research Scroll tooltip line by line, with colours and a live preview
• Overlap warnings between global & individual stages, plus a full in-game config editor

🎨 Feedback & Integrations

Players always know why something is locked: lock icons in inventories and JEI/EMI, "Locked" recipe overlays, toasts with custom per-stage icons, and configurable actionbar/chat messages.

• FTB Quests — native stage task & reward types (global + individual)
• KubeJS / CraftTweaker — StageEvent.Unlocked / Locked events
• Jade, Curios & Accessories support

📂 Creating Stages

Use the in-game editor, or write simple JSONs in config/historystages/global/ and individual/ — subfolders are picked up, so a big pack stays sorted. Full field reference: Stage Configuration.

The mod intentionally ships without default recipes for the Pedestal, Boosters & Scrolls — you decide how players obtain them (KubeJS, datapack, quest rewards, …). Give a scroll via:

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

📦 Dependencies

• Lootr — required
• Optional: JEI, EMI, FTB Quests, Jade, Curios, Accessories

❓ FAQ

Per player instead of server-wide? Yes — global, individual, or both mixed (overlaps become Dual-Phase locks).

Is Lootr really required? Yes, loot filtering is built on Lootr's container system. Without loot locking it just sits there quietly.

Do I need FTB Quests? No — the integration only activates when it's installed.

Supported versions?

• 1.20.1 — Forge (latest features)
• 1.21.1 — NeoForge (latest features)
• 1.21.1 — Fabric (currently a few versions behind)
• 1.19.2 — Forge (legacy, no longer updated)

Questions or found a bug? Join the Discord or open an issue — we read everything! 🙂