Dungeon runtime

The native dungeon runtime owns session membership, instance placement, encounter progress and temporary upgrades on the server. Its durable state is one aggregate; player components and client screens are projections of that state.

What it does

internal.dungeon is an internal subsystem, not a public DungeonAPI facade. DungeonSessionManager.init() installs tick, connection, death and entity-load hooks, bootstraps powerups and installs void recovery. Definitions come from DungeonDefinitionLoader; the complete authoring contract is in dungeon data.

DungeonWorldPolicy treats the built-in isekaiexpansion:dungeon_instance and every dimension referenced by a loaded definition as dungeon worlds. This policy is dimension-wide, not restricted to a placed instance’s bounding box.

Runtime model

Entry, placement and membership

tryEnter rejects spectators, an already-active participant and unknown definitions. It reuses an active session matching definition ID and physical GlobalPos entrance, otherwise allocates that entrance a stable slot and creates a session. The recorded party key uses the player UUID for SOLO, otherwise the quest team resolver; admission does not compare this key when reusing the gateway.

Slots map to a grid: column is floorMod(slot, 2048), row is floorDiv(slot, 2048); origin is column/row times authored spacing at authored base Y. Removing a session retains its entrance allocation. Slots are not reclaimed and are independent of the player’s dimension or team.

DungeonStructureService plans the Jigsaw graph, validates pieces and anchor coverage, checks the 256-chunk layout and 1024-chunk guarded preload budgets, then places synchronously. The guard is 1 chunk. Placement random uses world seed, anchor and definition ID; planning uses Minecraft’s structure context. There are no retained chunk tickets in this service.

The service searches for a safe entry before the first participant binds and stores exact feet coordinates as bottom-centre plus 0.02 blocks. Search bounds are 8 horizontal and 8 vertical blocks. Once participants exist, setSpawnPosition throws. An unsafe persisted arrival can trigger deterministic layout restoration, but restoration must make the same saved arrival safe.

After placement, a new session resets referenced gate controllers, binds the player and teleports them. Failed placement removes a newly created session; failed entry unbinds the player and removes the session if empty. Successful entry dispatches SESSION_STARTED for a new session, then PLAYER_ENTERED, with their corresponding scripts.

Teleportation clears velocity and fall distance. The player moves first; only then does NpcFollowerSync.transferFollowersToPlayer transfer loaded followers using its own placement rules. Return uses the entrance’s bottom-centre plus 0.02 blocks and resets portal cooldown. A missing return dimension or failed teleport leaves the participant bound for later recovery.

Ticking, hazards and completion

The server uses overworld game time. Each tick removes empty sessions, ignores resolved sessions, and fails active sessions whose definition disappeared or timed deadline expired. Deadline checks run even when all participants are offline.

Ordinary scripts and hazards need an online participant in the session dimension. TICK scripts run every 20 ticks. Extraction is represented by a positive completion deadline while status remains ACTIVE; it suspends hazard/tick processing and completes only when that deadline is reached with a participant present. The original timed deadline is evaluated first.

Hazards save a snapshot of their waves. A batch is attempted once, then the spawn index advances. Each spawn searches with 48 attempts, radius up to 3 blocks and vertical depth/delta 2, around anchors on a 1.25-block ring. Mobs initialise with SpawnReason.EVENT, become persistent, then receive authored NBT while preserving transform/UUID. Entities with nonempty authored NBT receive the equipment-preservation tag; every spawn receives the ise_dungeon_hazard:<sessionUUID>:<hazardUUID> ownership tag.

The in-memory entity index accelerates death callbacks. A 10-tick liveness check removes loaded dead/removed entities; an unloaded UUID remains pending. Entity-load reconciliation discards tagged entities whose session/hazard no longer exists or whose dimension is wrong, and reattaches valid entities to the hazard. Once the final hazard is removed, the runtime emits HAZARD_CLEARED, runs scripts and offers eligible powerups.

Completion first sets COMPLETED, emits SESSION_FINISHED, then cleans hazards. Each online participant receives the advancement and quest-completion trigger, clears powerups and attempts return/departure. Failure sets FAILED, emits the finish event when a definition and initiator are available, and returns online participants without completion credit. Both clear remaining persisted upgrade/offer progress; a session remains while offline or unsuccessfully returned participants are still bound.

Offline participants do not receive deferred completion credit on reconnect. A reconnect to a resolved session clears the transient component and attempts return/departure; reconnecting to an active session restores normalised levels, HUD and a pending offer. Disconnect stashes component levels and clears the mirror without removing membership. It does not pause the deadline.

Death and void recovery

PlayerManagerDungeonRespawnMixin wraps vanilla player recreation. DungeonRespawnController.prepare captures the original spawn settings before the dead entity is removed. For MUST_COMPLETE, it validates/restores the layout and supplies the saved session spawn through a temporary vanilla spawn point. The wrapper restores the old player’s original spawn in finally; finishing also restores the replacement player’s settings.

After vanilla registers the replacement, the controller enforces the exact target. Same-world drift above squared distance 1.0E-6 uses a network teleport correction; a wrong dimension uses Fabric teleportation. It clears motion/fall distance and restores the session component, HUD and pending offer. Failure to prepare/enforce the target fails the session while leaving the just-respawned player at their vanilla result.

Without MUST_COMPLETE, ordinary death follows vanilla respawn and removes that participant without teleporting them back to the gateway; other participants can continue. Out-of-world damage in a valid must-complete session is handled separately: damage is cancelled and an end-tick forced exit is queued. This bypasses the voluntary return-portal restriction.

