概要

ランクシステムは、ユーザーのDiscord活動量を可視化する機能です。 チャットでの発言やVCへの接続時間に応じてXPが溜まり、 一定量貯まるとレベルアップします。

ミュート勢の利便性を考慮し、VCミュート中もXPが獲得できる設計です。 また、テキストチャットとインチャットを別々に計測する設定も可能です。

機能一覧

経験値の獲得方法

チャット経験値

メッセージを送信するとXPが付与されます。 ただし、以下の条件で付与されません。

• Botユーザーのメッセージ
• ! や / で始まるコマンド
• クールダウン期間中の連続送信（デフォルト60秒）
• 有効期間外（active_start / active_end が設定されている場合）
• チャンネルフィルターで拒否されているチャンネル
• チャット獲得ロールが設定されている場合、そのロールを1つも持っていない

チャットXPの計算フロー

1. チャット/インチャット ロール要件チェック
   └── ロール未所持 → 付与なし

2. 基本XP = _calc_random_exp(chat=True)
   ├── モード0（固定値）: chat_exp × chat_multiplier
   ├── モード1（一様）: random.uniform(min, max)
   ├── モード2（三角）: random.triangular(min, max)
   └── モード3（カスタム）: ユーザー定義式 (lo, hi, R 利用可)

3. + メッセージボーナス
   ├── 文字数ボーナス（設定文字数以上で加算）
   ├── 添付ファイルボーナス（1添付ごとに加算）
   └── スタンプボーナス（1スタンプごとに加算）

4. × イベントブースト倍率（boost_chat_mult）

5. XPキャップ適用（日次上限を超過しないよう調整）

メッセージボーナス

メッセージの質に応じて追加XPが付与されます。管理者が各項目を個別に設定できます。

VC経験値

VCに接続している間、XPが付与されます。 切断時に接続時間に応じて一括計算されます。

• VC切断時に接続開始時からの経過秒数で比例計算
• 1分あたりのXP × (経過秒数 / 60) で計算（端数あり）
• 2人以上が接続している場合のみ有効
• ミュート中でもXPが獲得可能
• 1人VCでは獲得できません
• VC CHフィルターで拒否されているVCでは付与されません
• VC最小接続時間未満の接続では一切XPが付与されません
• VC自分ロール・同席者ロールの要件を満たさない場合は付与されません

⏳ VC最小接続時間

VC接続後、指定分数未満の接続ではXPが一切付与されません。 デフォルトは1分で、1分未満のVC接続はXPなしになります。

• 0に設定: 最小接続時間の制限がなくなり、1秒から比例計算でXPが付与されます
• 1以上: 指定分数を超えた場合のみXP付与。超えた分は端数まで比例計算（例: 90秒 = 1.5分分）
• 設定は「⏱️ クールダウン設定」Modalから行います（チャットクールダウンと同時設定）

💬🎙️ チャット・インチャット ロール要件 NEW

チャット・インチャットそれぞれに獲得に必要なロールを設定できます。 設定されたロールを1つも持っていないユーザーは、 そのトラックでXPを一切獲得できません。

これらの設定は「🎤 VC/チャット条件設定」Modalで一括管理できます。

XP集計モード

プリセットごとにXP集計モードを選択できます。 設定パネルの「XP集計モード」をクリックするたびに 3つのモードが循環します。

• 全体 (combined): chat_exp と inchat_exp と vc_exp を 合算して単一レベルを計算します。 チャットとVCの両方の活動が同じレベルに貢献するシンプルな方式です。
• VC/チャット (separate): チャットXP → chat_exp（+inchat_exp）、 VC XP → vc_exp として別々に記録し、 それぞれから独立したレベルを計算します。
• VC/チャット/インチャット (inchat): separate と同様にチャット・VCで独立したレベルを持ちつつ、 VCチャンネル内のテキストチャットやステージチャンネルでの 発言のみが別テーブル inchat_exp に記録され、 3つ目の独立したレベルとして表示されます。

🔑 重要な設計: レベルは保存されず、全ての表示でXPからその場計算されます。 そのため成長曲線の変更が過去のデータに即座に反映され、 レベルがずれる心配はありません。

ランダムEXPシステム

経験値の獲得量にバラつきを持たせられるランダムEXP機能を 搭載しています。4つのモードから選択可能です。

カスタム数式モード（モード3）

以下の変数が利用可能です：

設定例：

# 一様ランダムと同じ挙動
lo + int(R * (hi - lo + 1))

# 正規分布風
int((lo + hi) / 2 + (R - 0.5) * (hi - lo))

# 高確率で最大値近く
int(hi * R ** 0.5)

拡張機能

📅 XPキャップ

1日・1週間あたりの獲得XPに上限を設定できます。キャップを超えたXPは切り捨てられます。

• 日次上限: その日の0時からの合計獲得XPを制限
• 週次上限: 月曜0時からの合計獲得XPを制限
• 0を設定すると上限なし（デフォルト）

🚀 イベントブースト

特定の期間、XP獲得量に倍率を掛けられるイベント機能です。

• チャット倍率 / VC倍率を個別に設定
• 開始日時・終了日時を設定（期間限定ブースト）
• 期間外や無効時は倍率1.0x（通常状態）

