UnDocumented unRealscript
Bob Berry
Digitalo Studios, Inc.
Last Updated: 07/24/00
This document describes some of the hidden treasures UnrealScript while simultaneously exposing some entirely useless information.
Variable Declaration
· EditConst
Variable is displayed, but can not be changed in UnrealED’s default properties window.
e.g.
var(Object) native const editconst class Class;
var() editconst foo CantTouchThis;
· Skip
Used to short-circuit a function call by treating the parameter as an expression to be evaluated. Skip may only be specified as the second parameter of a native operator definition.
· Array<type>
There is some good news and some bad news here. The good news is variable length arrays are supported using the Array specifier.
e.g.
var Array<Wookie> AllWookies;
var Array<int> BunchOfInts;
The bad news is that they aren’t fully implemented in UnrealScript (as of UT420). This means you can declare them, but you can’t access them. This is one of those gems of entirely useless information referred to in the introduction.
· Map
There are plans for UnrealScript to support map variables (such as in Perl), however the implementation is only partially complete. You can see this by the error message generated when you define one and try to compile.
e.g.
var map<blah,blaht> Wookie;
· Travel
Specifies that this property can travel across levels and servers (persistent).
e.g.
var travel int Health;
Class Declaration
· NativeReplication
This tag specifies that the native C++ code for the given UnrealScript class should be responsible for handling replication. The following is a quotes an e-mail from Tim Sweeney regarding Native Replication:
* Native replication is enabled/disabled on a per-class basis. If an
UnrealScript class is defined with the "nativereplication" keyword, that
means you need to write a corresponding native replication function for the
variables _in_that_class_ -- see UnActor.cpp for the examples. Each class's
replication is either handled 100% in C++ (if you use "nativereplication")
or 100% in UnrealScript (otherwise).
* C++ native replication functions work just like the correspinding
"replication" statements in UnrealScript, the syntax is just different (if
you look at the code you'll see a pretty clear correspondence).
* UnrealScript or native replication code only defines replication for the
variables declared _in_that_class_file_. You can mix 'n match UnrealScript
and native replication in a series of classes and subclasses in the
inheretance chain. The code in 300 is already structured this way (native
replication defined for actor and pawn, but not all subclasses).
· NoUserCreate
Users may not instantiate these classes in UnrealED.
e.g.
class Wookie extends Actor NoUserCreate;
If you select the Wookie class in the class browser, right click in the viewport, and select “Add Wookie Here” from the context menu you will receive a log message stating that “You can't add actors of this class to the world.”
· SafeReplace
Specifies that a reference to this class may safely be set to Null or default if the class object can’t be found in any packages. For example, you create a map that uses textures from the package “Rugs.UTX”. You have two floors in your map, one surface using the “Persian” texture and the other using the “Throw” texture. If you close your map, delete “Persian” from the texture package and reload your map, the surface that was referencing Persian will be changed to reference the default texture. This is because the texture class was declared SafeReplace. Note that packages are not SafeReplace. That means if you had deleted the Rugs.UTX package completely (deleting the file), your map would not load because the “package” must be found.
· PerObjectConfig
Stores configuration information on a per-object basis rather than a per-class basis.
e.g.
class Wookie extends WalkingCarpet PerObjectConfig;
This says that each wookie object should have a separate configuration section (in the configuration file) based on its name.
· Within
Specifies that this class can only be instantiated within the context of another class. For example, if you can create a class “Chewbacca” that must always be owned by objects of class “Smuggler”.
e.g.
class Chewbacca extends Wookie Within Smuggler;
Note that this specifier does not currently (UT420) work, but can be made to do so with a few minor code changes in UnScrCom.cpp.
Flow Control
· Stop
Immediately stops executing state code.
· Assert
Just like a C++ assertion, if the expression within the assert call evaluates to false, the program will terminate with an descriptive error message. This is useful for debugging. Note however that UnrealScript assertions are always evaluated, not just in “debug mode” (since there is no debug mode for UnrealScript).
e.g.
function StopUnreal()
{
assert(1==0);
}
This function is called “StopUnreal” because the assert statement will always fail because 1 is always not equal to 0. Because it fails, execution of Unreal stops with an error message stating that the assertion failed and lets you know in which source file and on which line the assert statement was found.
Miscellaneous Tidbits
·
· Import / From
Allows you to import a package, enum, or struct for referencing.
e.g.
import package Botpack;
import enum EInputKey From Engine;
· New
Used to construct descendant classes of Object, but not descendants of Actor. New acts like a cross between a function and an operator using the form of:
object new(Object, Name, Int) class NewClass;
The 3 optional “function” parameters of this operator specify the parent object, the object name, and the object flags respectively.
e.g.
local TestObj to;
to = new(self, ‘MyFoo’, 0) class’TestObj’;
Note that the parameters are completely optional including the parenthesis surrounding them. Thus, a call to new could look like this:
To = new class’TestObj’;
· ArrayCount
Returns the number of elements in an array.
e.g.
local int NumElements;
local int foo[40];
NumElements = ArrayCount(foo);
In this case, NumElements is equal to 40.
· EnumCount
Returns the number of elements in an enum.
e.g.
enum EWookies
{
Chewbacca,
ChewysDad,
ChewysMom
};
function int GetNumWookies()
{
return Ewookies.EnumCount;
}
In this case, the useless function GetNumWookies returns 3. This function is useless because it always return 3 since enumerations can’t be modified at run-time.