![History Stages Banner](https://cdn.modrinth.com/data/cached_images/48b3f8553305ae3ee283e30b80d4b24f055cd2cd.png) **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:

Click to expand — JSON format

```json { "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

Click to expand — all commands require Permission Level 2 (OP)

**Global Stages** (server-wide): - `/history global unlock ` — unlocks a stage globally - `/history global unlock *` — unlocks all global stages - `/history global lock ` — relocks a specific stage - `/history global lock *` — resets all global stages - `/history global list` — lists all global stages - `/history global info ` — shows details for a stage **Individual Stages** (per player): - `/history individual unlock ` — unlocks a stage for a player (supports `@a`, `@p`, etc.) - `/history individual lock ` — relocks a stage for a player - `/history individual list ` — lists a player's stages - `/history individual info ` — shows stage details for a player **General:** - `/history reload` — reloads all configs and syncs to all clients

--- ## 🔧 For Developers & Script Authors

Click to expand — Forge Events for KubeJS, CraftTweaker & other mods

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

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

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.

Do I need to add crafting recipes for the Research Pedestal and Scrolls myself?

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.

Is Lootr really required? Can I use the mod without it?

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.

Does it work with KubeJS or CraftTweaker?

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.

Which Minecraft versions are supported?

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

Do I need FTB Quests to use this mod?

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.

Where are the stage config files stored now?

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](https://github.com/Flix100000/History-Stages/issues/new/choose) — we read everything! 🙂

Analytics

Error