packet-events-js

v1.0.1

Published

18 days ago

A protocol library for Minecraft Java Edition in pure JavaScript

0High
0Medium
0Low

frannndev

minecraft protocol packets java-edition networking

PacketEvents-JS

A robust protocol library for Minecraft Java Edition written entirely in pure JavaScript. Inspired by PacketEvents, designed to facilitate the processing and transmission of Minecraft protocol packets with full online mode support.

Features

Pure JavaScript - No external dependencies, only native Node.js
TCP Connection - Complete TCP client for Minecraft
Packet System - Read/write all protocol data types
Event System - Priority-based events with cancellation and async/await
Compression - Full zlib compression support
Encryption - Complete AES-128-CFB8 encryption support for online mode
Online Mode - Full Mojang/Microsoft authentication support
Offline Mode - Offline player UUID generation (version 3)
BungeeCord Forwarding - Legacy IP forwarding support
Velocity Forwarding - Modern forwarding with HMAC verification
Complete NBT - Named Binary Tag read/write
Chat Components - JSON Text Component with colors, formatting, and events
Multi-version - Support for Minecraft 1.7.2 to 1.21.11 (66 versions)
Packet Recorder - Record, export, import, and replay packet streams
Protocol Analyzer - Deep packet inspection, metrics, and traffic analysis
Middleware System - Plugin-based packet processing pipeline
Connection Manager - AutoReconnect, HealthMonitor, ConnectionPool, CircuitBreaker

Requirements

Node.js 18.0.0 or higher
ES Modules enabled

Installation

npm install packet-events-js

Or clone the repository:

git clone https://github.com/FrannnnDev/PacketEvents-JS.git
cd PacketEvents-JS

Basic Usage

Server List Ping

import { MinecraftClient, ProtocolVersion } from 'packet-events-js';

const client = new MinecraftClient({
    host: 'mc.hypixel.net',
    port: 25565,
    version: ProtocolVersion.V1_21_11
});

const status = await client.ping();
console.log(`Players: ${status.players.online}/${status.players.max}`);
console.log(`Latency: ${status.latency}ms`);

Connect to Server (Offline Mode)

import { 
    MinecraftClient, 
    ProtocolVersion, 
    Logger, 
    LogLevel,
    KeepAliveClientboundPacket, 
    KeepAliveServerboundPacket 
} from 'packet-events-js';

Logger.setGlobalLevel(LogLevel.DEBUG);

const client = new MinecraftClient({
    host: 'localhost',
    port: 25565,
    version: ProtocolVersion.V1_21_11,
    username: 'MyBot',
    offline: true
});

client.onPacket(KeepAliveClientboundPacket, async (event) => {
    const response = new KeepAliveServerboundPacket();
    response.keepAliveId = event.packet.keepAliveId;
    await client.sendPacket(response);
});

await client.login();
console.log(`Connected as ${client.playerName}`);

Encryption API

import { MinecraftEncryption, EncryptedConnection } from 'packet-events-js';

const keyPair = MinecraftEncryption.generateKeyPair();
console.log('Public Key:', keyPair.publicKey);
console.log('Private Key:', keyPair.privateKey);

const verifyToken = MinecraftEncryption.generateVerifyToken();
const sharedSecret = MinecraftEncryption.generateSharedSecret();

const encrypted = MinecraftEncryption.encryptRSA(keyPair.publicKey, sharedSecret);
const decrypted = MinecraftEncryption.decryptRSA(keyPair.privateKey, encrypted);

const aesEncrypted = MinecraftEncryption.encryptAES(sharedSecret, Buffer.from('Hello'));
const aesDecrypted = MinecraftEncryption.decryptAES(sharedSecret, aesEncrypted);

const serverHash = MinecraftEncryption.computeServerIdHash('', sharedSecret, keyPair.publicKey);

Auth Handler

import { AuthHandler, ClientAuthHandler, AuthMode } from 'packet-events-js';

const serverAuth = new AuthHandler({ mode: AuthMode.ONLINE });
serverAuth.initialize();

const publicKey = serverAuth.getPublicKey();
const verifyToken = serverAuth.generateVerifyToken();

const offlineUUID = serverAuth.generateOfflineUUID('PlayerName');

const clientAuth = new ClientAuthHandler({
    accessToken: 'token',
    selectedProfile: { id: 'uuid', name: 'Name' }
});

