ProgressiveStages 3.0

ProgressiveStages is a deeply customizable stage progression framework for Minecraft 1.21.1 on NeoForge. It gives modpack authors one place to define what players may use, where they may go, what automatically advances them, what a stage rewards, and how the entire progression graph appears in game.

Build a short stone to iron to diamond path, several independent technology and magic branches, a server wide story arc, temporary challenge stages, purchasable skill nodes, or a large quest driven pack. Stages are ordinary TOML files and every shipped feature is optional.

ProgressiveStages 3.0 is the stable 3.0 release.

The 3.0 progression map

Open the map with /stage, /stages, /ps, /stage gui, or the configurable keybind.

• Familiar vanilla advancement style task, goal, and challenge frames.
• Drag the map with the mouse and scroll with the wheel.
• Hover a node for its description, dependencies, trigger progress, and unlock preview.
• Click a node to pin its full details.
• Search by stage name, ID, description, category, or locked item.
• Hide stages the player already owns.
• Show or conceal future branches with reveal = "always", "dependencies", or "unlocked".
• Let the dependency graph place nodes automatically or set exact x and y coordinates.
• Give each stage its own item icon, frame type, background, color, category, and sort order.
• Purchase configured stages from the map. Every purchase is checked again by the server before any cost is removed.

The server remains authoritative. A modified client cannot grant stages, skip dependencies, or fake a purchase.

What can be gated

Each category can be enabled globally and customized inside individual stage files.

• Items. Gate use, pickup, hotbar access, mouse movement, or all inventory holding.
• Blocks. Gate placement and interaction.
• Fluids. Gate bucket pickup, placement, flow, submersion, and recipe viewer visibility.
• Recipes. Gate exact recipe IDs or every recipe that produces a locked item.
• Crops. Gate planting, growth, bonemeal, and harvesting.
• Dimensions. Stop portal and teleport travel with a post travel safety check.
• Enchantments. Gate enchanting, anvils, trades, and existing enchanted gear. Optional maximum levels support partial progression.
• Entities. Gate attacks and interactions.
• Fine grained interactions. Gate item on block, item on entity, and block right click combinations.
• Loot. Filter chest, fishing, archaeology, mob, block, and Lootr rolls.
• Mob spawns. Cancel a locked spawn or replace it with another entity.
• Pets. Gate taming, breeding, commanding, and riding.
• Screens. Gate block menus and held item menus such as backpacks.
• Villager trades and professions. Hide individual offers or block a profession's entire trading screen.
• Advancements. Hide locked advancements from the client until their stage is owned.
• Structures. Gate entry, containers, breaking, placement, explosions, and mob spawning.
• Regions. Gate hand authored three dimensional areas with independent rule flags and debuffs.
• Curios slots. Gate equipment slots when Curios is installed.
• Ores and encrypted blocks. Show a configurable substitute until the required stage is owned and guard the original drops.
• Abilities. Gate elytra flight, sprinting, swimming, and climbing.
• Beacon effects and brewing outputs. Gate individual effects and potions.

The same content may be gated by several stages. The player must own every still applicable stage. Per stage [unlocks] carve outs and [enforcement] policies remain scoped to the stage that declared them.

One matching language everywhere

Lock lists share the same readable prefixes.

Broad rules can keep exact exceptions:

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

Triggers live with their stage

Every automatic route belongs in the same stage TOML as the stage it unlocks. There is no separate global trigger file.

One stage can have several alternative [[triggers]] rules. A rule can require every condition with all_of, any condition with any_of, counts, tags, friendly durations, or custom KubeJS predicates.

Built in condition families cover:

• Items held, picked up, used, dropped, crafted, mined, or broken.
• Entity kills, boss kills, kills with a specific item, breeding, and taming.
• Advancements, effects, levels, XP, statistics, play time, sleeping, fishing, and riding.
• Dimensions, biomes, time spent in a biome, structures, altitude, weather, day count, and world time.
• Distance travelled.
• Another stage being held for a duration.
• Named custom counters controlled by commands, KubeJS, or another mod.
• Fully custom script conditions and script supplied progress.

Example:

