As of the 8/13 patch there’s a new way for Mods to control what content a user sees when enabling their mod.
Many files have a new element called ‘ExtFilter’, which defines the tags those files expose to the initial external filtering code.
External filtering can be achieved based on these tags in 2 ways… One is safe for Mods, the other is for testing and development:
Command Line Filtering
-extPassFilter=xxx,yyy,zzz
-extFailFilter=xxx,yyy,zzz
These define the pass and fail tag filters for the game’s execution… adding to any existing values already set or loaded elsewhere.
ConfigFilters.lua
-- Data:\Scripts\ConfigFilters.lua
PassFilter="xxx,yyy,zzz"
FailFilter="xxx,yyy,zzz"
This file can be included in any Mod (though Mods of Mods may want to stay clear), and also defines the pass and fail tag filters - it is additive, so it can work with the Command-Line flags during testing, etc.
How Filtering Works
Filtering by tag is used all over the engine now, not just in loading various content scripts - so this logic applies more than only here. However, this is a reasonable place to explain it.
When we have an asset (script, race, level, levels, etc) with some sort of tags (or none!) defined, and they are filtered, this is what happens:
Asset tags: aaa,bbb,ccc,zzz
Pass tags: aaa,bbb
Fail tags: xxx
So - We test for any pass tags that match. If there is no Pass tags values, all assets match. If an asset has no tags, it fails (it didn’t match). In this case, we pass the asset due to aaa & bbb. Then, we apply a test for the Fail tags, if any tag matches, this filtering attempt fails. In this case, the asset doesn’t have xxx, so it still passes.
Because the logic is very basic, it can be important to make tags very atomic - basic tags, combinations, tags with detail and tags with general classifications. That way, when something need to say ‘only humans for player one’ - the data required for that exists. We were very careful with our tags, so they should act as reasonable examples in that case.
Just as Props files are all found and ready from any required folder (so you can add an extra file instead of editing an existing file) - tags can be placed in a Tags subfolder - though this doesn’t impact the ExtFilter logic.
In the near future it is likely that all extra files (Props/Tags/etc) will be allowed to have their own ExtFilters values to add extra granularity.