Difference between revisions of "Defaultproperties"

Revision as of 05:29, 12 April 2008

The defaultproperties block is a special section in an UnrealScript class source file. It can define or redefine default values for all properties declared in the class or inherited from a parent class. If a property is not mentioned in the defaultproperties block, its default value is inherited from the parent class. If a property is not mentioned in any parent class defaultproperties either, its default value is corresponding the null value of the property's type.

Like cpptext blocks, the defaultproperties block is stripped from the source when the class source is imported by the UnrealScript compiler. This means you can neither see nor specify it in the Source code editor of UnrealEd versions coming with Unreal Engine generations 1 and 2. When exporting source scripts from UnrealEd's Actor Classes browser or with the BatchExportCommandlet, a defaultproperties block is generated for each class from the current default values of all properties that differ from their default value in the parent class. These generated defaults may include values read from configuration and localization files, so make sure they don't include any sensitive data like your login password before you publish them. Also, especially in UT2003 and UT3 exported defaults differ greatly from the imported defaults in some areas.

To edit default values of a class from within UnrealEd, go to the Actor Classes browser, find and right-click the class in the tree and select "Default properties..." in the pop-up menu. A window titled "Default Packagename.Classname Properties" similar to the Actor Properties window will open and allow you to change most of the default values. As with the Actor Properties window, what exactly you are allowed to change depends on the declaration of the corresponding variables.

Note: All script-editing capabilities have been removed from the Unreal Engine 3 Unreal Editor. This includes editing default values. Instead, you can create Archetypes, but only for non-abstract, placeable Actor classes.

General syntax

defaultproperties
{
  ...
}

The keyword defaultproperties and the braces must each be on their own line. Especially putting the opening brace on the same line as the keyword defaultproperties will not work! The default value definitions are separated by line breaks and are not regular UnrealScript code. They are more similar to the format of T3D files. Starting with Unreal Engine 2, the defaultproperties block may also contain Subobject definitions.

The defaultproperties section may contain comments. In Unreal Engine 1 block comment support for the defaults section is very buggy, so line comments should be used instead.

Default struct properties

Starting with Unreal Engine 3 it's also possible to specify default values for struct members. The syntax and rules are identical to the class defaultproperties, except that the block starts with the keyword structdefaultproperties:

struct (struct declaration)
{
  (struct member declarations)
  
  structdefaultproperties
  {
    ...
  }
}

As with class defaults, structs that extend another struct will inherit default values from the parent struct.

Specifying default values

Each line in the defaultproperties can assign a value to a class variable that is not a static array or to an element of a static or dynamic array variable. Dynamic array variables can also be assigned as a whole. Starting with Unreal Engine 3, dynamic arrays can also be manipulated in other ways than setting a value for an element or the complete array. Struct variables must always be assigned directly, but the actual members to manipulate can be specified in the value part.

The syntax for manipulating a value is:

propertyname=value

Note that Unreal Engine 1 does not allow whitespace before the equals sign. Any whitespace following the equal sign is treated as part of the value, which may cause trouble if the property type does not specifically allow whitespace. These restrictions no longer exist in Unreal Engine 2 and 3. This syntax is also used to assign an entire dynamic array by putting all array elements in the value definition. Trailing semicolons are allowed, but not required because only line breaks are used as separator.

The syntax for manipulating an array element is:

propertyname(index)=value

The index may only consist of decimal digits and can be surrounded by whitespace. However, Unreal Engine 1 does not allow spaces around the equals sign or before the first parenthesis. And yes, it demands round parentheses. Starting with Unreal Engine 2 you can also use square brackets and insert whitespace spaces around the equals sign and parentheses.

Manipulating dynamic arrays in UE3

Changing a dynamic array's default content only slightly from that of the parent class is a much easier task in Unreal Engine 3. The following operations can be freely mixed and are performed in the order they appear in the defaultproperties block.

Making the array completely empty:

propertyname.Empty

Adding a value to the end of the array:

propertyname.Add(value)

Removing all occurrences of a value from the array:

propertyname.Remove(value)

Removing an element at a specific index:

propertyname.RemoveIndex(index)

Replacing all occurrences of a value with another value:

propertyname.Replace(oldvalue,newvalue)

These operations always require the entire value to be specified. For partial manipulation of struct members you will have to use the regular array element notation propertyname(index)=value.

Value format

The defaultproperties block not only has a different general syntax, but also a slightly different way to specify some values.

Boolean values

Boolean values can be either "1", "True" or the language-specific string representation of that value to set the property to True, or "0", "False" or the language-specific string representation of that value to set the property to False. Any other value is ignored. Values are case-insensitive and can optionally be enclosed in double quotes.

Byte values

Byte values may only consist of decimal digits and must not contain a sign. Hexadecimal notation with the 0x prefix is not supported.

Enum values

Values of enum properties are simply the name of the enum constant, optionally enclosed in double quotes.

Float values

The value for a float property consists of:

1. an optional sign, i.e. + or -
2. zero or more decimal digits
3. optionally a dot followed by zero or more decimal digits
4. optionally the letter D or E in upper- or lowercase, followed by an optional sign and one or more decimal digits

A float value may be surrounded by whitespace and followed by any "junk data" except comma and right/closing round parenthesis.

Int values

Like byte values, int values may only consist of decimal digits. They may also be preceded by a minus sign. Hexadecimal notation is not supported.

Name values

The value of a name property may either be a double-quoted, non-empty string or a token that may start with a letter or digit and contain letters, digits, the underscore and the minus character. If the name starts with an underscore or minus character, you need to use the double-quoted notation. Note that the name value may not exceed 63 characters.

The usual notation in single quotes is not supported.

Object values

Values for object properties can be specified as usual. Additionally you can also omit the class name and single quotes and only write the qualified or unqualified object name.

Be careful when using Unreal Engine 1 or when specifying class limiter properties. You will not get a warning when the value doesn't fit in the variable due to type mismatches. Check the default value of your class in UnrealEd or with a tool such as UTPT to see if it was imported correctly.

Subobjects can only be referenced if they were defined before (i.e. above) the assignment or array operation referencing that subobject.

String values

For strings, the usual double-quoted notation is allowed.

Dynamic arrays

When assigning values to an entire dynamic array, the values are separated by commas and the entire list is enclosed in round parentheses. Each value must be specified as described in the above sections. There may not be any whitespace around values, unless permitted by the value type. The entire list of values must be on a single line:

property=(value1,value2,value3)

The assignment always replaces all previous elements in the array. The array is trimmed to a length equal to the number of values in the assignment.

Struct values

Struct values are specified in a similar way as array values: value definition are separated by commas and the entire definition is enclosed in round parentheses. The difference is, that for each value the struct member name must be specified like for class defaults:

property=(member1=value1,member2=value2)

The entire set of values must be on a single line, but starting with Unreal Engine 3 you can also enclose the struct value definition in curly braces to allow line breaks between the values:

property={(
  member1=value1,
  member2=value2
)}

Struct members not mentioned in the definition of the struct property value will inherit the parent class default value. If the property was declared in this class, the default member value for that struct type is inherited. If no default value for that struct member was specified in the struct type, the member type's null value is used.