Welcome to BSP.

If you are reading this page, you have probably downloaded the alpha version of BSP. Please read the whole thing, many questions are answered.

I will be writing a brief tutorial for BSP in a few days.

Someone suggested I make these colors more "printable". Thanks for the suggestion.

Some else suggested new icons. :) I'll look at any icon bars people submit.

I have given this alpha version number 0.15 so that it is perfectly clear that this is an alpha version.

With this in mind, please note the following:

I DISCLAIM ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE WITH RESPECT TO THE SOFTWARE "BSP" AND THESE ACCOMPANYING WRITTEN MATERIALS, IF ANY. I DO NOT WARRANT THAT THE OPERATION OF BSP WILL BE UNINTERRUPTED, ERROR FREE OR MEET YOUR SPECIFIC REQUIREMENTS. ADDITIONAL STATEMENTS SUCH AS PRESENTATIONS, WHETHER ORAL OR WRITTEN, DO NOT CONSTITUTE WARRANTIES BY ME AND SHOULD NOT BE RELIED UPON BY YOU.

If this software interrupts the operation of your computer or causes data loss on your computer, I disclaim all liabilitiy for any such occurence. You understand that this is an alpha version of BSP and that the software is provided for your enjoyment "as is".

YOU ACKNOWLEDGE THAT YOU HAVE READ THIS AGREEMENT, YOU UNDERSTAND THIS AGREEMENT, AND UNDERSTAND THAT BY CONTINUING THE INSTALLATION OF BSP, BY LOADING OR RUNNING BSP, OR BY PLACING OR COPYING BSP ONTO YOUR COMPUTER HARD DRIVE, YOU AGREE TO BE BOUND BY THESE TERMS AND CONDITIONS. YOU FURTHER AGREE THAT, EXCEPT FOR WRITTEN SEPARATE AGREEMENTS BETWEEN ME AND YOU, THIS AGREEMENT IS A COMPLETE AND EXCLUSIVE STATEMENT OF THE RIGHTS AND LIABILITIES OF THE PARTIES. THIS AGREEMENT SUPERSEDES ALL PRIOR ORAL AGREEMENTS, PROPOSALS OR UNDERSTANDINGS, AND ANY OTHER COMMUNICATIONS BETWEEN ME AND YOU RELATING TO BSP.

This document contains:

• I. What is BSP?
• II. What do I need to run BSP?
• A. Hardware Requirements
• B. Software Requirements
• C. Setting up the .ini fil
• III. What are the windows for?
• IV. What features does BSP have?
• V. What do I do with .map files?
• VI. BSP crashed my system and I'm mad, how do I complain?
• A. Known Bugs / Robustness Issues
• B. How to Report Bugs
• VII. What features will be added to BSP?
• VIII. Who am I? (Me, not you).
• IX. How to reach me.

I. What is BSP?

BSP is an editor for creating ".map" files compatible with the computer game Quake by id Software, Inc.

I highly recommend that you gather your pennies and order the full version of Quake so id can continue to produce great software.

II. What do I need to run BSP?

You will need a computer.

A. Hardware Requirements.

More specifically, you will probably want to run BSP on a computer similar to what is required to run Quake. I have developed BSP on a P90 with 16 Megs of RAM. If you have such a system, I think the program will work. If you don't at least have such a system, please don't flame me (see bug reporting below) if BSP doesn't work. I am not a commercial developer. I am just a hobbyist like you (or at least some of you). A 256 color display is necessary. I have not tried the program in high color or 16.7 M color, but I think it will work. I recommend running at the highest resolution your computer can muster in windows. My system runs at 1280 x 1024 and that is what I have used in developing BSP.

B. Software Requirements

I have developed BSP using Borland C++ v. 4.5. My computer currently runs Windows 95. However, for now, BSP is a 16-bit application and does not rely on any of the Win32 API. Therefore, I believe that BSP will run on a Windows 3.1 system. I'll try it at work and post word if this is so, but no promises for now!

