                                                        cutAlpha - BETA 0.4
                                                2016, Alias Conrad Coldwood


= INTRODUCTION ============================================================

This command-line tool exports static level geometry of most Build Engine
maps to iD Software's Quake maps. There's currently no support for actors
or entities, little support for textures, and no brush optimization.

Don't expect to be able to convert, compile and play. It just won't work.

But it will generate a geometry that is accurate enough that you can use it
as a base to port your levels. Also, be advised that this is a BETA release
and some features might change in the future, or be removed altogether.

I'm throwing in the (very dirty) source code.


= COMMANDS ================================================================

Every command has a shorthand, which is composed of the capital letters of
the long command. For instance, The short hand for "-SKip" is "-SK". Also
note that commands are case-insensitive.

-Replace
  Always replace output files.

-Group <file>
  Specifies the GRP file to use when files cannot be located. This system
  allows you to extract MAPs and ARTs directly out of the specified group
  file without having to extract them yourself. Because it is used as an
  alternative source, files already extracted have the priority over packed
  files (which is useful when using custom ART files).

-Input <file>
  Source file, must be a valid Build Engine map (almost anything should
  work, see list of supported formats).

-Output <file>
  Destination file. It will be replaced (after confirmation) if it already
  exists.

-Accuracy <level>
  Coordinates output accuracy, either "float" or "integer". While "float"
  provides a much better result, it's not supported by every version of
  QBSP. There's currently no correction in the rounding process.

-Scale <xy> <z>
  Rescale factor, applied on top of the hard-coded rescale factor (x: 1/16,
  y: -1/16, z: -1/128). Two values above 0 (X and Y uses the same value, Z
  uses an independant scaling).

-SKip <element>
  Elements that should be skipped during conversion. Can either be "floor",
  "ceiling" or "wall" (this parameter can be used multiple times). This
  option is pretty handy if you plan to port your map by recreating brushes
  manually (which would produce a much better result, and might be required
  for some games).

-Quake1
  Output a Quake I map file. In Quake II maps, three extra fields are added
  for each plane: SurfaceFlag, ContentFlag and MultiPurposeValue. These
  fields aren't supported by Quake I. Note that output maps should be fully
  compatible with Quake-based games such as Soldier of Fortune, SiN, Heavy
  Metal Fakk 2, Kingpin, Return To Castle Wolfenstein, etc.

-TexFolder <directory>
  This value is used when writing the map file, it's meant to tell QBSP and
  Radiant where textures are located (it's relative to the "textures"
  directory, located in the base/mod folder of the game). cutAlpha doesn't
  rely on this information, unless -TexExtract is also specified (in which
  case the specified directory becomes the destination directory)

-TexCaulk <file>
  This value is used when writing the map file, cutAlpha doesn't rely on
  this information. The caulk texture is used to cover faces that aren't
  visible, or faces that were created by the conversion process. By default
  "common/caulk" is used.

-TexExtract
  Automatically extracts necessary textures from TILES###.ART files. This
  option requires PALETTE.DAT to be available in the working directory.

-WallThickness <value>
  A value between 32 and 2048 to define wall thickness, in Build units.

-InRange <x1> <y1> <x2> <y2>
  By default, all sectors are converted. When using this parameter, only
  sectors located inside (even partially) the defined rectangular area will
  be converted (coordinates are in Build units).

-Debug <level>
  At level 1, a log file is written (or expanded) during execution, it
  contains everything shown during the conversion process. At level 2, more
  info is added (mostly loop iteration). At level 3, even more stuff is
  shown (the result of certain functions). By default, the debug level is 0
  (standard information, no log)


= SUPPORTED FORMATS =======================================================

Most of Ken Silverman's Build map versions are supported (specifically
version 3 to 7, which covers games such as Duke Nukem 3D, Redneck Rampage
and Shadow Warrior). Monolith's custom Blood map format version 6.00 (used
in the alpha leak), 6.03 (demo) and 7.0 (retail) are also supported:

Legend of the Seven Paladins 3D     v4    Sep 1994  Accend Incorporated
Duke Nukem 3D beta (aka Lame Duke)  v5              3D Realms
Witchaven                           v6    Jul 1995  Capstone Software
William Shatner's TekWar            v6    Aug 1995  Capstone Software
Duke Nukem 3D                       v7    Jan 1996  3D Realms
Witchaven II                        v7    May 1996  Capstone Software
Fate                                v7              DogBone Software
Powerslave (aka Exhumed)            v6    Dec 1996  Lobotomy Software
Redneck Rampage                     v7    Apr 1997  Xatrix Entertainment
Blood                               v7.0  May 1997  Monolith Productions
Shadow Warrior                      v7    May 1997  3D Realms
Nam                                 v7    Jun 1998  GT Interactive Software
Extreme Paintbrawl                  v7    Sep 1998  Creative Carnage
World War II GI                     v7    Jul 1999  TNT Team

The program is able to output two different map format: Quake or Quake II,
the later being compatible with Quake III Arena and games using either the
Quake II or III engine.


= WISHLIST ================================================================

Brush optimization (removing shading sectors, do not cut out inner loops
located above the ground level / under the ceiling level).

Better integer approximation.

