blockbytes

Zero-dependency Minecraft protocol buffer types.
Supports Java Edition, Bedrock Edition, and ClassiCube.
Works in Node.js ≥16, Bun, Deno, and modern browsers — no Buffer polyfill needed.

npm install blockbytes

Quick Start

import { JavaBuffer, BedrockBuffer, ClassiCubeBuffer } from 'blockbytes';

// ── Java Edition ──────────────────────────────────────────────────────────
const buf = new JavaBuffer(64);
buf.writeVarInt(300);
buf.writeString('minecraft:stone');
buf.writePosition(10, 64, -5);
buf.writeUUID('550e8400-e29b-41d4-a716-446655440000');

const r = JavaBuffer.from(buf.toBuffer());
r.readVarInt();    // 300
r.readString();    // 'minecraft:stone'
r.readPosition();  // { x: 10, y: 64, z: -5 }
r.readUUID();      // '550e8400-...'

// ── From hex string ───────────────────────────────────────────────────────
const b2 = JavaBuffer.fromHex('ac02');  // VarInt 300
b2.readVarInt(); // 300

// ── Clone ─────────────────────────────────────────────────────────────────
const copy = buf.clone(); // deep copy

API

MCBuffer — base class (inherited by all three)

new MCBuffer(size)        allocate empty buffer of N bytes
new MCBuffer(buffer)      wrap existing Buffer / Uint8Array / ArrayBuffer
MCBuffer.from(buffer)     static factory
MCBuffer.alloc(size)      static factory
MCBuffer.fromHex(hex)     static factory — build from hex string  ← NEW

.seek(n)          set read cursor
.reset()          reset both cursors to 0
.readOffset       current read position
.writeOffset      current write position
.remaining        bytes left to read
.clone()          deep-copy (preserves subclass type)  ← NEW

.toBuffer()       → Buffer (Node.js) or Uint8Array (browser)
.toUint8Array()   → Uint8Array  (portable, always works)
.toHex()          → hex string

.peekUInt8()      read UInt8 without advancing cursor  ← NEW
.readRemaining()  read all remaining bytes             ← NEW

Shared primitives (Big-Endian):

| Method | Bytes | | :--- | :--- | | readUInt8() / writeUInt8(v) | 1 | | readInt8() / writeInt8(v) | 1 | | readUInt16BE() / writeUInt16BE(v) | 2 | | readInt16BE() / writeInt16BE(v) | 2 | | readUInt32BE() / writeUInt32BE(v) | 4 | | readInt32BE() / writeInt32BE(v) | 4 | | readUInt64BE() / writeUInt64BE(v) | 8 → BigInt | | readInt64BE() / writeInt64BE(v) | 8 → BigInt | | readFloatBE() / writeFloatBE(v) | 4 | | readDoubleBE() / writeDoubleBE(v) | 8 | | readBool() / writeBool(v) | 1 | | readBytes(n) / writeBytes(data) | n |

JavaBuffer

import { JavaBuffer } from 'blockbytes';
// or: import { JavaBuffer } from 'blockbytes/java';

| Type | Read | Write | | :--- | :--- | :--- | | VarInt (signed 32-bit) | readVarInt() | writeVarInt(v) | | VarLong (signed 64-bit) | readVarLong() → BigInt | writeVarLong(v) | | String (VarInt + UTF-8) | readString() | writeString(s) | | Identifier (namespace:value) | readIdentifier() | writeIdentifier(s) | | Chat (JSON text component) | readChat() → object | writeChat(v) | ← NEW | | Position (packed 64-bit) | readPosition() → {x,y,z} | writePosition(x,y,z) | | Angle (1/256 turn → degrees) | readAngle() | writeAngle(deg) | | UUID (2 × Int64) | readUUID() → "xxxxxxxx-..." | writeUUID(uuid) | | Byte array (VarInt + bytes) | readByteArray() | writeByteArray(data) | | Long array (VarInt + Int64[]) | readLongArray() | writeLongArray(arr) | | Bit set (VarInt longs) | readBitSet() → bool[] | writeBitSet(bits) | | Fixed bit set (no prefix) | readFixedBitSet(n) | writeFixedBitSet(bits, n?) | ← NEW | | NBT (raw bytes) | readNBT(n?) | writeNBT(data) | ← NEW | | Optional | readOptional(fn) | writeOptional(v, fn) | | Array (VarInt-prefixed) | readArray(fn) | writeArray(arr, fn) |

