ProgressiveStages

ProgressiveStages 3.0

🧭 Build complete Minecraft progression systems through an in-game editor—then let ProgressiveStages enforce them everywhere.

✨ Create your progression in-game

Run /pstages editor to open the ProgressiveStages editor GUI.

Create, edit, organize, and configure your stages without needing to build every TOML file by hand. Design the progression your pack needs, connect its dependencies, configure its locks and unlock conditions, customize how it looks, and then test it in-game.

ProgressiveStages is not simply an item-locking mod. It is a complete progression-authoring platform that lets modpack creators decide what players can use, where they can travel, what they must accomplish, how progression is shared, what happens when a stage is earned or lost, and how the entire journey is presented in-game.

Every stage is defined in a readable TOML file. A stage can represent almost anything: an age, chapter, skill, class, research topic, quest milestone, boss tier, dimension, technology branch, magic school, server event, temporary blessing, punishment, or purchasable upgrade.

🌟 Build practically any kind of progression

• A simple Stone Age → Iron Age → Diamond Age progression.
• Several independent technology, exploration, farming, and magic branches.
• A large quest-driven modpack with hundreds of interconnected milestones.
• RPG-style skill trees with costs, prerequisites, attributes, rewards, and refunds.
• Team progression with FTB Teams or world-wide server milestones.
• Secret paths that remain hidden until the player discovers their prerequisites.
• Temporary challenge stages that expire, disappear on death, or require maintained XP.
• Fully scripted progression using KubeJS and the Java API.

ProgressiveStages itself does not require a quest mod, recipe viewer, team mod, scripting mod, or overlay mod. Every integration is optional and activates only when its related mod is installed.

🛡️ Server authoritative: the server owns stage progress, grants, revocations, dependencies, costs, and enforcement. A modified client cannot give itself stages, fake a purchase, or bypass progression rules.

---

🌳 What progression can look like

Progression can be linear:

🪨 Stone Age
   └── 🔩 Iron Age
       └── 💎 Diamond Age
           └── ⚔️ Netherite Age

It can branch into different playstyles and later converge:

🌱 Survival Basics
└── 🔩 Iron Age
    ├── ⚙️ Engineering ──────┐
    │   └── 🏭 Advanced Tech │
    ├── 🔮 Arcane Studies ───┼──▶ 👑 Endgame
    │   └── 🪄 Master Sorcery│
    └── 🧭 Exploration ──────┘
        └── 🌌 Outer Realms

Dependencies support all, any, and counted satisfaction. That means an endgame stage can require every branch, any one specialization, or a configurable number of paths.

🎯 Choose a Specialization
├── ⚙️ Technology ─┐
├── 🔮 Magic ──────┼──▶ 🏆 Mastery (complete any 2 paths)
└── ⚔️ Combat ─────┘

Stages may also be completely independent. A server can have a main story tree, optional skill trees, temporary events, and hidden secrets at the same time.

---

🗺️ The player progression map

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

The 3.0 map is modeled after Minecraft's advancement screen while remaining fully controlled by the pack author:

• Familiar vanilla task, goal, and challenge frames.
• A draggable, wheel-scrollable dependency graph.
• Automatic graph layout when coordinates are omitted.
• Exact x and y placement when a hand-authored layout is preferred.
• Dependency connectors that make branches and convergence easy to understand.
• Hover cards with descriptions, dependencies, trigger progress, and unlock previews.
• Click-to-pin detail panels for longer information.
• Search by name, ID, description, category, or locked item.
• A toggle to hide stages the player already owns.
• Per-stage icons, colors, categories, backgrounds, frames, and sort order.
• Server-validated stage purchases directly from the map.
• Live progress for automatic trigger conditions.
• Unknown icons, concealed names, and spoiler-safe descriptions.

Authors decide when a node becomes visible with [display].reveal:

Reveal mode	Behavior
always	The stage is always visible.
dependencies	The stage appears when its prerequisite path becomes relevant.
unlocked	The stage stays concealed until it is owned.

Set [stage].hidden = true to omit a stage from the map entirely while still using it internally.

