UnrealScript

See UnrealScript overview for all Unreal Wiki topics about learning and using UnrealScript.

UnrealScript is the Unreal Engine's scripting language. It is a staticly/strongly-typed, object-oriented and event-driven programming language very similar to Java and C++, with some influences from Visual Basic. If you want to learn UnrealScript, you should make yourself familiar with the fundamental concepts of object-oriented programming. It definitely helps already to know another programming language, preferably one that is strongly-typed and object-oriented as well.

Anatomy of an UnrealScript source file

A typical UnrealScript source file might look similar to the following example from UT2004:

1. class DMRosterBeatTeam extends xDMRoster;

3. /*

4.  * Roster for deathmatch levels.

5.  * Each level has its own roster.  

6.  * This special roster subclass is used to populate an enemy team with the

7.  * player's selected teammates.

8.  */

10. // called immediately after spawning the roster class

11. function Initialize(int TeamBots)

12. {

13. 	local GameProfile GP;

14. 	local int i, j;

16. 	GP = Level.Game.CurrentGameProfile;

17. 	if ( GP == none ) {

18. 		Log("DMRosterBeatTeam::Initialized() failed.  GameProfile == none.");

19. 		return;

20. 	}

22. 	// create roster entries for single player's teammates

23. 	for ( i=0; i<GP.PlayerTeam.Length; i++ )

24. 	{

25. 		j = Roster.Length;

26. 		Roster.Length = Roster.Length + 1;

27. 		Roster[j] = class'xRosterEntry'.Static.CreateRosterEntryCharacter(GP.PlayerTeam[i]);

28. 	}

30. 	// remaining team-specific info, might be used in menus at some point

31. 	TeamName = GP.TeamName;

32. 	TeamSymbolName = GP.TeamSymbolName;

34. 	super.Initialize(TeamBots);

35. }

37. defaultproperties

38. {

39. 	TeamName="Death Match"

40. 	TeamSymbolName="TeamSymbols_UT2003.Sym01"

41. }

As you can see, UnrealScript is a curly brace programming language: blocks of code are enclosed in curly braces. Each code statement is either followed by a block or terminated by a semicolon.

• Line 1 contains the mandatory class declaration. This file contains a class with the name DMRosterBeatTeam. The extends clause specifies that this class inherits attributes, methods and other class members from a class with the name xDMRoster, which is said to be the "super class" or "parent class" of DMRosterBeatTeam.
• Lines 3 to 8 are an example for a block comment. The important parts here are the characters /* on line 3 and */ on line 8. Everything between them is ignored by the UnrealScript compiler.
• Line 10 contains another type of comment, an end-of-line comment or just line comment. Outside of block comments this type of comment starts with the characters // and continues to the end of the same line. As with block comments, everything on the line following the double slashes is ignored by the compiler.
• Line 11 contains a declaration for an instance function. The function's name is specified to be "Initialize" and the function has one parameter of type int called "TeamBots". The block of code on lines 12 to 35 is the function's "body". Some functions do not have a body. The declaration of those functions is terminated by a semicolon instead.
• The line 13 declares a local variable of type GameProfile, a class defined elsewhere, and gives it the name "GP". The variable is initially empty.
• Line 16 assigns a value to the local variable "GP" so it no longer is empty. To determine the value, the function accesses the variable "Level". This variable is not declared here, but in a parent class of DMRosterBeatTeam. The object referenced by "Level" has a variable of its own, called "Game", whose contained object in turn has a variable called "CurrentGameProfile". The content of that variable is assigned to our local "GP" variable.
• On line 17 there's an If statement with a block of code that ends on line 20. That block of code is only executed if the expression in the parentheses following the keyword If returns the value True. The If condition checks, whether the content of the local "GP" variable equals the special value None, which simply means "empty".
• Lines 18 and 19 are only executed if the condition (here: "GP is empty") is true. So, if GP is empty, first the function with the name "Log" is called to write a message to the log file, then the Return statement exits the function. In this case the code after the If block will not be executed. In other cases the If block might not contain a Return and code execution would continue after the If block.
• On line 23 there's a typical For loop that iterates over a dynamic array. The code on lines 25 to 27 is executed for each element of the "PlayerTeam" array in the object stored in the local "GP" variable. Notice how the If statement on line 17 ensured that "GP" actually contains an object.
• Line 34 calls another version of the "Initialize" function, that was declared in a parent class of DMRosterBeatTeam, passing on the TeamBots parameter. This call tells us, that the "Initialize" function of the DMRosterBeatTeam class actually overrides a function with the same name in its parent class xDMRoster or another parent class further up the class hierarchy.
• Lines 37 to 41 are the defaultproperties block. This block defines default values for class variables. Both "TeamName" and "TeamSymbolName" are inherited from a parent class.