PacketByteBufferHelper
com.jsmacrosce.jsmacros.client.api.helper.PacketByteBufferHelper
Reads and writes typed values in a packet buffer; callers must use the packet's field order and matching read/write operations.
Packet-event buffers contain encoded packet data; Client.createPacketByteBuffer() creates a fresh buffer. Changes to a packet-event buffer do not change the packet object.
reset() restores the captured bytes and reader position (normally the start for a packet-backed helper); use it when you need to reread or decode from that captured position.
Supported standalone packets can be decoded using their registered codecs. Packet-backed helpers remember their network phase; overloads taking a protocol select a phase explicitly.
Conversion reads from the current reader position, so reset after inspecting a packet before decoding its untouched bytes. receivePacket() handles the original packet object,
whereas its named and class overloads decode the buffer first.
ts
const payload = Client.createPacketByteBuffer();
payload.writeString("hello").writeVarInt(42);
Chat.log(`${payload.readString()} and ${payload.readVarInt()}`);Constructors
new PacketByteBufferHelper
new PacketByteBufferHelper()#Creates a fresh buffer with no originating packet and the default
play phase. Captures its initial contents for reset().new PacketByteBufferHelper(FriendlyByteBuf base)#Uses the supplied buffer directly as its working buffer and captures a separate copy of its initial contents for
reset(). This helper has no originating packet and uses the default play phase.Parameters:
base: the non-null buffer to wrap
Encodes a packet using its selected phase's standalone codec and retains the packet as the helper's origin; this does not send or handle the packet. The encoded contents are captured for
reset(). The current connection phase is preferred when registered for the packet; otherwise its sole registered phase is selected. Unknown packets or packets with ambiguous phases throw IllegalArgumentException; a missing standalone codec also throws IllegalArgumentException.Parameters:
packet: the non-null packet to encode
Fields
BUFFER_TO_PACKET
static BUFFER_TO_PACKET: Map<Class<? extends Packet<?>>, Function<FriendlyByteBuf, ? extends Packet<?>>>read-only#the lookup table that turns a buffer back into a packet. Don't touch this here! Populated by
init() for packet classes with supported standalone codecs. toPacket(Class) uses it for play-phase decoding; explicit phase decoding selects the matching codec directly.Methods
canSerialize
Checks whether the packet has a standalone codec for the phase selected as in PacketByteBufferHelper(Packet). Returns
false for null, unknown packets, ambiguous phase selection, or missing codecs; it does not test whether encoding the packet's contents will succeed.Parameters:
packet: the packet to check, ornull
Returns: whether the packet has a supported standalone codec
clear
Resets the writers and readers index to 0. This technically doesn't clear the buffer, but rather makes it so that new operations will overwrite the old data.
Returns: self for chaining.
forEachInCollection
forEachInCollection(MethodWrapper<FriendlyByteBuf, ?, Object, ?> reader): PacketByteBufferHelperSince1.8.4#Parameters:
reader: the function to read the collection's elements from the buffer
Returns: self for chaining.
getBoolean
Reads a byte at the given index without changing the reader index.
Parameters:
index: the index to read from
Returns: the boolean value at the given index.
getByte
Parameters:
index: the index to read from
Returns: the byte at the given index.
getBytes
Parameters:
index: the index to start reading fromlength: the length of the array to read
Returns: the bytes at the specified index; the reader index is unchanged
getChar
Reads an unsigned byte at the given index without changing the reader index.
Parameters:
index: the index to read from
Returns: the char at the given index.
getDouble
Parameters:
index: the index to read from
Returns: the double at the given index.
getFloat
Parameters:
index: the index to read from
Returns: the float at the given index.
getInt
Parameters:
index: the byte index to read from
Returns: the integer at that index.
getLong
Parameters:
index: the index to read from
Returns: the long at the given index.
getMedium
Parameters:
index: the byte index to read from
Returns: the signed medium at that index.
getNetworkStateId
which network state a packet class belongs to, in the game's own numbering. This overload requires the packet class to occur in exactly one protocol. Use getNetworkStateId(Class, String) for a class shared between phases. The state is which part of the connection a packet belongs to — logging in, playing, or configuring — and it is why a packet cannot simply be read on the wrong one.
Parameters:
packetClass: the class of the packet to get the id for
Returns: the ordinal of the registered connection protocol
Returns the ordinal of the requested protocol for a packet registered in it. Throws IllegalArgumentException if the protocol is unknown or the packet is not registered in it.
Parameters:
packetClass: the packet classprotocol: the protocol identifier or name
Returns: the requested protocol's ordinal
getPacketId
Returns the packet ID registered for the packet class. The ID is specific to the protocol and direction, and may change across Minecraft versions; if the class is registered in multiple protocols, use getPacketId(Class, String).
Parameters:
packetClass: the class of the packet to get the id for
Returns: the ID registered for the packet class
Returns the packet ID registered for the requested protocol (for example, "play" or "configuration"). Throws IllegalArgumentException if the protocol is unknown or the packet is not registered in it.
Parameters:
packetClass: the packet classprotocol: the protocol identifier or name
Returns: the registered packet ID
getPacketName
Returns the shortcut name for a packet, or its simple class name when no shortcut is registered. The returned name is also used as packet-event
type and accepted by packet filterers.Parameters:
packet: the packet to name
Returns: the packet's shortcut name, or its simple class name if none is registered
getPacketNames
Returns the convenience names registered for packet classes. Names are also used as packet-event
type values and by filterer setType. Most encode direction in an S2C or C2S suffix, but this is a naming convention, not authoritative direction metadata; use isClientbound(Class) or isServerbound(Class) when available. Names are convenience aliases and may change. getPacketName(Packet) can return a class's simple name when that class has no registered alias.Returns: a list of all packet names.
getShort
Reads a short at the given index without changing the reader index.
Parameters:
index: the index to read from
Returns: the short at the given index.
getUnsignedByte
Parameters:
index: the index to read from
Returns: the unsigned byte at the given index, represented as a short.
getUnsignedInt
Parameters:
index: the byte index to read from
Returns: the unsigned integer at that index, represented as a long.
getUnsignedMedium
Parameters:
index: the byte index to read from
Returns: the unsigned medium at that index.
getUnsignedShort
Reads an unsigned short at the given index without changing the reader index.
Parameters:
index: the index to read from
Returns: the unsigned short at the given index, represented as an int.
init
static init(): void#Populates convenience packet-name mappings and registers packet IDs, directions, and supported standalone play-phase decoders using reflection. Reflective lookup failures may cause an
IllegalStateException.isClientbound
whether a packet class is one the server sends to the client. Reads the registered packet direction rather than inferring it from a convenience name. A name is the practical test for this: getPacketNames() ends almost every clientbound one with
S2C and every serverbound one with C2S, and the event's type is that same name.Parameters:
packetClass: the class to get the side for
Returns:
true if the packet is clientbound, false if it is serverboundisServerbound
whether a packet class is one the client sends to the server. This is the exact opposite of isClientbound(Class) for a registered packet class.
Parameters:
packetClass: the class to get the id for
Returns:
true if the packet is serverbound, false if it is clientboundmain
Runs the packet-mapping generator: initializes mappings, scans legacy packet classes on the class path (including declared nested classes), and prints missing
PACKETS.put lines to standard output. Class-path scanning can fail with IOException; arguments are ignored.Parameters:
args: ignored command-line arguments
markReaderIndex
markWriterIndex
Marks the current writer index for later use by resetWriterIndex().
Returns: self for chaining.
preferredProtocol
static preferredProtocol(Packet<?> packet, ConnectionProtocol current): String#Selects a registered phase for the packet, preferring
current when registered. If no current phase applies, selects the sole registered phase; throws IllegalArgumentException for an unknown packet or when multiple phases remain.Parameters:
packet: the packet whose registered phase to selectcurrent: the current connection phase, ornull
Returns: the selected phase identifier
readBitSet
readBlockHitResultHelper
Returns: the read block hit result as a helper.
readBlockPos
Returns: the read block position.
readBoolean
Returns: the read boolean value.
readByte
Returns: the read byte value.
readByteArray
Returns: the read byte array.
Will throw an exception if the byte array is bigger than the given maximum size.
Parameters:
maxSize: the maximum size of the byte array to read
Returns: the read byte array.
readBytes
Starts reading from this buffer's readerIndex.
Parameters:
length: the length of the array to read
Returns: the read byte array.
readChar
Returns: the read char value.
readChunkHelper
Reads a chunk position and looks up that chunk in the current client level.
Returns: its ChunkHelper, or
null if the lookup returns no chunk.readChunkPos
Returns: the chunk coordinates, with x at index 0 and z at index 1.
readChunkSectionPos
Returns: the read section coordinates, wrapped as a BlockPosHelper.
readDate
readDouble
Returns: the read double value.
readEnumConstant
readerIndex
Returns: the readers current position.
readFloat
Returns: the read float value.
readIdentifier
readInstant
readInt
Reads an integer from the current reader index.
Returns: the value read.
readIntArray
Returns: the read int array.
Reads and discards an int array, then returns this helper. The reader rejects an encoded array length greater than
maxSize.Parameters:
maxSize: the maximum size of the int array to read
Returns: this helper
readIntList
Reads an integer list from the buffer.
Returns: the decoded list
readList
Reads a list of elements from the buffer.
Parameters:
reader: reads each element
Type Parameters:
T: the type of elements read
Returns: the decoded elements
readLong
Returns: the read long value.
readLongArray
Returns: the read long array.
Reads and returns a long array. The
maxSize argument is ignored; the underlying reader instead rejects a length greater than the number of complete longs remaining in the buffer.Parameters:
maxSize: the maximum size of the long array to read
Returns: the read long array
readMap
readMap(MethodWrapper<FriendlyByteBuf, ?, K, ?> keyReader, MethodWrapper<FriendlyByteBuf, ?, V, ?> valueReader): Map<K, V>Since1.8.4#Reads a map's keys and values from the buffer.
Parameters:
keyReader: reads each map keyvalueReader: reads each map value
Type Parameters:
K: the type of map keysV: the type of map values
Returns: the read map.
readMedium
Reads a signed medium from the current reader index.
Returns: the value read.
readNbt
Returns: the read nbt data.
readNullable
Parameters:
reader: the function to read the value from the buffer if it's not null
Type Parameters:
T: the value type
Returns: the read value or
null if it was null.See:
readOptional
Parameters:
reader: the function to read the optional value from the buffer if present
Type Parameters:
T: the value type
Returns: the optional value.
See:
readPublicKey
readRegistryKey
Reads a registry key from the buffer.
Parameters:
registry: the registry the key belongs to
Type Parameters:
T: the type of values identified by the registry key
Returns: the decoded key
readShort
Reads a short from the current reader index.
Returns: the read short value.
readString
readUnsignedByte
Returns: the read unsigned byte value, represented as a short.
readUnsignedInt
Reads an unsigned integer from the current reader index.
Returns: the value read, represented as a long.
readUnsignedMedium
Reads an unsigned medium from the current reader index.
Returns: the value read.
readUnsignedShort
Reads an unsigned short from the current reader index.
Returns: the read unsigned short value, represented as an int.
readUuid
readVarInt
Returns: the read int.
readVarLong
Returns: the read long.
receivePacket
handles a packet as though the client had received it, for testing a listener. Nothing is converted here: this handles the original packet object, not modified buffer bytes. The named and class overloads decode instead. A helper without an original packet is a no-op in all three receive overloads. Nothing is sent anywhere either, so this is the opposite direction from sendPacket() and the send event's
replacePacket has no bearing on it. The listener type is not checked before handling; the packet's handler receives the current client game connection, so use a packet compatible with that listener.Returns: self for chaining.
handles a packet of the named type as though the client had received it. If this helper has an original packet, decodes through toPacket(String) and handles the result with the client game connection. Otherwise this is a no-op. The bytes must be correctly positioned and describe a compatible client game packet.
Parameters:
packetName: the name of the packet's class that should be received
Returns: self for chaining.
Decodes the requested packet at the current reader position and handles it with the client game connection. A helper without an original packet is a no-op; the listener type is not checked before handling.
Parameters:
clazz: the class of the packet to receive
Returns: self for chaining.
reset
Restores the buffer contents and reader position captured when this helper was created. For a packet-backed helper, this is the encoded packet data, not an empty buffer. The helper's buffer is separate from the packet object; resetting it does not change that object. Registry access is retained when restoring a registry-backed buffer.
Returns: self for chaining.
resetIndices
Resets the readers and writers index to their respective last marked indices.
Returns: self for chaining.
See:
resetReaderIndex
resetWriterIndex
sendPacket
Send a packet of the given type, created from this buffer, to the server. Decodes through toPacket() at the current reader position. A helper without an original packet is a no-op. Sending requires a connection and a suitable serverbound packet.
Returns: self for chaining.
builds a packet of the named type from this buffer and sends it to the server. Decodes through the class overload at the current reader position. Requires a connection, a supported codec and bytes matching a suitable serverbound packet.
Parameters:
packetName: the name of the packet's class that should be sent
Returns: self for chaining.
Send a packet of the given type, created from this buffer, to the server.
Parameters:
clazz: the class of the packet to send
Returns: self for chaining.
setBoolean
Parameters:
index: the index to write tovalue: the value to store
Returns: self for chaining.
setByte
Writes a short at the given index without changing the writer index.
Parameters:
index: the index to write tovalue: the value to store
Returns: self for chaining.
setBytes
Parameters:
index: the index to write tobytes: the bytes to store
Returns: self for chaining.
setChar
Parameters:
index: the index to write tovalue: the value to store
Returns: self for chaining.
setDouble
Parameters:
index: the index to write tovalue: the value to store
Returns: self for chaining.
setFloat
Parameters:
index: the index to write tovalue: the value to store
Returns: self for chaining.
setIndices
Parameters:
readerIndex: the readers new indexwriterIndex: the writers new index
Returns: self for chaining.
setInt
Writes an integer at the given byte index without changing the writer index.
Parameters:
index: the byte index to write tovalue: the value to write
Returns: this buffer helper.
setLong
Parameters:
index: the index to write tovalue: the value to store
Returns: self for chaining.
setMedium
Writes a medium at the given index without changing the writer index.
Parameters:
index: the index to write tovalue: the value to store
Returns: self for chaining.
setReaderIndex
Parameters:
index: the readers new index
Returns: self for chaining.
setShort
Parameters:
index: the index to write tovalue: the value to store
Returns: self for chaining.
setWriterIndex
Parameters:
index: the writers new index
Returns: self for chaining.
setZero
Parameters:
index: the index to write tolength: the amount of zeros to write
Returns: self for chaining.
skipBytes
Moves the readerIndex of this buffer by the specified amount.
Parameters:
length: the amount of bytes to skip
Returns: self for chaining.
toPacket
the packet this buffer came from, rebuilt from the buffer. A fresh helper without an original packet returns
null. A packet-backed helper decodes the original packet class using its saved network phase and the current reader position. This returns a decoded packet, not the original object carried by the event.Returns: the packet for this buffer, or
null if no packet was used to create this helperthe packet named, built from this buffer. Looks up the convenience name and decodes at the current reader position. Packet-backed helpers use their saved phase; fresh helpers default to play. The names are the ones getPacketNames() lists.
Parameters:
packetName: the name of the packet's class that should be returned
Returns: the packet for this buffer.
Decodes a named packet at the current reader position using an explicit network phase.
Parameters:
packetName: a convenience name from getPacketNames()protocol: the network phase
Returns: the decoded packet
the packet of the given class, built from this buffer. Decodes at the current reader position. Non-play helpers use their saved phase; play helpers use the registered decoder lookup. The bytes must match the requested codec.
Parameters:
clazz: the class of the packet to return
Returns: the packet for this buffer.
Decodes at the current reader position using a phase-specific codec, including configuration custom payloads. The bytes must match the requested codec.
Parameters:
clazz: the packet classprotocol: the network phase
Returns: the decoded packet
toString
writeBitSet
Parameters:
bitSet: the bit set to store
Returns: self for chaining.
writeBlockHitResult
Parameters:
hitResult: the hit result to store
Returns: self for chaining.
writeBlockHitResult(Pos3D pos, String direction, BlockPosHelper blockPos, boolean missed, boolean insideBlock): PacketByteBufferHelperSince1.8.4#Parameters:
pos: the position of the BlockHitResultdirection: the direction of the BlockHitResultblockPos: the block pos of the BlockHitResultmissed: whether the BlockHitResult missedinsideBlock: whether the BlockHitResult is inside a block
Returns: self for chaining.
writeBlockPos
Parameters:
pos: the block position to store
Returns: self for chaining.
Parameters:
x: the x coordinate of the block position to storey: the y coordinate of the block position to storez: the z coordinate of the block position to store
Returns: self for chaining.
writeBoolean
Parameters:
value: the value to store
Returns: self for chaining.
writeByte
Writes a short at the current writer index.
Parameters:
value: the value to store
Returns: self for chaining.
writeByteArray
Parameters:
bytes: the bytes to store
Returns: self for chaining.
writeBytes
Parameters:
bytes: the bytes to store
Returns: self for chaining.
writeChar
Parameters:
value: the value to store
Returns: self for chaining.
writeChunkPos
Parameters:
x: the x coordinate of the chunk to storez: the z coordinate of the chunk to store
Returns: self for chaining.
Parameters:
chunk: the chunk to store
Returns: self for chaining.
writeChunkSectionPos
Parameters:
chunkX: the section's x coordinatey: the section's y coordinatechunkZ: the section's z coordinate
Returns: self for chaining.
Parameters:
chunk: the chunk whose x and z coordinates define the section positiony: the section's y coordinate
Returns: self for chaining.
writeCollection
writeCollection(Collection<T> collection, MethodWrapper<FriendlyByteBuf, T, ?, ?> writer): PacketByteBufferHelperSince1.8.4#Writes a collection and its elements to the buffer.
Parameters:
collection: the collection to writewriter: writes each element
Type Parameters:
T: the type of elements in the collection
Returns: self for chaining.
writeDate
Parameters:
date: the date to store
Returns: self for chaining.
writeDouble
Parameters:
value: the value to store
Returns: self for chaining.
writeEnumConstant
Parameters:
constant: the enum constant to encode by ordinal
Returns: self for chaining.
writeFloat
Parameters:
value: the value to store
Returns: self for chaining.
writeGlobalPos
Parameters:
dimension: the dimension identifier; vanilla dimensions includeoverworld,the_nether, andthe_endpos: the position to store
Returns: self for chaining.
Parameters:
dimension: the dimension identifier; vanilla dimensions includeoverworld,the_nether, andthe_endx: the x coordinate of the position to storey: the y coordinate of the position to storez: the z coordinate of the position to store
Returns: self for chaining.
writeIdentifier
Parameters:
id: the identifier to store
Returns: self for chaining.
writeInstant
Parameters:
instant: the instant to store
Returns: self for chaining.
writeInt
Writes an integer at the current writer index.
Parameters:
value: the value to write
Returns: this buffer helper.
writeIntArray
Parameters:
ints: the int array to store
Returns: self for chaining.
writeIntList
Writes an integer list to the buffer.
Parameters:
list: the list to write
Returns: self for chaining.
writeLong
Parameters:
value: the value to store
Returns: self for chaining.
writeLongArray
Parameters:
longs: the long array to store
Returns: self for chaining.
writeMap
writeMap(Map<K, V> map, MethodWrapper<FriendlyByteBuf, K, ?, ?> keyWriter, MethodWrapper<FriendlyByteBuf, V, ?, ?> valueWriter): PacketByteBufferHelperSince1.8.4#Writes a map and its keys and values to the buffer.
Parameters:
map: the map to writekeyWriter: writes each keyvalueWriter: writes each value
Type Parameters:
K: the type of map keysV: the type of map values
Returns: self for chaining.
writeMedium
Writes a medium at the current writer index.
Parameters:
value: the value to store
Returns: self for chaining.
writeNbt
Parameters:
nbt: the nbt
Returns: self for chaining.
writeNullable
writeNullable(Object value, MethodWrapper<FriendlyByteBuf, Object, ?, ?> writer): PacketByteBufferHelperSince1.8.4#Parameters:
value: the optional value to storewriter: the function to write the optional value if it's not null to the buffer
Returns: self for chaining.
See:
writeOptional
writeOptional(T value, MethodWrapper<FriendlyByteBuf, T, ?, ?> writer): PacketByteBufferHelperSince1.8.4#Parameters:
value: the optional value to storewriter: the function to write the optional value if present to the buffer
Type Parameters:
T: the value type
Returns: self for chaining.
See:
writePublicKey
Parameters:
key: the public key to store
Returns: self for chaining.
writeRegistryKey
Writes a registry key to the buffer.
Parameters:
key: the key to write
Returns: self for chaining.
writerIndex
Returns: the writers current position.
writeShort
Parameters:
value: the value to store
Returns: self for chaining.
writeString
Parameters:
string: the string to store
Returns: self for chaining.
Throws an exception if the string is longer than the given length.
Parameters:
string: the string to storemaxLength: the maximum length of the string
Returns: self for chaining.
writeUuid
Parameters:
uuid: the UUID to store
Returns: self for chaining.
writeVarInt
Parameters:
i: the integer to encode as a variable-length integer
Returns: self for chaining.
writeVarLong
Parameters:
l: the long to store
Returns: self for chaining.
writeZero
Parameters:
length: the amount of zeros to write
Returns: self for chaining.