Перейти к содержимому
Mineforgian

ProgressiveStages

Fully customizable progressive stages for Minecraft with FTB Quests/KubeJS/JEI integration.

Загрузки
2K
Подписчики
16
Обновлён
11 августа 2026 г.
Лицензия
All-Rights-Reserved

Опубликован 4 февраля 2026 г.

Исходный код

ProgressiveStages 3.0

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

Minecraft NeoForge CurseForge Modrinth Discord

✨ 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

❤️ 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.

Ченджлог

3.0.3Релиз1.21.1 · 11 августа 2026 г.

ProgressiveStages 3.0.3

ProgressiveStages 3.0.3 improves enchantment control, polishes the in game progression map, and closes several enforcement and rendering gaps found during 3.0 testing.

Highlights

  • Stage aware enchantment generation. [enchants].max_levels and [enchants].selection_weights now shape enchanting table choices and player aware enchanted loot before enchantments are applied. Set a maximum level to cap retained and generated levels. Set a maximum of zero to remove the enchantment. Set a selection weight of zero to prevent new rolls without stripping existing items. The normal enchantment strip remains a final safety net.
  • Easy builder enchantment controls. The localhost editor exposes maximum levels and selection weights in the Rules tab. Search the live server registry, choose an exact enchantment, and edit either control without touching TOML.
  • Progression map polish. The in game advancement style map has clearer stage names, better spacing, shorter dividers, structured equipment and affinity previews, exact item icons, cycling tag icons, focused branch highlighting, and a more compact inspector.
  • Vanilla style inventory entry point. The progression button uses a parchment map emblem and matching vanilla button states with a wider default gap from the recipe book button. Existing settings for visibility, position, button size, and icon size remain supported.

Fixes

  • The open category list now renders above every stage frame and item icon. Nodes positioned under the list can no longer bleed through the menu.
  • Smithing upgrades now enforce locked recipe identifiers, recipe outputs, result items, and transitive ingredients. Result pickup is rejected on the server even if another mod redraws the smithing output.
  • Structure aware entity rules now read an immutable session snapshot during asynchronous chunk generation. Ocean ruins and similar structures no longer access server thread only session state from a chunk worker.
  • The localhost editor no longer shows the redundant Arrange and save button. Dragging still stores individual coordinates, Use automatic layout still removes manual coordinates, and Apply changes remains the single publication flow.

Compatibility

  • Minecraft 1.21.1.
  • NeoForge 21.1.219.
  • Java 21.
  • Client and server installation required.
  • Existing 3.0 stage files and configuration remain compatible. No migration is required.

Verification

The release passed the React test and production build, the complete Java test and Gradle build, dedicated server startup, virtual display client startup, browser verification of the localhost editor, transformed mixin target loading, and final JAR inspection. The reported smithing and progression menu cases were also confirmed in game before release approval.

3.0.2Релиз1.21.1 · 24 июля 2026 г.

ProgressiveStages — Full Changelog (2.0 → 3.0.2)

Everything since the 2.0 rewrite, version by version. All of it is additive and config-driven; old TOML keeps working.

3.0.2. Editor access and inventory button controls

  • /pstages editor now opens correctly for permission level 3 operators in integrated single-player worlds as well as dedicated servers.
  • Authenticated loopback access remains private. Remote hosts, origins, ports, and incorrect session secrets are rejected.
  • The editor now uses a simpler dark gray and gold stage-first layout with less visual clutter.
  • The survival inventory progression button can be removed with client.show_inventory_button = false.
  • client.inventory_button_x and client.inventory_button_y move the button relative to the inventory.
  • client.inventory_button_width, client.inventory_button_height, and client.inventory_button_icon_size control its size and centered lock icon.
  • Commands and the optional keybind continue to open the progression map when the inventory button is hidden.

