bspguy

https://github.com/wootguy/bspguy
Admin
bspguy is a command-line utility and 3D editor designed for editing, merging, and porting GoldSrc...
Tokens:7,267
Snippets:83
Trust Score:8.9
License:Unlicense
Update:2 months ago
Show doc for...
Tokens:
Raw
### Clipnode statistics output

Source: https://github.com/wootguy/bspguy/wiki/Merging-workflow

Example output showing the reduction in clipnode usage after applying optimization flags.

```text
 Data Type     Current / Max       Fullness
------------  -------------------  --------
...
clipnodes        23121 / 32767       70.6%
...
```

--------------------------------

### Build bspguy from Source on Windows

Source: https://github.com/wootguy/bspguy/blob/master/README.md

Commands to clone and compile the project using CMake on Windows.

```bash
git clone --recurse-submodules --shallow-submodules https://github.com/wootguy/bspguy
cd bspguy
mkdir build && cd build
cmake ..
cmake --build . --config Release
```

--------------------------------

### Display bspguy CLI Usage

Source: https://github.com/wootguy/bspguy/blob/master/README.md

View the command-line interface help menu to see available commands and options.

```text
Usage: bspguy <command> <mapname> [options]

<Commands>
  info      : Show BSP data summary
  merge     : Merges two or more maps together
  noclip    : Delete some clipnodes/nodes from the BSP
  delete    : Delete BSP models
  simplify  : Simplify BSP models
  transform : Apply 3D transformations to the BSP

Run 'bspguy <command> help' to read about a specific command.
```

--------------------------------

### Build bspguy from Source on Linux

Source: https://github.com/wootguy/bspguy/blob/master/README.md

Commands to clone and compile the project using CMake on Linux systems.

```bash
git clone --recurse-submodules --shallow-submodules https://github.com/wootguy/bspguy
cd bspguy
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make
```

--------------------------------

### Integrate bspguy with existing map scripts

Source: https://github.com/wootguy/bspguy/wiki/Merging-workflow

Call bspguy MapInit and MapActivate methods within an existing map script to maintain compatibility.

```AngelScript
#include "func_vehicle_custom"
#include "bspguy/v1/bspguy"

void MapInit()
{
	VehicleMapInit( true, true );
	bspguy::MapInit();
}

void MapActivate()
{
	bspguy::MapActivate();
}
```

--------------------------------

### Convert image to C header array

Source: https://github.com/wootguy/bspguy/blob/master/src/data/icons/readme.txt

Use this command to transform a binary image file into a C header file containing a byte array. Ensure the input file exists and the script has write permissions for the output file.

```bash
python -c "import sys;a=sys.argv;open(a[2],'wb').write(('const unsigned char '+a[3]+'[] = {'+','.join([hex(b) for b in open(a[1],'rb').read()])+'};').encode('utf-8'))" image.png image.h image
```

--------------------------------

### Configure executable and build flags

Source: https://github.com/wootguy/bspguy/blob/master/CMakeLists.txt

Defines the executable target, links required libraries, and sets C++ compiler flags for different build modes.

```cmake
else()
	add_executable(${PROJECT_NAME} ${SOURCE_FILES})
	target_link_libraries(${PROJECT_NAME} glfw liblzma GL GLU X11 Xxf86vm Xrandr pthread Xi GLEW stdc++fs ${CMAKE_DL_LIBS})
	set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Werror=return-type -fno-omit-frame-pointer -std=c++11")
	set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -DDEBUG_MODE -g -O0")
	set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O2")
endif()
```

--------------------------------

### Include Directories

Source: https://github.com/wootguy/bspguy/blob/master/CMakeLists.txt

Adds various project subdirectories to the include path.

```cmake
include_directories(src)
include_directories(src/bsp)
include_directories(src/cli)
include_directories(src/data)
include_directories(src/editor)
include_directories(src/gl)
include_directories(src/qtools)
include_directories(src/util)
include_directories(src/nav)
include_directories(src/lib)
include_directories(imgui)
include_directories(imgui/examples)
include_directories(imgui/backends)
include_directories(glew/include)
include_directories(${CMAKE_BINARY_DIR})
```

--------------------------------

### Organize Source Files in IDE