BungeeCord Forwarding

import { BungeeCordForwarding, UUID } from 'packet-events-js';

const uuid = UUID.randomUUID();
const handshakeAddress = BungeeCordForwarding.create(
    'play.example.com',
    '192.168.1.100',
    uuid,
    [{ name: 'textures', value: '...' }]
);

const result = BungeeCordForwarding.parse(handshakeAddress);
if (result.success) {
    console.log(`Client IP: ${result.clientIP}`);
    console.log(`UUID: ${result.uuid.toString()}`);
}

Velocity Modern Forwarding

import { VelocityForwarding, AuthHandler, AuthMode, UUID } from 'packet-events-js';

const auth = new AuthHandler({ 
    mode: AuthMode.VELOCITY, 
    velocitySecret: 'your-secret-key' 
});

const result = auth.handleVelocityForwarding(forwardingData);
if (result.success) {
    console.log(`Player: ${result.username}`);
    console.log(`UUID: ${result.uuid.toString()}`);
    console.log(`IP: ${result.clientIP}`);
}

const uuid = UUID.randomUUID();
const data = VelocityForwarding.create(
    'your-secret-key',
    '10.0.0.1',
    uuid,
    'PlayerName',
    [{ name: 'textures', value: '...', signature: '...' }]
);

Intercept Packets

import { EventPriority } from 'packet-events-js';

client.packetManager.on('packetSend', (event) => {
    if (event.packet.packetName === 'SetPlayerPosition') {
        console.log(`Moving to: ${event.packet.x}, ${event.packet.y}, ${event.packet.z}`);
        
        if (event.packet.y < 0) {
            event.cancel();
        }
    }
}, { priority: EventPriority.HIGH });

Create Custom Packets

import { 
    Packet, 
    defaultRegistry, 
    ConnectionState, 
    PacketDirection 
} from 'packet-events-js';

class MyCustomPacket extends Packet {
    static get packetId() { return 0x50; }
    static get packetName() { return 'MyPacket'; }

    constructor() {
        super();
        this.myField = 0;
    }

    read(buffer, context) {
        this.myField = buffer.readVarInt();
    }

    write(buffer, context) {
        buffer.writeVarInt(this.myField);
    }
}

defaultRegistry.register({
    packetClass: MyCustomPacket,
    state: ConnectionState.PLAY,
    direction: PacketDirection.CLIENTBOUND,
    packetId: 0x50
});

Advanced Features

Packet Recorder

Record, export, import, and replay complete packet streams:

import { PacketRecorder, PacketReplayer, PacketRecord } from 'packet-events-js';

const recorder = new PacketRecorder({
    includeRaw: true,
    maxRecords: 10000,
    filter: (packet) => true
});

recorder.start();

client.packetManager.on('packetReceive', (event) => {
    recorder.record(event.packet, 'CLIENTBOUND', 'PLAY', event.rawData);
});

const stats = recorder.getStats();
console.log(`Recorded: ${stats.totalPackets} packets, ${stats.totalBytes} bytes`);
console.log(`Duration: ${stats.duration}ms`);
console.log(`Packets by type:`, stats.packetsByType);

const exported = recorder.export();
const json = JSON.stringify(exported, null, 2);

const imported = recorder.import(JSON.parse(json));

const replayer = new PacketReplayer(recorder.records, {
    speed: 1.0,
    loop: false,
    onPacket: (record) => {
        console.log(`Replaying: ${record.packetName}`);
    }
});

await replayer.start();
replayer.pause();
replayer.resume();
replayer.stop();

Protocol Analyzer

Deep protocol analysis with metrics and traffic visualization:

import { ProtocolAnalyzer, ProtocolMetrics, PacketInspector } from 'packet-events-js';

const analyzer = new ProtocolAnalyzer({
    trackHistory: true,
    historySize: 1000,
    alertThresholds: {
        latency: 500,
        packetLoss: 0.1,
        throughputMin: 1000
    }
});

analyzer.on('alert', (alert) => {
    console.log(`Alert: ${alert.type} - ${alert.message}`);
});

analyzer.start();

client.packetManager.on('packetReceive', (event) => {
    analyzer.analyzePacket(event.packet, 'CLIENTBOUND', 'PLAY', event.rawData);
});

analyzer.recordLatency(50);

