Restage

Restage is a stage-based progression mod for Minecraft 1.21.1 (NeoForge) that lets pack authors gate recipes, dimensions, and item handling behind per-player stages. Stages are unlocked through configurable conditions — crafting, killing mobs, earning advancements, or manually submitting items — and the entire system is configurable live in-game through a polished ModernUI interface, no restart required.

---

Features at a glance

• Recipe blocking — hide and block crafting by mod, recipe ID, regex pattern, or output item
• Dimension blocking — prevent players from entering dimensions until a stage is unlocked
• Automatic unlock conditions — kills, crafting, advancements
• Manual unlock — require players to submit specific items in-game
• Item restrictions — fine-grained control over pickup, inventory, equip, right-click, left-click, and attack per item, item tag, or mod
• Custom coloured messages — per-rule rich-text feedback for every restriction action
• In-game GUI — live configuration editor with no restart needed (opens with a keybind or /restage gui)
• KubeJS API — full scripting API for pack authors who prefer code
• JEI integration — blocked recipes are hidden or annotated in JEI
• Create mod integration — basin, crushing wheel, deployer, mechanical press, millstone, and saw all respect recipe stages

---

Rule types

Recipe Rules

Type	What it blocks
Mod Rule	All recipes belonging to a mod namespace, with optional exceptions
Recipe ID	A single recipe by its full resource location
Regex Rule	All recipes whose ID matches a regex pattern, with optional exceptions
Output Rule	All recipes that produce a specific item

Dimension Rules

Block access to an entire dimension until the player holds the required stage.

Unlock Conditions

Type	Trigger
Item Condition	Player manually submits items (consumed on unlock)
Kill Condition	Player kills N entities of a specific type
Craft Condition	Player crafts N of a specific item
Advancement Condition	Player earns a specific advancement

Item Restrictions

Restrict one or more interactions with items matched by item ID, item tag, or mod namespace:

Flag	Description
Pickup	Prevent picking up from the ground
Inventory	Eject from inventory if present
Equip	Prevent equipping in armour slots
Right-click	Prevent right-click use
Left-click	Prevent left-click use
Attack	Prevent using as a melee weapon

Each restriction supports custom rich-text messages with per-segment colour picking for all three message slots (pickup, inventory, usage).

---

In-game configuration GUI

Open with the keybind (default: unbound) or /restage gui (requires permission level 2).

The GUI is built on ModernUI and requires no server restart — changes are saved and applied instantly across all connected players.

Main screen — lists every configured stage as a card showing rule/condition/restriction counts per category. Create, edit, or delete stages with inline confirmation dialogs.

Stage editor — sidebar with an editable stage name field and three category tabs (Rules · Conditions · Restrictions). The right panel lists all rules in the selected category with Edit and Delete per row.

Rule editor — sidebar type selector, autocomplete for all IDs (mod, item, recipe, entity, advancement, dimension, tag), optional exceptions list, count field for conditions, restriction flag checkboxes, and rich-text message composer.

All deletions require inline confirmation. Cancelling with unsaved changes prompts before discarding.

---

Commands

All commands require permission level 2 (operator), except reload which requires level 4.

/restage add <player> <stage>       — add a stage without the unlock animation
/restage grant <player> <stage>     — add a stage with the title/subtitle notification
/restage remove <player> <stage>    — remove a specific stage from a player
/restage removeall <player>         — remove all stages from a player
/restage info [player]              — show which stages a player currently holds
/restage list                       — list all players and their stages
/restage rules                      — dump currently loaded rules to chat
/restage gui                        — open the live configuration GUI
/restage reload                     — reload rules from config and re-sync all players

Tab-completion is available for stage names on all relevant commands.

---

KubeJS API

Restage exposes a full server-side KubeJS event for pack authors who prefer scripts over the GUI. Rules added via KubeJS are merged with GUI-configured rules at load time.

