A new game object property can be defined by calling the static method GameObjectCreatePropertyT(String, String, String, T). For example:

GamePropertyMetadata<float> metadata = GameObject.CreateProperty<float>(
  "X",                       // The name of the property.
  "Common",                  // The category (for use in game editors).
  "Defines the x-position.", // The description.
  0.0f);                     // The default value.

Once this method is called, the game object property is globally defined. If this method is called a second time with the same properties, it will not create a new game object property. Instead it will only return the metadata of the previous call. There cannot be multiple game object properties with the same name and type!

The metadata of any game object property can be queried by calling GameObjectGetPropertyMetadataT(String) where game object properties can be identified by

• the automatically assigned ID stored in the metadata (see Id), or
• by name and value type.

Either of these ways uniquely identifies a game object property.

Once a game object property is defined it can be set and queried on any game object. There are multiple ways to get the value of a game object property:

var gameObject = new GameObject();

// Method #1: Get value by name from game object.
float x = gameObject.GetValue<float>("X");

// Method #2: Get value by metadata from game object.
x = gameObject.GetValue<float>(metadata);

// Method #3: Get value by ID from game object.
x = gameObject.GetValue<float>(metadata.Id);

// Method #4: First get GameProperty<T> from game object. 
//            Then get the value from the GameProperty<T>.
GameProperty<float> property = gameObject.Properties.Get<float>("X");
x = property.Value;

Note that the game object property will return the default value as defined in the metadata if the property was never set on the object. (If the game object has template, the property will return the value of the template. See Templates.)

Setting the value of a game object property is similar:

var gameObject = new GameObject();

// Method #1: Set value by name.
gameObject.SetValue("X", 10.0f);

// Method #2: Set value by metadata.
gameObject.SetValue(metadata, 10.0f);

// Method #3: Set value by ID.
gameObject.SetValue(metadata.Id, 10.0f);

// Method #4: First get GameProperty<T> from game object. 
//            Then set the value of the GameProperty<T>.
GameProperty<float> property = gameObject.Properties.Get<float>("X");
property.Value = 10.0f;

The above described methods for reading or writing game object properties are basically equivalent.

In the last method a GamePropertyT is acquired. This object is a handle to the property of a particular game object. Other objects can store a GamePropertyT directly if they regularly need to read or change the property of a game object. When the object stores the GamePropertyT it is not necessary to also keep a reference to the game object that owns the property.

In some cases it is convenient to wrap a game object property using a standard CLR property. Here is an example that shows how to define a game object property in a class and wrap it using a CLR property:

public class MyGameObject : GameObject
{
  /// <summary> 
  /// The ID of the <see cref="X"/> game object property.
  /// </summary>
  public static readonly int XPropertyId = 
    CreateProperty<float>("X", "Common", "Defines the x-position.", 0.0f).Id;

  /// <summary>
  /// Gets or sets the x-position. This is a game object property.
  /// </summary>
  /// <value>The x-position.</value>
  public float X
  {
    get { return GetValue<float>(XPropertyId); }
    set { SetValue(XPropertyId, value); }
  }

  ...
}

The game object property can then be used like any other CLR property. (This pattern is extensively used in the UIControls of the DigitalRune Game UI library.

A GamePropertyT has a Changing event which is raised when the value is about to be changed. This event can be used for value coercion. The GamePropertyEventArgsT passed to the event handler contain the current value of the property (see OldValue) and the new value which is about to be set (see NewValue). The event handler can override the new value by setting the CoercedValue. For example:

var valueProperty = slider1.Properties.Get<float>("Value");
valueProperty.Changing += (s, e) =>
{
  if (e.CoercedValue < slider2.Value)
    e.CoercedValue = slider2.Value;
  if (e.CoercedValue > slider3.Value)
    e.CoercedValue = slider3.Value;
};

A GamePropertyT has a Changed which is raised when the value of the property has changed. Other objects can attach an event handler to this event to listen for changes. The event handler will receive a GamePropertyEventArgsT which contains the previous value of the property (see OldValue) and the new value (see NewValue).

Caution
An event handler of a Changed event of a property should not change the value of the property. This leads to nested Changed event calls and might have unexpected results. Value coercion can be done in the Changing event using the CoercedValue property of the GamePropertyEventArgsT.

Game object properties have a property Change, which is an event handler. This event handler can be connected with the Changed event of another property. This is very useful to connect game object properties of different game objects. Changing one property automatically updates the connected properties. Here is an example:

// mySlider is game object that represents a slider GUI control.
// myAvatar is a game object that represents the avatar of the player.
// Connect the "Value" game object property of the slider with the "Height" game object 
// property of the avatar. This way the slider automatically changes the avatar height.
GameProperty<float> sliderValue = mySlider.Properties.Get<float>("Value");
GameProperty<float> avatarHeight = myAvatar.Get<float>("Height");
sliderValue.Changed += avatarHeight.Change;

// Uncomment following line to create a two-way connection.
//avatarHeight.Changed += sliderValue.Change;

Read-only properties are not supported.

Properties are identified by their name and type. That means that a game object can have two or more properties with the same name, as long as the types are different. It is important to match the value types exactly when setting property values. Following examples show that the type of the properties matter:

gameObject.SetValue("X", 10);                   // Setting the integer "X" property.
gameObject.SetValue("X", 20.0f);                // Setting the float "X" property
int intX = gameObject.GetValue<int>("X");       // Returns 10!
float floatX = gameObject.GetValue<float>("X"); // Returns 20.0f!