Skip to content

Home

Jump to bottom
PIARIS edited this page Jun 21, 2026 · 2 revisions

DiscordBridgeJP

Minecraft ServerとDiscordをつなぐ、JDA(Discord Bot)ベースの連携プラグインです。チャットの双方向中継、アカウント連携、ロール色反映、コンソール連携、BAN同期など、Discord連携に必要な機能を一通り備えています。

対応バージョン: Paper / Purpur 1.21.8以降(26.1.x系含む)

ドキュメント

主な機能

チャット連携 MinecraftとDiscordのチャットを双方向に中継します。連携済みプレイヤーはWebhookでDiscordのアバターと表示名が反映されます。

アカウント連携 ゲーム内で発行されるコードをDiscordに貼るだけで連携完了。1つのDiscordアカウントに複数のMinecraftアカウントを紐づける運用にも対応しています。

ロール色反映 連携済みプレイヤーのDiscordロール色を、チャット欄・頭上のネームタグ・タブリストの3か所に反映します。

通知機能 参加・退出・初参加・進捗・死亡をDiscordへ通知します。文言・色は messages.yml から自由にカスタマイズできます。

コンソール連携 サーバーのコンソールログをDiscordへ中継し、許可されたロールはDiscord側からサーバーコマンドを実行できます。一般プレイヤーのコマンドのみを記録する専用ログチャンネルも設定可能です。

BAN同期 AdvancedBanと連携し、MinecraftとDiscordどちらでのBANも双方向に同期します。

リンク

Installation

DiscordBridgeJP の導入手順です。Discord Bot の作成から、サーバーへの設置・初期設定までを順番に説明します。

必要なもの

  • Paper または Purpur 1.21.8 以降(26.1.x系含む)
  • Discordサーバー(ギルド)の管理権限
  • Discord Developer Portal にログインできるDiscordアカウント

1. Discord Botを作成する

  1. Discord Developer Portal にアクセスし、「New Application」から新しいアプリケーションを作成します。名前は何でも構いません(例: ピア鯖Bot)。
  2. 左メニューの「Bot」を開き、「Reset Token」(初回は「Add Bot」)からBotを作成し、トークンをコピーしておきます。このトークンは絶対に公開しないでください。 誤って公開してしまった場合は、すぐにこの画面から再発行してください。
  3. 同じ「Bot」ページ内の「Privileged Gateway Intents」で、MESSAGE CONTENT INTENT を必ずONにしてください。これがOFFだとチャット中継・コマンド実行ができません。

2. Botをサーバーに招待する

  1. 左メニューの「OAuth2」→「URL Generator」を開きます。

  2. 「SCOPES」で bot にチェックを入れます。

  3. 「BOT PERMISSIONS」で以下にチェックを入れます。

    • View Channels(チャンネルを見る)
    • Send Messages(メッセージを送信)
    • Manage Messages(コード入力メッセージの自動削除を使う場合)
    • Manage Webhooks(チャット中継のWebhook表示に必須)
    • Read Message History
    • Add Reactions(コンソールコマンド実行時の✅表示)
    • Embed Links
    • Ban Members(BAN同期を使う場合)

  4. ページ下部に生成されたURLをコピーし、ブラウザで開いてBotを導入したいDiscordサーバーに招待します。

3. チャンネルIDを確認する

DiscordBridgeJPは複数のチャンネルをIDで指定します。IDをコピーするには、Discordの「ユーザー設定」→「詳細設定」で開発者モードをONにし、対象のチャンネルを右クリック→「IDをコピー」で取得します。

最低限、以下のチャンネルを用意してIDを控えておいてください。

  • チャット中継チャンネル: MinecraftとDiscordのチャットを中継するチャンネル
  • コンソールチャンネル: サーバーログの中継、Discordからのコマンド実行に使うチャンネル
  • 連携用チャンネル: アカウント連携コード(!XXXXXXXX)を貼ってもらうチャンネル
  • (任意)コマンドログ専用チャンネル: 一般プレイヤーが実行したコマンドのみを記録したい場合

