![](https://cdn.modrinth.com/data/cached_images/48b3f8553305ae3ee283e30b80d4b24f055cd2cd.png) * 📖 **[Wiki](https://historystages.github.io/)** — full documentation, config fields, JSON examples & developer API * 💬 **[Discord](https://discord.gg/BeZzxyZ9c4)** — support, questions & sneak peeks * 🐛 **[Issue Tracker](https://github.com/Flix100000/History-Stages/issues)** — bug reports & feature requests **History Stages** is a progression and gatekeeping mod for modpack creators. Lock items, recipes, dimensions, structures, biomes, mobs, fluids, merchant trades, 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** — recipe locks apply per player at the crafting table, the 2×2 grid, the stonecutter and the smithing table, and a locked recipe stays out of the recipe book * **Dimensions**, **Structures** & **Biomes** — with force-field zones, damage, potion effects & a red screen overlay * **Zones** [BETA] — an area you draw yourself, built from cuboids, spheres and cylinders, several shapes per zone. A locked zone pushes players back, shows a force-field wall up close and an outline from a distance, and tints the screen from the inside * **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** — attacklock & **interaction lock**: breeding, mounting, trading, leashing, shearing, milking, naming and equipping, each toggleable per entry and filterable by held item * **Spawn rules** — a spawn lock is a full rule: a phase, eight optional conditions (dimension, biome, sky, height, time of day, light, weather, moon phase) and biomes the creature additionally spawns in, with a sentence in the editor saying in plain words what the rule does * **Trades** — hide a single offer, a whole profession (optionally only on some of its levels), or a merchant level, per player, back the moment the stage unlocks. A locked offer is absent from the list rather than crossed out, so nobody loses a profession or stops levelling * **Fluids** — gate a fluid through whatever is carrying it: vanilla buckets, modded buckets and tank items alike, without listing a single item id. It also covers the recipes that fluid is consumed by or produces * **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 vanilla statistic, XP level, a status effect, the weather, the day count and the time of day (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, another stage — global, or an individual one the researcher alone has to hold — and items or whole **item tags** 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, zones and trades), 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 * **Changing backgrounds** — a stage can swap the map's background image once it is unlocked * **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 * A **recipe picker** that shows what a recipe is made of instead of its raw id, with fluids filed where the recipes are * A **zone editor** with a live map you can drag, zoom and jump around in * Dedicated editors for Dependencies, NBT criteria & 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** *** ## 🧩 **Scripts & Addons** **KubeJS and CraftTweaker** get a real integration: four KubeJS events, two ZenScript event types and a `hasStage` expansion on the player. Scripts can read which stages are unlocked, unlock or re-lock them, and ask whether a given thing is gated. What *belongs* to a stage stays with the editor, so the editor always shows what is actually locked. **Other mods can extend History Stages** without a fork and without a mixin. An addon registers its own lock categories, requirements, auto-triggers, per-stage settings and config sections, and each one gets a tab in the in-game editor built from the same widgets as the built-in ones — so a packmaker configures it without writing a script. → **[Addon Development](https://historystages.github.io/api/addon-development)** *** ## 🎨 **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** — full scripting API, see above * **Jade** — looking at a locked block, entity, armour stand or item frame names the stage it needs * **Curios** & **Accessories** — a locked item cannot be equipped as a trinket, ring or belt * **Spell Engine** & **Better Combat** — a locked weapon is inert: no spell damage, no attack *** ## 📂 **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: [The Stage File](https://historystages.github.io/wiki/stage-file/anatomy). 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[minecraft:custom_data={StageResearch:"YOUR_STAGE_NAME"}] ``` On 1.20.1 and older, where item data is still raw NBT: ``` /give @s historystages:research_scroll{StageResearch:"YOUR_STAGE_NAME"} ``` *** ## 📦 **Dependencies** * **Lootr** — required * _Optional:_ JEI, EMI, FTB Quests, Jade, Curios, Accessories, Spell Engine, Better Combat *** ## ❓ **FAQ**

Can stages be unlocked per player instead of server-wide?

Yes — global, individual, or both mixed in the same pack (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.

Do I have to update the server and the client together?

For 6.0, yes. The stage sync changed format, so a 6.0 client on a 5.x server gets the incompatible-mod screen instead of being dropped mid-login with nothing in the log. Settings and stage files migrate themselves on first load.

Which versions are supported?

* **1.21.1** — NeoForge * **1.20.1** — Forge * **1.21.1** — Fabric * **1.19.2** — Forge (legacy, no longer updated)

*** Questions or found a bug? Join the **[Discord](https://discord.gg/BeZzxyZ9c4)** or [open an issue](https://github.com/Flix100000/History-Stages/issues/new/choose) — we read everything! 🙂

PixlStudios

Modpack potential Mods

Organizations