Authoring Dungeons

CommonLib (ZiggfreedCommon) 2.4.0 adds dungeons. A dungeon is one file in your pack. A player goes in from a block, a character or a conversation line and lands in an area set up for their party: a fresh paste of your prefab. Each member who follows them in lands in the same area, and another party gets an area of its own. A run clears when the party does what the dungeon asks, and each member there collects a completion reward on the results screen.

The worked example on this page is Seasons of Orbis' graveyard, The Horseman's Graveyard. While Hallow's Eve runs, the Gravekeeper near Old Jack in the Forgotten Temple sends whoever presses F on him into it, and a run clears when the Headless Horseman falls.

The dungeon file

{
  "Enabled": true,
  "Share": {
    "PartyLocked": true,
    "MaxPlayers": 5,
    "AreasPerCopy": 4
  },
  "Area": {
    "Prefab": "Hallows_Eve/Hallows_Eve_Graveyard.prefab.json",
    "EntryOffset": {
      "Y": 1
    }
  },
  "Complete": {
    "Bosses": [ "Hallows_Eve_Headless_Horseman_Encounter" ]
  },
  "Rewards": {
    "Lootable": "Hallows_Eve_Graveyard_Clear",
    "Diminish": { "Steps": [1, 0.5], "Window": "Daily" }
  },
  "Copy": {
    "EmptyCloseSeconds": 60
  },
  "Season": "Hallows_Eve",
  "Text": {
    "NameKey": "dungeon.hallows_eve_graveyard.name",
    "DescriptionKey": "dungeon.hallows_eve_graveyard.description"
  }
}

Every leaf is optional. The table lists them all with what you get when you leave one out; each group is covered in its own section below.

The graveyard's name is dungeon.hallows_eve_graveyard.name in the pack's hallowseve.world.lang, "The Horseman's Graveyard". Write the key as it stands in your own lang file, without the file's name in front.

The world template and the area prefab

Each copy of a dungeon is a world of its own, started from a world template. Your prefab is pasted into it once for each party that goes in, each paste in an area of its own.

The world template: Instance

Instance names a native instance template by its folder under Server/Instances/. Leave it out and every copy starts from the library's own, ZiggfreedCommon_Dungeon_Void: an empty void world in Adventure mode that saves nothing, running the library's dungeon gameplay config, ZiggfreedCommon_Dungeon. That config gets a player who dies back up in their own area with everything still in their bag (their gear still loses some durability, as on any death), and keeps every block as it was built (see Block rules).

If you name a template of your own:

• It must not pin its world with an InstanceKey. A dungeon whose template does is an error, and it refuses entry.
• While Share.AreasPerCopy is above 1, it must run no portal timer and no world events: both belong to the whole world, so every party in the copy would share them. Either is an error that refuses entry. Set AreasPerCopy to 1, or name a template without them.
• Its gameplay config sets the rules inside. The game's own Default_Instance sends a player who dies out of the instance, and the game's Default drops half of each droppable stack on a death. To keep the library's rules, give your config the same Death.RespawnController, Death.ItemsLossMode and Plugin.ZigBlockRules, or make ZiggfreedCommon_Dungeon its Parent.

The area prefab: Area

• The prefab is pasted with its anchor on the area's spot, at height 64. Areas sit two to a row, Spacing blocks apart.
• The paste carries the prefab's entities and block states, so a boss fight, a spawn marker or an exit pad saved in the prefab comes with it.
• Every party gets a fresh paste. Before a used area is pasted again, the library clears out what the last party left there: creatures, drops and projectiles, never a player. It also empties every chest and other container inside the prefab's box, so each one starts with only what its own drop list puts in it, and the paste line in the log counts the containers it emptied.
• The area is pasted while the arriving player sits on the loading screen. A player who arrives while a new copy is still opening waits for it rather than opening another. Each paste's time is logged under [dungeon].

The graveyard's prefab, Hallows_Eve/Hallows_Eve_Graveyard.prefab.json, is an enclosed graveyard whose anchor is the floor of its entrance room, so EntryOffset Y 1 stands an arriving player on that floor. It carries the Horseman's fight and his spawn marker, so every fresh paste stages a fresh fight, and a vanilla Leave_Instance pad behind the arrival spot.

When it is open: Enabled and Season

A dungeon can be entered while Enabled is true (the default) and, when it names a Season, while that calendar event runs. Season takes a calendar event's id, such as Hallows_Eve; leave it out for a dungeon open all year. A child keeps its Parent's Season.

