Home

DiscordBridgeJP-1.1.3

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

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

ドキュメント

• Installation — 導入手順(Botの作成から設定完了まで)
• Configuration — config.yml / bot.yml の全設定項目
• Messages — messages.yml(通知文言・Embed設定)のカスタマイズ
• Commands & Permissions — コマンド・権限一覧
• FAQ / Troubleshooting — よくある質問・トラブルシューティング

主な機能

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

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

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

通知機能 参加・退出・初参加・進捗・死亡をDiscordへ通知します。文言・色は messages.yml から自由にカスタマイズできます。メンテナンスモード中は通知種別ごとに個別で抑制することもできます。

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

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

Discordサーバー離脱検知 連携済みプレイヤーがDiscordサーバーを抜けたことを検知し、再参加・再認証するまで次回ログインをブロックします。管理者による手動タイムアウトや強制連携解除にも対応しています。

リンク

• Modrinthページ
• ライセンス: PolyForm Noncommercial License 1.0.0(全文)

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」で、以下2つを必ずONにしてください。
   • MESSAGE CONTENT INTENT: OFFだとチャット中継・コマンド実行ができません。
   • SERVER MEMBERS INTENT: OFFだとDiscordサーバー離脱検知機能が動作しません(Botの接続自体が失敗することがあります)。

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同期を使う場合)
   • Moderate Members(Discord側タイムアウト機能との連携を使う場合)

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 ・ bot.yml ・ messages.yml ・ lang/ が自動生成されることを確認します。
3. サーバーを停止します。

過去のバージョン(1.0.x系)からアップデートする場合は、bot-tokenや各チャンネルIDがconfig.ymlからbot.ymlへ分離されています。同梱のupdate-guide.txt(起動後にplugins/DiscordBridgeJP/update-vX.X.X/フォルダに自動生成されます)を参照して移行してください。

5. bot.ymlを設定する

plugins/DiscordBridgeJP/bot.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同期、Discordサーバー離脱検知など)は config.yml にあり、デフォルトのままでも動作します。詳細は 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 の全設定項目です。

アップデートによる自動補完機能は廃止されています。 アップデートで新しい設定項目が増えても、既存ファイルへの自動追記は行われません。起動時に plugins/DiscordBridgeJP/update-vX.X.X/ フォルダが自動生成されるので、同梱の update-guide.txt の手順に従って手動で反映してください。

通知文言・Embed色・チャット表示形式などは config.yml ではなく Messages (messages.yml)で設定します。Botトークン・チャンネルIDは config.yml ではなく bot.yml にあります(下記参照)。

bot.yml(Discord接続、必須)

漏洩すると影響が大きい情報のため、config.ymlとは別ファイルに分離されています。GitHub等にソースを公開する場合は.gitignoreに追加することを推奨します。

キー	説明
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自体は許可し、下記の在籍確認・タイムアウト付与のうえキック
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=連携必須化モード。初参加(過去にこのサーバーへ入ったことのない)プレイヤーに連携を必須化する。未連携の場合は接続時にキック画面でコードが表示される。加えて、連携解除(unlink)自体もブロック対象として扱われるようになり、非除外対象者(OP・login-check-exempt-groups所属者を除く)は連携解除と同時にタイムアウトが付与されキックされる(再ログインには連携が必要)。false=連携任意モード。初参加も連携解除も自由で、キック・タイムアウトは一切発生しない

guild-leave(Discordサーバー離脱検知)

連携済みプレイヤーがDiscordサーバーを抜けたことを検知し、次回ログインをブロックする機能です。

キー	デフォルト	説明
guild-leave.enabled	true	この機能自体のON/OFF。falseにすると、既に付与されているタイムアウトも一括で解除される
guild-leave.rejoin-verify	true	Discordサーバーに再参加した際、念のため確認コードを発行して再認証させるか。falseなら再参加を検知した時点で自動的にタイムアウトを解除する
guild-leave.login-check-enabled	true	ログインを試みるたびに、そのプレイヤーのDiscord在籍状況をリアルタイムで確認するか。バニラ管理者(OP)以外は参加のたびにDiscordへ問い合わせが発生する(数秒待たされる場合がある)。Bot接続時の一括チェックだけでは拾いきれない「Bot切断中に離脱していた」ケースも確実にブロックしたい場合はtrueのままにする
guild-leave.login-check-exempt-groups	[]	LuckPerms導入時のみ有効。指定したグループ名(複数可、例: ["admin", "moderator"])に所属するプレイヤーは、タイムアウト自体は付与されるがキック/ログインブロックはされない。グループから外れた時点で次回ログインからブロックされる

