OtherStages

OtherStages is a configurable stage-based progression system for Minecraft Forge 1.20.1.

It lets you lock content behind custom stages and unlock those stages through configurable progression rules. The same stage metadata also drives the in-game unlock overlay, item tooltips, and several warning systems.

What the mod supports

Block specific items, item namespaces, item tags, and NBT-sensitive item variants.
Apply item restrictions to use, placement, attacks, mining, player crafting results, smithing/anvil operations, stonecutting, furnace-like manual recipe insertion, loot rolls, and directly usable equipment slots.
Block mobs, structures, dimensions, and villager trade levels.
Show a stage unlock overlay using each stage's display_name, description, icon, and color.
Show tooltip warnings on blocked items.
Warn and optionally teleport players away from restricted dimensions.
Detect blocked structures in real time and stop interaction, breaking, placing, and attacking inside them.
Hide blocked items in JEI or REI when those mods are installed.
Unlock stages through advancements, item counts, experience, dimensions, kill counts, craft counts, FTB Quests, and nested AND / OR logic.
Generate JSON snippets from storage blocks with the otherstages:stage_analyzer item.

Important behavior

A stage folder name is the internal stage ID. It can be anything, such as machine_age, arcane_tier, or chapter_03.
stage_info.json is required for every stage. The other JSON files are optional.
Stage order matters. If a player has a stage with a higher order, that player also satisfies restrictions from lower-order stages.
Keep order values unique and increasing if you want a clean linear progression.
Example stage folders are created automatically on first launch. They are only examples; you can rename or delete them.

Folder layout

On first launch the mod creates config files in:

config/
  otherstages-server.toml
  otherstages/
    stages/
      <stage_name>/
        stage_info.json
        blocked_items.json
        blocked_mobs.json
        blocked_structures.json
        blocked_dimensions.json
        blocked_villager_trades.json
        progression.json
    generated/

config/otherstages/generated/ is used by the Stage Analyzer item.

stage_info.json

This file defines the stage identity and the metadata shown to the player.

Supported fields

Field	Required	Type	Notes
`display_name`	No	string	Shown in commands, messages, and unlock overlay. Falls back to a formatted version of the folder name.
`description`	No	string	Optional subtitle/description used by the unlock overlay and stage info output.
`color`	No	string	Hex color in `#RRGGBB` format. Used to tint the unlock overlay.
`icon`	No	string	Item ID such as `minecraft:diamond_pickaxe`. Used in the unlock overlay.
`order`	No	integer	Controls progression hierarchy. Higher order means higher stage.

Translation-aware strings

If display_name or description starts with otherstages., it is treated as a translation key. Otherwise it is shown as plain text.

Example

{
  "display_name": "Machine Age",
  "description": "Basic automation is now available.",
  "color": "#4FC3F7",
  "icon": "minecraft:observer",
  "order": 3
}

Optional per-stage files

blocked_items.json

Used to block direct item IDs, item namespaces, NBT variants, tags, menu-based access rules, and interaction-driven block targets tied to the same stage.

Supported keys:

blocked_items
blocked_namespaces
blocked_tags
tagList as a legacy alias for blocked_tags
blocked_recipes
blocked_menu_classes
blocked_menu_packages
blocked_menu_types
blocked_block_ids
blocked_block_classes
blocked_block_entity_classes
blocked_block_entity_packages

Each blocked_items entry supports:

item
optional nbt
optional exact_match

Example:

{
  "blocked_items": [
    { "item": "minecraft:diamond_pickaxe" },
    {
      "item": "minecraft:potion",
      "nbt": { "Potion": "minecraft:strong_healing" },
      "exact_match": false
    }
  ],
  "blocked_namespaces": [
    "create"
  ],
  "blocked_tags": [
    "forge:tools/netherite"
  ],
  "blocked_recipes": [
    "minecraft:iron_pickaxe",
    "minecraft:netherite_upgrade_smithing"
  ],
  "blocked_menu_packages": [
    "appeng",
    "com.refinedmods.refinedstorage"
  ],
  "blocked_menu_types": [
    "minecraft:anvil",
    "minecraft:smithing"
  ],
  "blocked_block_ids": [
    "create:mechanical_crafter"
  ],
  "blocked_block_entity_packages": [
    "com.simibubi.create.content.kinetics.crafter"
  ]
}

