Overview

Dependency injection is a principle: a class receives the objects it uses instead of creating or finding them. Dependency injection containers come from .NET applications, such as web servers, where the container creates every object of the application through its constructor, from registrations written in code. Most containers for Unity keep that model: a composition root that registers each class, constructor injection, and container scopes.

A Unity project doesn't work that way. Unity creates MonoBehaviours and ScriptableObjects itself, your objects are placed in scenes and asset folders rather than created in code, and their lifetimes follow scenes and Destroy. Selvage keeps the principle and builds the rest around how Unity works.

Scripts that don't reference Selvage

With a container, your code names the container: the composition root registers each class, and a MonoBehaviour carries the container's [Inject] attribute.

With the Inject by Default setting enabled, Selvage injects a script that never mentions it, and no code registers the script:

using UnityEngine;

public class Player : MonoBehaviour
{
    Rigidbody body;
    AudioManager audioManager;
}

The script has no using Selvage, no attribute and no registration. Its fields declare what it needs, and the provider list decides where each one comes from. The same script compiles in a project without Selvage, where you assign its fields yourself.

Selvage injects only a member that holds null, so a field that isn't a dependency, such as a List<int>, only needs a value before Selvage injects it: in its initializer, in the constructor or in Awake. For more information, refer to Inject with scopes.

No constructor injection

In .NET, the container calls every constructor, so the constructor is where dependencies arrive. Unity calls the constructor of a MonoBehaviour or a ScriptableObject itself, with no parameters. Containers for Unity inject those objects through fields or methods instead, and create plain classes through the container or a factory so that their constructors receive something. A project ends up with two ways to receive a dependency, and with plain classes that can't be created with new.

Selvage has one way for every context: members, in a MonoBehaviour, a ScriptableObject, a plain C# class or the static members of a class. new and Instantiate work as usual and inject what they create.

A constructor makes sure an argument is passed, not that the container has one to pass: that's only known once the container is built, at runtime. The Validation tab of the Dependencies window reports a member that no provider can give before you enter Play mode, and a required member left null fails with an error that names it. Selvage injects members at the end of Awake or of the constructor, so you use them from Start or OnEnable on, or once new returns. For more information, refer to Validate members and Injection lifecycle.

No container to build

In .NET, nothing exists until code creates it, so the container has to be told about every class. In Unity, your scenes already hold their components and your folders their assets. Registering them in a container repeats in code, or in references dragged onto an installer, what the project already holds.

Selvage has the provider list instead. Each provider gives dependencies from one source, such as the loaded scenes or the folders that hold a Provide Definition, with no entry per object. Your own classes are provided by [Provide] on the class, and objects your code creates by the registry or a local block. The Dependencies window shows where each member's dependency comes from: Explain lists what each provider did for it. For more information, refer to Validate members.

No service locator

Many containers let any code ask for an object, with a call such as container.Resolve<T>(). That call is a service locator: the dependency is hidden in the code that makes it, which is the problem dependency injection removes.

Selvage has no such call. Every dependency is a declared member, so the Dependencies window validates and inspects all of them. The needs that lead to a service locator in other frameworks are met by members:

NeedMember
A dependency in static codeA static member. Selvage injects the static members of any class. For more information, refer to Contexts.
A dependency used only on a rare code pathA Manual member, injected by Manual.Inject when the path runs.
A dependency chosen from data at runtimeA channel read from a field with [DynamicChannel], then Manual.Reinject when the field changes. For more information, refer to Channels.
An object created without running its constructor, such as by a deserializerIts members, injected by Manual.Inject(this).
Every object of a typeA collection member, such as IEnumerable<T>. For more information, refer to How a member's type is matched.

Choosing among candidates without keys

When several objects fit a member, a container asks for a key, such as a name written both on the registration and on the member. The two must match, and a script copied into another project needs the same keys there.

Selvage chooses with a preference on each candidate, which reads facts your code already holds: the member's name, the class or namespace of the context, the tag or scene of its GameObject. A preference is a hint, never a filter, so a member with one candidate receives it whatever the preference says, and a copied script keeps working. When nothing in your code tells the candidates apart, a channel on the member names the one it wants. For more information, refer to Choose between several candidates.

Lifetimes without container scopes

In .NET, a container scope matches a unit of work, such as a web request, and a singleton lives as long as the application. Containers for Unity map scopes onto scenes and prefabs, through a hierarchy of containers you declare.

Unity objects already have lifetimes, so Selvage declares no container scopes. An object Selvage creates lives while a member holds it, and the Scene Provider gives the component closest to the member, so what a scene or a prefab instance shares follows from where objects are and which members hold them. For the equivalent of each container scope, refer to Container scopes. For more information, refer to Lifetimes.

Code added at compile time

In .NET, the container creates every object, so it can inject each one through reflection as it creates it. In Unity, objects come from new, Instantiate and scene loads that a container never sees, and IL2CPP strips the members that only reflection reaches.

Selvage adds code at compile time: when Unity compiles your scripts, an IL post-processor adds a call that injects each object at the end of its Awake, OnEnable or constructor, and assigns its members directly, without reflection. Every object is injected however it's created, and IL2CPP builds need no link.xml entry for your scripts. Selvage doesn't process a type from a precompiled DLL: Manual.Inject injects it. For more information, refer to What does Selvage add to my code?

Names

Container names come from .NET, and several of them mean something else to a Unity user, or describe something Selvage doesn't have. Selvage uses a C# or Unity word wherever one fits:

Container wordSelvage wordWhy
ServiceDependencyA Rigidbody, a Camera or a settings asset isn't a service. Dependency names whatever a member holds.
Container, installer, bindingProvider, the provider listNothing is registered per class. Providers give dependencies from their sources, in the order of the provider list.
ResolveInjectResolve<T>() is a service locator call. Selvage only injects members.
Singleton, transientPermanent, Shared, Separate, PooledTo a Unity user, a singleton is a static Instance a class keeps for itself. A lifetime says what members receive and how long Selvage keeps it.
Lifetime scopeLifetimeSelvage has no lifetime scopes. In Selvage, a scope is where [Inject] applies: a class, an assembly or the project.
Key, identifier, qualifierPreference, channelA key must match on both sides. A preference and a channel are hints, never filters.
Context (a container of a scene or a GameObject)Context (the object whose members are injected)Object already means UnityEngine.Object, so Selvage needs another word for the object it injects.
Injection point, siteMemberMember is the C# word for a field or a property.

What Selvage leaves to Unity

Some containers also call plain C# classes each frame, order the initialization of objects, or carry an event bus. Selvage injects dependencies and nothing else. MonoBehaviours and the PlayerLoop already run code each frame, and to start once another object has its dependencies, you wait until that context is ready. For more information, refer to Wait until a context is ready.