timeout-command

/discordbridgejp timeout / removetimeout / unlink <player> コマンドのタブ補完設定です。

キー	デフォルト	説明
timeout-command.tab-complete-mode	"all"	online=オンラインプレイヤーのみ候補に出す / all=サーバー参加経験のある全プレイヤーを候補に出す(オンラインを上位表示)

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

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

キー	デフォルト	説明
maintenance-mode	false	メンテナンスモードのON/OFF
maintenance.bypass-permission	""	メンテ中でも参加できるバイパス権限ノード。空ならOPのみ参加可能(LuckPerms等の権限プラグイン導入時のみ有効)
maintenance.reason	""	直近のメンテナンス理由。コマンドから自動保存されるが手動編集も可
maintenance.notify-join-leave	false	メンテ中、参加/退出通知をDiscordへ出すか
maintenance.notify-first-join	false	メンテ中、初参加通知をDiscordへ出すか
maintenance.notify-advancement	false	メンテ中、進捗達成通知をDiscordへ出すか
maintenance.notify-death	false	メンテ中、死亡通知をDiscordへ出すか
maintenance.notify-server	true	メンテ中、サーバー起動/停止通知をDiscordへ出すか(メンテ中でも起動・停止は把握したいことが多いためデフォルトtrue)
maintenance.chat-enabled	false	メンテ中、MC↔Discordのチャット中継を行うか

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

アップデートによる自動補完機能は廃止されています。 アップデートで新しい設定項目が増えても、既存ファイルへの自動追記は行われません。起動時に plugins/DiscordBridgeJP/update-vX.X.X/ フォルダが自動生成されるので、同梱の update-guide.txt の手順に従って手動で反映してください。

使えるプレースホルダ

プレースホルダ	説明	使える場所
{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にすると太字テキストになります)。メンテナンスモード中の個別抑制については Configuration の maintenance.notify-* を参照してください。

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

キー	説明
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 が使われます。

maintenance(メンテナンス開始/終了通知)

メンテナンスモードの開始・終了そのものを知らせる通知です。config.yml の maintenance.notify-* 設定(参加/退出/チャット中継等の抑制)とは別物で、こちらは /discordbridgejp maintenance on/off を実行するたびに必ず送られます。サーバー通知と同じくアイコンなし・絵文字付きの形式です。

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

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

通知	embed-color	message
start(開始)	red	:red_circle: メンテナンス開始。管理者以外は参加出来ません。
end(終了)	lime	:green_circle: メンテナンス終了。すべてのプレイヤーは入室可能です。

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	discordbridgejp.command.reload	config.yml / bot.yml / messages.yml / lang を再読込し、Botを再接続する
/discordbridgejp status	discordbridgejp.command.status	Botの接続状態を確認する
/discordbridgejp language <code>	discordbridgejp.command.language	表示言語を切り替える(例: ja、en)
/discordbridgejp namecolor <on|off> <player>	discordbridgejp.command.namecolor	指定プレイヤーのロール色反映(チャット欄/ネームタグ/タブリスト)をON/OFFする
/discordbridgejp silentlogin add|remove|list [player]	discordbridgejp.command.silentlogin	指定プレイヤーの入退室を完全サイレント化する(MC内・Discord通知の両方を抑制)
/discordbridgejp maintenance on|off [理由]	discordbridgejp.command.maintenance	メンテナンスモードの切替
/discordbridgejp timeout <player>	discordbridgejp.command.timeout	指定プレイヤーのログインを手動でブロックする(オンラインなら即キック)
/discordbridgejp removetimeout <player>	discordbridgejp.command.timeout	上記の手動ブロックを解除する
/discordbridgejp unlink <player>	discordbridgejp.command.forceunlink	他プレイヤーのDiscord連携を強制的に解除する(在籍状況に応じてタイムアウト・キックを伴う)