guild-id(サーバー自体のID)も同様に、サーバーアイコンを右クリックして取得できます。

4. プラグインを設置する

  1. ビルドした(またはModrinthからダウンロードした)DiscordBridgeJP.jar をサーバーの plugins フォルダに置きます。
  2. 一度サーバーを起動し、plugins/DiscordBridgeJP/ フォルダに config.yml ・ messages.yml ・ lang/ が自動生成されることを確認します。
  3. サーバーを停止します。

5. config.ymlを設定する

plugins/DiscordBridgeJP/config.yml を開き、以下を入力します。

bot-token: "ここにBotトークン"
guild-id: "ここにサーバーID"
chat-channel-id: "チャット中継チャンネルID"
console-channel-id: "コンソールチャンネルID"
verify-channel-id: "連携用チャンネルID"
command-log-channel-id: "0"  # 使わない場合は 0 のまま

その他の項目(通知の文言、ロール色反映、BAN同期など)は、デフォルトのままでも動作します。詳細は Configuration と Messages を参照してください。

6. 起動・動作確認

  1. サーバーを起動します。コンソールにBotの接続成功ログが出ることを確認してください。
  2. ゲーム内で /discordbridgejp status を実行し、Botが接続済みであることを確認します。
  3. Discordの連携用チャンネルが正しく案内に使われているか確認します。
  4. ゲーム内で /discordbridgejp link を実行し、表示されたコード(!XXXXXXXX)を連携用チャンネルに貼って、アカウント連携が完了することを確認します。

正しく連携できれば、以降そのプレイヤーのチャットはDiscordでWebhook表示(アバター+名前)になり、Discordロール色がMC内に反映されます。

トラブルシューティング

うまく動かない場合は FAQ / Troubleshooting を確認してください。

Configuration

plugins/DiscordBridgeJP/config.yml の全設定項目です。アップデートで新しい項目が増えた場合は、サーバー起動時に既存ファイルへ自動で補完されます(既存の値は上書きされません)。

通知文言・Embed色・チャット表示形式などは config.yml ではなく Messages (messages.yml)で設定します。

Discord接続(必須)

キー 説明
bot-token Discord Developer Portal で取得したBotトークン。他人に公開しないこと
guild-id Botを動かすDiscordサーバー(ギルド)自体のID
chat-channel-id MC↔Discordチャット中継チャンネルID
console-channel-id コンソールログ中継 / Discordからのコマンド実行チャンネルID
verify-channel-id アカウント連携コード(!XXXXXXXX)を入力するチャンネルID
command-log-channel-id プレイヤーコマンドログ専用チャンネルID。0で無効

いずれも導入手順は Installation を参照してください。

console-command

Discordのコンソールチャンネルでの発言を、サーバーコマンドとして実行する機能の設定です。

キー デフォルト 説明
console-command.enabled false trueにすると console-channel での発言をMCコマンドとして実行する(強い権限のため要注意)
console-command.role-id "0" 上記を許可するDiscordロールID

console-log-level

キー デフォルト 説明
console-log-level "ALL" コンソールチャンネルに中継するログの範囲。ALL=全ログ / WARN_ERROR=WARN・ERRORのみ。Discordチャンネル内でコマンドを実行した場合、その実行結果はこの設定に関わらず常に表示されます

language

キー デフォルト 説明
language "ja" 表示言語。lang/フォルダにあるYAMLファイルの言語コードを指定(ja、enなど)

name-color(ロール色反映)

連携済みプレイヤーのDiscordロール色をMC側へ反映する設定です。

キー デフォルト 説明
name-color.chat true チャット欄のプレイヤー名にロール色(フルカラー)を反映し、<名前>形式にする
name-color.nametag true 頭上のネームタグに反映(バニラ16色へ自動近似)
name-color.tablist true タブリスト(プレイヤー一覧)に反映(フルカラー)
name-color.cache-seconds 300 Discordロール色をREST取得してからキャッシュする秒数

