BrushBuilder

UT :: Object (UT) >> BrushBuilder (Package: Editor)

UT2003 :: Object >> BrushBuilder (Package: Editor)

This is the base class for UnrealEd's Brushbuilders (mappers should read that page for information on how to use the tools). The rest of this page is more of interest to coders who want to understand or make new brushbuilders.

UnrealEd

The brushbuilder buttons that appear in UnrealEd's toolbox are generated by subclasses of this base class. UnrealEd creates an interface button for all the first non-abstract child classes, ie:

Object
  +- BrushBuilder 
       +- MyChildClass -- is loaded
       |    +- MyGrandchildClass  -- isn't loaded
       +- MyAbstractChildClass -- abstract, not loaded
            +- MyOtherGrandchildClass -- is loaded

Functions are inherited as you'd expect, but properties defined in a parent class won't appear in the parameters. In other words, only properties that would appear under the classname if this were a regular actor appear in the brushbuilder parameters box.

Interface

Each script needs a Build() event; this is called when the user clicks the interface icons or the Build button in the parameters window. The parameters seen here correspond to editable variables declared in the class.

Functions

Several native functions perform the basic building commands.

Rough notes on brush creation:

This is pure speculation on my (tarquin's) part. The vertex building commands add points as vectors to a dynamic array. The poly building commands then pick these out to define the polys. The array is then discarded for the resulting brush, as can be seen in a brush itself (Brush Hacking), each poly has a segregated vertex list. At the construction stage, however, a vertex from the array can be used for several polys.

BrginBrush() reinitialises the vertex array. This is kept for each class, not in the RBB, so there's (unfortunately) no cross-talk possible between brushbuilder classes.

BadParameters

BadParameters( optional string Message )

This function produces a dialog box in UnrealEd displaying Message and an OK button. It should be called to alert the user of parameters that are out of range, or incompatible options. To span the messgae over several lines in the dialog box, use a string expression with "$ Chr(13) $". The Epic brushbuilder scripts have a block of input-checking conditions after declaring any local variables in the Build() function.

if( MyParameter <= 0 )
    return BadParameters();
if( HALisUnhappy )
    return BadParameters("I'm sorry, David, I can't let you do that.");
if( Confustication && MyParameter > 16 )
    BadParameters("You are about to make a brush that can't be used as a subtract. Click to proceed.");

A little innovation of Tarquin's not seen in the native builders is using BadParameters() without return as seen in the third example above, to warn the user of non-fatal problems: when the user clicks OK the builder will proceed. If you intend to release your builder, it's vital that you prevent the user from crashing UEd or creating BSP errors in their levels as a result of bad parameters.

Setting up

BeginBrush( bool MergeCoplanars , name Group )

This initialises the red builder brush. If not included, the vertices and polys from the last build with this class persist, and the brush will be a horrible mess (even if it doesn't look like a mess, polys will be super-imposed. Try applying a masked texture to see!)

MergeCoplanars: if set to true, the resulting brush will have coplanar sets of polygons merged. Note that non-adjacent polys will be merged if their textures are oriented in the same direction – the Extruder Brushbuilder does this sometimes. Since texture orientation is determined (I think) by the order in which the vertices are listed in the poly definition function call, some care may be needed.
Group: Sets the group name of the brush. Not sure of its purpose. The build-in brushbuilders allow the user to specify this.

EndBrush()

This wraps up the brush building process. Used to close the Build function thus:

return EndBrush();

Vertex building

Two functions add vertices to the list, taking the position either from a vector or 3 seperate co-ordinates:

int Vertexv( vector V );
int Vertex3f( float x, float y, float z );

They return the index of the vertex just created.

Vertex inspection

GetVertexCount()

Returns the number of vertices currently in the internal array. Since these start with 0, this number is also the index of the next vertex to be built. This is useful for poly building within a function call, as seen in Epic's CylinderBuilders for example.

GetVertex( int i )

Returns the position vector of a vertex from the array. Useful for bug-tracking, thus:

// show me the location of vertex i:
log(i $ ": " $ (GetVertex(i)));

There is also a function GetPolyCount(), which I assume returns the number of polys defined.

Poly building

Several functions define polygons. They all take similar parameters.

// build a 3-sided polygon:
Poly3i( Direction, i, j, k, ItemName, PolyFlags )

// build a 4-sided polygon:
Poly4i( Direction, i, j, k, l, ItemName, PolyFlags )

// build a polygon with any number of sides:
PolyBegin( Direction, ItemName, PolyFlags )
Polyi( i )
PolyEnd()

Poly3i and Poly4i build polys from 3 and 4 points. PolyBegin, Polyi and PolyEnd work together to build a poly from any number of points. Polyi is often placed inside a for() loop (see Flow Syntax). Their parameters all work in the same way.

int Direction: Determines which way the poly faces. This should be +1 or -1, though I suspect any value will work and the sign will determine the result. With Direction=1, the vertices are taken in an anti-clockwise direction when looking at the poly from the exterior. When working out which order to take vertices, remember the Unreal World uses a left-handed co-ordinate system. As a last resort, list them in sequence, try building and if the poly is visible from the wrong side, flip the value of Direction or re-order them.
int i, int j, int k, int l: specifies an item from the vertex array.
optional name ItemName: a name for the poly. Polys are grouped by name as a convenience to the mapper. The name itself doesn't matter. This is used only for the SHIFT+I command (see [Surface Selection]?). This can be set with an expression: see Scripting Custom Brushbuilders.
optional int PolyFlags: flags for that polygon. Omit this parameter to make regular polys; set to 0x00000108 for a two-sided sheet. See PolyFlags for the full list.

Properties

Two properties are unused by the script but are read by UnrealEd to create the interface. Set them in default properties.

BitmapFilename: the bitmap file to display on the button. This must be stored in {Base Directory}/System/editorres. The value required is the name of the file without the .BMP extension.
ToolTip: The hint text that appears when the user hovers the mouse pointer on the button.

Known Subclasses

Built-in:

Custom:

TarquinBuilderBase (not yet released)
TarquinCylinderBuilder?
TarquinSpiralStairBuilder
TarquinPanoramaBuilder?
TarquinTorusBuilder

Custom Brushbuilders

These add extra buttons to the interface.

[Tarquin's UT], home of his custom brush builders.
- Tarquin Brushbuilders
- Extruder Brushbuilder
Zxanphorian Brushbuilders
[Framebuilder], by JohnMcL.
[Unreal Realm Of Concepts], home of the Platonic Solids builder.

Category Class (UT)
Category Class (UT2003)