Source: https://github.com/wootguy/bspguy/blob/master/CMakeLists.txt

Uses source_group to organize files into logical folders within Visual Studio.

```cmake
source_group("Header Files\\bsp" FILES	src/bsp/BspMerger.h
							src/bsp/Bsp.h
							src/bsp/bsplimits.h
							src/bsp/bsptypes.h
							src/bsp/Entity.h
							src/bsp/Keyvalue.h
							src/bsp/Wad.h
							src/bsp/colors.h
							src/bsp/remap.h)
							
	source_group("Source Files\\bsp" FILES	src/bsp/BspMerger.cpp
							src/bsp/Bsp.cpp
							src/bsp/bsptypes.cpp
							src/bsp/Entity.cpp
							src/bsp/Keyvalue.cpp
							src/bsp/Wad.cpp
							src/bsp/colors.cpp
							src/bsp/remap.cpp)
	
	source_group("Header Files\\cli" FILES	src/cli/CommandLine.h
							src/cli/ProgressMeter.h)
							
	source_group("Source Files\\cli" FILES	src/cli/CommandLine.cpp
							src/cli/ProgressMeter.cpp)
	
	source_group("Header Files\\gl" FILES	src/gl/Shader.h
							src/gl/ShaderProgram.h
							src/gl/VertexBuffer.h
							src/gl/Texture.h
							src/gl/TextureArray.h
							src/gl/primitives.h
							${CMAKE_BINARY_DIR}/embedded_shaders.h
							src/gl/shaders.h)
							
	source_group("Source Files\\gl" FILES	src/gl/Shader.cpp
							src/gl/ShaderProgram.cpp
							src/gl/VertexBuffer.cpp
							src/gl/Texture.cpp
							src/gl/TextureArray.cpp
							src/gl/primitives.cpp
							${CMAKE_BINARY_DIR}/embedded_shaders.cpp
							src/gl/shaders.cpp)
							
	source_group("Source Files\\gl\\shaders" FILES ${SHADER_FILES})
							
	source_group("Header Files\\editor" FILES	src/editor/BspRenderer.h
								src/editor/TextureAtlas.h
								src/editor/Renderer.h
								src/editor/Fgd.h
								src/editor/Gui.h
								src/editor/PointEntRenderer.h
								src/editor/Command.h
								src/editor/AppSettings.h
								src/editor/MdlRenderer.h
								src/editor/SprRenderer.h
								src/editor/BaseRenderer.h
								src/editor/Clipper.h)
							
	source_group("Source Files\\editor" FILES	src/editor/BspRenderer.cpp
								src/editor/TextureAtlas.cpp
								src/editor/Renderer.cpp
								src/editor/Fgd.cpp
								src/editor/Gui.cpp
								src/editor/PointEntRenderer.cpp
								src/editor/Command.cpp
								src/editor/AppSettings.cpp
								src/editor/MdlRenderer.cpp
								src/editor/SprRenderer.cpp
								src/editor/BaseRenderer.cpp
								src/editor/Clipper.cpp)
```

--------------------------------

### Organize source files with source_group

Source: https://github.com/wootguy/bspguy/blob/master/CMakeLists.txt

Groups source and header files into virtual folders for IDE project organization.

