Now the Bad News
Some of the functions in the Guide
class are not available on Windows Phone 7 because they have no
equivalent system UI, so it makes a bit of sense for them to be missing.
However, a few functions in the Guide
and everything else in Gamer Services do not work on
Windows Phone 7 unless you are a partner Xbox LIVE game. If you don’t
know what that means, then unfortunately you are probably not one. The
API calls still exist on the platform and work if you have a partnership
agreement with Microsoft, but if you do not, you get an exception
trying to initialize the GamerServicesDispatcher (even if via GamerServicesComponent). This is the reason that the Guide methods on the phone do not require these components.
Platform-Specific Guide Functionality
Although the rest of these
APIs work on Windows, they’re there only to help debug Xbox
functionality.You deal with Xbox
projects. First, create a new Xbox Game project.
You need to initialize Gamer Services before doing
anything else on Xbox. So, add the following to your Initialize overload:
Components.Add(new GamerServicesComponent(this));
Notifications
As you move on to
platform-specific features, a good place to start is notifications.
You’ve probably seen quite a few notifications pop up while you were
playing on your Xbox, from when you first sign in to Xbox LIVE, to when
you get an achievement, to when you see your friends logging on. They’re
ubiquitous on the platform! The XNA runtime includes two separate APIs
to control the behavior of these notifications as well.
The first is the Guide.DelayNotifications method. This takes a single parameter that is a TimeSpan
for how long you want to delay the notifications, up to a maximum of
120 seconds (two minutes). If you pass in a larger delay, the maximum is
used. This method ensures that key portions of your game (for example, a
cut scene) are not interrupted by the notifications. After the delay is
over, the system delivers the notifications in the order they were
received.
Note
You cannot call DelayNotifications continuously. The system needs time to deliver notifications.
The other is a property called Guide.NotificationPosition,
which dictates where the notification shows up on the screen. There are
nine different areas where the notifications can show up: top left,
center or right; bottom left, center, or right; or middle left, center,
or right. The default location is the bottom center, but you are free to
move it elsewhere.
Other Players
One
of the great features of Xbox LIVE is the capability to interact with
your friends, even if you aren’t actually playing a game with them at
the time. To update your new game project to show off some of these
features, add a new variable to your game:
Use this to easily detect
button presses. You should also add a quick helper method to check for
the presses, so you don’t have to repeat the same code pattern multiple
times:
/// <summary>
/// Simple helper to determine if a button was pressed
/// </summary>
public bool WasButtonPressed(Buttons button, GamePadState current, GamePadState last)
{
return (current.IsButtonUp(button) && last.IsButtonDown(button));
}
Now, add the following code to your Update method to see the next system interface call:
GamePadState state = GamePad.GetState(PlayerIndex.One);
if (!Guide.IsVisible)
{
if (WasButtonPressed(Buttons.A, state, lastState))
{
Guide.ShowFriends(PlayerIndex.One);
}
}
lastState = state;
With this code, when you
press and release the A button on your controller, it shows the system
user interface for your friends, as in Figure 3. Use this in a game menu to show your friends.
You can also ask someone new to be your friend by using a call such as the following:
Guide.ShowFriendRequest(PlayerIndex.One, otherPlayer);
This is where the otherPlayer
parameter is of type Gamer .
This brings up the system user interface to enable the user to send a
friend request to the other person specified by otherPlayer.
Because this is the system UI providing this, all features of
requesting a friend are here, including attaching voice and text
messages. When your game has individuals playing a multiplayer game in a
public session, it gives your players an opportunity to request to be
friends with the people they enjoyed playing with.
A similar system screen to
the friends is the list of players you’ve recently played online with.
You can add support for this screen by adding the following to your Update method before storing the previous state:
if (WasButtonPressed(Buttons.X, state, lastState))
{
Guide.ShowPlayers(PlayerIndex.One);
}
Of course, what if you play
with someone who was a total jerk, and saying inappropriate things, and
generally being a bad person. Xbox LIVE enables a player to submit
feedback on other players. If you show a list of players within your
game, you might want to give your players a chance to submit feedback on
others. You can do so with the following API:
Guide.ShowPlayerReview(PlayerIndex.One, otherPlayer);
This API brings up the system screen for submitting player review, and like the earlier example uses a parameter of type Gamer. Perhaps you don’t want to
submit feedback on a player; you just want to see more information about
him or her. Then you use the following API to enable you to see his or
her gamer card:
Guide.ShowGamerCard(PlayerIndex.One, otherPlayer);
One of the more recent
features with Xbox LIVE is the concept of parties, in which you can be
in a group (or party) of people where you can chat and interact, even if
you are all playing different games. You can add the following call to your Update method to see the party screen as shown in Figure 4:
if (WasButtonPressed(Buttons.B, state, lastState))
{
Guide.ShowParty(PlayerIndex.One);
}
You can also see the party
session system screen, which enables you to invite your party members to
your games by using the following API:
Guide.ShowPartySessions(PlayerIndex.One, otherPlayer);
There are also other ways to
invite other players to your party , but the API
call is the following:
Guide.ShowGameInvite(PlayerIndex.One, listOfPlayers);
Note
There is another overload for ShowGameInvite that takes a string that is the session identification for use in mobile games if you happen to be an Xbox LIVE partner.
This sends an invite to your
current session to all players in the list you passed in.
Messaging and Signing In
Unlike the message box
API discussed earlier, which simply shows a message on your local
screen, there are two other APIs that enable you to send messages to
other players over the Xbox LIVE service. To see what messages you
currently have, add this code to your project in the Update method:
if (WasButtonPressed(Buttons.Y, state, lastState))
{
Guide.ShowMessages(PlayerIndex.One);
}
This pops up the system screen with your messages as seen in Figure 5. You can also use the following API to show the system screen enabling you to send a message to someone else:
Guide.ShowComposeMessage(PlayerIndex.One, "Hello", listOfPlayers);
The text you pass into the
method pre-populates the message (and it must be fewer than 200
characters). You can also pass in null as the list of players to have
the system show the select gamertag screen before the message is sent.
Lastly, what if you detect that
no one is signed in, or not enough people are signed in for your game
(you learn how to determine this in the next section)? To tell people to
sign in to the game, add the following code to your Update method:
if (WasButtonPressed(Buttons.LeftShoulder, state, lastState))
{
Guide.ShowSignIn(4, false);
}
This shows the sign-in system
screen. The first pane tells the system how many panes to show for the
sign in, and valid values are 1, 2, and 4. With a value of 1, a single
sign-in pane shows up for one person to sign in. With a value of 2, you
have two panes side by side
enabling players to sign in. With four, you have a square of panes
available for signing in. The next parameter determines which type of
profiles can sign in. If the value is true, only profiles that are
online enabled can sign in. If it is false, everyone can sign in. If it
is true, local players can still sign in as guests of an online account.
With these parameters, the screen appears as it does in Figure 6.
