Paperプラグイン「twbridge」の使い方

2025-11-15

twbridge は、Scratch互換のブロックエディタ TurboWarp から、
Minecraft Java版（Paperサーバ） を操作できるようにするプラグインです。

教育版Minecraft（MakeCode）でおなじみの「ブロックコーディング × エージェント操作」を、
Java版のPaper環境で再現することを目的としています。

Paperサーバの準備とプラグインの投入

1. Paperサーバを用意
   Paper公式サイトから対応するバージョンの .jar をダウンロードし、初回起動して基本設定を完了させておきます。
2. twbridge.jar を plugins フォルダに配置
   • Hangar（公式配布ページ）
   • GitHubリポジトリ
3. サーバを起動
   起動後、plugins/twbridge/ フォルダと config.yml が自動生成されます。
4. コンソールに次のようなメッセージが出力されます。

[TWBridge] WebSocket listening on ws://xx.xxx.xxx.xxx:8787
[TWBridge] Extension server running at http://xxx.xxx.xxx.xxx:8788/tw/twbridge.js

この2つのURLは後ほどTurboWarp側で使用します。

config.yml の設定とペアリング

config.yml の全体例

ws:
  bindAddress: "0.0.0.0"
  port: 8787
  requirePairing: true
  maxMsgPerSecond: 30
  maxMsgBytes: 8192
  originWhitelist:
    - "*"
http:
  enabled: true
  bindAddress: "0.0.0.0"
  port: 8788
  path: "/tw/twbridge.js"
  wsAddress: "127.0.0.1"
  corsAllowOrigins:
    - "*"
  cacheSeconds: 60
pairing:
  enabled: true
  windowSeconds: 60
debug: false

config.ymlの項目説明

セクション	キー	内容
ws	bindAddress	WebSocketの待ち受けアドレスです。0.0.0.0で全てのNICを許可します。
	port	WebSocketの待受ポート（TurboWarpで指定します）。
	requirePairing	接続前にペアリング操作を必須にします。
	maxMsgPerSecond	1秒あたりの送信上限メッセージ数です。
	maxMsgBytes	1メッセージの最大バイト数です。
	originWhitelist	許可する接続元のOriginです。"*"で全許可。
http	enabled	拡張JSを配布するHTTPサーバを有効化します。
	port	拡張配布用HTTPサーバのポート番号です。
	path	配布パス。TurboWarpでこのURLを指定します。
	wsAddress	拡張が案内する既定のWebSocketアドレス。
	corsAllowOrigins	CORS許可オリジンです。
	cacheSeconds	拡張JSのキャッシュ秒数です。
pairing	enabled	ペアリング機能の有効／無効です。
	windowSeconds	/twbridge pair コマンド後の受付秒数です。
debug	—	デバッグログの出力を有効化します。

websocketペアリングの使い方

1. ペアリングを有効化します。
   上記の設定で requirePairing: true と pairing.enabled: true が指定されていることを確認します。
2. Paperサーバのコンソールで次を実行します。
   /twbridge pair
   例：
   [TWBridge] Pairing window opened for 60 seconds.
3. この60秒の間にTurboWarpから「接続する」ブロックを実行します。
   成功すると、Paper側に次のように表示されます。
   [TWBridge] New client paired: 192.168.0.xxx
4. 一度ペアリングされた端末は、次回以降自動で接続が許可されます。
   新しい端末を追加するときは、再度 /twbridge pair を実行してください。
5. 開発・テスト時にペアリングを無効化する場合、以下のように設定すれば、認証なしで即時接続が可能です。（LAN内でのテスト限定で使用してください。）

ws:
    requirePairing: false
pairing:
    enabled: false

TurboWarp Desktop のカスタムJS読み込み

1. TurboWarp Desktop を起動します。
2. 右下の ⚙️（歯車アイコン）→「拡張を追加」→「URLを指定」を選びます。
3. Paperサーバの起動時に表示された拡張URLを入力します。
   

   http://192.168.0.xxx:8788/tw/twbridge.js

4. 「twbridge」または「Minecraft」カテゴリのブロックが追加されていれば読み込み成功です。

ブロックコードの使い方

接続から切断までの基本構成

以下のようにブロックを組むと、コマンドを実行できます。

