Configuration

AstralDungeons ships as two separate plugins that each carry their own configuration:

Dungeon server (paper module, plugin AstralDungeons, data folder plugins/AstralDungeons/) — hosts the actual dungeon world instances (see Dungeon Instances) and the room/dungeon blueprints (Dungeon & Room Blueprints). Ships config.yml and messages.yml.
Bridge server (bridge module, plugin AstralDungeons-Bridge, data folder plugins/AstralDungeons-Bridge/) — runs on the hub/lobby, owns the portals, keys and the dungeon-inventory UI, allocates instances across dungeon servers, and pays out rewards (Loot & Rewards) when a player returns from a run. Ships config.yml, leaderboards.yml, messages.yml, and the menus/ + dialogs/ folders.

Dungeon server `config.yml`

instance-timeout: "10m"
max-instances: 10
spawn-group: "spawn"

mobs:
  detection-range: 3 # Radius in chunks
  activation-range: 32 # In blocks
  loot-persistent-data-key: "astraldungeons:loot"

guidance-arrow:
  material: paper
  item-model: "items:arrow"

inventory:
  hand-slot: 4
  items:
    40:
      copy-from: "%stacksuppliers_classes.weapon_{classes_class_id}%"

Backed by the DungeonConfiguration record:

Field	Type	Default	Description
`instance-timeout`	Duration	`10m`	How long an instance may sit idle before `InstanceTimeoutTask` (runs every second) force-deletes it: an `ACTIVE` instance with zero participants past this age is deleted with cause `NEVER_JOINED`; a `CREATING` instance that never finishes generating past this age is deleted with cause `NEVER_CREATED`. Accepts the shared human-readable duration format (`y`/`d`/`h`/`m`/`s`/`ms`, combinable, e.g. `1h30m`) parsed by `DurationParser` — not ISO-8601.
`max-instances`	int	`10`	Hard cap on concurrent dungeon instances this process will host. Reported to the bridge on a heartbeat (every 30s, via `ServerService`) alongside the current instance count so the bridge can skip full servers; a creation request that still lands on a full server is silently dropped by `DungeonCreationListener`.
`spawn-group`	String	`spawn`	Server group name participants are sent to once an instance ends — win or lose — and the target of `/spawn`.
`mobs`	`MobsConfiguration`	see below	Controls dungeon mob/boss activation as players move, and how an AstralMobs drop is recognised as dungeon loot.
`guidance-arrow`	`ItemStackWrapper`	`paper` + item model `items:arrow`	Item shown on the arrows that ride the boss guidance stream.
`inventory`	`InventoryConfiguration`	see below	The fixed hotbar every player is given on entering a dungeon.

`mobs`