3.0.1. Schema 4 and authoring rehaul

  • Three file stage packages with stage.toml, rules.toml, and progression.toml, while untouched one file stages remain compatible.
  • A private dedicated server editor opened by /pstages editor. The operator client hosts a temporary authenticated loopback page, so the server exposes no web port.
  • Server authoritative registry, tag, recipe, advancement, loot resource, stage, KubeJS, and extension autocomplete with paging and revision safety.
  • Deterministic per entry priority, local exclusions, global allows, condition driven temporary rules, and independent EMI and JEI presentation.
  • One condition language for grant, revoke, temporary locks, modifiers, challenges, and simulation.
  • Persistent rolling health, damage, death, hit, lifecycle, temporary rule, challenge, variable, state, and history data.
  • Contextual equipment modifiers, affinity and proficiency profiles, variables, formulas, templates, multi state stages, atomic action pipelines, and generic challenge budgets.
  • Revisioned compressed compiled client snapshots for connected and future clients.
  • Expanded /pstages, Java, and KubeJS APIs with explain, simulation, history, lifecycle, challenge, migration, catalog, editor metadata, and rollback surfaces.
  • The stage screen now includes the why panel, active challenges, equipment preview, and progress history while retaining advancement style drag and scroll behavior.
  • A packaged Preact and TypeScript editor shell, seven compiled example packages, comprehensive schema 4 guide, migration flow, and release verification records.

🧱 2.0 / 2.0.1 — The rewrite