Example display configuration:

[stage]
id = "diamond_age"
display_name = "Diamond Age"
description = "Master diamond tools and unlock advanced machinery."
icon = "minecraft:diamond"
color = "#55FFFF"
category = "Main Progression"
tags = ["main", "tier3", "technology"]

[display]
frame = "challenge"
background = "minecraft:block/deepslate_tiles"
reveal = "dependencies"
sort_order = 30

# Optional manual map placement. Omit both for automatic layout.
x = 168
y = 0

The client only displays synchronized data. The server remains authoritative: a modified client cannot grant a stage, bypass a dependency, fake trigger progress, or purchase a stage without paying its validated cost.

---

🔒 Everything ProgressiveStages can gate

Each category is optional. Global enforcement settings provide pack-wide defaults, while a stage's [enforcement] section can customize how its own locks behave.

🎒 Items and inventories

Gate individual items, tags, entire mods, or ID patterns. Depending on configuration, ProgressiveStages can prevent:

• Using a locked item.
• Picking it up.
• Moving it with the mouse.
• Keeping it in the hotbar or inventory.
• Placing its block form.
• Repairing, renaming, or combining it in an anvil.
• Hiding or obscuring it in recipe viewers.
• Equipping it in supported Curios slots.

Lock overlays render in normal inventories, chests, hotbars, backpacks, anvils, and other slot-based menus.

🧱 Blocks and interactions

Gate block placement, breaking, and right-click interaction. Fine-grained rules can distinguish:

• Right-clicking a block with an empty hand.
• Using a specific item on a specific block.
• Using a specific item on an entity.
• Opening a block menu.
• Opening a held-item menu such as a backpack.

🛠️ Recipes and crafting

Lock exact recipe IDs or every recipe whose output is a locked item. Enforcement protects both recipe discovery and actual crafting output, so hiding a recipe in JEI or EMI is never the only defense.

💧 Fluids

Gate fluid pickup, bucket placement, world placement, flow, player submersion, and recipe-viewer visibility.

🌾 Crops and farming

Gate planting, natural growth, bonemeal, harvesting, and crop drops. This allows farming branches where seeds, mature crops, automation, or entire agriculture mods unlock at different times.

🌌 Dimensions and teleportation

Prevent portal travel and command/mod teleportation into locked dimensions. A post-travel safety check catches integrations that bypass normal portal events.

✨ Enchantments

ProgressiveStages can:

• Lock an enchantment completely.
• Keep it out of enchanting, anvils, and trades.
• Remove illegal enchantments from existing gear.
• Cap an enchantment at a temporary maximum level.

When several missing stages cap the same enchantment, the strictest remaining cap wins.

[enchants]
locked = ["minecraft:mending"]
max_levels = [
    "minecraft:sharpness:3",
    "minecraft:protection:2"
]

⚔️ Entities, combat, and interaction

Gate attacking or interacting with specific entities, registry tags, ID patterns, or entire mods. A combat branch can require one stage to fight undead and another to challenge bosses.

👾 Mob spawning and replacement

Cancel locked mob spawns or replace them with a different entity. This can keep late-game enemies out of early areas or transform them into a safer substitute until the relevant stage is earned.

🐺 Pets and mounts

Gate taming, breeding, commanding, interacting with, or riding pets and other supported entities.

🎁 Loot

Filter locked content from:

• Chests and generated containers.
• Fishing.
• Archaeology.
• Mob drops.
• Block drops.
• Lootr's per-player loot rolls.

Loot filtering is server-side, preventing players from receiving content simply because it appeared in a generated table.

🖥️ Screens and menus

Block specific block menus or held-item menus. This is useful when the item itself may be carried but its configuration or storage interface should unlock later.

🧑‍🌾 Villagers, trades, and professions

Use [trades] to hide individual offers based on their result, or [professions] to prevent opening an entire profession's trading screen. Wandering traders have no profession and can be managed through trade rules.

🏆 Advancements

Locked advancements can be withheld from the client entirely. They do not merely appear greyed out—they remain hidden until their required stage is owned, then refresh without requiring a relog.

