trenchbroom_pbr_guide.md

this guide is not done

I have been working on a better, updated guide here: https://coda.io/d/Trenchbroom-Guide_d77T7fADkTg/Beginners-Guide-to-Qodot_suWQh#_luwA5

Comparison Between Qodot Material Methods

Here's what options you have:

• Material Override
• Auto PBR
• Base Textures (Albedo-Only)

Benefit	Base	Override	Auto
Use Textures in Trenchbroom	✅	✅	✅
Loose Naming Scheme	✅
Simple Folder Structure	✅
Keep Material Tweaks on Map Rebuild		✅
ShaderMaterials-Compatible		✅
Builds Godot Materials for You			✅

This guide covers using the Material Override Method

How to make a Qodot project with Existing PBR materials

This guide will guide you through the process of making a Qodot project that is integrated with Trenchbroom, and uses PBR materials.

By the end of this guide you should be able to:

• Install Qodot
• Setup Textures to work with Qodot
• Setup QodotMap to find your textures
• Have a .tres/.material file applied in place of a basic texture
• Setup Trenchbroom to work with Qodot

There are also some examples to show some deeper examples and tips that are not necessary to getting this to work, but may help when implementing Qodot into your projects.

This guide expects you to already know how to:

• Create and rename folders
• Obtain and rename textures
• Add nodes in Godot
• Save scenes in Godot
• Create .material files in Godot

This guide also expects that Godot and Trenchbroom are both downloaded and located somewhere that you're able to find later. As a sidenote before starting, Qodot comes with some example textures, but this guide assumes you'll be adding new textures from scratch. https://cc0textures.com is one example of a place to find PBR textures for free.

Installing Qodot

Either create a new Godot project, or pick an existing project.

1. Navigate to AssetLib
2. Search "Qodot"
3. Click Download, then Install, then OK when the plugin installs
4. Go to Project > Project Settings
5. Navigate to the Plugins tab
6. Enable Qodot

Alternatively, download Qodot from the Github repository, drop the /addons folder into your Godot project, then follow steps 4-6.

Texture Setup

Setting up your texture folders and files properly will make everything work for Qodot. If it works for Qodot, it should will work for Trenchbroom.

Texture/Material Prerequisites

There are some prerequisites to using textures with Qodot. Before proceeding, make sure:

1. All textures you want to use for a single map are using the same file extension.
   (.jpg/.png/.bmp/.tga)
2. All PBR materials you want to use in a single map are the same filetype.
   (.tres or .material)
3. You are are not using textures inside of /addons/qodot/textures
   If you're using Qodot's example textures, they should be moved out to res://textures/ instead, for the sake of clarity and ease-of-use.

Different maps can have different file extensions for textures and materials, but each map needs to stick to one.

Your Textures Directory

Trenchbroom operates on texture files being in a /textures/group-name/ folder, and QodotMap finds these textures the same way. Textures need to be at least one level deeper than the /textures folder or else they won't be located by either program.

The placement of .map files in your project is less important, they can be located anywhere in your project directory that is helpful for you, and so long as Godot doesn't hide the folder. (folders named src are hidden to Godot by default). Read more about tips for project organization when it comes to .map files.

QodotMap Setup

QodotMap is the node that will hold your .map file.

• Add QodotSpatial node
• Add QodotMap node

You don't need a map file ready just yet, but the option to add it to the QodotMap node is there in the inspector.

For our textures, the QodotMap node needs to be able to locate the textures inside your project directory.

1. Click the folder icon on "Base Texture Dir" in the inspector and select your project's /textures folder.
   Note: By default, clicking this icon will show the /addons/qodot/textures folder. It's possible to use Qodot like this, but it will be far more cumbersome than choosing a res://textures folder or something similar instead.
2. Type a file extension into "Texture File Extension" (.jpg/.png/.bmp/.tga)
3. Type a material extension into "Material Extension" (.tres/.material/.res)