• Outside its season, a way in tells the player which event it opens for: "The Horseman's Graveyard only opens during Hallow's Eve." An event with no name reads "only opens in its season".
• Switched off, it reads "The Horseman's Graveyard is closed for now."
• A Season no calendar event defines keeps the dungeon closed, and the audit warns about it.

The Gravekeeper's placement names the same Season, so outside Hallow's Eve he is not in the temple at all.

Parties and areas: Share

• A player goes in with their party: the library's own party, which any player starts with /zigparty on a server running CommonLib. A player in no party is a party of one, so a dungeon can always be run alone.
• Members go in one at a time, each through the way in. The first reserves an area, and each member who follows lands in it. Only members on their way in or inside count against MaxPlayers, so a member who is offline neither goes in nor holds a place. When the area is full, the next member reads "There is no more room with your party in The Horseman's Graveyard."
• A party fills a free area of an open copy before a new copy opens. A copy is a world named after the dungeon and a number, in lower case, such as hallows_eve_graveyard-1. A copy whose ticks run slow (over 25 ms on average) takes no new party, and neither does a copy about to close.
• A player who dies gets back up in their own area. A player who leaves the world or the server is no longer one of its members, and neither is one who walks more than half a Spacing from their area's spot in a copy of more than one area. A player still on the way in after two minutes is let go.

The party's size and invite rules are the library's party settings, Server/ZiggfreedCommon/Party/ZiggfreedCommon.json: MaxSize 5, InviteTimeoutSeconds 60 and OwnerOnlyInvite false. A change there takes effect after a restart.

The way in

There are three ways in, and all three run the same entry with the same checks: a block's interaction chain ending in ZigEnterDungeon, a character's press F, and a conversation line. The last two open the Dungeon destination.

From a block: ZigRequires, then ZigEnterDungeon

{ "Type": "ZigEnterDungeon", "Dungeon": "<Id>" } sends the player in with their party. It decides nothing about who may go: put the gate in front of it. ZigRequires runs its Next for a player who meets its Requires block and its Failed for one who does not, and tells that player, in an error notice, the first thing they still need. Its Requires is the shared block a quest's gate uses (see Requirements); left out, it lets everyone through.

"Interactions": {
  "Use": {
    "Interactions": [
      {
        "Type": "ZigRequires",
        "Requires": { "Quests": ["Yourpack_Intro"] },
        "Next": { "Type": "ZigEnterDungeon", "Dungeon": "Yourpack_Crypt" }
      }
    ]
  }
}

• ZigEnterDungeon finishes, running its own Next, only when the player is on their way in. A refusal tells the player why (see below) and takes its Failed branch.
• A player who is dead, still arriving from a teleport or being teleported is turned away without a word, as the game's own instance portals do.
• Any interaction chain can end in it, such as the CollisionEnter chain of a pad players walk onto, the key vanilla's Leave_Instance pad uses for its way out.

ZigRequires is also a trigger volume condition: { "Type": "ZigRequires", "Event": "ENTER", "Requires": { ... } } in an effect's Conditions lets the volume act only for a player who meets it, and says nothing to anyone else. Every boot, the library reads each pack's Server/TriggerVolumes/Effects/ files and logs one SEVERE line under [gate] audit for a ZigRequires condition that cannot be read, writes a key it does not know, or spells its Type slightly wrong, since the game would let everyone through such a volume. On an MMO Skill Tree server, /mmoconfig validate and its startup content audit list the same findings under gate, as ZigRequires volume validation.

From a character or a conversation: the Dungeon destination

{ "Type": "Dungeon", "Dungeon": "<Id>" } goes wherever an Open goes: a placement's Interact.Open, which runs on press F, or a conversation line's open action. The entry runs a moment later on the player's world. A player who is sent in has the page they have open closed as the loading screen takes them; a refused one reads why where they are looking. The Gravekeeper is placed this way:

{
  "Name": "Hallows_Eve_Gravekeeper_Temple",
  "Enabled": true,
  "Where": {
    "GameplayConfig": ["ForgottenTemple"]
  },
  "Identity": {
    "Role": "Hallows_Eve_Gravekeeper"
  },
  "Anchor": {
    "WorldSpawn": {
      "Offset": { "X": -7.5, "Z": 4.5 },
      "Yaw": 180.0
    }
  },
  "Season": "Hallows_Eve",
  "Lifecycle": {
    "KeepAlive": true,
    "Respawn": true,
    "Fortify": true
  },
  "Interact": {
    "Open": { "Type": "Dungeon", "Dungeon": "Hallows_Eve_Graveyard" }
  }
}