I also run BSP on a computer with 16 Mb of RAM. If you have less, I don't know if it will work. BSP can use quite a bit of RAM when loading large .map files. If you have less than 16 Mb and BSP works or barfs with any kind of memory message, let me know (see bug reporting below, first).

BSP requires several Borland Run-Time Libraries to run. In particular, BSP requires the following libraries to be present (so far as I can tell):

• BC450RTL.DLL
• BIDS45.DLL
• OWL250.DLL

These files should reside in the same directory as the BSP executable

Files that come with the BSP.ZIP archive:

• BSP.EXE This is the executable, create an icon for this in Windows.
• BSP.INI The configuration file (see below) for BSP. Leave in the same directory as bsp.e.
• ENTS.QC The current list of all entities, extracted from the .qc files released by id and only including the essential information. This file needs to be in the directory listed for "entity_qc_directory" (see below).
• BADTEX.BMP This is a bitmap used when the texture wad key/value pair for a .map file either doesn't exist, or is invalid.
• HELP.HTM This file

C. Setting up the BSP.INI file

BSP uses an ".ini" file which I have creatively named "BSP.INI".

BEFORE YOU RUN BSP THE FIRST TIME, you will want/need to edit this file (using whatever ASCII text editor you want).

A typical BSP.INI file looks like this:

; ----------------- BSP.INI ----------------------
[BSP]
newmap=default.map
backup=backup.map
entity_qc_directory=c:\bc45\bsp3\
wad_directory=c:\qbsp\
map_directory=c:\qbsp\
default_wad=wizard.wad
badtex=c:\bsp\badtex.bmp
gridsize=16
stepsize=64
show_grid=0
show_coordinates=1
show_names=0
show_hits=0
far_clip_distance=-8192
; ------------------ END of BSP.INI ------------------

The entries in this file correspond to the following parameters:

• "[BSP]" This is the section heading, don't change this or the bsp.exe won't be able to read your settings!
• "newmap=" This sets the name of any maps created from scratch, i.e., blank maps.
• "backup=" This is the name of the file to write periodic backups to. For now, this setting is ignored.
• "entity_qc_directory=" This is the directory where the "ents.qc" file is located. In the above example, that directory is "c:\bc45\bsp3\". Don't forget the trailing backslash "\" or else BSP will not be happy.
• "wad_directory=" This is the directory where your texture .wad files are stored. If you don't have any, download them from: http://www.wf.net/~stephenc/. You will want to get at least one texture .wad file before running BSP.
• "map_directory=" This is the default directory to look for maps in. On my system, the processing tools qbsp, vis, and light reside in the directory "c:\qbsp\" (with trailing backslash). Thus, I have pointed BSP their for .map files and .wad files. You do not have to do this, it's up to you.
• "default_wad=" This is the .wad file to load when first starting BSP. It should sit in the "wad_directory". If this file does not exist, you will see "badtex" listed in the texture palette.
• "badtex=" This is the badtex.bmp file to load when a .wad is bad for some reason. Specify the whole path, including the file name, e.g., c:\bsp\badtex.bmp.
• "gridsize=" This is the default gridsize in world units.
• "stepsize=" This is the default unit to use when navigating the editing window using the keyboard.
• "show_grid=" This setting determines whether the grid is shown at startup of BSP. "0" means "NO" and "1" means "YES".
• "show_coordinates=" This setting determines whether, when the grid is on, coordinates are shown along the left and bottom axes.
• "show_names=" This setting determines whether the names of the entities are shown on the XY Map View.
• "show_hits=" This setting determines whether brushes which are "potentially selected" are drawn in blue with selection indices next to them (see "HITS" elsewhere herein).
• "far_clip_distance=" This setting determines the initial setting for the far clip plane. Note, this number should be NEGATIVE. If you use a positive number, nothing will show in the editing window! "-8192" will pretty much show the whole map to start.

III. What are the windows for?

Editing in BSP takes place in five windows:

• A. Edit Window
• B. XY View Window
• C. Entity Browser
• D. Texture Browser
• E. Selected Brush Window

