Описание
* 📖 **[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! 🙂