diff options
| author | Sho Sakuma <me@m1sk9.dev> | 2026-04-05 01:18:10 +0900 |
|---|---|---|
| committer | Sho Sakuma <me@m1sk9.dev> | 2026-04-05 01:18:10 +0900 |
| commit | 6e96b5de6ef49140a49eb0bd9cbd4b9fa541a2cb (patch) | |
| tree | afafd4444f8f7b89418182705dfe5de69a4b9868 /website/src/docs/features/velocity.md | |
| parent | 842bf9df75a5e23ab31bdfb5717b76449264e999 (diff) | |
| download | LunaticChat-6e96b5de6ef49140a49eb0bd9cbd4b9fa541a2cb.tar.gz LunaticChat-6e96b5de6ef49140a49eb0bd9cbd4b9fa541a2cb.tar.bz2 LunaticChat-6e96b5de6ef49140a49eb0bd9cbd4b9fa541a2cb.zip | |
docs(website): add v1 documentation pages and fix dark theme
Add 12 documentation pages covering configuration, permissions,
features (DM, channel chat, romaji conversion, Velocity integration,
message logging, admin), and reference (commands, message format,
player settings). Restructure sidebar for new docs layout.
Fix dark theme rendering caused by :global(.dark) in DownloadCard.vue
applying filter:invert(1) to html element. Fix download button colors
for dark mode. Add protocol version compatibility notice to download
page. Move favicon.ico to correct public directory.
Co-Authored-By: Claude <noreply@anthropic.com>
Diffstat (limited to 'website/src/docs/features/velocity.md')
| -rw-r--r-- | website/src/docs/features/velocity.md | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/website/src/docs/features/velocity.md b/website/src/docs/features/velocity.md new file mode 100644 index 0000000..d1394ec --- /dev/null +++ b/website/src/docs/features/velocity.md @@ -0,0 +1,109 @@ +--- +layout: doc +--- + +# Velocity 連携 + +Velocity プロキシを経由して複数の Paper / Folia サーバー間でグローバルチャットをリレーします. + +## セットアップ + +### 1. Velocity プラグインの導入 + +`LunaticChat-<version>-velocity.jar` を Velocity の `plugins/` ディレクトリに配置し,プロキシを再起動します. + +### 2. Paper 側の設定 + +各 Paper サーバーの `config.yml` で以下を設定します. + +```yaml +features: + velocityIntegration: + enabled: true + crossServerGlobalChat: true + serverName: "survival" # Velocity 設定のサーバー名に合わせる +``` + +### 3. 接続の確認 + +``` +/lcv status +``` + +接続状態,プロトコルバージョン,Velocity プラグインのバージョンなどを確認できます (パーミッション: `lunaticchat.command.lcv.status`, デフォルト: op) . + +## クロスサーバーグローバルチャット + +`crossServerGlobalChat` を `true` にすると,プレイヤーのチャットメッセージが Velocity を経由して他のすべての Paper サーバーに中継されます. + +### メッセージの流れ + +1. プレイヤーがチャットメッセージを送信 +2. Paper サーバーがメッセージを Velocity に送信 +3. Velocity が送信元以外の全サーバーにメッセージを中継 +4. 各サーバーのプレイヤーにメッセージが表示される + +### メッセージ重複排除 + +各メッセージに一意な ID が付与され,キャッシュにより同じメッセージが重複して表示されることを防ぎます.キャッシュサイズは `messageDeduplicationCacheSize` (デフォルト: `100`) で設定できます. + +## プロトコルバージョン + +Paper と Velocity 間の互換性はプロトコルバージョンで管理されます.接続時にハンドシェイクが行われ,互換性のないバージョン同士では接続が拒否されます. + +### バージョンバンプルール + +| レベル | 変更例 | 互換性 | デプロイ順序 | +|--------|--------|--------|-------------| +| PATCH (1.0.0 → 1.0.1) | optional フィールド追加,新 sub-channel 追加 | 完全互換 (`ignoreUnknownKeys=true` で安全) | 順不同,いつでも | +| MINOR (1.0.x → 1.1.0) | required フィールド追加,既存 sub-channel のセマンティクス変更 | `MIN_SUPPORTED_MINOR` の範囲内で後方互換 | **Velocity を先に更新** → 各 Paper を順次更新 | +| MAJOR (1.x.x → 2.0.0) | ワイヤフォーマット変更,sub-channel 削除/リネーム | 非互換 | **全サーバー同時デプロイ** | + +### 互換性判定 + +ハンドシェイク時に以下のルールで互換性が判定されます: + +- **MAJOR** が一致すること +- リモートの **MINOR** が `MIN_SUPPORTED_MINOR` 以上かつ自身の MINOR 以下であること +- **PATCH** は互換性判定に影響しない + +#### 例: Velocity がプロトコル 1.2.0 で `MIN_SUPPORTED_MINOR=1` の場合 + +| Paper プロトコル | 結果 | +|-----------------|------| +| 1.1.x | 接続 OK | +| 1.2.x | 接続 OK | +| 1.0.x | 拒否 (`MIN_SUPPORTED_MINOR` より古い) | +| 1.3.x | 拒否 (Velocity より新しい) | +| 2.0.x | 拒否 (MAJOR 不一致) | + +### 運用サイクル + +1. **プロトコル変更なし** → Paper / Velocity を独立にデプロイ可能 +2. **PATCH 変更** → どちら側からでも自由にデプロイ +3. **MINOR 変更** → Velocity を先行更新し,`MIN_SUPPORTED_MINOR` で旧 Paper の猶予期間を設定.全 Paper 更新後に `MIN_SUPPORTED_MINOR` を引き上げ +4. **MAJOR 変更** → メンテナンスウィンドウで一括更新 + +## 接続状態 + +| 状態 | 説明 | +|------|------| +| `DISCONNECTED` | 未接続 | +| `HANDSHAKING` | ハンドシェイク中 | +| `CONNECTED` | 接続済み | +| `FAILED` | 接続失敗 | + +ハンドシェイクのタイムアウトは5秒です.タイムアウトした場合,状態は `FAILED` になります. + +## 設定一覧 + +| 設定キー | デフォルト | 説明 | +|----------|-----------|------| +| `enabled` | `false` | Velocity 連携を有効にする | +| `crossServerGlobalChat` | `false` | クロスサーバーグローバルチャットを有効にする | +| `serverName` | `"Unknown"` | クロスサーバーチャットで表示されるサーバー名 | +| `messageDeduplicationCacheSize` | `100` | メッセージ重複排除キャッシュのサイズ | + +## メッセージフォーマット + +クロスサーバーチャットの表示形式は `config.yml` の `messageFormat.crossServerGlobalChatFormat` でカスタマイズできます.詳細は[メッセージフォーマット](/docs/reference/message-format)を参照してください. |