RestageEvents.addStageRules(event => {

    // Block all Thermal Expansion recipes until "thermal_unlock" stage
    event.addModRule("thermal_unlock", "thermal")

    // Block all Create recipes except the hand-crank
    event.addModRule("create_basic", "create", "create:hand_crank")

    // Block a single recipe by ID
    event.addIdRule("nether_access", "minecraft:nether_star")

    // Block all recipes matching a regex
    event.addRegexRule("end_stage", "minecraft:.*_sword")

    // Block all recipes that produce netherite ingots
    event.addOutputRule("netherite_tier", "minecraft:netherite_ingot")

    // Block the Nether dimension
    event.addDimensionRule("nether_access", "minecraft:the_nether")

    // Add a stage dependency fro another stage
    event.addStagePrerequisite("stage_b", "stage_a");

    // Unlock "nether_access" by submitting 3 blaze rods
    event.addItemCondition("nether_access", "minecraft:blaze_rod", 3)

    // Unlock "hunter" stage by killing 10 zombies
    event.addKillCondition("hunter", "minecraft:zombie", 10)

    // Unlock "crafter" stage by crafting 5 pistons
    event.addCraftCondition("crafter", "minecraft:piston", 5)

    // Unlock "explorer" stage via an advancement
    event.addAdvancementCondition("explorer", "minecraft:story/enter_the_nether")

    // Restrict netherite sword until "netherite_tier" stage
    let r = event.addItemRestriction("netherite_tier", "minecraft:netherite_sword")
    r.setCanPickedUp(false)
    r.setCanBeEquipped(false)
    r.setCanAttack(false)

    // Restrict all items in a tag
    event.addTagRestriction("end_stage", "minecraft:swords")

    // Restrict all items from a mod
    event.addModItemRestriction("thermal_unlock", "thermal")
})

The GUI automatically exports its current configuration to kubejs/server_scripts/restage_generated.js every time you save, so you can inspect or version-control the generated rules.

---

Configuration

config/restage-server.toml — server-side config with all rule lists and notification messages.

[stages]
  notifyOnBlock = true

  grantTitle    = "§a§lStage Unlocked!"
  grantSubtitle = "§f%s"
  grantChatMsg  = "§a[Stages] §fStage §e%s§f unlocked!"

  machineBlockedMsg = "§c[Stages] §fThis machine can't work: recipe blocked by a stage."
  craftBlockedMsg   = "§c[Stages] §fYou don't have stage §e%s§f to craft this."

  itemRestrictPickupMsg    = "§c[Stages] §fCan't pick up this item: stage §e%s§f required."
  itemRestrictInventoryMsg = "§c[Stages] §fItem removed from inventory: stage §e%s§f required."
  itemRestrictEquipMsg     = "§c[Stages] §fCan't equip this item: stage §e%s§f required."
  itemRestrictUseMsg       = "§c[Stages] §fCan't use this item: stage §e%s§f required."
  itemRestrictAttackMsg    = "§c[Stages] §fCan't attack with this item: stage §e%s§f required."

  uiOutputPath = "kubejs/server_scripts/restage_generated.js"

---

Dependencies

Mod	Required	Notes
NeoForge 21.1.x	✅ Required
ModernUI	✅ Required	Powers the in-game config GUI
KubeJS	⚪ Optional	Enables the scripting API
JEI	⚪ Optional	Recipe visibility integration
Create	⚪ Optional	Machine stage enforcement

---

Roadmap

✅ Implemented (v1.0.x)

• Per-player stage system with server-side persistence
• Recipe blocking: mod, ID, regex, output-item
• Dimension blocking
• Unlock conditions: item submission, kill, craft, advancement
• Item restrictions with 6 interaction flags and custom rich-text messages
• Live in-game configuration GUI (ModernUI)
• KubeJS scripting API with automatic JS export
• JEI recipe visibility integration
• Create mod machine integration (basin, crushing wheel, deployer, mechanical press, millstone, saw, furnace)
• Full command suite with tab-completion
• Stage prerequisites — require one or more stages before another can be unlocked, creating dependency chains and a proper progression tree

🔜 Planned

• Stage groups (AND / OR logic) — define a stage that unlocks when any or all stages in a group are present, enabling branching progression
• Global (server-wide) stages — stages shared by all players on the server, unlocked when any player meets the condition
• Team / party stages — share progress with players in the same team or party; unlocking a stage for one member grants it to all
• JSON import / export — export the full stage configuration to a portable JSON file and import it on another server or modpack
• Visual progression map — in-game GUI panel showing a graphical tree of stages and their unlock dependencies
• BossBar / ActionBar notifications — additional notification channels beyond chat and title/subtitle on stage unlock
• Location-based conditions — unlock a stage by visiting a specific biome, structure, or coordinate range
• WTHIT / The One Probe integration — show required stage when looking at a blocked machine or item

---

Restage is licensed All Rights Reserved. Issues and suggestions are welcome on the project page.