Nerd Herder

Moving to a new blog

Dean Johnson - MSFT — Tue, 12 Apr 2011 05:24:27 GMT

I recently created a new personal blog. I will no longer be updating this blog. Please come join me over at my new blog at http://www.deadlygenius.com.

Calling Guide.IsTrialMode on Windows Phone 7

Dean Johnson - MSFT — Mon, 21 Feb 2011 07:58:00 GMT

As you may have heard calling Guide.IsTrialMode can take around 60 milliseconds to return and thus should not be called each frame in your game. Unfortunately this performance penalty only occurs when your game is downloaded from the WP7 marketplace and not while you are in your development environment so you won't see that calls to Guide.IsTrialMode is slowing down your game’s performance.

So you may be wondering when should you call Guide.IsTrialMode. You could check at startup or game activation and then cache the value but this means your game is depending on the game exiting or deactivating when you call Guide.ShowMarketplace.

A better approach is to check the trial state on a background thread and cache the state for polling on the main thread. If the game is still in trial mode then the background thread can sleep for awhile until it wakes up and checks the state again.

The TrialModeManager singleton class below implements this trial caching on a separate thread and can be used in your games to allow you to poll the trial state without hitting the 60 milliseconds penalty.

/// <summary>
/// Simple singleton class that will check the state of trial mode on a background thread
/// </summary>
public class TrialModeManager
{
    /// <summary>
    /// Property to get the one and only instance of this class
    /// </summary>
    public static TrialModeManager Instance 
    {
        get
        {
            if (instance == null)
            {
                instance = new TrialModeManager();
            }
            return instance;
        }
    }
    private static TrialModeManager instance;

    /// <summary>
    /// Returns the trial state
    /// </summary>
    public bool TrialMode
    {
        get
        {
            return trialMode;
        }
    }
    // Default to trial mode
    private volatile bool trialMode = true;

    // The background thread
    private Thread trialThread;

    /// <summary>
    /// Simple constructor that create the background thread and starts it up
    /// </summary>
    private TrialModeManager()
    {
        trialThread = new Thread(CheckTrial);
        trialThread.IsBackground = true;
        trialThread.Start();
        // Wait for the thread to start up
        while (!trialThread.IsAlive);
    }

    /// <summary>
    /// The thread function that will check the trial state in the background
    /// </summary>
    private void CheckTrial()
    {
        // Stop the thread once we are no longer in trial since the state can't change anymore
        while (trialMode)
        {
            trialMode = Guide.IsTrialMode;

            // Sleep if the game is in trial 
            if (trialMode)
            {
                Thread.Sleep(TimeSpan.FromSeconds(3));
            }
        }
    }
}

Now in your game when you need to check if the game is in trial mode call TrialModeManager.Instance.TrialMode and you will not see a slowdown in your game.

Simple Sound Effect Cue Class

Dean Johnson - MSFT — Mon, 21 Feb 2011 06:51:39 GMT

In my last post I talked about varying the sounds played for events in your game. I also said I would write about a simple sound effect cue system that would work on Windows Phone 7 and all of the other platforms XNA Game Studio 4.0 supports.

Below is a simple class that will manage the playback of the several sound effects. The class will handle two types of playback.

/// <summary>
/// Determines how the next sound effect in the cue will be selected
/// </summary>
public enum SelectionMode
{
    RandomNoRepeats,
    Shuffle,
}

The first selection mode RandomNoRepeats does exactly what the name suggests and plays a random sound effect without playing the same sound effect twice in a row. The second Shuffle plays the list of sound effects in order. Once the end is reached the list is shuffled.

Now lets create the class that will manage our cue of sound effects.

/// <summary>
/// Simple class to play a cue of sound effects
/// </summary>
public class SoundEffectCue
{
    /// <summary>
    /// We hold a list of sound effect instances for each type of sound effect in the cue
    /// </summary>
    List<List<SoundEffectInstance>> soundEffectInstances;
    /// <summary>
    /// The current selection mode
    /// </summary>
    SelectionMode mode;
    /// <summary>
    /// The index into the soundEffectInstances list of the last sound we played
    /// </summary>
    int lastPlayedIndex;

