AGENT SKILL

unity-vivox

Vivox voice and text chat: channels, positional voice, mute and push-to-talk, mic permission.

License 许可
MIT
最近更新
2026-11-10
Stars
★ 2
Forks
0

01 前言 Front Matter

name
unity-vivox
description
Vivox voice and text chat: channels, positional voice, mute and push-to-talk, mic permission.

02 资源文件 7

03 SKILL.md 正文

unity-vivox — the await is the request, the event is the answer

Every asynchronous call on VivoxService.Instance completes when the request has been handed to the service, not when the thing you asked for happened. Login, channel join and message delivery all report their real outcome on an event. Code that treats the returned Task as the result compiles, runs, logs nothing, and ships a game in which no one can hear anyone. Subscribe first, call second, react in the handler.

Symptom → where to look

Symptom Go to
"Add voice chat to this game" reference/which-source-decides.md first — package present, which source decides — then §1, §2
The types do not resolve at all §1 — the package is absent
Second scene load throws 5041 §1 — the re-init guard
LoginAsync returned, LoggedIn never ran §4 — you subscribed after the call
Join awaited fine and nobody can hear anyone §2 — the await is not the join
Proximity (positional) or team voice; an eleventh channel or a 201st player fails with 20502 §2 — three joins, two ceilings
SendDirectedTextMessageAsync does not compile reference/text-tokens-permission.md §3 — the pair is spelled asymmetrically
In-game text chat or whispers; a directed message never arrives reference/text-tokens-permission.md §3, then reference/troubleshooting.md
Handlers fire on destroyed objects after a scene reload §4 — the unsubscribe rule
A mute button or push-to-talk mutes more, or less, than expected §5 — three different things are called mute
Where the access token comes from reference/text-tokens-permission.md §6
Works in the Editor, silent on a phone reference/text-tokens-permission.md §7 — permission is code
A one-shot reward fired twice §4 — reconnect re-fires LoggedIn
A speaking indicator; the participant roster §4, reference/events-and-participants.md
Old Client / ILoginSession / AccountId code no longer compiles below the table — v4 is gone; port it

VivoxService.Instance is the whole v16 surface: init, login, join, leave, send, mute. The v4 model — Client.Instance, ILoginSession, IChannelSession, AccountId, ChannelId — is gone, not deprecated. Code carrying those names is a port, not a fix.

1. Four calls, one order

com.unity.services.vivox >= 16.4.0 brings Unity.Services.Vivox and pulls in Core (com.unity.services.core) and Authentication (com.unity.services.authentication). Below that floor, part of the surface here is gone. Nothing resolves before it is installed — a compile failure naming a missing namespace, not a runtime error, so it sends people hunting a bad using.

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();

    VivoxService.Instance.LoggedIn += OnLoggedIn;   // before LoginAsync, always

    await VivoxService.Instance.LoginAsync(new LoginOptions { DisplayName = "Bob" });
}

Core → sign-in → Vivox init → Vivox login. Reordering produces silence or an error code that names something else, not a tidy error.

A second InitializeAsync() throws 5041 VxErrorAlreadyInitialized. The bootstrap MonoBehaviour on a scene that reloads will do exactly that. Either mark it DontDestroyOnLoad so Start runs once, or guard on IsInitialized.

Sign-in decides identity: the login binds to AuthenticationService.Instance.PlayerId, the id another client addresses a whisper to. Skip Authentication and you get a per-session GUID — display names still work, cross-session identity does not. Setup detail: reference/init-and-login.md.

2. Three joins, one event, two ceilings

Call Channel
JoinGroupChannelAsync(name, ChatCapability, ChannelOptions?) Non-positional — party, team, lobby, guild
JoinEchoChannelAsync(name, ChatCapability, ChannelOptions?) Echoes your own audio back; a test loop, not a feature
JoinPositionalChannelAsync(name, ChatCapability, Channel3DProperties, ChannelOptions?) 3D proximity voice driven by a transform

ChatCapability is TextOnly, AudioOnly or TextAndAudio, and it is fixed for the life of the join — a channel entered as TextOnly will never carry voice no matter what the mic does.

The join finishes on ChannelJoined(string channelName). The awaited Task says the request left the client. Bind the event first and do the "we are live" work in the handler; an await followed by roster or transmit code is the most common way this integration does nothing.

Two ceilings, both surfacing as 20502 VxXmppServerErrorServiceUnavailable, which names neither: 10 non-positional channels per user and 200 participants per channel. Leave before joining an eleventh; a positional channel that needs to exceed 200 is an enterprise Large 3D Channels setting, not a client change. Leaving is LeaveChannelAsync(name) or LeaveAllChannelsAsync(), and each exit fires ChannelLeft.