The foundation everything else builds on.

  • Per-team stage storage (FTB Teams or solo) — stages are a team property, not per-player.
  • Unified prefix lock system — one syntax everywhere: id: / mod: / tag: (#) / name: patterns, plus minecraft = true for the whole vanilla namespace.
  • Multi-stage gating — a single thing can require several stages at once (AND), enabling true dependency graphs.
  • Lock surfaces: items, blocks, fluids, entities, enchants, crops, screens/GUIs, loot, trades, pets (taming/breeding/commanding/riding), mob spawns + dynamic replacements, recipes (by id or by output), dimensions, [[regions]] (3D boxes with flags), [[interactions]] (item-on-block/entity).
  • Ore-spoof masquerade — locked ores render + drop as a decoy block until unlocked (chunk-packet rewrite, break-speed/harvest sync).
  • Transitive & automated crafting gating — block crafting with locked ingredients; gate vanilla Crafters via a nearest-player check.
  • Recipe-viewer integration — EMI/JEI hide locked items/recipes; per-stage [unlocks] carve-outs; always_unlocked whitelists.
  • Soft-dep compat — FTB Quests/Teams, Curios (per-slot gating), Lootr (per-player chests), Nature's Compass, Mekanism.
  • Fully &-color-configurable messages; reveal-locked-names-to-ops; creative-bypass warning.

🎯 2.3 — Per-stage triggers, GUI codex, fine-grained enforcement

  • Per-stage [[triggers]] — auto-grant a stage when conditions are met, declared right in the stage file (replaces the old global triggers.toml). Rules OR together; conditions combine by mode (all_of/any_of). Counters read vanilla stats, so they're retroactive and restart-proof.
  • Triggers respect dependencies — won't fire until prerequisites are owned (omit the dependency to let them fire freely).
  • In-game GUI codex — view-only stage tree: icons, descriptions, "Requires ALL of", "Leads to" branches, % to unlock with a live condition breakdown, and an "Unlocks" item grid. Handles linear / branching / multi-dependency / parallel trees.
  • Per-stage [enforcement] overrides — flip any global enforcement toggle for the resources one stage gates.
  • Per-stage [display] — mask locked item names (???), obscure icons (?), toggle tooltips/description per stage.
  • /stage progress (+ next / all) — per-trigger progress breakdown. EMI whitelist fix (whitelisted Create items now show).

🧬 2.4 — Power-ups, skill tree, juice

  • [attribute] — modify player attributes (max health, speed, scale, anything) while a stage is owned.
  • [revoke] / regression — lose a stage on_death, or hold it only while xp_below a threshold; optional cascade to dependents.
  • Temporary stages — duration = "30m": real-time expiry that counts down even while offline.
  • Server-wide stages — scope = "server": the first team to earn it unlocks it for everyone.
  • Skill-tree [cost] — make a stage buyable from the tree with xp_levels and/or items; server-validated + consumed; optional bypass_requirements to pay-to-skip the grind.
  • Unlock juice (all optional) — [unlock] toast / title / subtitle / sound / particles, 50/75/90% progress nudges, and a custom blue HUD progress bar above the XP bar (not the boss bar).
  • [abilities] — gate elytra gliding behind a stage.
  • 7 new triggers: effect, breed, day_count, weather, enter_structure, tame, kill_with.

🔒 2.5 — More gating surfaces + deep KubeJS

  • [professions] — gate a villager's whole trade GUI by its profession.
  • [advancements] — hide locked advancements from the advancements screen entirely (server-side); they reappear when the stage is gained.
  • [structures] improvements — auto-sized bounding boxes, entry_padding buffer, and bounce-back to your last safe spot.
  • Deep KubeJS — a ProgressiveStages script object: onGranted / onRevoked (fire on every engine grant), condition(id, predicate) for custom script triggers, and has / grant / revoke / list / percent.
  • Datapack-loaded stages — ship stage TOML inside a datapack (data/<ns>/progressivestages/stages/*.toml); config files override on conflict.
  • [stage] metadata in the GUI — hidden / color (#RRGGBB) / category now actually drive the tree.
  • Deeper /stage validate — detects full multi-node dependency cycles, unreachable stages, and dead trigger/dependency targets.
  • More triggers: world_time, per-species/#tag breed, #tag-victim kill_with, and script. Attribute modifiers re-applied on respawn.

🚀 3.0 — The big expansion

  • Jade and WTHIT overlays — looking at a locked block or mob shows "🔒 Requires: ". Both pulled from the Modrinth Maven (not bundled jars). Entity locks are now synced to the client.

  • 6 new triggers — reach_y, fish, sleep, ride, biome_time, and stage_held_for (time-since-grant, for time-gated chains).

  • [rewards] on grant — items / status effects / commands / teleport / xp the moment a stage unlocks (the companion to [cost]). Applied once to the player who earned it.

  • Stage tags + bulk ops — [stage] tags = [...] + /stage tag grant|revoke|list <players> <tag>.

  • [cost] cooldown + refund — per-player purchase rate-limit; refund_percent returns part of the cost on revoke (only for stages actually purchased).

  • Ability expansion — [abilities] now also gates sprint, swim, climb.

  • Authoring tools — /stage simulate (dry-run: what's next and exactly which conditions are short), /stage new (scaffold a stage file), /stage export (markdown progression guide).

  • Encrypted-block visual — [display].encrypt_blocks masquerades a stage's locked blocks as a placeholder until owned (per-stage on/off).

  • Comprehensive reference — the default diamond_age.toml now has a worked example for every trigger type and every feature.

  • Vanilla advancement-style progression map — framed nodes, dependency connectors, tiled/custom backgrounds, drag + wheel + keyboard panning, rich hover cards, search/filtering, pinned details, and purchases.

  • Per-stage map authoring — [display] now accepts x, y, frame, background, reveal, and sort_order, with automatic DAG layout when coordinates are omitted.

  • Named custom counters — declarative custom_counter triggers, command management, and KubeJS counter helpers.

  • Commands and scripting expanded — public /stage//stages//ps map aliases; actual-change script results; toggle, availability, dependency, tag, counter, evaluation, and GUI helpers.

  • Engine repair pass — correct per-stage exemptions/carve-outs, multistage secondary gates, mixed server/team scope, lifecycle cleanup, exact biome timing, and dedicated-client block/fluid/mod synchronization.

  • Build health — optional APIs now resolve from publisher Maven repositories and unit tests run in the standard build.

🧭 3.0.1 — Exact structure sessions and contextual rules

  • Generic provider API — companion mods register exact structure assignment providers through a one-way dependency. ProgressiveStages core imports no companion API.
  • Exact-instance arbitration — static gates remain authoritative; provider denial wins; permits cannot bypass a missing normal stage; cached claimed bounds fail closed on provider errors.
  • Committed sessions — debounced enters and exits, stable visit sequences, idempotent completion, immutable events, and typed incomplete/completed/death/teleport/dimension/disconnect/recovery outcomes.
  • Team-safe leases — in-progress stages grant on the first lease, survive additional participants, revoke on the final release only when the lease introduced them, and preserve pre-owned stages.
  • Contextual active locks — [active_locks] uses the unified item selector grammar and opposite present-in-context polarity, affecting item use only inside a matching structure session.
  • Event-driven leave_structure trigger — exact structure or tag, optional provider and session-stage filters, typed outcomes, and repeatable visits without permanent one-shot storage.
  • Java and operator tooling — structure registration/completion/reconciliation APIs, detailed item-use decisions, four lifecycle events, three structure stage causes, and /pstages structure diagnostics.

Old TOML files are forward-compatible across all of the above — every addition is opt-in.

3.0.2Релиз1.21.1 · 23 июля 2026 г.

ProgressiveStages — Full Changelog (2.0 → 3.0.2)

Everything since the 2.0 rewrite, version by version. All of it is additive and config-driven; old TOML keeps working.

3.0.2. Editor access and inventory button controls

  • /pstages editor now opens correctly for permission level 3 operators in integrated single-player worlds as well as dedicated servers.
  • Authenticated loopback access remains private. Remote hosts, origins, ports, and incorrect session secrets are rejected.
  • The editor now uses a simpler dark gray and gold stage-first layout with less visual clutter.
  • The survival inventory progression button can be removed with client.show_inventory_button = false.
  • client.inventory_button_x and client.inventory_button_y move the button relative to the inventory.
  • client.inventory_button_width, client.inventory_button_height, and client.inventory_button_icon_size control its size and centered lock icon.
  • Commands and the optional keybind continue to open the progression map when the inventory button is hidden.

3.0.1. Schema 4 and authoring rehaul

  • Three file stage packages with stage.toml, rules.toml, and progression.toml, while untouched one file stages remain compatible.
  • A private dedicated server editor opened by /pstages editor. The operator client hosts a temporary authenticated loopback page, so the server exposes no web port.
  • Server authoritative registry, tag, recipe, advancement, loot resource, stage, KubeJS, and extension autocomplete with paging and revision safety.
  • Deterministic per entry priority, local exclusions, global allows, condition driven temporary rules, and independent EMI and JEI presentation.
  • One condition language for grant, revoke, temporary locks, modifiers, challenges, and simulation.
  • Persistent rolling health, damage, death, hit, lifecycle, temporary rule, challenge, variable, state, and history data.
  • Contextual equipment modifiers, affinity and proficiency profiles, variables, formulas, templates, multi state stages, atomic action pipelines, and generic challenge budgets.
  • Revisioned compressed compiled client snapshots for connected and future clients.
  • Expanded /pstages, Java, and KubeJS APIs with explain, simulation, history, lifecycle, challenge, migration, catalog, editor metadata, and rollback surfaces.
  • The stage screen now includes the why panel, active challenges, equipment preview, and progress history while retaining advancement style drag and scroll behavior.
  • A packaged Preact and TypeScript editor shell, seven compiled example packages, comprehensive schema 4 guide, migration flow, and release verification records.

🧱 2.0 / 2.0.1 — The rewrite

The foundation everything else builds on.

  • Per-team stage storage (FTB Teams or solo) — stages are a team property, not per-player.
  • Unified prefix lock system — one syntax everywhere: id: / mod: / tag: (#) / name: patterns, plus minecraft = true for the whole vanilla namespace.
  • Multi-stage gating — a single thing can require several stages at once (AND), enabling true dependency graphs.
  • Lock surfaces: items, blocks, fluids, entities, enchants, crops, screens/GUIs, loot, trades, pets (taming/breeding/commanding/riding), mob spawns + dynamic replacements, recipes (by id or by output), dimensions, [[regions]] (3D boxes with flags), [[interactions]] (item-on-block/entity).
  • Ore-spoof masquerade — locked ores render + drop as a decoy block until unlocked (chunk-packet rewrite, break-speed/harvest sync).
  • Transitive & automated crafting gating — block crafting with locked ingredients; gate vanilla Crafters via a nearest-player check.
  • Recipe-viewer integration — EMI/JEI hide locked items/recipes; per-stage [unlocks] carve-outs; always_unlocked whitelists.
  • Soft-dep compat — FTB Quests/Teams, Curios (per-slot gating), Lootr (per-player chests), Nature's Compass, Mekanism.
  • Fully &-color-configurable messages; reveal-locked-names-to-ops; creative-bypass warning.

🎯 2.3 — Per-stage triggers, GUI codex, fine-grained enforcement

  • Per-stage [[triggers]] — auto-grant a stage when conditions are met, declared right in the stage file (replaces the old global triggers.toml). Rules OR together; conditions combine by mode (all_of/any_of). Counters read vanilla stats, so they're retroactive and restart-proof.
  • Triggers respect dependencies — won't fire until prerequisites are owned (omit the dependency to let them fire freely).
  • In-game GUI codex — view-only stage tree: icons, descriptions, "Requires ALL of", "Leads to" branches, % to unlock with a live condition breakdown, and an "Unlocks" item grid. Handles linear / branching / multi-dependency / parallel trees.
  • Per-stage [enforcement] overrides — flip any global enforcement toggle for the resources one stage gates.
  • Per-stage [display] — mask locked item names (???), obscure icons (?), toggle tooltips/description per stage.
  • /stage progress (+ next / all) — per-trigger progress breakdown. EMI whitelist fix (whitelisted Create items now show).

🧬 2.4 — Power-ups, skill tree, juice

  • [attribute] — modify player attributes (max health, speed, scale, anything) while a stage is owned.
  • [revoke] / regression — lose a stage on_death, or hold it only while xp_below a threshold; optional cascade to dependents.
  • Temporary stages — duration = "30m": real-time expiry that counts down even while offline.
  • Server-wide stages — scope = "server": the first team to earn it unlocks it for everyone.
  • Skill-tree [cost] — make a stage buyable from the tree with xp_levels and/or items; server-validated + consumed; optional bypass_requirements to pay-to-skip the grind.
  • Unlock juice (all optional) — [unlock] toast / title / subtitle / sound / particles, 50/75/90% progress nudges, and a custom blue HUD progress bar above the XP bar (not the boss bar).
  • [abilities] — gate elytra gliding behind a stage.
  • 7 new triggers: effect, breed, day_count, weather, enter_structure, tame, kill_with.

🔒 2.5 — More gating surfaces + deep KubeJS

  • [professions] — gate a villager's whole trade GUI by its profession.
  • [advancements] — hide locked advancements from the advancements screen entirely (server-side); they reappear when the stage is gained.
  • [structures] improvements — auto-sized bounding boxes, entry_padding buffer, and bounce-back to your last safe spot.
  • Deep KubeJS — a ProgressiveStages script object: onGranted / onRevoked (fire on every engine grant), condition(id, predicate) for custom script triggers, and has / grant / revoke / list / percent.
  • Datapack-loaded stages — ship stage TOML inside a datapack (data/<ns>/progressivestages/stages/*.toml); config files override on conflict.
  • [stage] metadata in the GUI — hidden / color (#RRGGBB) / category now actually drive the tree.
  • Deeper /stage validate — detects full multi-node dependency cycles, unreachable stages, and dead trigger/dependency targets.
  • More triggers: world_time, per-species/#tag breed, #tag-victim kill_with, and script. Attribute modifiers re-applied on respawn.

🚀 3.0 — The big expansion

  • Jade and WTHIT overlays — looking at a locked block or mob shows "🔒 Requires: ". Both pulled from the Modrinth Maven (not bundled jars). Entity locks are now synced to the client.

  • 6 new triggers — reach_y, fish, sleep, ride, biome_time, and stage_held_for (time-since-grant, for time-gated chains).

  • [rewards] on grant — items / status effects / commands / teleport / xp the moment a stage unlocks (the companion to [cost]). Applied once to the player who earned it.

  • Stage tags + bulk ops — [stage] tags = [...] + /stage tag grant|revoke|list <players> <tag>.

  • [cost] cooldown + refund — per-player purchase rate-limit; refund_percent returns part of the cost on revoke (only for stages actually purchased).

  • Ability expansion — [abilities] now also gates sprint, swim, climb.

  • Authoring tools — /stage simulate (dry-run: what's next and exactly which conditions are short), /stage new (scaffold a stage file), /stage export (markdown progression guide).

  • Encrypted-block visual — [display].encrypt_blocks masquerades a stage's locked blocks as a placeholder until owned (per-stage on/off).

  • Comprehensive reference — the default diamond_age.toml now has a worked example for every trigger type and every feature.

  • Vanilla advancement-style progression map — framed nodes, dependency connectors, tiled/custom backgrounds, drag + wheel + keyboard panning, rich hover cards, search/filtering, pinned details, and purchases.

  • Per-stage map authoring — [display] now accepts x, y, frame, background, reveal, and sort_order, with automatic DAG layout when coordinates are omitted.

  • Named custom counters — declarative custom_counter triggers, command management, and KubeJS counter helpers.

  • Commands and scripting expanded — public /stage//stages//ps map aliases; actual-change script results; toggle, availability, dependency, tag, counter, evaluation, and GUI helpers.

  • Engine repair pass — correct per-stage exemptions/carve-outs, multistage secondary gates, mixed server/team scope, lifecycle cleanup, exact biome timing, and dedicated-client block/fluid/mod synchronization.

  • Build health — optional APIs now resolve from publisher Maven repositories and unit tests run in the standard build.

🧭 3.0.1 — Exact structure sessions and contextual rules

  • Generic provider API — companion mods register exact structure assignment providers through a one-way dependency. ProgressiveStages core imports no companion API.
  • Exact-instance arbitration — static gates remain authoritative; provider denial wins; permits cannot bypass a missing normal stage; cached claimed bounds fail closed on provider errors.
  • Committed sessions — debounced enters and exits, stable visit sequences, idempotent completion, immutable events, and typed incomplete/completed/death/teleport/dimension/disconnect/recovery outcomes.
  • Team-safe leases — in-progress stages grant on the first lease, survive additional participants, revoke on the final release only when the lease introduced them, and preserve pre-owned stages.
  • Contextual active locks — [active_locks] uses the unified item selector grammar and opposite present-in-context polarity, affecting item use only inside a matching structure session.
  • Event-driven leave_structure trigger — exact structure or tag, optional provider and session-stage filters, typed outcomes, and repeatable visits without permanent one-shot storage.
  • Java and operator tooling — structure registration/completion/reconciliation APIs, detailed item-use decisions, four lifecycle events, three structure stage causes, and /pstages structure diagnostics.

Old TOML files are forward-compatible across all of the above — every addition is opt-in.

1.3Релиз1.21.9, 1.21.10, 1.21.11 · 13 марта 2026 г.

🔧 Config

Config file renamed: progressivestages-common.toml → progressivestages.toml 🛡️ New Enforcement Options (in progressivestages.toml)

block_item_hotbar — moves locked items out of the hotbar into inventory instead of dropping them block_item_mouse_pickup — prevents clicking locked items in GUIs (but lets players store them in chests) Left-clicking and mining with a locked tool is now properly blocked Attacking with a locked weapon is now properly blocked 🔒 Recipe-Only Locks (in stage TOML [locks])

New recipe_items = ["minecraft:diamond_pickaxe"] — locks crafting without locking the item itself Players can still pick up, hold, and use items found in loot — they just can't craft them EMI hides the recipe; item stays visible in the index Tooltip shows "🔒 Recipe Locked", "🔒 Item Locked", or "🔒 Item and Recipe Locked" as appropriate ⚙️ Per-Stage Enforcement Exceptions (new [enforcement] section in stage TOML)

Five new lists per stage: allowed_use, allowed_pickup, allowed_hotbar, allowed_mouse_pickup, allowed_inventory Accepts item IDs, tags (#c:gems/diamond), or whole mod IDs (mekanism) Lets specific items bypass individual enforcement rules even while still locked

Комментарии

Загружаем…