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
- 参考文档reference/events-and-participants.md4.0 KB
- 参考文档reference/init-and-login.md4.7 KB
- 参考文档reference/text-chat.md4.2 KB
- 参考文档reference/text-tokens-permission.md3.2 KB
- 参考文档reference/troubleshooting.md4.5 KB
- 参考文档reference/voice-channels.md5.1 KB
- 参考文档reference/which-source-decides.md1.2 KB
03 SKILL.md 正文
unity-vivox — the await is the request, the event is the answer
Every asynchronous call on
VivoxService.Instancecompletes 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 returnedTaskas 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()throws5041 VxErrorAlreadyInitialized. The bootstrapMonoBehaviouron a scene that reloads will do exactly that. Either mark itDontDestroyOnLoadsoStartruns once, or guard onIsInitialized.
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 awaitedTasksays the request left the client. Bind the event first and do the "we are live" work in the handler; anawaitfollowed 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.Instanceoutlives your scene. A handler subscribed from aMonoBehaviourand never removed keeps the destroyed object in the singleton's invocation list: on the next scene load the event runs twice and one copy throwsMissingReferenceException. Mirror every+=with a-=inOnDestroy, 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:
- It compiles, and
using Unity.Services.Vivox;resolves. - The order is Core init → sign-in → Vivox init → login, with nothing interleaved.
- No v4 names survive: no
Client.Instance,AccountId,ChannelId,ILoginSession,IChannelSession. Everything goes throughVivoxService.Instance. - Every consumed event is subscribed before the call that triggers it, and unsubscribed in
OnDestroy. - Join code reacts in
ChannelJoinedrather than on the line after theawait. - The directed pair is
SendDirectTextMessageAsyncout,DirectedMessageReceivedin, and the target is aPlayerId. - Android requests
RECORD_AUDIOat runtime before an audio-capable join; iOS has a non-empty microphone usage description. - No Vivox signing key, app secret or issuer sits in client code or in a
Resourcesasset.
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
reference/text-tokens-permission.md— §3, §6, §7 ·reference/which-source-decides.mdreference/init-and-login.md— bootstrap,LoginOptions, logout, re-init guard, server tokensreference/voice-channels.md— joins,Channel3DProperties, positional updates, mutereference/text-chat.md— message fields, history, edit and delete, rate limitingreference/events-and-participants.md— events,VivoxParticipant, roster, cleanupreference/troubleshooting.md— error codes, platform notes, the diagnostic ladder
04 同仓库更多 Skills
unity-web-release
Ship a WebGL/WebGPU build: shrink the download, Brotli server headers, Safari and iPhone memory.
unity-urp-migration
Migrate a Built-in project to URP, or fix a half-moved one: pink materials, PPv2, old shaders.
unity-ui-ugui
Canvas UI (uGUI): CanvasScaler, RectTransform anchors, Layout Groups, ScrollView, UI built from C#.
unity-ui-toolkit
UI Toolkit (UXML, USS, UIDocument): flex layout, binding, custom elements, editor windows.
unity-ugs
Unity Gaming Services API: which package, init and sign-in order, Cloud Save, Cloud Code, Remote Config.
unity-tilemap
Tile Palettes for rect, hex and iso grids, rule tiles, autotiling from a terrain sheet.