Stage files

Stage data files

Stages are defined as JSON files at:

data/<namespace>/stages/<stage_name>.json

The reload listener scans every namespace for a stages folder - the file's own namespace does not need to match the mod ID, and the filename itself has no meaning to the game (it is not read as part of the stage's identity).

Complete field reference

{
  "order": 2,
  "stage_translation_key": "stage.verox_rpg_prog.hellfire",

  "mob_attribute_scaling": {
    "health_multiplier": 1.5,
    "damage_multiplier": 1.35,
    "knockback_resistance_multiplier": 1.05,
    "armor_multiplier": 1.15,
    "attributes": [
      { "attribute": "unbound_lib:crit_chance", "amount": 0.05 }
    ]
  },

  "territories": [
    {
      "structures": ["minecraft:fortress", "minecraft:bastion_remnant"],
      "damage_per_second": 1.0,
      "max_health_percent_per_second": 0.05,
      "tint": "#5A0A0A",
      "protect_structures": true,
      "mob_scaling": { "health_multiplier": 1.3 }
    }
  ],

  "mob_equipment": [
    {
      "entity_ids": ["minecraft:piglin", "minecraft:piglin_brute"],
      "equipment": [
        {
          "slot": "mainhand",
          "item": "minecraft:golden_sword",
          "enchantments": [
            { "id": "minecraft:sharpness", "level": 1 }
          ],
          "drop_chance": 0.02
        }
      ]
    }
  ],

  "locked_ores": [
    { "ore_block": "minecraft:ancient_debris", "disguise_block": "minecraft:netherrack" }
  ],

  "main_boss": {
    "entity_id": "minecraft:wither",
    "display_item": "minecraft:nether_star",
    "location_translation_key": "boss.verox_rpg_prog.wither.location",
    "guaranteed_drops": ["minecraft:nether_star"],
    "player_scaling": {
      "radius": 48.0,
      "health_per_extra_player": 0.5,
      "damage_per_extra_player": 0.2,
      "knockback_resistance_per_extra_player": 0.0,
      "armor_per_extra_player": 0.0
    },
    "drops": {
      "mode": "additional",
      "drops": [
        { "item": "minecraft:netherite_scrap", "count_min": 2, "count_max": 4, "chance": 1.0 }
      ]
    }
  },

  "optional_bosses": [
    {
      "entity_id": "minecraft:blaze",
      "display_item": "minecraft:blaze_rod",
      "location_translation_key": "boss.verox_rpg_prog.blaze.location",
      "guaranteed_drops": [],
      "player_scaling": { "radius": 32.0, "health_per_extra_player": 0.0, "damage_per_extra_player": 0.0, "knockback_resistance_per_extra_player": 0.0, "armor_per_extra_player": 0.0 },
      "drops": { "mode": "additional", "drops": [] }
    }
  ],

  "locked_items": ["minecraft:netherite_sword"],
  "locked_blocks_to_mine": ["minecraft:brewing_stand"],
  "locked_dimensions": ["minecraft:the_end"]
}

order

Type: integer, required

The stage's position in progression. Determines when its unlocks become available and what a boss defeat advances the world to.

stage_translation_key

Type: string, required

The translation key for the stage's display name in the Progression Journal. A matching <key>.summary key is also expected for the description shown on the stage's first page.

mob_attribute_scaling

Type: object, optional. Default: all multipliers 1.0 (no change).

Applies to every hostile mob (anything extending Monster - Zombie, Skeleton, Spider, etc.) while this stage is the currently active one. Passive and neutral mobs (cows, villagers, etc.) are never affected.

Only applies to newly spawned mobs - a mob already in the world does not retroactively gain the bonus when the stage changes. Mobs loaded back in from saved chunks are not scaled again.

Values of 1.0 or less have no effect. This field cannot currently reduce a mob below its vanilla baseline.

attributes

Optional list of additional attribute modifiers, for any attribute - vanilla or modded:

"attributes": [
  { "attribute": "unbound_lib:crit_chance", "amount": 0.05 },
  { "attribute": "unbound_lib:armor_penetration", "amount": 0.1 },
  { "attribute": "minecraft:generic.movement_speed", "amount": 0.1, "operation": "add_multiplied_base" }
]

Unknown attributes are skipped silently, so a stage file can reference attributes from optional mods such as Unbound Lib without requiring them.

Not inherited: like the multipliers above, only the current stage's values apply. If mobs should keep a bonus in later stages, repeat it (ideally increased) in every following stage file.

territories

Type: list, optional.

Structures that belong to this stage. A territory works in two steps, depending on how far the world has progressed:

This lets players reach a boss's lair as soon as that boss is their next goal, but not plunder the structure before it falls.

{
  "structures": ["minecraft:fortress", "#minecraft:village"],
  "damage_per_second": 1.0,
  "max_health_percent_per_second": 0.05,
  "tint": "#5A0A0A",
  "protect_structures": true,
  "mob_scaling": {
    "health_multiplier": 1.3,
    "attributes": [{ "attribute": "unbound_lib:crit_chance", "amount": 0.1 }]
  }
}

Structures are checked per structure piece, not by one large box - for jigsaw structures like bastions or villages, only the actual buildings count. biomes exists in the schema for future use but is not recommended yet.