const report = analyzer.getReport();
console.log(`Packets: ${report.packets.total}`);
console.log(`Bytes: ${report.bytes.total}`);
console.log(`Avg Latency: ${report.latency.average}ms`);

const graph = analyzer.getTrafficGraph();
console.log(graph);

const metrics = new ProtocolMetrics();
metrics.recordLatency(100);
metrics.recordPacketLoss(1, 100);
console.log(`Avg Latency: ${metrics.getAverageLatency()}ms`);
console.log(`Packet Loss: ${metrics.getPacketLoss() * 100}%`);

const inspector = new PacketInspector();

const hexDump = inspector.hexDump(packetBuffer);
console.log(hexDump);

const structure = inspector.analyzeStructure(packet);
console.log(structure);

Middleware System

Plugin-based packet processing pipeline with built-in middleware:

import { 
    MiddlewarePipeline,
    LoggingMiddleware,
    RateLimitMiddleware,
    ValidationMiddleware,
    TransformMiddleware,
    CacheMiddleware,
    MetricsMiddleware
} from 'packet-events-js';

const pipeline = new MiddlewarePipeline();

pipeline.use(new LoggingMiddleware({
    logLevel: 'debug',
    includePayload: true,
    filter: (ctx) => ctx.packet.constructor.packetName !== 'KeepAlive'
}));

pipeline.use(new RateLimitMiddleware({
    maxPackets: 100,
    windowMs: 1000,
    onLimit: (ctx) => console.log('Rate limited!')
}));

pipeline.use(new ValidationMiddleware({
    rules: {
        'ChatMessage': (packet) => packet.message.length <= 256,
        'SetPlayerPosition': (packet) => Math.abs(packet.y) < 320
    },
    onInvalid: (ctx, rule) => console.log(`Invalid: ${rule}`)
}));

pipeline.use(new TransformMiddleware({
    transforms: {
        'ChatMessage': (packet) => {
            packet.message = packet.message.trim();
            return packet;
        }
    }
}));

const metricsMiddleware = new MetricsMiddleware();
pipeline.use(metricsMiddleware);

pipeline.use(async (ctx, next) => {
    console.log(`Before: ${ctx.packet.constructor.packetName}`);
    await next();
    console.log(`After: processing time ${ctx.processingTime}ms`);
});

client.packetManager.on('packetReceive', async (event) => {
    const ctx = await pipeline.process({
        packet: event.packet,
        direction: 'CLIENTBOUND',
        state: 'PLAY'
    });
    
    if (ctx.cancelled) {
        event.cancel();
    }
});

const metrics = metricsMiddleware.getMetrics();
console.log(`Processed: ${metrics.processed} packets`);
console.log(`Blocked: ${metrics.blocked} packets`);

Connection Manager

Advanced connection management with auto-reconnect, health monitoring, and connection pooling:

import { 
    AutoReconnect, 
    ReconnectStrategy,
    HealthMonitor,
    HealthStatus,
    ConnectionPool,
    CircuitBreaker
} from 'packet-events-js';

const reconnect = new AutoReconnect({
    strategy: ReconnectStrategy.EXPONENTIAL,
    baseDelay: 1000,
    maxDelay: 30000,
    maxAttempts: 10,
    jitter: true,
    onReconnect: (attempt) => console.log(`Reconnecting... attempt ${attempt}`),
    onMaxAttempts: () => console.log('Max reconnect attempts reached'),
    onSuccess: () => console.log('Reconnected!')
});

client.on('disconnect', async () => {
    await reconnect.attempt(async () => {
        await client.connect();
        await client.login();
    });
});

const healthMonitor = new HealthMonitor({
    latencyThreshold: 200,
    packetLossThreshold: 0.05,
    checkInterval: 5000
});

healthMonitor.on('statusChange', (status, previousStatus) => {
    console.log(`Health: ${previousStatus} -> ${status}`);
});

healthMonitor.on('alert', (alert) => {
    console.log(`${alert.type}: ${alert.message}`);
});

client.packetManager.on('packetReceive', (event) => {
    if (event.packet.constructor.packetName === 'KeepAliveClientbound') {
        healthMonitor.recordLatency(Date.now() - event.timestamp);
    }
});

const pool = new ConnectionPool({
    minConnections: 2,
    maxConnections: 10,
    strategy: 'least-loaded',
    healthCheck: async (conn) => conn.isConnected,
    healthCheckInterval: 30000
});