Helpers:

JavaBuffer.varIntSize(v)  // → 1–5, bytes a VarInt would take  ← NEW

BedrockBuffer

import { BedrockBuffer } from 'blockbytes';
// or: import { BedrockBuffer } from 'blockbytes/bedrock';

All integers are Little-Endian unless noted.

| Type | Read | Write | | :--- | :--- | :--- | | UInt16LE / Int16LE | readUInt16LE() | writeUInt16LE(v) | | UInt32LE / Int32LE | readUInt32LE() | writeUInt32LE(v) | | UInt64LE / Int64LE | readUInt64LE() → BigInt | writeUInt64LE(v) | | FloatLE / DoubleLE | readFloatLE() | writeFloatLE(v) | | VarUInt (unsigned 32-bit) | readVarUInt() | writeVarUInt(v) | | VarULong (unsigned 64-bit) | readVarULong() → BigInt | writeVarULong(v) | ← NEW | | ZigZag32 / VarInt | readZigZag32() / readVarInt() | writeZigZag32(v) | | ZigZag64 / VarLong | readZigZag64() / readVarLong() | writeZigZag64(v) | | Actor Runtime ID | readActorRuntimeID() → BigInt | writeActorRuntimeID(v) | ← NEW | | Actor Unique ID | readActorUniqueID() → BigInt | writeActorUniqueID(v) | ← NEW | | String (VarUInt + UTF-8) | readString() | writeString(s) | | Byte array (VarUInt + bytes) | readByteArray() | writeByteArray(data) | ← NEW | | UUID (2 × UInt64LE) | readUUID() → "xxxxxxxx-..." | writeUUID(uuid) | | BlockPos (ZigZag, VarUInt, ZigZag) | readBlockPos() → {x,y,z} | writeBlockPos(x,y,z) | | Vec3 (3 × FloatLE) | readVec3() → {x,y,z} | writeVec3(x,y,z) | | Vec2 (2 × FloatLE) | readVec2() → {x,y} | writeVec2(x,y) |

Note: Bedrock docs name ZigZag32 as "VarInt" and ZigZag64 as "VarLong". Both names are available: readVarInt() = readZigZag32(), etc.

ClassiCubeBuffer

import { ClassiCubeBuffer } from 'blockbytes';
// or: import { ClassiCubeBuffer } from 'blockbytes/classicube';

| Type | Read | Write | | :--- | :--- | :--- | | String (fixed 64-byte ASCII) | readString() | writeString(s) | | Coord — raw fixed-point Int16 | readCoord() | writeCoord(v) | | Coord — as float blocks (÷32) | readCoordF() | writeCoordF(blocks) | | ByteCoord (block-aligned 0–255) | readByteCoord() | writeByteCoord(v) | | Yaw (0–255 → 0–360°) | readYaw() | writeYaw(deg) | | Pitch (0–255 → 0–360°) | readPitch() | writePitch(deg) | | BlockType (UInt8) | readBlockType() | writeBlockType(id) | | PlayerType (0=normal, 100=op) | readPlayerType() | writePlayerType(v) | ← NEW |

CPE extensions:

| Type | Read | Write | Extension | | :--- | :--- | :--- | :--- | | ExtBlockType (UInt16BE) | readExtBlockType() | writeExtBlockType(id) | CustomBlocks | | MapDim (UInt16BE) | readMapDim() | writeMapDim(v) | LevelDimensions | | ClickDistance (Int16BE) | readClickDistance() | writeClickDistance(v) | ClickDistance | | ExtInfo payload | readExtInfo() | writeExtInfo(app, count) | — | | ExtEntry payload | readExtEntry() | writeExtEntry(name, ver) | — |

Helpers:

ClassiCubeBuffer.stripColors(s)  // remove §N color codes