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.