🏰 Structures

Gate entry into structures and independently control:

• Container access.
• Block breaking.
• Block placement.
• Explosions.
• Mob spawning.

Players who breach a locked structure can be returned to their last safe position, with configurable entry padding to keep them away from its boundary.

📍 Regions

Define hand-authored three-dimensional regions with their own restrictions, messages, rule flags, and debuffs. Regions are useful for server hubs, dungeons, arenas, towns, story locations, or areas not represented by a registered Minecraft structure.

💍 Curios equipment slots

When Curios is installed, individual slots can require stages. Locked equipment can be ejected and normal item enforcement remains available as a fallback.

⛏️ Ores and encrypted blocks

Locked ore or block IDs can be visually replaced with another block—stone by default—until the player earns the stage. Chunk data, break behavior, and drops are guarded so the visual disguise does not become a bypass.

[blocks]
locked = ["minecraft:diamond_ore", "minecraft:deepslate_diamond_ore"]

[display]
encrypt_blocks = true
encrypt_as = "minecraft:stone"

🪽 Player abilities

Gate movement abilities independently:

[abilities]
locked = ["elytra", "sprint", "swim", "climb"]

🧪 Beacon effects and brewing

Gate individual beacon effects per player and prevent unauthorized players or automation from extracting locked potion outputs from brewing stands.

💪 Stage-owned attributes

A stage can apply any registered vanilla or modded attribute while owned, including health, scale, attack damage, movement speed, or reach. Modifiers support additive, base-multiplicative, and total-multiplicative operations and are removed when the stage is revoked.

---

🧩 One matching language across the mod

Lock lists use the same readable syntax in nearly every category:

Entry	Meaning	Example
id:	One exact registry ID	id:minecraft:diamond
No prefix	Shorthand for id:	minecraft:diamond
mod:	An entire mod namespace	mod:mekanism
tag:	A registry tag	tag:minecraft:logs
#	Tag shorthand	#minecraft:logs
name:	Case-insensitive ID substring	name:netherite

Broad locks can contain exact carve-outs:

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

If multiple stages gate the same content, the player must own every applicable stage. A whitelist or [unlocks] entry affects only the stage that declared it; it does not silently override another stage's lock.

---

⚡ Automatic stage triggers

Triggers live inside the stage they unlock—there is no separate global trigger file.

A stage may have multiple [[triggers]] blocks. Each block is an alternative route to the same stage. Inside a block, use:

• mode = "all_of" to require every condition.
• mode = "any_of" to require at least one condition.

Built-in trigger conditions cover:

Family	Examples
Items	Hold, pick up, use, drop, craft, mine, or break an item/tool.
Combat	Kill entities, kill bosses, kill with a specific item, tame, or breed.
Player state	Level, XP, effects, statistics, play time, sleeping, fishing, or riding.
Exploration	Dimension, biome, time in biome, structure, altitude, distance, and advancements.
World state	Weather, day count, and world time.
Progression state	Hold another stage for a duration.
External progress	Named counters controlled by commands, KubeJS, quests, or another mod.
Custom logic	KubeJS predicates and script-supplied progress.

Counter-based conditions can be retroactive when backed by vanilla statistics. Event-indexed evaluation means relevant game events recheck only the conditions they may affect, while a configurable polling interval safely handles live state conditions.

📘 Example: one required route

[[triggers]]
mode = "all_of"
description = "Mine diamonds and complete ten factory quests"

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

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

🔀 Example: alternative routes

# Route 1: defeat the dragon.
[[triggers]]
mode = "all_of"
description = "Defeat the Ender Dragon"

  [[triggers.conditions]]
  type = "kill"
  entity = "minecraft:ender_dragon"
  count = 1

# Route 2: become a master explorer instead.
[[triggers]]
mode = "all_of"
description = "Visit the End and travel 50,000 blocks"

  [[triggers.conditions]]
  type = "dimension"
  dimension = "minecraft:the_end"

  [[triggers.conditions]]
  type = "distance"
  movement = "all"
  count = 50000

