Difference between revisions of "Talk:Variables"

Revision as of 07:38, 16 September 2015

Old page content

== Important notice to editors ==
{{stub}}
This article is a stub to relation of the fact, that primarily [[User:Ikuto|article creator]] have mainly filled in stuff about Unreal Engine 1 and some aspects of Unreal Engine 2. Any help on expanding this article with Unreal Engine 2 and Unreal Engine 3 stuff will be much appreciated.

__TOC__

== Simple Variables ==

Here are some examples of instance variable declarations in UnrealScript:

<uscript>var int a; // Declare an integer variable named "A".
var byte Table[64]; // Declare an array of 64 bytes named "Table".
var string[32] PlayerName; // Declare a max 32-character string.
var actor Other; // Declare a variable referencing an actor.</uscript>

Variables can appear in two kinds of places in UnrealScript: instance variables, which apply to an entire object, appear immediately after the class declarations. Local variables appear within a function, and are only active while that function executes. Instance variables are declared with the "var" keyword. Local variables are declard with the "local" keyword.

Here are the basic variable types supported in UnrealScript: 

* byte: A single-byte value ranging from 0 to 255. 
* int: A 32-bit integer value. 
* bool: A boolean value: either "true" or "false". 
* float: A 32-bit floating point number. 
* string: A string of characters. 
* name: The name of an item in Unreal (such as the name of a function, state, class, etc). Names are stored as a 16-bit index into the global name table. Names correspond to simple strings of 1-31 characters. Names are not like strings: strings can be modified dynamically, but names can only take on predefined name values. 

* Enumeration: A variable that can take on one of several predefined name values. For example, the ELightType enumeration defined in the Actor script describes a dynamic light and takes on a value like LT_None, LT_Pulse, LT_Strobe, and so on. 
* Object and actor references: A variable that refers to another object or actor in the world. For example, the Pawn class has an "Enemy" actor reference that specifies which actor the pawn should be trying to attack. Object and actor references are very powerful tools, because they enable you to access the variables and functions of another actor. For example, in the Pawn script, you can write "Enemy.Damage(123)" to call your enemy's Damage function – resulting in the enemy taking damage. Object references may also contain a special value called "None", which is the equivalent of the C "NULL" pointer: it says "this variable doesn't refer to any object". 

* Structs: Similar to C structures, UnrealScript structs let you create new variable types that contain sub-variables. For example, two commonly-used structs are "vector", which consists of an X, Y, and Z component; and "rotator", which consists of a pitch, yaw, and roll component.

Variables may also contain additional specifiers such as "const" that further describe the variable. Actually, there are quite a lot of specifiers which you wouldn't expect to see in a general-purpose programming language, mainly as a result of wanting UnrealScript to natively support many game- and environment- specific concepts: 

* const: Advanced. Treats the contents of the variable as a constant. In UnrealScript, you can read the value of const variables, but you can't write to them. "Const" is only used for variables which the engine is responsible for updating, and which can't be safely updated from UnrealScript, such as an actor's Location (which can only be set by calling the MoveActor and SetLocation functions). 
* input: Advanced. Makes the variable accessible to Unreal's input system, so that input (such as button presses and joystick movements) can be directly mapped onto it. Only relevent with variables of type "byte" and "float". 
* transient: Advanced. Declares that the variable is for temporary use, and isn't part of the object's persistent state. Transient variables are not saved to disk. Transient variables are initialized to zero when an actor is loaded. 
* native: Advanced. Declares that the variable is loaded and saved by C++ code, rather than by UnrealScript.
* private: The variable is private, and may only be accessed by the class's script; no other classes (including subclasses) may access it.
* editinline: Advanced. Indicates that object reference \ class reference can be expanded in actor \ object properties <Unreal Engine 2+>
* editconst: Advanced. Indicates that property can not be modified in the properties window

Arrays are declared using the following syntax:

<uscript>var int MyArray[20]; // Declares an array of 20 ints.</uscript>

