Gamer Services & Avatars

CNA snapshot 3b43bd86

ⓘ

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

AreaOffline / local (default)Server-backed (configured)
Profiles and sign-inLocal offline profiles; nobody is signed in until Guide::ShowSignIn or the CNA_GAMER_SERVICES_AUTO_SIGN_IN settingServer 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 editorThe same pages, backed by the service (sign-in, friends, messages, profiles)
AchievementsStored locally per profile, optionally described by a GamerServices/Achievements.json catalogCatalogs provisioned on the server
LeaderboardsLocal store with real sorting, ranking and paging; offline reads list only the profiles signed in on this machine and always sort the highest rating firstProvisioned boards, written during network gameplay and committed when the host ends the game; Ranked uses majority agreement
Friends, presence, messages, picturesNot 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 publishedService features
NetworkSessionLocal sessions in one process; SystemLink over direct UDP on the LAN, which works offlinePlayerMatch and Ranked through the server’s session directory and its authenticated relay, with invitations, host migration, extra local gamers and Opus voice
AvatarsXNA’s AvatarDescription, AvatarAnimation (31 presets) and AvatarRenderer (71 bones) with CNA’s own avatar art; a random avatar per local profileOne 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 (ws and wss). Apple’s system libcurl (8.7.1) has no WebSocket support: a macOS build linked against it refuses the online relay with RELAY_SECURE_WEBSOCKET_UNAVAILABLE and gets no event-channel hints (it keeps polling), so link a WebSocket-capable libcurl such as Homebrew’s. iOS builds are configured with CNA_ENABLE_NET=OFF, because the iOS SDK has no libcurl, and CNA_ENABLE_GAMER_SERVICES follows it, so neither GamerServices nor Net is 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 9bd5173 with 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 SendDataOptions combines as XNA’s flags (Chat with Reliable or InOrder; undefined bits are refused with ArgumentOutOfRangeException). Known gaps include guests in online sessions; see Known Issues.

Tutorials