V2.0 RELEASE

🔒 Looking for Beta Testers! Found a bug? Report it on our Discord or GitHub — every report helps shape the stable release.

🏆 What is ProgressiveStages?

ProgressiveStages 2.0 is the most complete progression-control framework available for NeoForge 1.21.1. Built for modpack developers who want players to actually earn their way through content — not skip straight to endgame on day one.

Lock items, blocks, fluids, recipes, crops, enchantments, dimensions, mobs, interactions, loot rolls, GUIs, pet interactions, structures, and 3D regions behind meaningful progression milestones. Players unlock stages through exploration, quests, advancements, boss kills, item pickups, or any combination of those events. No more sequence breaking. No more bypassing your carefully crafted progression curve.

If you've ever wanted Gamestages — but on modern NeoForge, with depth, with team support, with EMI/JEI integration, and with the kind of safety nets that survive real modpacks — this is it.

✨ What's new in 2.0?

2.0 is a ground-up rewrite of the locking model. Every category now uses the same unified prefix system, the same [unlocks] carve-out grammar, and the same per-stage [enforcement] exemptions. New surfaces, new triggers, and a completely rewritten config schema:

🆕 Unified prefix system — id: / mod: / tag: / name: / # all work in every locked list, across every category.
🆕 [[multi]] trigger requirements — gate a stage behind a set of conditions ("own a stone sword AND a stone pickaxe AND a stone axe"). Mix item:, advancement:, dimension:, and boss: sub-triggers freely, with all_of or any_of semantics.
🆕 Multi-stage gating — the same content can be locked by multiple stages at once. Players must unlock every gating stage to use it.
🆕 [crops] — full crop-progression gating: planting, growth, bonemeal, harvest.
🆕 [enchants] — gate enchantments at the table, the anvil, villager trades, AND strip them from existing gear on inventory scan.
🆕 [mobs] — gate spawning of specific mobs (or whole mod namespaces, or tags). Includes dynamic replacement — swap an unwanted spawn for a friendlier mob automatically.
🆕 [pets] — separately gate taming, breeding, commanding, and riding for animals.
🆕 [screens] — one list gates every GUI surface, including held-item GUIs (backpacks, portable workstations, held shulker boxes).
🆕 [structures] — gate entry to vanilla and modded structures, lock chests inside them, prevent block break/place/explosions/spawns inside the bounding box.
🆕 [[regions]] — define hand-authored 3D boxes per dimension with their own flags and debuffs.
🆕 [loot] — a single list filters chest, fishing, archeology, mob-drop, and block-drop rolls through a Global Loot Modifier. Lootr is supported out of the box.
🆕 [curios] — per-slot gating when Curios is installed.
🆕 [[interactions]] — fine-grained "item-on-block" / "item-on-entity" / "right-click-this-block" rules for Create-style and modded interactions.
🆕 Native FTB Quests "Stage Required" field on every quest and chapter — no workarounds.
🆕 /stage progress command — next shows what you can unlock right now (with per-trigger ✓/✗), all shows the full roadmap, <stage> shows the breakdown for one specific stage.
🆕 Creative-bypass popup so admins know when their actions are being skipped.
🆕 Configurable messages — every chat line, tooltip, and lock message supports &-color codes and placeholders.
🆕 Operator-only stage names — non-op players see spoiler-free generic messages.
🆕 [unlocks] carve-outs — broad locks (mod:ae2, name:diamond) can carve out specific exceptions on a per-stage basis.
🆕 [enforcement] per-stage exemptions — let players stockpile raw materials before unlocking the use of them.

🔐 The Comprehensive Locking System

Every category below uses the same unified prefix system. You can mix and match id: / mod: / tag: / name: entries in any list:

Prefix	Meaning	Example
`id:<namespace:path>`	Exact registry ID	`id:minecraft:diamond`
(no prefix)	Implicit `id:`	`minecraft:diamond`
`mod:<namespace>`	Entire mod namespace	`mod:ae2`
`tag:<namespace:path>`	A registry tag	`tag:minecraft:logs`
`name:<substring>`	Case-insensitive substring of the full ID	`name:netherite`
`#<namespace:path>`	Legacy tag shorthand	`#minecraft:crops`

