Struct MinecraftBuffer
Namespace: Void.Minecraft.Buffers
Assembly: Void.Minecraft.dll
Provides cursor-based reading and writing of Minecraft protocol values over span, sequence, or stream-backed storage.
public ref struct MinecraftBufferInherited Members
object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()
Remarks
Read and write operations advance
Constructors
MinecraftBuffer()
Prevents creation of an uninitialized buffer.
public MinecraftBuffer()Exceptions
Always thrown because a backing store is required.
MinecraftBuffer(Span<byte>)
Initializes a readable and writable fixed-capacity buffer over a span.
public MinecraftBuffer(Span<byte> memory)Parameters
The backing span, retained for the lifetime of this stack-only buffer.
MinecraftBuffer(ReadOnlySpan<byte>)
Initializes a read-only buffer over a span.
public MinecraftBuffer(ReadOnlySpan<byte> span)Parameters
span ReadOnlySpan<byte>
The backing read-only span.
MinecraftBuffer(ReadOnlySequence<byte>)
Initializes a read-only buffer over a possibly segmented byte sequence.
public MinecraftBuffer(ReadOnlySequence<byte> sequence)Parameters
sequence ReadOnlySequence<byte>
The backing sequence, retained without copying.
MinecraftBuffer(MemoryStream)
Initializes a buffer over an existing memory stream at its current position.
public MinecraftBuffer(MemoryStream memoryStream)Parameters
memoryStream MemoryStream
The backing stream, retained without transferring disposal ownership.
Properties
HasData
Gets whether unread bytes remain after the current position.
public readonly bool HasData { get; }Property Value
Length
Gets the current length of the backing storage in bytes.
public readonly long Length { get; }Property Value
Position
Gets the current zero-based byte position.
public readonly long Position { get; }Property Value
Methods
CopyAsBufferSpan(bool)
Copies buffer bytes into a newly allocated writable
public BufferSpan CopyAsBufferSpan(bool read = false)Parameters
read bool
true to copy only unread bytes and advance this buffer to the end; false to copy all bytes and preserve this buffer’s position in the returned copy.
Returns
A buffer span backed by a new byte array.
Dump()
Formats the current length, position, and complete hexadecimal contents for diagnostics.
public string Dump()Returns
A diagnostic buffer description.
DumpBytes()
Returns all bytes from the beginning through the current length without changing the final position.
public ReadOnlySpan<byte> DumpBytes()Returns
A view of the complete buffer contents.
DumpHex()
Formats all buffer bytes as an uppercase hexadecimal string without changing the final position.
public string DumpHex()Returns
The complete buffer contents in hexadecimal form.
GetVarIntSize(int)
Calculates the number of bytes required by Minecraft’s variable-length encoding of a 32-bit integer.
public static int GetVarIntSize(int value)Parameters
value int
The integer to measure.
Returns
A value from 1 through 5.
Read(long)
Reads a contiguous span of bytes and advances the position.
public ReadOnlySpan<byte> Read(long length)Parameters
length long
The number of bytes to read.
Returns
A read-only span containing the requested bytes.
ReadBoolean()
Reads one byte and converts it to a Boolean value.
public bool ReadBoolean()Returns
false for zero; otherwise, true.
ReadComponent(bool)
Reads a text component encoded as unnamed NBT or a length-prefixed JSON string.
public Component ReadComponent(bool asNbt = true)Parameters
asNbt bool
true to read unnamed binary NBT; false to parse JSON text.
Returns
The deserialized component.
ReadDouble()
Reads an IEEE 754 double-precision value in big-endian byte order.
public double ReadDouble()Returns
The decoded value.
ReadFloat()
Reads an IEEE 754 single-precision value in big-endian byte order.
public float ReadFloat()Returns
The decoded value.
ReadInt()
Reads a signed 32-bit integer in big-endian order.
public int ReadInt()Returns
The decoded value.
ReadJsonString()
Reads a length-prefixed UTF-8 string and parses it as a JSON node.
public JsonNode ReadJsonString()Returns
The parsed JSON node.
Exceptions
Parsing produces a null JSON node.
ReadLong()
Reads a signed 64-bit integer in big-endian order.
public long ReadLong()Returns
The decoded value.
ReadProperty()
Reads a length-prefixed profile property and its optional signature.
public Property ReadProperty()Returns
The decoded profile property.
ReadPropertyArray()
Reads a variable-length count followed by that many profile properties.
public Property[] ReadPropertyArray()Returns
Property[]
A newly allocated array containing the decoded properties.
ReadShort()
Reads a signed 16-bit integer in big-endian order.
public short ReadShort()Returns
The decoded value.
ReadString(int)
Reads a Minecraft protocol string encoded as a VarInt byte length followed by UTF-8 bytes.
public string ReadString(int maxLength = 32767)Parameters
maxLength int
Maximum allowed character count for the decoded string.
Returns
The decoded UTF-8 string. The returned value is never null.
Examples
var text = buffer.ReadString(16);Remarks
This method validates the decoded character length, not the encoded byte length. If maxLength is less than or equal to 0, length validation is skipped.
The buffer read position advances by the size of the string length prefix and payload bytes.
Exceptions
The length prefix is not a valid Minecraft VarInt value.
The decoded string length exceeds maxLength.
Propagated from the underlying buffer implementation in unsupported scenarios.
See Also
ReadTag(bool)
Reads one binary NBT tag from the current position.
public NbtTag ReadTag(bool readName = true)Parameters
readName bool
true to read the root tag name; otherwise, false.
Returns
The parsed tag. Only the bytes consumed by that tag are removed from the unread region.
ReadToEnd()
Reads all bytes from the current position through the current length.
public ReadOnlySpan<byte> ReadToEnd()Returns
The unread bytes; the position advances to the end.
ReadUnsignedByte()
Reads one unsigned byte and advances the position by one.
public byte ReadUnsignedByte()Returns
The byte read from the current position.
ReadUnsignedShort()
Reads an unsigned 16-bit integer in big-endian order.
public ushort ReadUnsignedShort()Returns
The decoded value.
ReadUuid()
Reads a UUID as two big-endian 64-bit protocol values.
public Uuid ReadUuid()Returns
The decoded UUID.
ReadUuidAsIntArray()
Reads a UUID from the four-integer representation used by some protocol fields.
public Uuid ReadUuidAsIntArray()Returns
The decoded UUID.
ReadVarInt()
Reads a Minecraft variable-length signed 32-bit integer.
public int ReadVarInt()Returns
The decoded integer.
Exceptions
The encoding uses more than five bytes.
ReadVarLong()
Reads a Minecraft variable-length signed 64-bit integer.
public long ReadVarLong()Returns
The decoded integer.
Exceptions
The encoding uses more than ten bytes.
ReadVarShort()
Reads the protocol’s one-to-three-byte variable short representation.
public int ReadVarShort()Returns
The decoded nonnegative integer value.
Reset()
Resets the backing buffer’s position to its initial position.
public void Reset()Seek(long)
Sets the position to an absolute byte offset from the beginning.
public void Seek(long offset)Parameters
offset long
The new absolute position.
Seek(long, SeekOrigin)
Moves the position relative to a selected origin.
public void Seek(long offset, SeekOrigin origin)Parameters
offset long
The signed byte offset from origin.
origin SeekOrigin
The reference point used to calculate the new position.
Write(scoped ReadOnlySpan<byte>)
Writes a byte span and advances the position by its length.
public void Write(scoped ReadOnlySpan<byte> data)Parameters
data ReadOnlySpan<byte>
The bytes to write.
Write(Stream)
Copies bytes from a stream’s current position into this buffer.
public void Write(Stream stream)Parameters
stream Stream
The source stream. This method does not dispose it.
WriteBoolean(bool)
Writes a Boolean as 0 or 1 in one byte.
public void WriteBoolean(bool value)Parameters
value bool
The value to write.
WriteComponent(Component, bool, bool)
Writes a text component as binary NBT or a length-prefixed JSON string.
public void WriteComponent(Component value, bool asNbt = true, bool writeNbtName = false)Parameters
value Component
The component to serialize.
asNbt bool
true to use binary NBT; false to use JSON.
writeNbtName bool
When writing NBT, whether to include the root tag name.
WriteDouble(double)
Writes an IEEE 754 double-precision value in big-endian byte order.
public void WriteDouble(double value)Parameters
value double
The value to write.
WriteFloat(float)
Writes an IEEE 754 single-precision value in big-endian byte order.
public void WriteFloat(float value)Parameters
value float
The value to write.
WriteInt(int)
Writes a signed 32-bit integer in big-endian order.
public void WriteInt(int value)Parameters
value int
The value to write.
WriteJsonString(JsonNode, JsonSerializerOptions?)
Serializes a JSON node and writes it as a length-prefixed UTF-8 string.
public void WriteJsonString(JsonNode node, JsonSerializerOptions? jsonSerializerOptions = null)Parameters
node JsonNode
The node to serialize.
jsonSerializerOptions JsonSerializerOptions?
Optional serializer options; null uses compact default output.
WriteLong(long)
Writes a signed 64-bit integer in big-endian order.
public void WriteLong(long value)Parameters
value long
The value to write.
WriteProperty(Property)
Writes a profile property and its optional signature.
public void WriteProperty(Property value)Parameters
value Property
The property to write.
Exceptions
value is marked as signed but has a null, empty, or whitespace signature.
WritePropertyArray(Property[]?)
Writes a profile property array using Minecraft’s length-prefixed format.
public void WritePropertyArray(Property[]? value)Parameters
value Property[]?
The properties to serialize. When null, an empty array is written.
Examples
buffer.WritePropertyArray(profile.Properties);Remarks
This method writes a VarInt element count first, then serializes each
Passing null is equivalent to passing [], so the written count is 0.
Exceptions
Propagated from
See Also
MinecraftBuffer.ReadPropertyArray()
WriteShort(short)
Writes a signed 16-bit integer to the buffer using Minecraft’s big-endian binary encoding.
public void WriteShort(short value)Parameters
value short
The value to write.
Remarks
This method writes exactly two bytes and advances the current buffer position by two.
The value is written in network order, which matches the encoding used by the Minecraft protocol.
Exceptions
The underlying backing buffer does not support writes.
InternalBufferOverflowException
The target writable span does not have enough capacity for the encoded value.
WriteString(ReadOnlySpan<char>)
Writes a Minecraft protocol string as UTF-8 bytes prefixed by its byte length encoded as VarInt.
public void WriteString(ReadOnlySpan<char> value)Parameters
value ReadOnlySpan<char>
The characters to encode and write.
Examples
buffer.WriteString("minecraft:stone");Remarks
The method writes the UTF-8 byte count first, then writes the encoded bytes. An empty span writes a zero length prefix and no payload bytes.
This method mutates the buffer by advancing the current position and appending or overwriting data depending on the backing storage.
Exceptions
The underlying backing buffer is read-only.
InternalBufferOverflowException
The target writable span does not have enough capacity for the encoded payload.
See Also
MinecraftBuffer.WriteVarInt(int)
WriteTag(NbtTag, bool)
Serializes and writes one binary NBT tag.
public void WriteTag(NbtTag value, bool writeName = true)Parameters
value NbtTag
The tag to serialize.
writeName bool
true to include the root tag name; otherwise, false.
WriteUnsignedByte(byte)
Writes one unsigned byte and advances the position by one.
public void WriteUnsignedByte(byte value)Parameters
value byte
The byte to write.
WriteUnsignedShort(ushort)
Writes an unsigned 16-bit integer to the buffer using Minecraft’s big-endian binary encoding.
public void WriteUnsignedShort(ushort value)Parameters
value ushort
The value to write.
Remarks
This method writes exactly two bytes and advances the current buffer position by two.
Exceptions
The underlying backing buffer does not support writes.
InternalBufferOverflowException
The target writable span does not have enough capacity for the encoded value.
WriteUuid(Uuid)
Writes a UUID as two big-endian 64-bit protocol values.
public void WriteUuid(Uuid value)Parameters
value Uuid
The UUID to write.
WriteUuidAsIntArray(Uuid)
Writes a UUID using its four-integer representation.
public void WriteUuidAsIntArray(Uuid value)Parameters
value Uuid
The UUID to write.
WriteVarInt(int)
Writes a signed 32-bit integer using Minecraft variable-length encoding.
public void WriteVarInt(int value)Parameters
value int
The integer to write.
WriteVarLong(long)
Writes a signed 64-bit integer using Minecraft variable-length encoding.
public void WriteVarLong(long value)Parameters
value long
The integer to write.
WriteVarShort(int)
Writes the low 23 bits of an integer using the protocol’s variable short representation.
public void WriteVarShort(int value)Parameters
value int
The value whose low 23 bits are written.