await pool.add('lobby', createClient('lobby.server.com'));
await pool.add('game1', createClient('game1.server.com'));
await pool.add('game2', createClient('game2.server.com'));

const { id, connection } = pool.get();
await connection.sendPacket(packet);
pool.release(id);

const breaker = new CircuitBreaker({
    failureThreshold: 5,
    successThreshold: 3,
    timeout: 30000,
    onOpen: () => console.log('Circuit OPEN - requests blocked'),
    onClose: () => console.log('Circuit CLOSED - requests allowed'),
    onHalfOpen: () => console.log('Circuit HALF-OPEN - testing')
});

try {
    await breaker.execute(async () => {
        await client.sendPacket(packet);
    });
} catch (error) {
    if (breaker.isOpen) {
        console.log('Circuit is open, request blocked');
    }
}

Project Structure

PacketEvents-JS/
├── src/
│   ├── index.js
│   ├── auth/
│   │   ├── AuthHandler.js
│   │   └── MojangAPI.js
│   ├── client/
│   │   └── MinecraftClient.js
│   ├── crypto/
│   │   └── Encryption.js
│   ├── events/
│   │   ├── EventEmitter.js
│   │   └── PacketEvent.js
│   ├── manager/
│   │   └── PacketManager.js
│   ├── protocol/
│   │   ├── ConnectionState.js
│   │   ├── PacketDirection.js
│   │   ├── ProtocolVersion.js
│   │   ├── types/
│   │   │   ├── VarInt.js
│   │   │   ├── UUID.js
│   │   │   ├── Position.js
│   │   │   ├── NBT.js
│   │   │   └── TextComponent.js
│   │   └── packets/
│   │       ├── Packet.js
│   │       ├── PacketRegistry.js
│   │       ├── handshake/
│   │       ├── status/
│   │       ├── login/
│   │       └── play/
│   ├── advanced/
│   │   ├── PacketRecorder.js
│   │   ├── ProtocolAnalyzer.js
│   │   ├── MiddlewareSystem.js
│   │   └── ConnectionManager.js
│   └── utils/
│       ├── PacketBuffer.js
│       └── Logger.js
└── examples/
    ├── authentication.js
    ├── basic-client.js
    ├── connection-flows.js
    ├── custom-packets.js
    ├── data-types.js
    ├── encryption.js
    ├── event-system.js
    ├── packet-buffer.js
    ├── packet-interception.js
    ├── packet-types.js
    ├── protocol-versions.js
    └── server-ping.js

Main API

MinecraftClient

const client = new MinecraftClient({
    host: string,
    port: number,
    version: ProtocolVersion,
    username: string,
    offline: boolean,
    accessToken: string,
    selectedProfile: object,
    registry: PacketRegistry
});

await client.connect();
await client.ping();
await client.login();
await client.sendPacket(packet);
await client.disconnect();

client.isConnected;
client.isReady;
client.uuid;
client.playerName;

PacketBuffer

import { PacketBuffer } from 'packet-events-js';

const buffer = PacketBuffer.writer();

buffer.writeBoolean(true);
buffer.writeByte(42);
buffer.writeShort(1000);
buffer.writeInt(100000);
buffer.writeLong(9999999999n);
buffer.writeFloat(3.14);
buffer.writeDouble(3.14159265);
buffer.writeVarInt(12345);
buffer.writeString("Hello Minecraft");
buffer.writeUUID(uuid);
buffer.writePosition(position);
buffer.writeNBT(nbtCompound);

const data = buffer.getBuffer();

const reader = PacketBuffer.reader(data);
const bool = reader.readBoolean();
const num = reader.readVarInt();
const str = reader.readString();

MinecraftEncryption

import { MinecraftEncryption, EncryptedConnection } from 'packet-events-js';

const keyPair = MinecraftEncryption.generateKeyPair();

const verifyToken = MinecraftEncryption.generateVerifyToken();
const sharedSecret = MinecraftEncryption.generateSharedSecret();

MinecraftEncryption.encryptRSA(publicKey, data);
MinecraftEncryption.decryptRSA(privateKey, data);

MinecraftEncryption.encryptAES(secret, data);
MinecraftEncryption.decryptAES(secret, data);

