                                                           SectorCut  version .9
                                                           Alias Conrad Coldwood
                                                                    January 2018


== I N T R O D U C T I O N ==

This command-line tool is designed to convert static geometry from popular 2.5D
first person shooters from the nineties (some 20 games over 3 different engines)
to Radiant maps (Quake or Quake II format). It can also convert the required
textures to 32-bit per pixel TGA, WAL, MIP, Quake's WAD2 and Half-Life's WAD3.


== W H A T ' S   N E W ==

Release .1 (added since cutAlpha):
  - Added support for the Doom Engine and the Jedi Engine.

Release .2:
  - New sector conversion system.
  - Fixed a bug where PAK files (Quake) wouldn't be read properly.
  - Rewrote part of the notification system.
  - Renamed some parameters.
  - Added -DebugVerbose 
  - Added -DebugLog

Release .3:
  - DebugVerbose 3 now displays the entire file system (use it with DebugLog to
    obtain an easy to read, complete list of files stored in resource files)
  - Added support for masked walls (Doom Engine only).
  - Self-neighboring walls are no longer "fixed", discarded instead.
  - Only the closest visible vertex is used for sector splitting.
  - Added -Skip as a replacement for -SkipWall, -SkipCeiling, -SkipFloor.
  - Debug logs are now named DEBUG####.LOG

