**************************************************
*                 Makebrush v0.6                 *
*              (c) by Lars Bensmann              *
**************************************************
* http://localhost.ruhr.de/~b-man/makebrush.html *
**************************************************

Introduction
------------
This utility is for everyone who wants to try making a Quake MAP-file.
It will make the most difficult part way easier. You don't have to care
about those numbers in the brushes anymore. It will also create rooms and
stairs automatically.


How does it work?
-----------------
Well, it's really easy.
Just type:

	makebrush [option]      (Linux version)
	makeb [option]          (DOS version)

First of all you will be asked what kind of object you want to define.
You can choose between a regular object, cube, plane, room, funny room,
and stairs. Solid staircases are not implemented yet.


Defining cubes
--------------
Enter 'c' to the first question to define a cube. You need to know one point
of your cube with all 3 neighboring points.

                  P5
        +---------+   So if you enter P1 as you first point, the next points
       /|        /|   need to be P2, P3, and P4 (order is not important for
   P4 / |       / |   the last three points).
     +--+------+  +
     | / P3    | /    Actually, you can define cubes in the plane mode pretty
     |/        |/     simple as well. So have a look which mode you like
     +---------+      better.
    P1         P2


Defining cubes aligned to the x, y, and z-axis
----------------------------------------------
This is really easy. You just have to enter two opposite corners, that's it
(e.g. P1 and P5). Of course, you can rotate the cube afterwards with the
'-r' option.


Defining planes
---------------
Now let's get to the plane mode. Typing 'p' at the beginning will put makebrush
into the plane enter mode.

In plane mode you can define any shapes that have the same thickness at every
point (including cubes). First of all you have to tell makebrush how many
corners the 2D plane has and then you have to enter a vector for the thickness.
Because it is a vector, you are not restricted to horizontal planes.

After this, you just have enter all the corner points of the 2D plane.


Rooms
-----
Now the fun begins. You always had this level in mind with the 50 sided room?
Well, no problem anymore, just use 'makebrush'.
'Makebrush' knows two different room modes. The regular 'room mode' and the 
'funny room mode'. The funny mode was my first try, but didn't generate the
results I wanted, but I left it in anyway, because the objects looked kind
of funny. (Well, now you know, why I called it this way :-)
Making a room is as simple as a regular object. Just enter the thickness of
the walls, and then enter the inner corner points of the room. You can also
specify a negativ thickness and the walls will go inside, so you have to
enter the outer corners.
Let me give you a brief descrition, of what the 'funny room mode' is.
Let's say you have two planes A and B:

     
     |\
     | \
     |  \
     |   \
    A    B

That's what it should look like (regular 'room mode'):

 positive walls:

    |\           negative walls:
    | \
    ||\\           |\
    || \\          | \
    ||  \\         ||\\
    ||   \\        || \\
    A    B         A    B

That's what the 'funny room mode' looks like:

 positive walls:

                 negative walls:
     |\
    ||\\            Sorry, I can't draw this :-)
    || \\
    ||  \\
    ||   \\
    A    B

Oh, I hate ASCII graphics, but I hope you get the idea anyway. If didn't
just try the following:

'makebrush -o test -i 20sides'.

This will generate twenty brushes for a 20 sided room in the files test1.
Now change '//#room' in the file '20sides' to '//#froom'.
Just compile them with QBSP and look what the difference is.
If you want to see the effect of negative walls, change the number after
the keyword 'thickness' in the file '20sides' from '50' to '-50', and do
the whole thing all over again.


Staircases
----------
There are two types of staircases implemeted yet. The first type creates
the given number of steps objects between the bottom and the top step.
The shapes of the two steps do not have to be the same (but they have to have
the same number of corner points)
The second type of staircases lets the single steps (which are all the same)
rotate around a given point.

Simple staircases
-----------------
At first you have to enter how many points you want to define. Read on first,
so you know how many you need to define the staircase you want.
Now you should enter the corner points of hte lowest and the highest step in
a sensible order. The first half of the points define the lowest step and the
last half the highest. If you enter the back left corner as point 1, you should
also enter the back left corner of the upper step as point 1 of the second half.
Thsi may seem a little bit complicated, but it's not that bad, once you get the
plan behind this. And then you can create some weird looking staircases by
messing up the order liberatly. Makebrush will calculate a line between the
first point on the lower step to the first point of the upper step. (From the
second to the second and so on.) So if you swap the order, your steps will
look something like this:


           7-------------8       7--------------8
Upper step |             |       |              |
           5-------------6       6--------------5
           |             |        \            /
           |             |           \      /
           |several steps|              \/
           |             |              /\
           |             |           /      \
           |             |        /            \
           3-------------4       3--------------4
Lower step |             |       |              |
           1-------------2       1--------------2

If you swap points 5 and 6 as well, the stairs will look like the
left picture again.