    Random random;

    // ...
}

The class has a few simple members. The first is a list that holds lists of sound effect instances. There is one list of sound effect instances per sound effect. Having multiple instances allows playback of the same sound effect even if a previous playback has not completed. The other variables hold the selection mode and the index of the last sound effect we played.

The constructor for the class is the following.

/// <summary>
/// Constructor used to create a new instance of a SoundEffectCue. 
/// The cue contains the sound effects that are passed into the constructor via the soundEffects parameter.
/// </summary>
public SoundEffectCue(IEnumerable<SoundEffect> soundEffects, int instanceCount, SelectionMode mode)
{
    // Create the list that will hold the list of sound effect instances
    soundEffectInstances = new List<List<SoundEffectInstance>>();

    // Loop over the passed in sound effect instances
    foreach (SoundEffect soundEffect in soundEffects)
    {
        // Create a new list of sound effect instances for each sound effect
        List<SoundEffectInstance> instances = new List<SoundEffectInstance>();
        for (int i = 0; i < instanceCount; i++)
        {
            instances.Add(soundEffect.CreateInstance());
        }
        soundEffectInstances.Add(instances);
    }

    this.mode = mode;
    random = new Random();
    lastPlayedIndex = -1;

    // If we are using the shuffle selection mode then shuffle for the first time
    if (mode == SelectionMode.Shuffle)
    {
        Shuffle();
    }
}

The constructor creates the list of sound effect instances from the list of sound effects passed into the constructor. If the selection mode was set to shuffle the list is shuffled for the first time.

The only other public method in the class is the Play method which will play a sound effect in the cue.

/// <summary>
/// Called from the game when you want to play a sound from the cue
/// </summary>
public void Play()
{
    // Call the appropriate play method based on the selection mode
    switch (mode)
    {
        case SelectionMode.RandomNoRepeats:
            PlayRandomNoRepeats();
            break;
        case SelectionMode.Shuffle:
            PlayShuffle();
            break;
        default:
            Debug.Assert(false, "Invalid playback mode");
            break;
    };
}

The Play method calls out to different play methods depending on the selection mode.

The first play method PlayRandomNoRepeats will play a random sound effect from the cue without playing the same sound effect twice in a row.

/// <summary>
/// Plays a random sound effect from the cue and prevents repeating sound effects from playing.
/// </summary>
private void PlayRandomNoRepeats()
{
    // Select a random index
    int playIndex = random.Next(soundEffectInstances.Count);

    // Did we just play this sound effect?
    if (playIndex == lastPlayedIndex)
    {
        // Just play the next index
        playIndex++;
        // Bounds check
        if (playIndex >= soundEffectInstances.Count)
        {
            playIndex = 0;
        }
    }

    // Loop over all of the instances looking for one that can be played
    for (int i = 0; i < soundEffectInstances[playIndex].Count; i++)
    {
        // If the instance is not playing already we can play the sound
        if (soundEffectInstances[playIndex][i].State != SoundState.Playing)
        {
            lastPlayedIndex = playIndex;
            soundEffectInstances[playIndex][i].Play();
            return;
        }
    }

    // Could not find a sound effect instance to play
    Debug.Assert(false, "All sound effect instances were already playing. Increase the number of sound effect instances.");
}

If all of the sound effect instance for the selected sound effect index are already playing the assert will be hit and lets you know that you should increate the number of instances in the cue.

The other playback method PlayShuffle is similar except it plays the sound effects in the list order until it reaches the end of the list where it then shuffles the list.

