======= vmt-vis =======
vmt-vis [OPTION]... BSPFILE:program:`vmt-vis` is the visibility compiler for VibeyMapTools. It calculates the Potentially Visible Set (PVS) for a BSP file, which determines what parts of the map can potentially be seen from any given location.
vmt-vis looks for a .prt file by stripping the file extension from BSPFILE
(if any) and appending ".prt". It then calculates 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 :doc:`qbsp` documentation for details.
Portal input is validated before VIS allocation: counts are bounded, portal endpoints and finite windings are checked, and PRT2/PRT1-AM cluster mappings must assign every real leaf exactly once. Empty clusters remain accepted because the interchange formats and VMT's own writer can represent them. A malformed or mismatched file fails with a specific diagnostic instead of producing partial visibility data. 🛡️
Note
Coming from ericw-tools? vmt-vis keeps the same PRT/PVS workflow under
the VMT-prefixed executable name. 🧭
Note
Compiling a map (without the -fast parameter) can take a long time, even
days or weeks in extreme cases. vmt-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.
.. program:: vmt-vis
.. option:: -log Write log files. Enabled by default.
.. option:: -nolog Don't write log files.
.. option:: -verbose, -v Verbose output.
.. option:: -nopercent Don't output percentage messages.
.. option:: -nostat Don't output statistic messages.
.. option:: -noprogress Don't output progress messages.
.. option:: -nocolor Don't output color codes (for TB, etc).
.. option:: -werror Finish any in-progress visibility work safely, then return an error if warnings were emitted. This is useful for strict CI builds.
.. option:: -quiet, -noverbose Suppress non-important messages (equivalent to :option:`-nopercent` :option:`-nostat` :option:`-noprogress`).
.. option:: -lowpriority [0] Run in a lower priority, to free up headroom for other processes.
.. option:: -threads n Set number of threads explicitly. By default vmt-vis will attempt to detect the number of CPUs/cores available.
.. option:: -fast Skip detailed calculations and calculate a very loose set of PVS data. Sometimes useful for a quick test while developing a map.
.. option:: -targetchecks n Set the target ratio of speculative target checks to regular portal-flow checks. ``0`` disables them and ``1`` requests roughly equal amounts. The default is ``0.5``; change it only when benchmarking a representative map.
.. option:: -gamedir "relative/path" or "C:/absolute/path" Override the default mod base directory. If this is not set, or if it is relative, it will be derived from the input file or the basedir if specified.
.. option:: -basedir "relative/path" or "C:/absolute/path" Override the default game base directory. If this is not set, or if it is relative, it will be derived from the input file or the gamedir if specified.
.. option:: -filepriority archive | loose Which types of archives (folders/loose files or packed archives) are higher priority and chosen first for path searching.
.. option:: -path "/path/to/folder" <multiple allowed> Additional paths or archives to add to the search path, mostly for loose files.
.. option:: -q2rtx Adjust settings to best support Q2RTX.
.. option:: -defaultpaths Whether the compiler should attempt to automatically derive game/base paths for games that support it. Enabled by default.
.. option:: -nodefaultpaths Opt out of :option:`-defaultpaths`.
.. option:: -noambientsky Disable ambient sound generation for textures with names beginning with 'SKY'.
.. option:: -noambientwater Disable ambient sound generation for textures with names beginning with ``*WATER`` or ``*04WATER``.
.. option:: -noambientslime Disable ambient sound generation for textures with names beginning with ``*SLIME``.
.. option:: -noambientlava Disable ambient sound generation for textures with names beginning with ``*LAVA``.
.. option:: -noambient
Disable all ambient sound generation.
.. seealso::
:bmodel-key:`_noambient` for selectively disabling ambient sounds.
.. option:: -noautoclean Keep the resumable ``.vis`` state file after a successful compile. The portal ``.prt`` file is always preserved; this option controls only resume state.
.. option:: -level n Select a test level from 0 to 4 for detailed visibility calculations. Lower levels are not necessarily faster in all cases. It is not recommended that you change the default level unless you are experiencing problems. Default 4.
.. option:: -visdist n Allow culling of areas further than n units.
.. option:: -nostate Ignore saved state files, for forced re-runs. Resume files are accepted only when their portal topology, real-leaf mapping, :option:`-level`, and exact :option:`-visdist` value match the current run. Older state formats are safely ignored and rebuilt. Successful detailed VIS also reports minimum, maximum, standard deviation, and mean visible-leaf percentage, making unusually broad PVS rows easier to spot.
.. option:: -phsonly Re-calculate the PHS of a Quake II BSP without touching the PVS.
.. bmodel-key:: "_noambient" "1" Disables ambient sound emission from these specific brushes.
- :doc:`qbsp` — BSP compiler
- :doc:`light` — Lighting compiler
Please post bug reports at https://github.com/themuffinator/VibeyMapTools/issues.
Improvements to the documentation are welcome and encouraged.
License GPLv3: GNU GPL version 3 or later https://gnu.org/licenses/gpl-3.0.html
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.