クライアント

createClient(options) は Client インスタンスを返し、サーバーへの接続を開始します。

最小のサンプル

const bedrock = require('bedrock-protocol')

const client = bedrock.createClient({
  host: '127.0.0.1',
  port: 19132,
  username: 'Notch',
  offline: true // Xbox Live 認証をスキップ
})

client.on('join', () => console.log('参加しました'))
client.on('spawn', () => console.log('ワールドに出現しました'))

// チャット(text パケット)を受信
client.on('text', packet => {
  console.log(`${packet.source_name}: ${packet.message}`)
})

オンラインモード(デフォルト)では、初回接続時に Microsoft アカウントでのサインインが求められます。onMsaCode を指定するとデバイスコード認証の URL / コードを受け取れます。

const client = bedrock.createClient({
  username: 'Notch',
  onMsaCode: data => {
    console.log(`ブラウザで ${data.verification_uri} を開き、コード ${data.user_code} を入力してください`)
  }
})

接続オプション

主要なオプションの一覧です。完全な一覧は クライアントオプション を参照してください。

オプション	必須	説明
host	条件付き	接続先ホスト。realms 指定時は不要
port	省略可	接続先ポート。デフォルト 19132
version	省略可	接続時に装うバージョン。未指定ならサーバーに自動一致
offline	省略可	true で Microsoft/Xbox 認証を無効化。デフォルト false
username	必須	接続時のプロファイル名。オフラインモードでは表示名になる
connectTimeout	省略可	接続試行のタイムアウト(ms)。デフォルト 9000
onMsaCode	省略可	デバイスコード認証開始時に呼ばれるコールバック
profilesFolder	省略可	認証トークンのキャッシュ先。デフォルトは .minecraft
skipPing	省略可	サーバーへの事前 ping(バージョン確認)をスキップ
followPort	省略可	ping 応答で告知されたポートに接続先を合わせる(realms 未指定時デフォルト true)
autoInitPlayer	省略可	spawn 後に SetPlayerInitialized を自動送信するか。デフォルト true
conLog	省略可	接続ログの出力先。null で無効化
compressionLevel	省略可	zlib 圧縮レベル。デフォルト 7
batchingInterval	省略可	送信キューのフラッシュ間隔(ms)。デフォルト 20
realms	省略可	Realm への接続に使用

イベントの発火順序

クライアントはライフサイクルに沿って次の順でイベントを発火します。

connect → (login) → join → spawn

イベント	発火タイミング
connect_allowed	サーバーへ ping し、バージョン情報を取得した後
status	ログインシーケンスの状態が変化したとき
session	認証と接続が完了したとき
join	認証が完了し、ゲームパケットの受信準備ができたとき
spawn	チャンク受信などが済み、ワールドに出現したとき
kick	サーバーからキックされたとき
close	接続が閉じたとき
error	回復可能な例外。捕捉しない場合はスローされる
heartbeat	tick_sync(keepalive)が双方向で成功した後
packet	すべての 受信パケットに対して発火

'packet' イベントで全部を見る

client.on('packet', ({ name, params }) => {
  console.log('受信:', name, params)
})

パケットダンプやプロトコル解析に便利です。

チャットの送信

text パケットでチャットを送れます。必須フィールドはすべて指定します。

client.queue('text', {
  type: 'chat',
  needs_translation: false,
  source_name: client.username,
  xuid: '',
  platform_chat_id: '',
  filtered_message: '',
  message: 'こんにちは!'
})

プレイヤーの参加を検知して挨拶する例:

client.on('add_player', packet => {
  client.queue('text', {
    type: 'chat',
    needs_translation: false,
    source_name: client.username,
    xuid: '',
    platform_chat_id: '',
    filtered_message: '',
    message: `ようこそ、${packet.username}!`
  })
})

コマンドの実行

command_request を送り、サーバーからの command_output をリクエスト時に生成した UUID で突き合わせて受け取ります。

const { randomUUID } = require('crypto')

const uuid = randomUUID()
client.on('command_output', packet => {
  if (packet.origin.uuid === uuid) console.log(packet.output)
})

client.queue('command_request', {
  command: '/list',
  origin: {
    type: 'player',
    uuid,
    request_id: '',
    player_entity_id: 0n // 1.26.x 以降では必須(下記参照)
  },
  internal: false,
  version: 'latest' // 1.26.x では文字列 'latest'(下記参照)
})

バージョン依存の注意点(1.26.x)

次の 2 フィールドはバージョン依存で、どちらかを誤ると 1.26.x では接続切断レベルの packet_violation_warning が発生します。警告文は実際の原因にかかわらず常に Command exceeds maximum size of 512 characters. という定型文なので、文字数制限の問題と誤解しないでください。

• version: 1.21.x 以下は varint(数値)、1.21.130 以降は文字列。1.26.x では 'latest' を渡す('52' のような数値風文字列は拒否されます)
• origin.player_entity_id: 1.21.x 以下では条件付き(省略可)、1.21.130 以降は無条件の li64(必須)。省略すると送信前のシリアライズ段階で例外が発生します

また、/say など一部のコマンドは 送信者自身には command_output が返らない ため、出力を待つ実装にしないでください。

切断

client.close()     // 接続を閉じてサーバーから退出
client.disconnect() // disconnect パケットを送ってから切断