A. The Edit Window shows a current 3D wire frame view of the map from the current camera position. If you perform an activity and this view does not update, hit the "F9" key to force a redraw of this window. The caption displays the current map being worked on. The circle in the upper right shows the current orientation of the camera view direction, in degrees.

At this point, clicking in the Edit Window only has one function. You can set the view direction by clicking in the orientation circle in the upper right. You will find this much faster than using the keyboard, especially for large levels with many brushes/entities.

This window can be slow to redraw on large maps. Bringing in the far clipping plane to about -512 or so will reduce the number of polygons which are drawn.

B. The XY View shows the current map from the top down. There are lists on the XY View to change the gridsize and there is a button to turn the grid on or off. In addition, the XY View contains the current scale for displaying the map.

The left and right mouse buttons are used with this view for performing a variety of operations depending upon which keys (or none) is/are also being held down:

• Left Mouse
• (no control key held down) Manipulate Brush/Clip Point.
• 1: If no brushes selected, creates a brush .
• 2: If brush selected and the click is inside the brush, moves brush in XY plane in the drag direction. If there are multiple brushes selected, it will move them all. (Note: For some reason, the update for moving multiple brushes can be very slow. I think it is because I recompute each whole brush constantly while dragging and this is slow. I may change this in the future).
• 3: If brush selected, and the click is outside of the brush, moves the closest face in the drag direction.
• 4: If you click on aclip point that's not currently selected, the click select's it. Dragging will move the clip point in XY plane.
• Shift - Select/Deselect Entity/Brush.
• Ctrl - Connect Entities (one should be selected, connects that one to the entity you click on)
• Ctrl + Shift - If brush selected, shears closest face or corner.
• Right Mouse
• (no control key held down) Position camera at click point.
• Shift - Place Clip Point.
• Ctrl - Set whole brush texture to current texture (single face texture setting is done in Selected Brush Window).
• Ctrl + Shift - Orient view direction based on drag angle.

C. The Entity Browser is used for modifying entity key/value pairs and also for creating new entities. The top portion of the window shows "classname" and its description. To create an entity, you would select an appropriate class. Create the brush to make the entity out of and then hit the "Make" button on the browser (or from the menu or control bar). The various check boxes are for setting appropriate flags for the currently selected entity. The key/value window lists all of the key/value pairs for the currently selected entity. The angle buttons add or modify and angle key/value pair for the current entity. The key and value windows can be used to add, edit, or delete key/value pairs from the current entity.

To add a key and value, type the key into the "Key" filed and the value in the "Value" field and hit the "Add" button. To remove a key value pair, select the pair from the list box and hit the "Del" button. To modify a pair, select the pair, type in the new value in the "Value" field and hit the "Add" button.

Clicking on the flag check boxes will insert the appropriate "spawnflags" for the selected entity. The top portion of the entity browser should contain a description of the various flags for each entity. The text is taken from id's .qc files. If you don't like it, modify the text in the ents.qc file. I'm not a .qc expert, so please refrain from asking me really detailed questions about flags and stuff.

D. The Texture Browser is pretty straightforward. Either select a texture from the list box, or click on it with the mouse. The yellow highlight will display around the current texture. There are also buttons to adjust the following:

• s - This is the "x" offset in texture space
• t - This is the "y" offset in texture space
• r - This rotates the texture in 90 degree increments
• sx - This flips the texture along the "x" (s) axis
• sy - This flips the texture along the "y" (t) axis
• ! - This button resets the s, t, r, sx, and sy values to the defaults. Otherwise, the values continue to apply to all chosen textures.

E. The Selected Brush Window is useful for several things. First, the window is really only relevant when one brush is selected. For now, the view is fixed and looks from +x to -x (or from right to left in the XY View). If the brush is too big or small for the Selected Brush Window, use the "+" and "- " arrows to adjust the size. The "?" button displays the textures for all of the faces of the brush. The "current" face is the yellow face and it's texture is written in yellow. The list box may be used to change the "current" face.

To change the texture of the whole brush, pick a texture in the Texture Palette and hit the "b" button. (Note: If more than one brush is selected, then all of the brushes will be painted with the selected texture. You have been warned.) To change only the current face (drawn in yellow), hit the "f" button.

