diff options
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)を参照してください． |