unity-multiplayer-services
Sessions API: create/join, join codes, matchmaking, relay, host migration, dedicated servers.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- unity-multiplayer-services
- description
- Sessions API: create/join, join codes, matchmaking, relay, host migration, dedicated servers.
02 资源文件 6
- 参考文档reference/cloud-prerequisites.md2.9 KB
- 参考文档reference/dedicated-server-sessions.md4.1 KB
- 参考文档reference/lower-level-clients.md2.0 KB
- 参考文档reference/player-language.md2.0 KB
- 参考文档reference/requirement-dimensions.md3.5 KB
- 参考文档reference/session-api.md11.5 KB
03 SKILL.md 正文
unity-multiplayer-services — one session API, and the layers under it you should not reach for
MultiplayerService.InstanceandISessioncover the whole flow — create, find, join, connect, reconnect, migrate the host, tear down. Lobby, Matchmaker and Relay are what that flow is made of, not three products to assemble by hand. Code that drops to one of those clients directly takes on a second lifecycle to keep in step with the session's, and the composed calls that were doing that work for it stop being usable.
Symptom → where to look
| Symptom | Go to |
|---|---|
| "How do players get into a game together?" — create and join, join codes, quick join | §1, then reference/session-api.md |
"Should this use Lobby, or Relay, or Matchmaker?"; code reaching straight for Unity.Services.Lobbies / Matchmaker / Relay |
§2 — settle the requirement first; all three are below one API |
| Netcode for GameObjects on a session's network; players join, but nothing is networked | §3 — the network is a session option, not a second start call |
Two gameplay netcode packages in manifest.json |
§3 — pick one |
Server build breaks on Unity.Services.Multiplayer.Server types |
§5 |
| Ticket matchmaking into a playable match returns nothing — the queue was never deployed | §4 — the queue/environment does not exist yet |
| Players drain out of a running dedicated match and never refill | §5 backfill |
| A room / party / lobby list: filter and sort fields for a browsable game list | reference/session-api.md |
| Host migration | reference/session-api.md — Host migration |
| Reconnect after a phone loses signal | §1 ReconnectToSessionAsync, then unity-live-services → reference/multiplayer.md §2 |
| The plan reads like a services brochure | §6 |
| Something genuinely cannot be done through the session API | reference/lower-level-clients.md |
Authoritative source when specifics differ from recall: the Multiplayer Services SDK pages on
docs.unity.com. There is a curated index of those pages at
https://docs.unity.com/en-us/mps-sdk/llms.txt — fetch it first when you need to know what is
documented and where it lives, then read the page it points at. This skill stays the authority on
how to apply the SDK; the index is the authority on what exists.
The index is a tool, not a citation. Never put that filename in front of the user — not in a plan, a summary, or an explanation of where an answer came from. Cite the documentation page, or say "the Multiplayer Services documentation". A reader handed a machine-readable index file has been given a dead end dressed up as a source.
When both are unreachable, the copy of the package
resolved into the project decides — read the assemblies under Library/PackageCache/ or open the
package in Package Manager. Do not invent a signature from either. Check type names, signatures,
defaults and limits against the resolved package; when
PackageInfo.FindForAssetPath("Packages/com.unity.services.multiplayer/package.json") returns
null there is none, and Unity.Services.Multiplayer.MultiplayerService will not resolve.
1. The surface you implement against
MultiplayerService.Instance (static), or unityServices.GetMultiplayerService() from
UnityServicesExtensions once Unity Gaming Services is initialised and the player is
authenticated. Everything else hangs off it.
| Job | Call |
|---|---|
| Host a new game | CreateSessionAsync(SessionOptions) → IHostSession |
| Join by id, create it if absent | CreateOrJoinSessionAsync(id, SessionOptions) |
| Join by id / by join code | JoinSessionByIdAsync, JoinSessionByCodeAsync |
| Come back after a drop | ReconnectToSessionAsync(id, ReconnectSessionOptions) |
| Auto-pick or create by filter | MatchmakeSessionAsync(QuickJoinOptions, SessionOptions) |
| Ticketed matchmaking | MatchmakeSessionAsync(MatchmakerOptions, SessionOptions, CancellationToken) |
| Browse open games | QuerySessionsAsync(QuerySessionsOptions) |
| What am I already in | GetJoinedSessionIdsAsync() |
ISession is the handle afterwards: players, properties, role, Network, LeaveAsync,
ReconnectAsync, RefreshAsync, SaveCurrentPlayerDataAsync. Cast it to IHostSession when
this peer hosts, IServerSession on a dedicated server. Every async call above throws
SessionException; catch that and read its session error type rather than the message string.
Full property tables, defaults, limits, filter and sort enums, the network model and the editor
components: reference/session-api.md.
2. Ground the recommendation before making one
Read the project first, then ask one question, then recommend. The dimension that changes the answer — who runs the match, how players find each other, what happens when the host walks away — is usually already decided somewhere in the repo. Recommending before looking produces a plan that contradicts the manifest.
Order: what the user already said → what is in the project (Packages/manifest.json, existing
networking scripts, server build targets, deployment assets) → a short, high-level question, but
only for a dimension that would change the recommendation and is not visible in either.
The six dimensions and what each maps to internally are in
reference/requirement-dimensions.md.
3. Networking is a session option, not a second system
The gameplay network comes up as part of create / join / matchmake / reconnect when the options carry it. There is no separate "now start netcode" step on that path.
var options = new SessionOptions { MaxPlayers = 4 }.WithRelayNetwork();
var session = await MultiplayerService.Instance.CreateSessionAsync(options);
WithRelayNetwork()— brokered connectivity, the default choice when players sit behind home routers.WithDirectNetwork()— a listen/publish address you control.WithDistributedAuthorityNetwork(),WithNetworkHandler()for a customINetworkHandler,WithHostMigration(),WithPlayerName().- Session metadata alone needs no gameplay netcode package. Rooms, codes, lists and properties
work on
com.unity.services.multiplayerby itself. Add a netcode package only when a simulation has to be shared. - Exactly one gameplay stack. Netcode for GameObjects is
com.unity.netcode.gameobjects. Netcode for Entities iscom.unity.netcode;com.unity.netcode.entitiesis not a package id — the registry returns 404 for it. Do not put both stacks in one project, and do not introduce a stack the project did not already choose.
4. What must exist in the cloud before the code runs
Initialisation and authentication are required for every path — com.unity.services.core and
com.unity.services.authentication. Past that, each workflow has its own cloud-side
prerequisite, and the usual "matchmaking silently finds nothing" is a queue that was never
deployed. The table is
reference/cloud-prerequisites.md.
5. Dedicated servers are a separate assembly
Unity.Services.Multiplayer.Server compiles only when UNITY_SERVER or ENABLE_UCS_SERVER is
defined. So any assembly of yours that touches it must be excluded from client builds the same
way — #if UNITY_SERVER around the references, or defineConstraints: ["UNITY_SERVER"] in the
.asmdef. Skip that and the client build fails on types it was never meant to see.
Entry point is MultiplayerServerService.Instance / GetMultiplayerServerService() with three
create methods returning IServerSession — the supported way in, since GetSessionAsync may be
internal in the resolved package; backfill (WithBackfillingConfiguration,
StartBackfillingAsync, StopBackfillingAsync) is what refills a running allocation.
reference/dedicated-server-sessions.md.
6. Write plans in the player's language
The user answers questions about their game, not about the SDK. "Should players see a list of open games, or only join with a code?" is answerable. "Do you want Lobby or Sessions?" makes them learn the vendor's product split to describe their own game.
Keep product names out of questions, plans and summaries unless the user brought them up — then
mirror their wording and do not enumerate the rest. Code, file edits and technical references use
the real type and namespace names, always. Before/after phrasings:
reference/player-language.md.
7. Testing
Two builds, two devices, two networks. Two editor instances share a NAT, a clock and a disk;
they will not reproduce the failures this package exists to handle. com.unity.multiplayer.playmode
gives local virtual players for a first pass, not a substitute for the second device. Sessions,
matchmaking and relay need a live UGS project to run at all.
Scope — what this skill does NOT do
Choosing the topology at all — peer-to-peer versus a hosting player versus a fleet, who is allowed
to be believed, what a disconnect means for the match, and microphone conflicts — is
unity-live-services → reference/multiplayer.md. That decision comes first; this skill is what you call once
it is made. Voice and text chat are unity-vivox. Anything that has to outlive the session —
currency, unlocks, progression, leaderboards — is unity-ugs for the API and unity-live-services
for the discipline around it. Netcode's own call-by-call surface (NetworkBehaviour, RPCs,
NetworkVariable) is not here either: this skill hands the netcode stack a live connection and
stops. Server fleet operations stay with whoever runs the fleet.
Reference
reference/session-api.md—IMultiplayerServiceandISessionin full: signatures, options tables with defaults and limits, filter/sort enums, the session network model, host migration, errors, editor components.reference/requirement-dimensions.md— how to ground a recommendation, and the six dimensions that change it.reference/player-language.md— questions and explanations, before and after.reference/dedicated-server-sessions.md— the server assembly, its build constraints,IMultiplayerServerService, backfill.reference/cloud-prerequisites.md— packages and cloud setup per workflow.reference/lower-level-clients.md— the three lower-level clients, what each is for, and the two conditions that justify using one.
04 同仓库更多 Skills
unity-web-release
Ship a WebGL/WebGPU build: shrink the download, Brotli server headers, Safari and iPhone memory.
unity-vivox
Vivox voice and text chat: channels, positional voice, mute and push-to-talk, mic permission.
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.