Skip to content
Conduit

Runtime dimensions

RuntimeDimensions builds a fresh ServerLevel at runtime, registers it on the server, and tears it down cleanly when you’re done. It’s the core of conduit-instance.

When to use it

Section titled “When to use it”
  • Spin up an isolated world the instant a match starts.
  • Destroy it the instant the match ends — no idle dimensions, no fixed ceiling.
  • Build the world from a spec: a void arena, or a copy of an existing level’s terrain rules.

API

Section titled “API”
// Create — returns a handle you hold for the match's lifetime.
RuntimeDimensionHandle create(MinecraftServer server, RuntimeDimensionSpec spec);


// Release — always destroys: evacuates players (with force), deletes
// the world's files, removes the dimension. Returns false (no-op) if a
// player is still inside and force is false.
boolean release(MinecraftServer server, RuntimeDimensionHandle handle);
boolean release(MinecraftServer server, RuntimeDimensionHandle handle, boolean force);


// Keys of all currently-active runtime dimensions.
Set<ResourceKey<Level>> active();

Every runtime dimension is keyed conduit:rt-<n>. Both calls must run on the server thread.

Example

Section titled “Example”
import me.zlex.conduit.instance.runtime.RuntimeDimensions;
import me.zlex.conduit.instance.runtime.RuntimeDimensionSpec;
import me.zlex.conduit.instance.runtime.RuntimeDimensionHandle;


// Match start: a fresh void arena.
RuntimeDimensionHandle arena = RuntimeDimensions.create(
        server, RuntimeDimensionSpec.voidWorld(server));


ServerLevel level = arena.level(server);
// …build the arena from a prefab, teleport players in, run the round…


// Match end: tear it down. force=true evacuates any stragglers to the
// overworld spawn before removing the dimension.
RuntimeDimensions.release(server, arena, /* force */ true);

Lifecycle

Section titled “Lifecycle”

Create builds a LevelStem from the spec, constructs a ServerLevel under a fresh conduit:rt-<n> key, inserts it into the server’s level map, and fires ServerLevelEvents.LOAD. If the spec is persist=true, the world is also recorded in the manifest (see below).

Release always destroys the world — persist does not protect against it. It evacuates players (with force), fires ServerLevelEvents.UNLOAD, removes the dimension from the level map, closes the level without saving, deletes its region files, and drops it from the manifest. If you want a world back later, don’t release it.

Restart survival (persist)

Section titled “Restart survival (persist)”

The persist flag on the spec controls whether a world returns after a server restart — nothing else:

  • persist=true worlds are recorded in a manifest at <world>/conduit_runtime_dimensions.json (stem + seed). On the next SERVER_STARTED they’re recreated under their original key, and the rt-<n> counter is advanced past them so new keys never collide.
  • On clean shutdown, persistent worlds are saved and kept; non-persistent temp worlds are force-released and deleted.

Safety

Section titled “Safety”
  • Never removes a world a player stands in without force. A level pulled out from under a player crashes chunk tracking; release returns false and logs a warning instead. With force, it evacuates stragglers to the overworld spawn first (via SafeTeleport).
  • Manifest-aware orphan sweep on server start — after persistent worlds are restored, any leftover conduit:rt-* dimension folder whose key isn’t active (a temp world from a crashed run) is deleted. Restored worlds are active, so they’re kept.
  • Shutdown cleanup on SERVER_STOPPING saves + keeps persistent worlds and force-releases (deletes) the temp ones, so discard worlds never linger.
  • All mutation runs on the server thread; never mutate the level map mid-tick from elsewhere.

Notes

Section titled “Notes”

The one accessor mixin (MinecraftServerLevelsAccessor) is the only bytecode-level surface — it exposes the server’s private level map, executor, and storage handle. It’s the single thing to re-validate on a Minecraft version bump; accessors are the most stable kind of mixin.

Section titled “Related”