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, allocates instances across dungeon servers, and pays out rewards (Loot & Rewards) when a player returns from a run. Ships only config.yml.

Dungeon server `config.yml`

instance-timeout: "10m"
max-instances: 10
spawn-group: "spawn"
mobs:
  detection-range: 1 # Radius in chunks
  activation-range: 32 # In blocks
guidance-arrow:
  material: "arrow"

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's server-selection logic 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 (resolved through the network's server registry, same mechanism as AstralCore's `connect` action) that participants are sent to once an instance ends — win or lose. See Dungeon Instances.
`mobs`	`MobsConfiguration`	see below	Controls dungeon mob/boss activation as players move.
`guidance-arrow`	`ItemStackWrapper`	material `arrow`	Item used for the boss guide-trail arrows.

`mobs`

Field	Type	Default	Description
`detection-range`	int (chunk radius)	`1`	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 the room's still-unconsumed mob spawn points (`DungeonInstance.findSpawnLocationsAround`).
`activation-range`	int (blocks)	`32`	Of the spawn points found by `detection-range`, only those within this block distance of the player actually spawn a mob (`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.

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.

`guidance-arrow`

ItemStackWrapper (see ItemStackWrapper for the full field set — material, name, lore, enchantments, item flags, amount, components, copy-from). Only material: "arrow" is set by default. This is the item stack shown on every entity in the "way to the boss" guide trail — a line of oriented ItemDisplay entities PathGuidanceService computes once per instance and renders from the spawn room to the boss. If the configured item fails to resolve (e.g. invalid material), PathGuidanceService logs a warning and falls back to a plain ItemStack(Material.ARROW).

Bridge server `config.yml`

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

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

Field	Type	Description
`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 a `data` placeholder registered, exposing `%data_experience%` (accumulated dungeon-run experience) — 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.

`messages.yml` (dungeon server)

Loaded into the DungeonMessages enum (ComponentWrapper values, MiniMessage-capable). Only the dungeon server ships messages.yml — the bridge has no message keys of its own.

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 — `DungeonInstance` forwards to all of them. 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`. `EndInstanceTask` re-runs once per second; the message is sent to all participants on its 10th run (~9s after the instance ends), participants are teleported to `spawn-group` on the 80th run (~79s), and kicked on the 90th run (~89s) before the instance itself is deleted on the 100th (~99s).
`lost`	`Game over! You have lost the game.`	The instance ends with any other end cause. Same timing as `won`.

Data folders

Two folders under the dungeon server's data directory 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.

Reload

/dungeon reload (aliases /dungeons, plus /dg on the bridge) exists on both servers, gated by permission dungeons.reload:

Dungeon server — additionally requires the class-level dungeons.command permission. 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.
Bridge server — re-reads only config.yml into DungeonsConfiguration (there is no messages.yml or blueprint folder on this side).

Neither reload touches the cache, messaging, or (bridge-side) party 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`
`guidanceArrow`	`DungeonConfiguration`	`guidance-arrow`
`rewardActions`	`DungeonsConfiguration` (bridge)	`reward-actions`

Last modified: 25 July 2026

Configuration

Dungeon server config.yml

mobs

guidance-arrow

Bridge server config.yml

messages.yml (dungeon server)