Your code gives the objects it creates to members in one of two ways: the registry, which every member of the object's type receives, or a local block, which only the objects created inside it receive.

Add an object to the registry

The Registry Provider gives the objects your code adds to it. By default, it's the first provider in the provider list, so what you add wins over every other provider. This is the equivalent of registering an instance in a dependency injection container. To add an object, do one of the following:

  • Add an object you already have. Members of its type receive it, and Selvage never ends it:
RegistryProvider.Listed.Add(profile);             // given as PlayerProfile
RegistryProvider.Listed.Add<IProfile>(profile);   // given as IProfile
  • Add a function that creates the object. Selvage calls it when a member first needs the object, and ends the object once no member holds it, like an object it creates for a [Provide] class. If the function returns null, the next provider is tried:
RegistryProvider.Listed.Add<IAudio>(() => new Audio());
Warning: Selvage ends what a function returns, and ending a component destroys its GameObject. Don't add a function that returns an object that exists elsewhere, such as () => Camera.main: add the object itself, or give it from the Scene Provider.

Members of the declared type T, and of each base class and interface of T, receive the object you add. A member injected before you add the object receives it only if it's Reactive and doesn't hold a dependency from a provider above this registry. Otherwise, call Manual.Reinject. An Async member waits for an object you add later only when you promise its type with WithinSeconds, as described in Require every member to be guaranteed. To add an object before the first scene loads, use [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]. When a Unity object you added is destroyed, Selvage removes it from the registry with a warning, and the next provider is tried.

To give each member its own object, pass a lifetime as the second argument. Selvage then calls the function for each member, or copies the object you added: such an object must be a Unity object or implement ICloneable, or Add throws an exception.

Entries you add in Play mode are removed when you exit Play mode. Entries you add in Edit mode stay until you remove them, and serve EditMode members.

The Validation tab of the Dependencies window shows a member as Guaranteed when the registry holds an object for it, and as May Be Supplied when it holds a function, or nothing yet, because code can add to a registry at any time. To have such members count as Guaranteed, promise their type: refer to Require every member to be guaranteed. When two entries could both be injected into a member and nothing tells them apart, Selvage displays an error that names both.

RegistryProvider.Listed is readable from RuntimeInitializeLoadType.BeforeSceneLoad on, and stays the same object until scripts reload, so you can keep a reference to it.

Remove an object from the registry

To remove an entry, pass Remove the object or the function you added. Clear removes every entry:

RegistryProvider.Listed.Remove(profile);                 // the object passed to Add
RegistryProvider.Listed.Remove<IAudio>(CreateAudio);   // the method passed to Add
RegistryProvider.Listed.Clear();

A function written inline in the Add call can't be passed again: to remove it later, add a method, or keep the delegate you passed. Removing an entry ends the objects waiting in its pool.

After a removal, a Reactive member that holds what the entry gave receives what the provider list gives now, and any other member keeps it. To make every member drop it, such as a connection that closed, add the entry with canRevoke: true, which costs a little at each injection, then remove it with revoked: true. A Reactive member then receives a replacement when one exists, and any other member returns to its default:

RegistryProvider.Listed.Add<IConnection>(connection, canRevoke: true);
RegistryProvider.Listed.Remove(connection, revoked: true);   // every member holding it drops it

If you pass revoked: true for an entry added without canRevoke, Selvage logs a warning and doesn't revoke it: Reactive members receive what the provider list gives now, and other members keep it, as after any removal.

Add a registry of your own

A registry is tried at its place in the provider list. To have the objects you add tried at a place other than the Registry Provider's, perform the following steps:

  1. Declare a registry class.
  2. In the provider list, add the registry where it should be tried.
  3. Add objects to it from code.
[Serializable]
public sealed class Cheats : RegistryProvider<Cheats> { }   // 1. The registry class

Cheats.Listed.Add<IDamage>(new GodMode());                 // 3. Add an object to it

The provider list holds one of each registry class. Listed throws an exception while the registry isn't in the list, with a message that says where to add it.

To use a registry outside the list, such as in a test, create it with new and add it with Injector.AddFirst or Injector.AddLast. Such a registry isn't in the list, so Listed never returns it. For more information, refer to Swap dependencies for tests and platforms.

Pass objects in a local block

A local block passes objects to the objects you create inside it. Open the block with Injector.Local. Everything created inside it, with new or Instantiate, receives the objects you pass, before any provider is tried:

public class Gun : MonoBehaviour
{
    [SerializeField] GameObject bulletPrefab;

    public void Fire(Vector3 direction)
    {
        using (Injector.Local(new BulletShot(direction), this))
            Instantiate(bulletPrefab);
    }
}
public class Bullet : MonoBehaviour
{
    [Inject] BulletShot shot;   // this bullet's direction
    [Inject] Gun gun;           // the gun that fired it
}

The block reaches everything that runs inside it: code started inside it, such as coroutines, await continuations and threads, and the objects those create, such as an effect the bullet instantiates in its Awake. A component instantiated inactive receives the block's objects when it's activated. A callback only registered inside the block, such as a C# event or a UnityEvent, and run later by other code, doesn't receive it. To create an object without the block, create it outside.

An object keeps what it received after the block ends, and receives the same objects again when it's reinjected. An object that existed before the block receives nothing, unless you reinject it inside the block, such as a bullet you take from your own pool:

using (Injector.Local(new BulletShot(direction)))
    Manual.Reinject(pooledBullet);

A Manual.Reinject call inside a block replaces what the object received with the block's objects. An object lent from a pool inside a block receives that block's objects.

Local blocks follow these rules:

  • A block is tried before the provider list. In nested blocks, the inner block wins.
  • An object in a block matches by type only: preferences and channels don't apply to it.
  • Two objects in one block that match the same member are an error, because Selvage can't tell them apart. Pass one, or nest two blocks.
  • A block that isn't ended is ended at the end of the frame, with an error that names the types it gives. A using statement always ends it.
  • If you end a block before a block opened inside it, the inner block stays open, and the objects created afterwards receive only the inner block's objects.
  • The static members of a class never receive a block's objects, even when you reinject them inside a block.
  • Selvage never destroys the objects you pass to a block.

The Validation tab shows a member that only a block gives as May Be Supplied.

Choose the registry or a local block

The registry and a local block differ in which members receive the object:

MethodReceived byUse for
RegistryEvery member of the object's type, until you remove it.An object that many scripts use, such as a save system you load at startup.
Local blockOnly the objects you create inside the block.Data that belongs to one object, such as the direction of a bullet you instantiate.