```cmake
source_group("Header Files\\qtools" FILES	src/qtools/rad.h
												src/qtools/vis.h
												src/qtools/winding.h)
												
	source_group("Source Files\\qtools" FILES	src/qtools/rad.cpp
												src/qtools/vis.cpp
												src/qtools/winding.cpp)
												
	source_group("Header Files\\util" FILES		src/util/util.h
												src/util/vectors.h
												src/util/Polygon3D.h
												src/util/Line2D.h
												src/util/mstream.h
												src/util/lzma_util.h
												src/util/ThreadSafeInt.h
												src/util/mat4x4.h
												src/util/bmp.h)
												
	source_group("Source Files\\util" FILES		src/util/util.cpp
												src/util/vectors.cpp
												src/util/Polygon3D.cpp
												src/util/Line2D.cpp
												src/util/mstream.cpp
												src/util/lzma_util.cpp
												src/util/ThreadSafeInt.cpp
												src/util/mat4x4.cpp
												src/util/bmp.cpp)
												
	source_group("Header Files\\nav" FILES		src/nav/NavMesh.h
												src/nav/NavMeshGenerator.h
												src/nav/LeafNavMeshGenerator.h
												src/nav/LeafNavMesh.h
												src/nav/PolyOctree.h
												src/nav/LeafOctree.h)
												
	source_group("Source Files\\nav" FILES		src/nav/NavMesh.cpp
												src/nav/NavMeshGenerator.cpp
												src/nav/LeafNavMeshGenerator.cpp
												src/nav/LeafNavMesh.cpp
												src/nav/PolyOctree.cpp
												src/nav/LeafOctree.cpp)
	
	source_group("Header Files\\util\\lib" FILES	src/util/lodepng.h)
	
	source_group("Source Files\\util\\lib" FILES	imgui/imgui.cpp
													imgui/imgui_tables.cpp
													imgui/imgui_widgets.cpp
													imgui/imgui_draw.cpp
													imgui/imgui_demo.cpp
													imgui/backends/imgui_impl_glfw.cpp
													imgui/backends/imgui_impl_opengl2.cpp
													src/util/lodepng.cpp)
```

--------------------------------

### View map statistics

Source: https://github.com/wootguy/bspguy/wiki/Merging-workflow

Displays the resource usage statistics of the generated BSP file, highlighting potential overflows.

```text
 Data Type     Current / Max       Fullness
------------  -------------------  --------
models             153 / 4096         3.7%
planes           14831 / 65535       22.6%
vertexes         31226 / 65535       47.6%
nodes            11647 / 32768       35.5%
texinfos          7091 / 32767       21.6%
faces            20846 / 65535       31.8%
clipnodes        33577 / 32767      102.5%  (OVERFLOW!!!)
leaves            7537 / 65536       11.5%
marksurfaces     28153 / 65536       43.0%
surfedges        98479 / 512000      19.2%
edges            52964 / 512000      10.3%
textures           272 / 4096         6.6%
lightdata          2.6 / 48.0  MB     5.4%
visdata            2.7 / 8.0   MB    34.0%
entities          1760 / 8192        21.5%
```

--------------------------------

### Add custom texture light to lights.rad

Source: https://github.com/wootguy/bspguy/wiki/Porting-Sven-Co‐op-Maps-to-Half‐Life

Define a custom texture light entry in the lights.rad file by specifying the texture name, RGB color values, and brightness.

```text
~spotred    208 0 0 1000
```

--------------------------------

### Configure Custom Shader Embedding

Source: https://github.com/wootguy/bspguy/blob/master/CMakeLists.txt

Defines a custom command and target to ensure shader files are processed during every build.

```cmake
add_custom_command(
	OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/__dummy_file.h  # fake file that never exists, causing this step to run every build
	${CMAKE_BINARY_DIR}/embedded_shaders.cpp
	COMMAND ${CMAKE_COMMAND} -P "${CMAKE_SOURCE_DIR}/embed_shaders.cmake" "embedded_shaders.h" "embedded_shaders.cpp" ${SHADER_FILES}
)
add_custom_target(
	my_custom_target_that_always_runs ALL
	DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/__dummy_file.h
)
```

--------------------------------

### Regenerate lightmaps with HLRAD

Source: https://github.com/wootguy/bspguy/wiki/Porting-Sven-Co‐op-Maps-to-Half‐Life

Use this command to fix broken lightmaps after scaling or subdividing faces. Ensure hlrad.exe and lights.rad are in the map directory.

```bash
hlrad.exe -estimate -nobleedfix -notextures -bounce 3 -extra mapname.bsp
```

--------------------------------

### MSVC Specific Build Configuration

Source: https://github.com/wootguy/bspguy/blob/master/CMakeLists.txt

Configures compiler flags, linker settings, and dependencies specifically for MSVC builds.