What you can lock

🪓 Items — use, pickup, hotbar, mouse-pickup, full-inventory removal, all independently toggleable.
📦 Blocks — placement and right-click interaction. State-aware (Visual Workbench-style shim systems are handled correctly).
🧪 Fluids — bucket pickup, bucket placement, in-world flow, submersion (locked fluids apply Slowness II + Blindness), and recipe-viewer visibility.
📜 Recipes — by recipe ID (locked_ids) OR by output item (locked_items). Hide locked recipes from EMI/JEI entirely or show them with overlays.
🌾 Crops — planting, growth, bonemeal, harvest. Growth uses nearest-player resolution so a single un-staged player doesn't slow the whole server.
🌍 Dimensions — pre-travel cancel + post-travel safety net + per-second tick check. Nature's Compass is gated automatically.
✨ Enchantments — at the table, the anvil, villager trades, AND stripped from inventory items on the periodic scan (catches loot, fishing, etc.). Curios slots are scrubbed too.
👾 Entities (attack) — [entities] blocks attacking specific entity types.
⚙️ Interactions — [[interactions]] lets you gate block_right_click, item_on_block, and item_on_entity events in fine detail.
🎁 Loot rolls — chest loot, fishing rolls, archeology, mob drops, block drops, Lootr per-player rolls — all filtered through a single [loot] list.
🐺 Mob spawning — locked_spawns cancels finalizeSpawn-based spawns. Dynamic replacement ([[mobs.replacements]]) lets you swap one mob for another at spawn time.
🐶 Pets — independently gate taming, breeding, commanding (sit/stand/follow), and riding.
🖥️ Screens (GUIs) — one list, two surfaces: block GUIs (crafting tables, anvils, chests, modded machines) AND held-item GUIs (backpacks, portable workstations, held shulkers).
🏛️ Structures — gate vanilla + modded structure entry. Chest-locking inside the bounding box is always on. Optional rule flags: prevent_block_break, prevent_block_place, prevent_explosions, disable_mob_spawning.
📐 Regions — hand-authored 3D boxes in a specific dimension with per-region flags: push players out + debuff, prevent break/place/explosions/spawns.
💍 Curios slots — per-slot gating with automatic ejection + enchantment-strip when Curios is installed.

Whitelists win

Every category supports always_unlocked = [...] for exact-ID exceptions. Lock all of Mekanism but keep the Configurator usable:

[items]
locked = ["mod:mekanism"]
always_unlocked = ["mekanism:configurator"]

And per-stage [unlocks] carves out exceptions in even broader scopes — see the docs for the full grammar.

⚡ Automatic Stage Triggers

Triggers live in one file (config/ProgressiveStages/triggers.toml). Stages grant themselves when players:

🏅 Complete a specific advancement — [advancements]
🎒 Pick up a target item — [items] (also scans inventory at login to catch players who already have it)
🌀 Enter a dimension for the first time — [dimensions] (one-time, persisted per-world)
💀 Defeat a boss — [bosses] (one-time, persisted per-world)

🆕 `[[multi]]` — compound trigger requirements

The headline 2.0 trigger feature. Require MULTIPLE conditions before a stage is granted:

[[multi]]
stage = "stone_tools_master"
description = "Own a full set of stone tools"
all_of = [
    "item:minecraft:stone_sword",
    "item:minecraft:stone_pickaxe",
    "item:minecraft:stone_axe",
]

Mix surfaces freely — items, advancements, dimensions, bosses:

[[multi]]
stage = "endgame"
description = "Beat the major bosses + reach the End + survive once"
all_of = [
    "boss:minecraft:ender_dragon",
    "boss:minecraft:wither",
    "dimension:minecraft:the_end",
    "advancement:minecraft:adventure/totem_of_undying",
]

