tech3bsp

An importer addon for Godot 4 to import an idTech3 BSP file as a Godot scene. Tested on all official builds >= 4.4.1-stable (including the current release version 4.6.stable.official) as well as current dev build 4.7.dev.

Currently supports "Quake 3 Arena", "Star Trek Voyager Elite Force" and "Return to Castle Wolfenstein" BSPs, as well as "WRATH: Aeon of Ruin" though these maps are quite large and will take minutes to import (runtime performance is acceptable). Potential plans to also add Ravens RBSP format (Jedi Outcast, etc.)

• This importer was written from scratch based on publicly available documentation of the Quake 3 BSP file format. No GPL code from the Quake 3 source release was copied or used. Work is based primarily on the unofficial specs found at https://www.mralligator.com/q3/.

If you want to work with Quake 1, Quake 2, Half-Life, or an alternate implementation of Quake 3 Arena BSP's, please check out https://github.com/jitspoe/godot_bsp_importer (which inspired this project).

Features

• Brush, static mesh, and patch geometry with lightmap and vertex color support (requires custom shaders, examples included).
• Import light volumes (lightgrid) for lighting dynamic objects (also requires custom shaders, examples included).
• Imports billboard meshes (typically light flares) - this is still WIP, right now these are just saved as a MultiMesh.
• Material remapping, and fallback automatic materials from albedo texture + lightmap texture.
• Entity remapping via a ConfigFile, automatically adds your own configured scenes into the imported map.
• Includes simple example entity remap file, example shaders, and some lightweight scenes to demonstrate entity remapping.

Installation and Usage

Place "addons/tech3bsp" into your Godot project (remember to include the "addons" directory itself), and enable it in "Project -> Project Settings -> Plugins". Any BSP files placed into your project directory will be automatically converted to Godot scenes.

If you are interested in using idTech3 light volumes (lightgrid) for lighting dynamic objects in your game, run the "setup.gd" script, which will add the necessary global uniforms for you (or add these manually):

• light_grid_ambient, sampler3D
• light_grid_direct, sampler3D
• light_grid_cartesian, sampler3D
• light_grid_normalize, vec3
• light_grid_offset, vec3
  • Make sure you have these globals available BEFORE doing imports: https://github.com/godotengine/godot/issues/77988

You can find very simple examples for shaders which support idTech3 lightmaps and light volumes, as well as an example entity remap ConfigFile and example scenes for BSP entities.

• The entity remap is done via a ConfigFile for simple reusability. It requires an [entities] section, and then the specific remapping is formatted as classname="res://<path to a scene>"
• The example entity scenes all use built-in scripts for simplicity and ease of removal if you don't need them. I highly recommend using external scripts for all scenes you actually care about.

