Options
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:
| Option | Ask yourself | What changes in your code |
|---|---|---|
Optional | Can my script work without the dependency? | Check the member for null before you use it. |
Manual | Do I want to choose when the member is injected? | Call Manual.Inject when you want it. |
EditMode | Do I need the dependency outside Play mode? | The member is also injected in Edit mode. |
Overwrite | Should a dependency replace the value I assigned? | Your value comes back when the dependency goes away. |
Async | Can my script wait for the dependency to arrive? | Wait until the context is ready before you use the member. |
Reactive | Should 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. |
Warm | Should 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. |
Weak | Should 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:
| Method | Description |
|---|---|
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 happens | What 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 nextManual.Reinjectcall.
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:
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.
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.