Use any_of instead of all_of for "satisfy any one route" gating. Per-player progress is persisted across restarts; retroactive credit on login is given for item / advancement / dimension surfaces (boss kills must be re-earned).

🔗 Dependency Graph

Stages declare other stages as prerequisites — single string or list. The dependency graph is an arbitrary DAG, validated at load time:

Linear progression — the classic tier chain:

🪨 stone_age
    └── ⚙️ iron_age
            └── 💎 diamond_age
                    └── 🔮 netherite_age

Branching paths — tech and magic unlock separately:

🪨 stone_age
    ├── ⚙️ iron_age
    │       ├── 💎 diamond_age
    │       └── 🏭 tech_age
    │               └── ☢️ nuclear_age
    └── 📚 magic_age
            ├── 🔮 arcane_age
            └── 🌿 nature_age

Multi-dependency gates — require multiple paths before unlocking endgame:

🪨 stone_age
    ├── ⚙️ iron_age ──────────────────┐
    │       └── 💎 diamond_age ───────┤
    │                                 ▼
    └── 📚 magic_age ─────────► 🌌 endgame_age
            └── 🔮 arcane_age ────────┘
                (requires BOTH diamond_age AND arcane_age)

Parallel independent trees — some stages have no dependencies at all:

🪨 stone_age          🌿 nature_age          🗺️ exploration_age
    └── ⚙️ iron_age       └── 🔮 druid_age       └── 🌋 nether_age
            └── 💎 diamond_age                             └── 🐉 end_age

With linear_progression = true, granting a stage auto-grants every missing dependency up the chain. With it false, /stage grant warns about missing dependencies and requires a second confirmation to bypass.

📖 EMI & JEI Integration

The best visual lock experience available for 1.21.1:

🔒 Lock-icon overlays on every locked item in the index and recipe viewer (size + position configurable)
🟠 Translucent highlight overlay on locked recipe outputs (color configurable, ARGB hex)
💬 Tooltips showing the required stage name — or a generic "Progress further to unlock" line for non-op players (reveal_stage_names_only_to_operators)
👻 Hide locked items from the search index entirely (optional)
❓ Item-name masking — locked items render as "Unknown Item" until unlocked
⚡ Updates instantly when a stage is granted or revoked, when switching gamemodes, or when reloading the config — no relog, no reload
🛡️ NBT-variant aware — every variant of locked items (Mekanism Chemical Tanks, Meka-Suit pieces, items with stored energy/fluid/chemical data) is hidden together

👥 Team Progression (FTB Teams)

🤝 Team-scoped stages — the whole team progresses together
🔄 Synchronized unlocks — one member earns it, the whole team gets it
💾 persist_stages_on_leave — keep a player's stages when they leave the team
🪂 Automatic fallback to solo mode when FTB Teams isn't installed

📋 FTB Quests Integration

Native, deep integration:

✅ Stage Tasks — quests require a stage before completing
🎁 Stage Rewards — quests grant stages directly
🆕 🔐 Stage Required field on every Quest and Chapter — hide quests or whole chapters until a stage is reached, built directly into the Visibility section of the properties UI
🔄 Live re-checks — granting/revoking a stage debounces a recheck for every affected player, budgeted per tick so heavy quest packs stay smooth
🪂 Soft-disable — if an FTB API change breaks integration, locks and EMI/JEI keep working; the mod logs a clear error pointing at the exact failure

🛠️ Pack Developer Tools

📝 TOML-based config — human-readable, fully commented, no JSON hell
🚀 Auto-generated examples — stone_age, iron_age, diamond_age, plus triggers.toml on first launch. The diamond_age.toml template is the canonical 2.0 reference, with every category and field documented inline.
🔄 Live reload — /progressivestages reload re-parses all stage TOMLs and re-syncs every online player, no restart required
✔️ Validation — /progressivestages validate parses every stage file with detailed error reporting and warns about dependency issues before your players find them
🆕 /stage progress — show players exactly what they can unlock next, the full roadmap, or the per-trigger breakdown for one specific stage
💬 Unlock messages — broadcast color-coded chat messages to every team member when a stage unlocks
🆕 Configurable messages — every player-facing string (tooltips, chat, command output, type labels, creative popup) is overridable in config
🐛 Debug logging — verbose stage-check / lock-query / team-operation output

