UnrealScript Classes

Overview

A class is essentially a blueprint for an item to be used by the engine in the game. The blueprint is used to create an instance of the class, which is what the engine actually works with. In generic programming terms, any instance of a class is called an object. This is also true for UnrealScript; however, items that the player sees and interacts with in the game in Unreal are called Actors because they extend from the Actor class. There are classes that extend from the base Object class directly, but these are generally helper classes used by Actors, such as Components.

The concepts of classes and objects in UnrealScript are similar to that of most other object-oriented programming languages. The internet is full of information about this topic.

Class Declaration

Each script corresponds to exactly one class, and the script begins by declaring the class, the class's parent, and any additional information that is relevent to the class. The simplest form is:

class MyClass extends MyParentClass;

Here a new class named MyClass is declared, which inherits the functionality of MyParentClass. This means each class contains all of the variables, functions, and states from its parent class. Additionally, it can then add new variable declarations, add new functions (or override the existing functions), and add new states (or add functionality to the existing states).

The concepts of inheritance and polymorphism (the overriding of functions) are important and warrant additional research for those new to programming, especially with object-oriented languages.

Class Specifiers

The class declaration can take several optional specifiers that affect the class. These keywords follow the basic class declaration, but go before the semicolon ending the declaration. They can either be all on the same line as the declaration or on seaprate lines following the declaration (it is a good practice to indent them if using new lines).

class MyClass extends MyParentClass [Specifier Specifier ... Specifier];

or

class MyClass extends MyParentClass
   [Specifier
   Specifier
   ...
   Specifier];

The available specifiers are listed below with descriptions:

Native(PackageName)

Indicates that "this class uses behind-the-scenes C++ support". Unreal expects native classes to contain a C++ implementation in the .EXE. Only native classes are allowed to declare native functions or implement native interfaces. Native classes must always derive from another native class. Native classes create an auto-generated C++ header file with the necessary glue to interact with the script variables and specified functions. By default, the PackageName is the package that the script class resides in. For example, if the class were in the Engine package, the resulting auto-generated header would be called EngineClasses.h.

NativeReplication

Indicates that replication of variable values for this class is handled in the C++ implementation. Only valid for native classes.

DependsOn(ClassName[,ClassName,...])

Indicates that ClassName is compiled before this class. ClassName must specify a class in the same (or a previous) package. Multiple dependency classes can be specified using a single DependsOn line delimited by commas, or can be specified using a separate DependsOn line for each class. This is important when a class uses a struct or enum declared in another class as the compiler only knows what is in the classes it has already compiled.

Abstract

Declares the class as an "abstract base class". This prevents the user from adding actors of this class to the world in UnrealEd or creating instances of this class during the game, because the class isn't meaningful on its own. For example, the Actor base class is abstract, while the Ladder subclass is not abstract -- you can place a Ladder in the world, but you can't place an Actor in the world. This keyword is propagated to intrinsic child classes, but not to script child classes. For example, Actor is abstract and Pawn extends from Actor but is not declared as abstract. The specifier is not inherited so Pawns can be instantiated.

Deprecated

Causes all objects of this class to be loaded but not saved. Any placed instances of deprecated actors will generate warnings for level designers when they load a map in the editor. This keyword is propagated to child classes.

Transient

Says "objects belonging to this class should never be saved on disk". Only useful in conjunction with certain kinds of native classes which are non-persistent by nature, such as players or windows. This keyword is propagated to child classes; child classes can override this flag using the NonTransient keyword.

NonTransient

Negates a Transient keyword inherited from a base class.

Config(IniName)

Indicates that this class is allowed to store data in a configuration file (.ini). If there are any configurable variables in the class (declared with the config or globalconfig variable specifiers), this specifier causes those variables to be stored in the specified configuration file inside the ( and ). This flag is propagated to all child classes and cannot be negated, but child classes can change the .ini file by redeclaring the Config keyword and specifying a different file name. The value of IniName is appended to the game name - minus the "Game" part - to specify the name of the .ini file to store data in (for instance, in UDKGame specifying Config(Camera) will cause the class to use the UDKCamera.ini file). The keyword inherit can also be specified as the IniName, which will cause the class to use the same config file as its parent. Some .ini files exist by default, such as:

