----------------------
Enhanced Quake Map Compiling Utilities - release 0.9b
Ported/Modified by Frank Condello
Web <http://www.planetquake.com/paroxysm/>
Email <pox@planetquake.com>

----------------------
USAGE:

These three commandline utilities allow you to compile Quake1 levels using features not available in the original compiling tools released by Id Software.

eQBSP and eVIS are Mac ports of the Quest Map Editor tools by Alexander Malmberg <http://quest-ed.sourceforge.net/> with a few more enhancements added in (see the "Commands.txt" file for supported commands)

Tyrlite+ is a port of Tyrlite0.94 by Kevin "Tyrann" Shanahan <http://www.planetquake.com/tyrann/> with some modifications made to support RGB lighting (in addition to RGBA), OpenQuartz <http://openquartz.sourceforge.net/> noise extensions, a progress indicator more consistent with eVIS, and a "_notents" key for lights.

All of these utilities require MacOS8.6 or higher, with CarbonLib 1.2.5 or later. They will also run native on MacOSX.

IMPORTANT: Read the files in the "PC READMES" folder for detailed info on features and usage. All supported eQBSP and eVIS commands are listed in the "Commands.txt" file, including Mac-only additions for all utilities.

----------------------
STUFF YOU NEED TO KNOW:

These tools were created to work the Quiver map editor <http://quiver.telefragged.com/>. The "eUtils Defs" file contains entity definitions, and should be placed in Quiver's "Definitions" folder. You can remove the original "Quake" definition file since this new file has the complete set of entities plus support for Tyrlite+, and detail brushes. The new light attributes show up in all light entities as wait, delay, mangle & _color (again, see the PC readme for usage info). Some of Tyrlite+'s options affect global lighting and need to be set in the worldspawn entity. Quiver does not allow the addition of worldspawn attributes, so a worldspawn entity has been included in the new definition file that contains the new lighting options. To modify these global lighting parameters, place a "Global Light" entity  anywhere in your map and edit the default settings  ("Global Light" can be found in the "Lights" entity group).

----------------------
DETAIL BRUSHES:

eQBSP and eVIS have the ability to use detail and hint brushes. You can create a detail brush by converting it into an "am_detail" entity (available in the "Special Structures" entity group). For more info on Detail brushes, please see the "Detail Brushes" section in the "OBJ2MAP User Guide" (included in this distribution).

----------------------
SPECIAL TEXTURES:

The "Textures" folder in this package contains a small WAD with "hint", "skip" and "ignore" textures, you should place a copy of this WAD in Quiver's "Textures" folder if you want to use these features. Any information found on the internet on using hint and skip textures for Quake2 (and detail brushes for that matter) is relevant for use in Quake1.

The "ignore" textures can be used to make a surface invisible in GLQuake (but otherwise behave like normal). eQBSP uses a horrid hack for ignore textures that exploits a bug in GLQuake, meaning that ignore textures don't (currently) work with software rendered Quake (the surface is rendered as a generic "checkerboard"). Note that textures with the word "ignore" anywhere in their name behave the same way (to allow for ignore liquids/skies etc.).

----------------------
MULTIPLE WAD SUPPORT

eQBSP doesn't rely on a map's "wad" key to find textures. It instead searches all WAD files placed in it's "Textures" folder, automatically extracting the first matching texture found. WAD files in the "Textures" folder must end with the file extension ".wad", but they can be aliases to WADs rather than the actual file. This makes it simply to share textures between eQBSP and Quiver or other map editors.
IMPORTANT: Quiver can extract textures from the bsp files in the default Quake paks for use within the editor, but eQBSP is not currently capable of reading those textures (it only reads WAD files). If you're using standard Quake textures in your maps, you can get a WAD that contains all of them for use with eQBSP here:
<ftp://3darchives.in-span.net/pub/idgames2/graphics/texture_wads/quakewad.zip>

More assorted WADs can also be found  in the "Quake & QuakeWorld" section at the PlayHouse website <http://www.planetquake.com/paroxysm/>

----------------------
LIGHT NOISE EXTENSIONS:

