There is no spoon

UE1:UE1PreProcessorCommandlet

From Unreal Wiki, The Unreal Engine Documentation Site
Revision as of 09:58, 19 December 2009 by Raven (Talk | contribs) (→‎Unreal)

Jump to: navigation, search

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)

Unreal

Preprocessor is already included in patch 227 for Unreal 1.

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:

  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 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 itself with a number and increment 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");

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
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 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:

  1. directive `process is found, so preprocessor knows that this class has to be parsed.
  2. directive `include is found. Preprocessor embade 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 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
Retrieved from "https://wiki.beyondunreal.com/UE1:UE1PreProcessorCommandlet?oldid=40349"