setup-vivox-voice-chat

Unity Vivox — ボイス＆テキストチャット

名前空間：Unity.Services.Vivox | パッケージ：com.unity.services.vivox 関連パッケージ：Unity.Services.Core、Unity.Services.Authentication

Vivox v16 以降では、v4 の Client / ILoginSession / IChannelSession モデルが、単一の静的エントリーポイント VivoxService.Instance に置き換えられました。初期化、ログイン、チャンネル参加、メッセージ送信、ミュートなど、すべての操作をここから行います。v4 のパターン（Client.Instance、AccountId、ChannelId、ILoginSession、UnityPurchasing.* など）は使用しないでください。これらは v16 では廃止されています。

ドキュメントマップ

トピック、API、エラーコードの詳細が異なる場合は、記憶よりも Unity Vivox の厳選ドキュメントマップ を正式な情報源として使用してください。このスキルとそのリファレンスでは SDK の適用方法を、ドキュメントマップでは何が記載されているかを確認できます。ファイル名 llms.txt をユーザーに伝えてはいけません。アクセスできない場合は、このスキルのリファレンスとワークスペースにインストールされたパッケージ（Package Manager／ソース）を正式な情報源として扱ってください。

詳細なリファレンス

シグネチャ、イベントの詳細、このファイルに記載されていないプラットフォーム固有の注意点が必要な場合にのみ、必要に応じて参照してください。

• 初期化、サインイン、アクセストークン： references/init-and-login.md
• ボイスチャンネル（位置ベース／位置ベースではないチャンネル）： references/voice-channels.md
• テキストチャット（チャンネルメッセージと個別メッセージ）： references/text-chat.md
• イベント、参加者、クリーンアップ： references/events-and-participants.md
• トラブルシューティングとプラットフォームに関する注意点： references/troubleshooting.md

初期化の順序（手順を省略しないでください）

正しい順序は UGS Core → Authentication のサインイン → Vivox の初期化 → Vivox へのログイン です。順序を省略または変更すると、エラーが表示されないまま失敗したり、分かりにくいエラーが発生したりします。

using Unity.Services.Core;
using Unity.Services.Authentication;
using Unity.Services.Vivox;

async void Start()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();
    await VivoxService.Instance.InitializeAsync();
    // subscribe to events (see table below) BEFORE calling LoginAsync
    await VivoxService.Instance.LoginAsync(new LoginOptions { DisplayName = "Bob" });
}

• VivoxService.Instance.InitializeAsync() を 2 回呼び出すと、5041 VxErrorAlreadyInitialized がスローされます。シーンの再読み込み時に再初期化されないようにしてください。
• Unity Authentication（AuthenticationService）を使用しない場合、プレイヤー ID はセッションごとの GUID にフォールバックします。表示名は引き続き使用できますが、セッション間での同一性は維持できません。Vivox Access Token（VAT）を使う方法については、references/init-and-login.md を参照してください。

チャンネルへの参加

Vivox には、チャンネルの種類ごとに 1 つずつ、3 種類の参加メソッドがあります。いずれも非同期ですが、参加は呼び出しを await した時点ではなく、ChannelJoined イベントを通じて完了します。先にイベントを購読してから呼び出してください。

メソッド	用途
VivoxService.Instance.JoinGroupChannelAsync(name, ChatCapability, ChannelOptions?)	位置ベースではないチャンネル（パーティー、チーム、ロビー、ギルド）
VivoxService.Instance.JoinEchoChannelAsync(name, ChatCapability, ChannelOptions?)	自分の音声を送り返すテストチャンネル
VivoxService.Instance.JoinPositionalChannelAsync(name, ChatCapability, Channel3DProperties, ChannelOptions?)	Transform の位置に基づく 3D 空間オーディオ

ChatCapability の値：TextOnly、AudioOnly、TextAndAudio。

上限： ユーザーごとに参加できる位置ベースではないチャンネルは最大 10 個、チャンネルごとの参加者は最大 200 人です。どちらかを超えると、20502 VxXmppServerErrorServiceUnavailable で失敗します。位置ベースのチャンネルで 200 人を超える場合は、エンタープライズ設定の Large 3D channels を使用してください。

VivoxService.Instance.LeaveChannelAsync(channelName) または LeaveAllChannelsAsync() でチャンネルから退出します。Channel3DProperties のフィールドや、Android／iOS でのマイク権限の扱いについては、references/voice-channels.md を参照してください。

テキストメッセージ

チャンネルメッセージ（TextOnly または TextAndAudio を使用して、チャンネルのすべての参加者にブロードキャストします）：

• 送信：VivoxService.Instance.SendChannelTextMessageAsync(string channelName, string message)
• 受信：VivoxService.Instance.ChannelMessageReceived（Action<VivoxMessage>）を購読します