UnrealScript supports only single-dimensional arrays, though you can simulate multidimensional arrays by carrying out the row/column math yourself.

In UnrealScript, you can make an instance variable "editable", so that users can edit the variable's value in UnrealEd. This mechanism is responsible for the entire contents of the "Actor Properties" dialog in UnrealEd: everything you see there is simply an UnrealScript variable, which has been declared editable.

The syntax for declaring an editable variable is as follows:

<uscript>var() int MyInteger; // Declare an editable integer in the default category.
var(MyCategory) bool MyBool; // Declare an editable integer in "MyCategory".</uscript>

== Object and actor reference variables ==

You can declare a variable that refers to an actor or object like this:

<uscript>var actor A; // An actor reference.
var pawn P; // A reference to an actor in the Pawn class.
var texture T; // A reference to a texture object.</uscript>

The variable "P" above is a reference to an actor in the Pawn class. Such a variable can refer to any actor that belongs to a subclass of Pawn. For example, P might refer to a Brute, or a Skaarj, or a Manta. It can be any kind of Pawn. However, P can never refer to a Trigger actor (because Trigger is not a subclass of Pawn).

One example of where it's handy to have a variable refering to an actor is the Enemy variable in the Pawn class, which refers to the actor which the Pawn is trying to attack.

When you have a variable that refers to an actor, you can access that actor's variables, and call its functions. For example:

<uscript>// Declare two variables that refer to a pawns.
var pawn P, Q;
 
// Here is a function that makes use of P.
// It displays some information about P.
function MyFunction()
{
        // Set P's enemy to Q.
        P.Enemy = Q;
 
        // Tell P to play his running animation.
        P.PlayRunning();
}</uscript>

Variables that refer to actors always either refer to a valid actor (any actor that actually exists in the level), or they contain the value "None". None is equivalent to the C/C++ "NULL" pointer. However, in UnrealScript, it is safe to access variables and call functions with a "None" reference; the result is always zero.

Note that an object or actor reference "points to" another actor or object, it doesn't "contain" an actor or object. The C equivalent of an actor reference is a pointer to an object in the AActor class (in C, you'd say an AActor*). For example, you could have two monsters in the world, Bob and Fred, who are fighting each other. Bob's "Enemy" variable would "point to" Fred, and Fred's "Enemy" variable would "point to" Bob.

Unlike C pointers, UnrealScript object references are always safe and infallible. It is impossible for an object reference to refer to an object that doesn't exist or is invalid (other than the special-case "None" value). In UnrealScript, when an actor or object is destroyed, all references to it are automatically set to "None".

== Class Reference Variables ==

In Unreal, classes are objects just like actors, textures, and sounds are objects.  Class objects belong to the class named "class".  Now, there will often be cases where you'll want to store a reference to a class object, so that you can spawn an actor belonging to that class (without knowing what the class is at compile-time).  For example:

<uscript>var() class C;
var actor A;
A = Spawn( C ); // Spawn an actor belonging to some arbitrary class C.</uscript>

Now, be sure not to confuse the roles of a class C, and an object O belonging to class C.  To give a really shaky analogy, a class is like a pepper grinder, and an object is like pepper.  You can use the pepper grinder (the class) to create pepper (objects of that class) by turning the crank (calling the Spawn function)...BUT, a pepper grinder (a class) is not pepper (an object belonging to the class), so you '''MUST NOT TRY TO EAT IT!'''

When declaring variables that reference class objects, you can optionally use the special class<classlimitor> syntax to limit the variable to only containing references to classes which expand a given superclass.  For example, in the declaration:

<uscript>var class<actor> ActorClass;</uscript>

The variable ActorClass may only reference a class that expands the "actor" class.  This is useful for improving compile-time type checking.   For example, the Spawn function takes a class as a parameter, but only makes sense when the given class is a subclass of Actor, and the class<classlimitor> syntax causes the compiler to enforce that requirement.

