feat: add the setup-multiplayer-services skill

README.md

@@ -24,6 +24,7 @@ npx skills add Unity-Technologies/skills
 | `ui-imgui` | IMGUI editor tooling — EditorWindows, custom Inspectors, PropertyDrawers |
 | `validate-urp-render-graph-renderer-feature` | Reviews a Unity 6+ URP `ScriptableRendererFeature` built on Render Graph |
 | `shader-graph-create-custom-node` | Custom Shader Graph nodes from HLSL |
+| `setup-multiplayer-services` | Multiplayer topology, sessions, lobbies, matchmaking, and discovery via Unity Multiplayer Services |
 
 ## Usage
 

skills/setup-multiplayer-services/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: setup-multiplayer-services
+description: >-
+  Guides the development of online multiplayer experiences where players connect, group, and interact in real-time using Unity Multiplayer Services.
+  Use when the user asks for topology choice, player grouping, hosting, matchmaking, discovery, network setup,
+  and session-based play (rooms, parties, lobbies) using the Unity Multiplayer Services APIs.
+---
+
+# Multiplayer SDK (Unity Multiplayer Services)
+
+## Instructions
+
+1. **Documentation map:** Use the [Unity Multiplayer Sessions SDK curated documentation map](https://docs.unity.com/en-us/mps-sdk/llms.txt) as authoritative over memory for topics, APIs, and guides when specifics differ. Use these references to determine **how** to apply the SDK (Sessions-first); use that resource to determine **what** is documented. **Never** mention the `llms.txt` filename to the user. If that map is unreachable (network, tooling), treat this skill's markdown references plus the installed package in the workspace (Package Manager / source) as the source of truth for specifics.
+
+2. **Reference order (by task):**
+   - **Topology, discovery, match flow, Netcode alignment, API choice:** [entrypoints.md](references/entrypoints.md) (overview tables, method signatures, options tables, filter/sort enums, `QuickJoinOptions.Timeout`, errors) → [implementation-fit.md](references/implementation-fit.md) → [examples.md](references/examples.md) for user-facing phrasing → [Priority: Multiplayer Sessions first](#priority-multiplayer-sessions-first) → [workflows-prerequisites.md](references/workflows-prerequisites.md) for extra depth.
+   - **Dedicated game server (`Unity.Services.Multiplayer.Server`):** [dgs-entrypoint.md](references/dgs-entrypoint.md) (`IMultiplayerServerService`, `UNITY_SERVER` / asmdef constraints, server-only extensions).
+   - **Lower-level service clients:** [underlying-services.md](references/underlying-services.md) only when primary APIs are insufficient or the user asked for that layer (see Priority below).
+
+## Priority: Multiplayer Sessions first
+
+When the task is **choosing** topology, discovery, match flow, or Netcode alignment—not only calling APIs—ground recommendations via [implementation-fit.md](references/implementation-fit.md) (conversation → project → short targeted questions).
+
+**Primary path:** Implement against **`Unity.Services.Multiplayer`** using **`IMultiplayerService` / `MultiplayerService.Instance`** and **`ISession`** (surface summary in [entrypoints.md](references/entrypoints.md)); keep composed flows consistent with `llms.txt`.
+
+**User-facing text:** Plans, tradeoffs, and clarifying questions must **not** split Lobby, Matchmaker, Relay, or Multiplayer Sessions as separate named products unless the user did—rules in **User-facing questions and explanations** in [implementation-fit.md](references/implementation-fit.md), samples in [examples.md](references/examples.md). Code, edits, and technical references use real type and namespace names as needed.
+
+**Underlying clients** (`Unity.Services.Lobbies`, `Unity.Services.Matchmaker`, `Unity.Services.Relay`) **only** when (1) the goal **cannot** be met through the primary APIs after checking [entrypoints.md](references/entrypoints.md), or (2) the user **explicitly** asked for those namespaces or products. Do **not** default implementations there.
+
+## Additional resources
+
+Read from this entrypoint only; links are one level under this skill folder (no `references/index.md` or README hub).
+
+- **[implementation-fit.md](references/implementation-fit.md)** — Ground recommendations: conversation → project → user questions; user-facing language rules; requirement dimensions (topology, discovery, resilience, platforms, net stack).
+- **[examples.md](references/examples.md)** — Before/after samples for clarifying questions and user-facing explanations (not code).
+- **[entrypoints.md](references/entrypoints.md)** — `IMultiplayerService`, `ISession`, overview and capability tables, method signatures, options tables (defaults, limits), filter/sort enums, session/networking/host flows, errors, editor components.
+- **[dgs-entrypoint.md](references/dgs-entrypoint.md)** — Dedicated server: `Unity.Services.Multiplayer.Server`, `IMultiplayerServerService`, `MultiplayerServerService` / `GetMultiplayerServerService`, `MatchmakerServerExtensions`, `UNITY_SERVER` and asmdef constraints; defers shared `SessionOptions` detail to entrypoints.
+- **[workflows-prerequisites.md](references/workflows-prerequisites.md)** — Package and cloud prerequisites by workflow (tables).
+- **[underlying-services.md](references/underlying-services.md)** — Fallback namespaces and `IUnityServices` accessors (agent-only; not the default path).

skills/setup-multiplayer-services/references/dgs-entrypoint.md

@@ -0,0 +1,79 @@
+## Table of Contents
+
+- [Overview](#overview)
+- [Build and assembly constraints](#build-and-assembly-constraints-unity_server)
+- [`IMultiplayerServerService` capabilities](#imultiplayerserverservice-capabilities)
+- [Method signatures](#method-signatures)
+- [Matchmaker server extensions](#matchmaker-server-extensions-matchmakerserverextensions)
+- [Session options (shared types)](#session-options-shared-types)
+- [Errors](#errors)
+
+## Overview
+
+Dedicated Game Server (DGS) session entrypoints live in the **`Unity.Services.Multiplayer.Server`** assembly only. They complement the client **`IMultiplayerService`** surface documented in **`entrypoints.md`**.
+
+| Topic | Details |
+|--------|---------|
+| **Assembly** | **`Unity.Services.Multiplayer.Server`** |
+| **Service access** | **`MultiplayerServerService.Instance`** (static) or **`unityServices.GetMultiplayerServerService()`** via **`Unity.Services.Core.UnityServicesExtensions`** after Services initialization on a server build. |
+| **Core type** | **`IMultiplayerServerService`** — create and resolve **server** sessions; async methods return **`IServerSession`** (session handle for dedicated server; types from the main **`Unity.Services.Multiplayer`** assembly). |
+
+## Build and assembly constraints (`UNITY_SERVER`)
+
+The **`Unity.Services.Multiplayer.Server`** assembly is compiled only when **`UNITY_SERVER`** or **`ENABLE_UCS_SERVER`** is defined (see the package **`Unity.Services.Multiplayer.Server.asmdef`** **`defineConstraints`**).
+
+Any **game or tool code** that references **`Unity.Services.Multiplayer.Server`** must satisfy one of the following:
+
+| Approach | What to do |
+|----------|------------|
+| **Scripting define** | Wrap references (types, calls, `using` that pulls server-only APIs) in **`#if UNITY_SERVER`** … **`#endif`** (or a define that implies the same server build), so non-server targets do not compile that code. |
+| **Assembly Definition** | In the **`.asmdef`** of the assembly that references **`Unity.Services.Multiplayer.Server`**, set **`defineConstraints`** to include **`UNITY_SERVER`** so the dependent assembly is not built for client-only targets. |
+
+Use one or both so client/player builds never require the Server assembly to be present or linked incorrectly.
+
+## `IMultiplayerServerService` capabilities
+
+| Area | What to use |
+|------|-------------|
+| **Create session** | **`CreateSessionAsync(SessionOptions)`** — new server session from options. |
+| **Create or join by id** | **`CreateSessionAsync(string sessionId, SessionOptions)`** — server session with a chosen session id (create if missing, join if present per SDK behavior). |
+| **Create from matchmaker** | **`CreateMatchSessionAsync(string matchId, SessionOptions)`** — server session tied to a Matchmaker match id; uses matchmaker configuration on options when applicable. |
+
+> **`GetSessionAsync`** exists on **`IMultiplayerServerService`** for package-internal use and is **`internal`** in the SDK source; treat the three **`Create*`** methods above as the supported public server entry surface for session creation from game code.
+
+## Method signatures
+
+```csharp
+// Creates a new dedicated-server session. Returns IServerSession. Throws SessionException on failure.
+Task<IServerSession> CreateSessionAsync(SessionOptions sessionOptions)
+
+// Creates or joins a server session using an explicit session id.
+Task<IServerSession> CreateSessionAsync(string sessionId, SessionOptions sessionOptions)
+
+// Creates a server session from a Matchmaker match id and session options.
+Task<IServerSession> CreateMatchSessionAsync(string matchId, SessionOptions sessionOptions)
+```
+
+## Matchmaker server extensions (`MatchmakerServerExtensions`)
+
+All members below are declared in **`Unity.Services.Multiplayer.Server`** (`MatchmakerServerExtensions`).
+
+```csharp
+// Configure backfill behavior on SessionOptions before create/match session.
+T WithBackfillingConfiguration<T>(this T options, bool enable, bool automaticallyRemovePlayers,
+    bool autoStart, int playerConnectionTimeout, int backfillingLoopInterval) where T : SessionOptions
+
+// Start backfilling on a matchmade session (server / session handle).
+Task StartBackfillingAsync(this ISession session)
+
+// Stop backfilling on a matchmade session.
+Task StopBackfillingAsync(this ISession session)
+```
+
+## Session options (shared types)
+
+**`SessionOptions`** and related lobby/network fields are defined in **`Unity.Services.Multiplayer`**, not in the Server assembly. For property tables, fluent **`SessionOptionsExtensions`**, and networking helpers, use **`entrypoints.md`** — apply the same options when calling **`IMultiplayerServerService`** create APIs on dedicated servers.
+
+## Errors
+
+Async methods on **`IMultiplayerServerService`** throw **`SessionException`** on failure (same family as the client **`IMultiplayerService`** session APIs).