Gamer Services & Avatars
Offline first, server optional. CNA implements XNA’s GamerServices, Guide, avatars and NetworkSession APIs. Out of the box everything runs locally: players are local offline profiles. Configured outside the game’s code, the same APIs connect to the self-hosted CNA Gamer Services server for accounts and Guide sign-in, profiles and pictures, friends and presence, achievements, leaderboards with Ranked arbitration, messages and player reviews, parties, avatars, and online sessions (session directory, invitations, host migration and an authenticated relay that also carries voice). It is a CNA service, not Xbox LIVE compatible, and no public instance is operated.
What exists, and where it runs
| Area | Offline / local (default) | Server-backed (configured) |
|---|---|---|
| Profiles and sign-in | Local offline profiles; nobody is signed in until Guide::ShowSignIn or the CNA_GAMER_SERVICES_AUTO_SIGN_IN setting | Server accounts created by the operator, signed in through the Guide; only refresh tokens are stored on the device |
| Guide (system UI) | A console-style system UI drawn by CNA: every standard Guide::Show* page, message boxes, keyboard input, the avatar editor | The same pages, backed by the service (sign-in, friends, messages, profiles) |
| Achievements | Stored locally per profile, optionally described by a GamerServices/Achievements.json catalog | Catalogs provisioned on the server |
| Leaderboards | Local store with real sorting, ranking and paging; offline reads list only the profiles signed in on this machine and always sort the highest rating first | Provisioned boards, written during network gameplay and committed when the host ends the game; Ranked uses majority agreement |
| Friends, presence, messages, pictures | Not available to local profiles: the friend list throws XNA’s GamerPrivilegeException, the social Guide pages throw GamerServicesNotAvailableException, a gamer picture comes back null, and presence can be set but is never published | Service features |
NetworkSession | Local sessions in one process; SystemLink over direct UDP on the LAN, which works offline | PlayerMatch and Ranked through the server’s session directory and its authenticated relay, with invitations, host migration, extra local gamers and Opus voice |
| Avatars | XNA’s AvatarDescription, AvatarAnimation (31 presets) and AvatarRenderer (71 bones) with CNA’s own avatar art; a random avatar per local profile | One stored avatar per account, drawn with a locally installed catalog |
Turning it on
Add GamerServicesComponent to the game, exactly as in XNA, and keep a GraphicsDeviceManager so the Guide and avatars find the graphics device service. The dispatcher pumps all asynchronous results on the game thread during Update. GamerServices is built when the CMake option CNA_ENABLE_GAMER_SERVICES is on; it defaults to the value of CNA_ENABLE_NET, and networking requires it, so a game can link the Guide, profiles and avatars without networking but not the other way round.
#include "Microsoft/Xna/Framework/GamerServices/GamerServicesComponent.hpp"
// in the Game constructor
getComponentsProperty().Add(std::make_shared<GamerServicesComponent>(*this)); // the owning overload
Service mode is chosen outside the game’s code, so the same binary works offline or online: environment variables CNA_GAMER_SERVICES_ENDPOINT and CNA_GAME_ID (plus an optional CA bundle and title version), a cna-title.json manifest (read from the working directory the game is started in, or from the path in CNA_GAMER_SERVICES_MANIFEST), a user settings file, or, in test and deployment hosts, CNA::GamerServices::setConfigurationOverride. With no endpoint, CNA stays offline.
- Transport security: the endpoint must be HTTPS (TLS 1.2 or later, certificate and host name verified). Plain HTTP is accepted only on a numeric loopback address with an explicit opt-in, for development.
- Credentials: no password is stored. Refresh tokens are kept in the desktop keyring on Linux, in 0600 files on headless Linux and macOS, and sealed with DPAPI on Windows (so far run only under Wine).
- Platforms: the service client needs libcurl 7.85 or newer with TLS on native desktop builds, and online sessions and the event channel need libcurl 7.86 or newer built with WebSockets (
wsandwss). Apple’s system libcurl (8.7.1) has no WebSocket support: a macOS build linked against it refuses the online relay withRELAY_SECURE_WEBSOCKET_UNAVAILABLEand gets no event-channel hints (it keeps polling), so link a WebSocket-capable libcurl such as Homebrew’s. iOS builds are configured withCNA_ENABLE_NET=OFF, because the iOS SDK has no libcurl, andCNA_ENABLE_GAMER_SERVICESfollows it, so neitherGamerServicesnorNetis built there. Browser builds run avatars, the Guide and local profiles, but the service, the relay, LAN discovery and voice are not available there; Android builds without libcurl stay offline when no endpoint is configured; with an endpoint configured they refuse service calls (SERVICE_TRANSPORT_UNAVAILABLE) rather than falling back silently.
The CNA Gamer Services server
cna-gamer-services-server (MIT, C++23 on SQLite) is one process that serves the control API, file downloads, an event channel and the session relay on one TLS port. The operator creates titles, accounts, achievements and leaderboards with its admin tool. To try it on one machine:
# in the server repository (its build presets need ccache)
cmake --preset dev && cmake --build --preset dev
build-agent/cna-gamer-services-server --database service.sqlite3 --insecure-loopback # development: http://127.0.0.1:47831
# in another terminal, for the game
export CNA_GAMER_SERVICES_ENDPOINT=http://127.0.0.1:47831/cna/v1
export CNA_GAMER_SERVICES_INSECURE_LOOPBACK=1
export CNA_GAME_ID=my.game
Commands are quoted from the server’s README (commit 4ab12fd) and CNA’s client rules and were not run for this page; Tutorial 164 walks through provisioning a title and an account, and Tutorial 168 covers running the server for other people. The repository also carries the operator tooling: loopback-only health, readiness and Prometheus endpoints, JSON logs, verified online SQLite backup and a restore that refuses to overwrite, an authenticated, CSRF-protected administrator web UI that delegates every change to the admin tool, and systemd, container, Compose and nginx TCP-passthrough templates — starting points, not evidence of a production deployment. Its README and HANDOFF.md are the operational reference.
Trust boundaries. Achievements and scores are authenticated, validated client claims: a modified or colluding client can submit plausible fake results, and there is no anti-cheat. The server limits connections and sign-ins per address but has no server-wide handshake rate limit, so put a network filter in front of it. Public-Internet deployment has not been independently qualified, and the server runs as a single process with a single database writer.
Avatars
AvatarRenderer::Draw renders real avatars from CNA’s own avatar catalogs — original art generated by CNA’s tools, not Xbox content — with XNA’s 71-bone skeleton and 31 animation presets. Bone transforms and bind poses follow XNA’s coordinate space, so samples that attach objects to avatar bones line up as they did on XNA. The Guide includes an avatar editor for accounts and local profiles. An AvatarDescription is 1,021 bytes in CNA’s own format; a game can share one over a network session without the server.
Five avatar samples are among the C++ ports, and they play at samples.libcna.com (for example AvatarShadows and AvatarAnimationBlending); the InverseKinematics sample runs with CNA avatars from its unchanged C# source on CNA.NET. The shipped avatar catalog is v3 revision 5. CNA records its Avatar v3 acceptance passing for revision 5 on 25 October 2026 on all eight renderers of its Linux multi-renderer build (the 233 avatar tests it names, and a checked-in 36-view visual regression on the six that draw), and a full 982-frame avatar review of revision 4 on 24 October 2026 on OPENGL33, OPENGLES3, SOFTWARE, SDL_GPU (Vulkan driver), WEBGPU and FNA3D (every frame rendered; against OpenGL 3.3 the worst mean pixel difference 0.09/255 and the worst silhouette overlap 0.9992). DIRECTX9 (through DXVK) and SDL_GPU on SDL’s Direct3D 12 driver (through vkd3d-proton) were reviewed under Wine on 16 October, not for revision 5. Native Windows drivers and SDL’s Metal driver have not been measured. CNA’s avatars look and move differently from Xbox avatars.
What has been qualified
- CNA’s final audit run of this work (2 October 2026, Linux, server commit
9bd5173with CNA’s client harnesses): the GamerServices suite 649 passed and the Net suite 524 passed, with no failures; the server’s 40 registered tests: 33 passed, 7 that need Linux network namespaces skipped for lack of a test tool, none failed. This is the latest Linux run in which the server’s tests drove real CNA processes. - The server’s handoff qualification (7 October 2026, Linux loopback, commit
4ab12fd): 46 configured tests, 29 passed, the 17 that drive real CNA processes skipped because no CNA build was available (a skip, not a pass), none failed; AddressSanitizer/UndefinedBehaviorSanitizer 19/19 and a focused ThreadSanitizer run 3/3. An independent black-box conformance suite runs 20 smoke cases plus one wall-clock relay-ticket-expiry case and exercises all 59 public operations over TLS and WebSocket. - macOS, recorded by CNA’s Apple campaign on one Apple M4: CNA’s test trees pass, including the networking and Guide tests; the server builds with Homebrew’s Boost after small portability fixes made during that campaign, and with CNA’s harnesses built against Homebrew curl 8.22, 37 of its 46 tests passed, 9 were skipped (seven need Linux network namespaces, two need extra 127.x loopback addresses that macOS does not configure) and none failed. Against Apple’s system libcurl 8.7.1, which has no WebSocket support, the relay is refused by name and the event channel falls back to polling.
- All of these are recorded runs on one machine over loopback, not re-run for this page; none is a measurement of the public Internet.
- Not qualified: Windows (its credential store, and the server’s database lock, have run only under Wine), a real wide-area network with NAT, voice on physical audio devices, and avatar pixels on native Windows drivers and on SDL’s Metal driver.
- Offline leaderboards persist stream columns, and
SendDataOptionscombines as XNA’s flags (ChatwithReliableorInOrder; undefined bits are refused withArgumentOutOfRangeException). Known gaps include guests in online sessions; see Known Issues.
Tutorials
- Tutorial 162: Gamer Services setup, local profiles and sign-in
- Tutorial 163: The Guide — message boxes, keyboard input and system pages
- Tutorial 164: Connecting a game to the CNA Gamer Services server
- Tutorial 123: Achievements and leaderboards, offline and on the server
- Tutorial 165: Friends, presence and gamer pictures
- Tutorial 97: Network sessions on the local network and Tutorial 166: Online sessions, invitations and host migration
- Tutorial 167: Drawing and animating avatars
- Tutorial 168: Operating the Gamer Services server
Known issues in this area
Current defects, gaps and limitations at this snapshot that touch this subject.
- CNA-PLAT-018: Online PlayerMatch and Ranked session traffic needs a libcurl with WebSocket support; with macOS's system libcurl the relay refuses with RELAY_SECURE_WEBSOCKET_UNAVAILABLE — PlayerMatch and Ranked sessions carry their traffic over a WSS relay through libcurl's WebSocket API, so a libcurl without ws/wss and TLS (Apple's system libcurl 8.7.1, or one older than 7.86) refuses the relay and those