World protection and client presentation

Dungeon-world hooks cancel natural spawning, keep blocks during explosions, restrict noncreative block breaking/placement and fluid placement, and deny generic entity block modification. These are specific hook protections, not a claim that every other mod’s direct world mutation is intercepted.

The HUD packet sends title, difficulty, session identity and session/extraction intervals, not the complete persistent session. Client state uses an immutable volatile snapshot. The ModernUI overlay hides while a screen is open, HUD is disabled or no future countdown exists; extraction takes display priority over the session timer.

DungeonCountdownClock interpolates a captured game-time interval with monotonic time at 20 ticks per second. This is presentation only: server game time remains authoritative, so lag or pause can make the display diverge. The powerup screen does not pause and refuses ordinary closure; selecting sends intent and begins its own exit animation without waiting for a server acknowledgement.

Aggregate NBT

The overworld file is data/isekaiexpansion/dungeon/runtime_v2.dat, opened through IsekaiPersistData. No former split-file store is read or migrated. The tables name the payload inside this state; block-entity and item NBT are documented separately in the authoring page.

Aggregate and allocations

Session records

Participant and hazard records

The participant-to-session index and next-slot counter are reconstructed, not serialized. Loading validates allocation/session correspondence, rejects duplicate session IDs and resolves cross-session participant duplicates by newest StartedAt first, removing older memberships and marking the repair dirty. Equal start times follow the underlying stable iteration order.

Malformed nested participant, hazard or script data can discard the enclosing session. Allocation/session errors are isolated per record; an unsupported root version discards everything. The loader does not import old filenames, infer missing spawn coordinates or reconstruct a missing allocation from a session.

Portal entities additionally save DungeonSession as an optional UUID and DungeonTheme as ENTRANCE, INNER_RETURN or HAZARD; missing/invalid theme becomes HAZARD. These are entity records, not another authority for membership.

Contracts

Mutate on the server thread. DungeonRuntimeState owns membership/index consistency and dirty tracking; get, all and session accessors can expose live mutable session objects. The collection returned by all is copied, but its sessions are not. Use addParticipant, removeParticipant and progress setters, and call markChanged after direct session mutations. Managed-session checks require the exact object held by the aggregate.

DungeonEvents exposes internal SESSION_STARTED, PLAYER_ENTERED, HAZARD_CLEARED and SESSION_FINISHED notifications. Contexts contain live session/definition references and a triggering player. They are not cancellable access checks, and the array-backed listener loops do not catch listener exceptions. Scripts also run actions before recording replay memory without a general exception barrier or rollback.

All network channels below have the isekaiexpansion: prefix:

HUD handling and powerup-screen opening marshal to the client thread; ModernUI view changes then use the UI thread. Editor permissions are server-checked. The gateway update has no distance check, unlike the other two editor updates.

Extending it

Definitions refer to code-registered DungeonRoguePowerup implementations. Register during common setup through DungeonRoguePowerupRegistry.register: null values, mismatched presentation ID and duplicate IDs reject. DungeonPowerupProgression.unique() means one level; stackable(maxLevel) requires at least 2. Restoration clamps known IDs to their registered level limits and discards unknown IDs from the transient component.

Implement onGranted, onEvent and onRemoved with the lifecycle in mind. Grant persists the advanced level before calling onGranted, and clears the pending offer only after a successful return. A throwing hook can therefore leave partially applied state. Reconnect/respawn restores levels without replaying onGranted; disconnect clears the mirror without onRemoved. Do not use those hooks as a guaranteed symmetric resource-acquisition pair.

Events include effective damage taken/dealt, player-credited enemy defeat and the IsekaiCore second interval. Dispatch requires active membership in the correct dimension. The built-in effects and authored pool fields are listed in dungeon data.

The script action vocabulary is an enum and switch, not a parser registry. Adding an action requires coordinated parser/record/runtime work and both language references. Adding a hazard side effect also needs saved-state and restart behaviour; a live entity UUID alone is not persistent encounter authority.

Operator commands

Commands live under /isekaiexpansion dev dungeon, also available through /ise dev dungeon, and require permission level 2. All except list require a player source.

Verifying

• Enter one physical gateway from unrelated parties, and a second gateway to the same definition; confirm the documented reuse and distinct allocation behaviour.
• Check missing pools/connectors, layout/preload budgets, blocked arrival restoration and a failed return dimension without losing membership.
• Restart during a delayed batch, with unloaded living entities, a partially unlocked gate, script cooldown and pending powerup choices.
• Test timed expiry with everyone offline, extraction with nobody in the dungeon, and expiry before extraction finishes.
• Complete with online/offline participants; confirm who receives advancement/quest credit and that resolved records survive until all departures succeed.
• Test ordinary death, must-complete death, original spawn restoration on exceptions, wrong-dimension correction and queued void exit.
• Round-trip every aggregate record; reject root-version drift, missing finite spawn, duplicate allocations/sessions, mismatched slots and malformed nested records. Check newest-session duplicate-member repair.
• Exercise duplicate/late powerup submissions and throwing grant/listener hooks; verify persisted state and pending offers instead of assuming rollback.
• Check HUD and powerup UI across disconnect, pause/lag and changing language, with server deadlines as the reference.

Related

• Dungeon data and authoring — every definition and authoring field.
• Persistent state storage — shared storage keys and world scope.
• Quest runtime — completion credit dispatch.
• NPC followers — squad transfer and arrival placement.