Release .4:
  - Tweaked notifications again.
  - Fixed Doom wall patches composition (ie. Doom's "brown144")
  - Rewrote wall creation (walls' thickness is constant, angles are accurate)
  - Added -TextureDummy

Release .5:
  - Fixed a bug where the wrong vertex would be selected when multiple points
    are stacked on top of each other.
  - Fixed a bug where vertices standing on top of walls would cause the program
    to think there's no wall visible.
  - Fixed a bug where vertices would not be considered standing on a segment
    because of said segment's direction.
  - Added prompt for confirmation when using -DebugVerbose > 1.
  - Added support for compressed and animated BM textures (Dark Forces).
  - Tweaked warnings & errors notifications.

Release .6:
  - Fixed a bug where some brushes would have co-planar faces.
  - Added bulk conversion.
  - Rewrote texture extraction process to accommodate bulk conversion.
  - Increased tolerance for precision loss when identifying wall order (only if
    the sector has one loop).

Release .7:
  - Fixed a bug where the command line parser would get stuck in an endless loop
    if two parameters are identical.
  - Fixed a bug where loops would not always be properly tagged clockwise.
  - Rewrote the scaling system.
  - Added -WallThickness (in radiant units)
  - Added -MapScale
  - Added -MapCenter

Release .8:
  - Fixed -MapScale (Y would always have the same value as X).
  - Fixed slopes not being scaled properly.
  - Added support for masked walls (Build Engine).
  - Releasing some doc.

Release .9:
  - Fixed a bug where files with any special attribute (such as read-only) would
    not be recognized at all.
  - Fixed a bug where Dark Forces levels would not be converted because of a
    parameter recognition error.
  - Added support for RFF 3.1 (Blood with Plasma Pak)


== S U P P O R T E D   G A M E S ==

    GAME (BUILD ENGINE)                  MAP   RELEASE   DEVELOPER
 1  Legend of the Seven Paladins 3D      v4    Sep 1994  Accend Incorporated
 2  Duke Nukem 3D beta (aka. Lame Duke)  v5    /         3D Realms
 3  Witchaven                            v6    Jul 1995  Capstone Software
 4  William Shatner's TekWar             v6    Aug 1995  Capstone Software
 5  Duke Nukem 3D                        v7    Jan 1996  3D Realms
 6  Witchaven II                         v7    May 1996  Capstone Software
 7  Fate                                 v7    /         DogBone Software
 8  Powerslave (aka. Exhumed)            v6    Dec 1996  Lobotomy Software
 9  Redneck Rampage                      v7    Apr 1997  Xatrix Entertainment
10  Blood                                v7.0  May 1997  Monolith Productions
11  Shadow Warrior                       v7    May 1997  3D Realms
12  Nam (untested)                       v7    Jun 1998  GT Interactive Software
13  One Unit: Whole Blood                v7.0  Oct 1998  Monolith Productions
14  Extreme Paintbrawl (untested)        v7    Sep 1998  Creative Carnage
15  World War II GI (untested)           v7    Jul 1999  TNT Team

    GAME (DOOM ENGINE)                         RELEASE   DEVELOPER
16  Doom                                       Dec 1993  iD Software
17  Doom II: Hell on Earth                     Sep 1994  iD Software
18  Heretic                                    Dec 1994  Raven Software
19  Ultimate Doom                              Apr 1995  iD Software
20  Hexen: Beyond Heretic                      Oct 1995  Raven Software
21  Strife: Quest for the Sigil (untested)     Feb 1996  Rogue Entertainment
22  Final Doom                                 Jun 1996  iD Software
23  Chex Quest (untested)                          1996  Digital Cafe

    GAME (JEDI ENGINE)                   MAP   RELEASE   DEVELOPER
24  Dark Forces (it "works")             v2.1  Feb 1995  LucasArts

    FILES (IN)
    GRP - Duke Nukem 3D, Powerslave, Redneck Rampage, and Shadow Warrior
    MAP - Ken Silverman's 3, 4, 5, 6, 7 and Monolith's 6.00, 6.03 and 7.00
    ART - Build Engine art files version 1
    RFF - Blood archives version 2.0 (demo), 3.0 (retail) and 3.1 (plasma)
    WAD - Doom Engine (both IWAD and PWAD)
    GOB - Dark Forces archives version 1.0
    LEV - Jedi Engine version 2.1
    BM  - Jedi Engine art files (standard, compressed and animated)

    FILES (OUT)
    WAD - Quake (v2) and Half-Life (v3) texture files
    MIP - Quake texture file
    WAL - Quake 2 texture file
    TGA - TrueVision Graphics
    MAP - Output levels for Quake-based games (Quake, Hexen II) as well as
          Quake 2 and Quake III Arena based games (Quake 2, Kingpin, Soldier of
          Fortune, SiN, Quake III Arena, Soldier of Fortune II, Return to Castle
          Wolfenstein, etc.)


== P A R A M E T E R S ==

-Level <mask> <target>
  Source map (always specify the file format for this one) and target map (will
  always be set to ".map", unless the source map is a file mask). For DOOM, the
  source map will be something along the lines of E?M? (Episode 1 to 4, Mission
  1 to 9). For Duke Nukem 3D, it will be E?L?.MAP (Episode 1 to 4, Level 1 to
  11). DOOM II and Hexen uses MAP?? (?? is a value between 1 and 32). Dark
  Forces uses *.LEV maps; Important: you can only load files from the working
  directory, or located inside resource files. You may convert multiple maps at
  once using a mask (for instance "E1M?" or "$*.MAP"); the target name is used
  as a directory in bulk conversions.

  -Level MAP11 edit.map
    Load and convert MAP11, output EDIT.MAP

  -Level MAP* AllOfIt
    Convert all levels starting with MAP, output files to "AllOfIt/" (located in
    the working directory).

-ResFile <resources>
  This parameter enables the use of files stored inside resources (GRP, RFF and
  DAT for Build, WAD for Doom, and GOB for Dark Forces; PAK is also supported so
  it is possible to read Quake's palette directly from it, would you ever need
  to convert ART tiles to WAD textures). Resources files must be separated by a
  comma. When specified, resources are used to setup the proper conversion mode
  (Build, Doom or Jedi). You cannot mix multiple types of resources (for
  instance, loading a WAD and a GRP). Later resources overwrites earlier.

  -ResFile "DOOM.WAD, GREED.WAD"
    Load both DOOM.WAD and GREED.WAD; GREED.WAD overwrites DOOM.WAD

-WallThickness <units>
  How thick outer walls and masks are (in radiant units, unaffected by the
  scale). The default value is 4.

-MapScale <h> <v>
  Rescaling factor of the map. The first value is used for both X and Y values
  (that is the horizontal plane), the second value is used for the Z value (the
  vertical plane). Try to convert the map with the default scale (1.00, 1.00) to
  see how it goes, you will likely need to adjust the scale depending on the
  original and target game. Important: when loaded maps are converted to Build
  units, so do not trust the original map metrics if you know them. Note that
  sectors may become too small to be converted after rescaling.

-MapCenter
  Center the map coordinates.

-textureTGA <path>
-textureMIP <path> <palette>
-textureWAL <path> <palette>
-textureWAD2 <name> <palette>
-textureWAD3 <name>
  Extract textures as TGA (32-bit per pixel), WAD2 (Quake), WAD3 (Half-Life),
  MIP (Quake), or WAL (Quake II) files. In some instances, a target palette is
  required (for Quake and Quake II). Palettes are simple files of 768 bytes,
  three bytes per color, one byte per attribute, in RGB order. To extract Build
  textures, make sure all TILES###.ART files are available. To extract Doom
  textures, always include the internal WAD first (ie. DOOM2.WAD). To extract
  Dark Forces textures, add TEXTURES.GOB to the list of resources.

-TextureDummy <path>
  Defines where textures are to be found. No texture is extracted though, this
  parameter is useful when textures are already available.

-Skip <element>
  Elements that should not be converted, separated by a comma: "wall", "floor",
  "ceiling", and "mask". Ceilings and floors are the top and bottom brushes of
  each sector. Walls are "solid walls" (those encasing the map). Masks are
  special transparent walls that often appear in-between sectors.

  -Skip "ceiling, mask"
    Skip conversion of ceilings and masks.

-Quake1
  By default, maps are exported to Quake II format (which is used by many other
  games, such as SiN, Soldier of Fortune, Quake III Arena, etc); Using this
  parameter will enable Quake I format instead (used in Quake and Hexen II).

-Replace
  Replace existing files without prompt.

-DebugVerbose <level>
  Provide more details on current operations. "0" displays only minimal info,
  "1" displays fixing attempts and automated tweaks, "2" displays non-trivial
  function calls, "3" displays information processed in loops (overkill), "4"
  gives an in-depth log of all operations (really overkill). You may use "-1"
  to make the program completely silent. As a general rule, don't use this
  parameter unless you really HAVE to.

-DebugLog
  Writes "debug.log" in real-time (can be HDD intensive in overkill modes).


  sectorcut.exe -RF doom2.wad -L map11 CircleOfDeath.map -TGA tex_cod
    Load resource file "DOOM2.WAD", convert MAP11 to CIRCLEOFDEATH.MAP, extract
    textures as TGA files to TEX_COD/ (in the current directory).

  sectorcut.exe -RF doom.wad,damage.wad -L e1m1 Damage.map -TGA dmgTex
    Load resource file "DOOM.WAD" and "DAMAGE.WAD", convert E1M1 to DAMAGE.MAP
    and extract textures as TGA files to DMGTEX/ (in the current directory).

  sectorcut.exe -level e1l1.map hollywood.map -skip ceiling -wallthickness 2
    Convert E1L1.MAP (the file must be located in the current directory) to
    HOLLYWOOD.MAP; no texture conversion, skip ceilings; set wall thickness to
    2 radiant units.

  sectorCut.exe -RF SW.GRP -dv 3 -dl
    List all files contained in "SW.GRP" and store the result in a debug log; no
    map conversion.


== P R O C E S S   O V E R V I E W ==

Here's a short explanation of the conversion process for those interested.

Source maps are not directly converted to brushes; instead, their content is
"stuffed" (a rough conversion with little to no validation) into a custom map
format called "bridgeMap". This format is inspired by Build map's and supports
extra features found in Doom and Jedi, such as texture names and the "three
textures per wall" ability.

The bridgeMap is then re-organized (each sector must have one and only one outer
loop, each inner loop is sorted right to left and top to bottom, the first wall
of each loop starts with the rightmost-topmost vertex available, walls of outer
loops are sorted in clockwise order, walls of inner loops are counter-clockwise,
etc.) and cleaned from engine-specific tricks (overlapping walls, misplaced
inner loops, etc.) As the number of walls and sectors can be affected by this
process, all the information related to sector and wall indices must be
calculated all over again.

Finally, the bridgeMap is converted to a Radiant map; The first step is to merge
inner loops with the outer loop (from the rightmost-topmost vertex of the inner
loop, project a ray to the right and find the nearest visible wall of the outer
loop, find the closest points located in the triangle formed by the corner, the
starting and ending points of the visible wall, and "cut" the sector using the
newly created edge between the corner and its closest visible point, this merges
the inner loop into the outer loop -- repeat the operation until there's no more
inner loop). Then, concave sectors are broken into multiple convex pieces (this
time, select the vertex forming a reflex inner angle (180+ degrees), and project
a perpendicular ray to the right to find the nearest visible wall, find nearest
vertex in triangle, cut the sector in two using that new line), slopes are
calculated, outer walls are created, etc.


== S P E C I A L   T H A N K S ==

I'd like to thank many people: those who invested so much time in reverse
engineering Doom and Dark Forces, those who released their source code or made
their development notes public, and those who provided invaluable math papers.
Thanks a bunch!

Doom Engine
  John Carmack, Matthew S Fell, Coleman Reed Ammerman, John Wolsh,
  Scott Amspoker, Jeff Bird, Alistair Brown, Frans P. de Vries, Paul Falstad,
  Robert Fenske, Nelson Fernandez Jr., Uwe Girlich, Stuart Herbert,
  Herre de Jonge, Tom Klok, Bernd Kreimeier, Steve Larsen, Hank Leukart,
  Greg Lewis, Joel Lucsy, Sean Malloy, John A. Matzen, Steve McCrea,
  Brian McKimens, Tom Neff, Tom Nettleship, Elias Papavassilopoulos,
  Robert D. Potter, Raphael Quinet, Colin Reed, Joost Schuur, Steve Simpson,
  S. Sproston, Matt Tagliaferri, Ted Vessenes

Build Engine & Blood
  Ken Silverman, Matt Saettler, DeepColdGrave, JM, Flanker, BME, Cosmo, ReBUILD

Dark Forces
  Yves Borckmans, Jereth Kok, Alexei Novikov, David Lovejoy, Serge Debroeyer, 
  Don Sielke, Florian Enhelhardt, Paul Nemesh, Randy Greene, Carlos Gomez,
  Jonathan Wise, Nicola Salmoria, Michael Taylor, Carl Kenner, Len Bowers, 
  Blake Crosby, Peter Klassen, Anthony Hall, Paulius Stepanas

Other
  David Eberly, Eric Weisstein


== C O N T A C T ==

   Mail: AliasConradColdwood@gmail.com
Website: http://gaarabis.free.fr/
