Overview: TagsAndFilters

This is actually two very similar systems, or two application of the same system, and is something entirely new to Homeworld Remastered. In brief, many files have lists of tags associated with them that control when they can be loaded by the game. First I'll go over how the system works in general, then go into the specifics of it's two incarnations.

## General

In general, this lets you filter and categorize parts of your mod by tags. Tags are a pretty common concept, but in case they're novel to you, a tag is simply a piece of text to label your file. You can have multiple tags on a file, separated by commas if so, and then filter based on those tags in other files. In this system there are two types of filters, pass and fail, each of which consists of one or more tags. it works as follows:

* If there are no filters, everything passes.
* If there is a pass filter, everything with at least one of the tags listed in the filter passes.
* If there is a fail filter, everything without any of the tags listed in the filter passes.
* If there is BOTH a pass and fail filter, things that have a tag listed in the pass filter and don't have any fail tags pass.
* If there is a pass filter and a fail filter that both list the same tag, I belief that tag fails. Don't do that.

## Specific.

That out of the way, on to where you can find this system. There are two types, the "ExtFilter" and everything else. To quote BitVenom "ExtFilter="xxx,yyy,zzz" are tags that are ONLY used during the initial bootstrap and gather phase of the game. Once. It finds a file (levels, rules, race) it checks that file's ExtFilter tags". In other words, if the file passes the extfilter test, the game loads it. If it fails, it does not load it, and from that point on it might as well not be part of the game. the ExtFilter can be used either through command line flags, which is useful for testing ends, or more permanently by including a ConfigFilters.Lua in data/scripts.

* CMD line flags: -extPassFilter=xxx,yyy,zzz -extFailFilter=xxx,yyy,zzz
* ConfigFilter.Lua: PassFilter="xxx,yyy,zzz" FailFilter="xxx,yyy,zzz"
* General Lua: ExtFilter="xxx,yyy,zzz"

On files you want to tag, you'll follow the third above syntax example. include that line somewhere in the file, near the top for best visibility and outside of any other structures, and fill out the tags as appropriate.

If you open gearbox's files you'll see that the ExtFilter = line is often followed by a Tags = line, which is the second appearance of this system. This is used in many different places for many different things, but follows the same structure. The difference here is that you'll have files being situationally filtered in and out based on circumstance rather than being done only on mod load. For instance a game rule can filter what playable races are available and what maps can be picked based on tags, and races filter what formations are available to them via tags. I'll try to find and list all the instances of them, but if I miss any anyone else is free to fill them.

The list will go here when I make it.

## But why though?

At first blush this may seem overly complicated, but it does solve problems. For instance, in my mod I wanted to include some new game types and suppress the gearbox ones from showing up, so that I would ensure that the scripting framework our ships need always is present for them and the maps available are ones appropriate for the design of our resourcing, among other concerns. Under HW2 I simply overwrote the original deathmatch gamerule, but in HWR there are suddenly multiple gamerules and overwriting them all is impractical. Instead I can simply include new rules in new files and use ConfigFilters to block the stock rules from loading, which has the advantage of being a system that works even if the names of the stock files change or new ones appear.

Or if someone were to make a mod that adds a new formation type, they can simply tag it properly and it'll appear in the formation options for the right races, without having to modify lists in each race file as likely would have happened if an older, pre-tagging implementation of formations had existed.

Other uses or potential uses for tagging and filtering exist, once you get the hang of it, but are left as an exercise to the reader.

Much of this information originally comes from https://forums.gearboxsoftware.com/t/mod-filtering-just-say-no-to-hacked-files/539459 where you might find useful clarifications or discussion.