This tool converts BSP maps into OBJ files (only supporting quake 3 right now). It automates the annoying common work of reading BSP geometry, finding textures from PK3 archives or extracted folders, copying those textures beside the OBJ, and producing something you can bring into Blender, Unity, Unreal, or a custom engine.

It can also export player-solid collision geometry. That export filters common gameplay blockers such as doors, teleport triggers, and moving train/platform clip blockers, which makes it useful for dogfooding your own engine collision against maps that you know are already good.

jai build.jai

The executable is written to:

bin/bsp_loader.exe

On Linux/macOS, PK3 extraction expects unzip to be installed and available on PATH.

For Quake 3 Arena, point at the game install directory that contains baseq3/pak0.pk3 through pak8.pk3:

bin\bsp_loader.exe -setup_assets -quake3 "C:\Program Files (x86)\Steam\steamapps\common\Quake 3 Arena"

This creates:

data/generated_quake3_assets/

For CPMA, point at the CPMA install. The tool accepts either the folder that directly contains baseq3/ and cpma/, or a parent folder containing a Q3/ child with those folders:

bin\bsp_loader.exe -setup_cpma_assets -cpma "C:\Users\username\programs\CPMA-153-no-q3-paks-v1"

This creates:

data/generated_cpma_assets/

After setup, you do not need to pass the original Quake 3 or CPMA install path again. The exporter uses the generated cache automatically.

The input file decides which cache is used:

• .bsp means a Quake 3 BSP and uses data/generated_quake3_assets/.
• .pk3 means a CPMA map package and uses data/generated_cpma_assets/.

Export a Quake 3 BSP:

bin\bsp_loader.exe data\q3dm17.bsp

Export a CPMA map package:

bin\bsp_loader.exe data\map_cpm15.pk3

By default, exports are written to:

data/exports/<map_name>/

For example, data/map_cpm15.pk3 exports to data/exports/cpm15/.

Map PK3 files are extracted into:

data/generated_map_pk3_assets/

Map-local textures are searched before the generated Quake 3 or CPMA cache, so custom textures included in a map PK3 are copied into the export automatically.

Collision export does not need an asset setup because it only writes geometry:

bin\bsp_loader.exe data\map_cpm15.pk3 -collision

By default, collision exports are written separately:

data/exports/<map_name>_collision/

The collision OBJ names include useful identifiers such as model index, entity classname, brush index, and texture tag. That makes it easier to inspect or tune filters later:

model_5_class_func_plat_brush_1611_local_1_tex_textures_gothic_trim_pitted_rust3_black

The default collision export skips semantic gameplay blockers that tend to close off sections of the map.