protocol-classicube 1.0.0-beta.1

package/Binary.js

@@ -0,0 +1,149 @@
+/**
+ * ClassiCube Protocol - Binary Read/Write Helpers
+ *
+ * Classic protocol types:
+ *   Byte      - 1 byte unsigned
+ *   SByte     - 1 byte signed
+ *   Short     - 2 bytes signed big-endian
+ *   Int       - 4 bytes signed big-endian
+ *   String    - 64 bytes, padded with spaces (0x20), ASCII
+ *   ByteArray - 1024 bytes of raw data
+ *   FByte     - Fixed-point: value / 32 for positions
+ */
+
+class BinaryWriter {
+  constructor() {
+    this._chunks = [];
+    this.length = 0;
+  }
+
+  writeByte(value) {
+    const buf = Buffer.alloc(1);
+    buf.writeUInt8(value & 0xFF, 0);
+    this._chunks.push(buf);
+    this.length += 1;
+    return this;
+  }
+
+  writeSByte(value) {
+    const buf = Buffer.alloc(1);
+    buf.writeInt8(value, 0);
+    this._chunks.push(buf);
+    this.length += 1;
+    return this;
+  }
+
+  writeShort(value) {
+    const buf = Buffer.alloc(2);
+    buf.writeInt16BE(value, 0);
+    this._chunks.push(buf);
+    this.length += 2;
+    return this;
+  }
+
+  writeInt(value) {
+    const buf = Buffer.alloc(4);
+    buf.writeInt32BE(value, 0);
+    this._chunks.push(buf);
+    this.length += 4;
+    return this;
+  }
+
+  /**
+   * Classic string: always 64 bytes, space-padded
+   */
+  writeString(value) {
+    const buf = Buffer.alloc(64, 0x20); // fill with spaces
+    const encoded = Buffer.from(String(value).substring(0, 64), 'ascii');
+    encoded.copy(buf, 0);
+    this._chunks.push(buf);
+    this.length += 64;
+    return this;
+  }
+
+  /**
+   * ByteArray: always 1024 bytes
+   */
+  writeByteArray(data) {
+    const buf = Buffer.alloc(1024, 0x00);
+    if (Buffer.isBuffer(data)) {
+      data.copy(buf, 0, 0, Math.min(data.length, 1024));
+    }
+    this._chunks.push(buf);
+    this.length += 1024;
+    return this;
+  }
+
+  /**
+   * Fixed-point position byte: value * 32
+   */
+  writeFByte(value) {
+    return this.writeSByte(Math.round(value * 32));
+  }
+
+  toBuffer() {
+    return Buffer.concat(this._chunks);
+  }
+}
+
+class BinaryReader {
+  constructor(buffer) {
+    this._buf = buffer;
+    this._offset = 0;
+  }
+
+  get bytesLeft() {
+    return this._buf.length - this._offset;
+  }
+
+  readByte() {
+    const val = this._buf.readUInt8(this._offset);
+    this._offset += 1;
+    return val;
+  }
+
+  readSByte() {
+    const val = this._buf.readInt8(this._offset);
+    this._offset += 1;
+    return val;
+  }
+
+  readShort() {
+    const val = this._buf.readInt16BE(this._offset);
+    this._offset += 2;
+    return val;
+  }
+
+  readInt() {
+    const val = this._buf.readInt32BE(this._offset);
+    this._offset += 4;
+    return val;
+  }
+
+  /**
+   * Classic string: read 64 bytes, trim trailing spaces
+   */
+  readString() {
+    const buf = this._buf.slice(this._offset, this._offset + 64);
+    this._offset += 64;
+    return buf.toString('ascii').trimEnd();
+  }
+
+  /**
+   * ByteArray: read 1024 bytes
+   */
+  readByteArray() {
+    const buf = this._buf.slice(this._offset, this._offset + 1024);
+    this._offset += 1024;
+    return Buffer.from(buf);
+  }
+
+  /**
+   * Fixed-point position byte: raw / 32
+   */
+  readFByte() {
+    return this.readSByte() / 32;
+  }
+}
+
+module.exports = { BinaryWriter, BinaryReader };

package/PacketIDs.js