Dependencies are always respected by normal trigger grants. Progress may accumulate early, but the stage cannot auto-grant until its prerequisite rules are satisfied.

---

🔗 Dependencies, scopes, tags, and categories

Stages support:

• Linear, branching, converging, circularly validated, or independent graphs.
• all, any, and counted dependency requirements.
• Team-scoped ownership for solo play or FTB Teams.
• Server-scoped ownership for world-wide milestones.
• Categories for organization and presentation.
• Tags for queries and bulk operations.
• Hidden internal stages.
• Starting stages.

Example server-wide event:

[stage]
id = "dragon_defeated"
display_name = "The Dragon Has Fallen"
description = "The first victory unlocks the End Age for the entire server."
scope = "server"
tags = ["story", "server_event"]

---

⏳ Stages can be temporary or lost

Progression does not have to be permanent.

• [stage].duration = "30m" creates a temporary stage that expires after real time, including time spent offline.
• [revoke].on_death = true removes it when the player dies.
• [revoke].xp_below = N keeps it only while total XP remains above a threshold.
• [revoke].cascade = true also removes stages that depend on it.

[stage]
id = "berserker_blessing"
display_name = "Berserker's Blessing"
duration = "30m"

[revoke]
on_death = true
cascade = true

This supports timed events, temporary classes, challenge runs, maintained qualifications, curses, blessings, and true regression systems.

---

💎 Purchasable skill-tree nodes

A [cost] table turns a stage into a purchasable map node.

[cost]
xp_levels = 30
items = ["minecraft:diamond:5", "minecraft:emerald:3"]
bypass_requirements = false
cooldown = "5m"
refund_percent = 50

• Dependencies are still enforced.
• bypass_requirements = true skips trigger requirements, not prerequisite stages.
• Cooldowns are tracked per player.
• Refunds can return a percentage of item and XP cost when a purchased stage is revoked.
• Every purchase is revalidated by the server before any cost is removed.

This makes ProgressiveStages suitable for RPG skills, research systems, prestige trees, class upgrades, and server shops without requiring a separate GUI mod.

---

🎉 Rewards and unlock presentation

[rewards] controls what the player receives on a real grant:

[rewards]
items = ["minecraft:diamond:5", "minecraft:netherite_scrap:2"]
effects = ["minecraft:strength:120:1", "minecraft:regeneration:60:0"]
commands = [
    "give {player} minecraft:cake 1",
    "say {player} has entered the Diamond Age!"
]
teleport = "minecraft:the_nether 0 70 0"
xp_levels = 5
xp_points = 100

Rewards run once for each real ownership change, not on login or synchronization. Team progression rewards the player who actually earned or purchased the stage rather than duplicating rewards to every team member.

[unlock] controls the moment-to-moment presentation:

[unlock]
toast = "Diamond Age reached!"
title = "&b&lDIAMOND AGE"
subtitle = "&7A new era begins"
sound = "minecraft:ui.toast.challenge_complete"
particle = "minecraft:totem_of_undying"
progress_nudges = true
hud_bar = true

Every effect is optional. A pack can use a quiet background stage, a dramatic story milestone, or anything between them.

---

📝 A complete starter stage example

[stage]
id = "iron_age"
display_name = "Iron Age"
description = "Smelt iron to unlock iron tools, machinery, and the next technology tier."
icon = "minecraft:iron_ingot"
dependency = ["stone_age"]
category = "Main Progression"
tags = ["main", "technology", "tier2"]
color = "#D8D8D8"
scope = "team"

[display]
frame = "goal"
reveal = "dependencies"
sort_order = 20
show_tooltip = true
show_description_on_tooltip = true

[items]
locked = [
    "minecraft:iron_pickaxe",
    "minecraft:iron_axe",
    "minecraft:iron_shovel",
    "minecraft:iron_sword",
    "minecraft:iron_helmet",
    "minecraft:iron_chestplate",
    "minecraft:iron_leggings",
    "minecraft:iron_boots"
]

[blocks]
locked = ["minecraft:anvil", "minecraft:blast_furnace"]

[recipes]
locked_outputs = ["tag:minecraft:iron_tool_materials"]

