🚀 Lesson 1.5: Mini-Project — A Game Bootstrapper with a Service Container

Why a Bootstrapper?

Without a bootstrapper, initialization scatters. Each system wakes up in its own Awake/Start, in an order Unity decides (and you fight with the Script Execution Order settings), each grabbing its own dependencies via singletons. Load order bugs, "the save system wasn't ready yet" null references, and half-initialized state follow.

A bootstrapper fixes this by making startup explicit and ordered. One object, running first in a dedicated scene, does the whole dance: create the services, initialize them in the sequence they depend on, and hand control to the game only when everything is ready. It's the runtime embodiment of the composition root from Lesson 1.2 — the single place that knows concrete types and wires the object graph.

The Boot Sequence at a Glance

Before the code, the shape of what we're building. The bootstrapper walks left to right: assemble the container, register services behind interfaces, initialize them asynchronously in order, then load the main scene.

Step 1: The Container & Interfaces

Start with the container. This is the Lesson 1.2 container, trimmed to what the bootstrapper needs — register a shared instance, resolve it later.

using System;
using System.Collections.Generic;

namespace Studio.Core
{
    public class ServiceContainer
    {
        private readonly Dictionary<Type, object> _services = new();

        public void Register<TInterface>(TInterface instance)
            => _services[typeof(TInterface)] = instance;

        public TInterface Resolve<TInterface>()
        {
            if (_services.TryGetValue(typeof(TInterface), out var s))
                return (TInterface)s;
            throw new InvalidOperationException(
                $"No service registered for {typeof(TInterface).Name}");
        }
    }
}

Now the three service contracts. Each has an async InitializeAsync so startup work (loading an audio bank, reading a save file, binding input) can happen without blocking, and takes a CancellationToken so a cancelled boot unwinds cleanly.

using System.Threading;
using UnityEngine;

namespace Studio.Core
{
    public interface IGameService
    {
        Awaitable InitializeAsync(CancellationToken token);
    }

    public interface IAudioService : IGameService
    {
        void Play(string clipId);
        void SetVolume(float volume);
    }

    public interface ISaveService : IGameService
    {
        void Save(string key, string value);
        string Load(string key);
    }

    public interface IInputService : IGameService
    {
        Vector2 MoveAxis { get; }
        bool JumpPressed { get; }
    }
}

A shared IGameService base gives every service the same InitializeAsync shape, which lets the bootstrapper treat them uniformly. All of this lives in Studio.Core — the bottom assembly from Lesson 1.1 that everything else depends down on.

Step 2: The Service Implementations

Now concrete implementations. They're deliberately simple — the point is the shape, especially how each InitializeAsync does real async work and honors the token. Note the audio and save services do a brief background hop or frame-yield to model genuine startup latency.

using System.Threading;
using UnityEngine;
using Studio.Core;

namespace Studio.Services
{
    public class AudioService : IAudioService
    {
        public async Awaitable InitializeAsync(CancellationToken token)
        {
            // Simulate loading an audio bank off the main thread.
            await Awaitable.BackgroundThreadAsync();
            System.Threading.Thread.Sleep(50);      // stand-in for real I/O
            await Awaitable.MainThreadAsync();
            token.ThrowIfCancellationRequested();
            Debug.Log("[Audio] ready");
        }

        public void Play(string clipId) => Debug.Log($"[Audio] play {clipId}");
        public void SetVolume(float volume) { /* set mixer volume */ }
    }

    public class FileSaveService : ISaveService
    {
        public async Awaitable InitializeAsync(CancellationToken token)
        {
            // Simulate reading a save file across a couple of frames.
            await Awaitable.NextFrameAsync(token);
            await Awaitable.NextFrameAsync(token);
            Debug.Log("[Save] ready");
        }

        public void Save(string key, string value)
            => PlayerPrefs.SetString(key, value);
        public string Load(string key)
            => PlayerPrefs.GetString(key, string.Empty);
    }

    public class InputService : IInputService
    {
        public Vector2 MoveAxis { get; private set; }
        public bool JumpPressed { get; private set; }

        public async Awaitable InitializeAsync(CancellationToken token)
        {
            // Enable the Input System action maps here, then yield once.
            await Awaitable.NextFrameAsync(token);
            Debug.Log("[Input] ready");
        }
    }
}

These sit in a Studio.Services assembly that references Studio.Core — services depend down on the interfaces, exactly the dependency direction from Lesson 1.1.

💡 Order matters, and it's explicit. Because each InitializeAsync is awaited one after another, save can safely assume audio is up, and input can assume both are. If save depended on audio's mixer being ready, this ordering guarantees it. Ordering initialization is one of the main reasons a bootstrapper exists.

Step 3: The Bootstrapper

The centerpiece. It's a MonoBehaviour in the init scene that creates the container, registers the services, initializes them in order with Awaitable, exposes the container to the rest of the game, and loads the main scene. It also survives the load (DontDestroyOnLoad) and threads the destroy token through every await.

