UE1:UE1PreProcessorCommandlet

About

This is preprocessor in form of ucc commandlet. Right now it's only available for UT1, but I'm working on version for Unreal 1. From 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)

Usage

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

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

Parameters

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

Options

option	description	override by project file
-clean	deletes preprocessor directives from .uc file	yes
-debug	turns on debug mode (prints every operation on parsed .uc file)	yes
-printglobals	prints all global variables	yes
-normalizeeol	tries to find \r and \n and change them into \r\n	yes
-bIsPackage	when defining <project_dir> you can type only name of package. Path will be detected automatically.	yes
-bIniVersion	macro __UENGINEVERSION__ will return uengine version saved in INI (FirstRun param), if false, it'll return version saved in engine.	yes
-deletelog	scans UScript source for log functions and deletes it	yes
-force	forces all source .uc files to be parsed	yes

Globals

Each other parameter will be concidered as global variable. If = is not detected, global variable is equal null. Example:

   val1=1 val val2=3

Directives

Currently supported directives are:

directive	description
`process	should be in the first line of .uc file. Tells preprocessor to parse file
`include(file)	embade file in the currently opened .uc (do not parses it)
`include(file,false)	embade file in the currently opened .uc (do not parses it)
`include(file,true)	embade file in the currently opened .uc and parses it
`require(file)	embade file in the currently opened .uc (do not parses it). If required file doesn't exists, it stops parsing current file and produce error.
`require(file,false)	embade file in the currently opened .uc (do not parses it). If required file doesn't exists, it stops parsing current file and produce error.
`require(file,true)	embade file in the currently opened .uc and parses it. If required file doesn't exists, it stops parsing current file and produce error.
`define(name)	defines variable name (used in `ifdef and `ifndef directives)
`define(name,value)	defines variable name with specified value (used in `if and ternary operation)
`undef(name)	removes name from local definitions
`error(name1,true)	produces error message and exits commandlet
`error(name1)	produces error message and stops parsing current file
`warn(name1)	produces warning message
`log(name1)	produces message
`ifdef(name)	evaluates to true if variable name is defined
`ifndef(name)	evaluates to true if variable name is not defined
`if ([expression1] [operator] [expression2])	checks to see if the first condition is true by comparing expression1 to expression2 using the operator.
`else if ([expression1] [operator] [expression2])	checks to see if the first condition is true by comparing expression1 to expression2 using the operator, only if first condition is false..
`else	part of conditional statement
`endif	ends conditional statement
`write(name)	writes defined variable name
`write(name1==name2option1:option2)	if statemente evaluate to true (variable name1 equals variable name2) writes option1 otherwise writes option 2
`write(name1<>name2?option1:option2)	if statemente evaluate to true (variable name1 does not match variable name2) writes option1 otherwise writes option 2
`write(name1>name2?option1:option2)	if statemente evaluate to true (variable name1 is greater then variable name2) writes option1 otherwise writes option 2
`write(name1<name2?option1:option2)	if statemente evaluate to true (variable name1 is less then variable name2) writes option1 otherwise writes option 2
`write(name1?option1:option2)	if statemente evaluate to true (variable name1 is defined) writes option1 otherwise writes option 2
`import(directory,extension,type,group,lodset,flags,package)	can be used to import textures/sounds from chosen directory
`namespace(name,value)	defines namespace name with specified value. It's combination of `define and `write. If namespace will be detected, it'll be replaced by value, without need of using `write
`remove.start	everything below this directive will be deleted
`remove.end	disables `remove.start

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

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

`import details:

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

`import(tex,pcx,TEXTURE,HUD)

Will make preprocessor iterate through all files in folder <UT>/<Project>/tex in search for all *.pcx files. When file with extension pcx will be found, preprocessor will create 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 `innclude directive.

Operators in conditional statement and write directive

operator	description	type
==	equal	string, float, integer, bool
<>	not equal	string, float, integer, bool
>=	greeter or equal	float, integer
<=	less or equal	float, integer
<	less	float, integer
>	greater	float, integer
!	negation, works as `ifndef

Unreal Engine version

Since 0.2.106 UE1PreProcessorCommandlet can check Unreal Engine version. This will be useful once preprocessor will be 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 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 Unrean Engine version, usable in conditional statements
__NUMERATE_CPP__ - replaces it self with a number and increment a counter (used in native functions). It's value depends on
__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");

parser will change it to:

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

Tips:

Avoid using functions with similar name - eg.: `log and `logx will screw up result code.
Avoid using parameters with similar name 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 to 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 informations
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 can 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
deleteinput=true          - will delete all output files before parsing input
printmacros=true          - will print all global macros if true
 
[globals]                 - group contatin 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:

directive `process is found, so preprocessor knows that this class has to be parsed.
directive `include is found. Preprocessor embade file default_header.uc and parses it
macro __DATE__ is found and current date is inserted at its place
directive `write is found. Because expression evaluates to ture 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