My program doesn't have bugs. It just develops random features.

Difference between revisions of "UE3:BrushBuilder (UT3)"

From Unreal Wiki, The Unreal Engine Documentation Site
Jump to: navigation, search
(Auto-generated page)
 
(copied description from UT2004 page (can't include, some functions are different!))
Line 4: Line 4:
 
| abstract = yes
 
| abstract = yes
 
}}
 
}}
−
{{autogenerated}}
+
<!--
−
Copyright 1998-2007 Epic Games, Inc. All Rights Reserved.
+
Descriptions below copied from UE2:BrushBuilder (UT2004).
 +
That page can't be included here like it was done for other games because some functions have changed.
 +
-->
 +
Base class of [[UnrealEd]] [[brush]] builders.
 +
 
 +
Tips for writing brush builders:
 +
 
 +
Always validate the user-specified parameters and call {{tl|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==
 
==Properties==
Line 12: Line 22:
 
'''Type:''' [[string]]
 
'''Type:''' [[string]]
  
−
<!-- enter variable description -->
+
File name (without extension) of the brush builder's [[toolbox]] icon. The icon should be in 24bit [[wp:BMP file format|BMP file format]] with dimensions of 30x30 pixels. UnrealEd will look for the file in the System/EditorRes directory.
  
 
'''Default value:''' "BBGeneric"
 
'''Default value:''' "BBGeneric"
Line 19: Line 29:
 
'''Type:''' [[string]]
 
'''Type:''' [[string]]
  
−
<!-- enter variable description -->
+
The tooltip for the brush builder's toolbox icon.
  
 
'''Default value:''' "Generic Builder"
 
'''Default value:''' "Generic Builder"
  
 
===Internal variables===
 
===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====
 
====Group====
 
'''Type:''' [[name]]
 
'''Type:''' [[name]]
Line 29: Line 41:
 
'''[[Variables#Modifiers|Modifiers]]:''' private
 
'''[[Variables#Modifiers|Modifiers]]:''' private
  
−
<!-- enter variable description -->
+
The group name for the generated brush. This value is set with the {{tl|BeginBrush}} function's second parameter and will become the final brush's {{tl|Group||Actor properties}} name.
  
 
====MergeCoplanars====
 
====MergeCoplanars====
Line 36: Line 48:
 
'''[[Variables#Modifiers|Modifiers]]:''' private
 
'''[[Variables#Modifiers|Modifiers]]:''' private
  
−
<!-- enter variable description -->
+
Whether co-planar faces of the brush should be merged. This value is set with the {{tl|BeginBrush}} function's first parameter.
  
 
====Polys====
 
====Polys====
Line 43: Line 55:
 
'''[[Variables#Modifiers|Modifiers]]:''' private
 
'''[[Variables#Modifiers|Modifiers]]:''' private
  
−
<!-- enter variable description -->
+
The list of polygons for the brush to build. The various Poly* functions add items to this list and the {{tl|GetPolyCount}} function returns the number of items in this list.
  
 
====Vertices====
 
====Vertices====
Line 50: Line 62:
 
'''[[Variables#Modifiers|Modifiers]]:''' private
 
'''[[Variables#Modifiers|Modifiers]]:''' private
  
−
<!-- enter variable description -->
+
The list of vertices for the brush to build. The functions {{tl|Vertex3f}} and {{tl|Vertexv}} add new items to this list and return the new item's index. The function {{tl|GetVertexCount}} returns the number of items in this list, the function {{tl|GetVertex}} returns a specific item.
  
 
==Structs==
 
==Structs==
 
===BuilderPoly===
 
===BuilderPoly===
−
<!-- enter struct description -->
+
Description of a polygon for the brush to build.
−
; [[array]]<[[int]]> VertexIndices : <!-- enter variable description -->
+
; [[array]]<[[int]]> VertexIndices : The list of vertices defining this polygon.
−
; [[int]] Direction : <!-- enter variable description -->
+
; [[int]] Direction : The direction of the polygon as specified by the first parameter of the {{tl|Poly3i}}, {{tl|Poly4i}} and {{tl|PolyBegin}} functions.
−
; [[name]] Item : <!-- enter variable description -->
+
; [[name]] Item : The item name of the polygon as specified by the optional last parameter of the {{tl|Poly3i}}, {{tl|Poly4i}} and {{tl|PolyBegin}} functions.
−
; [[int]] PolyFlags : <!-- enter variable description -->
+
; [[int]] PolyFlags : The flags of the polygon as specified by the optional last parameter of the {{tl|Poly3i}}, {{tl|Poly4i}} and {{tl|PolyBegin}} functions.
  
 
==Functions==
 
==Functions==
Line 65: Line 77:
 
{{code|native function [[bool]]&nbsp;'''BadParameters''' (optional&nbsp;[[string]]&nbsp;'''msg''')}}
 
{{code|native function [[bool]]&nbsp;'''BadParameters''' (optional&nbsp;[[string]]&nbsp;'''msg''')}}
  
−
<!-- enter function description -->
+
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====
 
====BeginBrush====
 
{{code|native function '''BeginBrush''' ([[bool]]&nbsp;'''InMergeCoplanars''', [[name]]&nbsp;'''InGroup''')}}
 
{{code|native function '''BeginBrush''' ([[bool]]&nbsp;'''InMergeCoplanars''', [[name]]&nbsp;'''InGroup''')}}
  
−
<!-- enter function description -->
+
Initializes the brush builder. This function should be the first to call after verifying that the user-specified parameters are valid.
  
 
====EndBrush====
 
====EndBrush====
 
{{code|native function [[bool]]&nbsp;'''EndBrush''' ()}}
 
{{code|native function [[bool]]&nbsp;'''EndBrush''' ()}}
  
−
<!-- enter function description -->
+
Finalizes the brush building process and returns ''True''. This is usually the last function to call during the brush building process.
  
 
====GetPolyCount====
 
====GetPolyCount====
 
{{code|native function [[int]]&nbsp;'''GetPolyCount''' ()}}
 
{{code|native function [[int]]&nbsp;'''GetPolyCount''' ()}}
  
−
<!-- enter function description -->
+
Returns the number of polygons defined so far.
  
 
====GetVertex====
 
====GetVertex====
 
{{code|native function {{tl|Vector|Object|structs}}&nbsp;'''GetVertex''' ([[int]]&nbsp;'''i''')}}
 
{{code|native function {{tl|Vector|Object|structs}}&nbsp;'''GetVertex''' ([[int]]&nbsp;'''i''')}}
  
−
<!-- enter function description -->
+
Returns the vertex with the specified index.
  
 
====GetVertexCount====
 
====GetVertexCount====
 
{{code|native function [[int]]&nbsp;'''GetVertexCount''' ()}}
 
{{code|native function [[int]]&nbsp;'''GetVertexCount''' ()}}
  
−
<!-- enter function description -->
+
Returns the number of vertices defined so far.
  
 
====Poly3i====
 
====Poly3i====
 
{{code|native function '''Poly3i''' ([[int]]&nbsp;'''Direction''', [[int]]&nbsp;'''i''', [[int]]&nbsp;'''j''', [[int]]&nbsp;'''k''', optional&nbsp;[[name]]&nbsp;'''ItemName''', optional&nbsp;[[bool]]&nbsp;'''bIsTwoSidedNonSolid''')}}
 
{{code|native function '''Poly3i''' ([[int]]&nbsp;'''Direction''', [[int]]&nbsp;'''i''', [[int]]&nbsp;'''j''', [[int]]&nbsp;'''k''', optional&nbsp;[[name]]&nbsp;'''ItemName''', optional&nbsp;[[bool]]&nbsp;'''bIsTwoSidedNonSolid''')}}
  
−
<!-- enter function description -->
+
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====
 
====Poly4i====
 
{{code|native function '''Poly4i''' ([[int]]&nbsp;'''Direction''', [[int]]&nbsp;'''i''', [[int]]&nbsp;'''j''', [[int]]&nbsp;'''k''', [[int]]&nbsp;'''l''', optional&nbsp;[[name]]&nbsp;'''ItemName''', optional&nbsp;[[bool]]&nbsp;'''bIsTwoSidedNonSolid''')}}
 
{{code|native function '''Poly4i''' ([[int]]&nbsp;'''Direction''', [[int]]&nbsp;'''i''', [[int]]&nbsp;'''j''', [[int]]&nbsp;'''k''', [[int]]&nbsp;'''l''', optional&nbsp;[[name]]&nbsp;'''ItemName''', optional&nbsp;[[bool]]&nbsp;'''bIsTwoSidedNonSolid''')}}
  
−
<!-- enter function description -->
+
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====
 
====PolyBegin====
 
{{code|native function '''PolyBegin''' ([[int]]&nbsp;'''Direction''', optional&nbsp;[[name]]&nbsp;'''ItemName''')}}
 
{{code|native function '''PolyBegin''' ([[int]]&nbsp;'''Direction''', optional&nbsp;[[name]]&nbsp;'''ItemName''')}}
  
−
<!-- enter function description -->
+
Begins the definition of a polygon consisting of a custom number of vertices. Vertices are specified with the {{tl|Polyi}} function and the polygon is finalized with the {{tl|PolyEnd}} function. If '''Direction''' is negative, the normal of the polygon is reversed.
  
 
====PolyEnd====
 
====PolyEnd====
 
{{code|native function '''PolyEnd''' ()}}
 
{{code|native function '''PolyEnd''' ()}}
  
−
<!-- enter function description -->
+
Finalizes a polygon started with the {{tl|PolyBegin}} function.
  
 
====Polyi====
 
====Polyi====
 
{{code|native function '''Polyi''' ([[int]]&nbsp;'''i''')}}
 
{{code|native function '''Polyi''' ([[int]]&nbsp;'''i''')}}
  
−
<!-- enter function description -->
+
Specifies the index of a vertex to include in the polygon currently being built with the {{tl|PolyBegin}} and {{tl|PolyEnd}} functions.
  
 
====Vertex3f====
 
====Vertex3f====
 
{{code|native function [[int]]&nbsp;'''Vertex3f''' ([[float]]&nbsp;'''x''', [[float]]&nbsp;'''y''', [[float]]&nbsp;'''z''')}}
 
{{code|native function [[int]]&nbsp;'''Vertex3f''' ([[float]]&nbsp;'''x''', [[float]]&nbsp;'''y''', [[float]]&nbsp;'''z''')}}
  
−
<!-- enter function description -->
+
Creates a vertex with coordinate components corresponding to the three float parameters.
  
 
====Vertexv====
 
====Vertexv====
 
{{code|native function [[int]]&nbsp;'''Vertexv''' ({{tl|Vector|Object|structs}}&nbsp;'''v''')}}
 
{{code|native function [[int]]&nbsp;'''Vertexv''' ({{tl|Vector|Object|structs}}&nbsp;'''v''')}}
  
−
<!-- enter function description -->
+
Creates a vertex with coordinates corresponding to the vector parameter.
  
 
===Events===
 
===Events===
Line 131: Line 143:
 
{{code|event [[bool]]&nbsp;'''Build''' ()}}
 
{{code|event [[bool]]&nbsp;'''Build''' ()}}
  
−
<!-- enter event description -->
+
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 {{tl|BadParameters}} and return ''false'', e.g. with <code>return BadParameters();</code>, to abort the building process. Otherwise call {{tl|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 {{tl|EndBrush}} and return ''true'', e.g. with <code>return EndBrush();</code>, to signal success.

Revision as of 13:45, 21 November 2008

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 System/EditorRes 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 last parameter of the Poly3i, Poly4i and PolyBegin functions.
int PolyFlags 
The flags of the polygon as specified by the optional last parameter of the Poly3i, Poly4i and PolyBegin 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.

Retrieved from "https://wiki.beyondunreal.com/UE3:BrushBuilder_(UT3)?oldid=33396"