[[triggers]]
mode = "all_of"
description = "Mine diamonds and earn ten quest points"

  [[triggers.conditions]]
  type = "mine"
  id = "minecraft:diamond_ore"
  count = 3

  [[triggers.conditions]]
  type = "custom_counter"
  counter = "quest_points"
  count = 10

Relevant game events ask only the indexed conditions to recheck. A configurable polling interval acts as a safety net for state based conditions.

Dependencies, scope, and stage life cycle

• Build linear, branching, converging, or independent dependency graphs.
• Choose all, any, or counted dependency satisfaction.
• Use team scoped stages for solo or FTB Teams progression.
• Use server scoped stages for world wide milestones.
• Group stages with categories and tags, then query or operate on the group.
• Add temporary durations.
• Revoke on death or when XP falls below a threshold.
• Cascade a revocation through dependent stages.
• Add item and XP purchase costs, cooldowns, and refund percentages.
• Apply stage owned attribute modifiers.
• Reward items, effects, commands, teleports, XP levels, or XP points on a real grant.
• Add a title, toast, sound, particles, progress nudges, or a HUD goal bar.

Commands for players and pack authors

Player and inspection tools include:

• /stage or /stage gui to open the map.
• /stage list, /stage check, /stage info, and /stage tree.
• /stage progress next, /stage progress all, or /stage progress <stage>.
• /stage simulate for a dry run of reachable and dependency blocked stages.

Administrative and authoring tools include:

• /stage grant and /stage revoke.
• /stage tag grant, revoke, and list.
• /stage category grant, revoke, and list.
• /stage bulk grant and revoke.
• /stage counter get, add, set, and reset.
• /stage sync to refresh a player's client state.
• /stage new <id> to scaffold a stage file.
• /stage export to create a Markdown progression guide in the config folder.
• /progressivestages reload for a validated live reload.
• /progressivestages validate for parse, dependency, registry, and trigger diagnostics.
• /progressivestages ftb status for FTB Quests diagnostics.

Suggestions are generated from loaded stage IDs, tags, categories, and counter names where applicable.

Expanded KubeJS API

KubeJS server scripts receive a global ProgressiveStages object.

ProgressiveStages.has(player, 'diamond_age')
ProgressiveStages.grant(player, 'diamond_age')
ProgressiveStages.revoke(player, 'diamond_age')
ProgressiveStages.available(player, 'diamond_age')
ProgressiveStages.percent(player, 'diamond_age')
ProgressiveStages.progress(player, 'diamond_age')
ProgressiveStages.addCounter(player, 'quest_points', 1)
ProgressiveStages.openGui(player)

The API also includes actual change callbacks, grant and revoke hooks, bulk operations, tag and category queries, dependency and dependent queries, definition snapshots, custom boolean conditions, custom progress providers, immediate trigger evaluation, synchronization, and the first class player.stages bridge.

Grant and revoke methods return whether ownership actually changed. Bulk methods return how many stages changed.

Java API and integration design

ProgressiveStagesAPI exposes ownership, dependency, definition, trigger progress, counter, bulk mutation, and synchronization operations. NeoForge events report grant and revoke changes with their cause.

Optional integrations are isolated behind compatibility seams and guarded mixins. The core does not require optional mod classes to load.

Supported optional integrations

• EMI and JEI. Hide locked entries or show lock overlays, tooltips, highlights, and instant refresh after a stage change.
• FTB Teams. Share team scoped stages while retaining solo fallback.
• FTB Quests and FTB Library. Stage tasks, rewards, required stage fields, and live rechecks.
• KubeJS. Global and player stage scripting APIs.
• Jade and WTHIT. Show the required stage while looking at a locked block or entity.
• Curios. Gate slots and eject locked equipment.
• Lootr. Filter each player's loot rolls.
• Mekanism. Handle NBT heavy item variants and automation surfaces.
• Nature's Compass. Respect locked dimension searches.
• Create and Visual Workbench. Preserve correct block and interaction classification.

All integrations are optional unless your pack uses their features.

Configuration layout

Launch once and ProgressiveStages creates:

config/
└── progressivestages/
    ├── progressivestages.toml
    └── stages/
        ├── stone_age.toml
        ├── iron_age.toml
        └── diamond_age.toml