Finally, the Selected Brush Window may be used to move the brush up or down, or to grow the top or bottom face of the brush. For now, the mouse drag interface is a bit clunky.

To move the whole brush up or down, simply click with the left mouse button inside the brush and drag up or down. For now, you don't have a lot of precision when doing this, big moves occur. For fine up/down motions of the whole brush, use the "-" and "=" ("+") keys on the keyboard. Sorry.

To stretch the top or bottom face of a brush, click just above the top of the brush (and the click should really be pretty close to the top) and drag in the appropriate direction to grow or shrink the top face of the brush. Same goes for the bottom. Alternatively, the top of the brush can be raised or lowered with the +Top and -Top buttons, respectively. Same goes for the bottom. The increment is set by the current gridsize.

The "w," "f," and "t" radio buttons are for wire, flat and texture modes in the Selected Brush Window. You can play with them, but for now, not much of interest will happen.

IV. What features does BSP have?

BSP has so many other features, I don't know where to begin. Just kidding. BSP has enough features to allow you to create fairly complicated .map files. In fact, some of the features may tempt you to go overboard. If you go wild, you will pay when you try to build the .map with qbsp and you wait, and wait, and wait. Spiral staircases are one of these features.

Portions of BSP are based directly upon id's QuakeEd. For the record, John Carmack gave me express permission to use any of the source I wanted. BSP is modeled, in many ways, after QuakeEd. I figured their feature list was a minimum and, thus, have implemented pretty much all of that functionality. The "ZChecker" is not in BSP, though, so editing is different.

Also, if you have selected brushes in one map, and then open a blank .map or open another .map file, the selected brushes will be copied over to the new map. This can be useful.

Other features include (from the button bar):

• Working with .map files:
• New Create a .map file from scratch
• Open Save an existing .map file for editing.
• Save Save current .map file.
• Save as Save current .map file under a new name.
• Miscellaneous settings:
• Preferences Set preferences (not implemented)
• Reload Reload ents.qc (probably not useful)
• Hits Toggles whether to display other brushes that could have been selected by last click on the XY View
• Names Toggles whether to show the names of entities on the XY View
• Coordinates Toggles whether, if grid is on, to show coordinates along left and bottom axes
• Grid Determines whether the grid shown in the XY View (for now, everything snaps to the gridsize, even if the grid is not shown)
• Moving selection around:
• (in menu only) X, Y, Z Move selected brushes along selected axis: X, Y, or Z.
• Moving camera around:
• Up / Down Level Move camera up or down a level (depending upon where you are in the map.)
• Working with selected brush(es):
• Mirror selected brushes along X, Y, or Z axis.
• Rotate selected brushes 90 degrees on X, Y, or Z axis.
• Complete Select brushes completely within the current selected brush. Deletes the "selection brush"
• Partial Select brushes that are partially or totally within the current selected brush. Deletes the "selection brush"
• Tall Removes the current selected brush and replaces it with a very tall brush.
• Short Removes the current selected brush and replaces it with a very short brush.
• (NEW) Rotate Rotates selected brush an arbitrary amount on X, Y, and/or Z axis.
• Make Entity Converts current selected brush into the entity currently listed in the Entity Browser window.
• Make Lights converts the selected brush (removes it) into the specified row, columns and depths of lights, with the light value selected from the dialog box.
• Stairs Removes the current selected brush and replaces it with stairs. Options are set via a dialog box. Stairs can be "floating", spiral, or block for now. Deletes the original selected brush. The new stairs are selected upon completion and can be placed as a unit.
• Room Takes the current selected brush and replaces it which six brushes that border where the original brush was. Removes the original brush.
• Arch Takes the current selected brush and replaces it with an arch. Options are set via a dialog box.
• Subtract Takes the current selected brush and carves it's interior out of every brush it touches. The original brush is left in place. To leave a "hole", just delete the original selected brush.
• Delete Deletes the currently selected brushes
• Working with the Clip Plane:
• Flip Flips the normal (side) of the clip plane which is used to cut portions off of selected brushes.
• Carve Once the clip plane is in place, the carve command causes the actual clipping of the brushes. Cannot be reversed.
• Up Moves the current clip point (up to three of which define the clip plane) up.
• Down Moves the current clip point (up to three of which define the clip plane) down.
• Working with the BSP windows:
• Arrange Arrange the windows (works best, for now, at 1280 x 1024 windows screen resolution)
• Tile Tile windows.
• Cascade Cascade windows.
• Miscellaneous:
• About About BSP.
• Exit BSP (currently does not prompt for saving current .map file)

