Wikis / Unreal Wiki / UE1:UE1PreProcessorCommandlet

About

This is a preprocessor in the form of a ucc commandlet. Right now it's only available for UT1, but I'm working on a version for Unreal 1. For unknown reasons it gives me lots of errors on Unreal 1 224 sources.

Install

Copy files in the archive to your <UTdir> folder.

Download

As always source code is included in zip file.

Unreal Tournament

link: UEnginePPC v. 0.5.296 for UT(~103kb)

Rune

link: UEnginePPC v. 0.3.168 for Rune (~633kb)

Unreal

Preprocessor is already included in patch 227 for Unreal 1.

Usage

In order to use the preprocessor you have to call ucc with the following parameters:

ucc uengineppc.parse project=[<project_dir>/<project_file>]  [-option...] [-globals...]

Parameters

• <project_dir> - relative project directory.
• <project_file> - file (.upc extension) containing all options. If file is detected, no further modifiers are checked

Options

Globals

All other parameters will be considered to be global variables. If = is not detected, global variable is equal null. Example:

   val1=1 val val2=3 

Directives

Currently supported directives are:

Notice that all variables used in directive `if and ternary operation are parsed in the following order:

1. Returns value from global variables if correct name is found, otherwise...
2. Returns value from local variables if correct name is found, otherwise...
3. Assumes that name is value.

`import details:

As type you can use only TEXTURE and SOUND. If the extension is uax or utx the preprocessor will create #exec obj load instead of #exec type import. For example code below:

`import(tex,pcx,TEXTURE,HUD)

will make the preprocessor iterate through all files in folder <UT>/<Project>/tex in search for all *.pcx files. When a file with extension pcx is found, the preprocessor will create a UScript #exec directive to import texture into group HUD. Group, LodStet, Flags and Package parameters are optional. Result will look like:

#exec TEXTURE IMPORT NAME=Tex001 FILE="tex/Tex001.pcx"
#exec TEXTURE IMPORT NAME=Tex002 FILE="tex/Tex002.pcx"
#exec TEXTURE IMPORT NAME=Tex003 FILE="tex/Tex003.pcx"

`namespace details:

Namespace can be useful to replace large parts of text, without need of use `write and `define directives. For example if you write directive:

`namespace(__SOMECLASS__,class'SomeClass'.static)

and use it in code:

__SOMECLASS__.SomeFunction();

parsed code will change to:

class'SomeClass'.static.SomeFunction();

You can also use macros:

`namespace(__SOMECLASS__,class'__SELF__.SomeClass'.static)

assuming that your package is MyPackege this directive means:

`namespace(__SOMECLASS__,class'MyPackege.SomeClass'.static)

Namespace works also in `require and `include directive.

Operators in conditional statement and write directive

Unreal Engine version

Since 0.2.106 UE1PreProcessorCommandlet can check the Unreal Engine version. This will be useful once the preprocessor is stable and compiled to U1.

`if(__UENGINEVERSION__==436)
//some UT436 specific code
`endif

Macros

Macros are in fact hardcoded constants. Each macro will write something in the currently parsed .uc file. Currently supported macros are:

• __FILE__ - will write name of currently parsed file, usable in conditional statements
• __CLASS__ - will write name of currently parsed class, usable in conditional statements
• __DATE__ - will write time
• __SELF__ - will write current package, usable in conditional statements
• __UENGINEVERSION__ - will write Unreal Engine version, usable in conditional statements
• __NUMERATE_CPP__ - replaces itself with a number and increments a counter (used in native functions). It's value depends on native_offset
• __LINE__ - will write current line (parsed output)
• __RELATIVE_LINE__ - will write current line (unparsed input)

Functions

You can also define functions in new section of project file, eg.:

[functions]
`log($value)=log($value,'ResidualDecay')

Now when you call in code:

`log("Log message");

the parser will change it to:

log("Log message",'ResidualDecay');

Tips:

• Avoid using functions with similar names - eg.: `log and `logx will screw up result code.
• Avoid using parameters with similar names in one function - eg.: `log($value1, $value2); will not work too good :).
• Functions can only be defined in project file.

Eventually all bugs listed above will be eliminated (current implementation was written in ~5-10 minutes).

Project file

Project file must have upc extension, and 'path' must be relative to ucc.exe location. Default location for files with preprocessor Unreal Script files is:

<project_folder>/classes/preprocessor

parsed .uc files will be stored in:

<project_folder>/classes

Here's all commands for project file.

