289 lines
11 KiB
Groff
289 lines
11 KiB
Groff
.\" Process this file with
|
|
.\" groff -man -Tascii qbsp.1
|
|
.\"
|
|
.TH QBSP 1 "TYR_VERSION" TYRUTILS
|
|
|
|
.SH NAME
|
|
qbsp \- Compile a Quake BSP file from a MAP source file
|
|
|
|
.SH SYNOPSIS
|
|
\fBqbsp\fP [OPTION]... SOURCFILE [DESTFILE]
|
|
|
|
.SH DESCRIPTION
|
|
\fBqbsp\fP is a tool used in the creation of maps for the \fB id Software\fP
|
|
game \fBQuake\fP. qbsp takes a .map file as input and produces a .bsp file
|
|
playable in the Quake engine. If the \fIDESTFILE\fP argument is not supplied,
|
|
the output filename will be chosen by stripping the file extension (if any)
|
|
from \fISOURCEFILE\fP and appending the .bsp extension.
|
|
|
|
.SH OPTIONS
|
|
.IP "\fB\-nofill\fP"
|
|
Doesn't perform outside filling
|
|
.IP "\fB\-noclip\fP"
|
|
Doesn't build clip hulls
|
|
.IP "\fB\-noskip\fP"
|
|
Doesn't remove faces using the 'skip' texture
|
|
.IP "\fB\-onlyents\fP"
|
|
Only updates .map entities
|
|
.IP "\fB\-verbose\fP"
|
|
Print out more .map information
|
|
.IP "\fB\-noverbose\fP"
|
|
Print out almost no information at all
|
|
.IP "\fB\-splitspecial\fP"
|
|
Doesn't combine sky and water faces into one large face
|
|
.IP "\fB\-transwater\fP"
|
|
Computes portal information for transparent water (default)
|
|
.IP "\fB\-notranswater\fP"
|
|
Computes portal information for opaque water
|
|
.IP "\fB\-transsky\fP"
|
|
Computes portal information for transparent sky
|
|
.IP "\fB\-nooldaxis\fP"
|
|
Use alternate texture alignment algorithm. The default is to use the original
|
|
QBSP texture alignment algorithm, which required the -oldaxis switch in
|
|
tyrutils-ericw v0.15.1 and earlier.
|
|
.IP "\fB\-forcegoodtree\fP (experimental)"
|
|
Force use of expensive processing for SolidBSP stage. Often results
|
|
in a more optimal BSP file in terms of file size, at the expense of
|
|
extra processing time.
|
|
.IP "\fB\-bspleak\fP"
|
|
Creates a .por file, used in the BSP editor
|
|
.IP "\fB\-oldleak\fP"
|
|
Create an old-style QBSP .PTS file (default is new)
|
|
.IP "\fB\-nopercent\fP"
|
|
Prevents output of percent completion information
|
|
.IP "\fB\-bsp2\fP"
|
|
Create the output BSP file in BSP2 format. Allows the creation of much larger
|
|
and more complex maps than the original BSP 29 format).
|
|
.IP "\fB\-2psb\fP"
|
|
Create the output BSP file in 2PSB format. This an earlier version of the
|
|
BSP2 format, supported by the RMQ engine (and thus is also known as the
|
|
BSP2rmq or RMQe bsp format). original BSP 29 format).
|
|
.IP "\fB\-leakdist [n]\fP"
|
|
Space between leakfile points (default 2)
|
|
.IP "\fB\-subdivide [n]\fP"
|
|
Use different texture subdivision (default 240)
|
|
.IP "\fB\-wadpath <dir>\fP"
|
|
Search this directory for wad files (default is cwd)
|
|
.IP "\fB\-oldrottex\fP"
|
|
Use old method of texturing rotate_ brushes where the mapper aligns
|
|
textures for the object at (0 0 0).
|
|
.IP "\fB\-maxNodeSize [n]\fP"
|
|
Switch to the cheap spatial subdivion bsp heuristic when splitting nodes
|
|
of this size (in any dimension). This gives much faster qbsp processing
|
|
times on large maps and should generate better bsp trees as well.
|
|
From txqbsp-xt, thanks rebb. (default 1024, 0 to disable)
|
|
.IP "\fB\-hexen2\fP"
|
|
Generate a hexen2 bsp.
|
|
.IP "\fB\-wrbrushes\fP"
|
|
(bspx) Includes a list of brushes for brush-based collision.
|
|
.IP "\fB\-wrbrushesonly\fP"
|
|
"-wrbrushes" combined with "-noclip" argument.
|
|
.IP "\fB\-notex\fP"
|
|
Write only placeholder textures, to depend upon replacements.
|
|
.IP "\fB\-omitdetail\fP"
|
|
Detail brushes are omitted from the compile.
|
|
.IP "\fB\-convert <fmt>\fP"
|
|
Convert a .MAP to a different .MAP format. fmt can be: quake, quake2, valve, bp (brush primitives).
|
|
Conversions to "quake" or "quake2" format may not be able to match the texture alignment in the source map, other conversions are lossless.
|
|
The converted map is saved to <source map name>-<fmt>.map.
|
|
|
|
.SH "SPECIAL TEXTURE NAMES"
|
|
.PP
|
|
The contents inside a brush depend on the texture name(s) assigned to
|
|
it.
|
|
.PP
|
|
By default brush contents are solid unless they have a special name.
|
|
Names beginning with an asterisk are liquids. A prefix of
|
|
\fI*slime\fP indicates slime, \fI*lava\fP is for lava and anything
|
|
else beginning with \fI*\fP will have contents as water.
|
|
.PP
|
|
All faces of a brush must have textures which indicate the same
|
|
contents. Mixed content types will cause qbsp to print an error and
|
|
exit.
|
|
|
|
.SS "SKIP"
|
|
.PP
|
|
Any surfaces assigned a texture name of \fIskip\fP will be compiled
|
|
into the bsp as invisible surfaces. Solid surfaces will still be
|
|
solid (e.g. the play can't walk or shoot through them) but they will
|
|
not be drawn. Water, slime and lava surfaces can be made invisible
|
|
using the texture names \fI*waterskip\fP, \fI*slimeskip\fP and
|
|
\fI*lavaskip\fP respectively.
|
|
|
|
.SS "HINT"
|
|
.PP
|
|
Hint surfaces cause a bsp split and portal to be generated the on the
|
|
surface plane, after which they are removed from the final bsp - they
|
|
are neither visible, nor structural. Strategic placement of hint
|
|
surfaces can be used by a map author to optimise the PVS calculations
|
|
so as to limit overdraw by the engine (see also: \fBvis\fP(1)).
|
|
.PP
|
|
Use a texture with the name \fIhintskip\fP on any surfaces of a hint
|
|
brush which you don't want to generate bsp splits or portals. All
|
|
surfaces of a hint brush must use either the \fIhint\fP or
|
|
\fIhintskip\fP texture name.
|
|
|
|
.SH "EXTERNAL MAP PREFAB SUPPORT"
|
|
.PP
|
|
This qbsp has a prefab system using a point entity named "misc_external_map".
|
|
The idea is, each "misc_external_map" imports brushes from an external .map file,
|
|
applies rotations specified by the "_external_map_angles" key, then translates them
|
|
to the "origin" key of the "misc_external_map" entity. Finally, the classname of the
|
|
"misc_external_map" is switched to the one provided by the mapper in the "_external_map_classname"
|
|
key. (The "origin" key is also cleared to "0 0 0" before saving the .bsp).
|
|
|
|
.PP
|
|
The external .map file should consist of worldspawn brushes only, although
|
|
you can use func_group for editing convenience. Brush entities are merged
|
|
with the worldspawn brushes during import. All worldspawn keys, and any point
|
|
entities are ignored.
|
|
Currently, this means that the "wad" key is not handled, so you need to add
|
|
any texture wads required by the external .map file to your main map.
|
|
|
|
.PP
|
|
Note that you can set other entity keys on the "misc_external_map" to configure the
|
|
final entity type. e.g. if you set "_external_map_classname" to "func_door", you can
|
|
also set a "targetname" key on the "misc_external_map", or any other keys for "func_door".
|
|
|
|
.IP "\fB_external_map\fP"
|
|
Specifies the filename of the .map to import.
|
|
.IP "\fB_external_map_classname\fP"
|
|
What entity you want the external map to turn in to.
|
|
You can use internal qbsp entity types such as "func_detail",
|
|
or a regular bmodel classname like "func_wall" or "func_door".
|
|
.IP "\fB_external_map_angles\fP"
|
|
Rotation for the prefab, "pitch yaw roll" format. Negative pitch is down.
|
|
.IP "\fB_external_map_angle\fP"
|
|
Short version of "_external_map_angles" for when you want to specify just a yaw rotation.
|
|
|
|
.SH "DETAIL BRUSH SUPPORT"
|
|
.PP
|
|
This version of qbsp supports detail brushes which are similar in concept to
|
|
Quake 2's detail brushes. They don't seal the map (previous versions did).
|
|
.PP
|
|
To be compatible with existing Quake 1 mapping tools, detail brushes can be
|
|
added by creating an entity with classname "func_detail". When qbsp reads the
|
|
map file, it will add any brushes included in a func_detail entity into the
|
|
worldspawn as details and remove the func_detail entity. Any number of
|
|
func_detail entities can be used (useful for grouping) and all included
|
|
brushes will be added to the worldspawn.
|
|
.PP
|
|
Here is an example entity definition suitable to add the the .QC files used by
|
|
BSP Editor:
|
|
.PP
|
|
.nf
|
|
/*QUAKED func_detail (0.5 0.5 0.9) ?
|
|
Detail brushes add visual details to
|
|
the world, but do not block visibility.
|
|
func_detail entities are merged into
|
|
the worldspawn entity by the qbsp compiler
|
|
and do not appear as separate entities in
|
|
the compiled bsp.
|
|
*/
|
|
.fi
|
|
.PP
|
|
For WorldCraft in .FGD format (untested):
|
|
.PP
|
|
.nf
|
|
@SolidClass color(128 128 230) = func_detail: "Detail" []
|
|
.fi
|
|
.PP
|
|
For Radiant in .ENT format:
|
|
.PP
|
|
.nf
|
|
<group name="func_detail" color="0 .5 .8">
|
|
Detail brushes add visual details to the world, but do not
|
|
block visibility. func_detail entities are merged into the
|
|
worldspawn entity by the qbsp compiler and do not appear as
|
|
separate entities in the compiled bsp.
|
|
</group>
|
|
.fi
|
|
.PP
|
|
What should be written to the .map file is a simple entity with one or more
|
|
brushes. E.g.:
|
|
.PP
|
|
.nf
|
|
{
|
|
"classname" "func_detail"
|
|
{
|
|
( -176 80 0 ) ( -208 80 0 ) ( -208 48 0 ) COP1_1 0 0 0 1.0 1.0
|
|
( -192 -80 64 ) ( -208 -80 0 ) ( -192 -64 64 ) COP1_1 0 0 0 1.0 1.0
|
|
( -176 -80 0 ) ( -192 -80 64 ) ( -176 -64 0 ) COP1_1 0 0 0 1.0 1.0
|
|
( -16 48 0 ) ( -16 64 64 ) ( 0 48 0 ) COP1_1 0 0 0 1.0 1.0
|
|
( -16 64 64 ) ( -16 80 0 ) ( 0 64 64 ) COP1_1 0 0 0 1.0 1.0
|
|
}
|
|
}
|
|
.fi
|
|
.PP
|
|
When qbsp detects detail brushes, it outputs a modified portal file format
|
|
with the header PRT2 (default is PRT1). This portal file contains extra
|
|
information needed by vis to compute the potentially visible set (PVS) for the
|
|
map/bsp. So you will also need a vis util capable of processing the PRT2 file
|
|
format.
|
|
|
|
.SH "DETAIL VARIANTS"
|
|
|
|
.SS "func_detail_illusionary"
|
|
.PP
|
|
func_detail variant with no collision (players / monsters / gunfire) and doesn't split world faces. Doesn't cast shadows unless enabled with "_shadow" "1". Useful for hanging vines. Still creates BSP leafs, which is unavoidable without a new .bsp file format.
|
|
|
|
.SS "func_detail_wall"
|
|
.PP
|
|
func_detail variant that doesn't split world faces. Useful for when you want a decoration touching a floor or wall to not split the floor/wall faces (you'll get some overdraw instead.) If it completely covers up a world face, that face will get clipped away, so it's not suitable for fence textures; see func_detail_fence instead.
|
|
|
|
.SS "func_detail_fence"
|
|
Similar to func_detail_wall except it's suitable for fence textures, never clips away world faces. Useful for fences, grates, etc., that are solid and block gunfire.
|
|
|
|
.SH "MODEL ENTITY KEYS"
|
|
|
|
.IP "\fB""_lmscale"" ""n""\fP"
|
|
Generates an LMSHIFT bspx lump for use by a light util. Note that both scaled and unscaled lighting will normally be used.
|
|
|
|
.SH MAP COMPATIBILITY
|
|
In addition to standard Quake 1 .map files, TyrUtils QBSP is compatible with:
|
|
|
|
.IP \(bu
|
|
Floating point brush coordinates and texture alignments
|
|
.IP \(bu
|
|
Valve's 220 map format as produced by the \fIHammer\fP editor
|
|
.IP \(bu
|
|
Extended texture positioning as supported by the \fIQuArK\fP editor
|
|
.IP \(bu
|
|
Standard Quake 2 map format (leading paths in texture names are
|
|
stripped and any extra surface properties are ignored)
|
|
.IP \(bu
|
|
Brush Primitives produce by Radiant editors (normally a Quake 3 format)
|
|
|
|
.SH AUTHOR
|
|
Written by Kevin Shanahan (aka Tyrann)
|
|
.br
|
|
Based on source provided by id Software and Greg Lewis
|
|
.br
|
|
http://disenchant.net
|
|
|
|
.SH "REPORTING BUGS"
|
|
Please post bug reports at https://github.com/ericwa/tyrutils-ericw/issues.
|
|
.br
|
|
Improvements to the documentation are welcome and encouraged.
|
|
|
|
.SH COPYRIGHT
|
|
Copyright (C) 2013 Kevin Shanahan
|
|
.br
|
|
Copyright (C) 1997 Greg Lewis
|
|
.br
|
|
Copyright (C) 1997 id Software
|
|
.br
|
|
License GPLv2+: GNU GPL version 2 or later
|
|
.br
|
|
<http://gnu.org/licenses/gpl2.html>.
|
|
.PP
|
|
This is free software: you are free to change and redistribute it. There is
|
|
NO WARRANTY, to the extent permitted by law.
|
|
|
|
.SH "SEE ALSO"
|
|
\fBlight\fP(1)
|
|
\fBvis\fP(1)
|
|
\fBbspinfo\fP(1)
|
|
\fBbsputil\fP(1)
|
|
\fBquake\fP(6)
|