Ubuntu Manpage: glbsp - GL Nodes builder for DOOM ports

NAME

       glbsp - GL Nodes builder for DOOM ports

SYNOPSIS

       glbsp [options] input.wad ... [-o output.wad]

       glbsp @argfile.rsp

DESCRIPTION

       glBSP  is  a  nodes  builder  specially  designed  to  be used with OpenGL-based DOOM game
       engines.  It adheres to the "GL-Friendly Nodes" specification, which means  it  adds  some
       new  special  nodes  to  a  WAD  file that makes it very easy for an OpenGL DOOM engine to
       compute the polygons needed for drawing the levels.

OPTIONS

Options begin with a single dash (you can also use two dashes like in many GNU programs).
Running glBSP without any options will show an informational screen.

-h -help
Show a summary of all the options.

-q -quiet
Quieter output. Information about each level (like the number of linedefs,
blockmap size, etc) is not displayed when this option is given, and a few other
messages are skipped. Important messages, like failure to build a certain level,
are still shown.

-f -fast
Allows glBSP to cheat a bit and re-use the original node information to create the
GL nodes, doing it much faster. Use this option to enable this feature. The
message "Using original nodes to speed things up" will be shown.

The downside to reusing the original nodes is that they may not be as good as the
ones glBSP normally creates, e.g. the special checks to minimise slime-trails don't
kick in, and the -factor value doesn't have much effect.

-w -warn
Shows extra warning messages, which detail various non-serious problems that glBSP
has while analysing the level structure. Often these warnings show a real problem
in the level (e.g. a non-closed sector or invalid sidedef), so they are worth
checking now and then.

-n -normal
glBSP usually detects if the normal node info (i.e. the non-GL variety) is
present: when yes, it is left untouched, otherwise glBSP creates it. This option
forces glBSP to replace the normal node data with newly constructed nodes.

-c -factor <num>
Sets the cost assigned to seg splits. Factor can be any number from 1 to 32, and
larger values make seg splits more costly (and thus glBSP tries harder to avoid
them), but smaller values produce better BSP trees. The default value is known to
be a good compromise.

-p -pack
Pack sidedefs, by detecting which sidedefs are identical and removing the
duplicates, producing a smaller PWAD.

NOTE: this may make your level a lot harder to edit! Therefore this is most useful
when producing the final WAD for public release.

-xr -noreject
Normally glBSP will create an simple REJECT map for each level. This options
prevents any existing REJECT map, such as one time-consumingly built by a dedicated
reject builder, from being clobbered.

The following options are rarely needed:

-v1 .. -v5
Specify the version of the "GL Nodes" spec to use (either 1, 2, 3 or 5). V1 is
considered obsolete now. The default is V2. Giving -v3 or -v5 will force certain
lumps to use the new formats, but is only useful for testing since glBSP will
automatically switch to V5 format whenever the ordinary limits are exceeded.

-m -mergevert
Merge duplicate vertices at the same location into a single vertex. This is
usually safe, but is not done by default because some engines (e.g. Risen3D) need
the duplicate vertices to stay separate for a special effect.

-y -windowfx
Lets glBSP detect and handle the "One-Sided Window" mapping trick. This can cause
problems in some engines so it is disabled by default.

-b -maxblock <num>
Sets the limit of the number of blocks the BLOCKMAP may contain before we truncate
it. Default is 16000. When the level is too large to fit, glBSP will truncate the
blockmap, so it covers less area on the level. This means that in the parts it
doesn't cover (at the outer edges) there is no collision detection: you can walk
through walls and other objects and bullets/missiles don't hit anything. On very
large but sparse levels, using a larger value (e.g. 30000) may help.

A more serious problem is when the blockmap overflows. The blockmap created would
be invalid, and could crash the DOOM engine when used. glBSP will create an empty
blockmap instead, causing modern ports to build their own blockmap.

-xp -noprog
Turn off the progress indicator.

-xn -nonormal
Forces glBSP to not create the normal node information when it detects that it is
absent.

-xu -prunesec
Removes any unused sectors that are found in the level. This has the potential to
cause problems, since in certain scripting languages (e.g. EDGE's RTS, or Doom
Legacy's Fragglescript) some commands use sector numbers directly, and pruning
unused sectors can cause those references to become invalid.

RESPONSE FILES

       New  in  version 2.20 is support for response files.  These are files containing a list of
       options.  You specify the response file by prefixing it with '@'.  For example:

       glbsp @argfile.rsp

       The "@argfile.rsp" on the command line will be replaced with the contents  of  that  file.
       New-line characters are treated like spaces.  Recursion (using '@' inside a response file)
       is not supported.

ZDBSP NODES

       When the normal nodes overflow, older versions of glBSP would simply write out the invalid
       node  data.  glBSP 2.20 and higher now write the node data in the ZDBSP format (originally
       created for the ZDoom engine).

AUTHORS

       Andrew Apted created glBSP and glBSPX and continues to maintain them.

       Andrew Baker, Janis Legzdinsh, André Majoral and Darren Salt have  contributed  code,  and
       Marc Pullen helped with the documentation.

       glBSP  was  originally based on BSP 2.3 (C) Colin Reed and Lee Killough, which was created
       from the basic theory stated in DEU5 (OBJECTS.C) by Raphael Quinet.

LICENSE

       This program is free software; you can redistribute it and/or modify it under the terms of
       the  GNU  General  Public  License  as  published  by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

       This program is is distributed in the hope  that  it  will  be  useful,  but  WITHOUT  ANY
       WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.  See the GNU General Public License for more details.