[[triggers]]
mode = "all_of"
description = "Smelt your first iron ingot"

  [[triggers.conditions]]
  type = "advancement"
  advancement = "minecraft:story/smelt_iron"

[rewards]
items = ["minecraft:iron_ingot:3"]
xp_points = 25

[unlock]
toast = "The Iron Age begins!"
sound = "minecraft:ui.toast.challenge_complete"
particle = "minecraft:happy_villager"

Important design rule: do not lock the action required to earn its own stage. If mining diamond ore unlocks Diamond Age, players must still be able to mine the ore before owning Diamond Age; lock the useful diamond equipment and advanced content instead.

---

⌨️ Commands

👤 Player and inspection commands

• /stage or /stage gui — open the progression map.
• /stage list — list owned or available stages.
• /stage check — check ownership.
• /stage info — inspect a stage definition.
• /stage tree — inspect dependency relationships.
• /stage progress next — show progress toward reachable stages.
• /stage progress all — show all visible progress.
• /stage progress <stage> — inspect one stage's conditions.
• /stage simulate — dry-run reachable stages and dependency blockers.

🛡️ Administration and pack-author commands

• /pstages editor — open the in-game stage editor GUI.
• /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 new TOML stage.
• /stage export to generate a Markdown progression guide.
• /progressivestages reload for a validated live reload.
• /progressivestages validate for parsing, registry, graph, and trigger diagnostics.
• /progressivestages ftb status for FTB Quests diagnostics.

Command suggestions are generated from loaded stage IDs, tags, categories, players, and counter names where applicable.

---

📜 KubeJS scripting

When KubeJS is installed, server scripts receive a global ProgressiveStages object and players receive the first-class player.stages bridge.

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

The API also supports:

• Grant and revoke callbacks that fire for real engine changes.
• Custom boolean trigger conditions.
• Custom progress providers.
• Named counters.
• Immediate trigger evaluation.
• Dependency and dependent queries.
• Tag and category queries.
• Bulk grants and revocations.
• Definition snapshots.
• Synchronization.

Grant and revoke calls return whether ownership actually changed; bulk operations return how many stages changed.

Example custom condition:

ProgressiveStages.condition('is_rich', player => {
  return player.inventory.count('minecraft:diamond') >= 64
})

[[triggers]]
mode = "all_of"

  [[triggers.conditions]]
  type = "script"
  id = "is_rich"

---

☕ Java API

ProgressiveStagesAPI exposes ownership, definitions, dependencies, trigger progress, counters, bulk mutations, and synchronization to other mods. NeoForge events report real grants and revocations together with their causes, including commands, triggers, purchases, integrations, and regression.

Optional integrations are separated behind compatibility layers and guarded mixins, so the core mod does not require optional classes to load.

---

🔌 Optional integrations

Integration	What ProgressiveStages adds
EMI	Hide locked entries, add overlays/tooltips, and refresh immediately after stage changes.
JEI	Hide locked items/recipes and restore them immediately on unlock.
FTB Teams	Share team-scoped stages while retaining a solo fallback.
FTB Quests + FTB Library	Required-stage fields, stage tasks, rewards, and live rechecks.
KubeJS	Global scripting API, player.stages, callbacks, custom conditions, and counters.
Jade	Show the required stage while looking at a locked block or entity.
WTHIT	Show the required stage while looking at a locked block or entity.
Curios	Gate equipment slots and eject locked equipment.
Lootr	Filter each player's independent loot rolls.
Mekanism	Handle NBT-heavy variants, chemicals, and relevant automation surfaces.
Nature's Compass	Prevent searches that would bypass locked-dimension progression.
Create	Preserve correct classification for Create-driven interactions and harvesting paths.
Visual Workbench	Preserve block and crafting enforcement through replaced workbench behavior.

All integrations are optional unless the pack uses the corresponding feature.

---

📁 Configuration layout

After the first launch:

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

