はじめに

bedrock-protocol は、Minecraft Bedrock Edition(旧 Pocket Edition)のプロトコルを Node.js から扱うためのライブラリです。認証と暗号化を内蔵しており、ボット(クライアント)・独自サーバー・プロキシ(Relay)をすべて JavaScript で実装できます。

非公式ドキュメントについて

このサイトは PrismarineJS/bedrock-protocol(MIT License)の内容をもとにした非公式の日本語ドキュメントです。記載内容はリポジトリの docs/API.md・README.md・index.d.ts を基にしています。

特徴

• 幅広いバージョン対応: Bedrock 1.16.201 〜 1.26.x(対応バージョンは順次追加されます)
• パケットを JavaScript オブジェクトとしてパース / シリアライズ
• keep-alive への自動応答
• クライアント: Microsoft / Xbox Live 認証、暗号化、サーバーの ping
• サーバー: 接続クライアントの Xbox Live 認証検証、ping 応答
• Relay(中間者プロキシ) の内蔵
• 他の PrismarineJS プロジェクト(ワールドプロバイダ等)との連携が容易

インストール

Node.js(LTS 版を推奨)が必要です。

npm install bedrock-protocol

既にインストール済みの環境で更新する場合は、依存関係ごと更新されるよう npm update を実行します。

RakNet バックエンドについて

デフォルトでは C++ 実装の raknet-native を使用します。ビルドツールが無い環境では、純 JS 実装の 'jsp-raknet'(または Rust 製の 'raknet-node')を raknetBackend オプションで指定できます。

最小のサンプル

クライアント

オフラインモードでローカルサーバーに接続し、チャットを受信してオウム返しする例です。

const bedrock = require('bedrock-protocol')

const client = bedrock.createClient({
  host: 'localhost', // 省略可
  port: 19132,       // 省略可(デフォルト 19132)
  username: 'Notch', // オフラインモード時の表示名
  offline: true      // true で Xbox Live 認証をスキップ
})

client.on('text', packet => {
  if (packet.source_name !== client.username) {
    client.queue('text', {
      type: 'chat',
      needs_translation: false,
      source_name: client.username,
      xuid: '',
      platform_chat_id: '',
      filtered_message: '',
      message: `${packet.source_name} said: ${packet.message}`
    })
  }
})

サーバー

接続してきたクライアントにカラフルなキックメッセージを送る例です。

const bedrock = require('bedrock-protocol')

const server = bedrock.createServer({
  host: '0.0.0.0',     // 全 IPv4 アドレスで待ち受け
  port: 19132,
  version: '1.21.50',  // 省略時は最新
  motd: { motd: 'Funtime Server', levelName: 'Wonderland' }
})

server.on('connect', client => {
  client.on('join', () => {
    client.disconnect('こんにちは!') // 接続直後にキック
  })
})

ping

const { ping } = require('bedrock-protocol')

ping({ host: 'play.cubecraft.net', port: 19132 }).then(console.log)
// → MOTD・オンライン人数・ゲームモードなどの ServerAdvertisement

基本の考え方

パケット名とイベント

• 受信した各パケットは パケット名を小文字化し packet_ プレフィックスを除いたもの がイベントとして発火します(例: packet_text → client.on('text', ...))。
• 送信も同じ名前を使います。client.queue('text', {...}) のように呼び出します。
• パケット名・フィールド名は 大文字小文字が区別 されます。必須フィールドはすべて埋める必要があります。
• 各パケットのフィールド定義はプロトコルドキュメントを参照してください。

write と queue

メソッド	動作
write(name, params)	パケットを 即時に 送信する
queue(name, params)	パケットをキューに入れ、次の送信バッチ(デフォルト 20ms 間隔)でまとめて送る

通常はパフォーマンスとブロッキング低減のため queue() を推奨します。

デバッグ

DEBUG 環境変数でプロトコルの詳細ログを有効化できます。スクリプトの先頭に次を書いておくのが手軽です。

process.env.DEBUG = 'minecraft-protocol'

接続ログやエラーの詳細が出力され、トラブルシューティングに役立ちます。

次のステップ

• クライアントガイド — 接続オプションとイベントの流れ
• サーバーガイド — 待ち受けとプレイヤー処理
• Relay ガイド — パケットの中間観測・改変