@@ -0,0 +1,35 @@
+/**
+ * ClassiCube Protocol - Packet IDs
+ * Based on the Classic Minecraft / ClassiCube protocol spec
+ */
+
+const PacketIDs = {
+  // Server -> Client
+  SERVER: {
+    SERVER_IDENTIFICATION: 0x00,
+    PING:                  0x01,
+    LEVEL_INITIALIZE:      0x02,
+    LEVEL_DATA_CHUNK:      0x03,
+    LEVEL_FINALIZE:        0x04,
+    SET_BLOCK:             0x06,
+    SPAWN_PLAYER:          0x07,
+    PLAYER_TELEPORT:       0x08,
+    PLAYER_UPDATE:         0x09,
+    PLAYER_MOVE:           0x0A,
+    PLAYER_ROTATE:         0x0B,
+    DESPAWN_PLAYER:        0x0C,
+    CHAT_MESSAGE:          0x0D,
+    DISCONNECT:            0x0E,
+    UPDATE_USER_TYPE:      0x0F,
+  },
+
+  // Client -> Server
+  CLIENT: {
+    PLAYER_IDENTIFICATION: 0x00,
+    SET_BLOCK:             0x05,
+    PLAYER_TELEPORT:       0x08,
+    CHAT_MESSAGE:          0x0D,
+  },
+};
+
+module.exports = PacketIDs;

package/client/ClientConnection.js

