Legacy:Object (UT3)/Functions

UT3 :: Object (UT3) (Non-Numeric Functions)

These are functions defined in the Object class that are related to colors, string and objects. All of them are declared final and most of them are also native and/or static. The few exceptions will be mentioned individually.

Since Object is the top-most class of the UT3 class hierarchy, all the functions described here can be used in all other classes. You could basically call them "global functions", though that somewhat waters down the OOP aspect.

See Legacy:Object (UT3)/Numeric Functions for other final functions that perform operations on numbers and derived structures such as vectors or rotators.
See Legacy:Object (UT3)/Operators for additional operations on values of various types.
See Object (UT3) for other members of the Object class, including non-final function stubs and events.

String Functions

Character positions in strings are counted from 0: The first character in a string with length 10 has index 0, the second index 1, and so on to the last character, which has index 9.

int Len (coerce string S) 

Returns the number of characters in S.

int InStr (coerce string S, coerce string T, optional bool bSearchFromRight) 

Returns the first (or, if bSearchFromRight is true, last) occurrence of T in S.

string Mid (coerce string S, int i, optional int j) 

Returns the substring of S starting at character index i. Unless j is omitted, the returned string's length is limited to j characters.

string Left (coerce string S, int i) 

Returns the substring of S consisting of the first i characters.

string Right (coerce string S, int i) 

Returns the substring of S consisting of the last i characters.

string Caps (coerce string S) 

Converts all characters in S to uppercase.

string Locs (coerce string S) 

Converts all characters in S to lowercase.

string Chr (int i) 

Returns a string only consisting of the character with the specified ASCII value.

int Asc (string S) 

Returns the ASCII value of the first character in S.

string Repl (coerce string Src, coerce string Match, coerce string With, optional bool bCaseSensitive) 

Non-recursively replaces all occurrences of Match in S with With. If bCaseSensitive is omitted of set to false, comparison with Match is case-insensitive.
"Non-recursively" is best explained with an example:

Repl("banana", "ban", "b")

This example will result in "bana", and not "ba", although "ban" could match the 'b' from the replacement string and the two characters "an" following the first replaced part.

string Split (coerce string Text, coerce string SplitStr, optional bool bOmitSplitStr) [non-native] 

Splits Text on the first occurrence of SplitStr and returns the remaining part of Text. If bOmitSplitStr is omitted or set to false, the SplitStr is returned as part of the result, otherwise it is removed.

JoinArray (array<string> StringArray, out string out_Result, optional string delim, optional bool bIgnoreBlanks) [non-native] 

Concatenates the elements of StringArray to a single string and separates the individual array elements with delim. which defaults to a comma if omitted. If bIgnoreBlanks is omitted or set to true, empty array elements and their separating delimiters will not be added to the string. The result is returned in out_Result.

ParseStringIntoArray(string BaseString, out array<string> Pieces, string Delim, bool bCullEmpty) 

Breaks up a delimited string into elements of a string array. If bCullEmpty is set to true, the array will not contain empty strings.

Color Functions

color MakeColor (byte R, byte G, byte B, optional byte A) [non-native] 

Constructs a Color value from the specified components. A defaults to 0 if omitted.

LinearColor MakeLinearColor (float R, float G, float B, float A) [non-native] 

Constructs a LinearColor value from the specified components.

LinearColor ColorToLinearColor (color OldColor) [non-native] 

Converts a Color value to LinearColor, dividing all components by 255.

Object-related Functions

string PathName (Object CheckObject) 

Returns the full path name of the specified object, including package and groups.
In earlier engine versions this was achieved by simply typecasting the object to string. That operation only results in the object's name now, though.

bool ClassIsChildOf (class TestClass, class ParentClass) 

Returns true if TestClass either is the same class as ParentClass or a subclass thereof. Returns false if either parameter is None.

bool IsA (name ClassName) [non-static] 

Returns true if the name of this object's class or any of any parent class matches the specified name.

Object DynamicLoadObject (string ObjectName, class ObjectClass, optional bool MayFail) 

Attempts to load an object with the specified name and class. Returns the object on success or None on failure. Unless MayFail is set to true, a warning is logged on failure.
This function can be quite expensive if the specified object's package is not yet loaded.

Object FindObject (string ObjectName, class ObjectClass) 

Attempts to find an existing object with the specified name and class. Returns the object on success or None on failure.

bool IsPendingKill ( ) [non-static] 

Returns whether the object is pending kill and about to have references to it NULLed by the garbage collector.

name GetPackageName ( ) [non-static, non-native] 