⚙️ Highly Configurable

Toggle any enforcement type independently — items, recipes, blocks, entities, dimensions, interactions, mobs, crops, pets, screens, loot, enchants, regions, structures.

🎯 Per-stage [enforcement] exemptions — let players stockpile raw diamonds before unlocking the use of diamonds:

  [items]
  locked = ["name:diamond"]
  [enforcement]
  allowed_pickup = ["minecraft:diamond"]
  allowed_inventory = ["minecraft:diamond"]

🎨 EMI/JEI visuals — icon size, position, overlay color, hide-vs-show
🔇 Notification cooldowns — no chat spam when touching locked items
🎭 Mask locked item names — keep content mysterious with "Unknown Item"
🔊 Lock sound — configurable sound + volume + pitch when an action is blocked
👮 Operator-only stage names — reveal_stage_names_only_to_operators hides stage IDs from non-op players for spoiler-free progression
🆕 ⚠️ Creative-bypass popup — warn admins when entering creative that locks are being skipped
🐛 Debug logging — detailed enforcement traces

💻 Commands

Player-facing

/stage list [player] — list a player's stages
/stage check <player> <stage> — boolean check
/stage info <stage> — stage metadata: id, dependencies, description, lock count
/stage tree — ASCII dependency tree of every loaded stage
🆕 /stage progress — what the caller can unlock right now
🆕 /stage progress next [player] — every reachable stage + per-trigger ✓/✗ breakdown
🆕 /stage progress all [player] — full roadmap, including unreachable stages
🆕 /stage progress <stage> [player] — per-trigger breakdown for one specific stage

Admin

/stage grant <player> <stage> — grant a stage (prompts for confirmation if dependencies are missing)
/stage revoke <player> <stage> — revoke a stage
/progressivestages reload — reload every stage file + triggers.toml, re-sync online players
/progressivestages validate — detailed parse + dependency check across every stage file
/progressivestages ftb status [player] — diagnostics for the FTB Quests integration
/progressivestages trigger reset <player> <type> <key> — clear a persisted trigger (dimension, boss, multi)
🆕 /progressivestages multi list [player] — every [[multi]] requirement and (with a player) their per-requirement progress
/progressivestages no-creative-popup — per-player toggle for the creative-bypass popup

🔌 Integrations

FTB Teams — team-shared stage state, automatic fallback to solo
FTB Quests + FTB Library — Stage Tasks, Stage Rewards, native Stage Required property, live rechecks
EMI — lock icons, highlights, tooltips, NBT-variant hiding
JEI — lock icons, highlights, tooltips
Curios — per-slot gating, ejection, enchantment strip
KubeJS — scriptable stage grants/queries
Lootr — per-player loot roll filtering via the published ILootrFilterProvider ServiceLoader
Mekanism — NBT-variant hiding for Chemical Tanks, Meka-Suit pieces, energized items
Nature's Compass — auto-gated when any dimension is locked
Create / Visual Workbench — state-aware block gating so workbench shims classify correctly

📦 Requirements

NeoForge for Minecraft 1.21.1 — required
EMI or JEI — optional, for recipe viewer integration
FTB Quests + FTB Library — optional, for quest integration
FTB Teams — optional, for team-shared progression
Curios — optional, for per-slot gating

📚 Documentation

The mod ships with an exhaustive DOCUMENTATION.md covering every TOML field, every config key, every command, every integration, and every troubleshooting tip. Read it on GitHub, or grab the file out of the jar.

🐛 Found a bug? Have a feature request?

Open an issue on GitHub or drop it in our Discord. ProgressiveStages 2.0 is actively developed and every report gets looked at. We're building toward a stable 1.0 release and your feedback directly shapes what comes next.