UE3:BrushBuilder (UT3)

Object >> BrushBuilder

Package: 

Editor

Direct subclasses:

CubeBuilder, ConeBuilder, CurvedStairBuilder, CylinderBuilder, LinearStairBuilder, SheetBuilder, SpiralStairBuilder, TetrahedronBuilder, VolumetricBuilder

This class in other games:

UT, U2, U2XMP, UE2Runtime, UT2003, UT2004, UDK

Base class of UnrealEd brush builders.

Tips for writing brush builders:

Always validate the user-specified parameters and call BadParameters function if anything is wrong, instead of actually building geometry. If you build an invalid brush due to bad user parameters, you'll cause an extraordinary amount of pain for the poor user.

When generating polygons with more than 3 vertices, be sure all the polygon's vertices are coplanar! Out-of-plane polygons will cause geometry to be corrupted.

Properties

Property group 'BrushBuilder'

BitmapFilename

Type: string

File name (without extension) of the brush builder's toolbox icon. The icon should be in 24bit BMP file format with dimensions of 30x30 pixels. UnrealEd will look for the file in the Engine\EditorResources\wxRes directory under the UT3 installation directory.

Default value: "BBGeneric"

ToolTip

Type: string

The tooltip for the brush builder's toolbox icon.

Default value: "Generic Builder"

Internal variables

These properties store the internal state of the brush builder and are not accessible from within UnrealScript because they are declared as private variables.

Group

Type: name

Modifiers: private

The group name for the generated brush. This value is set with the BeginBrush function's second parameter and will become the final brush's Group name.

MergeCoplanars

Type: bool

Modifiers: private

Whether co-planar faces of the brush should be merged. This value is set with the BeginBrush function's first parameter.

Polys

Type: array<BuilderPoly>

Modifiers: private

The list of polygons for the brush to build. The various Poly* functions add items to this list and the GetPolyCount function returns the number of items in this list.

Vertices

Type: array<Object.Vector>

Modifiers: private

The list of vertices for the brush to build. The functions Vertex3f and Vertexv add new items to this list and return the new item's index. The function GetVertexCount returns the number of items in this list, the function GetVertex returns a specific item.

Structs

BuilderPoly

Description of a polygon for the brush to build.

array<int> VertexIndices 

The list of vertices defining this polygon.

int Direction 

The direction of the polygon as specified by the first parameter of the Poly3i, Poly4i and PolyBegin functions.

name Item 

The item name of the polygon as specified by the optional (second-to-)last parameter of the Poly3i, Poly4i and PolyBegin functions.

int PolyFlags 

The flags of the polygon. The two-sided flag can be set via the optional last parameter of the Poly3i and Poly4i functions.

Functions

Native functions

BadParameters

native function bool BadParameters (optional string msg)

Displays a simple message box with the msg parameter's value as the message. If the parameter is omitted, a default message about bad brush builder parameters is displayed. This function always returns False.

BeginBrush

native function BeginBrush (bool InMergeCoplanars, name InGroup)

Initializes the brush builder. This function should be the first to call after verifying that the user-specified parameters are valid.

EndBrush

native function bool EndBrush ()

Finalizes the brush building process and returns True. This is usually the last function to call during the brush building process.

GetPolyCount

native function int GetPolyCount ()

Returns the number of polygons defined so far.

GetVertex

native function Object.Vector GetVertex (int i)

Returns the vertex with the specified index.

GetVertexCount

native function int GetVertexCount ()

Returns the number of vertices defined so far.

Poly3i

native function Poly3i (int Direction, int i, int j, int k, optional name ItemName, optional bool bIsTwoSidedNonSolid)

Defines a triangular polygon. i, j and k are indices of the vertices to use for the polygon. If Direction is negative, the normal of the polygon is reversed.

Poly4i

native function Poly4i (int Direction, int i, int j, int k, int l, optional name ItemName, optional bool bIsTwoSidedNonSolid)

Defines a quadrangular polygon. i, j, k and l are indices of the vertices to use for the polygon. Make sure all four vertices are on a plane! If Direction is negative, the normal of the polygon is reversed.

PolyBegin

native function PolyBegin (int Direction, optional name ItemName)

Begins the definition of a polygon consisting of a custom number of vertices. Vertices are specified with the Polyi function and the polygon is finalized with the PolyEnd function. If Direction is negative, the normal of the polygon is reversed.

PolyEnd

native function PolyEnd ()

Finalizes a polygon started with the PolyBegin function.

Polyi

native function Polyi (int i)

Specifies the index of a vertex to include in the polygon currently being built with the PolyBegin and PolyEnd functions.

Vertex3f

native function int Vertex3f (float x, float y, float z)

Creates a vertex with coordinate components corresponding to the three float parameters.

Vertexv

native function int Vertexv (Object.Vector v)

Creates a vertex with coordinates corresponding to the vector parameter.

Events

Build

event bool Build ()

This function is called when the user left-clicked the brush builder icon or the Build button in the brush builder properties window.

Override this function in your subclass to verify user-specified parameters. If any parameter would result in an invalid brush to be build, call BadParameters and return false, e.g. with return BadParameters();, to abort the building process. Otherwise call BeginBrush to start defining the brush. Call Vertex* functions to specify vertices and Poly* functions to define polygons. These calls can be mixed in any way you want, just make sure that in the end all vertex indices used in polygon definitions are actually valid. To finalize the brush, call EndBrush and return true, e.g. with return EndBrush();, to signal success.