Returns the name of the top-most package this object resides in. The name returned is the name of the package the object instances was saved in. All object instances created at runtime will return the map rather than their actual package. To get the package name of a class use either:

SomeInstance.class.getPackageName()

or:

string(SomeInstance.class.Outer)

Configuration and Localization

string Localize (string SectionName, string KeyName, string PackageName) 

Attempts to read the value of KeyName in section SectionName of the locatization file PackageName.<language>, where <language> is configured in the Language value under [Core.System] in UTEngine.ini.

SaveConfig ( ) [non-static] 

Saves the values of all config and globalconfig properties of this instance as the new default values in the corresponding INI file.

StaticSaveConfig ( ) 

Saves the current default values of all config and globalconfig properties of this class in the corresponding INI file.

bool GetPerObjectConfigSections (class SearchClass, out array<string> out_SectionNames, optional Object ObjectOuter, optional int MaxResults) 

Retrieve the names of sections which contain data for the specified PerObjectConfig class. MaxResults defaults to 1024 if omitted.
ObjectOuter is the Outer to use for determining which file to look in. Specify the same object that is used when creating the PerObjectConfig objects that sections are being retrieved for. (PerObjectConfig data is generally stored in a file named after the Outer used when creating those objects, unless the PerObjectConfig class specifies a config file in its class declaration) Specify None to use the transient package as the Outer.

More configuration-related functions may be implemented in a later patch.

State-related Functions

These functions are all non-static. See Object (UT3) for a description of the events mentioned here.

GotoState (optional name NewState, optional name Label, optional bool bForceEvents, optional bool bKeepStack) 

Transitions to the desired state and label if specified, generating the EndState event in the current state if applicable and BeginState in the new state, unless transitioning to the same state. If bForceEvents is set to true, Begin/EndState events are generated even if the state doesn't change.
Usually the entire state stack is cleared when using GotoState, but if bKeepStack is set to true, the stack stays intact and states can still be popped off as before the GotoState call.

bool IsInState (name TestState, optional bool bTestStateStack) 

Checks the current state and determines whether or not this object is actively in the specified state. This also works with inherited states.
If bTestStateStack is set to true, the state stack is checked as well. This check does not support inherited states in the stack, though.

bool IsChildState (name TestState, name TestParentState) 

Returns true if TestState derives from TestParentState.

name GetStateName ( ) 

Returns the current state name.

PushState (name NewState, optional name NewLabel) 

Pushes the new state onto the state stack, setting it as the current state until a matching PopState() is called. Note that multiple states may be pushed on top of each other. You may not push the same state multiple times.
This will call PausedState on the current state and PushedState on the new state being pushed onto the stack. It will not call BeginState or EndState.

PopState (optional bool bPopAll) 

Pops the current pushed state, returning execution to the previous state at the same code point. PopState() will have no effect if no state has been pushed onto the stack.
This will call PoppedState on the state being popped off the stack and ContinuedState on the new top-of-stack state. It will not call BeginState or EndState and the popped state will resume exactly at the spot where PushState was previously called.

Debugging Functions

ScriptTrace ( ) 

Dumps the current script function stack to the log file, useful for debugging.

name GetFuncName ( ) 

Returns the current calling function's name, useful for debugging.

SetUTracing (bool bShouldUTrace) 

Enables/disables script function call trace logging.

bool IsUTracing ( ) 

Returns whether script function call trace logging is currently enabled.

DumpStateStack ( ) [non-static] 

Logs the current state stack for debugging purposes.

Other Functions

string TimeStamp ( ) 

Returns a string containing a system timestamp.

LogInternal (coerce string S, optional name Tag) 

Writes a message to the log.
This function should not be called directly. Use the `log macro instead, which has the following signature:

`log(coerce string Msg, optional bool bCondition=true, optional name LogTag='ScriptLog')

WarnInternal (coerce string S) 

Same as calling LogInternal(SomeMsg, 'Warning');
This function should never be called directly. Use the `warn macro instead, which has the following signature:

`warn(coerce string Msg, optional bool bCondition=true)

Disable (name ProbeFunc) [non-static] 

Disables a probe function, such as Tick, Touch or HitWall.

Enable (name ProbeFunc) [non-static] 

Enables a probe function.

name GetEnum (Object E, coerce int i) 

Returns the name of an enum constant. For example:

GetEnum(Enum'EPhysics', PHYS_Projectile)

This returns the name value 'PHYS_Projectile', while the typecast expression string(PHYS_Projectile) would result in the string value "6", since enum constants are only "glorified" byte values.