• progressivestages.toml contains global defaults, enforcement and performance settings, integration switches, disclosure settings, visual behavior, and customizable messages.
• stages/ contains the individual stage TOML files.
• Nested folders are supported for organizing large packs.
• The generated diamond_age.toml is a heavily commented reference covering the complete schema.
• Datapacks may provide defaults at data/<namespace>/progressivestages/stages/*.toml.
• A config-folder stage with the same ID overrides the datapack version.
• Older layouts can be migrated without overwriting an existing 3.0 target.

---

✅ Safe reloads and validation

/progressivestages reload does not partially apply broken data. It builds and validates a complete candidate snapshot first. If parsing fails, a stage ID is duplicated, the dependency graph is invalid, a registry reference is dead, or runtime application fails, the previous working snapshot remains active.

/progressivestages validate helps identify:

• TOML parsing errors.
• Duplicate stage IDs.
• Missing dependencies.
• Multi-node dependency cycles.
• Transitively unreachable stages.
• Invalid registry references.
• Dead trigger targets.
• Invalid profession IDs.
• Integration-specific configuration problems.

This makes live iteration much safer for both local pack development and running servers.

---

🧪 Beta testing and release readiness

ProgressiveStages 3.0 is presented by the project as the stable 3.0 release, but large modpacks should still test their own configuration as if it were a pack-specific beta. Every pack combines different mods, scripts, recipes, teams, and automation systems.

Recommended beta pass:

1. Run /progressivestages validate with the final mod list and datapacks.
2. Test every stage before and after grant.
3. Test every dependency branch and convergence point.
4. Test revocation, death loss, expiration, cascade, refunds, and re-grants.
5. Test purchases with insufficient, exact, and excessive resources.
6. Test a dedicated server with at least two players and separate teams.
7. Test relogging, server restart, /reload, and /progressivestages reload.
8. Test hoppers, pipes, machines, fake players, backpacks, and other automation used by the pack.
9. Test all installed recipe viewers, quest mods, overlays, and Curios slots.
10. Confirm that no trigger requires an action the same stage prevents.

Suggested release labels for a modpack using ProgressiveStages:

Phase	Purpose
Internal Alpha	Validate the graph, file structure, and main progression route.
Closed Beta	Find bypasses, dead ends, multiplayer issues, and balance problems.
Open Beta	Test real player behavior, alternative routes, automation, and performance.
Release Candidate	Freeze stage IDs and verify migration, restart, and full-pack compatibility.
Stable	Ship only after every critical path and regression case passes.

---

🚀 Performance and multiplayer safety

• Enforcement and ownership are server-authoritative.
• Relevant events recheck indexed triggers rather than scanning every condition constantly.
• Polling is reserved as a configurable safety net for state-based conditions.
• Optional categories have fast paths when unused.
• Team, server, and solo scopes are stored and evaluated independently.
• Runtime state is cleared correctly on reload and server stop.
• Stage changes synchronize locked content, map state, entities, blocks, fluids, and recipe viewers to clients.
• Purchases validate prerequisites, trigger requirements, cooldowns, and resources before spending anything.

---

📋 Requirements

• Minecraft 1.21.1.
• NeoForge 21.1 or a compatible newer 21.1 build within the declared Minecraft range.
• No mandatory quest, team, scripting, recipe-viewer, equipment, or overlay mod.

---

📦 Installation

1. Install NeoForge for Minecraft 1.21.1.
2. Place the ProgressiveStages jar in mods/ on the client and server.
3. Install any optional integrations your pack needs.
4. Launch once to generate the main configuration and example stages.
5. Create or edit files under config/progressivestages/stages/.
6. Run /progressivestages validate.
7. Apply changes with /progressivestages reload or restart the server.

---

📚 Documentation and support

• Beginner Guide
• Complete Documentation
• Fully Commented Diamond Stage
• Beginner Example Pack
• Architecture and Project Structure
• Testing Handbook
• CurseForge
• Discord Community
• Bug Reports and Feature Requests

---

❤️ The complete progression framework

ProgressiveStages gives modpack authors a single, deeply customizable, server-safe system for building, enforcing, automating, rewarding, scripting, displaying, testing, and evolving virtually any kind of Minecraft progression.