ダイレクトメッセージ（ピアツーピア、チャンネルは不要です）：

• 送信：VivoxService.Instance.SendDirectTextMessageAsync(string playerId, string message)
• 受信：VivoxService.Instance.DirectedMessageReceived（Action<VivoxMessage>）を購読します

よくある誤り： 送信メソッドは SendDirectTextMessageAsync であり、SendDirectedTextMessageAsync ではありません。ただし、イベント名は DirectedMessageReceived です。この非対称性に注意してください。

VivoxMessage のフィールド：ChannelName（ダイレクトメッセージの場合は null）、SenderDisplayName、SenderPlayerId、MessageText、ReceivedTime、Language、FromSelf、MessageId。

編集／削除 API（EditChannelTextMessageAsync、DeleteChannelTextMessageAsync、EditDirectTextMessageAsync、DeleteDirectTextMessageAsync）と履歴（GetChannelTextMessageHistoryAsync、GetDirectTextMessageHistoryAsync）については、references/text-chat.md を参照してください。チャット履歴の保持期間は、デフォルトで 7 日間です。

必須のイベント購読

対応する非同期呼び出しを行う前にイベントを購読してください。再接続時には LoggedIn がすぐに発生することがあり、ChannelJoined は参加処理の完了時に発生します。

呼び出し	成功イベント	失敗／対となるイベント
LoginAsync()	LoggedIn	LoggedOut
JoinGroupChannelAsync() / JoinEchoChannelAsync() / JoinPositionalChannelAsync()	ChannelJoined(string channelName)	ChannelLeft(string channelName)
—（参加済みの任意のチャンネル）	ParticipantAddedToChannel(VivoxParticipant)	ParticipantRemovedFromChannel(VivoxParticipant)
SendChannelTextMessageAsync()（リモートで受信）	ChannelMessageReceived(VivoxMessage)	—
SendDirectTextMessageAsync()（リモートで受信）	DirectedMessageReceived(VivoxMessage)	—

OnDestroy / OnDisable では必ず購読を解除してください。 VivoxService.Instance は永続的なシングルトンです。破棄された MonoBehaviour に登録されたイベントハンドラーは、シーンの再読み込み時に二重に発火し、NRE が発生します。

参加者ごとのイベント（ParticipantMuteStateChanged、ParticipantSpeechDetected、ParticipantAudioEnergyChanged）は、VivoxService.Instance ではなく、ParticipantAddedToChannel から受け取る VivoxParticipant インスタンスにあります。references/events-and-participants.md を参照してください。

アクセストークン（概要）

デフォルトでは UGS Authentication を使用します。AuthenticationService.Instance.SignInAnonymouslyAsync()（または別のサインインメソッド）が完了すると、Vivox は UGS プロジェクトからアクセストークンを自動的に発行します。標準的なフローでは、手動でトークンを扱うコードは不要です。

サーバー側で Vivox Access Token（VAT）を発行する必要があるのは、UGS 以外の ID システムを使用する場合、またはチャンネル単位の特権トークン（キック、全員のミュート、文字起こし）が必要な場合のみです。言語別のサーバー例については、ドキュメントマップの「Access Token Developer Guide」セクションを参照してください。HMAC 署名キーをクライアントに埋め込まないでください。

検証

このパッケージを使用するコードを記述した後、次の点を確認してください。

1. プロジェクトがエラーなくコンパイルされ、using Unity.Services.Vivox; が解決されることを確認してください。
2. 初期化の順序が次のとおりであることを確認してください。UnityServices.InitializeAsync → AuthenticationService.Instance.SignInAnonymouslyAsync → VivoxService.Instance.InitializeAsync → VivoxService.Instance.LoginAsync。
3. v4 のレガシーパターンがないことを確認してください。Client.Instance、AccountId、ChannelId、ILoginSession、IChannelSession は使用しないでください。すべてのアクセスは VivoxService.Instance 経由で行ってください。
4. コードで使用するすべてのイベントは、それをトリガーする非同期呼び出しの前に登録し、OnDestroy で登録解除してください。
5. チャンネル参加のコードでは、参加が完了するかのように参加呼び出しを await しないでください。代わりに ChannelJoined を登録し、そのイベント内で処理してください。
6. ダイレクトメッセージの送信には SendDirectTextMessageAsync を使用してください（SendDirectedTextMessageAsync ではありません）。ダイレクトメッセージの受信には DirectedMessageReceived を使用してください。
7. Android ビルドでは、音声チャンネルに参加する前に実行時に RECORD_AUDIO を要求してください。iOS ビルドでは、plist に NSMicrophoneUsageDescription が含まれていることを確認してください。
8. HMAC 署名キーや Vivox の SECRET／APP_ID をクライアントコードに埋め込まないでください。VAT ベースのフローは文書化されていますが、サーバーに委任してください。