/// <summary>
/// Plays sound effects in order until reaching the end of the list then shuffle the list
/// </summary>
private void PlayShuffle()
{
    // Increment to the next sound effect in the list
    lastPlayedIndex++;
    // Are we at the end of the list?
    if (lastPlayedIndex >= soundEffectInstances.Count)
    {
        Shuffle();
    }

    // Loop over all of the instances looking for one that can be played
    for (int i = 0; i < soundEffectInstances[lastPlayedIndex].Count; i++)
    {
        // If the instance is not playing already we can play the sound
        if (soundEffectInstances[lastPlayedIndex][i].State != SoundState.Playing)
        {
            soundEffectInstances[lastPlayedIndex][i].Play();
            return;
        }
    }
            
    // Could not find a sound effect instance to play
    Debug.Assert(false, "All sound effect instances were already playing. Increase the number of sound effect instances.");
}

The PlayShuffle method utilizes the last method in the class Shuffle which performs a Fischer-Yates shuffle on the list of sound effect instances.

/// <summary>
/// An implementation of the Fischer-Yates shuffle that does not allow for the last item in the list to become the 
/// first item in the list. This prevents duplicate sounds after the shuffle.
/// </summary>
private void Shuffle()
{
    // Save the last sound effect played
    List<SoundEffectInstance> lastSoundPlayed = soundEffectInstances[soundEffectInstances.Count - 1];

    // Fischer-Yates shuffle
    for (int i = soundEffectInstances.Count; i > 1; i--)
    {
        int swapIndex = random.Next(i);
        List<SoundEffectInstance> temp = soundEffectInstances[swapIndex];
        soundEffectInstances[swapIndex] = soundEffectInstances[i - 1];
        soundEffectInstances[i - 1] = temp;
    }

    // Check to see if we just played this
    if (lastSoundPlayed == soundEffectInstances[0])
    {
        // Swap for some other random index
        int swapIndex = random.Next(1, soundEffectInstances.Count);
        soundEffectInstances[0] = soundEffectInstances[swapIndex];
        soundEffectInstances[swapIndex] = lastSoundPlayed;
    }

    // Reset the play index
    lastPlayedIndex = 0;
}

So that's a simple sound effect cue class that will allow you to have multiple sound effects in a single cue that can be used for a sound event in your game and allow for sound variation.

Sound Cue Variations

Dean Johnson - MSFT — Tue, 15 Feb 2011 06:44:00 GMT

Last week I was reading my friend Shawn’s blog post “Random shuffle” and it reminded me of a system I worked on that controlled the playback of sound effects.

When you play sound effects in a game you will often want to have a number of sound effects that can be played for each event in the game. For example you may have multiple sounds for when a player takes damage. Having multiple sound effects for events especially those that occur often in the game prevents the user from becoming annoyed and keeps the audio less predictable.

If you build games using XNA for Windows or Xbox 360 you may be familiar with the Microsoft Cross-Platform Audio Creation Tool or XAct for short. XAct allows you to setup audio cues that consist of multiple wave files. In your game code you tell XAct to play a specific cue. The cue then determines which of the specific wave files to play.

The specific wave to play is determined by the “Variation Playlist” setting for the audio cue.

XAct provides six different variation types:

· Ordered – The waves in the cue are played in a specific configured order.

· Ordered from Random – The waves are put into a random order and are then played in that order.

· Random – A random wave is selected and played.

· Random (no immediate repeats) – A random wave is played but is guaranteed not to be a repeat of the previous wave. Of course if there is only a single wave in the cue the sound will have to repeat.

· Shuffle – The list of wave that can be played are shuffled and then played in the shuffled order. Once all waves have been played the list is shuffled again.

· Interactive – Allows for interactive control between the game and XAct more info can be found here.

Often shuffle or random (no immediate repeats) will be what you want to use for your game.

If you are building a game on Windows Phone 7 you unfortunately won’t have access to the functionality provided by XAct and you will need to build the variation functionality into your game yourself.

In my next post I will discuss a simple sound effect instance variation system that you can use in your WP7 games.

XNA Game Studio 4.0 Programming: Developing for Windows Phone 7 and Xbox 360

Dean Johnson - MSFT — Sun, 30 Jan 2011 02:33:28 GMT

