diff --git a/docs/bspinfo.rst b/docs/bspinfo.rst new file mode 100644 index 00000000..3f702c7a --- /dev/null +++ b/docs/bspinfo.rst @@ -0,0 +1,53 @@ +NAME +==== + +bspinfo - print basic information about a Quake BSP file + +SYNOPSIS +======== + +**bspinfo** BSPFILE + +DESCRIPTION +=========== + +**bspinfo** will print a very basic summary of the internal data in +*BSPFILE*. The BSP version number is printed, followed by one line for +each of the data types inside, giving the count and data size in bytes +of each data type. + +If the filename *BSPFILE* does not have a .bsp extension, **bsputil** +will look for a .bsp file by stripping the file extension from BSPFILE +(if any) and appending ".bsp". + +AUTHOR +====== + +| Kevin Shanahan (aka Tyrann) - http://disenchant.net +| Eric Wasylishen +| Based on source provided by id Software + +REPORTING BUGS +============== + +| Please post bug reports at + https://github.com/ericwa/ericw-tools/issues. +| Improvements to the documentation are welcome and encouraged. + +COPYRIGHT +========= + +| Copyright (C) 2017 Eric Wasylishen +| Copyright (C) 2013 Kevin Shanahan +| Copyright (C) 1997 id Software +| License GPLv2+: GNU GPL version 2 or later +| . + +This is free software: you are free to change and redistribute it. There +is NO WARRANTY, to the extent permitted by law. + +SEE ALSO +======== + +**qbsp**\ (1) **light**\ (1) **vis**\ (1) **bsputil**\ (1) +**quake**\ (6) diff --git a/docs/bsputil.rst b/docs/bsputil.rst new file mode 100644 index 00000000..30f63abc --- /dev/null +++ b/docs/bsputil.rst @@ -0,0 +1,67 @@ +NAME +==== + +bsputil - utiltiy for working with Quake BSP files + +SYNOPSIS +======== + +**bsputil** [OPTION]... BSPFILE + +DESCRIPTION +=========== + +**bsputil is a small utility for basic manipulation of Quake BSP +files.** + +OPTIONS +======= + +--extract-textures + Extract the texture data from *BSPFILE*\ **and create a Quake WAD** + file. The output filename is generated from *BSPFILE*\ **by** + stripping the .bsp extension and adding the .wad extension. + +--extract-entities + Extract the entity data from *BSPFILE*\ **and create a plain** text + .ent file. The output filename is generated from *BSPFILE* by + stripping the .bsp extension and adding the .ent extension. + +--check + Load *BSPFILE*\ **into memory and run a set of tests to check that** + all internal data structures are self-consistent. Currently the tests + are very basic and not all warnings will result in errors from all + versions of the Quake engine. This option is not targeted at level + designers, but is intended to assist with development of the **qbsp + tool and check that a "clean" bsp file is generated.** + +AUTHOR +====== + +| Kevin Shanahan (aka Tyrann) - http://disenchant.net +| Eric Wasylishen +| Based on source provided by id Software + +REPORTING BUGS +============== + +| Please post bug reports at + https://github.com/ericwa/ericw-tools/issues. +| Improvements to the documentation are welcome and encouraged. + +COPYRIGHT +========= + +| Copyright (C) 2017 Eric Wasylishen +| Copyright (C) 2013 Kevin Shanahan +| Copyright (C) 1997 id Software +| License GPLv2+: GNU GPL version 2 or later +| . + +This is free software: you are free to change and redistribute it. There +is NO WARRANTY, to the extent permitted by law. + +SEE ALSO +======== + +**qbsp(1)** **light(1)** **vis(1)** **bspinfo(1)** **quake(6)** diff --git a/docs/index.rst b/docs/index.rst index 297978a6..9b9c3c3e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,9 +7,12 @@ Welcome to ericw-tools's documentation! ======================================= .. toctree:: - :maxdepth: 2 - :caption: Contents: - + + qbsp + vis + light + bspinfo + bsputil Indices and tables diff --git a/docs/light.rst b/docs/light.rst new file mode 100644 index 00000000..2274f760 --- /dev/null +++ b/docs/light.rst @@ -0,0 +1,613 @@ +NAME +==== + +light - Caclulate lightmap data for a Quake BSP file + +SYNOPSIS +======== + +**light** [OPTION]... BSPFILE + +DESCRIPTION +=========== + +**light** reads a Quake .bsp file and calculates light and shadow +information based on the entity definitions contained in the .bsp. The +.bsp file is updated with the new light data upon completion, +overwriting any existing lighting data. + +OPTIONS +======= + +| Note, any of the Worldspawn Keys listed in the next section can be + supplied as command-line options, which will override any setting in + worldspawn. + +Performance options: +-------------------- + +-threads n + Set number of threads explicitly. By default light will attempt to + detect the number of CPUs/cores available. + +-extra + Calculate extra samples (2x2) and average the results for smoother + shadows. + +-extra4 + Calculate even more samples (4x4) and average the results for + smoother shadows. + +-gate n + Set a minimum light level, below which can be considered zero + brightness. This can dramatically speed up processing when there are + large numbers of lights with inverse or inverse square falloff. In + most cases, values less than 1.0 will cause no discernible visual + differences. Default 0.001. + +-sunsamples [n] + Set the number of samples to use for "_sunlight_penumbra" and + "_sunlight2" (sunlight2 may use more or less because of how the suns + are set up in a sphere). Default 100. + +-surflight_subdivide [n] + | Configure spacing of all surface lights. Default 128 units. Minimum + setting: 64 / max 2048. In the future I'd like to make this + configurable per-surface-light. + +Output format options: +---------------------- + +-lit + Force generation of a .lit file, even if your map does not have any + coloured lights. By default, light will automatically generate the + .lit file when needed. + +-onlyents + Updates the entities lump in the bsp. You should run this after + running qbsp with -onlyents, if your map uses any switchable lights. + All this does is assign style numbers to each switchable light. + +-litonly + Generate a .lit file that is compatible with the .bsp without + modifying the .bsp. This is meant for tweaking lighting or adding + colored lights when you can't modify an existing .bsp (e.g. for + multiplayer maps.) Typically you would make a temporary copy of the + .bsp, update the lights in the entity lump (e.g. with "qbsp + -onlyents"), then re-light it with "light -litonly". Engines may + enforce a restriction that you can't make areas brighter than they + originally were (cheat protection). Also, styled lights + (flickering/switchable) can't be added in new areas or have their + styles changed. + +-nolighting + Do all of the stuff required for lighting to work without actually + performing any lighting calculations. This is mainly for engines that + don't use the light data, but still need switchable lights, etc. + +| + +Postprocessing options: +----------------------- + +-soft [n] + | Perform post-processing on the lightmap which averages adjacent + samples to smooth shadow edges. If n is specified, the algorithm + will take 'n' samples on each side of the sample point and replace + the original value with the average. e.g. a value of 1 results in + averaging a 3x3 square centred on the original sample. 2 implies a + 5x5 square and so on. If -soft is specified, but n is omitted, a + value will be the level of oversampling requested. If no + oversampling, then the implied value is 1. -extra implies a value + of 2 and -extra4 implies 3. Default 0 (off). + +Debug modes: +------------ + +-dirtdebug + Implies "-dirt", and renders just the dirtmap against a fullbright + background, ignoring all lights in the map. Useful for previewing and + turning the dirt settings. + +-phongdebug + Write normals to lit file for debugging phong shading. + +-bouncedebug + Write bounced lighting only to the lightmap for debugging / + previewing -bounce. + +-surflight_dump + Saves the lights generated by surfacelights to a + "mapname-surflights.map" file. + +-novisapprox + | Disable approximate visibility culling of lights, which has a small + chance of introducing artifacts where lights cut off too soon. + +Experimental options: +--------------------- + +-addmin + Changes the behaviour of *minlight*. Instead of increasing low light + levels to the global minimum, add the global minimum light level to + all style 0 lightmaps. This may help reducing the sometimes uniform + minlight effect. + +-lit2 + Force generation of a .lit2 file, even if your map does not have any + coloured lights. + +-lux + Generate a .lux file storing average incoming light directions for + surfaces. Usable by FTEQW with "r_deluxemapping 1" + +-lmscale n + Equivalent to "_lightmap_scale" worldspawn key. + +-bspxlit + Writes rgb data into the bsp itself. + +-bspx + Writes both rgb and directions data into the bsp itself. + +"-novanilla + Fallback scaled lighting will be omitted. Standard grey lighting will + be omitted if there are coloured lights. Implies "-bspxlit". "-lit" + will no longer be implied by the presence of coloured lights. + +"-wrnormals + Writes normal data into the bsp itself. + +MODEL ENTITY KEYS +================= + +Worldspawn Keys +--------------- + +The following keys can be added to the *worldspawn* entity: + +"light" "n" \| "_minlight" "n" + Set a global minimum light level of "n" across the whole map. This is + an easy way to eliminate completely dark areas of the level, however + you may lose some contrast as a result, so use with care. Default 0. + +"_minlight_color" "r g b" \| "_mincolor" "r g b" + Specify red(r), green(g) and blue(b) components for the colour of the + minlight. RGB component values are between 0 and 255 (between 0 and 1 + is also accepted). Default is white light ("255 255 255"). + +"_dist" "n" + Scales the fade distance of all lights by a factor of n. If n > 1 + lights fade more quickly with distance and if n < 1, lights fade more + slowly with distance and light reaches further. + +"_range" "n" + Scales the brightness range of all lights without affecting their + fade discance. Values of n > 0.5 makes lights brighter and n < 0.5 + makes lights less bright. The same effect can be achieved on + individual lights by adjusting both the "light" and "wait" + attributes. + +"_sunlight" "n" + Set the brightness of the sunlight coming from an unseen sun in the + sky. Sky brushes (or more accurately bsp leafs with sky contents) + will emit sunlight at an angle specified by the "_sun_mangle" key. + Default 0. + +"_anglescale" "n" \| "_anglesense" "n" + Set the scaling of sunlight brightness due to the angle of incidence + with a surface (more detailed explanation in the "_anglescale" light + entity key below). + +"_sunlight_mangle" "yaw pitch roll" \| "_sun_mangle" "yaw pitch roll" + Specifies the direction of sunlight using yaw, pitch and roll in + degrees. Yaw specifies the angle around the Z-axis from 0 to 359 + degrees and pitch specifies the angle from 90 (shining straight up) + to -90 (shining straight down from above). Roll has no effect, so use + any value (e.g. 0). Default is straight down ("0 -90 0"). + +"_sunlight_penumbra" "n" + Specifies the penumbra width, in degrees, of sunlight. Useful values + are 3-4 for a gentle soft edge, or 10-20+ for more diffuse sunlight. + Default is 0. + +"_sunlight_color" "r g b" + Specify red(r), green(g) and blue(b) components for the colour of the + sunlight. RGB component values are between 0 and 255 (between 0 and 1 + is also accepted). Default is white light ("255 255 255"). + +"_sunlight2" "n" + Set the brightness of a dome of lights arranged around the upper + hemisphere. (i.e. ambient light, coming from above the horizon). + Default 0. + +"_sunlight_color2" "r g b" \| "_sunlight2_color" "r g b" + Specifies the colour of \_sunlight2, same format as + "_sunlight_color". Default is white light ("255 255 255"). + +"_sunlight3" "n" + Same as "_sunlight2", but for the bottom hemisphere (i.e. ambient + light, coming from below the horizon). Combine "_sunlight2" and + "_sunlight3" to have light coming equally from all directions, e.g. + for levels floating in the clouds. Default 0. + +"_sunlight_color3" "r g b" \| "_sunlight3_color" "r g b" + Specifies the colour of "_sunlight3". Default is white light ("255 + 255 255"). + +"_dirt" "n" + 1 enables dirtmapping (ambient occlusion) on all lights, borrowed + from q3map2. This adds shadows to corners and crevices. You can + override the global setting for specific lights with the "_dirt" + light entity key or "_sunlight_dirt", "_sunlight2_dirt", and + "_minlight_dirt" worldspawn keys. Default is no dirtmapping (-1). + +"_sunlight_dirt" "n" + 1 enables dirtmapping (ambient occlusion) on sunlight, -1 to disable + (making it illuminate the dirtmapping shadows). Default is to use the + value of "_dirt". + +"_sunlight2_dirt" "n" + 1 enables dirtmapping (ambient occlusion) on sunlight2/3, -1 to + disable. Default is to use the value of "_dirt". + +"_minlight_dirt" "n" + 1 enables dirtmapping (ambient occlusion) on minlight, -1 to disable. + Default is to use the value of "_dirt". + +"_dirtmode" "n" + Choose between ordered (0, default) and randomized (1) dirtmapping. + +"_dirtdepth" "n" + Maximum depth of occlusion checking for dirtmapping, default 128. + +"_dirtscale" "n" + Scale factor used in dirt calculations, default 1. Lower values (e.g. + 0.5) make the dirt fainter, 2.0 would create much darker shadows. + +"_dirtgain" "n" + Exponent used in dirt calculation, default 1. Lower values (e.g. 0.5) + make the shadows darker and stretch further away from corners. + +"_dirtangle" "n" + Cone angle in degrees for occlusion testing, default 88. Allowed + range 1-90. Lower values can avoid unwanted dirt on arches, pipe + interiors, etc. + +"_gamma" "n" + Adjust brightness of final lightmap. Default 1, >1 is brighter, <1 is + darker. + +"_lightmap_scale" "n" + Forces all surfaces+submodels to use this specific lightmap scale. + Removes "LMSHIFT" field. + +"_bounce" "n" + 1 enables bounce lighting, disabled by default. + +"_bouncescale" "n" + Scales brightness of bounce lighting, default 1. + +"_bouncecolorscale" "n" + Weight for bounce lighting to use texture colors from the map: + 0=ignore map textures (default), 1=multiply bounce light color by + texture color. + +"_bouncestyled" "n" + 1 makes styled lights bounce (e.g. flickering or switchable lights), + default is 0, they do not bounce. + +"_spotlightautofalloff" "n" + When set to 1, spotlight falloff is calculated from the distance to + the targeted info_null. Ignored when "_falloff" is not 0. Default 0. + +Model Entity Keys +----------------- + +The following keys can be used on any entity with a brush model. +"_minlight", "_mincolor", "_dirt", "_phong", "_phong_angle", +"_phong_angle_concave", "_shadow", "_bounce" are supported on +func_detail/func_group as well, if qbsp from these tools is used. + +"_minlight" "n" + Set the minimum light level for any surface of the brush model. + Default 0. + +"_minlight_exclude" "texname" + Faces with the given texture are excluded from receiving minlight on + this brush model. + +"_minlight_color" "r g b" \| "_mincolor" "r g b" + Specify red(r), green(g) and blue(b) components for the colour of the + minlight. RGB component values are between 0 and 255 (between 0 and 1 + is also accepted). Default is white light ("255 255 255"). + +"_shadow" "n" + If n is 1, this model will cast shadows on other models and itself + (i.e. "_shadow" implies "_shadowself"). Note that this doesn't + magically give Quake dynamic lighting powers, so the shadows will not + move if the model moves. Set to -1 on func_detail/func_group to + prevent them from casting shadows. Default 0. + +"_shadowself" "n" \| "_selfshadow" "n" + If n is 1, this model will cast shadows on itself if one part of the + model blocks the light from another model surface. This can be a + better compromise for moving models than full shadowing. Default 0. + +"_shadowworldonly" "n" + If n is 1, this model will cast shadows on the world only (not other + bmodels). + +"_switchableshadow" "n" + If n is 1, this model casts a shadow that can be switched on/off + using QuakeC. To make this work, a lightstyle is automatically + assigned and stored in a key called "switchshadstyle", which the + QuakeC will need to read and call the "lightstyle()" builtin with "a" + or "m" to switch the shadow on or off. Entities sharing the same + targetname, and with "_switchableshadow" set to 1, will share the + same lightstyle. + +These models are only able to block style 0 light (i.e., non-flickering +or switchable lights). Flickering or switchable lights will shine +through the switchable shadow casters, regardless of whether the shadow +is off or on. + +"_dirt" "n" + For brush models, -1 prevents dirtmapping on the brush model. Useful + if the bmodel touches or sticks into the world, and you want to + prevent those areas from turning black. Default 0. + +"_phong" "n" + 1 enables phong shading on this model with a default \_phong_angle of + 89 (softens columns etc). + +"_phong_angle" "n" + Enables phong shading on faces of this model with a custom angle. + Adjacent faces with normals this many degrees apart (or less) will be + smoothed. Consider setting "_anglescale" to "1" on lights or + worldspawn to make the effect of phong shading more visible. Use the + "-phongdebug" command-line flag to save the interpolated normals to + the lightmap for previewing (use "r_lightmap 1" or "gl_lightmaps 1" + in your engine to preview.) + +"_phong_angle_concave" "n" + Optional key for setting a different angle threshold for concave + joints. A pair of faces will either use "_phong_angle" or + "_phong_angle_concave" as the smoothing threshold, depending on + whether the joint between the faces is concave or not. + "_phong_angle(_concave)" is the maximum angle (in degrees) between + the face normals that will still cause the pair of faces to be + smoothed. The minimum setting for "_phong_angle_concave" is 1, this + should make all concave joints non-smoothed (unless they're less than + 1 degree apart, almost a flat plane.) If it's 0 or unset, the same + value as "_phong_angle" is used. + +"_lightignore" "n" + 1 makes a model receive minlight only, ignoring all lights / + sunlight. Could be useful on rotators / trains. + +"_bounce" "n" + Set to -1 to prevent this model from bouncing light (i.e. prevents + its brushes from emitting bounced light they receive from elsewhere.) + Only has an effect if "_bounce" is enabled in worldspawn. + +LIGHT ENTITY KEYS +================= + +Light entity keys can be used in any entity with a classname starting +with the first five letters "light". E.g. "light", "light_globe", +"light_flame_small_yellow", etc. + +"light" "n" + Set the light intensity. Negative values are also allowed and will + cause the entity to subtract light cast by other entities. Default + 300. + +"wait" "n" + Scale the fade distance of the light by "n". Values of n > 1 make the + light fade more quickly with distance, and values < 1 make the light + fade more slowly (and thus reach further). Default 1. + +"delay" "n" + Select an attenuation formaula for the light: + +:: + + 0 => Linear attenuation (default) + 1 => 1/x attenuation + 2 => 1/(x^2) attenuation + 3 => No attenuation (same brightness at any distance) + 4 => "local minlight" - No attenuation and like minlight, + it won't raise the lighting above it's light value. + Unlike minlight, it will only affect surfaces within + line of sight of the entity. + 5 => 1/(x^2) attenuation, but slightly more attenuated and + without the extra bright effect that "delay 2" has + near the source. + +"_falloff" "n" + Sets the distance at which the light drops to 0, in map units. + +In this mode, "wait" is ignored and "light" only controls the brightness +at the center of the light, and no longer affects the falloff distance. + +Only supported on linear attenuation (delay 0) lights currently. + +"_color" "r g b" + Specify red(r), green(g) and blue(b) components for the colour of the + light. RGB component values are between 0 and 255 (between 0 and 1 is + also accepted). Default is white light ("255 255 255"). + +"target" "name" + Turns the light into a spotlight, with the direction of light being + towards another entity with it's "targetname" key set to "name". + +"mangle" "yaw pitch roll" + Turns the light into a spotlight and specifies the direction of light + using yaw, pitch and roll in degrees. Yaw specifies the angle around + the Z-axis from 0 to 359 degrees and pitch specifies the angle from + 90 (straight up) to -90 (straight down). Roll has no effect, so use + any value (e.g. 0). Often easier than the "target" method. + +"angle" "n" + Specifies the angle in degrees for a spotlight cone. Default 40. + +"_softangle" "n" + Specifies the angle in degrees for an inner spotlight cone (must be + less than the "angle" cone. Creates a softer transition between the + full brightness of the inner cone to the edge of the outer cone. + Default 0 (disabled). + +"targetname" "name" + Turns the light into a switchable light, toggled by another entity + targeting it's name. + +"style" "n" + Set the animated light style. Default 0. + +"_anglescale" "n" \| "_anglesense" "n" + Sets a scaling factor for how much influence the angle of incidence + of light on a surface has on the brightness of the surface. *n* must + be between 0.0 and 1.0. Smaller values mean less attenuation, with + zero meaning that angle of incidence has no effect at all on the + brightness. Default 0.5. + +"_dirtscale" "n" \| "_dirtgain" "n" + Override the global "_dirtscale" or "_dirtgain" settings to change + how this light is affected by dirtmapping (ambient occlusion). See + descriptions of these keys in the worldspawn section. + +"_dirt" "n" + Overrides the worldspawn setting of "_dirt" for this particular + light. -1 to disable dirtmapping (ambient occlusion) for this light, + making it illuminate the dirtmapping shadows. 1 to enable ambient + occlusion for this light. Default is to defer to the worldspawn + setting. + +"_deviance" "n" + Split up the light into a sphere of randomly positioned lights within + radius "n" (in world units). Useful to give shadows a wider penumbra. + "_samples" specifies the number of lights in the sphere. The "light" + value is automatically scaled down for most lighting formulas (except + linear and non-additive minlight) to attempt to keep the brightness + equal. Default is 0, do not split up lights. + +"_samples" "n" + Number of lights to use for "_deviance". Default 16 (only used if + "_deviance" is set). + +"_surface" "texturename" + Makes surfaces with the given texture name emit light, by using this + light as a template which is copied across those surfaces. Lights are + spaced about 128 units (though possibly closer due to bsp splitting) + apart and positioned 2 units above the surfaces. + +"_surface_offset" "n" + Controls the offset lights are placed above surfaces for "_surface". + Default 2. + +"_surface_spotlight" "n" + For a surface light template (i.e. a light with "_surface" set), + setting this to "1" makes each instance into a spotlight, with the + direction of light pointing along the surface normal. In other words, + it automatically sets "mangle" on each of the generated lights. + +"_project_texture" "texture" + Specifies that a light should project this texture. The texture must + be used in the map somewhere. + +"_project_mangle" "yaw pitch roll" + Specifies the yaw/pitch/roll angles for a texture projection + (overriding mangle). + +"_project_fov" "n" + Specifies the fov angle for a texture projection. Default 90. + +"_bouncescale" "n" + Scales the amount of light that is contributed by bounces. Default is + 1.0, 0.0 disables bounce lighting for this light. + +"_sun" "n" + Set to 1 to make this entity a sun, as an alternative to using the + sunlight worldspawn keys. If the light targets an info_null entity, + the direction towards that entity sets sun direction. The light + itself is disabled, so it can be placed anywhere in the map. + +The following light properties correspond to these sunlight settings: + +:: + + light => _sunlight + mangle => _sunlight_mangle + deviance => _sunlight_penumbra + _color => _sunlight_color + _dirt => _sunlight_dirt + _anglescale => _anglescale + style => flicker style for styled sunlight + targetname => targetname for switchable sunlight + _suntexture => this sunlight is only emitted from faces with this texture name + +"_sunlight2" "n" + Set to 1 to make this entity control the upper dome lighting emitted + from sky faces, as an alternative to the worldspawn key "_sunlight2". + The light entity itself is disabled, so it can be placed anywhere in + the map. + +The following light properties correspond to these sunlight settings: + +:: + + light => _sunlight2 + _color => _sunlight2_color + _dirt => _sunlight2_dirt + _anglescale => _anglescale + style => flicker style for styled dome light + targetname => targetname for switchable sunlight + _suntexture => this sunlight is only emitted from faces with this texture name + +"_sunlight3" "n" + Same as "_sunlight2", but for the lower hemisphere. + +"_nostaticlight" "n" + Set to 1 to make the light compiler ignore this entity (prevents it + from casting any light). e.g. could be useful with rtlights. + +OTHER INFORMATION +================= + +The "\b" escape sequence toggles red text on/off, you can use this in +any strings in the map file. e.g. "message" "Here is \\bsome red +text\b..." + +AUTHOR +====== + +| Eric Wasylishen +| Kevin Shanahan (aka Tyrann) - http://disenchant.net +| David Walton (aka spike) +| Based on source provided by id Software + +REPORTING BUGS +============== + +| Please post bug reports at + https://github.com/ericwa/ericw-tools/issues. +| Improvements to the documentation are welcome and encouraged. + +COPYRIGHT +========= + +| Copyright (C) 2017 Eric Wasylishen +| Copyright (C) 2013 Kevin Shanahan +| Copyright (C) 1997 id Software +| License GPLv2+: GNU GPL version 2 or later +| . + +This is free software: you are free to change and redistribute it. There +is NO WARRANTY, to the extent permitted by law. + +SEE ALSO +======== + +**qbsp**\ (1) **vis**\ (1) **bspinfo**\ (1) **bsputil**\ (1) +**quake**\ (6) diff --git a/docs/qbsp.rst b/docs/qbsp.rst new file mode 100644 index 00000000..a548cc50 --- /dev/null +++ b/docs/qbsp.rst @@ -0,0 +1,448 @@ +NAME +==== + +qbsp - Compile a Quake BSP file from a MAP source file + +SYNOPSIS +======== + +**qbsp** [OPTION]... SOURCFILE [DESTFILE] + +DESCRIPTION +=========== + +**qbsp** is a tool used in the creation of maps for the **id Software** +game **Quake**. qbsp takes a .map file as input and produces a .bsp file +playable in the Quake engine. If the *DESTFILE* argument is not +supplied, the output filename will be chosen by stripping the file +extension (if any) from *SOURCEFILE* and appending the .bsp extension. + +OPTIONS +======= + +-nofill + Doesn't perform outside filling + +-noclip + Doesn't build clip hulls + +-noskip + Doesn't remove faces using the 'skip' texture + +-onlyents + Only updates .map entities + +-verbose + Print out more .map information + +-noverbose + Print out almost no information at all + +-splitspecial + Doesn't combine sky and water faces into one large face. This allows + for statically lit water. + +-transwater + Computes portal information for transparent water (default) + +-notranswater + Computes portal information for opaque water + +-transsky + Computes portal information for transparent sky + +-nooldaxis + 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. + +-forcegoodtree (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. + +-bspleak + Creates a .por file, used in the BSP editor + +-oldleak + Create an old-style QBSP .PTS file (default is new) + +-leaktest + Makes it a compile error if a leak is detected. + +-nopercent + Prevents output of percent completion information + +-hexen2 + Generate a hexen2 bsp. This can be used in addition to -bsp2 to avoid + clipnode issues. + +-bsp2 + Create the output BSP file in BSP2 format. Allows the creation of + much larger and more complex maps than the original BSP 29 format). + +-2psb + 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). + +-hlbsp + Create the output BSP file in Half-Life's format. Note that the hull + size differences prevent this from being generally usable for the + vanilla quake gamecode. This cannot be used in combination with the + -bsp2 argument. + +-leakdist [n] + Space between leakfile points (default 2) + +-subdivide [n] + Use different texture subdivision (default 240). Lower values will + harm framerates. Higher values may not be supported. DP+FTEQW+QSS + support up to 4080 (unless lightmap scaling is in use), but such + values will cause other engines to crash-to-console. Use zero to + specify no subdivision. + +-wadpath + Search this directory for wad files (default is cwd). Multiple + -wadpath args may be used. This argument is ignored for wads + specified using an absolute path. + +-xwadpath + Like -wadpath, except textures found using the specified path will + NOT be embedded into the bsp (equivelent to -notex, but for only + textures from specific wads). You should use this for wads like + halflife's standard wad files, but q1bsps require an engine extension + and players are not nearly as likely to have the same wad version. + +-oldrottex + Use old method of texturing rotate\_ brushes where the mapper aligns + textures for the object at (0 0 0). + +-maxNodeSize [n] + 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) + +-wrbrushes + (bspx) Includes a list of brushes for brush-based collision. This + allows for arbitrary collision sizes in engines that support it, + currently only FTEQW. + +-wrbrushesonly + "-wrbrushes" combined with "-noclip" argument. This is NOT backwards + compatible. + +-notex + Write only placeholder textures, to depend upon replacements. This + avoids inclusion of third-party copyrighted images inside your maps, + but is not backwards compatible but will work in FTEQW and QSS. + +-notjunc + Don't attempt to fix T-junctions. This is only for engines or formats + that prefer micro-cracks over degenerate triangles. If you don't know + what that means, don't set this. + +-omitdetail + Detail brushes are omitted from the compile. + +-convert + 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 + -.map. + +-includeskip + Emit skip/nodraw faces. Mainly for Q2RTX. + +SPECIAL TEXTURE NAMES +===================== + +The contents inside a brush depend on the texture name(s) assigned to +it. + +By default brush contents are solid unless they have a special name. +Names beginning with an asterisk are liquids. A prefix of *\*slime* +indicates slime, *\*lava* is for lava and anything else beginning with +*\** will have contents as water. + +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. + +SKIP +---- + +Any surfaces assigned a texture name of *skip* 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 *\*waterskip*, *\*slimeskip* and *\*lavaskip* respectively. + +HINT +---- + +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: **vis**\ (1)). + +Use a texture with the name *hintskip* 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 *hint* or *hintskip* texture name. + +ORIGIN +------ + +An origin brush (all faces textured with "origin") can be added to a +brush entity (but not detail or compiler-internal entities like +func_group). Doing so causes all of the brushes in the brush entitiy to +be translated so the center of the origin brush lines up with 0 0 0. The +entity key "origin" is then automatically set on the brush entity to the +original cooridnates of the center of the "origin" brush before it was +translated to 0 0 0. + +In Hexen 2, origin brushes are the native way of marking the center +point of the rotation axis for rotating entities. + +In Quake, origin brushes can be used to make some map hacks easier to +set up that would otherwise require placing brushes at the world origin +and entering an "origin" value by hand. + +Note that, unlike the Hipnotic rotation support in QBSP, using origin +brushes does not cause the model bounds to be expanded. (With Hipnotic +rotation this was to ensure that the model is not vis culled, regardless +of its rotated angle.) Origin brushes are useful for more than just +rotation, and doing this bounds expansion would break some use cases, so +if you're going to rotate a model with an origin brush you might need to +expand the bounds of it a bit using clip brushes so it doesn't get vis +culled. + +EXTERNAL MAP PREFAB SUPPORT +=========================== + +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). + +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. + +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". + +\_external_map + Specifies the filename of the .map to import. + +\_external_map_classname + 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". + +\_external_map_angles + Rotation for the prefab, "pitch yaw roll" format. Assuming the + exernal map is facing the +X axis, positive pitch is down. Yaw of + 180, for example, would rotate it to face -X. + +\_external_map_angle + Short version of "_external_map_angles" for when you want to specify + just a yaw rotation. + +\_external_map_scale + Scale factor for the prefab, defaults to 1. Either specify a single + value or three scales, "x y z". + +DETAIL BRUSH SUPPORT +==================== + +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). + +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. + +Here is an example entity definition suitable to add the the .QC files +used by BSP Editor: + +:: + + /*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. + */ + +For WorldCraft in .FGD format (untested): + +:: + + @SolidClass color(128 128 230) = func_detail: "Detail" [] + +For Radiant in .ENT format: + +:: + + + 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. + + +What should be written to the .map file is a simple entity with one or +more brushes. E.g.: + +:: + + { + "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 + } + } + +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. + +DETAIL VARIANTS +=============== + +func_detail_illusionary +----------------------- + +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. + +Intersecting func_detail_illusionary brushes don't clip each other; this +is intended to make trees/shrubs/foliage easier with "_mirrorinside" +"1". + +func_detail_wall +---------------- + +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. + +Intersecting func_detail_wall brushes don't clip each other. + +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. + +Intersecting func_detail_fence brushes don't clip each other. + +MODEL ENTITY KEYS +================= + +"_lmscale" "n" + Generates an LMSHIFT bspx lump for use by a light util. Note that + both scaled and unscaled lighting will normally be used. + +"_mirrorinside" "n" + Set to 1 to save mirrored inside faces for bmodels, so when the + player view is inside the bmodel, they will still see the faces. + (e.g. for func_water, or func_illusionary) + +OTHER SPECIAL-PURPOSE ENTITIES +============================== + +func_illusionary_visblocker +--------------------------- + +For creating vis-blocking illusionary brushes (similar to +"func_detail_illusionary" or "func_illusionary". The player can walk +through them.) This gives the same effect as water brushes when the +"-notranswater" flag is used, except the interior of these brushes are +saved as CONTENTS_EMPTY. One thing to be aware of is, if the player's +view is very close to the faces of these brushes, they might be able to +see into the void (depending on the engine). Fitzquake family engines +have a workaround for this that is enabled if the brushes are textured +with a water texture ("*" prefix). + +MAP COMPATIBILITY +================= + +In addition to standard Quake 1 .map files, ericw-tools QBSP is +compatible with: + +- Floating point brush coordinates and texture alignments + +- Valve's 220 map format as produced by the *Hammer* editor + +- Extended texture positioning as supported by the *QuArK* editor + +- Standard Quake 2 map format (leading paths in texture names are + stripped and any extra surface properties are ignored) + +- Brush Primitives produce by Radiant editors (normally a Quake 3 + format) + +AUTHOR +====== + +| Eric Wasylishen +| Kevin Shanahan (aka Tyrann) - http://disenchant.net +| Based on source provided by id Software and Greg Lewis + +REPORTING BUGS +============== + +| Please post bug reports at + https://github.com/ericwa/ericw-tools/issues. +| Improvements to the documentation are welcome and encouraged. + +COPYRIGHT +========= + +| Copyright (C) 2017 Eric Wasylishen +| Copyright (C) 2013 Kevin Shanahan +| Copyright (C) 1997 Greg Lewis +| Copyright (C) 1997 id Software +| License GPLv2+: GNU GPL version 2 or later +| . + +This is free software: you are free to change and redistribute it. There +is NO WARRANTY, to the extent permitted by law. + +SEE ALSO +======== + +**light**\ (1) **vis**\ (1) **bspinfo**\ (1) **bsputil**\ (1) +**quake**\ (6) diff --git a/docs/vis.rst b/docs/vis.rst new file mode 100644 index 00000000..69b718d8 --- /dev/null +++ b/docs/vis.rst @@ -0,0 +1,103 @@ +NAME +==== + +vis - Compute visibility (PVS) for a Quake BSP file + +SYNOPSIS +======== + +**vis** [OPTION]... BSPFILE + +DESCRIPTION +=========== + +**vis** is a tool used in the creation of maps for the game Quake. vis +looks for a .prt file by stripping the file extension from BSPFILE (if +any) and appending ".prt". vis then calculates the potentially visible +set (PVS) information before updating the .bsp file, overwriting any +existing PVS data. + +This vis tool supports the PRT2 format for Quake maps with detail +brushes. See the qbsp documentation for details. + +Compiling a map (without the -fast parameter) can take a long time, even +days or weeks in extreme cases. Vis will attempt to write a state file +every five minutes so that progress will not be lost in case the +computer needs to be rebooted or an unexpected power outage occurs. + +OPTIONS +======= + +-threads n + Set number of threads explicitly. By default vis will attempt to + detect the number of CPUs/cores available. + +-fast + Skip detailed calculations and calculate a very loose set of PVS + data. Sometimes useful for a quick test while developing a map. + +-level n + Select a test level from 0 to 4 for detailed visibility calculations. + Lower levels are not necessarily faster in in all cases. It is not + recommended that you change the default level unless you are + experiencing problems. Default 4. + +-v + Verbose output. + +-vv + Very verbose output. + +-noambientsky + Disable ambient sound generation for textures with names beginning + with 'SKY'. + +-noambientwater + Disable ambient sound generation for textures with names beginning + with '*WATER' or '*04WATER'. + +-noambientslime + Disable ambient sound generation for textures with names beginning + with '*SLIME'. + +-noambientlava + Disable ambient sound generation for textures with names beginning + with '*LAVA'. + +-noambient + Disable all ambient sound generation. + +-visdist n + Allow culling of areas further than n units. + +AUTHOR +====== + +| Kevin Shanahan (aka Tyrann) - http://disenchant.net +| Eric Wasylishen +| Based on source provided by id Software + +REPORTING BUGS +============== + +| Please post bug reports at + https://github.com/ericwa/tyrutils-ericw/issues. +| Improvements to the documentation are welcome and encouraged. + +COPYRIGHT +========= + +| Copyright (C) 2017 Eric Wasylishen +| Copyright (C) 2013 Kevin Shanahan +| Copyright (C) 1997 id Software +| License GPLv2+: GNU GPL version 2 or later +| . + +This is free software: you are free to change and redistribute it. There +is NO WARRANTY, to the extent permitted by law. + +SEE ALSO +======== + +**qbsp**\ (1) **light**\ (1) **bspinfo**\ (1) **bsputil**\ (1) +**quake**\ (6)