How Selvage chooses a candidate

An object that could be injected into a member is a candidate. A member can have several candidates, such as when a scene contains two cameras. Selvage chooses among them in the following order:

  1. The first provider in the provider list that has a candidate gives it. Selvage doesn't consider candidates from the providers below it.
  2. The candidates' preferences decide: first the candidates whose preference matches the member, then the candidates without a preference, then the candidates whose preference doesn't match.
  3. Within the Scene Provider, among the candidates the preferences leave tied, the closest component wins.

Preferences don't apply to an object in a local block, which is tried before the provider list and matches by type only, or to a collection member, which receives every candidate of the first provider that has one.

If nothing tells two candidates apart, the member receives nothing, and Selvage displays an error that names the candidates and how to fix it. A required member then fails. For classes marked [Provide] and for assets, the Validation tab reports the tie before you enter Play mode.

Add a preference

A preference on a candidate indicates which members the candidate is for:

[Provide, Preference]                                 // for every member
public class GameAudio : IAudio { ... }

[Provide, Preference(ContextType = typeof(Menu))]    // for the members of Menu
public class MenuAudio : IAudio { ... }

In this example, the members of the Menu class receive MenuAudio, and every other IAudio member receives GameAudio.

Where you add a preference depends on the candidate:

CandidateWhere to add the preference
Scene componentA Provide Tuning component on its GameObject, with Has Preference enabled.
[Provide] classA [Preference(...)] attribute next to [Provide].
Registry entryThe preference argument: Add(obj, preference: new Preference { ... }).
AssetIts Provide Definition, with Has Preference enabled.
A Provide Tuning component on the Main Camera, with Has Preference enabled and Type, under Context Class, set to Player

The Attribute Provider leaves out a class that has [Preference] without [Provide].

Preference settings

A preference matches a member when every setting you set matches the member. Leave the other settings empty.

SettingIn the Inspector windowMatches a member
AskedAsMember > Asked AsThat asks for exactly this type.
MemberNameMember > Member NameWith this name. Case and a leading m_ or _ are ignored.
MemberAttributeMember > Member AttributeThat has an attribute of this class, or of a class that derives from it, such as SerializeField.
ChannelMember > ChannelWith this channel. The Inspector window takes it as text: a string, or the name of an enum value.
ContextTypeContext Class > TypeWhose context is of this class, or of a class that derives from it or implements it.
NamespaceContext Class > NamespaceWhose context's class is in this namespace, or in one inside it.
AssemblyContext Class > AssemblyWhose context's class is in the assembly with this name.
Tag, Layer, SceneContext GameObject > Tag, Layer, SceneWhose context's GameObject has this tag, is on this layer, or is in the scene with this name.
UnderContext GameObject > UnderWhose context's GameObject is at this path from its scene's root, or below it, such as "UI/HUD".

In a text setting, * matches any text, anywhere and any number of times, such as "Level*". No other pattern syntax exists. A type setting accepts an open generic type, such as typeof(Repository<>), to match every type made from it.

The settings that read the context's GameObject (Tag, Layer, Scene and Under) never match a context that isn't on a GameObject, and are only known when the member is injected, so the Validation tab can't use them.

An empty preference matches every member, so its candidate wins wherever no more precise preference matches.

When several preferences match

When several preferences match a member, the most precise one wins: the one that matches everything the others match, and more. For example, "UI/HUD" wins over "UI", and an exact value wins over a pattern that matches it. If no preference is more precise, Selvage displays an error. The Dependencies window reports it before you enter Play mode when it can.

A preference never removes a candidate: when there's only one candidate, a member receives it, whatever its preference. Selvage never reports a preference or a channel that matches nothing, so a script copied into another project keeps working there.

Channels

A preference lets the candidate choose its members. A channel lets the member choose its candidate: the candidate whose preference has the same Channel value wins for that member.

[Inject, Channel("Music")] IAudioBus bus;

[Provide, Preference(Channel = "Music")]
public class MusicBus : IAudioBus { ... }

A channel can be any value, such as a string, an enum value or a number. A member has one channel at most, and a channel doesn't apply to an object in a local block. A channel is a hint: with one candidate, the member receives it whatever its channel.

To read the channel from a field or property of the context's class each time the member is injected or reinjected, use [DynamicChannel]. When it's combined with [Channel], the written channel applies while the field or property holds null:

[SerializeField] string language;

[Inject, DynamicChannel(nameof(language))] AudioClip greeting;              // the channel is the value of language
[Inject, Channel("en"), DynamicChannel(nameof(language))] AudioClip intro;  // "en" while language is null

The field or property can be static. To use a value from another class, read it through a property of this one. Code analysis reports a name that isn't a readable field or property as SLV0108. A [DynamicChannel] is only known when the member is injected, so the Validation tab can't use it.