I have been a avid reader of technical books, mostly around computer programming since I was very young. Growing up I read many more technical books than I ever did fiction novels. It has also been a goal to someday write a technical book of my own.

During the development of XNA Game Studio 4.0 I thought it would a good time to write a book on XNA Game Studio 4.0. Luckily for me my coworker and friend Tom Miller was also looking to write another book. So we decided that we would work on a book together.

The book is now finished an available at your preferred book store. The amazon.com link is below.

http://www.amazon.com/XNA-Game-Studio-4-0-Programming/dp/0672333457/ref=sr_1_3?ie=UTF8&qid=1296353406&sr=8-3#_

We also have a Facebook page where you can tell us what you think about the book and any bugs you might find.

http://www.facebook.com/home.php#!/pages/XNA-Game-Studio-40-Programming-Developing-for-Windows-Phone-and-Xbox-Live/148023561880764

Avatar API changes in XNA Game Studio 4.0

Dean Johnson - MSFT — Sun, 30 Jan 2011 02:09:06 GMT

When we started to build XNA Game Studio 4.0 we made the decision to break the Microsoft.Xna.Framework.dll assembly into multiple assemblies to better support different functionality multiple platforms. Avatar functionality was pulled out into its own assembly called Microsoft.Xna.Framework.Avatar.dll. When you create a new Xbox 360 or Windows project in XNA Game Studio 4.0 your project will already contain this assembly reference by default.

In order to move avatar functionality into its own assembly we needed to ensure that types in other assemblies never referenced the types in the avatar assembly. In XNA Game Studio 3.1 the SignedInGamer type contained a property called Avatar which was of type AvatarDescription. Since SignedInGamer was moved into the Microsoft.Xna.Framework.GamerServices.dll assembly we had to remove the SignedInGamer.Avatar property.

At the same time we also wanted to provide a way to allow developers to access the avatar of any Gamer they may have a reference to. That includes FriendGamer and NetworkGamer objects something that was not supported in XNA Game Studio 3.1.

In order to obtain an AvatarDescription for a specific Gamer you now use the AvatarDescription.BeginGetFromGamer method. This method is asynchronous since it may take more than a few cycles to query the type of Gamer that you have passed in.

To load the local players avatar the code now looks like this.

First you will still need to initialize the GamerServicesComponent and subscribe to the SignedInGamer.SignedIn event in your Game class constructor.

Components.Add(new GamerServicesComponent(this));
SignedInGamer.SignedIn += new EventHandler<SignedInEventArgs>(SignedInGamer_SignedIn);

Next we need to create the SignedInGamer_SignedIn method that will handle the event.

void SignedInGamer_SignedIn(object sender, SignedInEventArgs e)
{
    // Only handle player one sign in
    if (e.Gamer.PlayerIndex == PlayerIndex.One)
    {
        AvatarDescription.BeginGetFromGamer(e.Gamer, LoadGamerAvatar, null);
    }
}

Once the BeginGetFromGamer method has completed it will call the LoadGamerAvatar method that we define below.

void LoadGamerAvatar(IAsyncResult result)
{
    // Get the AvatarDescription for the gamer
    avatarDescription = AvatarDescription.EndGetFromGamer(result);

    // Load the AvatarRenderer if description is valid
    if (avatarDescription.IsValid)
        avatarRenderer = new AvatarRenderer(avatarDescription);
}

We call EndGetFromGamer with the IAsyncResult to obtain the AvatarDescription. In this case avatarDescription and avatarRenderer are defined as member variables in the class. Before creating the AvatarRenderer we verify that the description is valid.

Another change that occurred with avatars in XNA Game Studio 4.0 was that their proportions were updated. This was a change that occurred across the Xbox 360 platform and we support in XNA Game Studio 4.0.

This does mean that custom animations need to be authored with a new animation rig. Luckily the existing rigs for Maya and the Softimage Mod Tool were updated to the new proportions and a new 3D Studio Max version was also created. All of these can be found at the link below.

http://create.msdn.com/en-US/education/catalog/utility/avatar_animation_rig