@@ -0,0 +1,308 @@
+/**
+ * ClientConnection
+ *
+ * Wraps a raw TCP socket from the client's perspective.
+ * Handles framing, dispatches ALL server packets,
+ * and exposes send helpers for client->server packets.
+ */
+
+const { EventEmitter } = require('events');
+const net = require('net');
+const PacketIDs = require('../PacketIDs');
+const { BinaryWriter } = require('../Binary');
+
+// Packet deserializers
+const ServerIdentification = require('../packets/ServerIdentification');
+const Ping                 = require('../packets/Ping');
+const LevelInitialize      = require('../packets/LevelInitialize');
+const LevelDataChunk       = require('../packets/LevelDataChunk');
+const LevelFinalize        = require('../packets/LevelFinalize');
+const SpawnPlayer          = require('../packets/SpawnPlayer');
+const PlayerTeleport       = require('../packets/PlayerTeleport');
+const PlayerUpdate         = require('../packets/PlayerUpdate');
+const PlayerMove           = require('../packets/PlayerMove');
+const PlayerRotate         = require('../packets/PlayerRotate');
+const DespawnPlayer        = require('../packets/DespawnPlayer');
+const SetBlock             = require('../packets/SetBlock');
+const ChatMessage          = require('../packets/ChatMessage');
+const Disconnect           = require('../packets/Disconnect');
+const UpdateUserType       = require('../packets/UpdateUserType');
+
+// Fixed packet sizes for server->client packets
+const SERVER_PACKET_SIZES = {
+  [PacketIDs.SERVER.SERVER_IDENTIFICATION]: 131,
+  [PacketIDs.SERVER.PING]:                   1,
+  [PacketIDs.SERVER.LEVEL_INITIALIZE]:        1,
+  [PacketIDs.SERVER.LEVEL_DATA_CHUNK]:     1028,
+  [PacketIDs.SERVER.LEVEL_FINALIZE]:          7,
+  [PacketIDs.SERVER.SET_BLOCK]:               8,
+  [PacketIDs.SERVER.SPAWN_PLAYER]:           74,
+  [PacketIDs.SERVER.PLAYER_TELEPORT]:        10,
+  [PacketIDs.SERVER.PLAYER_UPDATE]:           7,
+  [PacketIDs.SERVER.PLAYER_MOVE]:             5,
+  [PacketIDs.SERVER.PLAYER_ROTATE]:           4,
+  [PacketIDs.SERVER.DESPAWN_PLAYER]:          2,
+  [PacketIDs.SERVER.CHAT_MESSAGE]:           66,
+  [PacketIDs.SERVER.DISCONNECT]:             65,
+  [PacketIDs.SERVER.UPDATE_USER_TYPE]:        2,
+};
+
+class ClientConnection extends EventEmitter {
+  constructor() {
+    super();
+    this.socket   = null;
+    this._buffer  = Buffer.alloc(0);
+
+    // Re-ensamble del level
+    this._levelChunks    = [];
+    this._receivingLevel = false;
+
+    // Estado local del cliente
+    this.x     = 0;
+    this.y     = 0;
+    this.z     = 0;
+    this.yaw   = 0;
+    this.pitch = 0;
+    this.op    = false;
+
+    // Entidades de otros jugadores: Map<playerId, { name, x, y, z, yaw, pitch }>
+    this.players = new Map();
+  }
+
+  /**
+   * Conectar a un servidor ClassiCube.
+   * @param {string} host
+   * @param {number} port
+   * @returns {Promise<void>}
+   */
+  connect(host, port) {
+    return new Promise((resolve, reject) => {
+      this.socket = net.createConnection({ host, port }, () => resolve());
+      this.socket.on('data',  (chunk) => this._onData(chunk));
+      this.socket.on('close', ()      => this.emit('close'));
+      this.socket.on('error', (err)   => { this.emit('error', err); reject(err); });
+    });
+  }
+
+  disconnect() {
+    if (this.socket && !this.socket.destroyed) this.socket.destroy();
+  }
+
+  // ──────────────────────────────────────────────
+  // Framing
+  // ──────────────────────────────────────────────
+
+  _onData(chunk) {
+    this._buffer = Buffer.concat([this._buffer, chunk]);
+
+    while (this._buffer.length > 0) {
+      const packetId = this._buffer[0];
+      const size = SERVER_PACKET_SIZES[packetId];
+
+      if (size === undefined) {
+        this.emit('error', new Error(`Unknown server packet ID: 0x${packetId.toString(16)}`));
+        this._buffer = Buffer.alloc(0);
+        return;
+      }
+
+      if (this._buffer.length < size) break;
+
+      const raw = this._buffer.slice(0, size);
+      this._buffer = this._buffer.slice(size);
+      this._dispatch(packetId, raw);
+    }
+  }
+
+  _dispatch(packetId, buf) {
+    try {
+      switch (packetId) {
+
+        case PacketIDs.SERVER.SERVER_IDENTIFICATION: {
+          const pkt = ServerIdentification.deserialize(buf);
+          this.op = pkt.op;
+          this.emit('serverIdentification', pkt);
+          break;
+        }
+
+        case PacketIDs.SERVER.PING:
+          this.emit('ping');
+          break;
+
+        case PacketIDs.SERVER.LEVEL_INITIALIZE:
+          this._levelChunks    = [];
+          this._receivingLevel = true;
+          this.emit('levelInitialize');
+          break;
+
+        case PacketIDs.SERVER.LEVEL_DATA_CHUNK: {
+          const pkt = LevelDataChunk.deserialize(buf);
+          if (this._receivingLevel) {
+            this._levelChunks.push(pkt.chunkData.slice(0, pkt.chunkLength));
+          }
+          this.emit('levelDataChunk', pkt);
+          break;
+        }
+
+        case PacketIDs.SERVER.LEVEL_FINALIZE: {
+          const pkt      = LevelFinalize.deserialize(buf);
+          const levelData = Buffer.concat(this._levelChunks);
+          this._receivingLevel = false;
+          this._levelChunks    = [];
+          this.emit('levelFinalize', { ...pkt, levelData });
+          break;
+        }
+
+        case PacketIDs.SERVER.SET_BLOCK:
+          this.emit('setBlock', SetBlock.server.deserialize(buf));
+          break;
+
+        case PacketIDs.SERVER.SPAWN_PLAYER: {
+          const pkt = SpawnPlayer.deserialize(buf);
+          if (pkt.playerId === -1) {
+            // Somos nosotros
+            this.x = pkt.x; this.y = pkt.y; this.z = pkt.z;
+            this.yaw = pkt.yaw; this.pitch = pkt.pitch;
+          } else {
+            this.players.set(pkt.playerId, {
+              name: pkt.name,
+              x: pkt.x, y: pkt.y, z: pkt.z,
+              yaw: pkt.yaw, pitch: pkt.pitch,
+            });
+          }
+          this.emit('spawnPlayer', pkt);
+          break;
+        }
+
+        case PacketIDs.SERVER.PLAYER_TELEPORT: {
+          const pkt = PlayerTeleport.deserialize(buf);
+          if (pkt.playerId === -1) {
+            this.x = pkt.x; this.y = pkt.y; this.z = pkt.z;
+            this.yaw = pkt.yaw; this.pitch = pkt.pitch;
+          } else {
+            const p = this.players.get(pkt.playerId);
+            if (p) {
+              p.x = pkt.x; p.y = pkt.y; p.z = pkt.z;
+              p.yaw = pkt.yaw; p.pitch = pkt.pitch;
+            }
+          }
+          this.emit('playerTeleport', pkt);
+          break;
+        }
+
+        case PacketIDs.SERVER.PLAYER_UPDATE: {
+          const pkt = PlayerUpdate.deserialize(buf);
+          const p = this.players.get(pkt.playerId);
+          if (p) {
+            p.x += pkt.dx; p.y += pkt.dy; p.z += pkt.dz;
+            p.yaw = pkt.yaw; p.pitch = pkt.pitch;
+          }
+          this.emit('playerUpdate', pkt);
+          break;
+        }
+
+        case PacketIDs.SERVER.PLAYER_MOVE: {
+          const pkt = PlayerMove.deserialize(buf);
+          const p = this.players.get(pkt.playerId);
+          if (p) { p.x += pkt.dx; p.y += pkt.dy; p.z += pkt.dz; }
+          this.emit('playerMove', pkt);
+          break;
+        }
+
+        case PacketIDs.SERVER.PLAYER_ROTATE: {
+          const pkt = PlayerRotate.deserialize(buf);
+          const p = this.players.get(pkt.playerId);
+          if (p) { p.yaw = pkt.yaw; p.pitch = pkt.pitch; }
+          this.emit('playerRotate', pkt);
+          break;
+        }
+
+        case PacketIDs.SERVER.DESPAWN_PLAYER: {
+          const pkt = DespawnPlayer.deserialize(buf);
+          this.players.delete(pkt.playerId);
+          this.emit('despawnPlayer', pkt);
+          break;
+        }
+
+        case PacketIDs.SERVER.CHAT_MESSAGE:
+          this.emit('chatMessage', ChatMessage.deserialize(buf));
+          break;
+
+        case PacketIDs.SERVER.DISCONNECT: {
+          const pkt = Disconnect.deserialize(buf);
+          this.emit('disconnect', pkt);
+          this.disconnect();
+          break;
+        }
+
+        case PacketIDs.SERVER.UPDATE_USER_TYPE: {
+          const pkt = UpdateUserType.deserialize(buf);
+          this.op = pkt.op;
+          this.emit('updateUserType', pkt);
+          break;
+        }
+
+        default:
+          this.emit('unknownPacket', { packetId, buf });
+      }
+    } catch (err) {
+      this.emit('error', err);
+    }
+  }
+
+  // ──────────────────────────────────────────────
+  // Write helper
+  // ──────────────────────────────────────────────
+
+  _write(buf) {
+    if (this.socket && !this.socket.destroyed) this.socket.write(buf);
+  }
+
+  // ──────────────────────────────────────────────
+  // Send helpers - Client -> Server
+  // ──────────────────────────────────────────────
+
+  /**
+   * Login handshake. Primer paquete que debe enviarse.
+   * @param {object} opts
+   * @param {string} opts.username
+   * @param {string} [opts.verificationKey='-']
+   */
+  sendIdentification({ username, verificationKey = '-' }) {
+    const buf = new BinaryWriter()
+      .writeByte(PacketIDs.CLIENT.PLAYER_IDENTIFICATION)
+      .writeByte(7) // protocol version
+      .writeString(username)
+      .writeString(verificationKey)
+      .writeByte(0x00) // unused
+      .toBuffer();
+    this._write(buf);
+  }
+
+  /**
+   * @param {object} opts
+   * @param {number} opts.x
+   * @param {number} opts.y
+   * @param {number} opts.z
+   * @param {number} opts.mode      - 0 = destruir, 1 = colocar
+   * @param {number} opts.blockType - ID del bloque
+   */
+  sendSetBlock({ x, y, z, mode, blockType }) {
+    this._write(SetBlock.client.serialize({ x, y, z, mode, blockType }));
+  }
+
+  /**
+   * Actualiza la posicion del cliente en el servidor.
+   */
+  sendTeleport({ x, y, z, yaw = 0, pitch = 0 }) {
+    // playerId = -1 (self) cuando el cliente envia su propia posicion
+    this._write(PlayerTeleport.serialize({ playerId: -1, x, y, z, yaw, pitch }));
+    this.x = x; this.y = y; this.z = z;
+    this.yaw = yaw; this.pitch = pitch;
+  }
+
+  sendChat(message) {
+    this._write(ChatMessage.serialize({ playerId: -1, message }));
+  }
+}
+
+module.exports = ClientConnection;