```cmake
if(MSVC)
	add_executable(${PROJECT_NAME} ${SOURCE_FILES} src/data/icons/app_icon.rc)
	target_link_libraries(${PROJECT_NAME} glfw liblzma)

	add_custom_command(
		TARGET ${PROJECT_NAME}
		PRE_BUILD
		COMMAND ${CMAKE_COMMAND} -P "${CMAKE_SOURCE_DIR}/embed_shaders.cmake" "embedded_shaders.h" "embedded_shaders.cpp" "${SHADER_FILES}"
		${CMAKE_CURRENT_BINARY_DIR}/__dummy_file.h
	)
	add_dependencies(${PROJECT_NAME} my_custom_target_that_always_runs)

	# no warnings for release builds
	set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} /W0")
	set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} /W1")

	# parallel compile,
	set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /MP /we4715")
	set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS} /MP /we4715")
	
	set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -DDEBUG_MODE")
	
	set(CMAKE_EXE_LINKER_FLAGS_RELEASE "${CMAKE_EXE_LINKER_FLAGS_RELEASE} /SUBSYSTEM:WINDOWS")
	set(CMAKE_EXE_LINKER_FLAGS_DEBUG "${CMAKE_EXE_LINKER_FLAGS_DEBUG} /SUBSYSTEM:CONSOLE")
	
		
	add_subdirectory(glfw)
	
	set_property(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTY VS_STARTUP_PROJECT bspguy)
	
	if(CMAKE_SIZEOF_VOID_P EQUAL 4)
		set(GLEW_PATH ${CMAKE_CURRENT_SOURCE_DIR}/glew/lib/Release/Win32/glew32s.lib)
	else()
		set(GLEW_PATH ${CMAKE_CURRENT_SOURCE_DIR}/glew/lib/Release/x64/glew32s.lib)
	endif()
	
	target_link_libraries(${PROJECT_NAME} opengl32 ${GLEW_PATH})
endif()
```

--------------------------------

### Merge split map areas using bspguy CLI

Source: https://github.com/wootguy/bspguy/wiki/Porting-Sven-Co‐op-Maps-to-Half‐Life

Use the merge command to combine multiple isolated BSP files into a single map, applying the -hl flag to enforce the smaller world size limit.

```bash
bspguy merge mogul_hl -maps "a,b,c,d" -hl -noscript -noripent
```

--------------------------------

### Convert font to C header file

Source: https://github.com/wootguy/bspguy/blob/master/src/data/fonts/readme.txt

Use this Python command to convert a .ttf font file into a C header file containing a byte array. Ensure the font file is in the same directory or provide the correct path.

```python
python -c "import sys;a=sys.argv;open(a[2],'wb').write(('const unsigned char '+a[3]+'[] = {'+','.join([int(b) for b in open(a[1],'rb').read()])+'};').encode('utf-8'))" fontname.ttf fontname.h fontname
```

--------------------------------

### Clipnode usage statistics

Source: https://github.com/wootguy/bspguy/wiki/Merging-workflow

Displays the current clipnode usage relative to the maximum limit.

```text
 Data Type     Current / Max       Fullness
------------  -------------------  --------
...
clipnodes        32653 / 32767       99.7%
...
```

```text
 Data Type     Current / Max       Fullness
------------  -------------------  --------
...
clipnodes        28615 / 32767       87.3%
...
```

--------------------------------

### Merge BSP files

Source: https://github.com/wootguy/bspguy/wiki/Merging-workflow

Executes a basic merge of two BSP files into a single output file.

```bash
bspguy merge test.bsp -maps "echoes14, echoes14b"
```

--------------------------------

### Post-merge clipnode statistics

Source: https://github.com/wootguy/bspguy/wiki/Merging-workflow

Statistics output after performing a partial hull strip and merge.

```text
 Data Type     Current / Max       Fullness
------------  -------------------  --------
...
clipnodes        28473 / 32767       86.9%
...
```

--------------------------------

### Merge maps with hull 2 removal

Source: https://github.com/wootguy/bspguy/wiki/Merging-workflow

Uses the -nohull2 flag during the merge process to reduce clipnodes by removing hull 2.

```bash
bspguy merge test.bsp -maps "echoes14, echoes14b" -nohull2
```

--------------------------------

### Strip hull 2 from a single map

Source: https://github.com/wootguy/bspguy/wiki/Merging-workflow

Manually removes hull 2 from a specific map before merging to save clipnodes while preserving collision for large entities in other maps.

```bash
bspguy noclip echoes14 -hull 2 -o echoes14_nohull2
bspguy merge test.bsp -maps "echoes14_nohull2, echoes14b"
```
Tokens:
Raw