Difference between revisions of "Legacy:Commandlet"

Latest revision as of 15:49, 29 April 2010

This is a legacy page imported from the old Unreal Wiki. Please avoid editing or moving it and improve Commandlet instead.

UnrealScript Commandlet (command-line applet) class.

In UnrealEngine generations 1 and 2, commandlets are executed from the ucc.exe command line utility, using the following syntax:

UCC.exe package_name.commandlet_class_name [parm=value]...

for example:

UCC.exe Core.HelloWorldCommandlet
UCC.exe Editor.MakeCommandlet

In addition, if you list your commandlet in the public section of your package's INT file (see Engine.int for example), then your commandlet can be executed without requiring a fully qualified name, for example:

UCC.exe MakeCommandlet

As a convenience, if a user tries to run a commandlet and the exact name he types isn't found, then ucc.exe appends the text "commandlet" onto the name and tries again. Therefore, the following shortcuts perform identically to the above:

UCC.exe Core.HelloWorld
UCC.exe Editor.Make
UCC.exe Make

In UT3 you need to use UT3.exe with the parameter "run", since UCC.exe no longer exists. Note that the game only appears to load commandlets from packages that reside in the game's installation directory, not the "My Games\Unreal Tournament 3" directory.

It is perfectly valid to call the Main method of a commandlet class directly, for example from within the body of another commandlet.

Commandlets are executed in a "raw" UnrealScript environment, in which the game isn't loaded, the client code isn't loaded, no levels are loaded, and no actors exist.

You can load objects from packages. (e.g. levels, sound packages or code packages, this includes actors used in maps) However, you can only create non-Actor objects because otherwise UCC exits with a general protection fault since there's no level to put the actor in.

This example loads a map and prints out the map's name and author:

class SandboxCommandlet extends Commandlet;
 
function int Main(string TextParameters) {
 
  local LevelInfo LevelInfo;
  LevelInfo = LevelInfo(DynamicLoadObject(TextParameters $ ".LevelInfo0", class 'LevelInfo'));
 
  Log("Information about" @ TextParameters $ ":");
  Log("  Title: " @ LevelInfo.Title);
  Log("  Author:" @ LevelInfo.Author);
  }

Output:

{{innerbox| ucc Sandbox.SandboxCommandlet CTF-Face
}}

----
ucc.exe: UnrealOS execution environment
Copyright 1999 Epic Games Inc
----

Executing Class Sandbox.SandboxCommandlet
Information about CTF-Face:
  Title:  Facing Worlds
  Author: Cedric 'Inoxx' Fiorentino

Properties[edit]

string HelpCmd (localized) 

Command name to show for "ucc help".

string HelpOneLiner (localized) 

Command description to show for "ucc help".

string HelpUsage (localized) 

Usage template to show for "ucc help".

string HelpWebLink (localized) 

Hyperlink for more info.

string HelpParm[16], HelpDesc[16] (localized) 

Parameters and descriptions for "ucc help <this command>".

bool LogToStdout 

Whether to redirect log output to console stdout. (default is true)

bool IsServer, IsClient, IsEditor 

Whether to load objects required in server, client, and editor context. (default is true for all)

bool LazyLoad 

Whether to load objects immediately, or only on demand. (default is true)

bool ShowErrorCount 

Whether to show standard error and warning count on exit. All calls to Warn() and certain calls to Log() are counted as warnings, e.g.:

log("a warning", 'Error');

log("another warning", 'Warning'); warn("and another one"); (default is false)

bool ShowBanner 

Whether to show Unreal banner on startup. (default is true)

Methods[edit]

int Main(string Parms) (native) 

The main function. Put your code here. (This function is only declared as native event, not as final.)

Sample Commandlet[edit]

This is an example included in the Core package of UT.

//=============================================================================
/// UnrealScript "hello world" sample Commandlet.
///
/// Usage:
///     ucc.exe HelloWorld
//=============================================================================
class HelloWorldCommandlet
    extends Commandlet;
 
var int intparm;
var string strparm;
 
function int Main( string Parms )
{
    log( "Hello, world!" );
    if( Parms!="" )
        log( "Command line parameters=" $ Parms );
    if( intparm!=0 )
        log( "You specified intparm=" $ intparm );
    if( strparm!="" )
        log( "You specified strparm=" $ strparm );
}
 
