UDN
Search public documentation:

UnrealScriptDefaultProperties
日本語訳
中国翻译
한국어

Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UE3 Home > UnrealScript > UnrealScript Language Reference > UnrealScript Default Properties

UnrealScript Default Properties


Overview


When an object is created in the game, its properties are initialized to "default" values. These are values set by the gameplay programmer who created the class used to create the object. In many programming languages, a special function, the constructor, is called when objects are created to allow for initilizing variables. UnrealScript does not have an exact equivalent to this concept. Instead, UnrealScript uses a special block of "code" called the defaultproperties block to allow for setting up values for any or all of the instance variables belonging to the class to be used for initialization purposes when an instance of that class is created. This block of code always goes at the end of the script after all function and state declarations and, while it is part of UnrealScript, the code within this block is not standard UnrealScript and follows slightly different rules.

Specifying Default Property Values


As mentioned previously, the rules of the defaultproperties block is slightly different from the standard unrealscript syntax. The general differences are:

  • Statements are not allowed in the defaultproperties block, with the exception of dynamic array operations. This means you cannot perform calculations, call functions, etc. The defaultproperties block is solely for assigning literal values to instance variables.
  • Semi-colons can be placed at the end of each line, but are not required
  • Spaces should be avoided (such as between variable name, assignment operator, and value).
  • The opening curly brace of the defaultproperties block should be on a new line.

In addition to the basic differences listed above, the syntax for some types also differs from the standard assignment syntax in UnrealScript. The syntax for specifying default values for the different variable types are listed below:

Simple Types (Ints, Floats, Bools, Bytes):

VarName=Value

Static Array:

ArrayProp(0)=Value1
ArrayProp(1)=Value2

Or

ArrayProp[0]=Value1
ArrayProp[1]=Value2

Dynamic Arrays:

ArrayProp=(Value1,Value2,Value3)

Or

ArrayProp(0)=Value1
ArrayProp(1)=Value2
ArrayProp(2)=Value3

Or

ArrayProp.Add(Value1)
ArrayProp.Add(Value2)
ArrayProp.Add(Value3)

Names:

NameProp='Value'

Or

NameProp=Value

Objects:

ObjectProp=ObjectClass'ObjectName'

Subobjects:

Begin Object Class=ObjectClass Name=ObjectName
   VarName=Value
   ...
End Object
ObjectProperty=ObjectName

Structs (including Vectors, Rotators, etc.):

StructProperty=(InnerStructPropertyA=Value1,InnerStructPropertyB=Value2)

Or

StructProperty={(
                  InnerStructPropertyA=Value1,
                  InnerStructPropertyB=Value2
               )}

NOTE: Some types require different syntax when used inside a struct default value.

  • Inline static arrays must be declared like so (Notice that brackets "[]" are used here for the array delimiter instead of parenthesis "()"):
       StructProperty=(StaticArray[0]=Value,StaticArrayProp[1]=Value)
       
  • Inline dynamic arrays must be declared using the single line syntax:
       StructProperty=(DynamicArray=(Value,Value))</code>
       
  • Inline name variables must be wrapped with quotes:
       StructProperty=(NameProperty="Value")
       

Dynamic Array Operations - These can be used to modify the contents of a dynamic array, which can be inherited by a parent.

  • Empty - Clears the whole array.
       Array.Empty
       
  • Add(element) - Adds element to the end of the array.
       Array.Add(element)
       
  • Remove(element) - Removes the element from the array, this will remove all occurences of the element.
       Array.Remove(element)
       
  • RemoveIndex(index) - Removes the element at the given index.
       Array.RemoveIndex(index)
       
  • Replace(element1, element2) - Replaces element1 with element2. All occurences will be replaced. A warning is produced with element1 is not found.
       Array.Replace(element1, element2)
       

The following is an example of a complete defaultproperties block (based on Actor.uc):