Field	Type	Default	Description
`detection-range`	int (chunk radius)	`3`	On every block-changing player move inside an active instance, the surrounding chunks (this many chunks out from the player's chunk) are scanned for still-unconsumed mob spawn markers (`DungeonInstance.findSpawnLocationsAround`).
`activation-range`	int (blocks)	`32`	Of the spawn markers found by `detection-range`, only those within this block distance of the player are considered (`MobListener`, squared-distance check). The same value also gates the dungeon boss: the boss spawns once, the first time any participant comes within `activation-range` blocks of its location.
`loot-persistent-data-key`	Adventure `Key`	`astraldungeons:loot`	The persistent-data key `MobListener` looks for on every AstralMobs drop. A drop carrying a non-blank `STRING` under this key becomes a dungeon reward item whose payload is the command to run; a drop without it is logged and discarded. See Loot & Rewards.

Detection and activation are decoupled on purpose: detection-range is a coarse chunk-grid prefilter, and activation-range is the precise block-distance trigger applied to whatever it finds. A marker inside activation-range still only spawns when the player either stands within 25 blocks of it (a hard-coded constant, so mobs behind a corner still appear when the player is on top of them) or has line of sight to it.

`guidance-arrow`

ItemStackWrapper (see ItemStackWrapper for the full field set — material, name, lore, enchantments, item flags, amount, components, copy-from). This is the item stack shown on the oriented ItemDisplay arrows that ride each guidance pulse from the player toward the boss. If the configured item fails to resolve — an exception, or a stack that comes back null or air — PathGuidanceService logs a warning and falls back to a plain ItemStack(Material.ARROW).

`inventory`

The player's own inventory is wiped on entering a dungeon and rebuilt: slots 0–5 from their dungeon inventory gear (helmet, chestplate, leggings, boots, main hand, off hand), then everything under inventory.items on top.

Field	Type	Default	Description
`hand-slot`	int	`4`	The hotbar slot the player is locked to. Selected on join, and re-selected whenever they try to scroll away — `PlayerItemHeldEvent` for any other slot is cancelled.
`items`	`Map<int, ItemStackWrapper>`	slot `40`	Raw Bukkit inventory slot index → item to place there. Resolved once per player against their own placeholder container, so `copy-from` and `%placeholder%` values are per-player. Slot `40` is the vanilla off-hand index; the shipped default pulls the weapon for the player's AstralClasses class.

Bridge server `config.yml`

portal-group: "spawn"
reward-actions:
  - "[message] Tu as win %data_experience% points d'expérience chef !"

# Menu opened by /dungeon
inventory-menu: "dungeons-inventory"

The shipped reward-actions default is placeholder text and should be replaced. Backed by the DungeonsConfiguration record:

Field	Type	Description
`portal-group`	String	The server group that hosts the dungeon portals. `PortalListener` and `PortalParticleTask` are only registered when this server's own group matches, so the same build is inert everywhere else on the network.
`reward-actions`	`PaperActionList`	AstralCore action list run against a returning player. Triggered by `PlayerDataService.claimRewards`, which fires when the player connects to the bridge server (`PlayerConnectionListener`, listening for AstralSync's `PlayerDataLoadedEvent`). The action context has the run's `DungeonPlayerData` registered, exposing `%data_experience%`, `%data_killedMobs%`, `%data_duration%`, `%data_completed%` and `%data_blueprintId%` — see Placeholders. After the actions run, any queued reward commands are dispatched from console (with `%player_name%` substituted) and the cached player-reward data is deleted. See Loot & Rewards.
`inventory-menu`	String	Menu blueprint id opened by a bare `/donjons`. Must name a menu in the bridge's `menus/` folder; the shipped one is `dungeons-inventory`.

Bridge server `leaderboards.yml`

mobs: "dungeons-mobs"
time: "dungeons-time"
completion: "dungeons-completion"

Backed by the LeaderboardConfiguration record — three AstralLeaderboards board ids, updated by PlayerDataService#claimRewards once a run is claimed. All three are looked up through LeaderboardService; if that service is absent the update is skipped silently.

Field	Updated with	When
`mobs`	`increment` by the run's `killedMobs`	Every claimed run.
`time`	`update` to the run's `duration` (ms)	Only when the run was `completed`.
`completion`	`increment` by `1`	Only when the run was `completed`.

`messages.yml`

Both modules load their own messages.yml into their own DungeonMessages enum (ComponentWrapper values, MiniMessage-capable). They are different key sets — the two files are not interchangeable.

Dungeon server

Key	Default	Sent when
`player-death`	`%player_name% has died.`	A participant dies (`PlayerDeathEvent`) while their instance still has other participants alive. Broadcast to every participant in the instance. If the death leaves nobody alive, the instance instead ends immediately with cause `NO_ALIVE_PARTICIPANTS` and this message is skipped.
`won`	`Congratulations! You have won the game.`	The instance ends with cause `WON`.
`lost`	`Game over! You have lost the game.`	The instance ends with any other end cause.
`chat-format`	`<gray>%player_name%: <white>%message%`	The renderer applied to every chat message sent inside an instance. `%message%` is the raw message component. Chat from a player who is not in any instance's world is cancelled outright.

won/lost are sent by EndInstanceTask, which runs every 5 ticks from the moment the instance ends: the message goes out immediately, participants are teleported to spawn-group after ~12s, kicked after ~20s, and the instance is deleted after ~25s.

Bridge server messages

Key	Sent when
`creation-start`	Every entry gate passed; the create RPC is going out. `%blueprint_name%` available.
`creation-success`	A dungeon server accepted and built the instance.
`creation-failure`	The RPC failed, timed out, or every server declined.
`no-party`	The player walked into a portal (or ran `/donjons create`) without a party.
`not-party-leader`	A party member other than the leader stepped into the portal.
`invalid-party-size`	Party size is outside the blueprint's `minimum-players`/`maximum-players`. `%min%`/`%max%` available.
`failed-requirements`	At least one party member is missing the key or fails the blueprint's `requirements`. `%blueprint_name%` available.
`no-available-server`	No dungeon server with a free slot currently advertises that blueprint. `%blueprint_name%` available.
`preset-created`/`preset-renamed`/`preset-deleted`/`preset-equipped`/`preset-unequipped`	The matching preset action succeeded. `%preset_name%` available.
`preset-invalid-name`	A preset name outside 3–16 characters, or blank.
`preset-already-exists`	The player already has a preset with that name.
`preset-limit-reached`	The player already has 9 presets (the menu layout does not paginate).
`preset-must-unequip`	A preset is equipped and the player tried to create another — a new preset takes the gear being worn, which already belongs to the equipped one.
`unexpected-error`	A requirement threw, or the `/donjons` menu failed to open.

Data folders

Dungeon server

Two folders under plugins/AstralDungeons/ must be populated before any dungeon can be created; BlueprintService skips (with a warning) anything that doesn't validate:

Folder	Contents
`rooms/`	`RoomBlueprint` YAML files plus the WorldEdit schematics they reference. A room is skipped if its id is a duplicate or its referenced schematic file doesn't exist on disk.
`blueprints/`	`DungeonBlueprint` YAML files. A blueprint is skipped if its id is a duplicate, its declared start/end rooms don't resolve, or it has zero normal rooms/caps.

See Dungeon & Room Blueprints for the full YAML shape of both file types.

Bridge server

Folder	Contents
`blueprints/`	Bridge-side `DungeonBlueprint` YAML — the portal region, key item, entry requirements and party-size bounds for each dungeon. A duplicate `id` is warned about and skipped. See Portals & Keys.
`menus/`	AstralCore menu blueprints. Ships `dungeons-inventory` and `dungeons-preset`.
`dialogs/`	AstralCore dialog blueprints. Ships `dungeons-preset-create` and `dungeons-preset-rename`.

Reload

/dungeon reload exists on the dungeon server only, gated by the class-level dungeons.command permission plus dungeons.reload. It calls AstralDungeons.loadConfiguration(), which re-reads config.yml into DungeonConfiguration, re-reads messages.yml into DungeonMessages, and re-runs BlueprintService.load() — fully re-scanning rooms/ and blueprints/ from disk, so blueprint files added, edited, or removed since the last load take effect immediately. It does not affect dungeon instances already in progress.

The bridge exposes no reload command; its loadConfiguration() (re-reading config.yml, leaderboards.yml, messages.yml, and the blueprint/menu/dialog folders) only runs on enable, so bridge-side changes need a plugin or server restart.

Neither module's reload touches the cache or messaging connections — those are opened once in onEnable and require a restart to pick up connection-setting changes.

Configurate mapping note

Both configuration records are Configurate @ConfigSerializable types. An unannotated camelCase Java field maps to a kebab-case YAML key:

Java field	Declaring type	YAML key
`instanceTimeout`	`DungeonConfiguration`	`instance-timeout`
`maxInstances`	`DungeonConfiguration`	`max-instances`
`spawnGroup`	`DungeonConfiguration`	`spawn-group`
`detectionRange`	`DungeonConfiguration.MobsConfiguration`	`mobs.detection-range`
`activationRange`	`DungeonConfiguration.MobsConfiguration`	`mobs.activation-range`
`lootPersistentDataKey`	`DungeonConfiguration.MobsConfiguration`	`mobs.loot-persistent-data-key`
`guidanceArrow`	`DungeonConfiguration`	`guidance-arrow`
`handSlot`	`DungeonConfiguration.InventoryConfiguration`	`inventory.hand-slot`
`rewardActions`	`DungeonsConfiguration` (bridge)	`reward-actions`
`portalGroup`	`DungeonsConfiguration` (bridge)	`portal-group`
`inventoryMenu`	`DungeonsConfiguration` (bridge)	`inventory-menu`
`minimumPlayers`/`maximumPlayers`	bridge `DungeonBlueprint`	`minimum-players`/`maximum-players`

Last modified: 25 September 2026

Configuration

Dungeon server config.yml

mobs

guidance-arrow

inventory

Bridge server config.yml

Bridge server leaderboards.yml

messages.yml

Dungeon server

Bridge server messages

Data folders

Dungeon server

Bridge server

Reload

Configurate mapping note

Dungeon server `config.yml`

`mobs`

`guidance-arrow`

`inventory`

Bridge server `config.yml`

Bridge server `leaderboards.yml`

`messages.yml`