His role, Hallows_Eve_Gravekeeper, runs { "Type": "ZigPlacementInteract", "Open": { "Type": "Dungeon", "Dungeon": "Hallows_Eve_Graveyard" } } when pressed, so a Gravekeeper nothing placed, such as one spawned by command, opens the graveyard too. A press F has no chain to put a gate in front of, so to gate a character's way in, have them open a conversation whose line carries a Requires condition (the shared requirements block) and opens the Dungeon destination: the line shows only to players who meet it. See Conditions, Destinations and Placed NPCs.

What a refused player is told

Every way in tells a player who cannot go in why, in an error notice drawn into the page they have open or else in the corner. The words are in the library's ziggfreedcommon.dungeon.lang; the dungeon's name is its Text.NameKey.

A player never reads a pack author's mistake: the server log says what went wrong. An unknown dungeon id is logged once per id.

Runs: Run

• A run begins when the first player arrives in a fresh area. It counts that player and everyone already on the way in, and whoever arrives later joins it. The dungeon's leaves are read once, when the run begins, so an edit changes the next run, not this one.
• It fails when its time limit passes, when every member has left the area (nobody in it and nobody on the way), or, with FailOnWipe, when every member in the area is dead at once.
• When the time limit or a wipe fails it, everyone still in the area reads why: "Time ran out in The Horseman's Graveyard. The run failed." or "Your whole party fell in The Horseman's Graveyard. The run failed." A run that failed because everyone left tells nobody.
• A run that has ended, cleared or failed, takes nobody new. The area holds no new run until everyone has left it, and then it is pasted fresh for the next party, so a party that wants to go again leaves and goes back in.

The graveyard writes no Run: its runs have no time limit, and a party that falls carries on.

What clears a run: Complete

A run clears the moment every leaf you write holds. Write one or more of them: a dungeon whose Complete writes none has no clear, and its runs can only fail. A boss fight counts for the run of the area its players are in. The objective's fields are the ones on Objectives and criteria.

The graveyard writes Bosses alone, so its run clears when the Headless Horseman's fight, Hallows_Eve_Headless_Horseman_Encounter, is won. The library's own example of the other two leaves:

"Complete": {
  "Objective": { "Kind": "PICKUP_ITEM", "Target": "MyPack_Crypt_Relic", "Amount": 3 },
  "SurviveTimer": 300
}

With both written, the party must pick up three relics between them and last five minutes.

The completion Claim and the results screen: Rewards

At a clear, each member in the area earns one Claim: the table rolled once for them, titled with the dungeon's name (its Text.NameKey). Rewards are collected, never handed over unasked, so the Claim waits until the player takes it. A roll that lands nothing writes no Claim, and does not count as a clear for Diminish.

{
  "Name": "Hallows_Eve_Graveyard_Clear",
  "Rolls": [
    {
      "Grants": {
        "Rewards": [ { "Kind": "Currency", "Params": { "Currency": "Hallows_Eve_Sweets", "Amount": "10" } } ]
      }
    },
    {
      "Grants": {
        "Rewards": [ { "Kind": "Currency", "Params": { "Currency": "Seasons_Of_Orbis_Festival_Token", "Amount": "1" } } ]
      }
    }
  ]
}

With "Diminish": { "Steps": [1, 0.5], "Window": "Daily" }, a player's first clear of the graveyard each day pays this in full, and every later clear that day pays half of it. The day turns over at midnight UTC. The graveyard also writes "InChest": true, so its clear's Claim waits in the chest the Horseman leaves where he fell, beside his own.

The results screen

• Each member in the area at the clear sees the results screen: "Dungeon cleared", the run's time, what they and their party did (their damage to the bosses, the bosses beaten), and their completion reward with a Claim button.
• Claim hands the reward over and shows a notice of what they got, a reputation's gain included, the same notice as Claim on the Claims tab. Whatever does not fit in their bags, and a reward they leave, waits on the Claims tab in their menu.
• There is no Play Again button: a dungeon is entered again at its way in.
• A member who is dead or offline at the clear sees no screen, and their Claim waits on the Claims tab all the same.

The Horseman pays two more Claims of his own from his fight's script, his daily Claim and his Boss Kill Claim. Those are boss Claims, not the dungeon's: see A boss's Claim.

Block rules

In a copy of the library's template, survival and adventure players break, place and gather nothing, so every party finds its area as it was built. A player in creative mode can still break blocks by hand. What a survival player sees:

• Hitting a hard block shows the hit puff, but no crack, and the block never breaks.
• A plant vanishes for a moment and comes back.
• A blast still sets off explosive barrels, boomshrooms and traps, which react before the library can refuse the damage.

The rules come from the library's dungeon gameplay config:

