Scripting Custom Brushbuilders

Preliminaries

Prerequisites

• vague knowledge of UnrealScript.
• In particular a passing familiarity with functions, variables and flow control statements and a basic knowledge of the Unreal class structure.
• A little bit of mathematics: geometry, vectors and trigonometry. For more advanced stuff, matrix transformations.
• How to compile a package with ucc.
• read up on BrushBuilder, the parent class

(I knew only JavaScript when I started and fumbled my way with the help of tutorials: I recommend [Chimeric]'s excellent site.)

Code style

Bear in mind that streamlined code isn't necessary here. The user won't mind a few extra clock cycles – she's not having rockets fired at her! Aim for code legibility rather than efficiency.

Terms used

• builder brush means the red builder brush, the red dotted-line brush seen in the editor.
• [UT] refers to your base UnrealTournament directory.
• Names such as MyPackage, MyBuilder, etc are used as examples. If you follow this tutorial feel free to use more sensible names.

Caveat

I don't claim to know or understand the inner workings of UnrealEd. Some of what is presented here is based on observation of UnrealEd's behaviour and experimentation.

The maths bit

A simple brush in UEd is basically a polyhedron of some sort, which need not necessarily be convex. Other types of brush are sheet brushes and compound brushes (by that I mean made from intersecting the builder with several simple brushes).

Whatever the brush looks like, UEd stores it in two parts (see also T3D file):

• A list of vertices: these are simply points in 3D space, stored as co-ordinates or vectors, it's the same thing.
• A list of faces: these are the polygons that make the sides of the brush. A poly is described by a list of the vertices that make up its corners.

What this means is that brushes are made by defining some dots, and then joining them up to make shapes. (The dots part is geometry, or vector algebra depending on how you look at it. The shapes part is topology.)

• Order of the vertex list: They must be in sequence, or the poly will show diagonals, and essentially will be 'folded up' — think of making the poly's outline out of a piece of wire, following the order of the vertices. The engine draws the poly inside that wire like a soap bubble.
  
• Direction: The direction in which the list travels round the poly determines which way the poly will face. More on how this works below.
• Starting vertex: I believe that UEd treats the side formed by the first two vertices in the list as that poly's vertical – this sets the orientation of the poly's texture.

While the brushes may be concave, the individual polys must be convex. The Unreal engine currently has a maximum of 16 vertices per poly, and if you try to make one with more than this UEd will automatically split it.
The Unreal engine uses a left-handed co-ordinate system. This just means that the y-axis goes the opposite way to how it did at school!

Getting started

There are two ways to go about writing a new buidler: you can write a new class, or you can modify an existing one. The demonstration portion of this tutorial will work with either approach.

Making a new class

UnrealEd is designed to be modular. When it loads, it looks for subclasses of object.brushbuilder, and whatever it finds, it displays in the interface. You can see the native builders (and mine, if you've installed the Tarquin Brush Builder pack) in the actor browser if you un-check the 'actor classes only' box.
What this means is that all you need to do is write the class, compile it, and add the package to the list in UnrealTournament.ini — UEd will handle displaying the icon and making the property dialog box.
Make a new directory tree [UT]\MyPackage\Classes. The package name can be anything you like. Create a new text file named MyBuilder.uc in the Classes directory, and paste into it the code below:

// A blank builder
class MyBuilder
    extends BrushBuilder;
var() int Sides;
var() bool AlignToSide;
var() name GroupName;
function bool Build()
{
    if( Sides < 3 )
        return BadParameters("Bad input.");
    BeginBrush( false, GroupName );
    return EndBrush();
}
defaultproperties
{
Radius=0.000000
Sides=4
AlignToSide=True
GroupName=AName
BitmapFilename="AFilename"
ToolTip="A blank builder."
}

Add or change variables as you see fit, duplicating changes in the declaration and the defaultproperties section. The name declared by the class statement must match the filename so change that too if you've renamed the file.

The value of GroupName makes very little difference as far as I can tell, but you may as well put something that describes the builder.
UEd looks in [UT]\system\editorres for a file named AFilename.BMP. If UEd can't find a file of this name, or if the value is blank or the line deleted, UEd simply displays a grey button for the builder in the toolbox. Change this value to the name of a bitmap file in that directory to see an icon in the interface. If you want to make an icon yourself, they are 30 by 30, with a background of 50% grey.
Lastly, change the tooltip to whatever you like.

Compile your package with ucc, and add the following line unrealtournament.ini at the end of the [Editor.EditorEngine] section, after the other 'EditPackages' lines:

 EditPackages=MyPackage

Run UEd, and the button for new builder should be in the toolbox. Open the actor browser, uncheck the 'actor classes only' box and look for your builder under object.brushbuilder. Rather than work in a text editor and have to compile to see changes, it's easier to make changes in UEd and see how they work straight away. It's now an existing class, so move on to the next section!

Modifying an existing class

You can modify the script of an existing brush builder, recompile in UEd, use the builder and save your map, and as long as you don't save the package the next time you run UEd the builder you changed will be back to its old self. However, changing, adding or removing input variables to the builder code will upset UEd to the point of crashing!
This approach can be useful if you want to try an idea quickly, or you want to script a complex brush for a specific purpose.

If you've built your own class and are now modifying it within UEd, you should have added all the input variables the builder will need. Keep a text editor running, and paste your updated script into a different file (say MyBuilder.txt) for backup. When you are happy with the changes, quit UEd, open MyBuilder.uc and copy the script across from MyBuilder.txt. Remember that the version pasted from UEd won't have a defaultproperties section, so keep the one from MyBuilder.uc.

It's at this stage you can add or change input variables' names, type and default value.
Rebuild MyPackage.u with ucc (remember you have to delete the original, ucc won't overwrite files), and run UEd to see the new version.
I found the easiest way to script a builder was to edit its script in UEd, recompile from UEd and see the results straight away.

Anatomy of a builder

Class declaration

Defines the class name. The class must be a subclass of brushbuilder. See Class Syntax.

Input parameters

Variables that the user will set in the parameter dialog box, such as Height, Sides, AlignToSide, IWantFriesWithThis. These are declared as class variables thus:

var() float Height, OuterRadius, InnerRadius;
var() int Sides;
var() bool AlignToSide;

You can define and use enumeration type variables (out of this tutorial's scope). Variables defined here should be matched in the defaultproperties section, or they will hold peculiar values when first seen in the parameter dialog. See Variable Syntax and Displaying Variables in UnrealEd for details about how different variable types show up in the editor.

Procedural functions

Any actions your builder may need to do repeatedly can be called in a function from the build function. For example, the cylinder builder's build function calls a function to build a cylinder, may call it again to build an inner cylinder if the overal brush should be hollow, and then builds polys for the two ends.

Build function

This function is called by UEd when you left-click the builder icon, or press 'Build' in the parameter dialog box. Essentially, it's the main body of the builder script.

function bool Build()

Some of the Epic builders use the following, which is identical to UnrealScript:

event bool Build()

Default properties

This section goes at the end of the builder script, and contains default values for the input parameters, the tooltip text, and the filename for the icon bitmap.

defaultproperties
          {
          [parametername]=[parametervalue]
          BitmapFilename="[filename]"
          ToolTip="[tooltiptext]"
          }

UEd looks in {BaseDirectory?}\System\Editorres for a file named [filename].BMP. If the value is blank, or UEd can't find the file, the button will be grey with no picture.

Functions

The functions are used to build the brush are native functions of the BrushBuilder class that the current builder has inherited.

A little example (ued2)

'Half cube' brush builder

//-----------------------------------------------------------
//Half cube
//-----------------------------------------------------------
class Halfcube extends BrushBuilder;

var() name GroupName;
var() int Size;

event bool build()
{
BeginBrush( false, GroupName );

//So each time we call the vertex3f function, the created vertex is given a number,
//it's the number we use in the poly functions..
//First vertex is number 0, and so on

vertex3f(0,0,0); //0
vertex3f(Size,0,0); //1
vertex3f(0,Size,0); //2
poly3i(-1,0,1,2); // the base poly - the first parameter indicates the "front" of the face
vertex3f(0,0,Size); //3
vertex3f(Size,0,Size); //4
vertex3f(0,Size,Size); //5
poly3i(1,3,4,5); // the top poly
//
poly4i(-1,3,0,2,5); // the three sides.
poly4i(-1,3,4,1,0); //
poly4i(-1,2,1,4,5); //

return endbrush();
}

DefaultProperties
{
Size=128
GroupName=Halfcube
BitmapFilename="BBHalfCube"
ToolTip="half a cube"
}

Tips And Tricks

Naming polys

Mychaeel came up with a way to use an expression to set the ItemName parameter in the poly building functions. First declare a name variable in your BrushBuilder subclass; then use SetPropertyText to set it using an arbitarily constructed string value; then take the name value from the variable you declared.

// declare a name variable:
var name DynItemName;  

// set it as needed:
SetPropertyText( "DynItemName" , string(i) );

// use the DynItemName variable in the poly call:
Poly4i( sgn , Va2 , Vb2 , Vb1 , Va1 , DynItemName , PolyFlags );

Running Unrealscript in the Editor

Note: This won't work with UnrealEd 2.0 or earlier, because they don't have the AllObjects function.

A brushbuilder is an Object, and is one of the few (very few) classes in which you can run UnrealScript within the editor. The editor calls the Build() function of a brushbuilder to cause it to create a brush. You are not required to use this function to make a brush, however, and can do virtually anything you like with it! Remember that UnrealEd and the actual game run using mostly the same engine - as a result you can essentially treat your brushbuilder as any Object. Basically, anything you can do in the game, you can do with the brushbuilder.

Generally the first thing you will want to do in the Build script is to find an actor to do your dirty work. Objects can't use Spawn or a myriad of other things. It is quite simple to do so:

// A base class you can extend to call code within the editor.
class EditorScript extends BrushBuilder;

function actor LocateActor()
{
  local actor I,X;
  foreach AllObjects( class'Actor', I ) X = I;
  return X;
}

event bool Build()
{
  ExecuteScript( LocateActor() );
  return false;
}

function ExecuteScript( actor A )
{
  // Do whatever you want here, or ideally subclass this to make your own custom functionality.
}

Due to the way UnrealEd orders objects, in my experience this has always returned the camera. However, you cannot make it faster by changing the AllObjects to just look for cameras. Although a camera is of the class Engine.Camera, it doesn't not like being referred to as such and if you attempt to cast it it will return none. At first I thought having the camera would be handy, because it's location will always be the location where you are in the 3D view.. obviously useful if you plan to spawn things, etcetera. However, the Camera does not appear to actually change it's location variable... I haven't found any way of finding the location of the camera view in the editor. Speed optimizations aren't very important in the editor, but if you don't care what kind of actor you get you can improve the LocateActor function like so:

// This executes faster and generally, if not always, returns the LevelInfo.
function actor LocateActor()
{
  local actor I;
  foreach AllObjects( class'Actor', I ) return I;
}

Now that you have an actor, you can call functions from it to do whatever you like. If you have need of more complex functionality, you can create your own actor class, then use the actor class you found using LocateActor() to spawn your own actor, which can then be instructed to do whatever you like. Note that actors spawned in this manner will not have some functions such as tick executed on them in the editor.

As stated in the section on general brushbuilder scripting, you can accept parameters simply by defining variables like you would in any other Unrealscript. However, you cannot specify a group name. EG:

// These will not show up as parameters, but can still be used within the script.
var float NoDecl;
var(Cats) float NumberofCats;
var(Raindrops) float ChanceofCatbeingWetandAngry;

// These variables will show up as parameters, and UnrealEd will intelligently create the appropriate form of text box/whatever as appropriate for the type of variable.
var() int NumberofFoodPiecesinBowl;
var() string BDLYNAMDVAR;
var() bool bjkfLvpqrjstrKfsdcvIlikehungariannotation;

Note that changes made by your function or by the indirect consequences of your functions will actually affect actors in the level! If you save the level, those changes will be permanent, and Undo will not work reliably against these changes. Sometimes it will, sometimes it won't, depending on your code. You can still recover things by loading from your last save, however. Save really often, and be extremely careful with calling the destroy function on things.

As a side-note, calling destroy on things also tends to cause General Protection Faults, but it will not always do this. Sometimes it will also refuse to save your level after you have destroyed something through script. I believe that this is due to the lack of the Tick function. As you may know, Destroy() is a special type of latent function and the actor is not actually destroyed until the end of the tick, though it is flagged as bDeleteMe and as a result many operations refuse to touch it, knowing that it has already been declared 'dead.'

Comments

Foxpaw: I refactored the bit about brushbuilders being used for custom editor functions, and I added what I've learned about them, but I think this topic deserves it's own page. It is technically a custom brushbuilder, but I don't think that people will find it here. I already had the idea and decided to read up about the brushbuilder stuff to see if anyone else had tried it, but otherwise I doubt a person looking to run unrealscript in the editor would look here for the answer.

Foxpaw: What I said above about the cameras may or may not be true - I just remembered that I have a class in a package which is also called Camera. Apparently it doesn't conflict or anything though... but it may have caused the cast to refer to my camera class instead of Engine.Camera. If someone tests this please update it above or post here to confirm it.

Foxpaw: I've made another discovery. Brushbuilders are not instantiated when called - they persist. A brushbuilder will have the same settings when you run it as it did when it stopped running last time, or the defaults if it's the first run. This may be obvious to some, but I thought I'd mention it.. I ended up with strings being piled up on top of each other.

Dushnok: I'm very newbish at uscript but I added the little example (halfcube) . Just for newbies like me Do you think it's ok ?

EntropicLqd: Nice example. I'd be inclined to define all the points first and then the polygons afterwards. Question though - The first parameter indicates the "front" of the face by specifying the direction the vertices should be traversed. Presumably the sign is reversed if the vertices are specified in reverse order. e.g. The following are equivalent:

poly3i(-1,0,1,2);
poly3i(1,2,1,0);

Is there a "best way" to specify the order of the vertices?

Tarquin: the vector made by the first two vertices appears to give the orientation of the texture, but I've not managed to pin this down exactly.

---

Category To Do – Badly needs a more "user-friendly" format, with some pictures.