cubyz-node-client 0.1.0

package/README.md

@@ -0,0 +1,211 @@
+# Cubyz Node.js Client Library
+
+`cubyz-node-client` is a small TypeScript library that speaks the Cubyz networking protocol from Node.js. It exposes a high-level `CubyzConnection` class for establishing a UDP session with a running Cubyz server, handling the handshake, managing sequenced channels, and publishing client state packets.
+
+## Features
+
+- Typed wrapper around the Cubyz UDP protocol (init negotiation, confirmations, keep-alives)
+- Full handshake implementation and spawn data parsing
+- Helpers for sending chat messages, teleport updates, and rotation changes
+- Lightweight ZON parser for decoding server payloads without bundling Zig tooling
+- Designed for embedding in other tooling, bots, or integration tests
+- Configurable log level with typed disconnect events when the server closes the session
+
+## Requirements
+
+- Node.js 18 or newer (modern UDP & BigInt APIs)
+- Access to a Cubyz server (default UDP port `47649`)
+
+## Installation
+
+```bash
+npm install cubyz-node-client
+```
+
+## Building from source
+
+```bash
+npm install
+npm run build
+```
+
+Compilation outputs ESM modules alongside type declarations in `dist/`.
+
+## Quick start example
+
+You can run the included sandbox example to see the connection flow end-to-end:
+
+```bash
+# Optional overrides for host/port/player name
+export CUBYZ_HOST=127.0.0.1
+export CUBYZ_PORT=47649
+export CUBYZ_NAME=ExampleBot
+export CUBYZ_LOG_LEVEL=debug
+
+npm run sandbox
+```
+
+The example connects to the configured server, logs chat/player events, emits a greeting, and then shuts down gracefully after a few seconds.
+
+## Programmatic usage
+
+```ts
+import { CubyzConnection, DEFAULT_PORT } from "cubyz-node-client";
+
+const connection = new CubyzConnection({
+  host: "127.0.0.1",
+  port: DEFAULT_PORT,
+  name: "ToolingBot",
+  logger: console,
+  logLevel: "warn",
+});
+
+connection.on("connected", () => {
+  console.log("Channel handshake ready");
+});
+
+connection.on("handshakeComplete", (spawnData) => {
+  console.log("Server spawn data received:", spawnData);
+  connection.sendChat("Hello world from tooling!");
+});
+
+connection.on("players", (players) => {
+  console.log("Known players:", players);
+});
+
+connection.on("chat", (message) => {
+  console.log("[chat]", message);
+});
+
+connection.on("protocol", (event) => {
+  console.log("Protocol event:", event.protocolId);
+});
+
+connection.on("disconnect", (details) => {
+  console.log("Server closed connection", details.reason);
+});
+
+await connection.start();
+
+// Later: connection.close();
+```
+
+## API Reference
+
+### CubyzConnection
+
+#### Constructor Options
+
+```ts
+interface CubyzConnectionOptions {
+  host: string; // Server hostname or IP
+  port: number; // Server UDP port (default: 47649)
+  name: string; // Player/bot name
+  version?: string; // Protocol version (default: "0.1.0-dev")
+  logger?: CubyzConnectionLogger; // Custom logger (default: no-op)
+  logLevel?: LogLevel; // "debug" | "info" | "warn" | "error" | "silent"
+}
+```
+
+#### Events
+
+- **`connected`**: Emitted when the channel handshake with the server completes
+- **`handshakeComplete(spawnData: string)`**: Emitted when the server sends spawn/world data (ZON format)
+- **`chat(message: string)`**: Emitted when a chat message is received from the server
+- **`players(names: string[])`**: Emitted when the player list updates
+- **`protocol(event: ProtocolEvent)`**: Emitted for other protocol messages (entity updates, etc.)
+- **`disconnect(event: DisconnectEvent)`**: Emitted when the connection closes (reason: "server" | "timeout")
+
+#### Methods
+
+- **`async start()`**: Bind the UDP socket and initiate the connection
+- **`close(options?: CloseOptions)`**: Close the connection gracefully (optionally skip server notification)
+- **`sendChat(message: string)`**: Send a chat message to the server
+- **`teleport(x: number, y: number, z: number)`**: Update player position
+- **`setRotation(yawDeg: number, pitchDeg?: number, rollDeg?: number)`**: Update player rotation (degrees)
+- **`getPlayerNames(): string[]`**: Get the current list of known player names
+- **`publishPlayerState(force?: boolean)`**: Manually send a player state update
+
+## Key exports
+
+### Core Classes
+
+- **`CubyzConnection`**: High-level client with typed events for managing server connections
+- **`SendChannel`**: Low-level sequenced packet sender
+- **`ReceiveChannel`**: Low-level sequenced packet receiver
+
+### ZON Parser
+
+- **`parseZon(buffer: Buffer): ZonValue`**: Standalone ZON parser for inspecting server messages
+- **`ZonValue`**: TypeScript type representing parsed ZON data structures
+
+### Binary Utilities
+
+- **`encodeVarInt(value: number): Buffer`**: Encode a variable-length integer
+- **`decodeVarInt(buffer: Buffer, offset?: number): { value: number; bytesRead: number }`**: Decode a variable-length integer
+- **`seqLessThan(a: number, b: number): boolean`**: Compare sequence numbers with wraparound handling
+- **`addSeq(seq: number, delta: number): number`**: Add to a sequence number with wraparound
+
+### Constants
+
+- **`DEFAULT_PORT`**: Default Cubyz server port (47649)
+- **`DEFAULT_VERSION`**: Default protocol version
+- **`CHANNEL`**: Channel IDs (LOSSY, FAST, SLOW, etc.)
+- **`PROTOCOL`**: Protocol IDs (HANDSHAKE, CHAT, ENTITY, etc.)
+
+### TypeScript Types
+
+```ts
+export interface Vector3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface PlayerState {
+  position: Vector3;
+  velocity: Vector3;
+  rotation: Vector3;
+}
+
+export interface ProtocolEvent {
+  channelId: number;
+  protocolId: number;
+  payload: Buffer;
+}
+
+export interface DisconnectEvent {
+  reason: "server" | "timeout";
+}
+
+export interface CloseOptions {
+  notify?: boolean; // Send disconnect packet to server (default: true)
+}
+```
+
+## Development
+
+- **`npm run build`**: Compile TypeScript sources to `dist/`
+- **`npm run clean`**: Remove the `dist/` output directory
+- **`npm run sandbox`**: Build and run the sandbox example
+- **`npm run check`**: Run Biome linter/formatter checks
+- **`npm run check:write`**: Auto-fix linting and formatting issues
+
+## Project Structure
+
+```
+src/
+  index.ts          - Main exports
+  connection.ts     - CubyzConnection class
+  send_channel.ts   - Sequenced packet sender
+  receive_channel.ts - Sequenced packet receiver
+  binary.ts         - Binary encoding/decoding utilities
+  zon.ts           - ZON format parser
+  constants.ts      - Protocol constants
+sandbox/
+  main.ts          - Example usage
+```
+
+## Acknowledgments
+
+This project was created with the assistance of Large Language Models (GPT-5 Codex and Claude Sonnet 4.5).

