Choose an option

Options are properties of the [Inject] attribute. To set several, separate them with commas: [Inject(Optional = true, Reactive = true)]. To choose an option, answer the question in its row:

OptionAsk yourselfWhat changes in your code
OptionalCan my script work without the dependency?Check the member for null before you use it.
ManualDo I want to choose when the member is injected?Call Manual.Inject when you want it.
EditModeDo I need the dependency outside Play mode?The member is also injected in Edit mode.
OverwriteShould a dependency replace the value I assigned?Your value comes back when the dependency goes away.
AsyncCan my script wait for the dependency to arrive?Wait until the context is ready before you use the member.
ReactiveShould my script follow when the providers give another dependency?The member can receive another dependency later. React to the change in the property's set accessor.
WarmShould my script use what's available now, and receive a better dependency later without waiting?The member holds what's ready now. Add Reactive, or call Manual.Reinject, to receive the better one once it's prepared.
WeakShould my script hold the dependency without keeping it alive?The member returns to its default when nothing else holds the dependency.

To set an option for every member of a class or an assembly, refer to Set options for several members.

Optional

A member is required by default: when its dependency is missing, the member fails, and the Console window displays an error. An Optional member keeps its default instead, without an error:

[Inject(Optional = true)] IAnalytics analytics;

void Start() => analytics?.Track("start");   // null when no provider gives IAnalytics

To hold a stand-in object instead of null, use Overwrite.

Manual

A Manual member is injected only when you call Manual.Inject, such as when you take an object from a pool:

[Inject(Manual = true)] Player target;

public void OnSpawn() => Manual.Inject(this, nameof(target));
public void OnDespawn() => Manual.Release(this, nameof(target));

The Manual class works on any member, not only Manual members:

MethodDescription
Manual.Inject(context)Injects the members that aren't injected yet. Called in Awake, it injects them early.
Manual.Reinject(context)Replaces the dependency of each injected member with what the providers give now.
Manual.Release(context)Releases the members. The context stays alive, and is no longer ready.

To act on the static members of a class, pass the class's Type as the context. To act on one member only, pass its name, with nameof. A call with nothing to do does nothing. A name that matches no member throws an exception, and code analysis reports it as SLV0102.

Outside Play mode, Manual.Inject injects only EditMode members, and the others wait for Play mode. Passing the name of a required member that isn't EditMode returns a failed operation.

EditMode

Selvage injects members in Play mode and in builds. An EditMode member is also injected in Edit mode, for use in [ExecuteAlways] scripts, ScriptableObjects and Editor tools. A dependency injected in Edit mode stays when you enter Play mode.

Every provider that ships with Selvage gives dependencies in Edit mode. An object Selvage creates for an EditMode member, such as an instance of a provided prefab, is never saved into your scenes or your project. An object you add to a registry in Edit mode stays until you remove it. An addressable asset loads at once in Edit mode, because Addressables only progresses in Play mode.

The Live tab of the Dependencies window lists the contexts with EditMode members while you edit. For more information, refer to Inspect injected members.

Overwrite

Selvage injects only a member that holds null. With Overwrite, the dependency replaces the member's value, and the value comes back when the dependency goes away. A member with a value of its own therefore never fails:

[Inject(Overwrite = true)] IAudio audio = new SilentAudio();   // SilentAudio when no provider gives IAudio

Async

Some dependencies take time to arrive, such as an Addressables asset. A member can't wait for them unless it's Async: without this option, the member skips such a dependency and receives one from a provider below, or none. An Async member keeps its default until the dependency arrives. To receive one later without waiting, refer to Warm.

An Async member doesn't wait for an object your code adds to a registry later, unless you promise the object's type with WithinSeconds. For more information, refer to Require every member to be guaranteed.

A context is ready once all its members are injected, including its Async members. Before you use an Async member, wait until its context is ready.

The Context class tells you when a context is ready. The following example waits in Start, which is a coroutine:

[Inject(Async = true)] ISaveData save;

IEnumerator Start()
{
    yield return Context.WhenReady(this);
    ShowBest(save.BestScore);
}

Unity keeps calling Update while Start waits, so code in Update must check Context.IsReady.

To wait in an async method, an event handler or code that runs every frame, and to handle a failed wait or set a timeout, refer to Wait until a context is ready.

Reactive

