Dungeon Files

Each dungeon is a YAML file:

plugins/SinceDungeon/dungeons/<dungeon_id>.yml

The filename without .yml is the dungeon ID used by commands, leaderboards, API calls, and Premium affix configuration.

Top-Level Structure

template-world: "ForgottenCrypt_Template"
public: true

settings: { }
conditions: { }
rewards: { }
stages: { }

Template World

template-world: "ForgottenCrypt_Template"

In Core WORLD mode, the value must match the source world folder name. SinceDungeon creates temporary instance worlds from this template. In Premium SCHEMATIC mode, which works on Paper and Folia, the same template-world value names the schematic file. On Folia, Core world-copy mode is not supported, so use schematic mode with a preloaded shared world.

Public Visibility

public: true

Public dungeons appear in tab completion for player-facing commands such as /dungeon join and /dungeon top.

When public: false, normal members cannot join the dungeon, even if they manually type the dungeon ID. Admins with SinceDungeon.admin can still see private dungeons in tab completion and can join them for testing.

Settings

settings:
  max-players: 6
  required-lives-to-join: 1
  lives-deducted-per-death: 1
  lives-deducted-on-leave: 0
  lives-deducted-on-fail: 0
  lives-deducted-on-clear: 0
  keep-inventory-on-death: true
  prevent-item-dropping: true
  block-ender-pearls: true
  kick-delay-after-finish: 15
  force-daylight-and-clear-weather: true
  save-and-restore-stats: true
  death-action: "RESPAWN"
  clear-mob-drops: true
  randomize-stages: false
  cooldown-seconds: 1800
  cooldown-on-leave: true
  required-item: "NONE"
  consume-required-item: true

Death actions:

• RESPAWN: respawn at the dungeon start or checkpoint.
• FAIL: fail the entire run.
• SPECTATE: let the player watch remaining teammates.

Life costs:

• lives-deducted-per-death is charged each time a player dies inside the run.
• lives-deducted-on-leave is charged when a player leaves or disconnects before the run clears.
• lives-deducted-on-fail is charged to participants when the dungeon ends as failed.
• lives-deducted-on-clear is charged to participants when the dungeon is cleared.
• Set any outcome cost to 0 to disable that outcome penalty. Outcome costs are separate from per-death costs.
• cooldown-on-leave only controls whether cooldowns are applied on leave/fail; it does not change life deductions.

Command hooks:

settings:
  commands:
    on-start:
      - "lp user %player% permission set dungeon.in_game true"
    on-finish:
      - "lp user %player% permission unset dungeon.in_game"
    on-first-finish:
      - "eco give %player% 5000"

Conditions

Conditions are checked before the player enters.

conditions:
  level_check:
    name: "Level Requirement"
    check: "%player_level%;>=;10"
    msg: "<red>You must be at least Level 10 to enter this raid!"

Default condition processor:

• PAPI: PlaceholderAPI expression checks.

Condition format:

<left>;<operator>;<right>

Supported numeric operators:

• >=
• <=
• >
• <
• ==
• !=

Supported string operators:

• ==
• !=
• equalsIgnoreCase

Stages

Stages are numeric and run in order unless randomize-stages or Premium branching/jump actions alter flow.

stages:
  1:
    chance: 100.0
    commands:
      - "say Stage 1 completed by %player%"
    actions:
      arrival:
        type: "REACH_LOCATION"
        target: "10,64,10"
        radius: 3.0

Coordinates

Most locations use:

x,y,z

Example:

target: "10,64,-5"

Lists of locations:

locations:
  - "15,64,20"
  - "5,64,20"

Start Location

settings:
  start-location: "0,65,0"

Use NONE to keep the provider/world spawn.

For schematic dungeons, this is a local schematic coordinate. It also supports yaw and pitch:

settings:
  start-location: "0,65,0,180,0"

Stage Insertion

Admins can insert a stage into an existing dungeon file and shift later stage numbers:

/sincedungeon stage insert <map_id> <position>
/sdp stage insert <map_id> <position>

Complete Example

See Example Dungeon for a compact full YAML file using conditions, rewards, stages, wave combat, loot chests, keys, doors, and a boss.