Stage Modes

Every stage has a mode that controls how it gets unlocked and whether a Research Scroll is generated for it. The mode is set in the stage JSON using the "mode" key. If the key is absent, the stage behaves as default.

Mode	Scroll generated?	Unlock method
default	Yes	Player researches it at a Research Pedestal
auto	No	Unlocked automatically by discovery events
external	Yes	Pedestal refuses it — must be unlocked by command or script
temporary	No	Unlocked automatically, then re-locks after a timer

---

default

The standard mode. A Research Scroll is generated for this stage and players unlock it by researching that scroll at a Research Pedestal.

{
  "display_name": "Iron Age",
  "mode": "default"
}

The "mode" key can be omitted entirely — default is the fallback for any stage that does not specify one.

---

auto

No scroll is generated. The stage unlocks automatically when the player meets one or more trigger conditions defined in the "auto_trigger" block.

{
  "display_name": "Nether Explorer",
  "mode": "auto",
  "auto_trigger": {
    "mode": "any",
    "triggers": [
      { "type": "dimension", "id": "minecraft:the_nether" },
      { "type": "advancement", "id": "minecraft:story/enter_the_nether" }
    ]
  }
}

Combine mode

The "mode" field inside "auto_trigger" controls how multiple triggers are evaluated:

Value	Behaviour
"any" (default)	The stage unlocks when any one trigger fires
"all"	The stage unlocks only after every trigger has fired

Trigger types

Each entry in "triggers" requires a "type" field and type-specific parameters:

Type	Parameters	Description
"item"	"id"	Player picks up or crafts the item
"biome"	"id"	Player enters the biome
"dimension"	"id"	Player enters the dimension
"structure"	"id"	Player enters the structure
"entity"	"id", "sub_mode"	Player interacts with an entity
"block_place"	"id"	Player places the block
"block_break"	"id"	Player breaks the block
"advancement"	"id"	Player earns the advancement
"playtime"	"days"	Player has been online for N in-game days

The "entity" trigger supports an optional "sub_mode" field to restrict which interaction counts:

sub_mode	Behaviour
"any" (default)	Either killing or interacting triggers the stage
"kill"	Only killing the entity counts
"interact"	Only right-clicking the entity counts

Examples

"triggers": [
  { "type": "item", "id": "minecraft:diamond" },
  { "type": "biome", "id": "minecraft:jungle" },
  { "type": "entity", "id": "minecraft:villager", "sub_mode": "interact" },
  { "type": "playtime", "days": 3 }
]

---

external

A scroll is generated, but the Research Pedestal refuses to research it. The stage can only be unlocked by a server operator via the /history global unlock <stage> command or by an external script.

Use this mode when unlocking should be fully under the modpack author's control — for example, tied to a quest reward, a custom event, or a manual ceremony.

{
  "display_name": "Prestige Unlock",
  "mode": "external"
}

---

temporary

Like auto, but the stage re-locks automatically after a configured duration. No scroll is generated.

Use this for time-limited events such as a trading window, a seasonal buff, or an event that can recur on a cooldown.

{
  "display_name": "Harvest Festival",
  "mode": "temporary",
  "auto_trigger": {
    "triggers": [
      { "type": "advancement", "id": "mypack:events/harvest_begins" }
    ]
  },
  "temporary": {
    "duration": 3,
    "duration_unit": "days",
    "max_triggers": 0,
    "cooldown": 12,
    "cooldown_unit": "hours"
  }
}

temporary options

Key	Type	Default	Description
duration	Integer	1	How long the stage stays unlocked after the trigger fires
duration_unit	String	"hours"	Unit for duration: "seconds", "minutes", "hours", or "days"
max_triggers	Integer	1	Maximum number of times the stage may unlock in total (see below)
cooldown	Integer	0	Wait time after re-locking before the trigger is accepted again
cooldown_unit	String	"hours"	Unit for cooldown: same options as duration_unit

max_triggers in detail

• 1 — the stage unlocks exactly once and stays locked permanently afterwards. The cooldown does not apply. A server operator can still unlock it manually via /history global unlock, but that does not start a new timer.
• N > 1 — the stage may unlock up to N times total. After each re-lock, the cooldown must pass before the trigger is accepted again.
• 0 — unlimited unlocks. After each re-lock, only the cooldown prevents immediate re-triggering. A cooldown of 0 means the stage can fire again right away.