Entities in dungeons

A dungeon has two kinds of living things, and they are handled differently.

	NPC	Combat mob
Entry	Dungeon NPC Instance	Dungeon Mob Spawn
What it is	Any Typewriter entity definition (Typewriter's own entities, MythicMobsNPC, BetterModel, and so on)	A real vanilla mob
Who sees it	The members of the run only	Everybody in the world, but it belongs to the run
When it appears	While the run exists	Once per run, the first time a member enters its room
Placement	spawnLocation (fixed) or an NPC marker (generated)	room + positions (fixed) or MOB markers (generated)

NPCs of a run

A Dungeon NPC Instance shows an NPC per run, in the world of that run, to the members of that run only. A player who is not a member (another run in the same shared world, or a player who left) sees nothing. A member who leaves the run loses the NPC at once.

1. Create the entity definition as usual (an entity of Typewriter, a MythicMobsNPC, a BetterModel...). Always pick it by reference, never by typing an id.
2. Add a Dungeon NPC Instance and set definition.
3. In a fixed dungeon, set spawnLocation: the position in the template world. The slot of the run shifts it. In a generated dungeon, place an NPC marker in a room template and point its npc field at the instance. The spawnLocation is ignored.

allowedDungeonIds lists the dungeon instances whose runs show the NPC. Empty means every run of every dungeon. In a fixed dungeon the same spawnLocation applies to every dungeon concerned, so restrict the list when the dungeons differ. In a generated dungeon the NPC is shown only in a run whose layout has an NPC marker pointing at it. If several markers (or several rooms) name the same instance, only the first one counts, in layout order.

group is empty by default: the audience is the members of the run, one NPC per run. Pick a group entry only to share one NPC among the members of that group inside the same run.

Limits of NPCs

• Activities use absolute positions. An entity activity (a path to walk, a patrol) is not shifted into the slot or the world of the run. Leave activity empty (the NPC stands still) unless you know the activity only uses relative movement.
• MythicMobsNPC: use ticking off, and a recent build. A MythicMobsNPC definition with ticking on creates a real mob per viewer. In dungeons, set ticking to off on the definition. The server then holds one carrier mob per member, each hidden from everybody who is not that member, and a click gives exactly one interaction for the right player. This needs MythicMobsNPC 5.0 or later (per-run visibility fix); older versions show the carrier to everyone or twice.
• A cinematic played by a MythicMobsNPC in a dungeon is untested.
• The NPC is hidden beyond the show range (showRange, or the default of entities) and comes back when the member walks closer. This is normal.
• Chest NPC anchors: a Dungeon Loot Chest in NPC placement opens when its npcAnchor entity is right-clicked.

Combat mobs

A Dungeon Mob Spawn makes real vanilla mobs appear.

When. Once per run, the first time a member enters the room (fixed dungeon) or the room of the marker (generated dungeon). They never respawn. Waves are made by the Dungeon Spawn Mobs action. In a fixed dungeon the room entry makes them appear even if the room's enterOnce is off, and only once per run.

Where.

• Generated dungeon: at each MOB marker of a room template that points at the entry. room and positions are ignored.
• Fixed dungeon: at positions, when a member enters room. With an empty room nothing happens automatically: only the Spawn Mobs action makes the entry appear. dungeonInstance restricts the entry to the runs of one dungeon.

What. entityType (any mob; ENDER_DRAGON and WITHER are refused with a warning in the log), count (1 to 50 per placement), spread (0 to 32 blocks), name, equipment with a drop chance per slot, attributes (health, damage, speed...), and randomizeData.

Safe by default. blockDamage, dropVanillaLoot and dropExperience are all off. Mobs break and burn nothing (an explosion still hurts players), drop only the equipment you gave them (with a drop chance of 0 unless you raise it), and give no experience. Loot of a dungeon comes from its chests. Dropped items stay in the world after the run, so keep dropVanillaLoot off in a SHARED_WORLD_SLOTS dungeon.

They belong to the run. They are removed when the run ends. A mob of a run never targets or hurts the players of another run, and the players of another run cannot hurt it. What a mob splits or turns into (slimes, magma cubes, a drowned zombie, a vex called by an evoker) belongs to the run too.

Peaceful. The game removes hostile mobs at once in a world set to Peaceful, so the extension does not spawn them there: only mobs of the hostile class are refused (zombies, but also slimes, ghasts, phantoms, shulkers...). Neutral and passive mobs still appear. The site stays owed, the refusal is logged once per site, and the mobs appear on a later entry once the difficulty is raised. Raise the difficulty of the world, or pick a non-hostile type. This behaviour is not yet verified in game.

Items and portals. A dungeon mob never picks up items (a player's dropped gear stays on the ground) and cannot leave through a portal: it stays in the run's world and still counts toward the cap.

Players of other runs. A mob of a run never targets or hurts the players of another run, and the players of another run are not meant to hurt it. In a shared world (SHARED_WORLD_SLOTS) this rests on filters rather than on separate worlds, so use an isolated mode when it matters.

The cap

maxAliveMobs on the Dungeon Instance is the most mobs alive at once in one run (default 150, at most 500; 0 means no mob appears). A placement that would go over it makes only the mobs that fit appear and says so in the server log. The rest stays owed (kept with the run, across reloads) and appears, as far as the cap then allows, the next time a member enters the room, never more than the count of the entry in all.

Death

• onDeath on the entry: triggers run each time one of its mobs dies, for the players chosen by deathRecipients (default KILLER_OR_MEMBERS).
• When a dungeon mob dies (on_dungeon_mob_death): an event you can listen to from anywhere, filtered by dungeon and by mob entry.
• Only the mobs the entry made count. A slime that splits gives one reward and one event, not one per piece. What comes out of a mob (pieces, vexes, babies, reinforcements) goes with the run but runs nothing.

Knowing a room is cleared

Dungeon Mobs Alive (dungeon_mobs_alive) counts the living mobs of the run, or of one entry. 0 does not mean the room is cleared: the cap may have held some back, and the mobs are counted again after a reload. Use the death event, then a Dungeon Clear Room action, to say a room is cleared.

Waves and scaling

By default one wave appears at once and the number of mobs does not depend on the players. Three groups of fields change that.

• Players. perExtraPlayer adds mobs at each placement for every player beyond the first: count + perExtraPlayer × (players − 1). maxCount is the ceiling (0 = no ceiling of its own; 50 per placement and the maxAliveMobs of the dungeon still apply). playerCountSource says who counts: PRESENT_IN_ROOM (default) the members of the run in the room when the mobs are triggered, RUN_MEMBERS the online members of the run.
• Pace. maxSimultaneous is the most mobs of one site alive at once (0 = all at once). The next ones appear as the first ones die. It covers the whole site, not each placement.
• Waves. waves is an ordered list. Each wave has its own count and perExtraPlayer, an optional entityType (otherwise the one of the entry; equipment, attributes and name always come from the entry), a start and delayTicks. AFTER_PREVIOUS_CLEARED starts the wave delayTicks after the previous waves are cleared; AFTER_DELAY starts it delayTicks after the previous wave started, cleared or not. With waves, the count of the entry is no longer used. A wave whose type is refused is skipped with a warning and the next one goes on. The Dungeon Spawn Mobs action starts the next wave of an entry with waves at once.

Triggers: onWaveStart and onWaveCleared on a wave, onWaveCleared on the entry (after each wave), and onCleared on the entry when the whole site is cleared. They run for every online member of the run, once per site and per event. The death triggers run first. A site is cleared when every wave has started and no mob is alive or waiting for room under the cap.

Reload

Waves do not survive a reload. A site that still owed mobs makes them appear in one batch (the count of the entry) the next time a member enters the room, with no event. Waves that had not started are lost.

A chest appears when every mob is defeated

1. Create a Dungeon Loot Chest where the chest should stand and turn manualMode on, so that it is not placed when the run starts.
2. Create a Loot Chest Trigger action whose chestEntry is that chest. Keep triggerMode on ONCE (once per run, even though the triggers run for every member). Add a sound and a particleEffect if you like.
3. On the Dungeon Mob Spawn, add the action to onCleared. To react from elsewhere, create an On Dungeon Mobs Cleared event, filter it with mob and put the action in its triggers.

The chest appears in the world of the run when the last mob of the site is defeated. For a chest after each wave, use onWaveCleared of the wave instead.

Limits at a glance

Limit	Value
Mobs per placement (count)	1 to 50
Scatter radius (spread)	0 to 32 blocks
Mobs alive per run (maxAliveMobs)	150 by default, 500 at most
Refused mob types	ENDER_DRAGON, WITHER
Appearance	Once per run per site, no respawn
NPC allowedDungeonIds empty	Every run of every dungeon
MythicMobsNPC definition	ticking off, MythicMobsNPC 5.0 or later
Living mobs = 0	Not "room cleared": the cap or a reload may hide owed mobs
Platform	Paper only, no Folia
NPC activity	Absolute positions, not shifted
Peaceful world	Hostile mobs are refused

Related

• Runs and world isolation
• Generated dungeons