一般プレイヤーコマンド

コマンド	権限	説明
/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権限)のみ)
!auth <player名> <DiscordID>	管理者、またはconsole-command.role-idで指定したロールが、MC垢とDiscord垢を強制連携する。既存のタイムアウトも同時に解除される

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

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

権限ノード一覧

権限ノード	デフォルト	説明
discordbridgejp.admin	op	全ての管理コマンドをまとめて許可する上位互換権限(個別付与不要)
discordbridgejp.command.reload	op	/discordbridgejp reload
discordbridgejp.command.status	op	/discordbridgejp status
discordbridgejp.command.language	op	/discordbridgejp language
discordbridgejp.command.namecolor	op	/discordbridgejp namecolor
discordbridgejp.command.silentlogin	op	/discordbridgejp silentlogin
discordbridgejp.command.maintenance	op	/discordbridgejp maintenance
discordbridgejp.command.timeout	op	/discordbridgejp timeout, removetimeout
discordbridgejp.command.forceunlink	op	/discordbridgejp unlink <player>(他プレイヤーの強制解除)
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.adminを含む全ての権限が自動的にtrueになります。特定のコマンドだけを個別に制限したい場合は、該当グループにその権限ノードをfalseで明示的に上書きしてください。

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

FAQ / Troubleshootingページです。既存の項目はそのまま活かしつつ、1.1.3で追加された機能に関するトラブルシューティングを新設します。 markdown# FAQ / Troubleshooting

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

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

確認すること

• bot-token が正しくコピーされているか(前後に余計な空白や改行が入っていないか、bot.ymlに入力しているか)
• guild-id が、Botを招待した実際のDiscordサーバーのIDと一致しているか
• Discord Developer Portalの「Bot」ページで以下2つがONになっているか
  • MESSAGE CONTENT INTENT(OFFだとチャット内容が読み取れず、チャット中継・コマンド実行が機能しません)
  • SERVER MEMBERS INTENT(OFFだとDiscordサーバー離脱検知機能が使えず、Botの接続自体が失敗することがあります。エラーメッセージが出ないまま接続に失敗するケースもあります)

チャットが連携済みプレイヤーのアバター付き(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等でバニッシュした際は、動的に付与される一時権限がこの上書きより優先されるため、バニッシュ中だけ正しく抑制されます。同様にdiscordbridgejp.adminもワイルドカードで自動的にtrueになるため、特定コマンドだけを制限したい場合は個別ノードを明示的にfalseで上書きしてください。

ロール色の反映が遅い

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

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

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

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

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

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

連携解除(unlink)したら急にログインできなくなった

require-link-for-new-players: true の場合、連携解除(/discordbridgejp unlink、または管理者による強制解除)自体もブロック対象として扱われます。連携解除と同時にタイムアウトが付与され、再ログインには連携が必要になります(キック画面にコードが表示されるので、それをDiscordの連携用チャンネルに貼れば自分で再連携できます)。

バニラ管理者(OP)はこのチェックを完全にスキップします。特定のプレイヤー(サブ管理者等)だけこの挙動から除外したい場合は、guild-leave.login-check-exempt-groups にLuckPermsのグループ名を指定してください(この場合、タイムアウト自体は付与されますが、グループに所属している間はブロックされません)。

require-link-for-new-players: false(連携任意モード)であれば、この挙動は一切発生しません。

Discordサーバーを抜けたらキックされ続ける/再ログインできない

これは意図した動作です。連携済みプレイヤーがDiscordサーバーを抜けると、キック画面に「Discordサーバーを抜けました」という案内とキック理由(GUILD_LEAVE)が表示されます。Discordサーバーに再参加し、guild-leave.rejoin-verify: true(デフォルト)の場合はキック画面に表示されるコードを認証チャンネルに貼れば再ログインできます。rejoin-verify: falseの場合は、再参加を検知した時点で自動的にブロックが解除されます。

Botが一時的に切断していた間にプレイヤーがDiscordサーバーへ出入りしていた場合でも、Botが再接続したタイミングで在籍状況が一括チェックされ、既にDiscordへ戻っている場合はオンラインでも即座にキックされることがあります(整合性を取るための挙動です)。

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

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

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

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

それでも解決しない場合

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