defaultproperties
{
     HelpCmd="HelloWorld"
     HelpOneLiner="Sample"
     HelpUsage="HelloWorld"
     HelpParm(0)="IntParm"
     HelpParm(1)="StrParm"
     HelpDesc(0)="An integer parameter"
     HelpDesc(1)="A string parameter"
}

You can run this commandlet with:

UCC Core.HelloWorld intparm=123 strparm=bla bla
UCC Core.HelloWorld intparm=123 strparm="bla bla"

Note: The first one returns only "bla" as strparm, the second one prints out the full string.

Returning values from ucc executable[edit]

The return value from event Main() is not used. If ShowErrorCount = True it will return 1 if ErrorCount != 0. To create an error you can simply do:

Log("Bla", 'Error');

Known Subclasses[edit]

UnrealScript Commandlets[edit]

(not available in UT2003)

• HelloWorldCommandlet – example commandlet (see above)
• SimpleCommandlet – a test commandlet

Native Commandlets[edit]

• BatchExportCommandlet – exports objects from packages
• CheckSumCommandlet
• ChecksumPackageCommandlet
• CheckUnicodeCommandlet
• CompressCommandlet
• ConformCommandlet – used to make packages network-compatible
• DataRipCommandlet
• MakeCommandlet – Compiles UnrealScript sources to .u files
• MasterCommandlet – can be used to build UMOD installer files
• MasterServerCommandlet
• MergeDXTCommandlet
• PackageFlagCommandlet
• PS2ConvertCommandlet
• ServerCommandlet – Runs a dedicated server
• UpdateServerCommandlet
• UpdateUModCommandlet – can list or modify the content of a UMOD file

UT2003 And Above[edit]

• AnalyzeBuildCommandlet – prints out the content of all packages (only execute if you have lots of time ;))
• AnalyzePackageCommandlet – prints out information about memory usage of a package (e.g. maps)
• ConvertMaterialCommandlet
• DumpIntCommandlet – dumps all localized variables to an .int file (back up the existing .int first!)
• MasterMD5Commandlet – handles the md5 table for package security
• UTVCommandlet – used for running a UTV proxy server (requires UTV to be installed, see the Unreal Tech Page)

(the following are not specified in the .int files, so you need to explicitely specify the package)

• Editor.BatchImportCommandlet – opposite of BatchExportCommandlet
• Editor.CheckUnicodeCommandlet
• Editor.CompareIntCommandlet
• Editor.CutDownContentCommandlet
• Editor.StripSourceCommandlet – please be nice and don't use it

UT2004 Only[edit]

• DumpConfigCommandlet – Dumps the default configuration of all classes in all loadable U files to Dump*.ini
• ExportCacheCommandlet – Exports the cacheable class properties from the specified package files.
• GroupRepairCommandlet
• MapConvertCommandlet
• MergeIntCommandlet
• RearrangeIntCommandlet
• RebuildCommandlet
• TextureInfoCommandlet
• TextureLODCommandlet
• TextureStripCommandlet
• UModUnpackCommandlet

(incomplete list, some may need a package name specified)

(the following are not specified in the .int files, so you need to explicitely specify the package)

• Editor.CheckTexturesCommandlet – Checks for corrupted textures in texture packages

UT3 Only[edit]

Run UT3.exe with commandline parameter "help list" if you need a list with commandlets in UE3.

Discussion[edit]

MythOpus: So you can create Commandlet's with Uscript? I was wondering if that means you can create a custom commandlet that would delete a specified file and then rebuild it...

Wormbo: Commandlets can use the same features like any other UnrealScript class, except that there's no game environment to spawn actors in. In other words: Except for writing to the main log file there's nothing a commandlet can do to the file system.

DaWrecka: So you couldn't write a commandlet that would, for example, alter the LightBrightness of every light in a passed .UT2 (for use in a Darkmatch gametype) and save it with a new filename?

T-1: Hey, Wrecka. You might be able to save the information in a log file and then have a stand-alone program that strips the log information. There was a mod utility that did this, IIRC. Bold text