Tyrlite+ contains support for OpenQuartz <http://openquartz.sourceforge.net/> LIGHT noise extensions. These allow you to apply noise algorithms when lighting a level to break up common color-banding problems, or acheive more "organic" looking lightmaps. The following attributes have been added to the eUtils Quiver defs for all lights:

"Noise Level"  (_noise) accepts a floating point value from 0-1.0 (0 is no noise). You can "overexpose" the noise with values greater than 1.0, but the effect is usually undesireable (values of 0.5 or less are best for subtle effects).

"Noise Type" (_noisetype) can be set to 0 (Random), 1 (Smooth), or 2 (Perlin).

"Noise Resolution" (_resolution) controls the size or scaling of the effect. Higher numbers make the end effect larger (lower detail).

"Perlin Noise Persistence" (_persistence) This controls the perlin noise decay per octave.

You can use the "-noise" switch from the commandline to add random noise to all lights, but note that you cannot currently use noise on Global lights (Sunlight or Minlight).

----------------------
ABOUT BSP VERSIONS:

These Utils will generate one of three BSP versions depending on commandline parameters used:

BSP29 - The original Quake BSP version.

BSP30 - This format contains RGBA lighting information, and is widely supported in PC Quake engine mods. Some confusion surrounds this format since HalfLife maps are also version 30, so this is often referred to as "fake" version 30. Many engine modders have recently dropped support for this format in favour of external ".lit" files.

BSP01 - This format was created exclusively for the now defunct eQuake engine project. It contains RGB lighting information, and lacks internal textures to keep file size at a minimum.

The utils automatically handle BSP versioning in a foolproof fashion:
eQBSP will always generate BSP29 maps unless the "-nogfx" switch is used, in which case a BSP01 file is generated. Processing a BSP01 file with Tyrlite+ will always force RGB lighting, otherwise, Tyrlite+'s "-colored" switch (or "-coloured", or "-bsp30" as per 0.92 changes) can be used to generate "fake" BSP30 maps. Running Tyrlite+ without the "-colored" switch creates the standard BSP29 format.  Use "-lit" in Tyrlite+ to generate a BSP29 plus an external ".LIT" file. eVIS transparently compiles all BSP versions without changing the version number.

Basically, if you use "-nogfx" in eQBSP, you'll end up with a BSP01 map. Otherwise Tyrlite+ controls the version number,
(Note: Using more than one -colored/-lit setting in Tyrlite+ will result in the last one encountered being used).
 
----------------------
BUGS & LIMITATIONS:

These apps are RAM hungry lil"buggers. They should run fine with the default RAM settings on most maps, but you may have to increase their RAM partitions in the Finder's "Get Info" box if they start crashing or unexpectedly quit. If you're still getting "Out of memory!" errors, you may have to restart the computer. It's a good idea to run them on MacOSX if you can, just leave'm be in the background (they may appear to "hang" at times, but this is just how they work - they will also hog your CPU(s) like no tomorrow)

eQBSP has been modified to read Mac text files (since Quiver .map files export in Mac format). It will still work with DOS files, but UNIX files are currently not supported (Use a plain text editor like BBEDIT or mi to change the format in that case).

eQBSP doesn't always find leaks (even obvious leaks), and the points file is basically useless if it does. If eVIS refuses to VIS a map that seemed to build fine with eQBSP, then you've probably got a leak...

You can NOT use an alias to Quiver's entire "Textures" folder, only aliases to individual WADs inside that folder.

The progress indicators are a little buggy (under/over shoot), but they're better than nothing.

These are commandline apps - they are not meant to be pretty or easy to use.

----------------------
VERSION HISTORY:

