Defining custom Filters in DarkRadiant: Difference between revisions

From The DarkMod Wiki
Jump to navigationJump to search
m (use templates and sort page)
m (→‎Adding Filters: Dropped word "presumably" from "DR presumably uses the default ECMAScript flavor..." after consult with greebo)
 
(12 intermediate revisions by 2 users not shown)
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).  The general tag structure is:
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":
<filtersystem>
<filter name="...">
<filterCriterion>...</filterCriterion>
<filterCriterion>...</filterCriterion>
</filter>
</filtersystem>
There is one global '''<filtersystem>''' 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:
[[File:Add filters.png|border|700px]]
<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.
A filter can contain one or more '''Filter Rules''' which define what to search for and whether the matching objects should be shown or hidden. Look at this example:


== More complex Filters ==
[[File:Hide caulk.png|border|700px]]
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? ==
The above filter has one rule, and it is searching for a material/shader name:  
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 ==
  Type = texture
The following filter can be used to show patches only:
Match = textures/common/something
  <filter name="Display Patches Only">
Action = hide
<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 ==
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''' materials and hide them.
Use this filter to display brushes only (''type="object" match="brush"'' doesn't work).
 
<filter name="Display Brushes Only">
Pro Tip: 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. The regular expression syntax is like that of JavaScript. Or more precisely, DR uses the default ECMAScript flavor of the standard <regex> library defined for C++ 11. See  [http://www.cplusplus.com/reference/regex/ECMAScript/|ECMAScript Regular Expression Syntax].
<filterCriterion type="entityclass" match=".*" action="hide" />
 
<filterCriterion type="entityclass" match="worldspawn" " action="show" />
=== Filter Types ===
<filterCriterion type="object" match="patch" action="hide" />
 
</filter>
Let's look at the available filter types:
 
* '''entityclass''': Matches against certain entity class names (like light_torchflame, worldspawn, etc.)
* '''entitykeyvalue''': Matches against the spawnargs of entities.
* '''texture''': Matched against the material/shader names (on primitives as well as on models)
* '''object''': This can be used to filter patches or brushes, only two values are supported in the match field: "brush" or "patch"
 
== Applying two or more Filter Rules ==
 
It's perfectly possible to define multiple rules for a filter, and they are all evaluated in order as listed. Adjust the order with the "Move Up" and "Move Down" buttons (and ignore the values under "Index" if they become momentarily out-of-order). Example:
 
[[File:Show worldspawn only.png|700px]]
 
The above filter has two rules:
 
# The first rule matches against '''all''' entity class names, so it will '''hide''' all entities. (If only this rule was present, the map would appear completely empty.)
# The second rule will match worldspawn and '''show''' it, this will undo the previous rule, but only for worldspawn.
 
As a result, this filter will hide all entities but leave the worldspawn entity visible.
 
== Example Filters ==
 
=== Show Patches only ===
[[File:Show patches only.png|700px]]
 
This filter hides all entities except worldspawn, and will then hide all the brushes - only the patches will be visible. (Note that this also hides any patches that belong to func_static entities or similar.)
 
=== Show Brushes only ===
[[File:Show brushes only.png|700px]]
 
This filter hides all entities except worldspawn, and will then hide all the patches - only the brushes will be visible. (Note that this also hides any brushes that belong to func_static entities or similar.)
 
=== Hide all *_clip Textures ===
Use a regular expression to match against the texture name (where ".+" means "1 or more characters"):
 
[[File:Hide clip textures.png|700px]]
 
It will hide all textures in the textures/common/ folder ending with '''_clip'''
 
=== Hide all .ASE models ===
Again, use a regular expression to search for ASE:
 
[[File:Hide ase.png|700px]]
 
This will match against the "model" spawnarg of entities. If any of them is of the form '''X.ase''' it will hide them. Note that the dot has a special meaning in regular expressions (it's a wildcard). To prevent it from matching against any character, you'll have to escape it, therefore the awkward-looking backslash-dot \. notation.
 
=== Hide all but Loot ===
Here, the regular expression includes "^" meaning "start of string", and "|" meaning "or".
 
''Filter Name: Hide All But Loot''
 
{| style="width: 30%;"
! style="text-align:left;"| Type
! style="text-align:left;"| Entity Key
! style="text-align:left;"| Match
! style="text-align:left;"| Action
|-
|entityclass|| ||.*||hide
|-
|entityclass|| ||^atdm:loot_.*<nowiki>|</nowiki>^atdm:moveable_loot_.*||show
|}
 
=== None of these do what I need! ===
The above are simple examples - if you need help defining a special filter, head over to the [https://forums.thedarkmod.com forums] and ask in the DarkRadiant or Editor's Guild forum, chances are high that you will receive a qualified answer.


{{tutorial-editing}}
{{tutorial-editing}}
{{darkradiant|sort=Filters}}
{{darkradiant|sort=Filters}}

Latest revision as of 11:31, 10 March 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 can contain one or more Filter Rules which define what to search for and whether the matching objects should be shown or hidden. Look at this example:

Hide caulk.png

The above filter has one rule, and it is searching for 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 materials and hide them.

Pro Tip: 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. The regular expression syntax is like that of JavaScript. Or more precisely, DR uses the default ECMAScript flavor of the standard <regex> library defined for C++ 11. See Regular Expression Syntax.

Filter Types

Let's look at the available filter types:

  • entityclass: Matches against certain entity class names (like light_torchflame, worldspawn, etc.)
  • entitykeyvalue: Matches against the spawnargs of entities.
  • texture: Matched against the material/shader names (on primitives as well as on models)
  • object: This can be used to filter patches or brushes, only two values are supported in the match field: "brush" or "patch"

Applying two or more Filter Rules

It's perfectly possible to define multiple rules for a filter, and they are all evaluated in order as listed. Adjust the order with the "Move Up" and "Move Down" buttons (and ignore the values under "Index" if they become momentarily out-of-order). Example:

Show worldspawn only.png

The above filter has two rules:

  1. The first rule matches against all entity class names, so it will hide all entities. (If only this rule was present, the map would appear completely empty.)
  2. The second rule will match worldspawn and show it, this will undo the previous rule, but only for worldspawn.

As a result, this filter will hide all entities but leave the worldspawn entity visible.

Example Filters

Show Patches only

Show patches only.png

This filter hides all entities except worldspawn, and will then hide all the brushes - only the patches will be visible. (Note that this also hides any patches that belong to func_static entities or similar.)

Show Brushes only

Show brushes only.png

This filter hides all entities except worldspawn, and will then hide all the patches - only the brushes will be visible. (Note that this also hides any brushes that belong to func_static entities or similar.)

Hide all *_clip Textures

Use a regular expression to match against the texture name (where ".+" means "1 or more characters"):

Hide clip textures.png

It will hide all textures in the textures/common/ folder ending with _clip

Hide all .ASE models

Again, use a regular expression to search for ASE:

Hide ase.png

This will match against the "model" spawnarg of entities. If any of them is of the form X.ase it will hide them. Note that the dot has a special meaning in regular expressions (it's a wildcard). To prevent it from matching against any character, you'll have to escape it, therefore the awkward-looking backslash-dot \. notation.

Hide all but Loot

Here, the regular expression includes "^" meaning "start of string", and "|" meaning "or".

Filter Name: Hide All But Loot

Type Entity Key Match Action
entityclass .* hide
entityclass ^atdm:loot_.*|^atdm:moveable_loot_.* show

None of these do what I need!

The above are simple examples - if you need help defining a special filter, head over to the forums and ask in the DarkRadiant or Editor's Guild forum, chances are high that you will receive a qualified answer.

Retrieved from "https://wiki.thedarkmod.com/index.php?title=Defining_custom_Filters_in_DarkRadiant&oldid=26158"