package/dist/binary.d.ts

@@ -0,0 +1,11 @@
+import { Buffer } from "node:buffer";
+export declare function encodeVarInt(value: number): Buffer;
+export declare function decodeVarInt(buffer: Buffer, offset?: number): {
+    value: number;
+    consumed: number;
+};
+export declare function toInt32(value: number): number;
+export declare function addSeq(base: number, delta: number): number;
+export declare function seqLessThan(a: number, b: number): boolean;
+export declare function writeInt32BE(buffer: Buffer, offset: number, value: number): void;
+export declare function readInt32BE(buffer: Buffer, offset: number): number;

package/dist/binary.js

@@ -0,0 +1,51 @@
+import { Buffer } from "node:buffer";
+export function encodeVarInt(value) {
+    if (value < 0) {
+        throw new RangeError("VarInt cannot encode negative values");
+    }
+    const bytes = [];
+    let remaining = value >>> 0;
+    do {
+        let byte = remaining & 0x7f;
+        remaining >>>= 7;
+        if (remaining !== 0) {
+            byte |= 0x80;
+        }
+        bytes.push(byte);
+    } while (remaining !== 0);
+    return Buffer.from(bytes);
+}
+export function decodeVarInt(buffer, offset = 0) {
+    let value = 0;
+    let consumed = 0;
+    let shift = 0;
+    while (offset + consumed < buffer.length) {
+        const byte = buffer[offset + consumed];
+        value |= (byte & 0x7f) << shift;
+        consumed += 1;
+        if ((byte & 0x80) === 0) {
+            return { value: value >>> 0, consumed };
+        }
+        shift += 7;
+        if (shift >= 35) {
+            throw new Error("VarInt decoding failed: value too large");
+        }
+    }
+    throw new Error("VarInt decoding failed: reached end of buffer");
+}
+export function toInt32(value) {
+    return (value << 0) | 0;
+}
+export function addSeq(base, delta) {
+    return toInt32((base + delta) | 0);
+}
+export function seqLessThan(a, b) {
+    return toInt32(a - b) < 0;
+}
+export function writeInt32BE(buffer, offset, value) {
+    buffer.writeInt32BE(toInt32(value), offset);
+}
+export function readInt32BE(buffer, offset) {
+    return buffer.readInt32BE(offset);
+}
+//# sourceMappingURL=binary.js.map

