Share via

Gamer Services Overview

  • Article

The GamerServices namespace provides functionality available from Xbox LIVE and Games for Windows - LIVE to XNA Framework developers. This includes the capability to retrieve player preferences for local accounts as well as to display various LIVE Guide user interface screens programmatically.

Important

Games for Windows - LIVE is not available to finished games. This functionality is not included in the redistributable version of the XNA Framework, and a game that attempts to use these components without XNA Game Studio installed will result in a GamerServicesNotAvailableException.

Users must explicitly initialize the gamer services subsystem before they can use any gamer services or networking API calls. Most games will use the GamerServicesComponent, a game component which takes care of the process of initializing and pumping the gamer services system. This component will pass through the graphics device and window handle automatically. It calls Update to pump the gamer services pump at regular intervals. To take advantage of this component, most games simply need to add one line to the Game constructor:

Components.Add(new GamerServicesComponent(this));

Initializing the gamer services system can be a slow operation, and it has user-visible consequences. For example, the game may display the "Player Signed In" notification when the gamer services system is initialized. This happens when a local profile is set to sign in automatically, and, as a result, trigger a system update. Because of this, if a game is going to use these services, it is desirable to initialize everything in the game startup code in the constructor.

Programs that do not use the XNA Framework application model or component infrastructure can use GamerServicesDispatcher. In this case, you must also call the GamerServicesDispatcher.Initialize and GamerServicesDispatcher.Update methods directly. Under these conditions, you should initialize the GamerServicesDispatcher once at startup, and call GamerServicesDispatcher.Update at every frame.

The GamerServicesDispatcher.Update method enables the XNA Framework to raise events for notifications such as sign-in status changes and game invites when it is safe to raise the events.

Player Sign-In

For standard game clients with a user interface, the Guide user interface automatically displays the appropriate user interface when a player presses either the HOME key on the keyboard or the Guide button on the Xbox 360 controlller, allowing players to sign in. Before a player signs in, you can also choose to manually display the sign-in user interface using the Guide.ShowSignIn function.

When a SignedInGamer signs in, the SignedInGamer.SignedIn event is fired. You can get the list of signed-in players at any time using the static property Gamer.SignedInGamers.

Player Profile Information

The player profile information that is accessible using the Gamer.GetProfile method returns information such as the gamer picture, motto, and gamerzone. Specifically, the gamer profile provides the following information about a gamer:

You may use SignedInGamer.GameDefaults to retrieve a local gamer's preferred settings, such as:

Using SignedInGamer.Privileges, you can see if the player is allowed to:

You can also view whether a gamer is LIVE-enabled or a guest.

Privileges will be enforced by the framework. A player will never be allowed to create an online session if his or her multiplayer privilege is not enabled. Programmatic access to these settings is provided so that games may check to see if anything is forbidden. In such a case, the relevant menu options would be grayed out – this keeps the user from selecting a forbidden option and receiving an exception or error when attempting to call the method in question.

Guide User Interface

The XNA Framework exposes a property, Guide.IsVisible, which checks to see if the Guide user interface is active. The Guide runs independently alongside games. The player can view the Guide at any time by pressing the HOME key on the keyboard or the Guide button on the controller.

Many of the Guide calls are blocking. The XNA Framework uses the standard .NET async pattern to expose asynchronous versions of all the Guide methods. Blocking versions of the Guide methods automatically pump the graphics device while the UI is active. They call GraphicsDevice.Present at regular intervals with an empty (black) backbuffer. Games should have the asynchronous versions of the methods if it is desirable to continue rendering behind the Guide. The existing storage device UI has been changed to match the new design.