Targeting assets

A patch is registered against a label, and then narrowed to specific assets by name. This page covers both, and the small set of methods that decide which assets your Do callback runs against.

Labels

A label is a group of assets that load together. PM.Parts patches the parts label, PM.Planets patches the celestial-bodies label, and so on. When you use a typed module, the label is chosen for you, so you never type it. When you use the generic JSON API, you pass the label yourself:

PM.JSON:Patch("game_mode", "ExplorationModeScienceMinValues")

Here game_mode is the label and the second string is your patch's name.

Names: the default is everything

By default, a patch runs against every asset under its label. A PM.Parts:Patch(...) with no name filter runs against every part in the game. That is occasionally what you want (a sweeping change to all parts), but usually you want one or a few specific assets.

You narrow with :Named(...), passing the asset's id:

PM.Parts:Patch("KerbalImpactToleranceFix")
        :Named("eva_kerbal")
        :Do(function(part) part.crashTolerance = 30.0 end)

Now the callback only runs for eva_kerbal.

Naming several assets

:Named takes any number of names, and you can call it more than once. These are equivalent:

:Named("gridfin_1v_radial", "gridfin_2v_radial")

:Named("gridfin_1v_radial")
:Named("gridfin_2v_radial")

Calling it repeatedly reads well when the list is long. This real patch targets five fairings the same way:

PM.Parts:Patch("ConfigureFairingInterstageNodes")
        :Named(
            "fairing_0v_procedural",
            "fairing_1v_procedural",
            "fairing_2v_procedural",
            "fairing_3v_procedural",
            "fairing_4v_procedural"
        )
        :Do(function(part) ... end)

Excluding assets with NotNamed

:NotNamed(...) is the inverse. It is most useful with a patch that otherwise matches everything: "every part except these few." If you find yourself listing almost every asset in :Named, flip to matching all and excluding the rest with :NotNamed.

Naming assets with wildcards

:Named and its counterpart :NotNamed both allow for ? and * wildcards, where ? matches any single character, and * matches any length of characters. This allows for you to collapse a group of names like in the ConfigureFairingInterstageNodes patch above to the following assuming all assets follow a similar pattern in ID:

PM.Parts:Patch("ConfigureFairingInterstageNodes")
        :Named("fairing_?v_procedural")
        :Do(function(part) ... end)

As a warning though, this is an open naming filter, other mods can add assets that match this name filter and your patch will run against them. With proper asset naming conventions from mods, this issue can be avoided.

Which name do I use?

The name is the asset's id, not its display name. For parts it is the part id like engine_1.5v_methalox_bobcat. For bodies it is Mun, Eve, Kerbin. For tech nodes it is tNode_2v_rockets_01. For missions it is KSP2Mission_Main_Kerbin_03. When you are unsure of an id, the existing Redux patches under the game's assets are a good place to copy real ids from, and the typed module pages list the id style for each kind of content.

The most reliable way to find an exact id is the patch cache. After a run, pm_cache contains one archive for each label, for each feature set. For example, parts are under the parts_data label. In the archive, each asset is an entry with its id as the name. Browsing that archive gives you a complete, accurate list of real ids to target, rather than guessing. See Inspecting the cache.

Gating beyond the name

:Named and :NotNamed decide membership by id. When you want to run only against assets that have (or lack) a particular field or value, that is a job for the gates: :Requires, :Has, and :HasNo. See Gates.