Proper texture support would be huge.

Support for Blood RFF archive format?

Release file specifications for all supported Build formats and Quake.


= WHAT'S NEW ==============================================================

beta .2
- Better, configurable walls
- Very early texture "support"
- Conversion of a specific area
- Log file output
- Fixed a bug where skipping floor generation would crash the program
- Fixed a bug where corrupted walls would crash the program (Tekwar)
- Fixed a potential endless loop bug

beta .3
- Much better conversion ratio (no more issues with official Blood maps)
- Modified parameters list (merged some options, deleted others)
- Added custom rescale factor
- Fixed a bug where sectors would be improperly read because the index of
  wall[i].point2 isn't i + 1 (Blood)
- Fixed another bug where corrupted walls would crash the program (Tekwar)
- Fixed a bug where some shapes would falsely be considered clockwise

beta .4
- Added support for Ken Silverman's GRP files. Note: Powerslave's DAT files
  are also GRP files.
- Simple geometry texturing (most faces show the proper texture, but there
  is no alignment or scaling)
- Automatic texture extraction from ART files (proven that PALETTE.DAT and
  the ART files are available)
- Changed parameters again (sorry)


= ERROR AND WARNINGS ======================================================

getWallBefore:: failed to find wall[#]'s preceding wall
getWallAfter:: failed to find wall[#]'s following wall
  When creating solid walls, cutAlpha will search for the adjacent solid
  walls. This error is thrown when the preceding or following solid wall
  wasn't found. This message is a warning.

Sector2Area:: sector[#] corrupted, expected wall # to #, found #
  Sectors' walls are defined using a starting point (a wall index in the
  walls table) and a count (how many walls belong to that sector). On rare
  occasions, the wall index retrieved for a sector is located outside the
  range of walls that should be allocated to that sector. When such a thing
  happen, cutAlpha will close the most recent loop automatically. This
  message is a warning.

Sector2Area:: failed to merge innerLoop[#] to sector[#]
  This is a What The FUCK?! kind of error. Inner loops are supposedly all
  contained inside the main sector, which means that the inner loop should
  always be able to connect to the outer loop by tracing a ray going to the
  right. Sometimes, that doesn't happen, which means the loop that belongs
  to this sector is (at least partially) located outside the sector.

Sector2Area:: sector[#] is too small to process
  This warning is thrown when there's nothing left of the sector after
  removing its co-linear walls, overlaping points, and overlaping segments.

writeQuakeMap:: no area to write
  This error is thrown when no information is available to write the target
  map. This could happen if you have a Build map made of one unique and
  very narrow sector; or if you skipped the generation of all floors, walls
  and ceilings.

areaClip:: failed to clip sector[#]
  cutAlpha converts sectors into one or more convex shapes by projecting a
  ray from the edge of a wall that is forming an angle going "away" from
  the sector. It is expected that the ray will cut the shape in two parts,
  and both chunks are valid shapes. Sometimes, every attempt at cutting the
  shape failed, resulting in that error. Maybe the sector has two (or more)
  inner loops intersecting one another, or two (or more) walls of that
  sector intersect, forming a bowtie.


= FAQ =====================================================================

Q: Why do I get the message "FloatPlane: Bad Normal" after compilation?
A: Most likely, QBSP doesn't support floating point values, try converting
   the map again with "-accuracy integer".

Q: Why do I get the message "bounds out of range" after compilation?
A: Either a brush is located too far away from the origin of the coordinate
   system (try recentering the map to point 0, 0, 0); or the brush is too
   big to be processed (which can happen with large outdoor areas, or very
   long tunnels, there's no quick workaround for this: you'll have to
   shorten the section manually).

Q: Why do I get the message "leaked" after compilation?
A: Either a specific type of door wasn't converted as expected, or the
   rounding of decimal values created a gap between brushes. The way
   sectors are broken down in brushes right now isn't kind to QBSP. I need
   a better algorithm for that (turning shapes into triangles could work
   much better)

Q: What are the worst maps to convert?
A: Most bugs in the conversion originated from unexpected Build map tricks.
   Blood's BB1 and BB2 caused some headache until I figured out the two
   corrupted sectors were part of Shade's signature. I also had troubles
   with E1M4: walls in sector 191 (the underwater section on the far left
   of the map) are not ordered as I expected (outline walls are numbered:
   1353, 1366, 1367, and 1368). Sector 368 in Duke Nukem 3D's E4L1 (the
   kitchen near the mess hall) provides one inner loop before the sector
   outline, which I also didn't expect. Tekwar is a mess, some loops are
   not closed properly and instead propagates to other sectors, going far
   beyond the wallNum count (and subsequently caused the program to crash).
   Sector 573 in CITY1 and CITY3 (TekWar) is broken in two different loops,
   even though both loops are clockwise and sharing a wall (so they should
   in theory be divided in two sectors -- it doesn't make sense to me).
   There are also a few wall overlapping (see sector 731 in Level2, upper
   right corner of the map). There was no issue with Powerslave, but I
   still have to test Witchaven and Redneck Rampage.


= CONTACT =================================================================

Mail: aliasconradcoldwood@gmail.com
Site: http://gaarabis.free.fr/


= END OF FILE =============================================================