• Config(Engine): Uses the Engine configuration file, which is the name of your game followed by Engine.ini. For example, UDKGame's engine configuration file is named UDKEngine.ini.
• Config(Editor): Uses the Editor configuration file, which is the name of your game followed by Editor.ini. For example, UDKGame's editor configuration file is named UDKEditor.ini.
• Config(Game): Uses the Game configuration file, which is the name of your game followed by Game.ini. For example, UDKGame's game configuration file is named UDKGame.ini.
• Config(Input): Uses the Input configuration file, which is the name of your game followed by Input.ini. For example, UDKGame's engine configuration file is named UDKInput.ini.

PerObjectConfig

Configuration information for this class will be stored per object, where each object has a section in the .ini file named after the object in the format [ObjectName ClassName]. This keyword is propagated to child classes.

PerObjectLocalized

Localized data for this class will be defined on a per-object basis, where each object has a section in the localization file named after the object in the format [ObjectName ClassName]. This keyword is propagated to child classes.

EditInlineNew

Editor. Indicates that objects of this class can be created from the UnrealEd property window (default behavior is that only references to existing objects may be assigned through the property window). This flag is propagated to all child classes; child classes can override this flag using the NotEditInlineNew keyword.

NotEditInlineNew

Editor. Negates a EditInlineNew keyword inherited from a base class. No effect if no parent classes are using EditInlineNew.

Placeable

Editor. Indicates that this class can be created in UnrealEd and placed into a level, UI scene, or kismet window (depending on the class type). This flag is propagated to all child classes; child classes can override this flag using the NotPlaceable keyword.

NotPlaceable

Editor. Negates a Placeable keyword inherited from a base class. Indicates that this class may not be placed into a level, etc. in UnrealEd.

HideDropDown

Editor. Prevents this class from showing up in UnrealEd property window combo boxes.

HideCategories(Category[,Category,...])

Editor. Specifies one or more categories that should be hidden in the UnrealEd property window for objects of this class. To hide variables declared with no category, use the name of the class which declares the variable. This keyword is propagated to child classes.

ShowCategories(Category[,Category,...])

Editor. Negates a HideCategories keyword inherited from a base class.

AutoExpandCategories(Category[,Category,...])

Editor. Specifies one or more categories that should be automatically expanded in the UnrealEd property window for objects of this class. To auto-expand variables declared with no category, use the name of the class which declares the variable.

CollapseCategories

Editor. Indicates that properties of this class should not be grouped in categories in UnrealEd property windows. This keyword is propagated to child classes; child classes can override this flag using the DontCollapseCategories keyword.

DontCollapseCategories

Editor. Negates a CollapseCatogories keyword inherited from a base class.

ForceScriptOrder(true/false)

Editor. Forces property windows displaying an object of this class to use script-defined ordering for properties and categories (if true) or alphabetical order (if false).

Within ClassName

Advanced. Indicates that objects of this class cannot exist without an instance of ClassName. In order to create an object of this class, you must specify an instance of ClassName as the Outer object. This keyword must be the first to follow the class declaration itself.

Inherits(ClassName[,ClassName,...])

Advanced. Used for multiple inheritance - specifies the additional base classes. Multiple bases can be specified using a single Inherits line delimited by commas, or can be specified using a separate Inherits line for each base class. Only valid for native classes. Multiple inheritance from two UObject-derived classes is not supported.

Implements(ClassName[,ClassName,...])

Advanced. Specifies one of more interface classes which this class will implement. Multiple interfaces can be specified using a single Implements line delimited by commas, or can be specified using a separate Implements line for each interface class. Only native classes can implement native interfaces.

NoExport

Advanced. Indicates that this class's C++ declaration should not be included in the automatically-generated C++ header file by the script compiler. The C++ class declaration must be defined manually in a separate header file. Only valid for native classes.

ClassGroup(Groupname[,Groupname,...])

Indicates that the Editor's Actor Browser should include this class and any subclass of this class within the specified GroupName when Group View is enabled in the Actor Browser.