🏰 Dungeon

Private, party-based dungeon runs for your TypeWriter server, fixed or generated.

A TypeWriter extension by BTC Studio

✨ What it does

A dungeon is described by one Dungeon Instance entry. Players pick it in a global menu, join a lobby, mark themselves ready and are teleported in when the countdown ends. Staff and quests can also send a player straight in with an action or a command.

Two kinds of dungeon share the same runs, menus, chests, NPCs, mobs, events and facts:

• 
  
• Fixed: you build the dungeon once in a template world and draw the rooms as zones in game.
• Generated: you build room templates and a generator assembles a new layout for each run, from the start room to the boss room. The same seed always gives the same dungeon.

🌍 Runs and isolation

• 
  
• Three isolation modes: Slime clone, a world per run, or slots of a shared world. You pick one per dungeon with a single field.
• One run per group: several runs of the same dungeon can go on at the same time, up to the limit you set. A time limit and an entry cost apply to each run.
• A clean end every time: a run ends on completion, time out, admin close or when the last player leaves. Only one end wins when several happen at once, so you never get a double refund.
• Failed start, nothing kept: if anything fails on the way in, players stay where they were, the cost is refunded and the world is thrown away.
• Reload safe: a typewriter reload or a Publish keeps the runs going, with their members, deadline, opened chests and spawned mobs. A server restart ends the runs.

🚪 Menus and lobbies

• 
  
• Global menu: a browser of the dungeons of a category, ordered by priority. A dungeon whose criteria a player does not meet is shown locked.
• Party menu with live lobbies: players join a lobby, toggle ready and see others arrive without clicking. The menu repaints for everyone who has it open.
• Countdown and costs: the run starts once everyone is ready and the minimum size is met. The countdown stops if somebody un-readies. The entry cost is taken from the leader or from the whole group, and only if nobody is missing anything.
• Party plugins: it reads the party of MMOCore, Parties or the TypeWriter party extension, so friends enter together. It never creates or changes those parties.
• Waiting scoreboard and idle kick: show who is missing during the wait. A lobby that sits idle is emptied after a delay you set.
• Both menus use GUI layouts, so you design them in the web panel like any other menu.

🗡️ Inside a run

• 
  
• Fixed rooms: each room is a zone with onEnter and onLeave triggers, modifiers, criteria and priority. An in-game editor places the nodes of the zone.
• Loot chests: block chests or NPC-anchored chests, real or client-side. One inventory per player or a shared one, weighted or independent loot.
• Combat mobs: real vanilla mobs that appear once per run, with equipment, attributes, drop rules and triggers on death, bounded by a cap.
• Per-run NPCs: an NPC shown only to the members of one run, built from any TypeWriter entity definition.
• Statistics: attempts, completions and best time per dungeon and per player.

🧬 Generated dungeons

• 
  
• Room templates: small structures with doors and markers, edited in game.
• Connector types: define which doors can join two rooms.
• Room pools and generator: the generator draws rooms from your pools and assembles the layout from a seed.
• Affixes: modifiers applied to a generated run.
• Clear rooms from your own logic: an action declares a generated room cleared and fires its onClear.

🧩 Entries, commands and placeholders

Entries (33)

Dungeon setup

• 
  
• dungeon_instance: define a dungeon: isolation, party size, time limit, costs
• dungeon_category: group dungeons for the global menu
• dungeon_room_config: spawn point and room settings
• dungeon_room: room zone with enter and leave triggers
• dungeon_loot_chest: loot chest of a dungeon
• dungeon_mob_spawn: combat mobs of a room, spawned once per run

Generated dungeons

• 
  
• dungeon_generator: assemble a layout for each run from a seed
• dungeon_room_pool: pool of rooms the generator can draw from
• dungeon_room_template: saved structure of one room
• dungeon_connector_type: door types that join two rooms
• dungeon_affix: modifiers applied to a generated run

Actions

• 
  
• dungeon_global_menu: open the dungeon browser of a category
• dungeon_party_menu: lobby menu of a dungeon
• dungeon_enter: send a player into a run
• dungeon_leave: remove a player from their run
• dungeon_close: end a run
• dungeon_complete: complete the run and send members back
• dungeon_clear_room: declare a generated room cleared
• dungeon_spawn_mobs: spawn a wave of mobs
• loot_chest_trigger: trigger a loot chest

Events

• 
  
• on_dungeon_start: a run starts
• on_dungeon_complete: a run is completed
• on_dungeon_room_enter: a player enters a room
• on_dungeon_room_leave: a player leaves a room
• on_dungeon_mob_death: a dungeon mob dies

Facts

• 
  
• indungeon: is the player inside a dungeon?
• indungeon_instance: is the player inside a specific dungeon?
• dungeon_mobs_alive: dungeon mobs still alive

Audience and groups

• 
  
• dungeon_run_audience: players in a dungeon run
• dungeon_run_group: players of a dungeon run, as a group

Entities

• 
  
• dungeon_npc_instance: NPC shown only to the members of a run

Artifacts

• 
  
• dungeon_artifact: statistics: attempts, completions, best time
• active_dungeon_instance_artifact: state of the runs, kept across reloads

Commands

• 
  
• /typewriter dungeon enter | leave | close <instance>
• /typewriter dungeon global-menu <category> and /typewriter dungeon instance-menu <instance>
• /typewriter dungeon force-start <instance>: start your lobby without waiting for ready, the countdown or the group size
• /typewriter dungeon room <room> edit | addnode | removenode | removenodeat | save | cancel: the in-game room editor
• Permission typewriter.dungeon.admin covers every command. Players need no permission to use the menus.

Placeholders

• 
  
• %typewriter_dungeon_remaining%, %typewriter_dungeon_remaining_formatted%: time left in the player's run
• %typewriter_dungeon_players%, %typewriter_dungeon_max%, %typewriter_dungeon_list%: the party of the run
• %typewriter_dungeon_attempts%, %typewriter_dungeon_completions%, %typewriter_dungeon_best%: statistics of the player
• And more: lobby countdown, per-player health, totals, statistics by dungeon id. All are listed in the documentation.

🚀 Set up

• 
  
• Install the GUI extension and the TypeWriter Quest extension, drop the Dungeon jar in plugins/Typewriter/extensions/ and restart.
• Add a Dungeon Room Config (capture the spawn point where you stand) and a Dungeon Instance with the template world folder name and the group size.
• Add the Dungeon Artifact and Active Dungeon Instance Artifact, then a Dungeon Category that lists your dungeon.
• Add a Dungeon Global Menu and a Dungeon Party Menu on a sequence page, fire the menu from an NPC, add a loot chest and a Dungeon Complete action, then publish.

The documentation has the full walkthrough, including generated dungeons.

📋 Requirements

• 
  
• TypeWriter 0.9.0-beta-177 or newer, with the Quest and GUI extensions
• Paper server (Folia is not supported)
• Fixed dungeon: a template world folder in your server root
• Optional: Advanced Slime Paper (Slime clone mode), MMOCore or Parties (external parties), CraftEngine or Nexo (custom chest blocks), PlaceholderAPI