Gamer Services & Avatars

CNA snapshot b0e97bb1

ⓘ

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, friends, presence, pictures, leaderboards and online sessions. It is a CNA service, not Xbox LIVE, 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.

#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 with TLS on native desktop builds. 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
cmake -S . -B build -G Ninja && cmake --build build --parallel
build/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 and CNA’s client rules and were not run for this page; Tutorial 164 walks through provisioning a title and an account.

⚠

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. Avatar rendering was reviewed on OpenGL 3.3, Vulkan, Software, SDL_GPU and WebGPU; it has not been measured on OpenGL ES 2, Direct3D, Metal, FNA3D or SDL_Renderer. 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): the GamerServices suite 649 passed and the Net suite 524 passed, with no failures; the server’s 40 registered tests: 33 passed, 7 network-isolation tests skipped for lack of a test tool, none failed. These are CNA-recorded runs, not re-run for this page.
Not qualified: Windows and macOS, a real wide-area network with NAT, voice on physical audio devices, and avatar pixels on Direct3D and Metal.
Known gaps include stream columns in offline leaderboards, guests in online sessions, and XNA’s combined SendDataOptions flags; see Known Issues.