Channel3DProperties, the falloff models and the per-frame position update are in reference/voice-channels.md.

4. Events, and the unsubscribe that is not optional

Call Completion event Counterpart
LoginAsync() LoggedIn LoggedOut
any Join*ChannelAsync() ChannelJoined(string) ChannelLeft(string)
— (any joined channel) ParticipantAddedToChannel(VivoxParticipant) ParticipantRemovedFromChannel(VivoxParticipant)
a remote SendChannelTextMessageAsync() ChannelMessageReceived(VivoxMessage) ChannelMessageEdited / ChannelMessageDeleted
a remote SendDirectTextMessageAsync() DirectedMessageReceived(VivoxMessage) DirectedMessageEdited / DirectedMessageDeleted

VivoxService.Instance outlives your scene. A handler subscribed from a MonoBehaviour and never removed keeps the destroyed object in the singleton's invocation list: on the next scene load the event runs twice and one copy throws MissingReferenceException. Mirror every += with a -= in OnDestroy, and null-guard the service — it can be gone during quit.

Per-participant signals — mute state, speech detected, audio energy — are not on the service but on the VivoxParticipant that ParticipantAddedToChannel hands you; a roster row or speaking indicator binds there. Reconnection re-fires LoggedIn and ChannelJoined, so handlers must be idempotent — a first-login reward granted in one fires again. Those three names, and roster wiring: reference/events-and-participants.md.

5. Three things are called mute

Intent Where What it does
"Stop transmitting me" VivoxService.Instance.MuteInputDevice() / UnmuteInputDevice(), state on IsInputDeviceMuted Local capture stops; nobody in any channel hears you
"I don't want to hear that player" participant.MutePlayerLocally() / UnmutePlayerLocally() Client-side only; the other player is unaware and everyone else still hears them
"That player may not be heard by anyone" A privileged token minted on a server Moderation, not a client capability

The first pair is also push-to-talk: hold to unmute rather than joining and leaving a channel per key press.

3, 6–7. Text, access tokens, microphone permission → reference/text-tokens-permission.md

§3 channel and directed text — SendDirectTextMessageAsync out, DirectedMessageReceived in, to a PlayerId; §6 where tokens are minted and why no signing key sits in the client; §7 permission is code, not a manifest line — the runtime RECORD_AUDIO request and the iOS usage description.

Verification

Before calling an integration done, read the code for these — each fails quietly:

  1. It compiles, and using Unity.Services.Vivox; resolves.
  2. The order is Core init → sign-in → Vivox init → login, with nothing interleaved.
  3. No v4 names survive: no Client.Instance, AccountId, ChannelId, ILoginSession, IChannelSession. Everything goes through VivoxService.Instance.
  4. Every consumed event is subscribed before the call that triggers it, and unsubscribed in OnDestroy.
  5. Join code reacts in ChannelJoined rather than on the line after the await.
  6. The directed pair is SendDirectTextMessageAsync out, DirectedMessageReceived in, and the target is a PlayerId.
  7. Android requests RECORD_AUDIO at runtime before an audio-capable join; iOS has a non-empty microphone usage description.
  8. No Vivox signing key, app secret or issuer sits in client code or in a Resources asset.

Report which of the eight you checked by reading and which by running. Without Vivox credentials it is "read" all the way down, and saying so separates verified from merely compiling.

Scope — what this skill does NOT do

Microphone ownership, permission policy and mute authority are unity-live-services. When another feature captures audio (a sensing SDK that holds the microphone open, recording, speech input), adding voice breaks one of them; who owns the device and how the other is suspended is decided there, as are the store's microphone declaration, its review cost, and whether a mute may be a client decision. §5 only names the API.

Sessions, lobbies, matchmaking and relay are unity-multiplayer-services; the topology choice behind them is unity-live-services. Deriving a channel name from a session id belongs there.

Project, environment and sign-in setup is unity-ugs; credential handling and the offline path are unity-live-services. §1 assumes anonymous sign-in already works.

The manifest merge, permission read-back on a real APK and store listing are unity-android-release. §7 stops at the runtime request.

Voice activity detection and the volume APIs are not documented here — VAD thresholds, a mic input slider, per-participant or per-channel gain. They exist, and §5 stops at mute: enumerate them on the project's package and take docs.unity.com's Vivox section as the authority.

Mixer routing, ducking voice under music and the cost of an AudioSource are unity-audio; the chat UI — roster list, message log, CJK text — is unity-game-ui.

Reference

04 同仓库更多 Skills