Along with the rigs the animation packs were also updated and can be found at the link below.

http://create.msdn.com/en-US/education/catalog/utility/avatar_animation_pack

Finally the avatar samples have also been update to support XNA Game Studio 4.0 including the custom avatar animation sample.

http://create.msdn.com/en-US/education/catalog/sample/custom_avatar_animation

Custom Avatar Animations PLUS 21 New Animations

Dean Johnson - MSFT — Mon, 20 Jul 2009 23:15:25 GMT

We have just posted three new avatar items to the XNA Creators Club Online site.

Custom Avatar Animation Sample
This sample shows users how to import and play custom avatar animations though the content pipeline. http://creators.xna.com/en-US/sample/customavataranimation

Avatar Animation Rig
We have provided both an Softimage Mod Tool 7.5 version and Maya 2008 version of the animation rig that can be used to create custom animations. http://creators.xna.com/en-US/utility/avataranimationrig Please take a look at the “readme” to understand how to load and export animations.

Avatar Animation Pack
This pack contains 21 new animations that users can use in their games. We provided them in FBX format for direct use in your games or in source format for both Softimage Mod Tool 7.5 and Maya 2008. http://creators.xna.com/en-US/utility/avataranimationpack Please take a look at the “readme” to understand how to load and export animations.

Enjoy

Simple example on how to load a signed in gamers avatar

Dean Johnson - MSFT — Wed, 24 Jun 2009 23:27:01 GMT

Now that XNA Game Studio 3.1 has been released I have had time to notice the types of questions people are asking on the forums about avatars. One question that has come up a few times is how to load a signed in gamers avatar. There are a couple of pitfalls. One thing that can be confusing to developers is that a SignedInGamer from the Gamer.SignedInGamers collection may be null for the first few frames when the game loads. So when a developer tries to read the Avatar property of a signed in gamer they will receive a null reference exception. The developer needs to wait until the gamer is recognized as being signed in and then attempt to load the players avatar. You game should not just check for the signed in gamer in a tight loop. Your game should go about doing other things like updating input and rendering. Games also need to handle the case where the signed in gamer doesn't have an avatar.

There are a few ways to wait for the SignedInGamer to not be null and load the appropriate avatar. I will show a couple of methods. The first just polls and checks to see if the signed in gamer is not null and when it is not it loads the players avatar. If the player doesn't have an avatar a random one is created. Also if the system takes longer than 3 seconds for the gamer to sign then the code will load a random one instead. Below is an example of the first method.

public class SimpleAvatarGame : Microsoft.Xna.Framework.Game
{
    GraphicsDeviceManager graphics;

    AvatarDescription avatarDescription;
    AvatarRenderer avatarRenderer;
    AvatarAnimation avatarAnimation;

    public SimpleAvatarGame()
    {
        graphics = new GraphicsDeviceManager(this);
        Content.RootDirectory = "Content";

        graphics.PreferMultiSampling = true;
        graphics.PreferredBackBufferWidth = 1280;
        graphics.PreferredBackBufferHeight = 720;

        Components.Add(new GamerServicesComponent(this)); 
    }

    protected override void LoadContent()
    {
        avatarAnimation = new AvatarAnimation(AvatarAnimationPreset.Celebrate);
    }

    protected override void Update(GameTime gameTime)
    {
        if (GamePad.GetState(PlayerIndex.One).Buttons.Back == ButtonState.Pressed)
            this.Exit();

        LoadUserAvatar(gameTime);

        // You may want to check that the avatar renderer has loaded
        // so that the animation does not start playing until it has loaded
        avatarAnimation.Update(gameTime.ElapsedGameTime, true);

        base.Update(gameTime);
    }