With regards to entity imports, the addon will try and push entity keys (e.g. angles, wait, etc.) to your scenes, so if you want to actually use those values remember to have an @export var with the same name as the entity key (i.e @export var angles, @export var wait), otherwise the value will just be ignored (the entity remap will still occur, it just won't have that property).

• A special note: for now these values are currently just passed as-is, mainly because idTech3 generally repurposes some properties for different results (e.g. angles on a func_door controls its movement direction, while on info_player_start it controls the rotation). For now handle what you want to do with the value on a per-class or per-scene basis, or maybe create a helper class to convert in the way that makes the most sense for your project. Will probably revisit this.

A note on the example shaders as well, these do not have ambient_light_disabled since I believe having additional control over the ambient channel in a final scene is necessary for artistic purposes. As a result, when adding a BSP to a default scene, colors can look more "washed out" because your clear color is probably default grey and automatically applying ambient light via the bg source. Either edit the shader to disable ambient lighting, or add a WorldEnvironment and disable or configure ambient light to your needs.

Import Options

Unit Scale

• Scale the resulting scene map size. The default value results in roughly equivalent idTech3 scaling. Defaults to 32.0.

Light Brightness Multiplier

• Multiply light brightness for imported lights (does not affect lightmaps or the lightgrid). Defaults to 1.0.

Light Attenuation

• OmniLight attenuation setting for imported lights, defaults to 1.0.
  • This setting will have no effect on lightmaps, only light entities (if lightmaps are also enabled, these can still be used for additional lighting/shadows on dynamic objects).
  • Setting this to higher values can result in substantially "smaller" lights due to the physical nature of the falloff curve.
  • A setting of 0.0 comes closer to matching Return to Castle Wolfensteins light falloff, while 1.0 is "hotter" towards the center, which is a bit more like Quake 3 Arena. As far as I'm aware there's currently no way to actually change the light falloff curve calculation via the editor, so these are just "close enough" approximations.
  • If you also have "Use Physical Light Units" enabled for your project, I highly recommend turning the "Light Brightness Multiplier" down to something like 0.1 otherwise your lights will be extremely blown out.

Entity Map

• A path to a ConfigFile where entity remaps can be defined. Please check the "examples" directory for an example file.

Print Missing Entities

• Whether to print to the console when entity remaps are not present (this can be noisy on entity-heavy BSPs if you don't have remaps set up yet). Enabled by default.

Materials Path

• Path for material overrides. The BSP stores textures with a pattern similar to "textures/base/wall01" - the addon will reinterpret this to import Godot materials, so the pattern "/materials/{texture_name}.material" will load "/materials/base/wall01.material")
  • The path can be absolute (i.e. "res://materials/{texture_name}.material") or relative (i.e. "/materials/{texture_name}.material")

Textures Path

• Path to a directory of image files, primarily for fallback material generation purposes right now. Unlike the "Materials Path" option, this just needs to be a directory as it will test multiple image types. Defaults to "textures/"
  • All your file name casing should match how it appears in the BSP file.
  • As with materials, paths can be absolute (i.e. "res://textures/") or relative (i.e. "textures/" or "/textures/")

Fallback Materials

• Whether to generate fallback materials when a material is missing from the material path, either using an example shader supporting lightmaps and/or vertex colors, or a StandardMaterial3D if both vertex color and lightmap imports are disabled. Default true.

Water, Slime, and Lava Scenes

• PackedScene's for BSP liquids, please see the example scenes in the "examples" directory.

Import Lightmaps

• Whether to import pre-baked lighting data from the BSP. This will be stored in the scene itself, rather than saved as individual images to the "res" directory. Enabled by default.

Import Lightgrid

• Whether to import the lightgrid for lighting dynamic meshes, which is also stored with the saved scene. Default enabled.
  • If you import the lightgrid but NOT the lightmaps, you may need to introduce your own shader to use the lightgrid data. The example shader provided relies on the presence of a DirectionalLight3D and a light() shader stage to incorporate the lightgrid into the final result. Consider applying the lightgrid to the EMISSION channel in the fragment() stage instead, or apply at all stages of lighting instead of just directional, whatever works best for your project (doing it in fragment() also means you can use the vertex_lighting render_mode though, if you need that extra retro push).

Import Vertex Colors

• Whether to import baked vertex colors. Default enabled (as static meshes use it).

Import Lights

• If a map is compiled with either a _keeplights key enabled in worldspawn, or -keeplights in the BSP phase, light entities can be imported with this enabled. If lightmaps are also imported, these lights will not affect anything on the same culling layer as the map scene (simulating Godot's lightmapper behavior). Disabled by default.
  • A note on patches and specular highlights: right now, patches (curved geometry) do not fuse vertices, so specular highlights will look incorrect along the edges of each curved segment. This may be updated to fuse vertices later.

Entity Shadow Light

• The entire scene is lit via a generated DirectionalLight3D (see special notes below). This toggles whether this light will also cast shadows from meshes other than the map. These meshes will need to be on visibility layers other than 1 to do any shadowcasting. Disabled by default.

Import Billboards

• Whether to import lightflares. This is very WIP and more of a placeholder for now. Disabled by default.

Split Mesh

• Splits the mesh up by surfaces, though at some point this will be reworked to either split along a grid or somehow use vis data from the BSP itself. Godot works best with a small amount of meshes that contain a large amount of geometry, rather than many meshes each containing a small amount of geometry, so this is disabled by default.
  • Additional BSP models will automatically be "split" into their own MeshInstance3D's, as will patch geometry. Further, if a BSP model or a patch would generate more surfaces than `Rend