低レベル API とカスタマイズ
docs/API.md には載っていない、ソースコード(src/)から読み取れる高度な機能をまとめます。
手動の接続ライフサイクル(delayedInit)
通常 createClient() は内部で接続まで進めますが、Client クラスを直接使うと各段階を手動制御できます。
const { Client } = require('bedrock-protocol')
// delayedInit: true でコンストラクタ内の自動初期化を止める
const client = new Client({
host: '127.0.0.1',
port: 19132,
username: 'Notch',
offline: true,
delayedInit: true
})
// init() を明示的に呼ぶと serializer 等が準備され connect_allowed が発火する
client.init()
client.once('connect_allowed', () => {
// ping やバージョン確認など、接続前処理をここで行える
client.connect()
})connect_allowed は「サーバーへ ping してバージョン情報を得た後」に発火するため、動的ポート解決や事前チェックを挟みたい場合に有用です。
createClient の戻り値
createClient() も同じ Client インスタンスを返すので、client.connect() のようなメソッドはそのまま呼べます。
接続前の ping
Client は個別の ping メソッドを持ちます(RakNet レベルの unconnected ping)。
await client.ping() // 接続可能性チェック。失敗時は conLog に案内が出て例外スローステートマシン(ClientStatus)
Connection.status は次の数値 enum です。'status' イベントで変化を購読できます。
| 値 | 名前 | 意味 |
|---|---|---|
| 0 | Disconnected | 未接続 / 切断済み |
| 1 | Connecting | RakNet 接続中 |
| 2 | Authenticating | ハンドシェイク・ログイン中 |
| 3 | Initializing | 認証済み、スポーン待ち |
| 4 | Initialized | ワールドに出現済み |
client.on('status', newStatus => console.log('status:', newStatus))送信キューの挙動
queue()で積んだパケットはデフォルト 20ms 間隔の_tickでまとめて送られます。- 特例として
level_chunkだけはキューを素通りして即送信されます(ワールド配信のレイテンシ削減のため。src/connection.js参照)。 sendBuffer(buffer, immediate)は protodef シリアライズ済みの生バッファを送ります。独自フォーマット実験や再送制御に使えます。
パケットロギングのフック
DEBUG 環境変数以外に、インスタンス単位でロガーを差し替えられます。
client.inLog = (...args) => console.log('[受信]', ...args)
client.outLog = (...args) => console.log('[送信]', ...args)Relay の RelayPlayer はさらに upInLog / upOutLog / downInLog / downOutLog(上流・下流それぞれの入出力)を持ち、logging: false オプションで一括無効化できます。
圧縮アルゴリズムの制御
src/options.js と src/server.js にある未記載オプション:
| オプション | 既定値 | 説明 |
|---|---|---|
compressionAlgorithm | 'deflate' | 'none' | 'deflate' | 'snappy'(snappy は 1.19.30 前後の実験的仕様向け) |
compressionThreshold | 512 | このバイト数未満のペイロードは圧縮しない(サーバーのみ) |
compressionLevel | 7 | deflate のレベル(1–9) |
クライアントは 1.19.30 以上では最初 none で始め、サーバーからの network_settings 応答で設定を同期します。
サーバー側では実行時に差し替えも可能です:
server.setCompressor('deflate', 6, 1024) // アルゴリズム, level, thresholdstartGameData と entityId
start_game パケットの中身は client.startGameData に保持され、entityId getter はその runtime_entity_id を返します。ワールド座標・ゲームルール等もここから取得できます。
client.on('spawn', () => {
const { spawn_position, world_spawn, gamemode } = client.startGameData
console.log('初期スポーン:', spawn_position, gamemode)
})パース失敗時のダンプ
受信パケットのデシリアライズに失敗し、かつ 'error' リスナーが登録されていない場合、ライブラリは自動でバッファを hex ダンプします。1KB 超のパケットは <timestamp>_packetReadError.txt というファイルに保存されるので、未知のパケット解析に使えます。
プロトコル定義の事前コンパイル
パークーラ / シリアライザは protodef スキーマを実行時コンパイルして生成されます。リポジトリで npm run build(tools/compileProtocol.js)を実行すると data/<version>/{read,write,size}.js として事前コンパイルされ、起動が高速化します(npm パッケージ利用時は minecraft-data からの動的ロードにフォールバック)。