Difference between revisions of "Defining custom Filters in DarkRadiant"

From The DarkMod Wiki
Jump to navigationJump to search
(WIP save)
Line 1: Line 1:
 
Filters can be used to hide certain parts of your map file in DarkRadiant. The filtersystem works independently from the regioning or show/hide commands. This affects the model preview window as well. The defined Filters can be toggled through the '''Filters''' menu in the menubar. You can have multiple filters active at the same time.
 
Filters can be used to hide certain parts of your map file in DarkRadiant. The filtersystem works independently from the regioning or show/hide commands. This affects the model preview window as well. The defined Filters can be toggled through the '''Filters''' menu in the menubar. You can have multiple filters active at the same time.
  
== Defining Filters ==
+
== Adding Filters ==
The stock filters are defined in the file '''games/doom3.game''' in your DarkRadiant installation folder (where the EXE is located in). In DarkRadiant 0.9.9 and upwards, the user-defined filters are saved in your user settings folder, (Windows XP: ''C:\Documents and Settings\Username\Application Data\DarkRadiant'', Windows Vista: ''C:\Users\Username\AppData\Roaming\DarkRadiant'', Linux: ''~/.darkradiant''), in a file called '''filters.xml'''. If this file doesn't exist, you can create it by hand using a text editor (just copy the following structure into it for starters).
+
Open the Filter Editor from the top menu bar to define custom filters. By default, there are a couple of read-only stock filters in the list which you can't edit, but you can add new ones to that list by clicking "Add":
  
The general file structure is:
+
[[File:Add filters.png|border|400px]]
<?xml version="1.0"?>
 
<filters>
 
<filter name="...">
 
<filterCriterion>...</filterCriterion>
 
<filterCriterion>...</filterCriterion>
 
</filter>
 
</filters>
 
There is one global '''<filters>''' tag with several filters defined beneath it. Each '''<filter>''' tag can have one or more '''<filterCriterion>''' elements which describe the rules of the filter.
 
  
An easy example is the caulk filter:
+
A filter contains one or more '''Filter Rules''' which are applied in the order they appear in the list. The filter defines what criteria to search for and whether the matching objects should be shown or hidden. Look at this example:
<filter name="Caulk">
 
<filterCriterion type="texture" match="textures/common/caulk" action="hide" />
 
</filter>
 
It has only one criterion which evaluates the texture of the visited object. If the texture matches the regex "textures/common/caulk" the element is hidden. Simple as that.
 
  
'''Regular expressions''' (regex) can be used within the '''match''' attribute of a certain filter, which can be really powerful.
+
[[File:Simple filter.png|border|400px]]
 +
 
 +
The above filter has two rules, both are matching against a material/shader name.
 +
 
 +
Type = texture
 +
Match = textures/common/something
 +
Action = hide
 +
 
 +
Any texture name matching the value in the "Match" column will be hidden, as the "Action" column decides (the Entity Key field is empty, as it is not used by texture type filters). This filter will therefore look for all '''caulk''' and '''monster_clip''' materials and hide them.
 +
 
 +
Note: The text in the "Match" column is evaluated as ''regular expression'' which can be used for wildcard matching and more. See below for some examples.
 +
 
 +
=== Filter Types ===
 +
 
 +
Let's go through the filter types to explain what they are doing when the rule is applied:
 +
 
 +
- object
 +
- entityclass
 +
- entitykeyvalue
 +
- texture
 +
 
 +
// WIP
  
 
== More complex Filters ==
 
== More complex Filters ==

Revision as of 10:38, 15 January 2020

Filters can be used to hide certain parts of your map file in DarkRadiant. The filtersystem works independently from the regioning or show/hide commands. This affects the model preview window as well. The defined Filters can be toggled through the Filters menu in the menubar. You can have multiple filters active at the same time.

Adding Filters

Open the Filter Editor from the top menu bar to define custom filters. By default, there are a couple of read-only stock filters in the list which you can't edit, but you can add new ones to that list by clicking "Add":

Add filters.png

A filter contains one or more Filter Rules which are applied in the order they appear in the list. The filter defines what criteria to search for and whether the matching objects should be shown or hidden. Look at this example:

Simple filter.png

The above filter has two rules, both are matching against a material/shader name.

Type = texture
Match = textures/common/something
Action = hide

Any texture name matching the value in the "Match" column will be hidden, as the "Action" column decides (the Entity Key field is empty, as it is not used by texture type filters). This filter will therefore look for all caulk and monster_clip materials and hide them.

Note: The text in the "Match" column is evaluated as regular expression which can be used for wildcard matching and more. See below for some examples.

Filter Types

Let's go through the filter types to explain what they are doing when the rule is applied:

- object - entityclass - entitykeyvalue - texture

// WIP

More complex Filters

It's perfectly possible to define multiple criterions for a filter, the <filterCriterion> tags are evaluated one after the other. Take a look at the "All Entities" filter:

<filter name="All entities">
	<filterCriterion type="entityclass" match=".*" action="hide" />
	<filterCriterion type="entityclass" match="worldspawn" action="show" />
</filter>

The first criterion filters all entities with the match .* (matches everything). As worldspawn is also an entity, this criterion alone would hide everything, that's why the second criterion overrules the first one by showing the worldspawn entity.

What filter types do exist?

You can filter the following types:

  • entityclass: Filters certain entity classes (like light_torchflame, worldspawn, etc.)
  • texture: This affects all shader names (on primitives as well as on models)
  • object: This can be used to filter patches.

How to display Patches only

The following filter can be used to show patches only:

<filter name="Display Patches Only">
	<filterCriterion type="texture" match=".*" action="hide" />
	<filterCriterion type="entityclass" match=".*" action="hide" />
	<filterCriterion type="entityclass" match="worldspawn" action="show" />
	<filterCriterion type="object" match="patch" action="show" />
</filter>

How to display Brushes only

Use this filter to display brushes only (type="object" match="brush" doesn't work).

<filter name="Display Brushes Only">
	<filterCriterion type="entityclass" match=".*" action="hide" />
	<filterCriterion type="entityclass" match="worldspawn" " action="show" />
	<filterCriterion type="object" match="patch" action="hide" />
</filter>