package/index.js

@@ -0,0 +1,62 @@
+/**
+ * classicube-protocol
+ *
+ * Implementacion completa del protocolo ClassiCube / Classic Minecraft.
+ * Protocol version 7. Sin dependencias externas. Node.js 14+.
+ */
+
+'use strict';
+
+const PacketIDs                        = require('./PacketIDs');
+const { BinaryWriter, BinaryReader }   = require('./Binary');
+const ServerConnection                 = require('./server/ServerConnection');
+const ClientConnection                 = require('./client/ClientConnection');
+
+// Packets
+const PlayerIdentification = require('./packets/PlayerIdentification');
+const ServerIdentification = require('./packets/ServerIdentification');
+const Ping                 = require('./packets/Ping');
+const LevelInitialize      = require('./packets/LevelInitialize');
+const LevelDataChunk       = require('./packets/LevelDataChunk');
+const LevelFinalize        = require('./packets/LevelFinalize');
+const SpawnPlayer          = require('./packets/SpawnPlayer');
+const PlayerTeleport       = require('./packets/PlayerTeleport');
+const PlayerUpdate         = require('./packets/PlayerUpdate');
+const PlayerMove           = require('./packets/PlayerMove');
+const PlayerRotate         = require('./packets/PlayerRotate');
+const DespawnPlayer        = require('./packets/DespawnPlayer');
+const SetBlock             = require('./packets/SetBlock');
+const ChatMessage          = require('./packets/ChatMessage');
+const Disconnect           = require('./packets/Disconnect');
+const UpdateUserType       = require('./packets/UpdateUserType');
+
+module.exports = {
+  // Utilidades core
+  PacketIDs,
+  BinaryWriter,
+  BinaryReader,
+
+  // Conexiones de alto nivel
+  ServerConnection,
+  ClientConnection,
+
+  // Todos los paquetes
+  packets: {
+    PlayerIdentification,
+    ServerIdentification,
+    Ping,
+    LevelInitialize,
+    LevelDataChunk,
+    LevelFinalize,
+    SpawnPlayer,
+    PlayerTeleport,
+    PlayerUpdate,
+    PlayerMove,
+    PlayerRotate,
+    DespawnPlayer,
+    SetBlock,
+    ChatMessage,
+    Disconnect,
+    UpdateUserType,
+  },
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+"name": "protocol-classicube",
+"version": "1.0.0-beta.1",
+"description": "ClassiCube / Classic Minecraft protocol implementation for Node.js. No dependencies.",
+"main": "index.js",
+"type": "commonjs",
+"keywords": [
+"classicube",
+"minecraft",
+"minecraft-classic",
+"protocol",
+"network",
+"server",
+"client"
+],
+"author": "Rosendo Torre",
+"license": "MIT",
+"engines": {
+"node": ">=14.0.0"
+},
+"files": [
+"index.js",
+"Binary.js",
+"PacketIDs.js",
+"packets/",
+"client/",
+"server/"
+]
+}

