API reference / @jsprismarine/prismarine / World
Class: World
Defined in: prismarine/src/world/World.ts:501
Implements
Constructors
Constructor
new World(
__namedParameters):World
Defined in: prismarine/src/world/World.ts:641
Parameters
__namedParameters
Returns
World
Properties
ITEM_ENTITY_LIMIT
readonlystaticITEM_ENTITY_LIMIT:2048=2048
Defined in: prismarine/src/world/World.ts:2764
The most dropped stacks one world keeps on the ground at once.
Neither edition publishes a number like this, and neither needs one. Java bounds its item entities with a 6000-tick despawn, and both editions merge stacks that land together, which this server does too in entity/other/Item.ts. What neither bounds is a burst. BlockUpdateScheduler lets one tick process 4096 positions, every one of which can destroy a block and roll its loot table, and a world that has just generated hundreds of chunks has that much work waiting in it. The reported crash was over 10,000 stacks on the ground, each one falling, comparing itself against its neighbors to merge, and going out to every player in range, every tick.
The number is this server's own judgement rather than anything Mojang publishes: well past what play produces, well short of what the per-tick merge pass can carry.
Methods
addEntity()
addEntity(
entity):Promise<void>
Defined in: prismarine/src/world/World.ts:3011
Adds an entity body to the level. Generic bodies a data runtime can build are handed to it first; its replacement body re-enters here after the runtime has indexed it, so the replacement is added normally.
Parameters
entity
The entity to add.
Returns
Promise<void>
addGameEventListener()
addGameEventListener(
listener): () =>void
Defined in: prismarine/src/world/World.ts:3444
Registers a listener for Java game events in this dimension.
Listeners are stored in the chunk section containing their position. Call World.moveGameEventListener after a dynamic listener moves.
Parameters
listener
GameEventListener
Returns
A function that unregisters the listener.
() => void
announceGameRule()
announceGameRule(
name,value,editable):Promise<void>
Defined in: prismarine/src/world/World.ts:3802
Tells everyone in this world that a game rule changed. Called by the level, whose rules these are, for each of its worlds.
Parameters
name
string
value
number | boolean
editable
boolean
Returns
Promise<void>
attachChangeSink()
attachChangeSink(
sink):void
Defined in: prismarine/src/world/World.ts:701
Gives this world somewhere to report its changes.
Attached from outside rather than built here, for the same reason a player does not build its own session: the world would otherwise have to know the network layer exists in order to construct a piece of it.
Parameters
sink
WorldChangeSink
Where changes go from now on.
Returns
void
blockEntityChanged()
blockEntityChanged(
position,tags):void
Defined in: prismarine/src/world/World.ts:2124
Reports that the block entity at a position is now these tags.
What makes this world a import('../blockentity/blockEntityWrite').BlockEntityWorld, so that every block entity write goes through one place and reaches the clients holding the chunk. Called by writeBlockEntity and by nothing else: it reports rather than writes, and calling it without having written the chunk tells a client something that is not true.
Parameters
position
The block the block entity sits in.
tags
Its complete data, as the chunk would serialize it.
Returns
void
breakBlock()
breakBlock(
position,player?):Promise<boolean>
Defined in: prismarine/src/world/World.ts:2186
Destroys the block at a position: takes it out of the world, tells every player, and plays the break where it stood.
Deliberately idempotent - a position already holding air is left alone and reported as false. Which packet announces a break depends on the breaking mode and the game mode. With server-authoritative block breaking, the default, survival reports a PREDICT_DESTROY_BLOCK in the tick's PlayerAuthInputPacket. With the client timing breaks, survival sends an InventoryTransaction, on its own or inside the input. Creative sends a PlayerAction in either mode, and a client is free to send more than one. Rather than guess which one to trust, every route calls this, and whichever arrives second finds the work already done. That is what keeps the break from sounding twice.
Parameters
position
the block to destroy.
player?
who broke it, when a player did. Decides what it drops.
Returns
Promise<boolean>
true if a block was there and is now gone.
broadcastMove()
broadcastMove(
entity,teleport?):Promise<void>
Defined in: prismarine/src/world/World.ts:3364
Tells everyone in this world that an entity has moved.
Queued rather than sent, and flushed once at the end of the tick - see PlayerSession.queueMoveActor, which explains why sending each one on its own made mobs move in fits and starts. A move outside the tick waits at most one tick, which is fifty milliseconds and below anything a player can see.
Parameters
entity
The entity that moved.
teleport?
boolean = false
Whether clients should snap instead of interpolate.
Returns
Promise<void>
dataEntities()
dataEntities():
LiveEntityRuntime
Defined in: prismarine/src/world/World.ts:3422
The data-driven entities of this world's dimension.
What drives every mob's behavior: its components, its goals, its brain, the spawn cycle and the despawn pass.
Returns
LiveEntityRuntime
This dimension's runtime.
dragonFightSaveState()
dragonFightSaveState():
DragonFightState|undefined
Defined in: prismarine/src/world/World.ts:2508
The fight's persistable state, without creating a fight that never ran.
The level's save reads this; a world whose fight was never asked for answers undefined, and the level keeps whatever the save already held.
Returns
DragonFightState | undefined
dropContents()
dropContents(
position,contents):Promise<void>
Defined in: prismarine/src/world/World.ts:2799
Puts items on the ground at a position, one entity each.
Past World.ITEM_ENTITY_LIMIT stacks in the world the remaining drops are lost rather than spawned. Losing a drop is worse than vanilla and better than the server going down, and it is reported so an operator can tell which happened.
Parameters
position
where they land, still.
contents
what to drop; nulls are skipped, so a block that drops nothing for the tool used can say so plainly.
Returns
Promise<void>
dropFromBlock()
dropFromBlock(
block,contents):Promise<void>
Defined in: prismarine/src/world/World.ts:2813
Puts what a block yielded on the ground, each stack popping out of the block.
Where a Bedrock Dedicated Server 1.26.52 puts a block's drop: at a random spot inside the block, pushed a little sideways and upward; see popOut. The push is what brings stacks from neighboring blocks within the half block they merge at, and merging is what keeps a burst of breaks under World.ITEM_ENTITY_LIMIT.
Parameters
block
the block they came out of.
contents
what to drop, as for World.dropContents.
Returns
Promise<void>
dropFromPlayer()
dropFromPlayer(
player,contents):Promise<void>
Defined in: prismarine/src/world/World.ts:2829
Drops player-held stacks from the player's eyes, with Java's forward toss and pickup delay.
Java places the item at eye height minus 0.3 blocks and gives it a 0.3-block-per-tick velocity along the view, with its small vanilla spread. The spawn position passed to World.spill is the item's feet; the item actor reports 0.125 blocks above it.
Parameters
player
The player who dropped the stacks.
contents
The stacks to drop; nulls and empty stacks are skipped.
Returns
Promise<void>
emitGameEvent()
emitGameEvent(
event,at,sourceId?):void
Defined in: prismarine/src/world/World.ts:3465
Posts one Java game event to listeners in the already-loaded chunks.
Parameters
event
string
The namespaced Java game event.
at
The integer block position where it occurred.
sourceId?
number
The runtime id of its source entity, when one caused it.
Returns
void
entityEquipmentChanged()
entityEquipmentChanged(
entity):void
Defined in: prismarine/src/world/World.ts:1666
Tells everyone watching that an entity is holding or wearing something new.
Called from the one place equipment is written, entity/data/liveBodies.ts, which has already dropped the writes that changed nothing.
Parameters
entity
Whose equipment changed.
Returns
void
getBlock()
getBlock(
x,y,z,layer?):Promise<Block>
Defined in: prismarine/src/world/World.ts:1185
The block at a position, carrying the state the chunk holds.
Every one of the palette's 22079 states resolves, because the names a chunk can hold come out of the same content build this method reads. The properties travel with the name, so a lit lamp, a half slab and a stair on its side each read their own facts rather than the ones their default state has.
Parameters
x
number
y
number
z
number
layer?
number = 0
Returns
Promise<Block>
Throws
When no registry names the block the chunk holds, which is a corrupt chunk or a world saved against a plugin that is no longer loaded. This used to answer air, and air is a position a caller is free to build in, so the block was lost on the next write.
getBlockState()
getBlockState(
x,y,z,layer?):Promise<BlockState>
Defined in: prismarine/src/world/World.ts:1169
The exact block state at a position, properties included.
getBlock answers "which block is this", collapsing every state of it onto one Block. Anything the client resolves by runtime id - break sounds, destroy particles - needs the state itself, because that is what the id identifies.
Parameters
x
number
y
number
z
number
layer?
number = 0
Returns
Promise<BlockState>
getBlockUpdates()
getBlockUpdates():
BlockUpdateScheduler
Defined in: prismarine/src/world/World.ts:2413
The queue of positions waiting to react to a change - see BlockUpdateScheduler.
Returns
BlockUpdateScheduler
getBlockWriteVersion()
getBlockWriteVersion():
number
Defined in: prismarine/src/world/World.ts:1241
The latest block-write version, unique across world instances and monotonic per world.
Returns
number
getChunk()
getChunk(
cx,cz,options?):Promise<Chunk>
Defined in: prismarine/src/world/World.ts:1202
Returns the chunk in the specifies x and z, if the chunk doesn't exists it is generated.
Parameters
cx
number
cz
number
options?
How badly the chunk is wanted. Defaults to immediate, which is what a caller that is about to read blocks out of it means.
Returns
Promise<Chunk>
getChunkAt()
Call Signature
getChunkAt(
x):Promise<Chunk>
Defined in: prismarine/src/world/World.ts:1819
Returns a chunk from a block position's x and z coordinates.
Parameters
x
Returns
Promise<Chunk>
Call Signature
getChunkAt(
x,z):Promise<Chunk>
Defined in: prismarine/src/world/World.ts:1820
Returns a chunk from a block position's x and z coordinates.
Parameters
x
number
z
number
Returns
Promise<Chunk>
getDimension()
getDimension():
DimensionType
Defined in: prismarine/src/world/World.ts:3836
Which dimension this world is, and therefore how tall it is and where its floor sits.
Resolved once from the stem's type by the level. The chunk stack, the disk format and the portal rules all read it from here, so none of them carries its own copy.
Returns
getDragonFight()
getDragonFight():
DragonFight|undefined
Defined in: prismarine/src/world/World.ts:2496
The dragon fight of this world, created on first ask over the state the save held.
Returns
DragonFight | undefined
The fight, or undefined in a dimension whose type has no has_ender_dragon_fight flag, which is every vanilla dimension but the End.
getEntities()
getEntities():
Entity[]
Defined in: prismarine/src/world/World.ts:3479
Get all entities in this world.
Returns
Entity[]
the entities.
getEntity()
getEntity(
runtimeId):Entity|null
Defined in: prismarine/src/world/World.ts:3603
One entity, by the id the protocol names it with.
The map has always been here; only the array of its values was exposed. Everything that arrives from a client naming an entity - an attack, an interaction, a pick - names it by runtime id, and resolving that by walking getEntities() is a linear scan through everything in the world for something the map answers in one step.
Parameters
runtimeId
bigint
The entity's runtime id.
Returns
Entity | null
The entity, or null if nothing here has that id.
getEntityGrid()
getEntityGrid():
EntityGrid
Defined in: prismarine/src/world/World.ts:3611
Where everything is, as of the top of this tick.
Returns
EntityGrid
The grid, for asking what is near a point.
getFormattedName()
getFormattedName():
string
Defined in: prismarine/src/world/World.ts:3814
Returns
string
getGameRuleManager()
getGameRuleManager():
GameRuleManager
Defined in: prismarine/src/world/World.ts:3779
The level's game rules, which every world of the save shares.
Returns
GameRuleManager
getGenerator()
getGenerator():
Generator
Defined in: prismarine/src/world/World.ts:812
Returns
getKnownSpawnPosition()
getKnownSpawnPosition():
Vector3|null
Defined in: prismarine/src/world/World.ts:2074
The spawn point if it has already been found, and null while it has not.
World.getSpawnPosition searches for dry land the first time it is asked, which is why it is asynchronous. A caller inside the tick cannot wait for that search, so it gets what the world knows now. The Overworld answers the level's spawn, which is the one the save keeps.
Returns
Vector3 | null
The spawn point, or null before it has been resolved.
getLevel()
getLevel():
Level
Defined in: prismarine/src/world/World.ts:3769
The level this world is one dimension of.
Returns
getLoadedChunk()
getLoadedChunk(
cx,cz):Chunk|null
Defined in: prismarine/src/world/World.ts:1228
The chunk at a coordinate if it is already in memory, and null otherwise.
The synchronous counterpart to getChunk, which mob AI needs: pathfinding reads a few hundred blocks to plan one route and has to answer inside the tick, and getChunk would both make that asynchronous and quietly generate terrain as a mob walked towards it. The last answer is remembered, because the callers ask in runs: the light engine scans a column of 384 blocks, and a path finder reads a few hundred around one position, each through this. The cache is one entry and is dropped whenever chunks gains or loses one, so the only way to make it lie is to change the map without going through the load or unload path.
Parameters
cx
number
Chunk x.
cz
number
Chunk z.
Returns
Chunk | null
The loaded chunk, or null - never a generated one.
getLoadedChunkCount()
getLoadedChunkCount():
number
Defined in: prismarine/src/world/World.ts:1246
How many chunks are in memory, which is what the mob spawner budgets against.
Returns
number
getName()
getName():
string
Defined in: prismarine/src/world/World.ts:3811
Returns
string
getPlayerData()
getPlayerData(
player):Promise<Partial<WorldPlayerData>>
Defined in: prismarine/src/world/World.ts:3854
Get the player data for a player.
Parameters
player
The player to get the data for.
Returns
Promise<Partial<WorldPlayerData>>
The player data.
getPlayers()
getPlayers():
Player[]
Defined in: prismarine/src/world/World.ts:3618
Get all players in this world.
Returns
Player[]
the players.
getPortalIndex()
getPortalIndex():
PortalIndex
Defined in: prismarine/src/world/World.ts:2418
The lit nether portal blocks of this world, kept in step with its block writes and chunk loads.
Returns
PortalIndex
getProvider()
getProvider():
BaseProvider
Defined in: prismarine/src/world/World.ts:3794
The level's provider, which serves every dimension of the save.
Returns
getRaidManager()
getRaidManager():
RaidManager|undefined
Defined in: prismarine/src/world/World.ts:2428
The village raids of this dimension, which only the Overworld has.
Built on first use from what the level saved, so a raid that was running when the server stopped carries on.
Returns
RaidManager | undefined
getSeaLevel()
getSeaLevel():
number
Defined in: prismarine/src/world/World.ts:824
The y this world's generator floods to, which worldgen's relative_to_sea_level anchors and the content rules that ask about the water line resolve against.
The generator's own answer when it has one, which the noise generator reads from its stem's noise_settings and the flat generator fixes at Java's -63. A generator without one gets the Overworld's 63.
Returns
number
getSeed()
getSeed():
bigint
Defined in: prismarine/src/world/World.ts:3826
The seed every generated chunk, structure placement and carver in this world comes from.
A 64-bit value, as Java's is. It was a number until it turned out that a seed above 2^53 arrived here rounded, which generated a world the player had not asked for.
Returns
bigint
getServer()
getServer():
Server
Defined in: prismarine/src/world/World.ts:3941
Returns
The server instance.
getSpawnPosition()
getSpawnPosition():
Promise<Vector3>
Defined in: prismarine/src/world/World.ts:1835
Returns the world spawn, in block coordinates.
The height is the one level.dat stores, which is one block below where a player's feet go: see placePlayerSpawn for where a player actually starts.
Returns
Promise<Vector3>
getStem()
getStem():
LevelStem
Defined in: prismarine/src/world/World.ts:3774
The stem this world was built from: its dimension type id and its generator definition.
Returns
getSystems()
getSystems():
WorldSystems
Defined in: prismarine/src/world/World.ts:2513
The light engine and the two scheduled tick lists - see WorldSystems.
Returns
WorldSystems
getTicks()
getTicks():
number
Defined in: prismarine/src/world/World.ts:3784
The level's clock, which every world of the save shares.
Returns
number
getUUID()
getUUID():
string
Defined in: prismarine/src/world/World.ts:3807
Returns
string
getWeather()
getWeather():
"thunder"|"clear"|"rain"
Defined in: prismarine/src/world/World.ts:2518
What the sky is doing: clear, rain or thunder. One answer per level.
Returns
"thunder" | "clear" | "rain"
hitBlock()
hitBlock(
position,face,striker?):Promise<void>
Defined in: prismarine/src/world/World.ts:1690
One swing against a block: the sound of the hit and the chips that come off it.
Struck, not broken. START_BLOCK_CRACKING was the only thing sent while mining, and that is the progress overlay - it draws the cracks spreading and makes no sound at all, which is why digging was silent until the block gave way.
The material comes from the runtime id, the same way a break's destroy event gets it: the client looks the block up and plays whatever that block is made of.
The sound goes to everyone near but the one striking, whose client plays its own hits in either breaking mode. A Bedrock Dedicated Server 1.26.52 sends the striker none. This one reached them too, and with their client's own hits it sounded like digging at several times the speed.
Parameters
position
The block being struck.
face
number
Which side was hit; the chips come off that one.
striker?
Who is striking it, when a player is.
Returns
Promise<void>
isRainingAt()
isRainingAt(
x,y,z):boolean
Defined in: prismarine/src/world/World.ts:2546
Whether rain is falling on one position, Java's Level.isRainingAt.
Three of Java's four conditions: it has to be raining, the position has to see the sky, and nothing may stand above it. The fourth is the biome's precipitation, which is a temperature curve over the height that neither edition publishes in a form this repository holds, so every biome counts as rainy here and fire in a snowy one is put out where Java would leave it burning.
The sky test is the light engine's. Full sky light means an unobstructed column: sky light loses at least one per step the moment it has to travel sideways, so 15 at a position and nowhere short of the sky above it are the same statement. The engine already keeps it per block and updates it with every write, which is the whole reason not to walk the column here - World.topOfColumn answers per chunk at sub chunk resolution, so one block on a hilltop would shelter the whole chunk from the rain.
It is also Java's own test rather than an approximation of it. Level.canSeeSky reads the MOTION_BLOCKING heightmap, which a fire does not raise because it has no collision; a fire does not dampen light here either, so the position it stands in still reads 15.
Parameters
x
number
y
number
z
number
Returns
boolean
False in an unloaded chunk or a dimension without a sky. A loaded chunk outside the simulation light ring is initialized and settled on demand before this test reads it.
loadChunk()
loadChunk(
x,z,options?):Promise<Chunk>
Defined in: prismarine/src/world/World.ts:1355
Loads a chunk in a given x and z and returns its.
A request for a chunk that is already being loaded joins that one rather than starting a second. They arrive together constantly - the preload asks for a batch of thirty-two in one turn, and every player whose view distance reaches a chunk asks for it as well - and each duplicate was a whole chunk generated and then thrown away, because the last one to finish overwrote the others in the map. Worse than wasted: two callers held two different objects for one position, so a block written into one was invisible through the other.
Parameters
x
number
x coordinate.
z
number
z coordinate.
options?
How badly the chunk is wanted. A caller that joins a load already in flight and wants it more than whoever started it moves that load up the generator's queue, so a chunk asked for as the far rim and then stood on does not keep the turn it was given when nobody needed it.
Returns
Promise<Chunk>
Throws
When the world has been closed, since its provider is gone and a chunk generated now would be generated after the save that was meant to persist it.
loadedBlockAt()
loadedBlockAt(
x,y,z):SystemBlock|undefined
Defined in: prismarine/src/world/World.ts:2677
The block at a position, or undefined when its chunk is not in memory.
The synchronous read the light engine and the random tick pass need: both run inside the tick and neither may generate terrain by looking at it.
Parameters
x
number
y
number
z
number
Returns
SystemBlock | undefined
loadedBlockRuntimeIdAt()
loadedBlockRuntimeIdAt(
x,y,z):number|undefined
Defined in: prismarine/src/world/World.ts:2699
The runtime id at a position, or undefined where loadedBlockAt has no block.
The same read without resolving the id to a state, for a caller that keeps a table of its own per runtime id. The light engine does: it wants two numbers per block and asks tens of millions of times while a world preloads, and resolving each of those to a BlockState and then through the property table by name and state values was most of the cost of lighting a chunk.
Parameters
x
number
World x.
y
number
World y.
z
number
World z.
Returns
number | undefined
The runtime id, air's where the column has no sub chunk, and undefined when the chunk is not in memory or y is outside the dimension.
locateBiome()
locateBiome(
name,origin):BiomeSearchResult|undefined
Defined in: prismarine/src/world/World.ts:1992
The nearest cell of a biome, or undefined when there is none within Java's reach.
What /locate biome answers. Nothing is generated: the generator walks its climate sampler outward from the origin on Java's grid, 6400 blocks out at one column per 32 blocks and one sample per 64 blocks of height.
Parameters
name
string
A biome identifier, with or without its minecraft: namespace, or a #tag such as #minecraft:is_ocean.
origin
Where to search from, in blocks.
x
number
y
number
z
number
Returns
BiomeSearchResult | undefined
The sampled position, or undefined when the generator has no biome walk of its own, no biome by that name can occur here, or the radius held none.
locateStructure()
locateStructure(
name,origin,radius?):StructureSearchResult|undefined
Defined in: prismarine/src/world/World.ts:1952
The nearest structure whose name matches, or undefined when there is none in range.
What /locate structure answers. Nothing is generated: the generator lays candidate structures out against the bare noise terrain and reports where the nearest one starts, so the search costs no chunks however far it reaches.
Parameters
name
string
What the player typed. See structureNameMatches for how loosely it is read.
origin
Where to search from, in blocks.
x
number
z
number
radius?
number = LOCATE_RADIUS
How far out to look, in rings of placement regions; Java's 100 by default.
Returns
StructureSearchResult | undefined
Java's locate position and the generation point, or undefined when the generator places no structures, has no search of its own, or found nothing inside the radius.
moveGameEventListener()
moveGameEventListener(
listener):void
Defined in: prismarine/src/world/World.ts:3449
Re-files a dynamic game-event listener after its position changes.
Parameters
listener
GameEventListener
Returns
void
notifyBlockBreak()
notifyBlockBreak(
position,identifier,sourceId?):void
Defined in: prismarine/src/world/World.ts:3432
Notifies nearby data-driven block sensors that one block broke.
Parameters
position
The integer position of the broken block.
identifier
string
The namespaced identifier of the broken block.
sourceId?
number
The runtime id of the player or entity that broke it, when known.
Returns
void
placePlayerSpawn()
placePlayerSpawn(
random?):Promise<PlayerSpawn>
Defined in: prismarine/src/world/World.ts:2021
Where a player with no saved position starts, chosen the way a Bedrock Dedicated Server chooses it.
A block nothing registered a behavior for reads as air, so it does not obstruct.
Parameters
random?
RelocationOffset
picks the offset when the spawn has to move; for tests.
Returns
Promise<PlayerSpawn>
playNamedSound()
playNamedSound(
x,y,z,sound):void
Defined in: prismarine/src/world/World.ts:2095
Plays a sound at a block, named the way a resource pack spells it.
The engine systems and the block behaviors name their sounds - open.door, random.chestopen, random.fizz where lava meets water - and the level sound events the rest of this world sends are numbers out of a fixed client enum with no entry for most of them.
Parameters
x
number
Block x.
y
number
Block y.
z
number
Block z.
sound
string
The sound definition's name.
Returns
void
playNamedSoundAt()
playNamedSoundAt(
position,sound,options?):void
Defined in: prismarine/src/world/World.ts:2109
Plays a named sound at an exact world-space point.
The counterpart of World.playNamedSound for things that are not blocks, the way World.spawnNamedParticleAt is for particles: an entity's position is already the point, so nothing centers it.
Parameters
position
Where the sound plays.
sound
string
The sound definition's name.
options?
NamedSoundOptions
Volume and pitch, when the definition's own are not wanted.
Returns
void
raidSaveState()
raidSaveState():
RaidRecord[] |undefined
Defined in: prismarine/src/world/World.ts:2443
The raids to save, or undefined when this world never ran one.
Returns
RaidRecord[] | undefined
randomTickChunks()
randomTickChunks():
RandomTickChunk[]
Defined in: prismarine/src/world/World.ts:2582
Where this tick's random draws land: Java's ServerLevel.tickChunks, in two halves.
Only a chunk a player ticket holds is simulated, so an empty server draws nothing at all however much of the world is in memory - which is also why nobody's furnaces burn while they are logged off. And within a chunk, only the sections whose palette holds something that takes random ticks, which is Java's LevelChunkSection.isRandomlyTicking; see Chunk.getRandomTickSections. The three hundred blocks of air over an Overworld column and the stone under it are both skipped.
The section test has to be Java's rather than merely cheap, because the draw state is one counter shared across the world: a section drawn for that Java skips steps the counter and moves every position drawn afterwards. Public for the same reason World.loadedBlockAt is: WorldSystems is handed the world's reads rather than the world itself.
Returns
RandomTickChunk[]
One entry per simulated chunk, with its randomly ticking sections.
removeEntity()
removeEntity(
entity):Promise<void>
Defined in: prismarine/src/world/World.ts:3043
Removes an entity from the level.
Parameters
entity
The entity to remove.
Returns
Promise<void>
removeGameEventListener()
removeGameEventListener(
listener):void
Defined in: prismarine/src/world/World.ts:3454
Removes a listener from this world's game-event registries.
Parameters
listener
GameEventListener
Returns
void
replayStateDigest()
replayStateDigest():
string
Defined in: prismarine/src/world/World.ts:3492
Hashes loaded chunks, selected pending simulation work, and live entity state for one replay tick.
Chunks include blocks, biomes, and block entities. Player inventories are included because duplicate or missing stacks can leave every other world field unchanged. Scheduler queues are copied in processing order; lighting is represented by queue depth only, so this digest compares those boundaries but cannot restore them.
Returns
string
resendBlock()
resendBlock(
x,y,z):void
Defined in: prismarine/src/world/World.ts:2163
Tells the players who can see a block what is there, without changing it.
For a client that predicted a change the server did not make: a refused placement leaves the block that client drew on its screen until something else happens at the position. Nothing is sent for a position whose chunk is not in memory or that lies outside the dimension.
Parameters
x
number
Block x.
y
number
Block y.
z
number
Block z.
Returns
void
save()
save():
Promise<void>
Defined in: prismarine/src/world/World.ts:3682
Writes this world to disk: every player in it, every changed chunk, the level data.
Queued behind whatever save is already running rather than run beside it. A caller that asks for a save gets one, so this waits its turn instead of declining like the autosave does, but it never writes at the same time as another pass.
Returns
Promise<void>
saveChunks()
saveChunks():
Promise<void>
Defined in: prismarine/src/world/World.ts:3634
Saves changed chunks into disk.
In batches with a yield between them, for the same reason the preload runs in batches: writing a chunk is synchronous, so Promise.all over every changed chunk was one uninterrupted run of work. The first autosave after a start region preload has all 441 chunks to write and held the event loop for ten seconds - the server froze solid, and the tick loop came back announcing it had skipped two hundred ticks.
A failed chunk write is logged and left dirty for retry. Other chunks in the pass still save, and the next pass tries the failed chunk again.
Returns
Promise<void>
saveForReplay()
saveForReplay():
Promise<void>
Defined in: prismarine/src/world/World.ts:3692
Saves players and chunks for a replay checkpoint, propagating persistence errors.
Ordinary autosaves log failed writes and retry them later. A replay snapshot must fail instead, because copying the provider after a swallowed error would capture stale state.
Returns
Promise<void>
saveLevelData()
saveLevelData():
Promise<void>
Defined in: prismarine/src/world/World.ts:3845
Writes the level's metadata through the provider: the spawn, the clock, the rules, the weather and the stems. The level's, because Bedrock keeps one of each per save; kept here so /setworldspawn and the autosave reach it through the world they hold.
Returns
Promise<void>
savePlayerData()
savePlayerData(
player,requireSuccess?):Promise<void>
Defined in: prismarine/src/world/World.ts:3888
Writes a player's record into the level, filed under World.playerDataKey and stamped with this world's dimension so the next login puts them back here.
Parameters
player
requireSuccess?
boolean = false
Propagate a persistence error when creating a replay checkpoint.
Returns
Promise<void>
sendActorEvent()
sendActorEvent(
entity,event,data?):Promise<void>
Defined in: prismarine/src/world/World.ts:1802
Tells everyone watching that something happened to one entity - it was hurt, it died, it swung an arm. The client plays the animation and the sound that go with it.
Parameters
entity
The entity it happened to.
event
What happened.
data?
number = 0
Extra detail, for the events that carry any.
Returns
Promise<void>
sendActorMetadata()
sendActorMetadata(
entity):Promise<void>
Defined in: prismarine/src/world/World.ts:1655
Tells everyone watching that an entity now looks different.
Parameters
entity
Who changed.
Returns
Promise<void>
sendActorSound()
sendActorSound(
entity,sound):Promise<void>
Defined in: prismarine/src/world/World.ts:1647
A noise one entity made: being hit, dying, swinging at something.
Parameters
entity
Who made it.
sound
Which noise.
Returns
Promise<void>
sendStatusEffect()
sendStatusEffect(
entity,effect,change):Promise<void>
Defined in: prismarine/src/world/World.ts:1812
Tells clients tracking an entity about one status effect change.
Parameters
entity
The actor whose effect changed.
effect
The effect state.
change
Whether it was added, updated, or removed.
Returns
Promise<void>
sendTime()
sendTime():
Promise<void>
Defined in: prismarine/src/world/World.ts:2999
Sends the current time to all players in the world.
Once a second rather than on every tick. The client runs its own day cycle between updates, so twenty of these a second told it nothing it had not already worked out - SetTimePacket is in the default log-excluded-packets purely because of the noise this made.
Returns
Promise<void>
sendWorldEvent()
sendWorldEvent(
position,event,data):Promise<void>
Defined in: prismarine/src/world/World.ts:1638
Sends a world event packet to all the viewers in the position chunk.
Parameters
position
Vector3 | null
world position.
event
event identifier.
data
number
event data.
Returns
Promise<void>
setBlockByName()
setBlockByName(
x,y,z,name,now?,delay?):Promise<boolean>
Defined in: prismarine/src/world/World.ts:2398
The same, for a block in its default state.
Parameters
x
number
World x.
y
number
World y.
z
number
World z.
name
string
The block's namespace id.
now?
number = ...
The tick to schedule the resulting updates from.
delay?
number = 1
Ticks before the neighbors are looked at.
Returns
Promise<boolean>
false if nothing changed, or this server has no such block.
setBlockRuntimeId()
setBlockRuntimeId(
x,y,z,runtimeId,now?,delay?):Promise<boolean>
Defined in: prismarine/src/world/World.ts:2277
The one way a block changes.
Everything a block change has to do, in one place: write it, tell every client, and give the blocks around it a chance to react. Routing every change through here is what makes physics work at all - a caller that writes into the chunk directly changes the world without anything noticing, so the sand above stays in mid air and the water beside it never moves.
Parameters
x
number
World x.
y
number
World y.
z
number
World z.
runtimeId
number
The block state to put there.
now?
number = ...
The tick to schedule the resulting updates from.
delay?
number = 1
Ticks before the neighbors are looked at.
Returns
Promise<boolean>
false if nothing changed - the position is outside the world, its chunk is not loaded, or that block is already there.
setLoadedBlockRuntimeId()
setLoadedBlockRuntimeId(
x,y,z,runtimeId,now?,delay?,notifyNeighbors?):boolean
Defined in: prismarine/src/world/World.ts:2308
The same write, for a chunk that is already in memory.
World.setBlockRuntimeId is this method with a chunk load in front of it. The split exists because the content behaviors write blocks from inside the tick and cannot await: a door has to see its own other half the moment it writes it, and generating terrain because a behavior looked at a position would be worse than declining to write.
Parameters
x
number
World x.
y
number
World y.
z
number
World z.
runtimeId
number
The block state to put there.
now?
number = ...
The tick to schedule the resulting updates from.
delay?
number = 1
Ticks before the neighbors are looked at.
notifyNeighbors?
boolean = true
Whether to run the engine updates the change causes. Java's flag 1 in setBlockAndUpdate, against the bare write a diode uses for its own state.
Returns
boolean
false if nothing changed, including when the chunk is not in memory.
setLoadedBlockState()
setLoadedBlockState(
x,y,z,block,notifyNeighbors):boolean
Defined in: prismarine/src/world/World.ts:2332
The same write, naming the block by its state rather than by its runtime id.
What the engine systems write through - see import('./EngineWorld'). They carry a Bedrock identifier and a state record and know nothing of runtime ids, and a state this server's palette does not hold is declined rather than guessed at.
Parameters
x
number
y
number
z
number
block
SystemBlock
notifyNeighbors
boolean
Whether to run the engine updates the change causes.
Returns
boolean
false if nothing changed.
setSpawnPosition()
setSpawnPosition(
pos):void
Defined in: prismarine/src/world/World.ts:2060
Set the world's spawn position. The Overworld's is the level's, Bedrock's SpawnX/Y/Z.
Parameters
pos
The position.
Returns
void
setTicks()
setTicks(
tick):void
Defined in: prismarine/src/world/World.ts:3789
Sets the level's clock, which is what /time set does.
Parameters
tick
number
Returns
void
setWeather()
setWeather(
kind,durationTicks?):void
Defined in: prismarine/src/world/World.ts:2560
Sets the weather, which is what /weather <kind> [duration] does.
Parameters
kind
"thunder" | "clear" | "rain"
clear, rain or thunder.
durationTicks?
number
How long, in ticks. Left out, each kind gets Java's own randomized default: 10 to 150 minutes clear, 10 to 20 raining, 3 to 13 storming.
Returns
void
spawnNamedParticle()
spawnNamedParticle(
x,y,z,particle):void
Defined in: prismarine/src/world/World.ts:2139
Emits a named particle effect at a block, such as minecraft:crop_growth_emitter.
The counterpart of World.playNamedSound: the hardcoded effects World.sendWorldEvent carries are numbered, and the ones a behavior pack can name are not.
Parameters
x
number
Block x.
y
number
Block y.
z
number
Block z.
particle
string
The effect's identifier.
Returns
void
spawnNamedParticleAt()
spawnNamedParticleAt(
position,particle):void
Defined in: prismarine/src/world/World.ts:2148
Emits a named particle effect at an exact world-space point.
Parameters
position
Where the effect appears.
particle
string
The effect's identifier.
Returns
void
startBlockCracking()
startBlockCracking(
position,face,tool,previous):Promise<BlockMining|null>
Defined in: prismarine/src/world/World.ts:1717
Starts the crack animation on a block a player began mining, as a Bedrock Dedicated Server does with server-authoritative block breaking.
The cracks on whatever the player mined before stop first, then start on this block with the progress a tick is worth. They continue every tick through World.updateBlockCracking until the block breaks or the player stops.
Parameters
position
The block being mined.
face
number
The face being mined, which decides where the particles fly.
tool
Item | null
What the player holds, or null for a bare hand.
previous
BlockMining | null
What the player was mining until now. When it is this same block, the mining carries on from when it began rather than starting over.
Returns
Promise<BlockMining | null>
What the player is mining now, or null for air and for a block that breaks at once, which have nothing to animate.
stopBlockCracking()
stopBlockCracking(
position):Promise<void>
Defined in: prismarine/src/world/World.ts:1791
Ends the crack animation on a block, as when the player stops mining it or moves on.
Parameters
position
The block.
Returns
Promise<void>
topOfColumn()
topOfColumn(
x,z):number
Defined in: prismarine/src/world/World.ts:2716
One past the highest y a column stores a block for - see Chunk.getTopStoredY.
Public for the same reason loadedBlockAt is. A chunk that is not in memory answers with the dimension ceiling, because the only safe answer about a column nothing can read is that something might stand anywhere in it.
Parameters
x
number
World x.
z
number
World z.
Returns
number
One past the highest stored y.
update()
update(
tick):Promise<void>
Defined in: prismarine/src/world/World.ts:962
Called every tick.
Parameters
tick
number
Returns
Promise<void>
updateBlockCracking()
updateBlockCracking(
mining):Promise<boolean>
Defined in: prismarine/src/world/World.ts:1767
One tick of mining: the particles off the face being mined, then the crack progress.
A Bedrock Dedicated Server sends this pair every tick for as long as a block is being mined. The particles leave from the block's center and carry its runtime id, which the client textures them with. The progress goes to the block's corner, like the start and the stop.
The block can change while it is mined: another player breaks it, or a command or a flood replaces it. The cracks belonged to the block that was there, so they stop with it.
Parameters
mining
BlockMining
What is being mined.
Returns
Promise<boolean>
False when the block is no longer the one being mined, in which case its cracks were stopped and nothing else was sent.
Lifecycle
disable()
disable():
Promise<void>
Defined in: prismarine/src/world/World.ts:801
On disable hook.
The order is the whole of it. Marking the world closing stops the preload asking for more chunks and stops the tick; waiting for the start region means every chunk that was generated is in this.chunks before the save walks it; and the provider is closed last, once nothing is left that could ask it for anything.
An autosave a tick started is one of those things. World.save waits for it before writing anything of its own, so by the time the level closes the provider no write is outstanding - closing the database under one is the same failure the start region race used to cause. The provider itself is the level's to close, once every world of the save has been through this.
Returns
Promise<void>
Implementation of
enable()
enable():
Promise<void>
Defined in: prismarine/src/world/World.ts:711
On enable hook: puts back what the save kept for this dimension and generates the start region, unless WorldData.startRegion defers it. The level has opened the provider and read the save-level state by now.
Returns
Promise<void>