API reference / @jsprismarine/prismarine / world/World / World
Class: World
Defined in: prismarine/src/world/World.ts:536
Implements
Service
Constructors
Constructor
new World(
__namedParameters):World
Defined in: prismarine/src/world/World.ts:659
Parameters
__namedParameters
Returns
World
Properties
ITEM_ENTITY_LIMIT
readonlystaticITEM_ENTITY_LIMIT:2048=2048
Defined in: prismarine/src/world/World.ts:3233
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/data/droppedItems.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
actors()
actors():
MapIterator<StoreActor>
Defined in: prismarine/src/world/World.ts:3918
Every entity of this world, through its actor, in no particular order and without a copy. A caller that needs an order sorts what it keeps.
Returns
MapIterator<StoreActor>
The entities.
addGameEventListener()
addGameEventListener(
listener): () =>void
Defined in: prismarine/src/world/World.ts:3872
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
addPlayer()
addPlayer(
session):void
Defined in: prismarine/src/world/World.ts:3469
Adds a player to the world: files it in the player map by entity id, which World.viewerOf and the viewers read, and then gives its store player an entity in this world's store under the same id. The store shows the arriving player the world and the world the player, through the player's actor.
The one way a player enters a world, on its join and on its arrival from another. Until it runs, nothing in the world can target or see the player. Synchronous, so the entry is part of the caller's unit, and an undo of that unit takes the player out again.
Parameters
session
The player's session.
Returns
void
announceGameRule()
announceGameRule(
name,value,editable):void
Defined in: prismarine/src/world/World.ts:4220
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
void
attachChangeSink()
attachChangeSink(
sink):void
Defined in: prismarine/src/world/World.ts:727
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. The level attaches it as soon as it builds the world, before the world loads a chunk, so the sink is handed every chunk as it enters.
Parameters
sink
WorldChangeSink
Where changes go from now on.
Returns
void
beginChangeTick()
beginChangeTick():
void
Defined in: prismarine/src/world/World.ts:1028
Opens this tick of the world's change log, before the input step applies anything. Opening a tick that is already open does nothing.
Returns
void
blockEntityChanged()
blockEntityChanged(
position,tags,before):void
Defined in: prismarine/src/world/World.ts:2461
Logs that the block entity at a position is now these tags, field by field (blockentity/blockEntityLog.ts).
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, which replication sends from the log. Called by writeBlockEntity and by nothing else: it records 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.
before
NBTTagCompound | null
What stood there before, or null when nothing did.
Returns
void
breakBlock()
breakBlock(
position,player?):boolean
Defined in: prismarine/src/world/World.ts:2539
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.
Reads and writes the loaded chunk only, and runs to the end before it returns, so a handler calls it inside its unit. A block in a chunk that is not loaded is left alone.
Returns
boolean
true if a block was there and is now gone.
broadcastMove()
broadcastMove(
entity,teleport?):Promise<void>
Defined in: prismarine/src/world/World.ts:3808
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.
It only announces. The entity index refiled the entity when its position was written, whether or not the move is announced.
Parameters
entity
ShownActor
The entity that moved.
teleport?
boolean = false
Whether clients should snap instead of interpolate.
Returns
Promise<void>
chunkTickets()
chunkTickets():
ChunkTickets
Defined in: prismarine/src/world/World.ts:1427
The chunk tickets of this world: how a system inside the tick asks for chunks it lacks without waiting for them. See ChunkTickets.
Returns
ChunkTickets
closeTick()
closeTick(
tick):void
Defined in: prismarine/src/world/World.ts:1057
Closes a tick the ticker opened and then did not update the world in, such as a frozen one: seals it and sends what the input step applied in it. The world itself holds still, as Java's tick rate manager freezes everything but the players. The players still act, and their arm swings, sounds, emotes and movement reach the other clients in the tick that applied them, as they do in a running tick, rather than piling up in the replicator and going out all at once on the unfreeze.
Only a tick this call sealed replicates, so a world that updated, which sealed and replicated its own tick, sends nothing twice. A world whose entity store is broken stops replicating as it stops ticking.
Parameters
tick
number
The server tick.
Returns
void
dataEntities()
dataEntities():
LiveEntityRuntime
Defined in: prismarine/src/world/World.ts:3840
The data-driven entities of this world.
What drives every mob's behavior: its components, its goals, its brain, the spawn cycle and the despawn pass.
Asked for by level as well as dimension, because the runtime's store holds this world's change log and another level has the same dimension: by dimension alone, a second level's Overworld wrote its blocks, mobs and undos into the default level's.
Returns
LiveEntityRuntime
This world's runtime.
dragonFightSaveState()
dragonFightSaveState():
DragonFightState|undefined
Defined in: prismarine/src/world/World.ts:2992
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:3261
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
(Item | Block | null)[]
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):void
Defined in: prismarine/src/world/World.ts:3275
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
ContentPosition
the block they came out of.
contents
(Item | Block | null)[]
what to drop, as for World.dropContents.
Returns
void
dropFromPlayer()
dropFromPlayer(
player,contents):Promise<void>
Defined in: prismarine/src/world/World.ts:3296
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. That is the position the item actor reports; the stack lies the definition's position_offset below it.
Parameters
player
Pick<ShownActor, "getPosition" | "pitch" | "yaw">
The player who dropped the stacks.
contents
(Item | Block | null)[]
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:3893
Posts one Java game event to listeners in the already-loaded chunks.
Parameters
event
string
The namespaced Java game event.
at
ContentPosition
The integer block position where it occurred.
sourceId?
number
The runtime id of its source entity, when one caused it.
Returns
void
getActor()
getActor(
runtimeId):StoreActor|null
Defined in: prismarine/src/world/World.ts:3936
One entity of this world by its runtime id, through its actor.
Parameters
runtimeId
bigint
The entity's runtime id.
Returns
StoreActor | null
The entity, or null if nothing here has that id.
getActors()
getActors():
StoreActor[]
Defined in: prismarine/src/world/World.ts:3927
Every entity of this world, through its actor, in ascending runtime id order. A copy, sorted, for a caller outside the tick.
Returns
StoreActor[]
The entities.
getBlock()
getBlock(
x,y,z,layer?):Promise<Block>
Defined in: prismarine/src/world/World.ts:1368
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:1352
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:2896
The queue of positions waiting to react to a change - see BlockUpdateScheduler.
Returns
BlockUpdateScheduler
getBlockWriteVersion()
getBlockWriteVersion():
number
Defined in: prismarine/src/world/World.ts:1471
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:1385
Returns the chunk in the specifies x and z, if the chunk doesn't exists it is generated.
Parameters
cx
number
cz
number
options?
ChunkRequestOptions
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:2141
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:2142
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:4254
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
DimensionType
getDragonFight()
getDragonFight():
DragonFight|undefined
Defined in: prismarine/src/world/World.ts:2980
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.
getEntityIndex()
getEntityIndex():
EntityIndex
Defined in: prismarine/src/world/World.ts:4095
Where every entity of this world is now.
The dimension's one index (ADR 0007), which the entity runtime owns. A position write is visible to the next query, and every query answers in ascending runtime id order.
Returns
EntityIndex
The index, for asking what is near a point.
getEntityStore()
getEntityStore():
EntityStore
Defined in: prismarine/src/world/World.ts:1083
The entity store of this world's dimension, which holds its change log.
Returns
EntityStore
getFormattedName()
getFormattedName():
string
Defined in: prismarine/src/world/World.ts:4232
Returns
string
getGameRuleManager()
getGameRuleManager():
GameRuleManager
Defined in: prismarine/src/world/World.ts:4186
The level's game rules, which every world of the save shares.
Returns
GameRuleManager
getGenerator()
getGenerator():
Generator
Defined in: prismarine/src/world/World.ts:843
Returns
Generator
getKnownSpawnPosition()
getKnownSpawnPosition():
Vector3|null
Defined in: prismarine/src/world/World.ts:2396
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:4176
The level this world is one dimension of.
Returns
getLoadedChunk()
getLoadedChunk(
cx,cz):Chunk|null
Defined in: prismarine/src/world/World.ts:1411
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:1476
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:4229
Returns
string
getPendingChunkLoadCount()
getPendingChunkLoadCount():
number
Defined in: prismarine/src/world/World.ts:4195
How many chunk loads are in flight: read from disk or generating, and not in the world yet. A load whose chunk is ready and waits only for the next input step to admit it is not counted, because only a tick moves it on.
Returns
number
getPlayerData()
getPlayerData(
player):Promise<Partial<WorldPlayerData>>
Defined in: prismarine/src/world/World.ts:4272
Get the player data for a player, filed under keyOfPlayer.
Parameters
player
The player to get the data for, of which only the name and XUID are read.
getName
() => string
getXUID
() => string | null
Returns
Promise<Partial<WorldPlayerData>>
The player data.
getPortalIndex()
getPortalIndex():
PortalIndex
Defined in: prismarine/src/world/World.ts:2901
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:4212
The level's provider, which serves every dimension of the save.
Returns
BaseProvider
getRaidManager()
getRaidManager():
RaidManager|undefined
Defined in: prismarine/src/world/World.ts:2911
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:855
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:4244
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:4309
Returns
The server instance.
getSpawnPosition()
getSpawnPosition():
Promise<Vector3>
Defined in: prismarine/src/world/World.ts:2157
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:4181
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:2997
The light engine and the two scheduled tick lists - see WorldSystems.
Returns
WorldSystems
getTicks()
getTicks():
number
Defined in: prismarine/src/world/World.ts:4202
The level's clock, which every world of the save shares.
Returns
number
getUUID()
getUUID():
string
Defined in: prismarine/src/world/World.ts:4225
Returns
string
getViewers()
getViewers():
PlayerSession[]
Defined in: prismarine/src/world/World.ts:4112
The clients that see this world: the sessions of its online players.
Returns
The sessions.
getWeather()
getWeather():
"thunder"|"clear"|"rain"
Defined in: prismarine/src/world/World.ts:3002
What the sky is doing: clear, rain or thunder. One answer per level.
Returns
"thunder" | "clear" | "rain"
hitBlock()
hitBlock(
position,face,striker?):void
Defined in: prismarine/src/world/World.ts:1961
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?
Pick<ShownActor, "getRuntimeId">
Who is striking it, when a player is, matched by entity id.
Returns
void
isRainingAt()
isRainingAt(
x,y,z):boolean
Defined in: prismarine/src/world/World.ts:3030
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.
lastChangeTick()
lastChangeTick():
SealedTick|undefined
Defined in: prismarine/src/world/World.ts:1069
The last sealed tick of the world's change log, until the next tick begins.
Returns
SealedTick | undefined
The tick, or undefined while one is open or before the first one sealed.
loadChunk()
loadChunk(
x,z,options?):Promise<Chunk>
Defined in: prismarine/src/world/World.ts:1585
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?
ChunkRequestOptions
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.
loadedBlock()
loadedBlock(
x,y,z,layer?):Block|undefined
Defined in: prismarine/src/world/World.ts:1457
getBlock for a chunk that is already in memory: the block at a position, or undefined when its chunk is not loaded. Nothing is loaded or generated.
Parameters
x
number
y
number
z
number
layer?
number = 0
Returns
Block | undefined
Throws
When no registry names the block the chunk holds, as getBlock does.
loadedBlockAt()
loadedBlockAt(
x,y,z):SystemBlock|undefined
Defined in: prismarine/src/world/World.ts:3161
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:3183
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:2314
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:2274
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:3877
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:3860
Notifies nearby data-driven block sensors that one block broke.
Parameters
position
ContentPosition
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
onChangeTickCost()
onChangeTickCost(
listener): () =>void
Defined in: prismarine/src/world/World.ts:1078
Hears what each sealed tick of the world's change log cost, in entries and estimated bytes, which the replay scenarios report (non-gating).
Parameters
listener
(cost) => void
Returns
A function that removes the listener.
() => void
placePlayerSpawn()
placePlayerSpawn(
random?):Promise<PlayerSpawn>
Defined in: prismarine/src/world/World.ts:2343
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:2417
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:2432
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. It is a named-sound occurrence in the change log, which replication sends to the players near 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:2926
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:3066
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.
relayAnimation()
relayAnimation(
animation):void
Defined in: prismarine/src/world/World.ts:2091
Shows a player's animation, such as an arm swing, to the players that see the player. The player's own client already played it. It is an animate occurrence in the change log, which replication sends to the players tracking the player.
Parameters
animation
Whose animation, and what it is.
action
number
data
number
What the action carries, zero for the ones that carry nothing.
entity
bigint
swingSource
string | null
What caused a swing, by name, or null.
Returns
void
relayEmote()
relayEmote(
emote):void
Defined in: prismarine/src/world/World.ts:2100
Shows a player's emote to the players that see the player. It is an emote occurrence in the change log, which replication sends to the players tracking the player.
Parameters
emote
Whose emote, and the fields the relay carries.
emote
string
The emote piece's uuid.
entity
bigint
flags
number
lengthTicks
number
platformId
string
xuid
string
The account the emote belongs to, as the server knows it.
Returns
void
relaySound()
relaySound(
sound):void
Defined in: prismarine/src/world/World.ts:2110
Plays a sound a player's client made, such as a step, to the players near it. The sender's own client already played it. It is a relayed-sound occurrence in the change log, which replication sends to everyone near the sound but the sender.
Parameters
sound
Who made it, and the fields their client sent.
actor
bigint
The entity the sound belongs to, or -1 for none.
baby
boolean
data
number
firedAt
{ x: number; y: number; z: number; } | null
Where a projectile sound was fired from, or null.
global
boolean
sender
bigint
The player whose client made it, which already played it.
sound
number
The sound, or -1 for a name outside the server's enum.
type
string
x
number
y
number
z
number
Returns
void
removeGameEventListener()
removeGameEventListener(
listener):void
Defined in: prismarine/src/world/World.ts:3882
Removes a listener from this world's game-event registries.
Parameters
listener
GameEventListener
Returns
void
removePlayer()
removePlayer(
session):void
Defined in: prismarine/src/world/World.ts:3493
Removes a player from the world, on its leave and on its departure for another: out of the player map first, so a leaving player is not among the clients told it left, and then its entity out of this world's store, which takes it off every client that was shown it. The store player keeps what its next entity needs.
Parameters
session
The player's session.
Returns
void
replayChunkLeave()
replayChunkLeave(
x,z):boolean
Defined in: prismarine/src/world/World.ts:3663
Applies a chunk entry of the change log that says a chunk left, for a world built from a snapshot that replays the log forward: the chunk is taken out of memory as an unload takes it, without a save. The entities it held left in entries of their own ahead of it. A chunk that entered needs its content, which arrived as an input, so it is loaded through World.getChunk instead.
Parameters
x
number
The chunk's x coordinate, in chunks.
z
number
The chunk's z coordinate, in chunks.
Returns
boolean
Whether the chunk was in memory.
replayStateDigest()
replayStateDigest(
header?):string
Defined in: prismarine/src/world/World.ts:3986
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.
Everything here is either written through the change log or in the tick header, so a snapshot of the world plus the log of the ticks after it reaches the digest of any of them.
Parameters
header?
The clocks and in-flight work to hash, which are this world's own unless a replay of the log hands it those of the sealed tick it reached.
gameRules
readonly (readonly [string, readonly [number | boolean, boolean]])[]
Every game rule, as its name, its value and whether it can be edited.
pendingChunkLoads
readonly (readonly [number, string])[]
Each chunk load in flight, as its packed position and its urgency, by position.
pendingLighting
{ deferred: number; queued: number; }
How deep the light queue is.
pendingLighting.deferred
number
pendingLighting.queued
number
randomTickState
number
The state of the generator that draws random tick positions.
tick
number
The level clock, as World.getTicks reads it.
weather
{ clearWeatherTime: number; raining: boolean; rainTime: number; thundering: boolean; thunderTime: number; }
The level's weather, as a save holds it.
weather.clearWeatherTime
number
weather.raining
boolean
weather.rainTime
number
weather.thundering
boolean
weather.thunderTime
number
Returns
string
resendBlock()
resendBlock(
x,y,z):void
Defined in: prismarine/src/world/World.ts:2509
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. It is a block-shown occurrence in the change log, which replication sends with the tick's block changes.
Parameters
x
number
Block x.
y
number
Block y.
z
number
Block z.
Returns
void
runInputNow()
runInputNow(
apply):void
Defined in: prismarine/src/world/World.ts:1097
Applies one input as a unit of the change log, which closes when the input returns: when it throws, what it wrote is undone and the error is thrown on to the caller.
A world whose entity store failed to undo a unit drops the input unapplied. Its state no longer matches its log and it has stopped ticking (World.update reports that once), so an input would go on writing to a half-undone world.
Parameters
apply
() => void
The input's handler.
Returns
void
save()
save():
Promise<void>
Defined in: prismarine/src/world/World.ts:4171
Writes the level this world is one dimension of: every player, every changed chunk, the level data. Queued behind whatever write is already running; see LevelSave.
Returns
Promise<void>
saveChunks()
saveChunks():
Promise<void>
Defined in: prismarine/src/world/World.ts:4163
Writes this world's changed chunks and players now, through the level's save.
Returns
Promise<void>
saveLevelData()
saveLevelData():
Promise<void>
Defined in: prismarine/src/world/World.ts:4263
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:4294
Writes a player's record into the level, filed under keyOfPlayer and stamped with this world's dimension so the next login puts them back here.
Parameters
player
PlayerRecordSource & object
requireSuccess?
boolean = false
Propagate a persistence error when creating a replay checkpoint.
Returns
Promise<void>
sealChangeTick()
sealChangeTick():
SealedTick|undefined
Defined in: prismarine/src/world/World.ts:1038
Seals the open tick of the world's change log, for a world the ticker opened and then did not update, such as a frozen one.
Returns
SealedTick | undefined
The sealed tick, or undefined when none was open.
sendActorEvent()
sendActorEvent(
entity,event,data?):void
Defined in: prismarine/src/world/World.ts:2077
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. It is an actor-event occurrence in the change log, which replication sends to the players tracking the entity and to the entity's own client.
Parameters
entity
ShownActor
The entity it happened to.
event
What happened.
data?
number = 0
Extra detail, for the events that carry any.
Returns
void
sendActorSound()
sendActorSound(
entity,sound):void
Defined in: prismarine/src/world/World.ts:1926
A noise one entity made: being hit, dying, swinging at something. It is an actor-sound occurrence in the change log, at where the entity stands now, which replication sends to whoever is near enough rather than to whoever is tracking the entity, because a sound is audible from further than a mob is worth drawing.
Separate from a block's sound because the wire format differs in a way that matters: a mob's sound carries which mob is making it, so a client can pick the zombie's grunt over the skeleton's rattle.
Parameters
entity
ShownActor
Who made it.
sound
Which noise.
Returns
void
sendStatusEffect()
sendStatusEffect(
entity,effect,change):void
Defined in: prismarine/src/world/World.ts:2121
Tells clients tracking an entity, and its own client, about one status effect change. It is a status-effect occurrence in the change log, which replication sends after the tick seals.
Parameters
entity
Pick<ShownActor, "getRuntimeId">
The actor whose effect changed.
effect
StatusEffect
The effect state.
change
StatusEffectChange
Whether it was added, updated, or removed.
Returns
void
sendTime()
sendTime():
void
Defined in: prismarine/src/world/World.ts:3452
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
void
sendWorldEvent()
sendWorldEvent(
position,event,data):void
Defined in: prismarine/src/world/World.ts:1901
Something cosmetic happened: particles, a splash, a block's cracks. It is a world-effect occurrence in the change log, which replication sends to the players near it, or to every player in the world when there is no position.
Parameters
position
Vector3 | null
Where, or null for the world as a whole.
event
Which effect.
data
number
Extra detail, for the effects that carry any.
Returns
void
setBlockByName()
setBlockByName(
x,y,z,name,now?,delay?):boolean
Defined in: prismarine/src/world/World.ts:2881
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
boolean
false if nothing changed, its chunk is not loaded, or this server has no such block.
setBlockRuntimeId()
setBlockRuntimeId(
x,y,z,runtimeId,now?,delay?):boolean
Defined in: prismarine/src/world/World.ts:2632
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
boolean
false if nothing changed - the position is outside the world, its chunk is not loaded, or that block is already there. A chunk that is not loaded is never loaded for a write: a caller inside a tick cannot wait for it.
setLoadedBlockRuntimeId()
setLoadedBlockRuntimeId(
x,y,z,runtimeId,now?,delay?,notifyNeighbors?):boolean
Defined in: prismarine/src/world/World.ts:2661
The same write, for a chunk that is already in memory.
World.setBlockRuntimeId is this method with the neighbor updates always on. The content behaviors write blocks from inside the tick: 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:2685
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:2382
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:4207
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:3044
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
shownEntities()
shownEntities(): readonly
ShownEntity[]
Defined in: prismarine/src/world/World.ts:3909
Every entity this world shows its clients, as replication holds it from the change log.
What tracking reads, and it has to be every one, because a tracker hides anything it holds that is missing from the set.
Returns
readonly ShownEntity[]
spawnNamedParticle()
spawnNamedParticle(
x,y,z,particle):void
Defined in: prismarine/src/world/World.ts:2478
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:2488
Emits a named particle effect at an exact world-space point. It is a named-particle occurrence in the change log, which replication sends to the players near it.
Parameters
position
Where the effect appears.
particle
string
The effect's identifier.
Returns
void
startBlockCracking()
startBlockCracking(
position,face,tool,previous):BlockMining|null
Defined in: prismarine/src/world/World.ts:2001
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
BlockMining | null
What the player is mining now, or null for air, for a block in a chunk that is not loaded and for a block that breaks at once, which have nothing to animate.
stopBlockCracking()
stopBlockCracking(
position):void
Defined in: prismarine/src/world/World.ts:2064
Ends the crack animation on a block, as when the player stops mining it or moves on.
Parameters
position
The block.
Returns
void
tickHeader()
tickHeader():
object
Defined in: prismarine/src/world/World.ts:3948
What this world's own clocks and in-flight work are now: the part of the replay digest that no change log entry carries, which each sealed tick holds as its header.
Returns
A plain copy.
gameRules
readonlygameRules: readonly (readonly [string, readonly [number|boolean,boolean]])[]
Every game rule, as its name, its value and whether it can be edited.
pendingChunkLoads
readonlypendingChunkLoads: readonly (readonly [number,string])[]
Each chunk load in flight, as its packed position and its urgency, by position.
pendingLighting
readonlypendingLighting:object
How deep the light queue is.
pendingLighting.deferred
readonlydeferred:number
pendingLighting.queued
readonlyqueued:number
randomTickState
readonlyrandomTickState:number
The state of the generator that draws random tick positions.
tick
readonlytick:number
The level clock, as World.getTicks reads it.
weather
readonlyweather:object
The level's weather, as a save holds it.
weather.clearWeatherTime
readonlyclearWeatherTime:number
weather.raining
readonlyraining:boolean
weather.rainTime
readonlyrainTime:number
weather.thundering
readonlythundering:boolean
weather.thunderTime
readonlythunderTime:number
topOfColumn()
topOfColumn(
x,z):number
Defined in: prismarine/src/world/World.ts:3200
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):void
Defined in: prismarine/src/world/World.ts:998
Runs one tick of the world, between opening and sealing that tick of its change log (ADR 0015), then sends what it changed.
The ticker opens the log before the input step, so the inputs it applies land in this tick, and an update the ticker did not open for opens it here. Sealing hands the tick to the change sink. A tick that throws is sealed and sends nothing, and the sink keeps what it read for the next tick's sends. A world whose entity store failed to undo a unit is no longer trusted, so it stops ticking and says so once.
Parameters
tick
number
The server tick.
Returns
void
updateBlockCracking()
updateBlockCracking(
mining):Promise<boolean>
Defined in: prismarine/src/world/World.ts:2049
One tick of mining, as mineTick decides it: the particles off the face being mined, then the crack progress, or the stop once the block is no longer the one being mined. A block whose chunk is not loaded sends nothing, and the mining waits for 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.
viewerOf()
viewerOf(
runtimeId):PlayerSession|undefined
Defined in: prismarine/src/world/World.ts:4121
The session of the player with this entity id in this world, joined or not.
Parameters
runtimeId
bigint
The player's entity id.
Returns
PlayerSession | undefined
The session, or undefined when no player in this world has the id.
Lifecycle
disable()
disable():
Promise<void>
Defined in: prismarine/src/world/World.ts:818
On disable hook: stops the world and writes it, through the level's save.
A level shutting down stops every world first with World.stop and writes them in one pass instead.
Returns
Promise<void>
Implementation of
Service.disable
enable()
enable():
Promise<void>
Defined in: prismarine/src/world/World.ts:737
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>
Implementation of
Service.enable
stop()
stop():
Promise<void>
Defined in: prismarine/src/world/World.ts:833
Stops the world, so that nothing new starts while the save that follows runs.
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 unload batch in flight finishes its write. The provider is the level's to close, once every world of the save has been through this and the last pass has committed.
Returns
Promise<void>