    /// <summary>
    /// Load player one's avatar
    /// </summary>
    private void LoadUserAvatar(GameTime gameTime)
    {
        // Avatar may already be loaded
        if (avatarRenderer != null)
            return;

        // Check to see if the user is signed in
        if (Gamer.SignedInGamers[PlayerIndex.One] != null)
        {
            // Get the users avatar description
            avatarDescription = Gamer.SignedInGamers[PlayerIndex.One].Avatar;

            // If this is not valid the user doen't have an avatar
            if (!avatarDescription.IsValid)
            {
                avatarDescription = AvatarDescription.CreateRandom();
            }

            avatarRenderer = new AvatarRenderer(avatarDescription);
        }
        // Check to see if it has been longer than 3 seconds
        else if (gameTime.TotalGameTime.TotalSeconds > 3)
        {
            avatarDescription = AvatarDescription.CreateRandom();
            avatarRenderer = new AvatarRenderer(avatarDescription);
        }
    }

    protected override void Draw(GameTime gameTime)
    {
        GraphicsDevice.Clear(Color.CornflowerBlue);

        if (avatarRenderer != null)
        {
            avatarRenderer.World = Matrix.CreateRotationY(MathHelper.ToRadians(180.0f));
            avatarRenderer.View = Matrix.CreateLookAt(new Vector3(0, 1, 3), new Vector3(0, 1, 0), Vector3.Up);
            avatarRenderer.Projection = Matrix.CreatePerspectiveFieldOfView(MathHelper.ToRadians(45.0f), 
                                                     GraphicsDevice.Viewport.AspectRatio, .01f, 200.0f); 
            avatarRenderer.Draw(avatarAnimation.BoneTransforms, avatarAnimation.Expression);
        }

        base.Draw(gameTime);
    }
}

Another technique for determining when the gamer has signed in and to read their Avatar property is to subscribe to the SignedInGamer.SignedIn event handler. Below is an example how to do this.

public class SimpleAvatarGame : Microsoft.Xna.Framework.Game
{
    GraphicsDeviceManager graphics;

    AvatarDescription avatarDescription;
    AvatarRenderer avatarRenderer;
    AvatarAnimation avatarAnimation;

    public SimpleAvatarGame()
    {
        graphics = new GraphicsDeviceManager(this);
        Content.RootDirectory = "Content";

        graphics.PreferMultiSampling = true;
        graphics.PreferredBackBufferWidth = 1280;
        graphics.PreferredBackBufferHeight = 720;

        Components.Add(new GamerServicesComponent(this));

        SignedInGamer.SignedIn += new EventHandler<SignedInEventArgs>(LoadGamerAvatar); 
    }

    void LoadGamerAvatar(object sender, SignedInEventArgs e)
    {
        avatarDescription = e.Gamer.Avatar;

        // Check to see if the player has an avatar
        if (!avatarDescription.IsValid)
        {
            avatarDescription = AvatarDescription.CreateRandom();
        }

        avatarRenderer = new AvatarRenderer(avatarDescription);
    } 

    protected override void LoadContent()
    {
        avatarAnimation = new AvatarAnimation(AvatarAnimationPreset.Celebrate);
    }

    protected override void Update(GameTime gameTime)
    {
        if (GamePad.GetState(PlayerIndex.One).Buttons.Back == ButtonState.Pressed)
            this.Exit();

        // You may want to check that the avatar renderer has loaded
        // so that the animation does not start playing until it has loaded
        avatarAnimation.Update(gameTime.ElapsedGameTime, true);

        base.Update(gameTime);
    }

    protected override void Draw(GameTime gameTime)
    {
        GraphicsDevice.Clear(Color.CornflowerBlue);

        if (avatarRenderer != null)
        {
            avatarRenderer.World = Matrix.CreateRotationY(MathHelper.ToRadians(180.0f));
            avatarRenderer.View = Matrix.CreateLookAt(new Vector3(0, 1, 3), new Vector3(0, 1, 0), Vector3.Up);
            avatarRenderer.Projection = Matrix.CreatePerspectiveFieldOfView(MathHelper.ToRadians(45.0f), 
                                                     GraphicsDevice.Viewport.AspectRatio, .01f, 200.0f);
            avatarRenderer.Draw(avatarAnimation.BoneTransforms, avatarAnimation.Expression);
        }

        base.Draw(gameTime);
    }
}

