VContainer Documentation

When using VContainer, it is helpful to understand the following core concepts:

• DI Container: A central registry that holds all dependent references and performs auto-wiring.
• Composition Root: The specific location in your application where you configure and resolve dependencies.
• Auto-wiring: The process of automatically managing and injecting services into classes with minimal manual configuration.
• IoC (Inversion of Control): A design principle where the control flow responsibility is shifted to an entry point, allowing for better separation of concerns.

VContainer provides three primary lifetime modes for registered objects:

• Singleton: A single instance is shared across all containers. Note that the same type cannot be registered multiple times within the same container.
• Transient: A new instance is created every time the object is resolved.
• Scoped: An instance is tied to a specific LifetimeScope.
  • If the LifetimeScope is a singleton, it behaves similarly to a Singleton.
  • If you create child LifetimeScope instances, each child receives its own unique instance.
  • When a LifetimeScope is destroyed, all registered objects implementing IDisposable have their Dispose() method called.

Generate static content into the build directory. The resulting files can be served using any static content hosting service.

$ yarn build

To optimize container build performance when registering a large number of objects, you can enable parallel container builds by setting the VCONTAINER_PARALLEL_CONTAINER_BUILD compilation flag.

Warning: Enabling this flag may result in slower build times if you have only a few objects to register. Use this primarily for large-scale registrations.

To install VContainer using Unity's Package Manager, add the following line to the dependencies section of your project's Packages/manifest.json file.

"jp.hadashikick.vcontainer": "https://github.com/hadashiA/VContainer.git?path=VContainer/Assets/VContainer#1.19.0"

To integrate VContainer, follow these steps:

1. Create a LifetimeScope: Create a class that inherits from LifetimeScope. This acts as your composition root where you register dependencies.
2. Register Dependencies: Override the Configure method in your LifetimeScope subclass and use the IContainerBuilder to register your classes.
3. Attach to GameObject: Create an empty GameObject in your Unity scene and attach your LifetimeScope component to it. VContainer will automatically build the container and dispatch to the PlayerLoopSystem when the scene plays.

public class GameLifetimeScope : LifetimeScope
{
    protected override void Configure(IContainerBuilder builder)
    {
        builder.Register<HelloWorldService>(Lifetime.Singleton);
    }
}

You can use LifetimeScope.Enqueue to register specific instances that will be available to the next scene that is loaded. This is useful for passing data or services across scene boundaries during a loading process.

// LifetimeScopes generated during this block will be additionally Registered.
using (LifetimeScope.Enqueue(builder =>
{
    // Register for the next scene not yet loaded
    builder.RegisterInstance(extraInstance);
}))
{
    // Loading the scene..
}

When loading scenes additively, you can use LifetimeScope.EnqueueParent to ensure that any LifetimeScope generated within that block is parented to a specific scope.

class SceneLoader
{
    readonly LifetimeScope currentScope;

    public SceneLoader(LifetimeScope currentScope)
    {
        this.currentScope = currentScope;
    }

    IEnumerator LoadSceneAsync()
    {
        // LifetimeScope generated in this block will be parented by `this.currentScope`
        using (LifetimeScope.EnqueueParent(currentScope))
        {
            var loading = SceneManager.LoadSceneAsync("...", LoadSceneMode.Additive);
            while (!loading.isDone)
            {
                yield return null;
            }
        }
    }
}

VContainer is available on the OpenUPM registry. It is recommended to use the openupm-cli to install it.

openupm add jp.hadashikick.vcontainer

To deploy the website using SSH, set the USE_SSH environment variable to true before running the deploy command.

$ USE_SSH=true yarn deploy