Chapter 49 GamerServices and Local Identity

Gamer is the base of SignedInGamer. Initialization creates four fixed local identities: Stub Gamer and Stub Gamer (1) through (3). Player One is not a guest; the other three are guests. All four report IsSignedInToLive=true, although no online sign-in occurs.

GetFromGamertag, GetPartnerToken, and their asynchronous pairs are stubs. IsFriend returns false, and GetFriends() returns an empty FriendCollection. The friend types themselves work as containers; CNA has no source from which to populate them.

XNA exposes Presence as a get-only reference property whose returned object is mutable. CNA adds a non-const getPresenceProperty() overload so that the same usage remains possible in C++:

The fragment assumes the corresponding GamerServices headers and namespace imports.

The store is rooted at StorageDevice::GetStorageRootEXT(), which is based on SDL_GetPrefPath. Achievement files live below GamerServices/achievements; leaderboard files live below GamerServices/leaderboards. Calling StorageDevice::SetAppNameEXT changes the root for both systems. Chapter 50 defines that shared boundary.

Achievements use one JSON file per sanitized gamertag, with records of the form {"key":...,"earnedTicks":...}. Leaderboards use one file per sanitized (key)_(gameMode). Characters outside [A-Za-z0-9._-] become underscores; an empty name becomes _. Writes use an adjacent temporary file followed by rename, with direct writing as a fallback. Missing or malformed files produce an empty store.

JSON numbers are represented as double. Achievement ticks, leaderboard ratings, and 64-bit property values therefore lose low bits above $2^{53}$. For a 2026 DateTime, the quantization step is about 128 ticks, or 12.8 microseconds. The stored integer remains stable after the first serialization, but the original 64-bit value is not a bit-exact round trip.

AwardAchievement and GetAchievements use the local store. Returned entries contain a persisted Key, IsEarned=true, and the earned time, subject to the numeric limitation above. Name, Description, and GamerScore remain empty or zero; DisplayBeforeEarned remains true. Xbox Live supplied that catalog metadata outside the AwardAchievement(string) call, and CNA has no equivalent catalog. Applications that display achievement names or scores must maintain their own mapping.

Achievement::GetPicture() throws NotImplementedException. Artwork is another service-owned field for which the local store has no source.

LeaderboardReader, LeaderboardWriter, and LeaderboardEntry are disk-backed. Their policy is CNA-specific because FNA exposes no functioning PC implementation from which to inherit sorting or paging behavior:

• •

  entries sort by rating, descending;

• •

  paging around an absent gamer starts at the top;

• •

  persisted entries whose gamertags have no matching live Gamer are omitted;

• •

  the asynchronous pairs complete synchronously;

• •

  assigning Rating on a writer-created entry persists it immediately.

A reader-created entry has no persistence hook. Changing its in-memory rating does not update the file.

Most Guide UI calls are no-ops: compose message, friend request, friends, game invite, gamer card, marketplace, messages, party, player review, players, sign-in, and ShowAchievementsEXT. DelayNotifications is also inert.

Two asynchronous families are CNA-rendered overlays: BeginShowMessageBox/EndShowMessageBox and BeginShowKeyboardInput/EndShowKeyboardInput. They stay pending until the game’s Draw() path invokes the matching RenderPending*EXT hook with a SpriteBatch, SpriteFont, and white pixel. The hooks render the prompt and poll keyboard or mouse input. Guide.IsVisible reports whether either operation is pending.

Keyboard input preserves UTF-16 surrogate pairs. Password mode masks displayed code units but returns the unmasked text. Escape cancels the operation. Because std::string cannot distinguish XNA’s null-on-cancel result from a confirmed empty string, callers must query WasKeyboardInputCanceledEXT before interpreting the result.

Only one Guide overlay can be pending. The test corpus covers pending state, callback identity, Enter and Escape, prompt fields, password display, and competing requests.

GamerPresence supplies all 60 XNA display strings and formats parameterized modes. Its SetPresenceModeStringEXT publication hook is empty: no service consumes the result. GamerPrivileges is fixed and permissive, and nothing enforces it. GamerProfile uses synthetic defaults except for host-derived Region. These objects carry useful local state, not authentication or policy authority.

GamerServicesComponent must be added to Game.Components before using the Gamer or Guide APIs, as on XNA 4.0 for Windows. Its dispatcher creates and frees the local gamer set. The Update() method on GamerServicesDispatcher is empty; the local asynchronous implementations complete their own actions.

The pinned headers and implementations establish the API shapes, fixed identities, file layout, overlay hooks, and stubs. Unit tests cover persistence behavior and Guide state; the isolated harness covers the dispatcher interaction. These tests do not establish interoperation with Xbox Live, because CNA has no such transport.