package/dist/binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.js","sourceRoot":"","sources":["../src/binary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,MAAM,IAAI,UAAU,CAAC,sCAAsC,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,SAAS,GAAG,KAAK,KAAK,CAAC,CAAC;IAC5B,GAAG,CAAC;QACF,IAAI,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC;QAC5B,SAAS,MAAM,CAAC,CAAC;QACjB,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;YACpB,IAAI,IAAI,IAAI,CAAC;QACf,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC,QAAQ,SAAS,KAAK,CAAC,EAAE;IAC1B,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,MAAc,EACd,MAAM,GAAG,CAAC;IAEV,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,CAAC;QAChC,QAAQ,IAAI,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;QAC1C,CAAC;QACD,KAAK,IAAI,CAAC,CAAC;QACX,IAAI,KAAK,IAAI,EAAE,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,KAAa;IAChD,OAAO,OAAO,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,OAAO,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,MAAc,EACd,MAAc,EACd,KAAa;IAEb,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,MAAc;IACxD,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC"}

package/dist/connection.d.ts

@@ -0,0 +1,117 @@
+import { Buffer } from "node:buffer";
+import { EventEmitter } from "node:events";
+declare const LOG_LEVEL_ORDER: {
+    readonly debug: 0;
+    readonly info: 1;
+    readonly warn: 2;
+    readonly error: 3;
+    readonly silent: 4;
+};
+export type LogLevel = keyof typeof LOG_LEVEL_ORDER;
+export interface Vector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface PlayerState {
+    position: Vector3;
+    velocity: Vector3;
+    rotation: Vector3;
+}
+export interface ProtocolEvent {
+    channelId: number;
+    protocolId: number;
+    payload: Buffer;
+}
+export interface CubyzConnectionLogger {
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+    debug?: (...args: unknown[]) => void;
+}
+export interface CubyzConnectionOptions {
+    host: string;
+    port: number;
+    name: string;
+    version?: string;
+    logger?: CubyzConnectionLogger;
+    logLevel?: LogLevel;
+}
+export interface CloseOptions {
+    notify?: boolean;
+}
+type CubyzConnectionEvents = {
+    connected: [];
+    handshakeComplete: [string];
+    chat: [string];
+    players: [string[]];
+    protocol: [ProtocolEvent];
+    disconnect: [DisconnectEvent];
+};
+export interface DisconnectEvent {
+    reason: "server" | "timeout";
+}
+export declare class CubyzConnection extends EventEmitter {
+    readonly host: string;
+    readonly port: number;
+    readonly name: string;
+    readonly version: string;
+    private readonly baseLogger;
+    private readonly logLevel;
+    private readonly socket;
+    private readonly connectionId;
+    private remoteConnectionId;
+    private state;
+    private handshakeComplete;
+    private readonly sendChannels;
+    private readonly receiveChannels;
+    private readonly pendingConfirmations;
+    private readonly playerMap;
+    private lastKeepAliveSent;
+    private lastInbound;
+    private lastInitSent;
+    private tickTimer;
+    private playerStateTimer;
+    private readonly playerState;
+    private lastPlayerStateSent;
+    private disconnectSent;
+    private disconnectEmitted;
+    private initSent;
+    private handshakeQueued;
+    constructor({ host, port, name, version, logger, logLevel, }: CubyzConnectionOptions);
+    private log;
+    private emitDisconnect;
+    on<K extends keyof CubyzConnectionEvents>(event: K, listener: (...args: CubyzConnectionEvents[K]) => void): this;
+    once<K extends keyof CubyzConnectionEvents>(event: K, listener: (...args: CubyzConnectionEvents[K]) => void): this;
+    off<K extends keyof CubyzConnectionEvents>(event: K, listener: (...args: CubyzConnectionEvents[K]) => void): this;
+    emit<K extends keyof CubyzConnectionEvents>(event: K, ...args: CubyzConnectionEvents[K]): boolean;
+    start(): Promise<void>;
+    close(options?: CloseOptions): void;
+    private tick;
+    private flushSendQueues;
+    private queueConfirmation;
+    private flushConfirmations;
+    private sendKeepAlive;
+    private sendInit;
+    private sendInitAck;
+    private ensureReceiveChannels;
+    private handlePacket;
+    private handleInitPacket;
+    private queueHandshake;
+    private handleSequencedPacket;
+    private handleConfirmation;
+    private handleProtocol;
+    private handleHandshake;
+    private handleEntityUpdate;
+    private emitPlayers;
+    getPlayerNames(): string[];
+    sendChat(message: string): void;
+    teleport(x: number, y: number, z: number): void;
+    setRotation(yawDeg: number, pitchDeg?: number, rollDeg?: number): void;
+    setPosition(x: number, y: number, z: number): void;
+    publishPlayerState(force?: boolean): void;
+    private encodePlayerStatePacket;
+    private startPlayerStateLoop;
+    private sendDisconnectPacket;
+}
+export {};