Injection lifecycle
When Selvage injects members
Selvage injects the members of a context when the context is created, at the end of the following method:
| Context | Injected at the end of |
|---|---|
| MonoBehaviour | Awake |
| ScriptableObject | OnEnable |
| Plain C# class | Its constructor |
| Static members of a class | Its static constructor. In the Editor, also each time you enter Play mode |
A MonoBehaviour's members are therefore still null inside Awake, and injected in
Start and OnEnable. To use a member inside Awake, call
Manual.Inject(this) before you use it. The Manual class injects and releases a context when
you call it. For more information, refer to Manual.
Unity doesn't allow its API while it creates a MonoBehaviour or a ScriptableObject, or outside its main thread. A context created there waits, and Selvage injects it at one of the following points, before the code of that method runs:
| Context | Injected at the start of |
|---|---|
| Static members of a MonoBehaviour or ScriptableObject class, when Unity creates one of its objects before any code uses the class | The Awake or OnEnable of the first object of the class that
wakes |
| An object you create in a field initializer or constructor of a MonoBehaviour or ScriptableObject | The
Awake or OnEnable of the object that creates it, or before that object's
Start when it declares neither |
| An object you create on another thread | The next callback of any script on the main thread |
A bootstrapper whose Awake runs first and registers dependencies therefore provides them to
those contexts too. Like a MonoBehaviour's own members, they're still null to code that runs before that point,
such as another object's earlier Awake, and to code that runs while Unity creates objects: constructors,
field initializers and OnAfterDeserialize.
A script on an inactive GameObject is injected when the GameObject is first activated, because that's when Unity
calls its Awake method.
Selvage injects members in Play mode and in builds. To inject a member in Edit mode too, use the
EditMode option. A context created in Edit mode, such as a
ScriptableObject asset that Unity loads or an [ExecuteAlways] component, has its other members
injected when you enter Play mode.
Values you assign yourself
Selvage injects only a member that holds null. If you assign a value yourself, in the Inspector
window, in an initializer or in a constructor, Selvage keeps your value:
[SerializeField, Inject] Camera view; // a Camera assigned in the Inspector window stays
To inject over your value, and restore it when the dependency goes away, use the
Overwrite option.
Missing dependencies
When no provider has a dependency for a member, the dependency is missing. The member keeps its
default, which is its initializer, or null.
A member is required by default, so a missing dependency makes it fail: the Console window
displays an error that names the member. A null member is therefore never a silent mistake. To accept
a missing dependency, use the Optional option.
To find missing dependencies before you enter Play mode, refer to Validate members.
When Selvage releases members
When a context ends, Selvage releases its members, in the reverse order of their injection, and an object Selvage created for a member ends once no other member holds it. The members of a plain C# object return to their defaults. The members of a destroyed Unity object keep their last values. Selvage releases a context at the following times:
| Context | Released |
|---|---|
| MonoBehaviour, ScriptableObject | After OnDestroy. |
Plain C# class that implements IDisposable or IAsyncDisposable | After its Dispose or DisposeAsync method. The method can still use the members. |
| Plain C# class that implements neither | When the garbage collector collects it. |
| Static members of a class | Never in a build. In the Editor, when you exit Play mode, as described in When you exit Play mode. |
A MonoBehaviour that also implements IDisposable is released after OnDestroy only. To
release a plain C# object when you choose, implement IDisposable. Releasing twice does nothing. In the
Editor, every context is also released before scripts reload, as described in
When scripts reload.
To release a context that stays alive, call Manual.Release(context): every member returns to its
default, and the next injection starts over. To release one member only, call
Manual.Release(context, memberName). The rest of the context stays injected.
How long an object Selvage created lasts depends on its lifetime. For more information, refer to Lifetimes.