API reference / @jsprismarine/prismarine / Level
Class: Level
Defined in: prismarine/src/world/Level.ts:141
One save: a seed, a provider, a dimension set, and the state Bedrock keeps once per level.
Level.enable opens the provider and reads the saved state; Level.world builds a dimension's world when it is first asked for; Level.update advances the clock once per server tick and ticks every loaded world; Level.disable saves and closes.
Constructors
Constructor
new Level(
options):Level
Defined in: prismarine/src/world/Level.ts:201
Parameters
options
Returns
Level
Throws
When the stems have no minecraft:overworld, a stem names a dimension type that dimensionTypes does not carry, or two stems bind one type.
Properties
name
readonlyname:string
Defined in: prismarine/src/world/Level.ts:143
The folder name under worlds/, which is also the worlds.<name> key.
seed
readonlyseed:bigint
Defined in: prismarine/src/world/Level.ts:146
The seed every generated chunk, structure placement and carver in this level comes from.
Methods
captureReplayInitialState()
captureReplayInitialState():
Promise<ReplayInitialStateManifest>
Defined in: prismarine/src/world/Level.ts:609
Saves and captures the provider-backed initial state for a replay.
The provider snapshot includes persisted records for loaded and unloaded chunks. Restore it into a fresh provider before that provider opens, then validate and restore the random state with Level.restoreReplayRandomState.
Returns
Promise<ReplayInitialStateManifest>
Throws
When the provider cannot capture replay snapshots or persisted state cannot be saved.
customDimensionDefinitions()
customDimensionDefinitions():
object[]
Defined in: prismarine/src/world/Level.ts:521
The DimensionDefinition of every custom dimension, for DimensionDataPacket.
A dimension type the Bedrock overlay does not list is one the client has never heard of, so it has to be told the bounds and the id the level chose, from FIRST_CUSTOM_DIMENSION_ID in stem order. The generator type is Void, as Dragonfly sends it: the client generates nothing for a dimension a server feeds it.
Returns
object[]
One entry per custom dimension type, in stem order; empty for a vanilla level.
dimensionTypeOf()
dimensionTypeOf(
dimensionId):DimensionType
Defined in: prismarine/src/world/Level.ts:337
The dimension type a stem binds.
Parameters
dimensionId
string
Returns
Throws
When no stem has that dimension id.
getDimensionTypes()
getDimensionTypes():
ReadonlyMap<string,DimensionType>
Defined in: prismarine/src/world/Level.ts:323
The dimension types the stems use, by type id, with their Bedrock ids resolved.
Returns
ReadonlyMap<string, DimensionType>
getGameRuleManager()
getGameRuleManager():
GameRuleManager
Defined in: prismarine/src/world/Level.ts:591
The level's game rules, one set for every world of the save.
Returns
GameRuleManager
getGeneratorFactories()
getGeneratorFactories():
GeneratorFactories
Defined in: prismarine/src/world/Level.ts:328
The generator kinds this level builds its stems with.
Returns
getName()
getName():
string
Defined in: prismarine/src/world/Level.ts:303
The level's folder name, which is what the tick loop and the logs call it.
Returns
string
getPlayerData()
getPlayerData(
key):Promise<Partial<WorldPlayerData> |null>
Defined in: prismarine/src/world/Level.ts:968
The record for one player, from the provider's player storage or the fallback JSON file.
Parameters
key
string
What the record is filed under; see World.playerDataKey.
Returns
Promise<Partial<WorldPlayerData> | null>
The record, or null when this save has none for the key. A provider read that fails is logged and falls through to the file.
getProvider()
getProvider():
BaseProvider
Defined in: prismarine/src/world/Level.ts:313
The one provider every dimension of this save reads and writes through.
Returns
getServer()
getServer():
Server
Defined in: prismarine/src/world/Level.ts:308
The server this level belongs to.
Returns
getSpawn()
getSpawn():
Vector3|null
Defined in: prismarine/src/world/Level.ts:697
The world spawn if it is known, and null while it is not.
Bedrock's SpawnX/Y/Z is one point per save and it is in the Overworld, so the Overworld world searches for it and every world reads it from here.
Returns
Vector3 | null
getStems()
getStems():
ReadonlyMap<string,LevelStem>
Defined in: prismarine/src/world/Level.ts:318
The resolved level stems by dimension id, in the order the level was given them.
Returns
ReadonlyMap<string, LevelStem>
getTicks()
getTicks():
number
Defined in: prismarine/src/world/Level.ts:581
The level's clock, in ticks since it was created.
Returns
number
getWeather()
getWeather():
WorldWeather
Defined in: prismarine/src/world/Level.ts:596
The level's weather: one cycle for the whole save, rendered where there is a sky.
Returns
WorldWeather
isClosed()
isClosed():
boolean
Defined in: prismarine/src/world/Level.ts:707
Whether Level.disable has closed the provider, after which nothing can be read or written.
Returns
boolean
legacyEntities()
legacyEntities(): readonly
LegacyWorldEntity[]
Defined in: prismarine/src/world/Level.ts:715
Entity snapshots the save kept outside its chunks, which a provider without actor storage wrote for the Overworld. Empty once a chunk-storing provider owns the save.
Returns
readonly LegacyWorldEntity[]
loadedWorld()
loadedWorld(
dimensionId):World|undefined
Defined in: prismarine/src/world/Level.ts:403
The world of one dimension if the level has built it, whether or not its enabling has finished; undefined otherwise. Nothing is built.
The one accessor that answers a world mid-enable, which is how WorldManager names the default world while its start region generates. Level.worlds lists ready worlds only.
Parameters
dimensionId
string
Returns
World | undefined
readyWorldOfType()
readyWorldOfType(
typeId):World|undefined
Defined in: prismarine/src/world/Level.ts:425
The ready world whose dimension type has this id, or undefined.
Level.worlds filtered by type, without the iterator: the content adapter asks on every block it reads, which made the lookup one of the busier calls of a tick.
Parameters
typeId
string
Returns
World | undefined
restoreReplayRandomState()
restoreReplayRandomState(
manifest):void
Defined in: prismarine/src/world/Level.ts:660
Verifies a matching initial boundary and restores only its random streams.
Parameters
manifest
Returns
void
save()
save():
Promise<void>
Defined in: prismarine/src/world/Level.ts:826
Writes the whole level: every loaded world's players and chunks, then the level data.
Returns
Promise<void>
saveLevelData()
saveLevelData():
Promise<void>
Defined in: prismarine/src/world/Level.ts:839
Writes the level's own state through the provider: the spawn, rules, weather and stems into the provider's record, and the spawn, clock, generator and Nether scale into level.dat.
A level whose spawn is still unknown writes everything else and leaves the stored spawn where it is. Overwriting a real spawn point with a guess would be worse than the gap.
Returns
Promise<void>
savePlayerData()
savePlayerData(
key,data,requireSuccess?):Promise<void>
Defined in: prismarine/src/world/Level.ts:996
Writes one player's record, through the provider when it stores players and into the fallback JSON file otherwise.
Declined once the level has closed. A shutdown kicks everyone, and each client's connection closes some time after the provider has gone, so a save arrives once more per player with nothing left to write to; the shutdown's own save wrote them while they were still online.
Parameters
key
string
data
requireSuccess?
boolean = false
Propagate a persistence error when creating a replay checkpoint.
Returns
Promise<void>
setSpawn()
setSpawn(
at):void
Defined in: prismarine/src/world/Level.ts:702
Sets the world spawn; see Level.getSpawn.
Parameters
at
Returns
void
setTicks()
setTicks(
tick):void
Defined in: prismarine/src/world/Level.ts:586
Sets the clock, which is what /time set does.
Parameters
tick
number
Returns
void
storedDragonFightState()
storedDragonFightState():
DragonFightState|undefined
Defined in: prismarine/src/world/Level.ts:896
The dragon fight the save held, which the End world's fight starts from.
Returns
DragonFightState | undefined
storedRaids()
storedRaids():
RaidRecord[]
Defined in: prismarine/src/world/Level.ts:879
The raids the save held, which the Overworld's raid manager starts from.
Returns
RaidRecord[]
update()
update(
tick):Promise<void>
Defined in: prismarine/src/world/Level.ts:805
One server tick: the clock advances once, the weather cycle runs, and every loaded world updates against the new tick.
The weather goes before the worlds for the reason ServerLevel.tick runs advanceWeatherCycle before its tick lists: a fire scheduled this tick should be put out by rain that started this tick.
The worlds tick one after another in stem order, as MinecraftServer.tickChildren walks its levels, rather than interleaved. An entity that leaves one world for another during its update is then in exactly one world's roster at any point of the tick; a world ticked later skips an arrival that was already ticked this tick.
Parameters
tick
number
The server's tick counter, which the worlds pace their own work by.
Returns
Promise<void>
world()
world(
dimensionId):Promise<World>
Defined in: prismarine/src/world/Level.ts:360
The world of one dimension, built and enabled on first request.
The first call for a dimension asks the factories for the stem's generator, builds the world and enables it; every later call answers the same instance once that enabling has finished. Two overlapping first calls share one build. A world whose enabling failed is forgotten, so the call after the failure builds it again rather than answering the same rejection for the life of the level. Only an eager stem's world generates its start region here; a lazy one is built from inside a server tick and leaves its first chunks to whoever arrives.
Parameters
dimensionId
string
The stem's key, minecraft:the_nether for the Nether. The vanilla stems share their dimension type's id.
Returns
Promise<World>
Throws
Before Level.enable, when no stem has that id, or when the stem's generator cannot be built or the world cannot be enabled.
worlds()
worlds():
IterableIterator<World>
Defined in: prismarine/src/world/Level.ts:413
Every world whose enabling has finished, in build order.
A world still enabling is left out: it has no players, it must not tick before its start region is settled, and WorldManager.getWorldByDimension promises loaded worlds only.
Returns
IterableIterator<World>
Lifecycle
disable()
disable():
Promise<void>
Defined in: prismarine/src/world/Level.ts:948
Saves and closes: every world stops and writes itself, the level data goes out once more, and the provider is closed last, once nothing is left that could ask it for anything.
Returns
Promise<void>
enable()
enable():
Promise<void>
Defined in: prismarine/src/world/Level.ts:729
Opens the provider, reads the saved state and builds the eager worlds.
The eager worlds are constructed before the first await, so a caller that starts this and needs one of them at once, as WorldManager needs the default world, finds it through Level.loadedWorld while the provider is still opening.
Returns
Promise<void>