If you have any questions please ask on the forums here http://forums.xna.com.

AvatarDescription.Description

Dean Johnson - MSFT — Thu, 28 May 2009 21:54:22 GMT

In a couple of previous posts here and here I talked about the AvatarDescription.Description property that returns a byte[].

The AvatarDescription.Description property is provided to allow developers to recreate a previously created AvatarDescription object. The byte[] from the property is used in conjunction with the AvatarDescription(byte[] ) constructor to recreate the description object.

There are three main scenarios this enables.

Avatars in online games

When a player joins an online game their game sends their AvatarDescription.Description to all of the other players in the session. Each of the other players can then create the AvatarDescription object using the AvatarDescription(byte[] ) constructor.

Saving a players random avatar choice

You may want to allow a player to select some of the characters in their game. For example a user may pick party members in an RPG. The developer can continue to generate random AvatarDescription objects by calling AvatarDescription.CreateRandom(). The developer can then save the AvatarDescription.Description for the random avatars the player as selected along with other save game data. The data can then be read when the player loads the game so that they see the same characters they had in a previous game.

Loading a avatar designed by the developer

The final scenario allows the developer to design a specific avatar for use as a character in their game. This can be done by creating the desired look for the avatar in the Xbox 360 dash avatar editor. Then use an Xbox 360 XNA Game Studio game to load the AvatarDescription object from the SignedInGamer.Avatar property for the profile associated with the avatar you want to use. Put a breakpoint somewhere in your code after loading the AvatarDescription. Debug the code and put the AvatarDescription object you created in the watch window in Visual Studio.

Next you will need to copy the contents of the Description property and format the text. You can then use these values to construct a new byte[] that can be used to create the AvatarDescription in your game. You can either hard code this byte[] in your source code or save it to a file and create a content processor.

AvatarDescription.IsValid… When & Why the description returned is invalid?

Dean Johnson - MSFT — Wed, 20 May 2009 23:51:37 GMT

In previous posts I talked about how the AvatarDescription contains data to define what an avatar should look like so that the AvatarRenderer knows what assets to load in order to render the avatar. The AvatarDescription type contains a property called IsValid which is a read only bool. So what does this property tell the developer? It tells the developer if the description is valid of course! So when can a developer expect a description to be valid and invalid?

First let’s go over the different ways a user can create an AvatarDescription object.

Gamer.SignedInGamers[PlayerIndex.One].Avatar – Returns the avatar description from a gamers profile.

AvatarDescription.CreateRandom() – Returns a randomly created avatar description.

AvatarDescription(byte[] data) – Constructor that allows the developer to construct a description from a byte[] that was returned from the AvatarDescription.Description property of an already created AvatarDescription object. A future post will talk more about this constructor and why it is useful.

Now for the rules on when descriptions are valid vs. invalid.

· On Windows the profile and random avatar descriptions will return as invalid descriptions because Windows does not support avatars.

· On Xbox the random avatar description will return valid descriptions.

· On Xbox the profile avatar description can return both valid and invalid descriptions. If a user does not have an avatar associated with their profile then the avatar description returned will be invalid.

Not too confusing right?

So how do invalid AvatarDescriptions behave?

The properties on the AvatarDescription such as the Height, BodyType, and Description return default values. IsValid returns false as you would expect.

So what happens if you use an invalid AvatarDescription to create an AvatarRenderer? Does it throw an exception? No. You will get back an AvatarRenderer object. You can do everything that you would do normally with an AvatarRenderer created with a valid AvatarDescription. The difference is when you call draw nothing will be displayed to the screen. This was done so that while you develop your game on Windows you will not need to wrap all of your AvatarRenderer constructor or draw calls in try/catch statements. While the avatar will not draw on Windows there is also a chance that the users profile on the Xbox will also be invalid. The developer should detect that the game can’t display an avatar and do something appropriate. For example the developer may create a stand in model to use when a user doesn’t have a valid avatar description.