minecraft-logs

name	minecraft-logs
description	Capture Minecraft Bedrock network packets using a proxy relay. Start packet capture, save raw binary dumps and processed JSON logs. Use when debugging Bedrock protocol, analyzing bot behavior, or recording gameplay packets.
allowed-tools	Read, Glob, Grep, Bash

Minecraft Bedrock Packet Capture

Capture Bedrock Edition network packets using a proxy relay between the game client and server.

Quick Start

# Start packet capture proxy with defaults
npm run start --workspace=minecraft-logs-recorder

# Or directly
node packages/minecraft-logs-recorder/src/dump-packets.ts

Connect Minecraft Bedrock to localhost:19150 - packets will be relayed to localhost:19198 and logged.

CLI Options

node packages/minecraft-logs-recorder/src/dump-packets.ts [OPTIONS]

OPTIONS:
  --listen-host <host>   Proxy listen host (default: 0.0.0.0)
  -l, --listen-port <port>   Proxy listen port (default: 19150)
  -d, --dest-host <host>     Destination server host (default: 127.0.0.1)
  -p, --dest-port <port>     Destination server port (default: 19198)
  -v, --version <ver>        Protocol version (default: 1.21.130)
  --offline                  Offline auth (default)
  --online                   Online authentication
  --profiles <path>          Profiles folder (default: ./profiles)
  -o, --log-dir <path>       Output directory (default: ./logs)
  -h, --help                 Show help

Output Files

Both files share the same base name:

File	Format	Purpose
{version}-{timestamp}.bin	Binary	Raw packets for replay
{version}-{timestamp}.jsonl	JSON Lines	Processed packet data

Filename format: {version}-{yyyy-mm-dd-{seconds}} (e.g., 1.21.130-2025-01-02-43200)

Common Scenarios

Capture from BDS Server

node packages/minecraft-logs-recorder/src/dump-packets.ts \
  -d 127.0.0.1 -p 19132 -o ./captures

Capture with Online Auth

node packages/minecraft-logs-recorder/src/dump-packets.ts \
  --online --profiles ~/.minecraft-profiles

Custom Listen Port

node packages/minecraft-logs-recorder/src/dump-packets.ts -l 19160

JSONL Log Format

{"t":1234,"tick":100,"d":"C","p":"player_action","action":"start_break","pos":[50,64,100]}
{"t":1235,"tick":100,"d":"S","p":"inventory_slot","window":"inventory","slot":0,"item":"diamond_pickaxe"}

Fields:

• t - Milliseconds since capture start
• tick - Game tick
• d - Direction: C=client→server, S=server→client
• p - Packet name

Analyzing Captured Logs

Using Custom Analyzer

To analyze with a specific tool, provide the log file path:

# Example: custom analyzer script
python your-analyzer.py logs/1.21.130-2025-01-02-43200.jsonl

# Example: jq for JSON processing
cat logs/*.jsonl | jq -c 'select(.p=="item_stack_response")'

Quick Analysis Commands

# List captured logs
ls -la logs/*.jsonl logs/*.bin

# Count packets by type
grep -o '"p":"[^"]*"' logs/*.jsonl | sort | uniq -c | sort -rn

# Find specific packets
grep '"p":"inventory_transaction"' logs/*.jsonl

# Show timeline (first 20 packets)
head -20 logs/*.jsonl

Binary Replay

Use .bin files to replay captured sessions:

import { createReplayClient } from 'minecraft-logs-recorder/replay';

const client = createReplayClient('logs/1.21.130-2025-01-02-43200.bin');
client.on('inventory_slot', (params) => {
  console.log('Inventory slot update:', params);
});

Re-analyzing Binary Files

To re-run an analyzer on an existing .bin file (e.g., after updating analyzer logic):

node --experimental-strip-types -e "
import { PacketDumpReader } from 'minecraft-bedrock-test-server';
import { CraftingAnalyzer } from 'minecraft-logs-analyzers';

const inputFile = 'path/to/capture.bin';
const outputBase = inputFile.replace('.bin', '-reanalyzed');

const reader = new PacketDumpReader(inputFile);
const analyzer = new CraftingAnalyzer(outputBase);

// Direction swap: bin files have S/C swapped due to legacy bug
const fixDirection = (d) => d === 'S' ? 'C' : 'S';

let count = 0;
while (reader.canRead()) {
  const packet = reader.read();
  if (!packet) break;
  analyzer.log(fixDirection(packet.type), packet.data.name, packet.data.params);
  count++;
}

analyzer.close();
reader.close();
console.log('Processed', count, 'packets');
console.log('Output:', outputBase + '-crafting.jsonl');
"

Replace CraftingAnalyzer with any analyzer class (InventoryAnalyzer, etc.). The output filename suffix matches the analyzer's config.name property.

Available Analyzers

Analyzer	Description	Logged Packets
InventoryAnalyzer	Inventory operations	inventory_slot, inventory_content, inventory_transaction, item_stack_request/response, mob_equipment, player_action, animate

Using Analyzers Directly

import { InventoryAnalyzer } from 'minecraft-logs-analyzers';

const analyzer = new InventoryAnalyzer('logs/my-capture');
analyzer.attachToBot(client);
// ... on disconnect:
analyzer.close();

Package Structure

Package	Purpose
minecraft-logs-recorder	Packet capture proxy + replay
minecraft-logs-analyzers	Analyzer classes + types

Reading Binary Log Files

Use npm run read-log to read and filter .bin packet log files:

npm run read-log -- <file.bin> [options]

Options:
  --tick <n>              Show packets at specific tick
  --tick-start <n>        Start tick (inclusive)
  --tick-end <n>          End tick (inclusive)
  --names                 Output packet names only (default)
  --full                  Output full packet data (JSON)
  --include <pattern>     Include only matching packets (glob, comma-separated)
  --exclude <pattern>     Exclude matching packets (glob, comma-separated)
  --direction <C|S>       Filter by direction (C=client->server, S=server->client)
  -h, --help              Show help

Examples

# List all packet names at tick 100
npm run read-log -- logs/capture.bin --tick 100

# Show full packets from tick 50-100, excluding player_auth_input
npm run read-log -- logs/capture.bin --tick-start 50 --tick-end 100 --full --exclude player_auth_input

# Show only inventory-related packets
npm run read-log -- logs/capture.bin --include 'inventory_*,item_stack_*'

# Show clientbound packets only
npm run read-log -- logs/capture.bin --direction C

Output Formats

Names only (default):

tick:100 S player_auth_input
tick:100 S inventory_slot
tick:100 C mob_equipment

Full JSON (--full):

{"tick":100,"d":"S","p":"inventory_slot","params":{...}}

Related Skills

• Use /create-analyzer to create new domain-specific analyzers