Namespace matches are exact. create blocks create:*, but it does not block createaddition:*.

blocked_recipes matches recipe ids and is currently enforced for the player crafting grid, crafting table, smithing menu, stonecutter, and manual ingredient insertion into furnace-like menus.

blocked_menu_classes matches an exact menu class name. blocked_menu_packages matches any menu class whose fully-qualified name starts with the configured prefix. blocked_menu_types matches the registered MenuType id when one exists.

blocked_block_ids matches the placed block id itself, such as create:mechanical_crafter. blocked_block_classes matches the runtime block class. blocked_block_entity_classes and blocked_block_entity_packages are for interaction-driven machines that expose a block entity but not a normal menu.

Active in-game effects of blocked item rules:

Block using the item directly.
Block placing blocked blocks and using blocked tools or weapons.
Clear blocked crafting results in the player crafting grid and crafting table.
Block configured recipe ids in the player crafting grid, crafting table, smithing menu, stonecutter, and manual ingredient insertion into furnace-like menus.
Block manually inserting blocked items into non-player menu slots, including many modded tables and terminals.
Close configured blocked menus automatically when a player without the required stage opens them.
Deny interaction with configured interaction-driven blocks such as create:mechanical_crafter, even when they do not open a normal menu.
Deny smithing or anvil operations that use blocked inputs.
Block taking blocked outputs from result-like menu slots before they can be moved into directly usable player slots.
Remove blocked items from the hotbar, offhand, armor, and supported Curios slots by moving them to the main inventory or dropping them if it is full.
Prevent blocked items from running normal player inventory ticking while they stay in the main inventory.
Filter blocked items out of loot generated for that player.

OtherStages stays player-based. Automation from other mods can still create blocked items, but blocked players cannot keep them in directly usable slots, cannot use them manually, and cannot manually feed blocked recipe ingredients into many menu-driven machine screens.

blocked_mobs.json

Blocks natural spawning and nearby spawn attempts for the listed entities.

{
  "blocked_mobs": [
    "minecraft:enderman",
    "minecraft:warden"
  ]
}

blocked_structures.json

Blocks entering and interacting inside listed structures.

{
  "blocked_structures": [
    "minecraft:stronghold",
    "minecraft:ancient_city"
  ]
}

Minecraft 1.20.1 uses separate IDs for many village variants, so include each variant you want to block.

blocked_dimensions.json

Blocks travel to listed dimensions.

{
  "blocked_dimensions": [
    "minecraft:the_nether",
    "minecraft:the_end"
  ]
}

If teleportOnInvalidDimension is enabled in otherstages-server.toml, players found inside a restricted dimension can be moved back to safety on login.

If a player's respawn point is set inside a blocked dimension, the respawn target is reset to the Overworld.

blocked_villager_trades.json

Blocks villager trades by profession and level.

Supported fields per entry:

profession
level
min_level
max_level

profession accepts:

a profession ID such as minecraft:librarian
*
any
empty / null

Example:

{
  "blocked_villager_trades": [
    {
      "profession": "*",
      "min_level": 2,
      "max_level": 5
    },
    {
      "profession": "minecraft:cleric",
      "level": 1
    }
  ]
}

If a villager has both allowed and blocked trades, the trading screen opens with only the accessible offers. If nothing is accessible, the player receives a warning instead.

progression.json

Defines how a player unlocks the stage.

Supported condition types:

advancement
item_count
experience
dimension
kill_count
craft_count
ftb_quest
and
or

Example:

{
  "unlock_conditions": {
    "type": "AND",
    "conditions": [
      { "type": "advancement", "advancement": "minecraft:story/enter_the_nether" },
      { "type": "item_count", "item": "minecraft:blaze_rod", "count": 8, "consume": true },
      { "type": "dimension", "dimension": "minecraft:the_nether" }
    ]
  },
  "next_stage": "end_access"
}