Every editable stage file lives under config/progressivestages/stages/. Nested folders are supported.

• progressivestages.toml contains global defaults, performance settings, integration switches, disclosure rules, visual settings, and every configurable message.
• stages/ contains one or more stage TOML files. Nested folders are supported.
• diamond_age.toml is the fully commented generated reference and links to the maintained GitHub guides.
• Datapacks may provide stages at data/<namespace>/progressivestages/stages/*.toml. A config stage with the same ID wins.

Older loose layouts are migrated without overwriting an existing 3.0 target file.

Safe live reloads

/progressivestages reload builds and validates a complete candidate snapshot first. If any file fails to parse, a stage ID is duplicated, the dependency graph is invalid, or application fails, the previous working snapshot remains active.

Use /progressivestages validate before shipping a pack and follow the repository testing handbook for multiplayer and integration checks.

Requirements

• Minecraft 1.21.1.
• NeoForge 21.1 or newer within the declared Minecraft compatibility range.
• ProgressiveStages itself has no required recipe viewer, quest, team, scripting, or overlay mod.

Documentation and support

• Beginner guide: https://github.com/EnVisione/ProgressiveStages/blob/master/GETTING_STARTED.md
• Complete documentation: https://github.com/EnVisione/ProgressiveStages/blob/master/DOCUMENTATION.md
• Fully commented Diamond Stage reference: https://github.com/EnVisione/ProgressiveStages/blob/master/examples/reference/diamond_stage.toml
• Architecture and project structure: https://github.com/EnVisione/ProgressiveStages/blob/master/ARCHITECTURE.md
• Testing handbook: https://github.com/EnVisione/ProgressiveStages/blob/master/TESTING.md
• Bug reports: https://github.com/EnVisione/ProgressiveStages/issues
• Community Discord: https://discord.com/invite/9v4gaRSfdJ

If you find a bug, include the ProgressiveStages version, NeoForge version, relevant stage TOML, progressivestages.toml, and the latest log. Never include private server credentials or unrelated secrets.

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

🏆 What is ProgressiveStages?

ProgressiveStages is the ultimate progression control mod 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, recipes, blocks, entities, dimensions, fluids, and entire mods behind meaningful progression milestones. Players unlock stages through exploration, quests, boss kills, or custom conditions. No more sequence breaking. No more bypassing your carefully crafted progression curve.

Perfect for expert modpacks, skyblock-style challenges, gated tech progression, or any pack where the journey matters as much as the destination. If you've ever wanted Gamestages on modern NeoForge — this is it.

✨ Core Features

🔐 Comprehensive Locking System

Lock anything and everything standing between your players and the endgame:

• 🪓 Items — block use, pickup, crafting, and inventory holding
• 📦 Blocks — prevent placement and right-click interaction (furnaces, chests, machines, anything)
• 📜 Recipes — hide crafting outputs entirely from recipe viewers
• 🌍 Dimensions — gate portal travel to the Nether, End, or any custom dimension
• 👾 Entities — prevent attacking specific mobs, bosses, or all entities from a mod until the stage is earned
• 🧪 Fluids — hide specific fluids, fluid tags, or all fluids from a mod in EMI/JEI
• 🏭 Entire Mods — one line locks every item, block, entity, and fluid from a mod namespace
• 🔍 Name Matching — names = ["diamond"] locks anything with "diamond" in its ID across every installed mod, across ALL content types — items, blocks, entities, and fluids simultaneously
• ⚙️ Interactions — gate Create-style item-on-block interactions, right-clicking machines, applying items to blocks, and other custom player-world interactions

🎛️ Granular Mod Control

Most mods lock everything at once or nothing. ProgressiveStages gives you surgical precision:

• mods = ["mekanism"] — locks EVERYTHING from Mekanism (items, blocks, entities, fluids)
• item_mods = ["mekanism"] — locks only Mekanism items, not blocks or entities
• block_mods = ["mekanism"] — locks only Mekanism blocks, not items or entities
• entity_mods = ["mekanism"] — locks only Mekanism entities from being attacked
• fluid_mods = ["mekanism"] — locks only Mekanism fluids from EMI/JEI visibility

And every lock type has a matching whitelist — lock all of Mekanism but allow the Configurator back:

mods = ["mekanism"]
unlocked_items = ["mekanism:configurator"]
unlocked_blocks = ["mekanism:teleporter"]
unlocked_entities = ["mekanism:robit"]
unlocked_fluids = ["mekanism:hydrogen"]

Whitelists always win — no matter how broad the lock, your exceptions are respected.

📖 EMI & JEI Integration

The best visual lock experience available for 1.21.1:

• 🔒 Lock icons on every locked item in the search index and recipe viewer
• 🟠 Orange overlay highlights on locked recipe outputs
• 💬 Tooltips showing the required stage name
• 👻 Hide locked items from search entirely (optional) — works for ALL NBT variants including Mekanism Chemical Tanks, Meka-Suit pieces, and any item with stored energy, fluid, or chemical data
• ❓ Item name masking — locked items show as "Unknown Item" until unlocked
• ⚡ Updates instantly when a stage is granted or when switching gamemodes — no relog, no reload required
• 🎨 Fully configurable — icon size, overlay color, icon position

👥 Team Progression (FTB Teams)

Progression that works the way multiplayer should:

• 🤝 Team-scoped stages — the whole team progresses together
• 🔄 Synchronized unlocks — one member earns it, everyone gets it
• 🛡️ Stage matching rules — lower-stage players must match the team's stage to join

📋 FTB Quests Integration

Native, deep integration with FTB Quests:

• ✅ Stage Tasks — require a specific stage before a quest completes
• 🎁 Stage Rewards — grant stages directly as quest rewards
• 🔐 Stage Required field — hide entire quests or chapters until the player reaches a stage, built directly into the quest properties UI — no workarounds needed

⚡ Automatic Stage Triggers

No commands needed — stages grant themselves when players:

• 🏅 Complete a specific advancement
• 🎒 Pick up a target item (also scans inventory on login to catch players who already have it)
• 🌀 Enter a dimension for the first time (one-time, persists across restarts)
• 💀 Defeat a boss (one-time, persists across restarts)

🔗 Dependency Graph

Build a real progression chain — stages can require other stages before they can be granted. ProgressiveStages supports any structure you can imagine.

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

Missing a dependency when using /stage grant? The command warns you and asks for confirmation before bypassing it. With linear_progression = true, granting a stage auto-grants all missing dependencies up the chain automatically.

🛠️ Pack Developer Tools

Everything you need to build and iterate fast:

• 📝 TOML-based config — human-readable stage files, fully commented, no JSON hell
• 🚀 Auto-generated examples — stone_age, iron_age, diamond_age created on first run with every field documented inline
• 🔄 Live reload — /progressivestages reload applies all changes without a server restart
• ✔️ Validation command — catch typos, invalid IDs, and missing dependencies before your players find them
• 💬 Unlock messages — send color-coded chat messages to the whole team when a stage unlocks
• 🐛 Debug logging — detailed output for troubleshooting your stage setup

⚙️ Highly Configurable

• Toggle any enforcement type independently — items, recipes, blocks, entities, dimensions, interactions
• Creative mode bypass — ops and creative players skip all locks and lock UI
• Customizable EMI/JEI visuals — icon size, overlay color, icon position, show/hide locked items
• Notification cooldowns — no chat spam when touching locked items
• Mask locked item names — show "Unknown Item" to keep content mysterious
• Debug logging — detailed output for troubleshooting

💻 Commands

Player:

• /stage list — View your unlocked stages
• /stage check <stage> — Check if you have a specific stage

Admin:

• /stage grant <player> <stage> — Grant a stage
• /stage revoke <player> <stage> — Revoke a stage
• /progressivestages reload — Reload all stage files live
• /progressivestages validate — Check stage files for errors
• /progressivestages ftb status <player> — Debug FTB integration
• /progressivestages trigger reset <player> <type> <key> — Reset a one-time trigger

📦 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

🐛 Found a bug? Have a feature request?

Open an issue on GitHub or drop it in our Discord. This mod 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.