{
  "Parent": "Default_Instance",
  "World": {
    "AllowBlockBreaking": true,
    "AllowBlockGathering": false,
    "AllowBlockPlacement": false
  },
  "Death": {
    "RespawnController": {
      "Type": "WorldSpawnPoint"
    },
    "ItemsLossMode": "None"
  },
  "Plugin": {
    "WorldEvents": {},
    "ZigBlockRules": {
      "CreativeOnlyBreaking": true
    }
  }
}

• World.AllowBlockBreaking is true because the game refuses every break while it is false, a creative player's included.
• Plugin.ZigBlockRules.CreativeOnlyBreaking (false unless set) then refuses every other breaker before the block takes damage: survival and adventure players, NPCs, explosions, and a projectile, which counts as whoever fired it. It also keeps a block-group cycling tool to creative.
• Set CreativeOnlyBreaking false to let everybody break, or AllowBlockBreaking false to let nobody.
• A World group you write replaces the parent's whole group, so write all three block switches. A Plugin group merges over the parent's.

For server owners: dungeons.json

{ "Hallows_Eve_Graveyard": { "Enabled": false } }

{ "Hallows_Eve_Graveyard": { "Share": { "AreasPerCopy": 2 }, "Copy": { "EmptyCloseSeconds": 30 } } }

A server owner changes any leaf of any dungeon this way, such as letting more players into an area, without touching the pack that ships it.

/zigdungeon

/zigdungeon list                            # every dungeon and how it is set up
/zigdungeon status                          # the copies open now: areas in use, players inside and on the way, tick time
/zigdungeon close hallows_eve_graveyard-1   # close a copy now; everyone inside goes back where they came in
/zigdungeon enter Hallows_Eve_Graveyard     # go in yourself, in an empty area

• enter takes you in as a party of one, in an empty area, through the same checks every way in makes. When it refuses, it says exactly why, such as the prefab path no pack ships.
• close refuses any world the library did not open as a dungeon copy.
• The permission nodes are derived from the names: ziggfreed.ziggfreedcommon.command.zigdungeon for the command and ziggfreed.ziggfreedcommon.command.zigdungeon.<verb> for each verb, and a verb needs both. Nobody holds them until you grant them, and the console holds everything.

Checking your work

The first time anyone tries to enter a dungeon after it loads, the library checks it for errors, and a dungeon with an error refuses entry: players read "cannot be entered right now". Each error is logged once under [dungeon] audit, saying what to fix. The whole audit, warnings included, runs at boot on a server started with the environment variable ZIGGFREEDCOMMON_AUDIT_ON_BOOT=1, which suits a test server. A switched-off dungeon is not audited.

A warning about a missing template, prefab, boss or table may only mean its pack is not installed on this server.

Counting runs: quests, achievements and Records

A quest step, a board contract or an achievement criterion can count dungeon runs, in one dungeon or in any, with one of four objective kinds:

The Target is dungeon: followed by the dungeon's Difficulty, so dungeon: with MatchMode PREFIX counts any difficulty. The Qualifier is the dungeon's id; leave it out to count every dungeon. A step that counts clears of the graveyard:

{
  "Kind": "INSTANCE_ROUND_WON",
  "Target": "dungeon:",
  "MatchMode": "PREFIX",
  "Qualifier": "Hallows_Eve_Graveyard",
  "Amount": 1
}

• Records has a Dungeons tab ranking the runs each player started, cleared and failed across every dungeon on the server. /zigstats show lists a player's lines for each dungeon and difficulty, such as Dungeon_Runs_Completed/dungeon:@Hallows_Eve_Graveyard for normal clears of the graveyard. A clear also counts as a round won. See Records.
• A boss fought inside a dungeon gets a tab of its own on Records' Boss Fights, named for the fight and the dungeon: "The Headless Horseman in The Horseman's Graveyard".

Known limits

• In a copy of more than one area, a player who strays out of their area (more than half a Spacing from its spot) stops being a member, and if they then die they get back up at the first area's spot.
• A block item whose BlockType carries a prefab list still pastes that prefab, even though placing blocks is refused.
• Creatures held in chunk sections outside the prefab's own survive the clear between parties.
• A Dungeon destination naming an id no file defines is caught only when someone first uses it, with one warning in the log.
• ZigEnterDungeon fires no EnterInstanceTeleporterEvent, the event the game's own instance portals fire.

Related

• Claims - the Claims tab, boss Claims and diminishing returns
• ZiggfreedCommon - what the library owns, its owner files and commands
• Objectives and criteria - the step shape an objective and a run counter use
• Placed NPCs - placements and what press F opens
• Records - the Dungeons tab and Boss Fights