next_stage is optional. It can be useful as documentation for your own stage chain, but the actual unlock logic is driven by unlock_conditions.

How progression checks run

The mod reevaluates progression automatically when useful events happen, including:

player login
player tick with cooldown
advancement completion
interaction
kills
crafting
item pickup
dimension change

You can also force a recheck with:

/otherstages check <player>

Commands

All commands are under /otherstages and require permission level 2.

Stage inspection

/otherstages stage list
/otherstages stage <stage_name> info
/otherstages player <target> info

Stage management

/otherstages player <target> add <stage>
/otherstages player <target> remove <stage>
/otherstages player <target> clear
/otherstages player <target> reset

reset now uses the defaultStartingStage value from config/otherstages-server.toml.

Progression and reload

/otherstages check <player>
/otherstages reload
/otherstages cache clear
/otherstages cache info

cache info prints current item cache entries, tracked players, hits, misses, invalidations, and hit rate.

Debug helpers

/otherstages debug item
/otherstages debug menu
/otherstages debug block
/otherstages debug stages
/otherstages dimension check <player> <dimension>
/otherstages dimension list <player>

debug menu prints the current open menu when one exists, or the last remembered non-player menu after you close it. It shows the class, package, registered menu type, whether the current player is blocked from it, the required stage when applicable, and copy-ready blocked_menu_* snippets. It also suggests which key is usually the best fit for the current screen.

debug block inspects the block you are looking at. It is useful for systems like Create where interaction can be block-driven instead of menu-driven. It now prints copy-ready blocked_block_* snippets and suggests the most stable key to use. If the block does not look menu-based, blocked_menu_* is probably not the right lever.

Client-side behavior

Unlock overlay

When a stage is granted, the client receives a stage unlock notification that uses:

display_name
description
icon
color

This is the current generic overlay format. It does not depend on stage names like stone_age, iron_age, or diamond_age.

Tooltips

Blocked items add a tooltip line telling the player which stage is required.

JEI / REI

If JEI or REI is installed, blocked items are hidden for each player according to that player's unlocked stages.

Dimension and structure warnings

Restricted dimensions use a warning overlay and optional safety teleport.
Restricted structures use warning overlays plus hard interaction blocking.

Server config

Main server config file:

config/otherstages-server.toml

Important options:

enableStageMode
enableTooltips
enableWarnings
warningDuration
teleportOnInvalidDimension
defaultStartingStage
enableDebugLogging
cacheSize

defaultStartingStage is currently used by /otherstages player <target> reset. It is not automatically granted to every new player on first login in the current code path.

Stage Analyzer

The mod includes the otherstages:stage_analyzer item.

Usage:

Give yourself the item.
Sneak + right-click a storage block.
The mod scans the contents and writes JSON lines to config/otherstages/generated/.
Copy the generated lines into your blocked_items.json.

The analyzer supports vanilla containers and many modded storage systems through direct support or reflective fallbacks.

If the clicked block is not a supported container, the analyzer falls back to a block inspection readout with the block ID and state properties.

Notes and current scope

This README documents the loader-backed stage files that are active in the current code path.
Internal scaffolding exists for some future restriction types, but this README only documents features that are currently enforced in gameplay.
stage_info.json is required for each stage.
The folder name is the internal stage ID.
Higher order means higher progression tier.
If a stage should behave as a later tier, give it a larger order.
Use /otherstages reload after editing JSON files.

OtherStages

What the mod supports

Important behavior

Folder layout

stage_info.json

Supported fields

Translation-aware strings

Example

Optional per-stage files

blocked_items.json

blocked_mobs.json

blocked_structures.json

blocked_dimensions.json

blocked_villager_trades.json

progression.json

How progression checks run

Commands

Stage inspection

Stage management

Progression and reload

Debug helpers

Client-side behavior

Unlock overlay

Tooltips

JEI / REI

Dimension and structure warnings

Server config

Stage Analyzer

Notes and current scope

Links

Other Stage