Document MultiplayerSettings.json samples and fields#211
Merged
Conversation
Agent-Logs-Url: https://github.com/PlayFab/MpsAgent/sessions/99d20b59-5a6c-4ac4-bcb2-2e06f0ada1f8 Co-authored-by: dgkanatsios <[email protected]>
Copilot created this pull request from a session on behalf of
dgkanatsios
May 4, 2026 01:44
View session
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds in-repo documentation for LocalMultiplayerAgent configuration samples so developers can choose an appropriate MultiplayerSettings.json starter file and understand the schema without reverse-engineering the config classes. It fits the codebase by documenting the LocalMultiplayerAgent configuration surface and making existing samples discoverable from the main READMEs.
Changes:
- Added a new
LocalMultiplayerAgent/Samples/README.mdwith sample-selection guidance and a field-by-fieldMultiplayerSettings.jsonreference. - Added discoverability links to the new samples/config reference from the repo root README and the LocalMultiplayerAgent README.
- Consolidated platform/mode guidance for Windows, Linux, and macOS sample configurations into one entry point.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
README.md |
Adds a top-level link to the new LocalMultiplayerAgent samples/config reference. |
LocalMultiplayerAgent/readme.md |
Points LocalMultiplayerAgent users to the new samples README for schema guidance. |
LocalMultiplayerAgent/Samples/README.md |
Introduces sample selection guidance and detailed MultiplayerSettings.json field documentation. |
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
…mprove readability Round-2 multi-agent review surfaced 4 important issues + several nits. This commit addresses all of them and adds developer-readability improvements. Technical fixes: - PortMappingsList: type was wrong (PortMapping[][] vs actual List<List<PortMapping>> in MultiplayerSettings.cs). - DeploymentMetadata: type was wrong (Dictionary<string,string> vs actual IDictionary<string,string>). - SessionConfig.InitialPlayers: type was wrong (string[] vs actual List<string> in AgentInterfaces/SessionConfig.cs). - ForcePullContainerImageFromRegistry: clarify that LMA always pulls for Windows container runs regardless of the flag (per MultiplayerServerManager.cs:68-73). - Region: validator uses IsNullOrWhiteSpace, so the doc now says "non-empty, non-whitespace" rather than just "non-empty". - TitleId / BuildId: simplify the contradictory "yes (validation) / may be left empty" wording to "no (auto-generated)" matching SetDefaultsIfNotSpecified. - ImageDetails.Registry: note it's effectively required when ForcePull* is true and the image isn't on Docker Hub. Coverage gaps: - Added Windows-containers-on-Windows row to the sample matrix (the default MultiplayerSettings.json already supports this scenario by flipping RunContainer to true; the validator path at MultiplayerSettingsValidator.cs:170-176 enforces it). - Added a "Container mode with separate game assets" subsection to "What you typically need to edit" covering AssetDetails, MountPath, and the StartGameCommand-must-contain-MountPath validator rule. - Added a "Common pitfalls" section covering: OutputFolder must exist (LCOW sample sets a non-default path), AgentListeningPort firewall setup, Windows-container forced pulls, StartGameCommand mount-path requirement, macOS no-process-mode, and placeholder-value validation. Readability: - Added a Contents (table of contents) section with anchor links to each major heading and subsection. - Replaced the bullet-list "what to edit" with three jsonc snippets (container, container-with-assets, process) so developers see the actual JSON shape they need to copy. Co-authored-by: Copilot <[email protected]>
…ehavior Addresses round-2 multi-agent review findings (4 agents, 4 models): Readability (developer ergonomics): - Add Quickstart section at top with launch commands for Windows/Linux/macOS - Trim TOC to top-level + 3 'what to edit' subsections - Move Common pitfalls section above Field reference so first-run gotchas are seen before users hit them - Split the 21-row Top-level field table into 5 thematic mini-tables (Runtime mode / Heartbeat & maintenance / Identity / Game-server config / Image-pull behavior) for scannability - Frame the JSON snippets as 'patches' over the sample file and clarify that // comments must be stripped before saving - Replace inline /* ... */ placeholder with explicit '// use the ImageDetails block from the previous snippet' for less-ambiguous copy-paste - Make the process-mode snippet Windows-primary with inline Linux variant - Merge the two duplicate default-MultiplayerSettings.json picker rows Correctness (additional LMA behavior to document): - Note LMA only runs PortMappingsList[0]; additional inner lists are ignored - Note AssetDetails MountPath should be unique across entries (not validated) - Add LegacyAllocationInfo row to SessionConfig table - State that LMA only consumes AssetDetail.LocalFilePath/MountPath, not SasTokens/DownloadUris (which the production MPS service supports) - Mention the production MPS 30-entry cap on DeploymentMetadata - Split the placeholder pitfall: <your_game_server_exe> is rejected by name; <path_to_game_server_package> fails the regular file-existence check with a generic 'file not found' message Co-authored-by: Copilot <[email protected]>
Add Prerequisites section (Docker per scenario, .NET 8 SDK + dotnet publish commands, setup scripts incl. SetupLinuxContainersOnWindows.ps1). Snippet 1 (now: 'Container mode (image and ports)'): explicitly scope it to Linux containers with game baked into image; add 'Image-pull behavior at a glance' table and a Private-registries note covering the lack of ACR-specific auth modes. Snippet 2: inline a complete ImageDetails block (was an empty placeholder that would resolve to ':latest' and fail), add explicit 'RunContainer: true', and call out that Windows containers cannot bake the game into the image. Field reference fixes verified against source: GamePort.Number is unvalidated for process mode; SessionId only auto-generates when SessionConfig is omitted; PortMappingsList inner-list 'validation' is container-mode only; soften top-level grouping ordering claim; soften Username/Password log-redaction claim; nuance RunContainer 'Required'. Pitfalls: clarify that the placeholder substring check catches both <your_game_server_exe> and <your_game_server_executable_with_arguments>; add Local-image / docker-build pitfall for the macOS sample shipping with ForcePullContainerImageFromRegistry: true; add LCOW SetupLinuxContainersOnWindows.ps1 note alongside firewall guidance; add explicit '// comments are illustrative' pitfall. Anchor fix: rename heading away from em-dash to keep slug single-hyphenated. Co-authored-by: Copilot <[email protected]>
dgkanatsios
approved these changes
May 4, 2026
jotavalenciano
approved these changes
May 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The four sample
MultiplayerSettings.jsonfiles underLocalMultiplayerAgent/Samples/had no accompanying explanation, and the schema itself was only documented externally on Microsoft Learn — leaving users to reverse-engineer field semantics fromMultiplayerSettings.csandMultiplayerSettingsValidator.cs.Changes
LocalMultiplayerAgent/Samples/README.md../MultiplayerSettings.jsoncovers the Windows-process-on-Windows case and that LCOW requires the-lcowlaunch flag.AssetDetails,PortMappingsList,ContainerStartParameters(incl.ImageDetails,ResourceLimits),ProcessStartParameters,SessionConfig, andGameCertificateDetails. Each row notes type, required-ness, and validation rules drawn directly from the config and validator classes.GameServerEnvironmentis inferred (not a JSON field),MountPathis ignored in process mode,PublicPortdefaults toNodePortlocally,AssetDetailsis optional for Linux containers, andStartGameCommandis optional for Linux containers but required elsewhere.README.mdandLocalMultiplayerAgent/readme.mdso the new doc is discoverable alongsideSettingsJsonGeneratorandBuildTool.Scope is intentionally limited to documenting current behavior — no code, samples, or validator logic changed. The samples README links out to Microsoft Learn for the end-to-end walkthrough rather than duplicating it.