package/packets/ChatMessage.js

@@ -0,0 +1,48 @@
+/**
+ * Packet 0x0D - Chat Message (bidirectional)
+ *
+ * Server -> Client:
+ *   Player ID -1 (0xFF) = server message
+ *   Other IDs = player chat
+ *
+ * Client -> Server:
+ *   Player ID is always 0xFF (unused by server but must be sent)
+ *
+ * Layout:
+ *   Byte   - Packet ID (0x0D)
+ *   SByte  - Player ID
+ *   String - Message (64 bytes)
+ *
+ * Total: 66 bytes
+ */
+
+const { BinaryWriter, BinaryReader } = require('../Binary');
+const PacketIDs = require('../PacketIDs');
+
+const SERVER_MESSAGE_ID = -1;
+
+/**
+ * @param {object} opts
+ * @param {number} opts.playerId  - -1 for server, player ID otherwise
+ * @param {string} opts.message
+ */
+function serialize({ playerId = SERVER_MESSAGE_ID, message }) {
+  return new BinaryWriter()
+    .writeByte(PacketIDs.SERVER.CHAT_MESSAGE)
+    .writeSByte(playerId)
+    .writeString(message)
+    .toBuffer();
+}
+
+function deserialize(buf) {
+  const r = new BinaryReader(buf);
+  const packetId = r.readByte();
+  if (packetId !== PacketIDs.SERVER.CHAT_MESSAGE) {
+    throw new Error(`Expected ChatMessage (0x0D), got 0x${packetId.toString(16)}`);
+  }
+  const playerId = r.readSByte();
+  const message = r.readString();
+  return { packetId, playerId, message };
+}
+
+module.exports = { serialize, deserialize, PACKET_SIZE: 66, SERVER_MESSAGE_ID };