As with dynamic object casting, you can dynamically cast classes like this:

<uscript>class<actor>( SomeFunctionCall() )</uscript>

== Enumerations ==

Enumerations exist in UnrealScript as a convenient way to declare variables that can contain "one of" a bunch of keywords. For example, the actor class contains the enumeration EPhysics which describes the physics which Unreal should apply to the actor. This can be set to one of the predefined values like PHYS_None, PHYS_Walking, PHYS_Falling, and so on.

Internally, enumerations are stored as byte variables. In designing UnrealScript, enumerations were not seen as a necessity, but it makes code so much easier to read to see that an actor's physics mode is being set to "PHYS_Swimming" than (for example) "3".

Here is sample code that declares enumerations.

<uscript>// Declare the EColor enumeration, with three values.
enum EColor
{
        CO_Red,
        CO_Green,
        CO_Blue
};
 
// Now, declare two variables of type EColor.
var EColor ShirtColor, HatColor;
 
// Alternatively, you can declare variables and
// enumerations together like this:
var enum EFruit
{
        FRUIT_Apple,
        FRUIT_Orange,
        FRUIT_Bannana
} FirstFruit, SecondFruit;</uscript>

In the Unreal source, we always declare enumeration values like LT_Steady, PHYS_Falling, and so on, rather than as simply "Steady" or "Falling". This is just a matter of programming style, and is not a requirement of the language.

UnrealScript only recognizes unqualified enum tags (like FRUIT_Apple) in classes where the enumeration was defined, and in its subclasses.  If you need to refer to an enumeration tag defined somewhere else in the class hierarchy, you must "qualify it":

<uscript>FRUIT_Apple // If Unreal can't find this enum tag...
EFruit.FRUIT_Apple // Then qualify it like this.</uscript>

== Structs ==

An UnrealScript struct is a way of cramming a bunch of variables together into a new kind of super-variable called a struct. UnrealScript structs are just like C structs, in that they can contain any simple variables or arrays.

You can declare a struct as follows:
<uscript>// A point or direction vector in 3D space.
struct Vector
{
        var float X;
        var float Y;
        var float Z
};</uscript>

Once you declare a struct, you are ready to start declaring specific variables of that struct type:

<uscript>// Declare a bunch of variables of type Vector.
var Vector Position;
var Vector Destination;</uscript>

To access a component of a struct, use code like the following.

<uscript>function MyFunction()
{
        Local Vector A, B, C;
         
        // Add some vectors.
        C = A + B;
 
        // Add just the x components of the vectors.
        C.X = A.X + B.X;
 
        // Pass vector C to a function.
        SomeFunction( C );
 
        // Pass certain vector components to a function.
        OtherFunction( A.X, C.Z );
}</uscript>

You can do anything with Struct variables that you can do with other variables: you can assign variables to them, you can pass them to functions, and you can access their components.

There are several Structs defined in the Object class which are used throughout Unreal. You should become familiar with their operation, as they are fundamental building blocks of scripts: 

* Vector: A unique 3D point or vector in space, with an X, Y, and Z component. 
* Plane: Defines a unique plane in 3D space. A plane is defined by its X, Y, and Z components (which are assumed to be normalized) plus its W component, which represents the distance of the plane from the origin, along the plane's normal (which is the shortest line from the plane to the origin). 
* Rotation: A rotation defining a unique orthogonal coordinate system. A rotation contains Pitch, Yaw, and Roll components. 
* Coords: An arbitrary coordinate system in 3D space. 
* Color: An RGB color value. 
* Region: Defines a unique convex region within a level.

I'm rewriting this for less redundancy in content with other pages. — Wormbo 09:46, 1 October 2008 (UTC)

Explanation of superscript "S" missing

Some modifiers are superscripted by "S", but the explanation of it is missing in the "Infobox EngineVersion". Probably it got lost with this change. --SeriousBarbie (talk) 10:38, 16 September 2015 (EDT)