By default, a member keeps the dependency it received until it's released or reinjected. A Reactive member is reinjected by Selvage when what the providers give may have changed. For a property, the set accessor runs with each new dependency, so you can react there:

[Inject(Reactive = true)]
ICharacter Character
{
    get => character;
    set { character = value; RefreshPortrait(); }
}
ICharacter character;

Selvage reinjects a Reactive member, on the next frame, in the following cases:

What happensWhat the member receives
The provider that gave its dependency announces a change: the registry when you add or remove an object, a watched scene object that appears or leaves, or a custom provider.What the whole provider list gives now. If nothing gives it anything, it keeps its dependency, unless that dependency was revoked: it then returns to its default.
A provider is added, removed or turned off, or the provider list is edited.A dependency from a provider above the one that gave its current dependency, if one has it. Otherwise it keeps its dependency.

A Reactive member that holds nothing receives a dependency as soon as a provider announces a change and has one for it.

The Scene Provider looks for components only when a member is injected, so a Reactive member doesn't follow a component that's created or destroyed, unless that object is watched. A destroyed component reads as null, like any reference to a destroyed object. To give a member what the providers give now, call Manual.Reinject, which asks every provider again.

If a new dependency can't be injected, Selvage logs an error, and the member keeps its current dependency.

Warm

A provider that takes time, such as one that loads an Addressables asset, gives its dependency only to members that can receive it later. Other members skip it and receive a dependency from a provider below. A member receives the dependency of a provider that takes time in the following ways:

  • It waits for it, with Async. The member's injection, and its context's readiness, end when the dependency arrives.
  • It has it prepared, with Warm. The member's injection doesn't wait: the member receives the best dependency that's ready now, and Selvage prepares the dependencies of the providers above it in the background. The member receives a prepared dependency on the next Manual.Reinject call.

The two combine: a member that's both Async and Warm waits like an Async member, and holds the dependency that's ready below while it waits.

For example, the demo's CloudSave provider, first in the provider list, gives a save from a simulated cloud after a second, and the Registry Provider below it holds the save on this device, ready at once. The following diagram shows what a SaveData member holds over time, depending on its options:

No option Device save (Registry Provider): the member skips CloudSave Async null: the member waits Cloud save (CloudSave) Warm Device save: the cloud save is prepared, then held ready Cloud save Async, Warm Device save: the member waits Cloud save (CloudSave) Injection The cloud save is ready Manual.Reinject

The Async members receive the cloud save when it arrives, because their injection waits for it: their context is ready only then. The Warm member's injection ends at once, with the device save, so its context is ready at once. The cloud save is then held ready, and reaches the member when you call Manual.Reinject. To have it delivered as soon as it's ready instead, also make the member Reactive. The demo's Hud uses Async, Warm and Reactive.

Selvage also prepares dependencies from the providers below the one that gave the member's dependency, down to the first provider whose dependencies can't change. When the provider that gave the dependency revokes it, a Reactive Warm member receives a ready dependency from a provider below at once, instead of returning to its default while a replacement loads.

A prepared dependency is held, and a provider that takes time keeps loading in the background, so a Warm member costs memory and work even before it receives what was prepared. A Warm member that's also Weak receives the best dependency that's ready, and nothing is prepared for it.

Note: Without Async, a Warm member never waits. When no provider has a dependency ready, a required one fails on its first injection, and an optional one keeps its default, until a prepared dependency reaches it.

Weak

An object Selvage created, such as an instance of a [Provide] class, ends once no member holds it. A Weak member holds its dependency without keeping it alive. Use it when something else keeps the dependency alive, or to break a loop: when two objects Selvage created hold each other, each keeps the other alive, so neither ever ends. Make one of the two members Weak:

[Provide]
public class Session : ISession
{
    [Inject] IMatchmaker matchmaker;          // keeps the matchmaker alive
}

[Provide]
public class Matchmaker : IMatchmaker
{
    [Inject(Weak = true)] ISession session;   // doesn't keep the session alive
}

The session then ends once no other member holds it, and releases the matchmaker as it ends.

An object that only Weak members hold ends one frame later, unless a member that isn't Weak takes it by then. When the dependency ends, the member returns to its default, and a required member fails. With Reactive, the member receives a replacement when a provider has one.

Weak only changes something for the objects Selvage creates. Selvage never ends a scene component, an asset or an object you add to a registry, so a Weak member holds those like any other member.