🟢 有効期間

ランクシステムの計測自体を特定の期間だけ有効にできます。

• 開始日時のみ設定 → その日時以降のみ計測
• 終了日時のみ設定 → その日時までのみ計測
• 両方空欄 → 常時有効（デフォルト）
• 有効期間外は一切XPが付与されません

#️⃣ チャンネルフィルター

特定のチャンネル・カテゴリをXP計測の対象・除外に指定できます。 テキストCH（TC）とVCで独立して設定可能です。

フィルターはホワイトリスト（許可）と ブラックリスト（拒否）の2つを同時に設定できます。

テキストCH（TC）とVCでそれぞれ以下の4項目を設定できます：

• ✅ カテゴリWH（そのカテゴリ内の全CHが許可対象）
• ✅ チャンネルWH（個別のCHを許可対象）
• ❌ カテゴリBL（そのカテゴリ内の全CHを除外）
• ❌ チャンネルBL（個別のCHを除外）

📊 ランキング

/ランキング コマンドでサーバー内のXPランキングを表示できます。

• プリセット一覧がページネーションで表示される
• ✅ 選択ボタン → Modalで種別（全て/チャット/VC/インチャット）と期間（全期間/週間/月間）を設定
• 0XPのユーザーは表示されません
• 全期間の「全て」は chat_exp + inchat_exp + vc_exp の合計でソート

期間ランキング

• 週間: ISO週単位（月曜～日曜）。週替わりで自動リセット＆ログ出力（設定時）
• 月間: 暦月単位（1日～月末）。月替わりで自動リセット＆ログ出力（設定時）
• 集計値は chat_exp + inchat_exp + vc_exp のその場加算で算出（DBカラム参照ではない）

レベル・経験値の仕組み

成長テンプレート

4種類のテンプレートから選択できます。デフォルトは 🌱 スムーズ成長（初期が優しめ）です。

📈 成長曲線グラフ

各テンプレートの累積XP（Lv.1から各レベルに到達するまでの必要総XP）を比較したグラフです。

高度設定：カスタム数式

管理者は任意の数式で成長曲線を設計できます。テンプレートにない独自の曲線も自由に設定可能です。

使用可能な構文

設定例

# デフォルト（スムーズ成長）
5 * L ** 2 + 50 * L

# 序盤ハードル+スムーズ成長
5 * L ** 2 + 50 * L + 100

# 線形成長
30 * L + 20

# イベント向け
max(100, 50 * L ** 1.5)

# 超長期サーバー向け
200 * L ** 1.8

コマンド一覧

設定パネル項目一覧

/ランク設定 で開く設定パネルでは、 2つのSelectメニューとアクションボタンで設定を変更できます。
上のSelect: 追加機能のON/OFF（複数選択可）
下のSelect: 各項目の詳細設定
設定項目を選ぶとModalが開くか、直接値が切り替わります。

以下が設定可能な全項目です：

拡張機能設定

拡張機能は上のSelectメニューからON/OFFを切り替えます。 ONにすると下のSelectに詳細設定項目が出現します。

⭐ メイン設定

複数のプリセットを作成できるランクシステムでは、 メイン設定機能で /ランク コマンドの表示対象を1つに絞れます。

📋 ログ設定

ランクシステムの各イベントを特定のチャンネルにログ出力できます。 5つのカテゴリに分かれており、それぞれ個別に 出力先チャンネルを設定可能です。 設定されていないカテゴリはグローバル設定にフォールバックします。

ログカテゴリ一覧

設定方法

1. /ランク設定 を実行
2. プリセットのエディタを開く
3. 下のSelectで「📋 ログ機能設定」を選択
4. ログ設定Viewでカテゴリを選択 → Modal内でChannelSelect
5. 未設定のカテゴリはグローバルCHにフォールバック
6. 全て未設定の場合はログは出力されません

ランク表示の例

/ランク を実行すると、以下のような 画像式のランクカードが表示されます。 XP集計モードに応じてメーターの本数が変化します。

全体モード（combined・メーター1本）

VC/チャットモード（separate・メーター2本）

インチャットモード（inchat・メーター3本）

注意事項

• BotユーザーのメッセージはXP計測の対象外です
• 同じメッセージの連投はクールダウンで制限されます
• VCは2人以上で接続している場合のみXPが付与されます
• レベルアップ通知は設定したチャンネルに送信されます
• カスタム数式の結果が0以下になった場合、デフォルト式に戻ります
• XPキャップは日次リセット（0時）・週次リセット（月曜0時）でリセットされます
• CHフィルターはCH ID・カテゴリIDで指定します
• VC最小接続時間のデフォルトは1分です。1分未満のVC接続ではXPが付与されません。0に設定すると比例計算になります
• チャット/インチャット獲得ロールを設定すると、そのロールを持たないユーザーはXPを獲得できません
• ランキングではXPが0のユーザーは表示されません
• 期間ランキングの集計値はDBカラムではなく chat_exp + inchat_exp + vc_exp の加算で算出されます
• レベルは保存されず、全てXPからその場計算されます。数式を変更しても過去データとの整合性は保たれます