package/packets/DespawnPlayer.js

@@ -0,0 +1,38 @@
+/**
+ * Packet 0x0C - Despawn Player (Server -> Client)
+ *
+ * Elimina la entidad de un jugador del mundo del cliente.
+ * Se envia cuando un jugador se desconecta o cambia de mundo.
+ *
+ * Layout:
+ *   Byte  - Packet ID (0x0C)
+ *   SByte - Player ID
+ *
+ * Total: 2 bytes
+ */
+
+const { BinaryWriter, BinaryReader } = require('../Binary');
+const PacketIDs = require('../PacketIDs');
+
+/**
+ * @param {object} opts
+ * @param {number} opts.playerId
+ */
+function serialize({ playerId }) {
+  return new BinaryWriter()
+    .writeByte(PacketIDs.SERVER.DESPAWN_PLAYER)
+    .writeSByte(playerId)
+    .toBuffer();
+}
+
+function deserialize(buf) {
+  const r = new BinaryReader(buf);
+  const packetId = r.readByte();
+  if (packetId !== PacketIDs.SERVER.DESPAWN_PLAYER) {
+    throw new Error(`Expected DespawnPlayer (0x0C), got 0x${packetId.toString(16)}`);
+  }
+  const playerId = r.readSByte();
+  return { packetId, playerId };
+}
+
+module.exports = { serialize, deserialize, PACKET_SIZE: 2 };

package/packets/Disconnect.js

@@ -0,0 +1,36 @@
+/**
+ * Packet 0x0E - Disconnect (Server -> Client)
+ *
+ * Kicks the player with a reason.
+ * Layout:
+ *   Byte   - Packet ID (0x0E)
+ *   String - Disconnect reason (64 bytes)
+ *
+ * Total: 65 bytes
+ */
+
+const { BinaryWriter, BinaryReader } = require('../Binary');
+const PacketIDs = require('../PacketIDs');
+
+/**
+ * @param {object} opts
+ * @param {string} opts.reason
+ */
+function serialize({ reason }) {
+  return new BinaryWriter()
+    .writeByte(PacketIDs.SERVER.DISCONNECT)
+    .writeString(reason)
+    .toBuffer();
+}
+
+function deserialize(buf) {
+  const r = new BinaryReader(buf);
+  const packetId = r.readByte();
+  if (packetId !== PacketIDs.SERVER.DISCONNECT) {
+    throw new Error(`Expected Disconnect (0x0E), got 0x${packetId.toString(16)}`);
+  }
+  const reason = r.readString();
+  return { packetId, reason };
+}
+
+module.exports = { serialize, deserialize, PACKET_SIZE: 65 };