Play around a bit with the staircase mode. You can create several interesting
objects. The only restriction is that you have to have the same number of
points for the first and the last step.

For one interesting example type:

'makebrush -o test -i platform'

This will give you an impression of what is possible. If you create interesting
objects, don't hesitate to mail me (lars@b-man.ruhr.de) the coordinates in a
file of the same format as 'platform' or '20sides'. I'd like to include several
more examples with makebrush. (Or look at the 'filemode'-section for a more
elegant solution).

Spiral staircases
-----------------
The input mode is similar to the plane mode. You just have to define one step
here, because all steps will be the same (just rotated around the center of
your spiral staircase).
First of all you have to enter the number of steps (including the first and
the last one). Now type in the vector for the thickness of the steps, followed
by the amount of rotation of the last step in degrees (e.g. if you want a two
story staircase enter 720.)
Now you have to enter the center point of your staircase. The z-value is
actually irrelevant, bu you have to enter it anyway :-)
Now enter the points just as in the plane mode.


Rotation
--------
Yes, you can also rotate your object around any point you like. You can even
rotate the object several times around different points. This might be useful
to move the object to a specific position as long as I don't have any kind of
translation included.
You have to specify '-r' on the command line (or '-r#' for several roatations).
Makebrush let's you enter the fixed point for the first rotation followed by
the rotation around the x-, y-, and z-axis. YOu have to repeat this as many
times as you entered at the command line.
Makebrush will rotate around the x-axis first, then around the y-axis and last
around the z-axis. So if you want to have a different order use multiple
rotations.


And what happens now?
---------------------
About 0.1 sec after entering the last value you will see your brush on
the screen (if you entered points that make sense, e.g. if all points
were on the same plane you had a pretty flat 3D-object or entering
the same point more than once is also a pretty stupid thing to do.)

If you specified 'texture' on the command line your brush will have the
right texture already. If you didn't specify it, the field will default
to 'BRICKA2_2'.

If you specified the -o option, your brush(s) will be written to the
specified file. Just import it in your MAP file, et voila.


Filemode ('-i' option)
----------------------
The filemode is really neat. You can just edit your MAP file, decide to
add a object. Write a line with the syntax below and Makebrush will
expand it to the brush format. Of course, you can also add several
lines at once, and convert them with one invocation.
If you entered the '-i' option at the command line, Makebrush will
process the specified file and won't require any user input.
It will copy everything to the output (screen or to the file you
defined with the '-o' option.) until it reaches a line that starts
with the characters "//#".
You can use all modes described above (and one extra one). The
appropriate commands are:

//#object # (x1/y1/z1) (x1/y2/z3) ... (xn/yn/zn)
           <- number of points to follow

//#cube (x1/y1/z1) (x2/y2/z2) (x3/y3/z3) (x4/y4/z4)

//#acube (x1/y1/z1) (x2/y2/z2)
(the cube modes are the only ones where you don't have to specify the
number of points (always four or two!))

//#plane # (x1/y1/z1) ... (xn/yn/zn) thickness (x/y/z)

//#room # (x1/y1/z1) ... (xn/yn/zn) thickness #

//#froom # (x1/y1/z1) ... (xn/yn/zn) thickness #

//#stairs # (x1/y1/z1) ... (xn/yn/zn) steps # height #

//#istairs # (x1/y1/z1) ... (xn/yn/zn) steps # thickness (x/y/z) degree # center (x/y/z)