個別プレイヤー単位でON/OFFしたい場合は /discordbridgejp namecolor <on|off> <player> コマンドを使います。

chat-command / sticky-message

キー デフォルト 説明
chat-command.enabled true Discord側のテキストコマンド(!list等)を有効にするか
chat-command.prefix "!" テキストコマンドの接頭辞
sticky-message.enabled true チャットチャンネル下部に案内メッセージを固定表示する機能

link(アカウント連携)

キー デフォルト 説明
link.code-expiry-seconds 600 連携コードの有効期限(秒)
link.delete-code-message false 連携用チャンネルに貼られた本人のコードメッセージを、処理後にBotが削除するか
link.unlink-mode "block" require-link-for-new-players: true 中の unlink 動作。block=一般プレイヤーのunlinkコマンドを拒否 / kick=unlink自体は許可し解除後に即KICK
link.multi-account.enabled false 1つのDiscordアカウントに複数のMinecraftアカウントを紐づけられるようにするか
link.multi-account.max-per-discord 2 1つのDiscordアカウントに紐づけられるMinecraftアカウントの上限(multi-account.enabled時のみ有効)

require-link-for-new-players

キー デフォルト 説明
require-link-for-new-players false trueにすると、初参加(過去にこのサーバーへ入ったことのない)プレイヤーに、Discordアカウント連携を必須化する。未連携の場合は接続時にキック画面でコードが表示される。既にプレイ済みのプレイヤーは対象外

maintenance(メンテナンスモード)

/discordbridgejp maintenance on [理由] で即時切替・保存されます。手動でconfig.ymlを編集することもできます。

キー デフォルト 説明
maintenance-mode false メンテナンスモードのON/OFF
maintenance.bypass-permission "" メンテ中でも参加できるバイパス権限ノード。空ならOPのみ参加可能(LuckPerms等の権限プラグイン導入時のみ有効)
maintenance.reason "" 直近のメンテナンス理由。コマンドから自動保存されるが手動編集も可

ban-sync(BAN同期)

AdvancedBanと連携してBANを双方向に同期します。

キー デフォルト 説明
ban-sync.mc-to-discord true MinecraftでのBANをDiscordへ反映するか
ban-sync.discord-to-mc true DiscordでのBANをMinecraftへ反映するか
ban-sync.unban-sync true BAN解除も同様に同期するか

複数アカウント連携時は、紐づく全Minecraftアカウントに対してBAN/解除が反映されます。

recognize-legacy-discordsrv-permissions

キー デフォルト 説明
recognize-legacy-discordsrv-permissions true discordsrv.silentjoin / discordsrv.silentquit 権限(SuperVanishJP等が付与)も discordbridgejp.* と同等に扱うか。SuperVanishJPとの互換性のための設定

debug

キー デフォルト 説明
debug false trueにすると、Webhook送信やロール色反映などの詳細ログをコンソールに出力する。動作確認・トラブルシューティング時に使用

設定変更後は /discordbridgejp reload で反映できます(Botの再接続を伴います)。

Messages

plugins/DiscordBridgeJP/messages.yml の全設定項目です。チャット表示・通知に関する文言、Embedの色、添付ファイルの扱いをまとめて設定できます。

messages.yml は Configuration (config.yml)とは別ファイルです。config.yml の language を en に変更しても、messages.yml の文言は自動翻訳されません。プレースホルダの中身(進捗名・死亡メッセージ)だけが言語設定に応じて変わるので、外国語サーバーとして運用する場合はこのファイルの文言を直接書き換えてください。

アップデートで新しい項目が増えた場合は、サーバー起動時に既存ファイルへ自動で補完されます(既存の値は上書きされません)。

使えるプレースホルダ

プレースホルダ 説明 使える場所
{playername} プレイヤー名 通知全般
{advancement} 進捗名 進捗通知のみ
{deathmessage} 死亡メッセージ全文(プレイヤー名を含む) 死亡通知のみ

使える色(embed-color)

