Agent skill

minecraft-logs

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.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/minecraft-logs

SKILL.md

Minecraft Bedrock Packet Capture

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

Quick Start

bash
# 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

bash
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

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

Capture with Online Auth

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

Custom Listen Port

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

JSONL Log Format

json
{"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:

bash
# 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

bash
# 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:

typescript
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):

bash
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

typescript
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:

bash
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

bash
# 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):

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

Related Skills

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

Didn't find tool you were looking for?

Be as detailed as possible for better results