Tarquin's Extrude Builder

release 080 (28 May 01)

Hello brave soul, and thanks for downloading the pack.
This builder takes a shape in 2 dimensions and extrudes it along a 3-dimensional path. The shape can be translated without rotation to each path point, or turned to follow the path giving each section the same cross-section.
Currently both the shape and the path have to be specified by the user as point vectors; the aim for future versions will be to add ways of defining these points that are more user-friendly.
This release should be considered to be experimental.
I recommend you use this with UT patch 432 or higher. If you successfully use the pack with a lower version please let me know.
Acknowledgements, version history, legal stuff & disclaimer: see the end of this file.
If you find the pack useful, or have any comments or suggestions, or make a really cool map using these builders, feel free to let me know.

Documentation online

This document covers the essentials. There is a version of this documentation on my website (http://www.planetunreal.com/tarquin) which has been considerably expanded, with extra detail and screenshots.
There's also a tutorial which goes through the basic steps of making a brush with this tool.

Upgrading

If you're upgrading from an older build, you only need to replace the TarquinExtrudeBuilder.u file that's in your [UT]\system folder and the documentation with the new versions.
The new features are marked with the version number.

Installation

Installing the pack will add a new button to the UnrealEd toolbox, below the Epic brush builders. This will function in exactly the same way as the native builders: left-click to build, right-click to open the parameters window.

umod version: Double-click the file to install it. Apart from adding a line to unrealtournament.ini, nothing existing on your system is overwritten.
zip version: unzip the contents of the file, and place the files thus:

• TarquinExtrudeBuilder..u in [UT]\system,
• the .bmp file in [UT]\system\editorres,
• this file you are currently reading wherever you wish.

— where [UT] is your UnrealTournament folder.
You also need to add the following line to unrealtournament.ini, at the end of the [Editor.EditorEngine] section, after the other 'EditPackages' lines:

EditPackages=TarquinExtrudeBuilder

This documentation covers the basics. The online version has pictures, and there's a tutorial too.

Caveat

Because of the complexity of the procedure, it's not possible for this builder to check that it isn't making a brush that is bad in some way — so it's up to you, the user to exercise caution when you use this. The documentation on my site is the best place to find out more, but here's the brief list of things to watch out for:

• Tight bends: If path points are too close, the tube will bend too far and go into itself. Use ShowJoints in the Command Module to see clearly if the tube joints are seperate. If they only touch at vertices or edges, UEd will collapse the vertices and destroy polys with zero area automatically; this may be bad for the BSP in the long run, I have no idea.
• Self-intersection: If the path, say, goes up, right, down, left... the tube will pass through one of its earlier sections. This is probably a Bad Thing.
• Shape restrictions: The extruder can only build convex caps, as it makes them with a single poly. If you build a looped brush, then you can have any sort of shape, since there is no cap.
  As of build 078, you will be warned if the shape is concave.
• Shape Direction: no longer an issue. As of build 078, the points of the shape may be listed clockwise or anti-clockwise, it doesn't matter.

Essential point to note: Input fields in a sub-list (the point vectors, and the two parameters lists) do NOT update in the same way as the others: if you type in a number and then press 'build' your latest change will NOT be taken into account. You must press return after typing, or hit tab to move to the next field, or click on another field, or click that field's name so the number field pops back from bevelled to flat.
I may repeat this point further down as I really don't want emails from people saying it doesn't work properly because they haven't read this.

Options

ShapePoints, PathPoints

In this version the only way to specify the points of path is by entering them here as point vectors. For the points of the shape, you can use presets (build 075 and later).
Note that the shape should be 2-dimensional in the XY plane, so leave the Z-coordinate at zero. (If you are particularly brave, you can try making the shape 3-dimensional, but, as they say at restaurants where you can have your steak well done: 'not responsible'.)
If the point (0,0,0) is to be included in the path or the shape, it must be used in first position. (the script determines how many points you want to use from the array by looking for the first occurence of the zero vector.)
The shape points must all be different; the path points must all be different: the builder checks for this.

As of build 078, you can quickly reset these long lists of numbers to zero. See the section on commands.

NOTE: The input fields for the point vectors do not update in the same way as the others: if you type in a number and then press 'build' your latest change will not be taken into account. You must press return after typing, or hit tab to move to the next field, or click on another field, or click that field's name so the number changes back from entry mode to flat.

ShapeFactor, PathFactor

The points of the shape and path respectively are scaled by these numbers. With the default value, typing ( 0,2,1) will give a point at ( 0, 128, 64 ), for example. This is simply as a convenience.

ExtrudeType

Translational: the basic extrude type simply shifts the shape to each point without rotating it, like successive platforms. With this option, the z component of the path points must either be always increasing or decreasing, otherwise the brush will cross itself.
Tangential: the 'proper' extrude type keeps the cross-section of the brush the same throughout, dipping the shape at each bend of the path.
There are diagrams showing how this works at the website: http://www.planetunreal.com/tarquin.
Third Way (080): A different type of extrusion that eliminates camber by always rotating relative to the starting joint. I couldn't think of a descriptive name, so named in honour of MisterTonyBlair's vision (this is sarcasm BTW).
It's not quite what I had in mind, since after coding this I realised that I was aiming for is mathematically impossible, but it's here anyway — well! it would seem the name is rather accurate after all! Remarkable.
This may produce sides made from two non-coplanar triangles, rather like the sloped option for spiral stairs.

ShapeSource

This option tells the builder where to look for information on how to make the shape.
Vectors: reads the shape data from the ShapePoints vector array in the brush builder properties.
pSquare & pCircle (075): Selecting one of these options tells the Preset Module to enter points into the ShapePoints array for you. The brush builder will then read those points and make the brush as usual.
You can give the Preset Module more detailed instructions by entering numbers into the PresetMetrics list, but if you leave that list full of zeros the module will build a default square and default circle respectively.
The section on presets below gives further details.
MrPointy: I used this as a test shape: it's a big cross shape that clearly shows the directions of the relative X and Y axes at each turn. I've left it in as switching to this shape can sometimes make it clearer to see what's going on.

PathSource (075)

Vect_Abs: reads the path data from the vector array in the brush builder properties, and takes each vector to represent a point measured from the origin.
Vect_Rel: reads the path data from the vector array in the brush builder properties, and takes each vector to represent a point measured from previous point — rather like a treasure map that says "four paces North, then three paces SouthWest, then ten paces West etc".

PresetMetrics (075)

An array of values that can be used to give the Preset Module instructions on how to build the preset shapes. If left at zero, the preset will be built with default parameters. The section on presets below gives further details.

Levels Only (removed from build 078 onwards)

The C_ShowJoints command of the command module takes over this option's function.

ClosedPath

Makes the brush into a loop by joining the last path point to the first.

MergeCoplanars

Uses UEd's built-in poly merging to merge coplanar faces. Leave this set to true for a cleaner wireframe.

ReversePolys (removed from build 078 onwards)

This option is no longer necessary, as cunning jiggery-pokery in the builder now determines which way to orient the polys. It no longer matters whether you list the shape points clockwise or anticlockwise.

SheetPolys (075)

(Advanced) Builds sheet polys, and doesn't build caps. This option will let you have only 2 shape points.

InvisibleFinal (075)

Advanced. Doesn't build the final section of the brush. The upshot is that the final joint (the top cap) is tilted according to a piece of path that remains invisible (instead of just being a cross-section).

Randomiser, RandomiserCaps (080)

Wiggles the path points randomly for weird effects (someone asked me for a cave builder). If the explanation that follows makes no sense, try setting X and Y to something small, say 0.5. Try the default preset circle for a good cave.
The randomiser numbers affect the relative co-ordinates of each point, within its respective joint plane. A value of 0.25 for X, say, means that each point's relative X co-ordinate will be increased by between 0 and .25 of its normal value.
Negative numbers are fine. Leaving Z at zero means the path itself is respected — the points only wiggle within their planes. For a more random effect, you can change Z, but I recommend a smaller number than X and Y, say 0.1. The wiggle in Z is proportional to the length of the path section that starts at that plane.
The RandomiserCaps values are applied to the cap vertices, Randomiser to the rest.

Maths (078)

Ignore. MA_Quaternion uses the new maths code. MA_Matrix uses the old pre-078 maths code which can produce diagonal lines across faces.

GroupName

Same as the Epic builders.

_COMMAND (078)

Makes the builder execute special commands. See below.

_Parameters (078)

List of parameters for the command module. See below.

Presets Module (075)

Over the last few days I've been using this builder to make a map, and I've found that I'm nearly always using a square or a rectangular shape. With that in mind, I've writen some presets that should make using the builder a little less complicated.
Select the type of preset you want in the ShapeSource list. You can also set options for the presets in the PresetMetrics array, but if you leave all the entries there set to zero, the preset will be built with default options.
Offset values shift the shape away from the origin — this is the same idea as moving the shape in the 2D shape editor away from the pivot point before revolving it.
The third column shows the default value: if the field is left at zero, this value is assumed.

Square
Sets the shape points to a square.

PresetMetrics[0]	breadth (x)	1
PresetMetrics[1]	width (y)	1
PresetMetrics[2]	x-offset	0
PresetMetrics[3]	y-offset	0

Circle
Sets the shape points to a circle.

PresetMetrics[0]	sides	8
PresetMetrics[1]	sides used	current value of sides
PresetMetrics[2]	x-offset	0
PresetMetrics[3]	y-offset	0
PresetMetrics[4]	align to side (0=false, 1=true)	0

Once you've built with a preset, the point vectors for that shape will be stored in the ShapePoints list. You can then edit these vectors, to use the preset shape as a starting point for something else. Remember to set ShapeSource to "SO_Vectors", otherwise you'll just make the preset again.

Command Module (078)

The _COMMAND option, at the end of the parameters list has a list of special commands the builder can execute. Select a command from the list and press build.
When this is set to C_None, the command module stays in neutral and is inactive — the brush will be built as normal. With other commands, the rest of the options above in the list are ignored — I've mentioned exceptions below. As a convenience, most of these commands reset the command list after they have executed, although because of the way UnrealEd updates the list in the dialog box, this isn't visible until you've clicked in the dialog box to make it active. The commands for showing the shape and showing the joints don't reset the command list, as you may want to make changes to your points and run the same command again to see the result.

C_ShowShape
Does exactly that: shows the current shape by building a single sheet brush, in the XY plane. This is the 'blueprint' for your building (using the example from the tutorial).
You can use this with any ShapeSource setting, the presets or "SO_Vectors" (but not MrPointy. He's antisocial like that!)
(if you've read my list of ideas for future versions of the Tarquin Brush Builder pack, you may know I mentioned a disc sheet builder. With this command and the circle preset — voila!)

C_ShowJoints
This performs the same function as the LevelsOnly option in pre-078 builds. Using the terminology from the tutorial, this builds just the floor plans for the brush.
You can use this with any setting of ShapeSource and PathSource.
This can be very useful when trying to understand where a path is going. It will also show clearly if the current options make a bad brush: if vertices from different sheets touch, UEd has had to join two vertices (I think!). If edges touch, UEd has had to collapse a poly. If two sheets cross each other, you have real problems, as the current options will make a brush that dips into itself, which may lead to BSP errors in subtracted brushes.

C_ResetShape, C_ResetPath
These two commands set all the ShapePoints or PathPoints values to zero. They command won't change the red builder brush, and the _COMMAND option will be reset to neutral automatically afterwards.
(I got fed up typing lots of zeros!)

C_ScaleShape, C_MoveShape, C_RotShape
These three commands apply a transformation to the vectors currently in the ShapePoints list, and then display the result the same way as C_ShowShape. Parameters for these commands can be entered into the _Parameters list:

Command	Parameters[1]	Parameters[0]
Scale	x scale	y scale
Move	x move	y move
Rotate	angle (degrees)	(ignored)

Note that these commands don't pay any attention to the value of ShapeSource so if you want to use these to transform a preset shape, use C_ShowShape to make the preset, and then apply the transformation.

C_ConvPath
This command converts the path vectors from absolute to relative and vice versa. The current value of PathSource is read to determine what type the path points are currently, and this value is then changed to reflect the new type.

C_MakeArc
This command inserts vectors into the PathPoints array to make an arc and builds a brush with the new path.
The builder looks at he last three path points — call the A,B,C in order. The arc will start at point A. B and C are used for information about the size and orientation of the arc and will be over-written.
B is taken to be the centre of the arc, and C is a point 1/4 of the way around the full circle. Another way of looking at it is that line AB goes from 12 o'clock to the centre of the clock face, and BC from the centre to 3 o'clock.
Note that if these two lines are of different lengths the arc will be a piece of an ellipse rather than a circle.

Specify in the parameters list the resolution of the arc:

_Parameters[0]	Sides per circle
_Parameters[1]	Sides used
_Parameters[2]	Align to side (0=false, 1=true)

C_MakeMirror
Extends the path by drawing a mirror image. Takes the last path section to be a normal vector to mirror plane.
The value in _Parameters[0] states what to do with the normal:
0 discards it,
1 keeps it, so the resultant path will have the mirror plane bisecting this section.
2 doubles it first, the the mirror plane will fall where the last path point was.

Notes

This document uses CSS to display text clearly. Unfortunately, some features work in Netscape, some in IE. Take your pick!

The Girl Whose UT Nick Shall Remain Undisclosed who willingly entered into conversations about vectors over breakfast, and for generally being cool.
Robert Wey (creator of extremely cool UT editing stuff) for advice and encouragement.
The writers of various web pages on using quaternions to represent 3-dimensional rotations, which have been rather informative.
All the people who made UT the excellent game that it is. Without UEd's brushbuilder plug-in architecture this pack would not be possible.

080 (28 May 2001)
	Added randomising stuff.
	Added Mystical Third Way extrusion type.
	Added MakeArc & MakeMirror commands.
	Removed duplicate of this history list from this document ;-) !
078 (20 April 2001)
	Changed maths code to use quaternions: the funny diagonal glitch is gone.
	Added command module.
	Now detects direction & convexity of shape.
	Fixed: tiny bug in circle preset.
	Fixed: bug where preset offset could make a shape point zero.
	Removed: ReversePolys option (no longer needed), LevelsOnly option (functionality now in the command module).
075 (9 April 2001)
	Added presets module.
	Added sheet & invisible final options.
	Added relative path points.
	Changed default values.
070 (6 April 2001)
	General release.

legal stuff

This pack is (c) Tarquin 2001 (tarquindarkling@bigfoot.com)
You may NOT re-use, alter, or recompile this code without my express permission.
You are NOT allowed to commercially exploit this release, i.e. put it on a CD or any other electronic medium that is sold for money without my explicit permission.
You MAY distribute this release through any electronic network (internet, FIDO, local BBS etc.), provided you include this file and leave the archive intact.
UNREAL TOURNAMENT (c)1999 Epic Megagames, Inc. All Rights Reserved. Distributed by GT Software, Inc. under license. UNREAL TOURNAMENT and the UNREAL TOURNAMENT logo are registered trademarks of Epic Megagames, Inc.
All other trademarks and trade names are properties of their respective owners.

disclaimer

This pack is provided 'as is'. This is an experimental brush builder, and you use it at your own risk. By installing and using this pack you agree that I will not be liable for any damage to your data resulting from use, direct or indirect, of this pack.