MinecraftEncryption.computeServerIdHash(serverId, sharedSecret, publicKey);

const conn = new EncryptedConnection(sharedSecret);
conn.enable();
const encrypted = conn.encrypt(data);
const decrypted = conn.decrypt(data);

AuthHandler

import { AuthHandler, ClientAuthHandler, AuthMode, BungeeCordForwarding, VelocityForwarding } from 'packet-events-js';

AuthMode.ONLINE;
AuthMode.OFFLINE;
AuthMode.BUNGEECORD;
AuthMode.VELOCITY;

const handler = new AuthHandler({ mode: AuthMode.ONLINE });
handler.initialize();
handler.getPublicKey();
handler.generateVerifyToken();
handler.generateOfflineUUID(username);

const bungeAuth = new AuthHandler({ mode: AuthMode.BUNGEECORD });
const result = bungeAuth.handleBungeeCordForwarding(serverAddress);

const velocityAuth = new AuthHandler({ 
    mode: AuthMode.VELOCITY, 
    velocitySecret: 'your-secret' 
});
const result2 = velocityAuth.handleVelocityForwarding(loginPluginData);

EventEmitter

import { EventPriority } from 'packet-events-js';

EventPriority.LOWEST;
EventPriority.LOW;
EventPriority.NORMAL;
EventPriority.HIGH;
EventPriority.HIGHEST;
EventPriority.MONITOR;

emitter.on('event', callback, { priority: EventPriority.HIGH });

emitter.on('packet', (event) => {
    event.cancel();
});

await emitter.emitAsync('event', data);

TextComponent

import { TextComponent, ChatColor } from 'packet-events-js';

const message = TextComponent.text('Hello!')
    .color(ChatColor.GREEN)
    .bold()
    .append(
        TextComponent.text(' World')
            .color(ChatColor.YELLOW)
            .italic()
    )
    .clickEvent('run_command', '/help')
    .showText(TextComponent.text('Click for help'));

const json = message.toString();

Supported Versions

66 versions supported from 1.7.2 to 1.21.11:

| Range | Versions | |-------|----------| | 1.21.x | 1.21.11, 1.21.10, 1.21.9, 1.21.8, 1.21.7, 1.21.6, 1.21.5, 1.21.4, 1.21.3, 1.21.2, 1.21.1, 1.21 | | 1.20.x | 1.20.6, 1.20.5, 1.20.4, 1.20.3, 1.20.2, 1.20.1, 1.20 | | 1.19.x | 1.19.4, 1.19.3, 1.19.2, 1.19.1, 1.19 | | 1.18.x | 1.18.2, 1.18.1, 1.18 | | 1.17.x | 1.17.1, 1.17 | | 1.16.x | 1.16.5, 1.16.4, 1.16.3, 1.16.2, 1.16.1, 1.16 | | 1.15.x | 1.15.2, 1.15.1, 1.15 | | 1.14.x | 1.14.4, 1.14.3, 1.14.2, 1.14.1, 1.14 | | 1.13.x | 1.13.2, 1.13.1, 1.13 | | 1.12.x | 1.12.2, 1.12.1, 1.12 | | 1.11.x | 1.11.2, 1.11.1, 1.11 | | 1.10.x | 1.10.2, 1.10.1, 1.10 | | 1.9.x | 1.9.4, 1.9.3, 1.9.2, 1.9.1, 1.9 | | 1.8.x | 1.8.9, 1.8.8, 1.8.7, 1.8.6, 1.8.5, 1.8.4, 1.8.3, 1.8.2, 1.8.1, 1.8 | | 1.7.x | 1.7.10, 1.7.9, 1.7.6, 1.7.5, 1.7.4, 1.7.2 |

Examples

See the examples folder for complete usage examples:

basic-client.js - Basic client connection
server-ping.js - Server list ping
packet-types.js - All packet types demonstration
encryption.js - Encryption usage
authentication.js - Authentication modes
event-system.js - Event system usage
packet-buffer.js - PacketBuffer operations
data-types.js - Protocol data types
protocol-versions.js - Protocol version utilities
connection-flows.js - Connection flow examples
custom-packets.js - Custom packet creation
packet-interception.js - Packet interception

References

This project is inspired by:

PacketEvents - Original Java library
wiki.vg Protocol - Protocol documentation
MCProtocolLib - Reference implementation

License

MIT License