This should be pretty straight forward, if you've read the other
sections. You can add the keywords 'rotate (x/y/z) x y z' and/or
'texture TEXNAME' at the end of each line. (rotate can be specified
several times). Every keyword can be abbreviated by the first letter,
e.g. '//#o' or 's' (for steps). Order is really important for the
options other than 'rotate' and 'texture'. And you should seperate
each number, point definition and keyword by exactly one space.
(You can have spaces in the paranthesis, but don't have to).
For an example look at the file 'filemode' included with Makebrush.
There you will get a general idea of how it works.

And here is a pretty handy option that is just available in the
filemode yet:

//#template TEMPLATEFILE

Where TEMPLATEFILE specifies the file you want to import into
your MAP. It should look something like this:

{
 "classname" "brush_template"  //optional (ignored)
 "center" "x y z"              //center point used for rotation,
                               //scaling and translating
                               //(default: "0 0 0")
 "rotate" "x y z"              //rotate around the axis (in degree)
                               //(default: "0 0 0")
 "scale" "x y z"               //scale the object
                               //(default: "1 1 1")
 "origin" "x y z"              //translate the object, so the center
                               //point is at the origin
                               //(not used by default)
 {
  ( x y z ) ( x y z ) ( x y z ) ...
  ...
 }
 (More brushes)...
}

All the options 'center', 'rotate', 'scale', and 'origin' can also be
given after TEMPLATEFILE. Don't enclose them in quotation marks, just
...center (x/y/z) rotate (x/y/z) scale (x/y/z) origin (x/y/z)
You can just specify some of them and in any order, but they have to
be seperated by exactly one space.


Options
-------
Makebrush knows a few options entered from the command line:

Makebrush v0.6
(c) by Lars Bensmann

Usage:   makebrush [options]

Options:
     -h           this Help screen
     -m[ocaprfsi] specify Mode:
                   a Aligned cube mode     o regular Object mode
                   c Cube mode             p Plane mode
                   f Funny room mode       r Room mode
                   i spIral staircase mode s Staircase mode
     -r[#]        Rotate object or room # times (default: 1)
     -c           add Comments to output
     -q           Quiet mode (no output besides the actual brush)
     -v#          set Verbose mode: 0  quiet mode (same as -q)
                                    1  normal mode
                                    2  some debugging information
                                    3  lots of debugging information
     -t TEXNAME   change default Texture to TEXNAME
     -i INPUT     process file INPUT (enter filemode)
     -o OUTPUT    write brush (and comments) to file OUTPUT
     -e ERROR     write prompt/debuging/error messages to file ERROR


It's very advisable to use the -o option. This will write everything that
belongs in a MAP file into the specified file. Major improvment over 0.45,
so you don't have to search for every brush (or use the quiet mode and
don't be prompted for the input).
The '-c' option is pretty useful for more complex levels or rooms. It will
add a short description to each brush consisting of the corner points of
the object. This will allow you to identify every wall pretty easily, so
you can remove it, change it by hand or whatever. Unfortunately this doesn't
work for the 'funnyroom'-mode and when importing a template (although the
comments from the template-file are copied, so there might be a description in
there.)


Future
------
- Add template import to interactive mode.
- Add a 'solid stairs mode'.
- Add 'escalators'.
- Add a couple of new input modes
- Let rooms be defined in plane and cube mode as well.
- If I still have to much time after finishing all the above, I might
  write a GUI for it. But don't count on it.
- ??? Any idea from YOU?


Feedback
--------
I could use some constructive critisism. So please tell me what you think
about 'makebrush' and what you would like to see improved or added.
I'm also looking for somebody who could proof read this documentation.
My English isn't the best (don't talk about my typing :-), so I sometimes
have problems expressing things correctly so everone can understand it.


Thanks
------
This whole thing was just made possible by the great Quake MAP Specs from
Nicholas Dwarkanath. If you're interested in making a MAP-file get
the latest version from http://www.infi.net/~nichd/qmapspec.html.
Thanks for the template idea go to: Mark D. Ratzburg 
(ratzburg@omnifest.uwm.edu).


Bugs
----
Well, this program isn't too user-friendly, but it should do it's work.
So please don't tell me that you cannot get back to correct your last entry
or whatever, but if you find anything that produces wrong results, please
tell me (lars@b-man.ruhr.de).
When trying to generate larger brushes, I sometimes got an errors from
'QBSP' (AddBrushPlane: numbrushfaces == MAX_FACES). Well, I thought maybe
the object has to many faces, but I got this error even on an object with
just seven planes. And my object with the most faces that compiled correctly
had 9 planes. Sometimes, if you rotate the object QBSP can't handle it anymore.
It's really weird. If anybody has an idea if this is a limitation of the
Quake engine or QBSP or a bug in makebrush, please tell me.
And if anybody knows how to estimate if QBSP can compile the brush or not.
This would be really useful, because I don't know when to split a larger
object into several smaller ones.
As long as I haven't got around to look into this, the easiest solution is
to use the room mode (or funnyroom mode if possible). This will generate
several but less complex brushes. If you already tried to create a room,
try not to generate a room with a large 10 sided polygon as the bottom.
If you really want to do something like this, just add a point in the
middle of the complex plane, just outside, so there will be several
triangles generated instead of the too complex brush.
By far the worst bug is in the 'room'-mode. If you get a really strange
QBSP error. I really don't know why QBSP won't compile some of the
rooms anymore. It works putting every brush in a single MAP-file, but
they won't compile together :-(. If anybody has an idea what the
problem might be, please tell me. (I know I still got a (rounding?)
error in the calculation for the rooms, but...)
I did rewrite the room-mode completely. Maybe this bug is gone, although
the mode is far from perfect (too many planes in the brushes :-(


History
-------

0.1	First release

0.2	Added command line switches

0.3	Added cube and plane mode

0.4	Added room and funny room mode

0.45	Added rotation and stairs mode.
	Also fixed the broken quiet mode again.

0.5	Added file parser and support for a seperate brush-output file.
	Included import of brush templates.

0.6     Added spiral staircase mode and aligned cube mode.
	Rewrote room mode completely, but it still isn't as it is supposed
	to be.


Legal stuff
-----------

I don't promise this program will do anything useful. It may work for you or
it may not. It works for me that's all I can tell you.