Features on the Menu (almost all of the button bar features are in the menu):

• Edit | Select All Selects all brushes/entities
• Edit | Deselect All Deselects any selected brushes/entities
• Edit | Copy Copies the current selection and selects the copy. The copy is offset in XY by the current gridsize

Keyboard Features:

• Keys 0 - 9: Select/Deselect other "potentially hit" brushes. Based upon left mouse click in the XY View.
• F1-F3 Select Clip Point 1-3, respectively.
• F5 / F6 Move current Clip Point up or down, respectively.
• Esc If clip plane is shown, gets rid of it. If not, deselects and current brush. If an "entity" was the currently selected object, partially deselects the entity.
• F9 Redraw the Edit Window
• F12 Subtract selection
• Keypad "-" Delete selection
• Return Change mode between wire frame, flat, and textured. Doesn't do much now, except in wire frame mode
• Ins Carve selected brushes by Clip Plane
• Space Copy selected brushes/entity
• / Flip normal of Clip Plane
• O/P Change perspective distance in/out (like zooming)
• N/M Similar to O/P
• R/F Move far clipping plane in and out (see status bar while changing to see current value).
• A/W/D/X Move camera left, forward, right, or back (aligned to XY axis).
• Y / H Move camera up or down along Z axis.
• Keypad 2/4/6/8 Move selected brushes down, left, right, up in XY View
• - / = (+) Move selected brushes down or up along Z axis
• Left Arrow /
• Right Arrow Rotate camera left or right
• Delete / PgDn Pitch camera up or down (might be roll).
• Home / End Roll camera left or right (might be pitch).
• Up / Down Arrow Move forward / backward (not quite working correctly right now)
• B Rotate camera by 180 degrees.
• [ Increase step size (for moving camera with keyboard)
• ] Decrease step size (for moving camera with keyboard)

How does this "hits" thing work. If you try to select a floor and keep getting the ceiling instead, you need to use the 0-9 keys to select the proper brush. Any time a bare left click is made, BSP keeps track of all of the brushes the click could have selected. The "closest" is actually selected or deselected. But, up to 9 other brushes are stored in the 0-9 keys. Hitting these keys (usually you will only care about keys 0 to about 3) will toggle a particular brush on or off. If Show Hits is enabled, then the Edit Window will show the potential selected brushes in blue, along with index (key) numbers at the vertices. Use these numbers to select the brush you want. You'll have to play with this to get the idea.

V. What do I do with .map files?

Save them and then run qbsp, vis and light on them. Details for doing this can be found elsewhere.

VI. BSP crashed my system and I'm mad, how do I complain?

SAVE YOUR WORK OFTEN!!! I can't emphasize this point enough!

A. Known Bugs / Robustness Issues

Bugs fixed to date:

FIXED: 8/13/96 v. 0.11 Made bsp.ini error checking more robust to now present a file open dialog box when BSP can't find a file. Should solve most setup problems. If you are prompted to select a .qc, badtex.bmp or .wad file, your bsp.ini is not set up correctly. You should fix it, read the instructions carefully on this.

FIXED: 8/14/96 v. 0.12 If making lights, stairs or arches crashed the system b/c it didn't bring up adialog: try v.0.12, I think I figured out the problem.

FIXED 8/18/96 v. 0.15. Upon loading, the wad and world class names are displayed correctly. Cleaned up some view refresh problems. Added mirror/rotate 90 buttons. Added dialog to rotate on X, Y, and/or Z axis by arbitrary degrees. Made Selected Brush Window default to a larger view. Fixed problems with F12/brush subtraction on complex brushes (should work right now). Fixed (1/2 way :)) texture palette problem in 256 color mode (true color/high color still looks like garbage). Fixed Texture browser button "creep". Some other stuff I can't remember.

