Skip to main content

Runs and world isolation

A run is one play-through of a dungeon by one group. This page explains what a run owns, how its world is made, and which isolation mode to pick.

What a run owns​

Every run has its own:

  • members: the players of the group. A player is in one run at a time.
  • world or slot: the place where the dungeon exists for this run only.
  • time limit: the cooldownSeconds field of the dungeon (a maximum duration; empty or 0 means no limit).
  • state: the room each member is in, the once rooms already used, the chests, the mobs already spawned.
  • audience: the NPCs and chests of a run are shown to its members only.

Several runs of the same dungeon can exist at once, up to maxSimultaneousInstances. That number is also the number of lobbies of the dungeon. When all of them are taken, the next group is told "All the runs of this dungeon are taken."

Groups​

A group is whoever joins a lobby together, or the single player of a Dungeon Enter action. If the player has a party in MMOCore, Parties or the Typewriter party extension, that whole party joins the lobby together when there is room for all of it. Dungeon only reads those parties: it never creates or changes one.

The group size must be between minPartySize and maxPartySize, and every member must match the criteria of the dungeon. An admin using /typewriter dungeon force-start skips the minimum size and the criteria.

Choosing an isolation mode​

Set the isolation field of the Dungeon Instance.

ModeIsolatedCostNeeds
SLIME_CLONEYesLow: an in-memory cloneAdvanced Slime Paper and a template that is a loaded slime world.
WORLD_PER_RUNYesHigh: copies the template folder, then deletes the copyA template world folder in the server root.
SHARED_WORLD_SLOTSNoLowest: nothing is copiedA world built identically in every slot.
AUTO (default)SLIME_CLONE when Advanced Slime Paper is installed, otherwise WORLD_PER_RUN.

A mode that cannot run on the server refuses the run; it never falls back to another mode. The player reads "The dungeon cannot be started on this server." and the server log says why.

SLIME_CLONE​

Each run gets an in-memory clone of a slime world. This is the cheapest mode that is fully isolated. It needs Advanced Slime Paper, and templateWorld must name a loaded slime world.

WORLD_PER_RUN​

Each run gets a copy of the template world folder, which is a real new world. The copy is made off the server threads, the new world is named by the extension and stamped with a marker file so that only worlds it made can ever be deleted. At the end of the run the world is unloaded without saving and its folder is deleted.

  • The template is never loaded, written or deleted by the extension.
  • A link (symbolic link, junction) anywhere in the template folder makes the copy refuse.
  • The template name may only use letters, digits, _ and - (up to 64 characters). The main world of the server and names that look like run worlds are refused.
  • If a world cannot be unloaded because a player stays in it, it stays loaded and is deleted at the next start.

This is also the only mode that holds a generated dungeon: the extension creates an empty world for the run and pastes the rooms into it. With a generator, AUTO and WORLD_PER_RUN work, while SLIME_CLONE and SHARED_WORLD_SLOTS are refused.

SHARED_WORLD_SLOTS​

All the runs of the dungeon take place in the template world itself, each in its own slot of a grid. The extension shifts every position you authored (spawn, rooms, chests, NPCs, mob positions) by the offset of the slot of the run, so you build the dungeon once at the origin slot and then build it identically in every other slot (for example by pasting it).

The sharedSlots field sets the grid:

FieldMeaningDefault
spacingX, spacingZBlocks between two slots. At least the footprint.512
columnsSlots per row. 0 = every slot in one row along X.0
footprintX, footprintZSize of the template, in blocks.256
This mode is not isolated

Mobs, dropped items and blocks are shared by all the slots of the world. When a run ends, its mobs, chests and NPCs are removed, but the world itself is not repaired: items dropped on the ground and blocks broken by players or mobs stay. Players of other slots are hidden from each other, and the chests, NPCs and mobs of a run are filtered to its members, but a dungeon with destructive mobs or world edits will leave marks. In a shared world, keep blockDamage and dropVanillaLoot off on Dungeon Mob Spawn entries.

Two dungeons built on the same shared world share its slots. Use the same maxSimultaneousInstances for both.

Starting a run​

The launch is all-or-nothing:

  1. Criteria and group size are checked, and the isolation mode is resolved.
  2. A place is reserved, so a double click gives one run, not two.
  3. For a generated dungeon, the layout is made, then pasted into the new world a few rooms per tick.
  4. The world is prepared (clone, copy or slot).
  5. The entry cost is taken, all or nothing.
  6. Each member's origin is recorded and everyone is teleported.
  7. The run turns active, then chests, onStart, modifiers (and the affixes of a generated dungeon) run for each member.

If any step fails, the players stay where they were, the cost is refunded, the world is released and the place is given back.

Ending a run​

The first of these wins, and only one end runs even when several happen together:

  • Dungeon Complete (the dungeon was finished).
  • The time limit (cooldownSeconds) ran out.
  • Dungeon Close or /typewriter dungeon close <instance>.
  • Every member left, changed world or disconnected.

The end runs onEnd for each online member, cleans the chests, NPCs and mobs of the run, sends the members back (to the exitPoint of Complete and Close when it is set, otherwise to where each came from), then releases the world. A player who disconnects in a run is brought back to where they came from at their next join. If they come back within the reconnection delay (reconnectGrace, 2 minutes by default), they keep their place instead: see Disconnections.

Reload and restart​

EventWhat happens to the runs
typewriter reload, PublishThe runs are adopted again: members, world, deadline, room state, opened chests and spawned mobs come back. onStart and modifiers do not run again.
Server restartThe runs end: their worlds are gone. Players are sent home at their next join and orphaned world folders are purged.

To make adoption work, link an Active Dungeon Instance Artifact in the runtimeArtifact field. Without it the runs are written to a runs.json file of the extension, and the server log warns you at load. Several dungeons can share one artifact.

A run that cannot be adopted (its dungeon was deleted, its world is not loaded, its generated layout cannot be rebuilt) is closed at start-up and its players are sent home. The log says why.

Lobbies are not restored by a reload or a restart: they come back empty, apart from the lobbies of the runs that were adopted.