defaultproperties
{
   	// objects
   	MessageClass=class'LocalMessage'

	// declare an inline subobject of class SpriteComponent named "Sprite"
   	Begin Object Class=SpriteComponent Name=Sprite
       		// values specified here override SpriteComponent's own defaultproperties
      		Sprite=Texture2D'EngineResources.S_Actor'
      		HiddenGame=true
   	End Object
   	//todo
   	Components.Add(Sprite)

	// declare an inline subobject of class CylinderComponent named "CollisionCylinder"
   	Begin Object Class=CylinderComponent Name=CollisionCylinder
       		// values specified here override CylinderComponent's own defaultproperties
      		CollisionRadius=10
      		CollisionHeight=10
      		AlwaysLoadOnClient=True
      		AlwaysLoadOnServer=True
   	End Object
   	//todo
   	Components.Add(CollisionCylinder)

   	CollisionComponent=CollisionCylinder

	// floats (leading '+' and trailing 'f' characters are ignored)
   	DrawScale=00001.000000
   	Mass=+00100.000000
   	NetPriority=00001.f

	// ints
   	NetUpdateFrequency=100

	// enumerations
   	Role=ROLE_Authority
   	RemoteRole=ROLE_None

	// structs
   	DrawScale3D=(X=1,Y=1,Z=1)

	// bools
   	bJustTeleported=true
   	bMovable=true
   	bHiddenEdGroup=false
   	bReplicateMovement=true

	// names
   	InitialState=None

	// dynamic array (in this case, a dynamic class array)
   	SupportedEvents(0)=class'SeqEvent_Touch'
   	SupportedEvents(1)=class'SeqEvent_UnTouch'
   	SupportedEvents(2)=class'SeqEvent_Destroyed'
   	SupportedEvents(3)=class'SeqEvent_TakeDamage'
}

Struct Defaults


When you declare a struct in UnrealScript, you can optionally specify default values for the struct's properties. Anytime the struct is used in UnrealScript, it's members are initialized with these values. The syntax is identical to the defaultproperties block for a class - the only exception is that you must name the block structdefaultproperties. For example:

struct LinearColor
{
   var() config float R, G, B, A;

   structdefaultproperties
   {
      A=1.f
   }
};

Anytime you declare a LinearColor variable in UnrealScript, the value of its A property will be set to 1.f. Something else that is important to understand when using structdefaultproperties is that class defaults override struct defaults. If you have a class member variable of type LinearColor, any value you assign to that member variable in the class defaultproperties will override the value in the struct's defaults.

var LinearColor NormalColor, DarkColor;

defaultproperties
{
	NormalColor=(R=1.f,B=1.f,G=1.f)       // value of A will be 1.0f for this property
	DarkColor=(R=1.f,B=1.f,G=1.f,A=0.2f)  // value of A will be 0.2f for this property
}

Accessing default values of variables


UnrealEd enables level designers to edit the "default" variables of an object's class. When a new actor is spawned of the class, all of its variables are initialized to those defaults. Sometimes, it's useful to manually reset a variable to its default value. For example, when the player drops an inventory item, the inventory code needs to reset some of the actor's values to its defaults. In UnrealScript, you can access the default variables of a class with the Default keyword. For example:

var() float Health, Stamina;

...

// Reset some variables to their defaults.
function ResetToDefaults()
{
	// Reset health, and stamina.
   	Health = Default.Health;
   	Stamina = Default.Stamina;
}

Accessing default values of variables through a class reference

If you have a class reference (a variable of class or class<classlimitor> type), you can access the default properties of the class it references, without having an object of that class. This syntax works with any expression that evaluates to class type.

var class C;
var class PC;

Health = class'Spotlight'.default.LightBrightness;	// Access the default value of
                                                   	// LightBrightness in the Spotlight class.

Health = PC.default.Health;	// Access the default value of Health in
                            	// a variable class identified by PC.

Health = class(C).default.Health;	// Access the default value
                                    	// of Health in a casted class
                                    	// expression.