色名、または16進カラーコード(#RRGGBB)が使えます。

black / dark_blue / dark_green / dark_aqua / dark_red / dark_purple / gold / gray / dark_gray / blue / green / aqua / red / light_purple / yellow / white / lime / orange / pink / purple / dark_magenta

例: embed-color: "lime" または embed-color: "#7FFF00"

discord-to-minecraft(Discord→MCチャットの表示形式)

キー デフォルト 説明
discord-to-minecraft.format "C" Discordから送られたメッセージをMC内でどう表示するか

選べる形式は3つです。

  • A: [Discord] 名前 > メッセージ(プレーン・色なし)
  • B: [Discord \| ロール名] 名前 > メッセージ(Discord最上位ロール名入り。ロール無しは\|部分を省略)
  • C: [Discord] 名前 > メッセージ(名前部分だけDiscord最上位ロール色)

attachments(Discordの添付ファイル)

キー デフォルト 説明
attachments.image "link" 画像添付の表示方法。link=画像URLをそのまま流す / text=固定文字に置換
attachments.attachment-image-text "[添付画像]" image: "text" の場合に使われる固定文字
attachments.attachment-file-text "[添付ファイル]" 画像以外のファイルに常に使われる固定文字

notifications(プレイヤー通知)

参加・初参加・退出・進捗・死亡の5種類です。いずれもDiscordアバターのアイコン付きEmbedで送られます(embed: falseにすると太字テキストになります)。

共通の項目構成は以下の通りです。

キー 説明
enabled 通知を出すか
embed true=アイコン付きEmbed / false=太字テキスト
embed-color Embed左側の色
message 通知文言({プレースホルダ}使用可)

デフォルト値の一覧です。

通知 embed-color message
join(参加) lime {playername}がサーバーに参加しました
first-join(初参加) purple {playername}が初めてサーバーに参加しました
leave(退出) red {playername}がサーバーから退出しました
advancement(進捗) gold {playername}が進捗 [ {advancement} ] を達成しました
death(死亡) black {deathmessage}

first-join は初参加(過去にこのサーバーに入ったことがない)プレイヤーにのみ適用され、それ以外は通常の join が使われます。

server(サーバー通知)

サーバー起動・停止の通知です。プレイヤー通知と異なりアイコンは付かず、絵文字を文言に直接含める形式です。

キー 説明
enabled 通知を出すか
embed true=Embed / false=太字テキスト
embed-color Embed左側の色
message 通知文言。空にすると送信されない(無効化)。絵文字を入れたい場合はここに直接記述する

デフォルト値の一覧です。

通知 embed-color message
startup(起動) lime :white_check_mark: サーバーが起動しました。
shutdown(停止) red :octagonal_sign: サーバーが停止しました。

停止通知は、メッセージの送信が完了してからBotが切断されるため、確実にDiscordへ届きます。

設定変更後は /discordbridgejp reload で反映できます。

Commands & Permissions

Minecraft内コマンド

ベースコマンドは /discordbridgejp(エイリアスなし)です。

管理者コマンド(discordbridgejp.admin、デフォルトOPのみ)

コマンド 説明
/discordbridgejp reload config.yml / messages.yml / lang を再読込し、Botを再接続する
/discordbridgejp status Botの接続状態を確認する
/discordbridgejp language <code> 表示言語を切り替える(例: ja、en)
/discordbridgejp namecolor <on|off> <player> 指定プレイヤーのロール色反映(チャット欄/ネームタグ/タブリスト)をON/OFFする
/discordbridgejp silentlogin add <player> 指定プレイヤーの入退室を完全サイレント化する(MC内・Discord通知の両方を抑制)
/discordbridgejp silentlogin remove <player> 上記の解除
/discordbridgejp silentlogin list サイレント指定中のプレイヤー一覧を表示する
/discordbridgejp maintenance on [理由] メンテナンスモードを有効化する(理由は省略可)
/discordbridgejp maintenance off メンテナンスモードを解除する

一般プレイヤーコマンド

コマンド 権限 説明
/discordbridgejp link discordbridgejp.link(デフォルトtrue) Discordアカウント連携コードを発行する。表示されたコード(!XXXXXXXX)を連携用チャンネルに貼ると連携完了
/discordbridgejp unlink discordbridgejp.unlink(デフォルトtrue) Discordアカウント連携を解除する

link / unlink はデフォルトで誰でも実行できます。権限を制限したい場合はLuckPerms等で個別に剥奪してください。

Discord内コマンド

チャットチャンネル

コマンド 説明
!list オンラインプレイヤー一覧を表示する(接頭辞!はconfig.ymlのchat-command.prefixで変更可能)

連携用チャンネル(verify-channel)

入力 説明
!XXXXXXXX(8文字のコード) ゲーム内で発行されたコードを貼ると、そのDiscordアカウントとの連携が完了する
!list 連携済みアカウント一覧を表示する(管理者(ADMINISTRATOR権限)のみ)

コンソールチャンネル(console-channel)

console-command.enabled: true かつ console-command.role-id で指定したロールを持つユーザーの発言は、サーバーコマンドとして実行されます(先頭の/は省略可)。実行が成功すると、送信したメッセージに✅のリアクションが付きます。強い権限を持つ機能のため、信頼できるロールにのみ付与してください。

権限ノード一覧

権限ノード デフォルト 説明
discordbridgejp.admin op 管理コマンド全般(reload/status/language/namecolor/silentlogin/maintenance)の実行権限
discordbridgejp.link true /discordbridgejp link でアカウント連携コードを発行する権限
discordbridgejp.unlink true /discordbridgejp unlink で連携を解除する権限
discordbridgejp.silentjoin false 参加時のDiscord通知のみ抑制する(MC側のチャットには影響しない)
discordbridgejp.silentquit false 退出時のDiscord通知のみ抑制する

default: false の権限は、OPであっても自動では付与されません。明示的にLuckPerms等で付与する必要があります。

互換性として、config.yml の recognize-legacy-discordsrv-permissions: true 時は、SuperVanishJP等が動的に付与する discordsrv.silentjoin / discordsrv.silentquit 権限も同様に扱われます。

LuckPermsでワイルドカード(*)権限を持つ場合の注意

管理者グループに *(全権限)を付与している場合、discordbridgejp.silentjoin / silentquit も自動的にtrueになり、常に入退室通知が抑制されてしまうことがあります。これを避けたい場合は、該当グループに個別ノードをfalseで明示的に上書きしてください。

/lp group <グループ名> permission set discordbridgejp.silentjoin false
/lp group <グループ名> permission set discordbridgejp.silentquit false

FAQ / Troubleshooting

導入・運用でよくある質問とトラブルシューティングです。当てはまる症状が見つからない場合は、config.ymlのdebug: trueにしてから/discordbridgejp reloadし、コンソールログ(特に[Webhook]や[debug][NameColor])を確認してください。多くの問題はここに原因が出ます。

Botが起動しても接続されない

確認すること

  • bot-token が正しくコピーされているか(前後に余計な空白や改行が入っていないか)
  • guild-id が、Botを招待した実際のDiscordサーバーのIDと一致しているか
  • Discord Developer Portalの「Bot」ページで MESSAGE CONTENT INTENT がONになっているか(これがOFFだとチャット内容が読み取れず、チャット中継・コマンド実行が機能しません)

チャットが連携済みプレイヤーのアバター付き(Webhook)表示にならない

PIARIS6245: メッセージ のような無装飾の表示になってしまう場合の原因はだいたい次のいずれかです。

  • Botに 「ウェブフックの管理」権限 が無い。Discord Developer PortalのOAuth2 URL Generatorで権限を付け直し、再度招待URLからBotを招待し直してください(後から権限を足しても、既に参加済みのBotには自動で反映されないため、サーバー側のロール設定 or 再招待が必要です)
  • debug: true にして/discordbridgejp reload後、もう一度MCチャットを送信し、コンソールに出る[Webhook]ログを確認してください。「Webhook作成に失敗」と出ていれば権限不足、「client未準備」が出続ける場合はprepare自体が走っていない可能性があります

/discordbridgejp reload のたびにWebhookが壊れる

RejectedExecutionException: The Requester has been stopped! のようなエラーが出る場合は、古いバージョンのプラグインを使っています。reload時にBotの接続(JDA)を作り直す際、Webhookクライアントが古い接続を参照したままになる不具合が過去にありました。最新版に更新してください。

進捗達成時のMC内チャット表示が白色になる/おかしい

○○が進捗[進捗名]を達成しました のような表示が白色になったり崩れたりする場合は、古いバージョンの不具合です。過去のバージョンでは、Discord通知用の日本語翻訳処理をサーバー全体のメッセージ翻訳に誤って割り込ませてしまい、バニラの進捗ブロードキャストの色情報が失われていました。最新版では修正済みです。

入退室の通知が常に出ない/常に抑制される

LuckPermsで管理者グループに *(ワイルドカード、全権限)を付与している場合、discordbridgejp.silentjoin / silentquit も自動的にtrue扱いになり、常に通知が抑制されます。これはバグではなく、DiscordSRVも同じ仕組み(hasPermissionによる権限チェック)を採用しているため同様の挙動になります。

対処は、該当グループに個別ノードをfalseで明示的に上書きすることです。 /lp group <グループ名> permission set discordbridgejp.silentjoin false /lp group <グループ名> permission set discordbridgejp.silentquit false

これでワイルドカードを持っていても、通常時は通知が出るようになります。SuperVanishJP等でバニッシュした際は、動的に付与される一時権限がこの上書きより優先されるため、バニッシュ中だけ正しく抑制されます。

ロール色の反映が遅い

アカウント連携が完了すると、Discordからロール色を取得して即座に反映する設計になっています(通常は1秒未満)。数分かかる場合は、debug: trueでログを確認してください。[debug][NameColor]のログが出ない場合はイベント自体が発火していない可能性があるため、最新版か確認してください。タイムアウト気味な場合はDiscord API側の混雑が原因のこともあり、その場合は時間経過で自然に解消します。

連携コード(!XXXXXXXX)が読みにくい

Minecraftの標準フォントは0(ゼロ)とO(オー)、1、I、lが似て見えることがあります。現在のバージョンでは、これらの紛らわしい文字をコード生成時に除外しています。それでも判読しづらい場合は、コード部分をクリックするとクリップボードにコピーされる機能があるので、目で読み取らず直接貼り付けてください。

新規プレイヤーがサーバーに入れない

require-link-for-new-players: true の場合、初参加(過去にこのサーバーへ入ったことが一度もない)プレイヤーは、Discordアカウントと連携するまで参加できません。これは意図した仕様です。

参加しようとすると、キック画面に連携コード(!XXXXXXXX)が表示されます。このコードを、連携したいDiscordアカウントから連携用チャンネルに貼ることで連携が完了し、次回から参加できるようになります。既に一度でも参加したことのあるプレイヤーは対象外です。

/plugins コマンドで「Bukkit Plugins:」と表示される

これは正常です。PaperサーバーでもCraftBukkit由来の表示文言がそのまま使われているだけで、実際にPaperで動いているかどうかとは無関係です。/version コマンドで実際のサーバーソフトを確認できます。

WARN/ERRORのみモードでDiscordから実行したコマンドの結果が見えない

console-log-level: "WARN_ERROR" に設定している場合でも、Discordのコンソールチャンネルから実行したコマンドの結果は、実行直後の数秒間だけレベルフィルタを無視して必ず表示されるようになっています。それでも見えない場合は、コマンド自体がエラーになっていないか、Botに該当コマンドを実行する権限があるか確認してください。

それでも解決しない場合

GitHubのIssue で報告してください。debug: true 時のコンソールログを添えていただけると原因の特定が早くなります。

Clone this wiki locally