在 Unity 多人游戏中接入 Vivox…

当需要为 Unity 多人游戏添加语音聊天、麦克风支持、语音设置 UI、静音、VAD、按键说话、空间语音、队伍/派对/大厅频道或游戏内文字聊天时，用 Unity Vivox v16+ 的 VivoxService.Instance 完成接入与配置。

适用场景

解决思路

1. 使用 Vivox v16+ 的统一静态入口 VivoxService.Instance 完成初始化、登录、加入频道、消息与静音等所有操作；不要使用 v4 的 Client.Instance、AccountId、ChannelId、ILoginSession、IChannelSession 等旧模式。
2. 严格按顺序初始化：先 await UnityServices.InitializeAsync()，再 await AuthenticationService.Instance.SignInAnonymouslyAsync()，再 await VivoxService.Instance.InitializeAsync()，最后 await VivoxService.Instance.LoginAsync(new LoginOptions { DisplayName = "Bob" })；顺序错误会静默失败或抛出难以理解的错误。
3. 避免重复初始化：VivoxService.Instance.InitializeAsync() 调用两次会抛出 5041 VxErrorAlreadyInitialized，在场景重载时要加保护。
4. 在调用 LoginAsync 之前先订阅事件（如 LoggedIn、LoggedOut）。
5. 加入频道时先订阅事件再调用异步方法，因为加入是通过 ChannelJoined 事件完成而不是 await 返回：非位置频道用 JoinGroupChannelAsync(name, ChatCapability, ChannelOptions?)，回声测试频道用 JoinEchoChannelAsync(name, ChatCapability, ChannelOptions?)，3D 空间音频用 JoinPositionalChannelAsync(name, ChatCapability, Channel3DProperties, ChannelOptions?)。
6. ChatCapability 取值使用 TextOnly、AudioOnly 或 TextAndAudio。
7. 注意频道限制：每个用户最多 10 个非位置频道，每个频道最多 200 名参与者；超出会返回 20502 VxXmppServerErrorServiceUnavailable；位置频道超过 200 人需使用 Large 3D channels 企业设置。
8. 离开频道用 VivoxService.Instance.LeaveChannelAsync(channelName) 或 LeaveAllChannelsAsync()。
9. 发送频道文字消息用 VivoxService.Instance.SendChannelTextMessageAsync(string channelName, string message)，接收订阅 VivoxService.Instance.ChannelMessageReceived（Action<VivoxMessage>）。
10. 发送定向消息用 VivoxService.Instance.SendDirectTextMessageAsync(string playerId, string message)（注意不是 SendDirectedTextMessageAsync），接收订阅 VivoxService.Instance.DirectedMessageReceived（Action<VivoxMessage>）。
11. 使用 VivoxMessage 字段：ChannelName（定向消息为 null）、SenderDisplayName、SenderPlayerId、MessageText、ReceivedTime、Language、FromSelf、MessageId。
12. 按需使用消息编辑/删除 API（EditChannelTextMessageAsync、DeleteChannelTextMessageAsync、EditDirectTextMessageAsync、DeleteDirectTextMessageAsync）和历史 API（GetChannelTextMessageHistoryAsync、GetDirectTextMessageHistoryAsync）；聊天历史默认保留 7 天。
13. 订阅必要事件：LoginAsync 对应 LoggedIn/LoggedOut；加入频道对应 ChannelJoined(string channelName)/ChannelLeft(string channelName)；参与者变化用 ParticipantAddedToChannel(VivoxParticipant)/ParticipantRemovedFromChannel(VivoxParticipant)；频道消息接收用 ChannelMessageReceived(VivoxMessage)；定向消息接收用 DirectedMessageReceived(VivoxMessage)。
14. 在 OnDestroy 或 OnDisable 中始终取消订阅事件，因为 VivoxService.Instance 是持久单例，已销毁的 MonoBehaviour 上的事件处理器会重复触发并在场景重载时出现空引用。
15. 每个参与者的事件（ParticipantMuteStateChanged、ParticipantSpeechDetected、ParticipantAudioEnergyChanged）挂在#从 ParticipantAddedToChannel 拿到的 VivoxParticipant 实例上，而不是 VivoxService.Instance 上。
16. 默认使用 UGS Authentication 自动生成访问令牌：只要 AuthenticationService.Instance.SignInAnonymouslyAsync()（或其他登录方式）完成，Vivox 就会从 UGS 项目自动铸造访问令牌，标准流程无需手写令牌代码。
17. 仅在非 UGS 身份系统或需要频道级特权令牌（踢人、全员静音、转录）时，才在服务端铸造 Vivox Access Token (VAT)；不要把 HMAC 签名密钥嵌入客户端。
18. Android 构建在加入音频频道前需在运行时请求 RECORD_AUDIO 权限；iOS 构建需在 plist 中加入 NSMicrophoneUsageDescription。
19. 实现语音设置 UI 时使用 VoiceVadMinimumVolume、麦克风滑块、静音按钮和说话指示器；按需实现按键说话、静音自己和他人、私聊/定向消息。
20. 实现邻近/3D 空间语音时使用 JoinPositionalChannelAsync 并配置 Channel3DProperties，由 transform 位置驱动空间音频。
21. 实现队伍/派对/大厅/公会语音频道时使用 JoinGroupChannelAsync 创建非位置频道。
22. 写完后验证：项目编译通过且 using Unity.Services.Vivox; 可解析；初始化顺序正确；无 v4 遗留模式；所有事件在触发它们的异步调用之前订阅并在 OnDestroy 取消订阅；加入频道代码不 await 加入调用而是订阅 ChannelJoined；定向消息发送用 SendDirectTextMessageAsync、接收用 DirectedMessageReceived；Android/iOS 权限已配置；客户端未嵌入 HMAC 密钥或 Vivox SECRET/APP_ID。
23. 需要签名、事件细节或平台注意事项时，按需阅读 references/init-and-login.md、references/voice-channels.md、references/text-chat.md、references/events-and-participants.md、references/troubleshooting.md；以 Unity Vivox 文档地图为权威，但不要向用户提及 llms.txt 文件名。

适用边界 · 注意事项

• 不使用 Unity Vivox 或未安装 com.unity.services.vivox >=16.4.0 的项目不适用。
• 仍在使用 Vivox v4 旧 API（Client.Instance、ILoginSession、IChannelSession）且不打算迁移的项目不适用。
• 需要非 UGS 身份系统或频道级特权令牌但无法提供服务端铸造 VAT 的环境，不能直接套用默认客户端流程。