[接続する (ws://192.168.0.xxx:8787)]
[コマンドを送る (say Hello from twbridge!)]
[切断する]

Paperサーバのチャットに

[Server] Hello from twbridge!

と表示されれば通信成功です。

websocketの接続と切断

用途：TurboWarp DesktopからPaperサーバ上のtwbridgeへつなぎます。
前提：config.yml の ws.port（例：8787）に合わせます。requirePairing: true の場合は先に /twbridge pair を実行します。

例：接続 → 状態確認 → 切断

[接続する (ws://192.168.0.xxx:8787)]
[接続中かどうかを確認]
[切断する]

• 「接続する」には ws://<サーバIPまたはホスト>:<ポート> を入力します。

• 「接続中かどうかを確認」はブールのレポーター（表示の仕方は拡張に依存）です。

• 通信テストが終わったら「切断する」で閉じます。

Minecraftコマンドの送信

用途：任意のMinecraftコマンドをPaperサーバ側で実行します。
前提：接続済みであること。

例：/say を実行（接続→送信→切断の最小例）

[接続する (ws://192.168.0.xxx:8787)]
[コマンドを送る (say Hello from twbridge!)]
[切断する]

Paperサーバのチャットに次が表示されれば成功です。

[Server] Hello from twbridge!

• /say 以外のコマンドはサーバ設定や権限により結果が異なることがあります。

• 連続で複数コマンドを送る場合も、基本は同じ要領です（本記事では待機などの運用テクニックは割愛します）。

エージェントのスポーンとデスポーン

用途：プレイヤー近くにエージェント（作業ロボ）を出したり消したりします。
前提：接続済みであること。

例：エージェントを出す → 確認 → 消す → 切断

[接続する (ws://192.168.0.xxx:8787)]
[エージェントを出す]
[エージェントを消す]
[切断する]

• 現在の実装では、見た目はアーマースタンド相当の簡易なエージェントです。

• 移動・回転・ブロック設置などは未実装です（今後拡張予定です）。

トラブルシュート

症状	確認ポイント
接続できない	– TurboWarpはDesktop版を使用していますか？- IPアドレスとポート番号を確認してください。- ファイアウォールでポート(8787/8788)がブロックされていませんか？
拡張が読み込めない	– URLが正しいか確認します。- http.enabled が true になっていますか？
ペアリングで失敗する	– /twbridge pair を実行してから60秒以内に接続しましたか？
コマンドが反映されない	– 接続状態が維持されていますか？- /say 以外のコマンド実行には権限が必要な場合があります。

まとめ・今後の拡張予定

twbridge は、
「ブロックでマイクラを動かす」という教育版の魅力を
Java版のPaperサーバ環境に持ち込むための最小プラグインです。

現在は接続とエージェント生成の基本機能のみですが、今後以下を追加予定です。

項目	目的・概要
エージェントの移動・回転・ブロック設置／破壊	MakeCodeに近い行動ブロックを追加し、ワールド内での作業（移動・向き変更・設置・破壊）を実行できるようにします。
状態取得ブロック（座標・向き など）	位置・向き・周囲ブロックなどの情報を取得し、条件分岐や自動化ロジックを組み立てやすくします。
スレッド化によるエージェントの独立動作	各エージェントを別スレッド＋独立タイマーで処理し、同時並行で異なる行動を進められるようにします。
wss（セキュアWebSocket）対応	HTTPS環境やブラウザ版TurboWarpから安全に接続できるようにし、運用の選択肢を広げます。
接続ログ・監視機能の拡充	接続中のクライアントや操作履歴を把握しやすくし、授業・実験時の管理とトラブルシュートを容易にします。

関連リンク

ブロックコードプラグイン関連

1. Minecraft: Education の「ブロックコーディング×Agent（作業ロボ）」体験を JAVA版マイクラで再現

PDCA関連

1. マイクラで学ぶPDCAサイクル ー 遊びながら考える力を育てる
2. マイクラでPDCAを回す！子どもと学ぶためのホワイトボードプラグインを自作した話

Paperサーバ関連

1. マインクラフトサーバの構築方法：子どもと学ぶためのPaperサーバ構築ガイド
2. GitHub ActionsでPaperMCプラグインを“自動”公開するまで