Filters and Tags

Introduction

This system can be difficult for people to get a handle on, so this article will take two approaches. First, an explanation attempting to explore the context of this system in hopes that will make it's workings more meaningful, and thus more memorable. Second, a more stripped down practical example, for those wanting to get straight to the nuts and bolts.

Overview and background

You can think about filters as a set of rules for if something can be used. Something either passes a filter, or fails it, based on some descriptive tags applied to that thing. Filter systems are used in a few different parts of the game, but the first and most important is the ExtFilter. We will focus on that initially, for simplicity.

The ExtFilter is used to determine if a file is loaded at all. If it does not pass the ExtFilter, for the purposes of your mod that file does not exist. This system exists in part to help modders solve a problem, that of removing files in the base game from their mod. Consider the race files: In the HW2 model where there was one races.lua, a mod would always overwrite that with their own and could remove the stock races while doing so. The modern HWR approach instead is modular with individual definition files starting the setup of each race, which among other things allows for the possibility of different mods that add races being loaded simultaneously. But that means that in order to remove races from a mod, that mod's only recourse would be to 'hide' those race's files from the engine by including new empty files with the same name. The ExtFilter provides the solution, letting a mod set it's own rules for what files get loaded.

As said ExtFilters are the first layer, but many files that is subject to the ExtFilter are also subject to a second stage of filtering within gameplay, the details depending on the file type in question. Campaign, level sets, races, game types, and formations can be ExtFiltered, and of these, level sets, races, and formations are filtered again. You can think of the ExtFilter as a 'global' filter and the others as 'local' filters

Formations are subject to filters within the race definitions. This is how it is decided what formations a player of a given race has access to, and is used within the game to give the Vaygr a slightly different formation list than everyone else.

Races and level sets are subject to filters within the gametype definitions, and only those passing the filters set by the currently selected gametype will be listed in the interface. This allows different game types to have different races and maps available for different gametypes within the same mod.

Beyond that, all these filters work exactly the same. There is a value set in the file in question, named ExtFilter for the global filtering and Tags for the local filtering. This naming is a bit confusing, so I'll restate it:

• The ExtFilter value defines the tags for the global filtering phase
• The Tags value defines the tags for the local filtering phase

Each single text string with all the tags describing the file, each tag separated by commas. For instance, the Vaygr cross formation has the ExtFilter value "sgf_gbx,sgf_hwrm", marking it as a strike group made by gearbox for base HWR, and the Tags value "sgf_vgr".

Filtering rules themselves consist of two strings similar to the tags, the pass filter and the fail filter. Both of these are optional.

If there is a pass filter defined, a file must have at least one of the tags listed in the filter, so in the case of the Vaygr cross formation a pass filter of "sgf_mod" would not allow that file to be loaded, but one of "sgf_mod,sgf_gbx" would, because the sgf_gbx tag is present in each. If no pass filter is defined then the default state is passing.

If a fail filter is defined then any file containing any of the tags in the fail filter, appropriate enough, fail filtering. In other words they are rejected. This is true even if they match part of a pass filter, a file must survive both tests to be loaded.

Nuts and bots explanation

This section is intended for quick reference, so some information will be duplicated from the long-form explanation above.

For clarity, the first filtering step, the ExtFilter, will is referred to as global filtering, while all other filtering is local.

Global filter rules are set in data:scripts\ConfigFilters.lua. Here's the filter from Homeworld Fulcrum

FailFilter="races_gbx"
PassFilter="rules_hwat,races_dm,levels_dm_hw1,levels_hwat,campaigns_hwat,rules_sp,sgf_gbx,sgf_hwrm"

This sets up a fail filter that blocks out all the core game factions, and then a pass filter that loads modded gametypes, races tagged for deathmatch, HWRM's ported HW1 deathmatch levels, modded levels, modded campaigns, standard single-player game-rules, and standard strike-group sets. For any filterable file to be loaded it must have one of the passFilter tags but not the one fail tag.

Now an example from a race file, the stock Taiidan.lua

