Provide objects your code creates
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 returnsnull, the next provider is tried:
RegistryProvider.Listed.Add<IAudio>(() => new Audio());
() => 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:
- Declare a registry class.
- In the provider list, add the registry where it should be tried.
- 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
usingstatement 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:
| Method | Received by | Use for |
|---|---|---|
| Registry | Every 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 block | Only the objects you create inside the block. | Data that belongs to one object, such as the direction of a bullet you instantiate. |