r10 July 7, 2002
- fixed eVis crash when run with "-noambient"
- fixed eQBSP crash when processing am_detail entities containing no valid brushes
- eQBSP reports the coordinates of the first point on the bad face for "didn't split the polygon" errors
- eQBSP max brush limit raised by 1024
- selectively disable func_water* face mirroring in eQBSP by setting a "_nomirror" key to non-zero
- added newline at start of error messages (don't print in the middle of progress displays)
- fixed occasional "GetFileSpace: overrun" errors in Tyrlite+ when lighting BSP01 (RGB) maps
- Tyrlite+ checks "_notents" key for non-zero value (light will not affect submodels if true)

r9 June 10, 2002
- Tyrlite in sync with PC release 0.94 (last Mac release was based on 0.8)
- Tyrlite PC changelist between 0.8  and 0.94 (see PC README for more details)
	- Added .lit support
	- Added some checks for entity key/value lengths
	- Added check for too many switching lights
	- Fixed bug with "-nominlimit" option when not using colored lights.
	- Downgraded "not 3 values for color" to a warning for compatability with some QC mods.
	- Correctly calculate sample points for surfaces using non-standard texture alignment
	- added check for tracestack overflow
	- some cleanups, local functions made static, more const stuff
- Added OpenQuartz noise extensions to Tyrlite (renamed Tyrlite+ to reflect additional features)
- eQBSP mirrors inside faces of "func_water" entities. (NOTE: func_water is not a standard Quake entity)

r8 May 11, 2002
- eQBSP handles 'degenerate edge' errors internally, ignores 'point off plane' errors and 'CanonicalVector: degenerate' error reduced to a warning.
- eQBSP ignores extra brush info it doesn't understand (will now work with GTKRadiant maps that use extra texture alignment coordinates)
- eQBSP supports "NOT DETAIL" am_detail brushes used by OBJ2MAP
- "ignore" textures work in vanilla GLQuake
- Point files reverted to original Quake format (not Quest)
- Using a malloc wrapper to catch memory errors. 
- added rVis optimization to eVIS (faster - sometimes much faster)
- removed "clip" texture from utility.wad (use Quake's to avoid mismatches)

r6-7
- experimental developer releases

r5 June 10, 2001
-Added targets for the raw2map & tri2map terrain generators by Seth Galbraith
-Can now flag detail brushes as pass-through or solid (default is solid)
-Fixed mkdir (now properly points to the Mac IO wrapper) - not used anyway
-"ignore" textures flagged as TEX_SPECIAL (unused lightmap nolonger generated)
-Increased stack to 1024k fixing random crashes on large maps
-Default VIS level is now 4 (highest) was 2 (don"t need -level 4 switch anymore)
-Got rid of Tyrlite file logging routines (Code clean up only; was never enabled)
-Fixed some inconsistencies with the "plst" resources used by MacOSX
-Cleaned up source/project slightly

r4 March 30, 2001
-All utils are Carbonized (NOT TESTED IN OSX!)
-Multiple BSP versions supported across all utils
-Tyrlite can now output RGB or RGBA lightmaps (BSP01 and BSP30)
-eQBSP now contains the -nogfx option to exclude texture mips (BSP01)
-Cleaned up source compiling issues with Tylite's thread files
-Added Mac vers and plst resources

r3 February 10, 2001
-eQBSP nolonger chokes on texture names with 16 characters
-eQBSP nolonger reports that texture frames were added when in fact they were not.
-eQBSP now defaults to a subdivide value of 256 rather than 240 (quicker compiles & render speed)
-Increased number of valid faces per brush to 128 to deal with nasty carved geometry
-Tweaked eVIS's progress indicators
-Tyrlite's progress indicator changed to match eVIS (much faster now that SIOUX doesn't update every face)

r2 January 18, 2001
-eQBSP's multiple wad texture searching now works properly
-eQBSP no longer prints debug info when parsing detail brushes
-eVIS replies with "LoadPortals: No vising required (numportals: 0)" instead of "Out of memory! malloc failed for 0 bytes!" when vising simple one room maps.
-eVIS properly reports "-verbose" in usage string instead of "-v"
-Worked around a glitch in Tyrlite's progress counter to avoid truncating the total face count
-Upped the recommended RAM to 128MB, minimum to 64MB (virtual memory is fine)

r1 January 12, 2001
-Initial unified release

----------------------
eQBSP, eVIS and Tyrlite are distributed under the GNU GENERAL PUBLIC LICENSE (see gnu.text for more info). Sourcecode is available from <http://www.planetquake.com/paroxysm/>