The following are bugs that I know of and intend to fix as soon as possible. Please don't send reports about these problems, unless you have a programming suggestion on how to fix the bug!:

• When I load a map file, the top of my video display sometimes gets garbled, but comes back, mostly, when I use the menus, etc.
• Big maps redraw kind of slow.
• Error saying "couldn't write map file" sometimes.
• After I do some editing, I can't seem to select any brushes. SOLUTION (for now): Save your current map and restart BSP. The map should load and work correctly.
• If I keep opening maps without shutting down BSP, it crashes after a little while. (Hey, sorry, it's an alpha version!).
• Preferences doesn't do anything.
• Using the "X" box on the window frame to close BSP doesn't seem to work. SOLUTION: Use the menu or control bar button.
• The palette for displaying the Texture Palette is "okay" (a bit off) for the first wad opened, but then looks like garbage. SOLUTION: Still working on it!
• When BSP crashes, all of my other windows programs also crash. SOLUTION: Until BSP is more stable, be careful, close down other programs, etc. SAVEOFTEN!
• BSP bleeds system resources - Yes, a memory leak is present, so keep an eye on your resources until future versions of BSP become more stable. BSP will act crazy after a while.
• Opening multiple instances of BSP crashes (at least one of the instances). SOLUTION: Try to restrain yourself.

B. How to Report Bugs

• CHECK THIS PAGE TO SEE IF THE BUG IS ALREADY LISTED.
• Wait two (2) days, I will update the bug list daily (or at least try to). Don't send me a report if I already listed the bug (unless you can tell me the solution, of course).
• Send me an e-mail telling me exactly what is happening, what system you're using, etc. (Please try to give me enough info to reproduce the problem. If I can't reproduce it, I can't fix it. If a particular .map file causes the crash, send the file to me as an attachment)

Please remember that this editor is a one man job, for a guy who has a very busy other life. Don't flame me about how BSP sucks. If you don't like it, there are/will be plenty of other options. This project started as a study of Binary Space Partitioning Trees and ended up far from their as an exercise to learn about Windows programming. The topic was new to me. Some of the bugs are from me being naive about Windows programming. Some are from me being an idiot :).

This editor is FreeWare. You get what you pay for.

VII. What features will be added to BSP?

• Currently, I intend to implement:
• XZ, an YZ editing panes (like XY View)
• Better copy/paste
• Feedback when dragging selections
• Copy To Vector Offset
• Moving whole clip plane at once
• Flat and texture preview modes
• Grouping of brushes/entities/other groups and displaying of only what you want to see (should speed up the editor, of course)
• Other canned items
• Built-in QBSP, VIS, and LIGHT
• New file format with export to .map file. This will allow:
• Faster load/save
• Negative brushes
• Storing groupings beyond current editing session
• Texture Wad Tools (if not done by 50 others by then)
• ?Random level generator...?
• Multiple .map files open at one time, copy/paste between them. (Remember, if you open a new map with some brushes selected, they will be copied to the other map. This can be useful.)
• Save / Restore on Window menu of user defined window positions.

And, I'm always open to suggestions about essential features!

VIII. Who am I? (Me, not you).

I am currently a Patent Attorney in Atlanta, Georgia. I am 28.

I went to law school at the University of Florida, my home state. I have a chemistry degree from Harvard.

I spent much of my time their, and since I was about 12 years old, programming computers. I was a computer consultant for Harvard and various organizations around Harvard for the four years I was there and for several years thereafter.

I like to play computer games, but am more interested in seeing how they are programmed.

I read alot.

I could say more, but that would be a bit pompous.

My resume is at http://www.needlepatent.com

IX. How to reach me.

Web:

http://ourworld.compuserve.com/homepages/bernier

E-mail:

bernier@atlanta.com

Snail mail address and phone number available upon request.