For every QodotMap, there is a property called "Texture File Extension" which the QodotMap parses on texture files while it's building the .map file. This is why each map needs to have textures that use the same file extension, otherwise the images won't be parsed by QodotMap while building.

QodotMaps also only looks to associate .tres files or .material files with an image if the Material Extension property has an extension specified. This is set to .tres by default.

Associating Textures with Materials

Image files can be read by Trenchbroom, and re-interpreted as .material or .tres files by Qodot if the image file and .material/.tres file have the exact same filename, barring their file extension.

Here is an example of this:

- /textures
	- /jungle
		- vines.png
		- vines.material
		- zebra.png
		- zebra.material

Only the vines.png and zebra.png will show up in Trenchbroom, but Qodot will apply the .material file instead. This can be more useful than Qodot's default means of assigning the image textures to a default material, which may not be tuned the way you want on first-glance.

Game Definitions

To get Trenchbroom connected to your Godot project's /textures folder, follow these guides on the Qodot wiki:

1. Exporting Game Definitions for Trenchbroom
   https://github.com/Shfty/qodot-plugin/wiki/2.-Usage#exporting-game-definitions-for-trenchbroom

2. Setting Up Trenchbroom for Godot Project Integration
   https://github.com/Shfty/qodot-plugin/wiki/7.-TrenchBroom#setting-up-trenchbroom-for-godot-project-integration

Further Examples

Here are longer examples that aim to show more details about how to work with Qodot, but these aren't necessary to get Qodot working with Trenchbroom or to have PBR materials applied to brushes.

Creating the Textures Folder

Here's what needs to be seen by Trenchbroom in order to have your textures read:

- /textures
	- /foliage
		- vines.png
		- grass.png

In this example, all images inside /foliage will appear in editor. To hide certain images from the editor (normal maps, roughness maps, etc.) add a subfolder to store and hide these PBR files from Trenchbroom.

Here's one way to organize textures that use PBR:

- /textures
	- /foliage
		- /pbr
			- vines_normal.png
			- vines_displacement.png
			- vines_roughness.png
		- vines.png
		- vines.material

Creating Folders for Maps and Scenes

Trenchbroom will read .map files from anywhere. This section is just a reminder to keep your project organized. Skip to the next section if you already have folders setup for .maps and .tscn files.

If you plan to save each .map file in a .tscn file so that it's easy to access through Godot's scene system, the following folder structure provides a way to organize this kind of project:

- /levels
	- /mapsource
		- jungle.map
	- /scenes
		- jungle.tscn

For more advanced games, try dividing up maps and the corresponding .tscn files into subgroups. Trenchbroom doesn't care where the .map file is, so long as you can locate it if the .map file moves. Here is a deeper example of a folder structure for creating a Quake-like game with Qodot:

- /levels
	- /chapter01_jungle
		- /mapsource
			- jungle01.map
			- jungle02.map
		- /scenes
			- jungle01.tscn
			- jungle02.tscn
	- /chapter02_volcano
		- /mapsource
			- volcano01.map
		- /scenes
			- volcano01.tscn

Adapting Existing Directories for Qodot Use

If you already have a folder system setup that you're adapting to Qodot, here are a few things to keep in mind.

For textures, make sure you have:

1. an easily-accessible /textures folder.
2. a sub-folder to name each grouping of textures. Every texture must belong to a subfolder inside of /textures or else Trenchbroom won't read the texture.
3. optionally, a subfolder named /pbr inside your groupings for any PBR images that you don't want to see in-editor. This can include normal maps, roughness maps, and others.

For maps, make sure you have:

1. a folder to keep .map files handy for Trenchbroom to edit.
2. a folder to save .tscn versions of your .map files.
   This structure may not be ideal for Godot projects that are building .map files in-game, decided by the player, rather than being built by you inside of the Godot editor.

things this guide is missing

• missing difference between auto pbr and texture/material with matching names

• doesn't show trenchbroom process of getting textures and applying that texture

• doesn't show building a map and seeing the final result

then i'll add screenshots i guess