EmakiDungeon

EmakiDungeon is a party dungeon plugin: you team up, pick a difficulty, clear a private dungeon world together, and claim the loot

• Every party gets its own world cloned from the template, so runs never interfere with each other, and the world is deleted as soon as the run ends
• The dungeon ships with a complete challenge flow: first pick the difficulty and drop mode, then confirm ready, wait out the world preparation countdown, and enter
• Entry limits are managed per day / week / month, with challenge time windows, weekdays, week-of-month, and cooldown support
• Routed rewards go into a stash first and are only paid out on clear; leaving mid-run or failing voids everything, and player state rolls back to a snapshot taken on entry
• Built-in party system (invite / apply / kick / party channel); in-dungeon chat is isolated from global chat by default, and you can toggle global listening any time
• Built-in map editor: mark regions, place markers, fill blocks, run a test start in game, and write back to the template on save
• The run is described by flow.yml: rooms, waves, gates, branch options, trigger zones, timers, kill targets, and 22 module types in total
• GraalJS dungeon scripts and CoreLib action pipelines let you hook custom logic to dungeon lifecycle events

Basics

Item	Value
Module version	1.0.2
Build artifact	EmakiDungeon-1.0.2.jar
API coordinate	emaki.jiuwu.craft:emaki-dungeon-api:1.0.1 (compile-time only, never put it into plugins/)
Main command	/edg (aliases /dungeon, /edungeon)
Required dependency	EmakiCoreLib (required: true, join-classpath: true)
Optional dependencies	MythicMobs, WorldGuard (everything works without them; the matching integrations just stay off)
Permission nodes	emakidungeon.play, emakidungeon.dungeon.*, emakidungeon.bypass.limit, emakidungeon.bypass.escape, emakidungeon.script, emakidungeon.editor, emakidungeon.admin, emakidungeon.*
Supported platforms	Paper 26.1+, Folia supported (folia-supported: true)

NOTE

Every dungeon also gets a dynamically registered permission emakidungeon.dungeon.<dungeonId> whose default is open to all players; to make a dungeon members-only, flip that default off in your permission plugin and grant it to the groups you want

Pages

Page	Contents
Commands	Player commands, party subcommands, editor session commands, admin commands, and the permission table
Configuration	Every key of the global config.yml, the per-dungeon config.yml, and the reward box GUI
Challenges & Rewards	Entry flow, entry limits, party rules, reward stash and payout, failure rollback
Flow & Triggers	The 22 module types of flow.yml, editor workflow, lifecycle actions, and scripts
API	For developers: the emaki-dungeon-api facades and every event

Core capabilities

Capability	Description
Instance world pool	Worlds are cloned from templates, one spare world is kept warm per dungeon (pool.max-worlds, global limit.max-instances); worlds are created on demand and deleted on dispose, and startup self-checks clean up leftovers
Challenge flow	Leader starts, difficulty select, drop-mode select, full-party ready confirmation (times out to cancel), world preparation wait (bossbar or chat, cancellable), then entry counts against limits
Three-tier entry limits	Daily / weekly / monthly counts with challenge windows, evaluated in the order month > week > day, plus a standalone cooldown; counters bucket by server timezone or general.timezone
Reward stash and payout	Routed loot is stashed during the run and paid into the reward box or inventory on clear using the chosen drop mode; failing voids the stash and restores the player snapshot
Party and chat isolation	Party size and invite mode are configurable; dungeon chat stays inside the instance unless the player runs /edg globalchat on, and the party channel is separate
Command guard	Commands inside a dungeon pass a blacklist/whitelist filter, escape commands (like /tp *) sit in a separate blacklist that no allow-rule can override, and players crossing the boundary are pulled back
Map editor	A separate edit world with two-point regions, six marker types, area fill, panel field editing, test start (no counts, no leaderboard), write-back only on save
Scoring and ranking	Five weights (damage, kills, heal, deaths, defense) feed the score, plus per-dungeon leaderboards and personal stats
Lifecycle actions	11 lifecycle segments (from dungeon_enter to dungeon_destroy) run through the CoreLib action pipeline for broadcasts, sounds, and custom logic
Runtime monitors	Alert thresholds for MSPT P95, heap slope, and write-queue backlog (threshold <= 0 disables), reported to console and the audit log

Default configuration layout

plugins/EmakiDungeon/
├── config.yml               ← main configuration (global switches and limits)
├── world/
│   └── <dungeonId>/
│       ├── config.yml       ← per-dungeon config (auto-generated when missing)
│       ├── flow.yml         ← flow definition (auto-generated when missing)
│       └── region/          ← dungeon map region files
├── gui/
│   └── rewardbox.yml        ← reward box GUI (pages and capacity)
├── scripts/                 ← GraalJS dungeon scripts, file name = <dungeonId>.js (optional)
├── instances.yml            ← runtime instance records (auto-generated, do not edit)
├── parties.yml              ← party snapshots (auto-generated, do not edit)
└── lang/

A dungeon template is simply a folder under world/, and the folder name is the dungeon ID. On startup and on /edg admin reload the plugin scans that directory and fills in a missing config.yml or flow.yml from the bundled templates, without overwriting existing files

Typical workflow

1. First create a folder under plugins/EmakiDungeon/world/ as the dungeon ID (for example my_dungeon) and drop your map region files into it (or start empty and build with the editor)
2. Restart the server or run /edg admin reload; the missing config.yml and flow.yml are generated for you
3. Run /edg editor my_dungeon, place markers, wire the flow, and click "Save and write back" when done
4. Then tune difficulty, entry limits, and drop modes in config.yml, and run /edg admin reload again
5. Players run /edg list to see dungeons and /edg enter my_dungeon to start; the leader picks a difficulty and everyone confirms readiness
6. On clear, open the reward box (/edg rewards), or turn the reward box off in config to send payouts straight to the inventory

Related modules

Module	How it fits
EmakiCoreLib	Required dependency: scheduling, messages, config checks, and the action pipeline; dungeon lifecycle actions run as CoreLib action segments
EmakiMobs	Spawn waves can reference EmakiMobs definitions with the emakimobs: prefix (vanilla entity ids work without it)
EmakiItem / EmakiLevel	The settlement command chain settlement.commands can call their commands to grant items and experience
MythicMobs / WorldGuard	Optional dependencies; the plugin runs normally without them and the matching integrations stay off