mob_equipment

Type: list, optional.

Equips specific weapons/armor onto matching mob types while this stage (or any earlier one, see below) is active. Grouped by entity_ids so many mobs can share one loadout.

{
  "entity_ids": ["minecraft:zombie", "minecraft:husk", "minecraft:drowned"],
  "equipment": [
    {
      "slot": "mainhand",
      "item": "minecraft:iron_sword",
      "enchantments": [{ "id": "minecraft:sharpness", "level": 1 }],
      "drop_chance": 0.02
    }
  ]
}

slot accepts mainhand, offhand, head, chest, legs, feet. drop_chance defaults to 0.0 (the item never drops on death) unless set otherwise.

Inheritance: if a later stage does not redefine equipment for a given entity, the highest earlier stage that does define it is used automatically. To explicitly stop a mob's equipment at some stage, give that entity an empty "equipment": [] in that stage.

Works with any registered item or enchantment, vanilla or modded - resolution is purely by ID, not by hardcoded type.

locked_ores

Type: list, optional.

Ore blocks that remain fully minable while locked, but are visually disguised as another block and yield that block's item instead of the real ore.

{ "ore_block": "minecraft:diamond_ore", "disguise_block": "minecraft:stone" }

This is distinct from locked_blocks_to_mine: an ore in this list can always be broken (it is never fully inaccessible), only its appearance and drop change while sealed.

main_boss / optional_bosses

main_boss is the boss whose death advances the world to this stage's order. optional_bosses are additional bosses tied to the stage for guide/flavor purposes and drop configuration, but killing one does not advance progression.

Both use the same structure:

player_scaling

{
  "radius": 48.0,
  "health_per_extra_player": 0.5,
  "damage_per_extra_player": 0.2,
  "knockback_resistance_per_extra_player": 0.0,
  "armor_per_extra_player": 0.0
}

At spawn, the boss counts alive players within radius blocks. For every player beyond the first, the listed fractions are added (e.g. health_per_extra_player: 0.5 with 3 nearby players adds +100% health). A solo player triggers no bonus. This does not update dynamically if players join or leave mid-fight - it is evaluated once, at spawn.

drops

{
  "mode": "additional",
  "drops": [
    { "item": "minecraft:netherite_scrap", "count_min": 2, "count_max": 4, "chance": 1.0 }
  ]
}

guaranteed_drops is separate from this table: it exists because some vanilla bosses spawn their signature item directly in Java code rather than through their loot table (the Wither's Nether Star is the primary example). Without listing it here, the Guide UI's drop preview and any future guaranteed-drop logic would not know about it - the loot table itself genuinely does not contain it.

locked_items

Type: list of item IDs, optional.

Fully inaccessible while locked - cannot be picked up meaningfully, equipped, used, or crafted with while the owning stage is not yet reached. Shown with a "Sealed" tooltip everywhere the item appears.

locked_blocks_to_mine

Type: list of block IDs, optional.

Fully inaccessible while locked - cannot be broken or placed at all. Intended for functional blocks (Enchanting Table, Anvil, Beacon, redstone components) rather than naturally-generated ore, which should use locked_ores instead.

locked_dimensions

Type: list of dimension IDs, optional.

Blocks travel into the listed dimension via any portal while the owning stage has not been reached. The player is stopped before the actual dimension change happens; nothing else about the portal is altered.

Mod-dependent stages

Stage files can react to which mods are installed, so one progression can adapt itself - for example a different stage when Iron's Spells 'n Spellbooks is present.

required_mods / excluded_mods

Any stage file can list mod IDs on its top level:

{
  "required_mods": ["irons_spellbooks"],
  "order": 2,
  "stage_translation_key": "stage.verox_rpg_prog.frostbound"
}

To swap a stage, give the original file "excluded_mods": ["irons_spellbooks"] and add a replacement with "required_mods": ["irons_spellbooks"] and the same order. Only one of them is ever loaded.

Stage additions

To extend an existing stage without copying the whole file, place an addition file at:

data/<namespace>/stage_additions/<name>.json

{
  "required_mods": ["irons_spellbooks"],
  "order": 3,
  "optional_bosses": [
    { "entity_id": "irons_spellbooks:fire_boss", "display_item": "irons_spellbooks:cinder_essence" }
  ],
  "locked_items": ["irons_spellbooks:netherite_spell_book"]
}

The addition is merged into the loaded stage with the same order. Supported fields: optional_bosses, locked_items, locked_blocks_to_mine, locked_ores, locked_dimensions, territories, mob_equipment - all are appended to the stage's own lists. required_mods and excluded_mods work here as well. An addition whose order matches no loaded stage is skipped with a warning in the log.

Built-in Iron's Spells 'n Spellbooks support

With Iron's Spells 'n Spellbooks installed, the default progression automatically grows from 5 to 7 stages: Sculk Dread is replaced by Frostbound (Ice Spider), and Catacombs (Dead King) and Ashen Citadel (Tyros) are added. Iron's spellbooks, gear and structures are sealed alongside the matching tiers. The full layout is visible in-game in the Progression Journal.

The ISS stages are regular stage files using required_mods / excluded_mods and stage additions, so they can be overridden or removed by a datapack like any other stage.