ExtFilter = "races_gbx,races_hw1,races_tai,races_hwrm,races_dm,races_dm_hw1,races_gbx_hwrmc"
Tags = "race_gbx,race_hw1,race_tai,race_hwrm,race_dm,race_dm_hw1,race_gbx_hwrmc"

SG_Pass_Tags = "sgf_common,sgf_tai,sgf_vgr,sgf_hgn,sgf_kus"

In order, these lines do the following, in order:

• Set the global filter tags for the faction, used to determine if the file is loaded with the mod at all
• Set the local filter tags for the faction, used to determine if faction is available within a gametype
• Defines a local pass filter for strike groups, used to determine what formations are available to the faction.

This file would not be loaded by the Fulcrum config filter, because it contains the races_gbx global tag. A copy of the race without that tag would be loaded by Fulcrum because of the pass filter for the races_dm tag.

Next let's look at the sg_wall.lua strike group file.

ExtFilter = "sgf_gbx,sgf_hwrm"
Tags = "sgf_common"

Again, first line sets the global tags, and the second sets the local tags. Fulcrum loads it, as both global tags are in the global pass filter. The Taiidan have access to wall, as it sets a pass filter including the common tag.

Finally, the Vaygr dart formation, sg_vgr_dart.lua:

ExtFilter = "sgf_gbx,sgf_hwrm"
Tags = "sgf_vgr"

Same story as with the wall for the global filtering, but the local pass filter for the Taiidan does not include the formation's only local tag, so the Taiidan do not have access to this formation.

Usage

To enable the usage of filters, you must create a file called "configfilters.lua" in data\scripts\. There are 2 things that you you can put in the file, the first being a PassFilter and the second being a FailFilter. If you have a PassFilter, anything that's not in the pass filter will FAIL.

If you are going to use filters, always add "sgf_gbx,sgf_hwrm" to the PassFilter list, or Homeworld will crash randomly.

Filters are used to determine if an asset will be loaded by the engine. Filters are found usually at the top of a file, in the format ExtFilter = "...". They are found in races, levels, campaigns & strike groups. You could have, for example, ExtFilter = "myCustomCampaign", and in your configfilters.lua file you would have a PassFilter = "myCustomCampaign, sgf_gbx, sgf_hwrm" Found in data\scripts\configfilters.lua

PassFilter

This is used to tell the engine to load content.

FailFilter

This is used to tell the engine to not load content

Example

PassFilter="myCustomCampaign,sgf_gbx,sgf_hwrm" -- Enables custom campaign and required strike groups (to avoid a crash)
FailFilter="levels_dm,levels_hw1,levels_dm_hw1" -- Disables default homeworld levels

Tags

Description

Tags can be applies to races, for example the default Homeworld deathmatch and deathmatch homeworld 1 races only gamerules, one gamerule uses all the homeworld races and another gamerule uses only 2 factions, all races would have a tag "race_dm", and add another tag to the homeworld 1 races called "race_dm_hw1", and in your 4 races gamerule you would add Race_Pass_Tags = "race_dm" and in the hw1 races gamerule you would add "race_dm_hw1". This tells the rules to only load races with the tag "race_dm_hw1".

Race_Pass_Tags

Applies to races

Level_Pass_Tags

Applies to levels

Race_Paths

Usage unknown

SG_Pass_Tags

Applies to strike groups

SG_Pass_Tags = "sgf_common,sgf_hgn"

Example

-- in scripts/rules/deathmath.lua
Race_Pass_Tags = "race_dm" -- only allows homeworld 1 races to play in this rule

-- in scripts/rules/deathmathhw1.lua -- homeworld 1 only races
Race_Pass_Tags = "race_dm_hw1" -- only allows homeworld 1 races to play in this rule

Notes

• If you are using filters and default strike groups you must add sgf_gbx and sgf_hwrm to PassFilter to avoid a spontaneous crash.
• Just Say No To Hacked Files - Gearbox Forums
• Discussion on how filters work can be found here https://forums.gearboxsoftware.com/t/homeworld-remastered-karos-graveyard/4541584/9 and here https://forums.gearboxsoftware.com/t/homeworld-remastered-karos-graveyard/4541584/11

Scope

Related Pages

Comments

Page Status

Updated Formatting? Yes
Updated for HWRM? Yes