API reference / @jsprismarine/prismarine / BlockRuntimeIds
Class: BlockRuntimeIds
Defined in: prismarine/src/block/state/BlockRuntimeIds.ts:20
Turns a block state into the number that travels in chunk palettes.
The id is the FNV-1a hash of the block's own {name, states} compound, serialised as little endian NBT. That choice is what StartGamePacket announces with block_network_ids_are_hashes, and it is what keeps blocks modular: an id depends on nothing but the block itself, so a plugin can add blocks without renumbering anyone else's, and the server never needs a copy of the client's internal palette ordering.
The alternative the protocol allows - the id being a position in the client's canonical list - would mean shipping and maintaining that exact ordered list for every client version, and would make every plugin block shift the ids of vanilla ones.
See
https://gist.github.com/Alemiz112/504d0f79feac7ef57eda174b668dd345
Constructors
Constructor
new BlockRuntimeIds():
BlockRuntimeIds
Returns
BlockRuntimeIds
Methods
get()
staticget(state):number
Defined in: prismarine/src/block/state/BlockRuntimeIds.ts:144
Parameters
state
Returns
number
getByName()
staticgetByName(name):number
Defined in: prismarine/src/block/state/BlockRuntimeIds.ts:51
The id of a block in its default state, for the many callers that only know a name. Replaces the old name-keyed mapping, which had no way to say which oak log it meant.
Parameters
name
string
Returns
number
getState()
staticgetState(runtimeId):BlockState|null
Defined in: prismarine/src/block/state/BlockRuntimeIds.ts:129
The state an id came from, for reading a chunk back.
A hash cannot be inverted, so this indexes every state the catalog can produce and looks the id up. Building it costs a pass over ~14k states, so it is deferred until something actually reads a block, and rebuilt when a plugin changes the catalog.
Parameters
runtimeId
number
Returns
BlockState | null
reset()
staticreset():void
Defined in: prismarine/src/block/state/BlockRuntimeIds.ts:157
Drops memoised ids. Needed after a plugin changes a schema, and by tests.
Returns
void
serialize()
staticserialize(state):Buffer
Defined in: prismarine/src/block/state/BlockRuntimeIds.ts:38
The little endian NBT bytes a state hashes to. Exposed because it is also exactly what StartGamePacket sends for a plugin's custom blocks.
The compound is built from the schema rather than from the property values, which is what keeps each property on its vanilla tag type; the protocol only writes it.
Parameters
state
Returns
Buffer
tryGetByName()
statictryGetByName(name):number|null
Defined in: prismarine/src/block/state/BlockRuntimeIds.ts:80
The same as getByName, but null rather than a throw for a name that is not a block.
Items are why this exists. minecraft:stick has no block state and never will, so asking what block it places is an ordinary question with an ordinary answer - not an error, and certainly not one that should cost the packet it was being written into.
Parameters
name
string
Returns
number | null
tryGetByState()
statictryGetByState(name,states?):number|null
Defined in: prismarine/src/block/state/BlockRuntimeIds.ts:100
The id of a block in a particular state, or null if this server has no such block or state.
The default state is enough for most callers, and getByName serves them. It is not enough for anything that builds or simulates: a roof is stairs facing four ways, a door is two halves that must agree, and flowing water is the same block at eight different depths. Those are one name with different properties, which a name alone cannot distinguish.
Memoised, because the callers are world generation and block physics - both of which resolve the same handful of states thousands of times - and building the state object is most of the cost of asking.
Parameters
name
string
The block's namespace id.
states?
Readonly<Record<string, BlockStateValue>>
Properties to set; the rest take defaults.
Returns
number | null
The runtime id, or null rather than a throw: a caller that cannot find a block should lose that detail, not take world generation or the tick down with it.