API reference / @jsprismarine/prismarine / world/Level / Level
Class: Level
Defined in: prismarine/src/world/Level.ts:146
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:210
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:148
The folder name under worlds/, which is also the worlds.<name> key.
seed
readonlyseed:bigint
Defined in: prismarine/src/world/Level.ts:151
The seed every generated chunk, structure placement and carver in this level comes from.
Methods
beginChangeTick()
beginChangeTick():
void
Defined in: prismarine/src/world/Level.ts:894
Opens this tick of every ready world's change log, before the input step, so the inputs it applies land in the tick that applied them.
Returns
void
captureReplayInitialState()
captureReplayInitialState():
Promise<ReplayInitialStateManifest>
Defined in: prismarine/src/world/Level.ts:667
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.
closeTick()
closeTick(
tick):undefined
Defined in: prismarine/src/world/Level.ts:905
Closes the tick of every world whose change log tick is still open, for a level the ticker did not update, such as a frozen one. A world that throws is logged, and the worlds after it still close theirs.
Parameters
tick
number
The server tick.
Returns
undefined
customDimensionDefinitions()
customDimensionDefinitions():
object[]
Defined in: prismarine/src/world/Level.ts:579
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:365
The dimension type a stem binds.
Parameters
dimensionId
string
Returns
DimensionType
Throws
When no stem has that dimension id.
getDimensionTypes()
getDimensionTypes():
ReadonlyMap<string,DimensionType>
Defined in: prismarine/src/world/Level.ts:351
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:649
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:356
The generator kinds this level builds its stems with.
Returns
getName()
getName():
string
Defined in: prismarine/src/world/Level.ts:331
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:1113
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 playerKeyOf.
Returns
Promise<Partial<WorldPlayerData> | null>
The record, or null when this save has none for the key.
getPlayerPersistence()
getPlayerPersistence():
PlayerPersistence
Defined in: prismarine/src/world/Level.ts:1103
Where this level's player records are read and written; see PlayerPersistence.
Returns
PlayerPersistence
getProvider()
getProvider():
BaseProvider
Defined in: prismarine/src/world/Level.ts:341
The one provider every dimension of this save reads and writes through.
Returns
BaseProvider
getRespawnSearch()
getRespawnSearch():
RespawnSearch
Defined in: prismarine/src/world/Level.ts:1098
Where this level's players come back after a death; see RespawnSearch.
Returns
RespawnSearch
getServer()
getServer():
Server
Defined in: prismarine/src/world/Level.ts:336
The server this level belongs to.
Returns
getSpawn()
getSpawn():
Vector3|null
Defined in: prismarine/src/world/Level.ts:754
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:346
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:639
The level's clock, in ticks since it was created.
Returns
number
getWeather()
getWeather():
WorldWeather
Defined in: prismarine/src/world/Level.ts:654
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:764
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:772
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:431
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
pendingSave()
pendingSave():
Promise<void>
Defined in: prismarine/src/world/Level.ts:947
Settles once the pass whose cut is taken has committed, or at once when none is pending; see LevelSave.pendingCommit.
Returns
Promise<void>
prepareWorld()
prepareWorld(
dimensionId):Promise<void>
Defined in: prismarine/src/world/Level.ts:454
Starts building the world of one dimension outside every tick, so a tick that needs it does not wait, and whatever the build loads waits for an input step. A world built or building already is left alone. A failed build is logged, and the next call starts it again.
Parameters
dimensionId
string
The stem's key.
Returns
Promise<void>
The build, which settles once the world is ready or the build failed.
readyWorld()
readyWorld(
dimensionId):World|undefined
Defined in: prismarine/src/world/Level.ts:441
The world of one dimension once its enabling has finished, or undefined. Nothing is built.
What a tick reads when it needs another dimension: a tick never waits for a build, so it asks Level.prepareWorld for one and reads this again at a later input step.
Parameters
dimensionId
string
Returns
World | undefined
readyWorldOfType()
readyWorldOfType(
typeId):World|undefined
Defined in: prismarine/src/world/Level.ts:483
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:717
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:930
Writes the whole level in one pass: every loaded world's players and chunks, and the level data. See LevelSave.save.
Returns
Promise<void>
saveLevelData()
saveLevelData():
Promise<void>
Defined in: prismarine/src/world/Level.ts:959
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. Queued behind a pass that is running; see LevelSave.saveLevelData.
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:1122
Writes one player's record; see PlayerPersistence.save.
Parameters
key
string
data
requireSuccess?
boolean = false
Propagate a persistence error when creating a replay checkpoint.
Returns
Promise<void>
saveWorlds()
saveWorlds(
worlds):Promise<void>
Defined in: prismarine/src/world/Level.ts:939
Writes some of the level's worlds in one pass, with the level data: their players and changed chunks. A world asks for this to save itself.
Parameters
worlds
readonly World[]
The worlds, ready or not.
Returns
Promise<void>
setSpawn()
setSpawn(
at):void
Defined in: prismarine/src/world/Level.ts:759
Sets the world spawn; see Level.getSpawn.
Parameters
at
Returns
void
setTicks()
setTicks(
tick):void
Defined in: prismarine/src/world/Level.ts:644
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:1020
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:1003
The raids the save held, which the Overworld's raid manager starts from.
Returns
RaidRecord[]
update()
update(
tick):undefined
Defined in: prismarine/src/world/Level.ts:865
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.
A world whose update throws is logged with its name, and the worlds after it still tick. One broken dimension then costs that dimension its tick and never another's.
Parameters
tick
number
The server's tick counter, which the worlds pace their own work by.
Returns
undefined
world()
world(
dimensionId):Promise<World>
Defined in: prismarine/src/world/Level.ts:388
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:471
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:1077
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:786
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>