[project]                 - project information
path=path                 - path to project
debug=true                - turns on debug mode (prints every operation on parsed .uc)
make=true                 - if true, ucc commandlet will run make after parsing all files
make_ini=make.ini         - ini used in ucc make commandlet
clean=true                - if true, will delete preprocessor directives
output=folder             - override default output folder where parsed .uc files are written
input=folder              - override default input folder where parsed .uc files are stored
bIsPackage=true           - when defining path you may type only name of package. Path will be detected automatically.
bIniVersion=true          - if true, macro __UENGINEVERSION__ will return uengine version saved in INI (FirstRun param), if false, it'll return version saved in engine.
bDeleteLog=true           - scans UScript source for log functions and deletes it
native_offset             - offset for __NUMERATE_CPP__ macro (starting number)
bForce=true               - if true forces all source .uc files to be parsed
printnamespace=true       - will print global namespace if true
bClearOutput=true         - will delete all output files before parsing input
printmacros=true          - will print all global macros if true
native_offset=1600        - offset when using __NUMERATE_CPP__ macro
 
[globals]                 - group containing global variables for whole project
someglobal=somevalue      - global variable (sample)
 
[namespace]
some_namespace=some_value - declares namespace 'some_namespace' with value equal 'some_value' (for usage see `namespace details)
 
[functions]
`some_function($some_value)=log($some_value,'ResidualDecay') - declares function `some_function

example:

[project]
path=../MyProject/
debug=true
make=true
make_ini=make.ini
clean=true
output=classes
input=classes/preprocessor
bIsPackage=false
 
[globals]
global_value1=test1
global_value2=test2

Example

Let's say you have project file in <UDir>/system called REmitter.upc with content:

[project]
path=../REmitter/
debug=true
make=false
make_ini=make.ini
clean=true
output=classes
input=classes/preprocessor
printglobals=true
 
[globals]
__NUM_NATIVES__=1

and classes:

REmitterBase.uc

`process
`include(classes/includes/default_header.uc,true)
// Base class for emitter related actors.
// Quaternion implementation originally written by UsAaR33.
class REmitterBase extends Actor native;
 
struct Quat
{
	var() config float W, X, Y, Z;
};
//converts rotator to quaternion
native`write(__NUM_NATIVES__==1?(2330):) static final function Quat RotationToQuat( rotator R, bool bHighPrecision);

default_header.uc

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Copyright 2005-2008 Dead Cow Studios. All Rights Reserved.
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Coder: Raven
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Last revision: __DATE__
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You run preprocessor and:

1. directive `process is found, so preprocessor knows that this class has to be parsed.
2. directive `include is found. Preprocessor embeds file default_header.uc and parses it
3. macro __DATE__ is found and current date is inserted at its place
4. directive `write is found. Because expression evaluates to true, first value - (2330) - is inserted at it's place

output .uc file will look like this:

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Copyright 2005-2008 Dead Cow Studios. All Rights Reserved.
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Coder: Raven
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Last revision: 21-9-2008 20:1
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Base class for emitter related actors.
// Quaternion implementation originally written by UsAaR33.
class REmitterBase extends Actor native;
 
struct Quat
{
	var() config float W, X, Y, Z;
};
//converts rotator to quaternion
native(2330) static final function Quat RotationToQuat( rotator R, bool bHighPrecision);

Changelog

• v 0.5.296
  • Added two new macros
• v 0.5.262
  • Added new advanced functions to define in new section of project file
• v 0.4.194
  • Added new `remove.start and `remove.end directives to remove larger parts of code
  • Namespaces are now usable in `include and `require directives
• v 0.4.194
  • Added new global namespace
• v 0.3.185
  • Added new __NUMERATE_CPP__ macro
  • Added new commadline option -force
  • Added new project option bForce
  • Various updates and fixes
• v 0.3.168
  • Fixed bug in GetVariable function. Variable search is aborted if name is NULL.
• v 0.3.150
  • added option to delete log calls out of UScript source
• v 0.3.144
  • added bIniVersion to commandline and project file (changes the way macro __UENGINEVERSION__ works)
• v 0.2.123
  • new directive `else if
• v 0.2.106
  • new directive `namespace
  • new macro __UENGINEVERSION__
  • new macro __SELF__
  • macros can be used in conditional statements
• v 0.2.56
  • new directive `import used to create #exec directive for large number of textures/sounds
• v 0.1.35
  • fixed directive `write bug (now it doesn't ignore defined variables)
• v 0.1.5
  • added new option bIsPackage
• v 0.1.4
  • fixed bug with inline `write directive
• v 0.1.1
  • initial release