using System.Threading;
using UnityEngine;
using UnityEngine.SceneManagement;
using Studio.Core;
using Studio.Services;

namespace Studio.Boot
{
    public class Bootstrapper : MonoBehaviour
    {
        [SerializeField] private string _mainSceneName = "Main";

        // The composed container, made available to the rest of the game.
        public static ServiceContainer Services { get; private set; }

        async void Awake()
        {
            // This object (and its services) must survive the scene load.
            DontDestroyOnLoad(gameObject);

            try
            {
                await BootAsync(destroyCancellationToken);
            }
            catch (System.OperationCanceledException)
            {
                // Expected if the app quits mid-boot — swallow quietly.
            }
            catch (System.Exception e)
            {
                Debug.LogException(e);   // surface real boot failures
            }
        }

        private async Awaitable BootAsync(CancellationToken token)
        {
            var container = new ServiceContainer();

            // 1) Create the concrete services.
            var audio = new AudioService();
            var save  = new FileSaveService();
            var input = new InputService();

            // 2) Register each behind its interface.
            container.Register<IAudioService>(audio);
            container.Register<ISaveService>(save);
            container.Register<IInputService>(input);

            // 3) Initialize IN ORDER — each finishes before the next starts.
            await audio.InitializeAsync(token);
            await save.InitializeAsync(token);
            await input.InitializeAsync(token);

            // 4) Publish the container, then hand off to the game.
            Services = container;
            Debug.Log("[Boot] all services ready → loading main scene");

            await SceneManager.LoadSceneAsync(_mainSceneName);
        }
    }
}

Read the four numbered blocks against Figure 1 — they're the same four stages. Everything downstream now reaches its dependencies through Bootstrapper.Services.Resolve<T>(), or (better) gets them injected by a scene-level installer that reads from that container. A gameplay object, for instance:

using UnityEngine;
using Studio.Core;
using Studio.Boot;

public class Player : MonoBehaviour
{
    private IAudioService _audio;

    void Start()
    {
        // Pull the ready-made service the bootstrapper composed.
        _audio = Bootstrapper.Services.Resolve<IAudioService>();
    }

    void Footstep() => _audio.Play("footstep");
}

Step 4: Scenes & Running It

Wire it up in the editor:

1. Create two scenes: Boot (nearly empty) and Main (your gameplay scene).
2. In Boot, add an empty GameObject named Bootstrapper and attach the Bootstrapper component. Set Main Scene Name to Main.
3. Open File ▸ Build Settings and add both scenes. Drag Boot to the top so it loads first (index 0). Add Main below it.
4. Put the scripts in their assemblies: container and interfaces in Studio.Core, implementations in Studio.Services, the bootstrapper in Studio.Boot (referencing both). This is the Lesson 1.1 layout in miniature.
5. Press Play from the Boot scene. Watch the Console: [Audio] ready → [Save] ready → [Input] ready → [Boot] all services ready, then the Main scene loads.

The ordered log is the proof: services come up one at a time, in the sequence you declared, and the game only starts once they're all ready. Stop Play mid-boot and the OperationCanceledException path unwinds it cleanly instead of resuming into a torn-down app.

What You Built & How to Extend It

You assembled every Module 1 idea into one artifact: a bootstrapper that is a composition root (1.2), lives in layered assemblies (1.1), initializes services with Awaitable and a cancellation token (1.3), and is the seed for patterns like an event bus (1.4). The services are swappable behind interfaces, the startup order is explicit, and gameplay code stays ignorant of concrete types.

Ways to grow it

• A loading screen with progress. Have BootAsync report progress (e.g. an IProgress<float> or an event per service) and drive a progress bar in the Boot scene — trivial now that init is sequential and awaited.
• Parallel where safe. Services with no interdependency can init concurrently: await Awaitable.WhenAll(...)-style patterns (or await several started operations together) shorten boot time while keeping the ordered ones ordered.
• Adopt a real DI framework. Swap the hand-rolled container for VContainer: register in a LifetimeScope, let it auto-inject into MonoBehaviours, and the bootstrapper shrinks. The concepts map one-to-one.
• Event-driven readiness. Publish a ServicesReady event on the bus from Lesson 1.4 so any system can react to boot completion without the bootstrapper knowing about it.
• Graceful failure. If a service's InitializeAsync throws (corrupt save, missing audio bank), catch it per-service and fall back to a safe default rather than aborting the whole boot.

🎓 Module 1, complete. You can now structure a large project, wire it with dependency injection, control time with async/await, apply scaling patterns, and stand it all up from a clean bootstrapper. That's the architectural foundation the rest of Unity Advanced builds performance, rendering, netcode, and tooling on top of.

Hands-on Challenge

Summary

🚀 What's Next?

Module 1 gave you an architecture that scales. Now we make sure it's fast. Module 2 opens the performance track: in Lesson 2.1: The Profiler in Depth, you'll learn to measure before you optimize — reading the Profiler window frame by frame to find where time actually goes, so every optimization that follows is aimed at a real bottleneck.