Zenject Documentation

Zenject provides a comprehensive suite of dependency injection features:

• Injection Types: Supports Constructor, Field, Property, and Method injection for both normal C# classes and MonoBehaviours.
• Binding Capabilities: Conditional binding (by type, name, etc.), optional dependencies, convention-based binding, and decorator pattern support.
• Container Management: Supports Nested Containers (Sub-Containers), global project-wide bindings, and injection across different Unity scenes.
• Object Lifecycle & Creation: Factories for post-initialization object creation, built-in memory pools, and LazyInject<> for just-in-time injection.
• Unity Integration: Automatic injection via ZenjectBinding components, ZenAutoInjecter for game objects, and scene parenting.
• Testing & Validation: Object graph validation at editor time, auto-mocking with Moq, and built-in support for unit, integration, and scene tests.
• Performance: Support for multiple threads for resolving/instantiating and 'reflection baking' to eliminate reflection overhead by modifying generated assemblies.

Derive from ScriptableObjectInstaller instead of MonoInstaller to create installers that persist changes made in the Unity Inspector during Play Mode. This is ideal for tweaking runtime parameters like game settings.

Warning: Changes made to these settings via code will also be saved persistently. Treat settings objects as read-only in code to avoid unintended permanent changes.

public class GameSettings : ScriptableObjectInstaller
{
    public Player.Settings Player;
    public SomethingElse.Settings SomethingElse;

    public override void InstallBindings()
    {
        Container.BindInstances(Player, SomethingElse);
    }
}

public class Player : ITickable
{
    readonly Settings _settings;
    public Player(Settings settings) => _settings = settings;

    public void Tick()
    {
        // Use _settings.Speed etc.
    }

    [Serializable]
    public class Settings
    {
        public float Speed;
    }
}

When using ByInstaller or ByMethod to create subcontainers, lifecycle interfaces like IInitializable, ITickable, and IDisposable are not automatically forwarded to the subcontainer by default. To ensure these events are triggered, you have two primary options:

1. Derive the Facade from Kernel: Make your facade class inherit from Kernel and use BindInterfacesAndSelfTo<T>() in the parent container. This allows the parent container to forward lifecycle calls to the subcontainer.
2. Use .WithKernel(): Add the .WithKernel() method to your binding statement. This automatically handles the forwarding of lifecycle events without requiring your facade class to inherit from Kernel.

Note that for dynamically created subcontainers (e.g., via a BindFactory), you must explicitly call the lifecycle methods (like _greeter.Initialize()) on the created instance if you are not using a Kernel-based approach.

// Option 1: Using WithKernel() to enable lifecycle events
public class Greeter
{
    public Greeter()
    {
        Debug.Log("Created Greeter");
    }
}

public class TestInstaller : MonoInstaller
{
    public override void InstallBindings()
    {
        Container.Bind<Greeter>()
            .FromSubContainerResolve()
            .ByMethod(InstallGreeter)
            .WithKernel() // This enables IInitializable, ITickable, and IDisposable
            .AsSingle();
    }

    void InstallGreeter(DiContainer subContainer)
    {
        subContainer.Bind<Greeter>().AsSingle();
        subContainer.BindInterfacesTo<GoodbyeHandler>().AsSingle();
        subContainer.BindInterfacesTo<HelloHandler>().AsSingle();
    }
}

Scene Decorators allow you to add behavior to a scene without modifying its original installers. Unlike scene parenting, all scenes in a decorator setup share the same Container, meaning they can access each other's bindings.

To set up a Scene Decorator:

1. Open your main production scene.
2. In the Scene Hierarchy, right-click the menu beside the scene name and select Add New Scene.
3. Drag the new scene so it is positioned above the main scene.
4. Right-click inside the new scene and select Zenject -> Decorator Context.
5. On the SceneDecoratorContext component, set the Decorated Contract Name to match the contract name used in the main scene's SceneContext.
6. Create a MonoInstaller script to define the new behaviors.
7. Add a GameObject to your decorator scene with this installer and drag it into the Installers property of the SceneDecoratorContext.

Important Notes:

• Decorator scenes must be loaded before the scenes they decorate.
• Use the Validate command (CTRL+ALT+V) to verify multi-scene setups.

public class ExampleDecoratorInstaller : MonoInstaller
{
    public override void InstallBindings()
    {
        Container.Bind<ITickable>().To<TestHotKeysAdder>().AsSingle();
    }
}

public class TestHotKeysAdder : ITickable
{
    public void Tick()
    {
        if (Input.GetKeyDown(KeyCode.Space))
        {
            Debug.Log("Hotkey triggered!");
        }
    }
}

Integration tests run in a PlayMode environment involving SceneContext and ProjectContext. They execute bindings for IInitializable, ITickable, and IDisposable just like a normal game run.

To set them up:

1. Open Unity's Test Runner and go to the PlayMode tab.
2. Click "Create PlayMode Test Assembly Folder".
3. Add a reference to Zenject-TestFramework to the new .asmdef file.
4. Right-click in the folder and select Create -> Zenject -> Integration Test.
5. Inherit from ZenjectIntegrationTestFixture.

Integration tests follow a three-phase lifecycle:

• Before PreInstall(): Set up the initial scene (load prefabs, create GameObjects).
• After PreInstall(): Call Container.Bind methods to configure the container.
• After PostInstall(): All non-lazy objects are instantiated, injected, and IInitializable.Initialize has been called.

Note: You must yield return null immediately after PostInstall() if you want MonoBehaviour.Start() methods to run.

public class SpaceShipTests : ZenjectIntegrationTestFixture
{
    [UnityTest]
    public IEnumerator TestVelocity()
    {
        PreInstall();

        Container.Bind<SpaceShip>().FromNewComponentOnNewGameObject()
            .AsSingle().WithArguments(new Vector3(1, 0, 0));

        PostInstall();

        var spaceShip = Container.Resolve<SpaceShip>();
        Assert.IsEqual(spaceShip.transform.position, Vector3.zero);

        yield return null; // Wait for Update/Start

        Assert.That(spaceShip.transform.position.x > 0);
    }
}