DEV Community: Clément L.

Unity game architecture Part 2

Clément L. — Fri, 13 Oct 2023 16:09:23 +0000

More DI, FSM entry points and MessagePipe

Adding Messages to the Pipe
GameEntryPoint as a Finite State Machine
MessagePipe in action
- Pub / Sub
- The Mediator Pattern
Conclusion

This is part 2 of a series of articles about game architecture in Unity.

If you haven't read part 1 yet, you can find it here.

As I was thinking about the next part of this series, I realized that having access to the full source code of the project would be a great way to illustrate the concepts I'm talking about...
I cannot just share Bill's source code, so I decided to create a new project, with a similar architecture, but with a different game : Flare Survivors so you can follow along and see the code in action here : clandais/flare-survivors.

Adding Messages to the Pipe

I was looking for a way to keep things decoupled and stumbled upon Cysharp/MessagePipe.

It was perfect as it was designed to be used with Dependency Injection and it was also compatible with VContainer and built on top of UniTask.
MessagePipe promotes itself as a "high performance in-memory messaging pipeline for .NET and Unity".

It also comes with a diagnostics window to keep track of who is subscribing to what !

The integration of MessagePipe was pretty easy. It needs to be registered, in my case, in GameLifetimeScope.

public class GameLifetimeScope : LifetimeScope
{        
    protected override void Configure(IContainerBuilder builder)
    {
        RegisterMessagePipe(builder);
        /* ... */
        builder.RegisterEntryPoint<GameEntryPoint>();
    }

    private void RegisterMessagePipe(IContainerBuilder builder)
    {
        // Register MessagePipe
        MessagePipeOptions options = builder.RegisterMessagePipe(
            options =>
            {
                // Enable capture stack trace for diagnostics window
                options.EnableCaptureStackTrace = true;
            });
        // Setup GlobalMessagePipe to enable diagnostics window and global function
        builder.RegisterBuildCallback(
            c => GlobalMessagePipe.SetProvider(c.AsServiceProvider()));
        /* ... */
    }
}

GameEntryPoint as a Finite State Machine

I wanted the GameEntryPoint to handle the game state and that each game state handled its own logic.
On entering a new state, the previous one cleans its garbage and the new one initializes itself and loads its stuff.

In order to keep it simple for now, I went with a simple Finite State Machine.

/// <summary>
///   Base class for all states.
/// </summary>
public abstract class BaseState : IDisposable
{
    public abstract void Enter();
    public abstract void Tick();
    public abstract void Exit();
    public abstract void Dispose();
}

/// <summary>
///  Base class for all game states.
/// </summary>
public abstract class BaseGameState : BaseState
{
    [Inject] protected IObjectResolver Resolver;
    [Inject] protected SceneReferences SceneReferences;
    [Inject] protected IAsyncRequestHandler<LoadSceneRequest, LoadSceneResponse> LoadSceneRequestHandler;
    [Inject] protected CoroutineRunner CoroutineRunner;

    public override void Dispose()
    {
        Resolver?.Dispose();
    }
}

The GameEntryPoint is responsible for handling the current state and switching to a new one.

public class GameEntryPoint : 
        IStartable,
        ITickable,
        IDisposable
{

    // Inject the IObjectResolver to "find" the states
    [Inject] private IObjectResolver _resolver;
    // Inject the ISubscriber to listen to GameStateTransitionMessage
    [Inject] private ISubscriber<GameStateTransitionMessage> _gameStateTransitionSubscriber;

    // Here goes the garbage
    private IDisposable _disposable;
    // The current state (obviously)
    private BaseGameState _currentState;

    public void Start()
    {
        SetupSubscriber();
        // Resolve the first state   
        _currentState = _resolver.Resolve<GameBootState>();
        _currentState.Enter();
    }

    public void Tick()
    {
        // Tick the current state
        _currentState.Tick();
    }

    // When a GameStateTransitionMessage is received, we exit the current state and enter the new one
    private void OnGameStateTransition(GameStateTransitionMessage msg)
    {
        _currentState.Exit();
        _currentState = msg.GameState;
        _currentState.Enter();
    }

    // Setup the subscriber to listen to GameStateTransitionMessage
    private void SetupSubscriber()
    {
        DisposableBagBuilder disposableBag = DisposableBag.CreateBuilder();
        _gameStateTransitionSubscriber
            .Subscribe(OnGameStateTransition)
            .AddTo(disposableBag);
        _disposable = disposableBag.Build();
    }

    // Clean the mess
    public void Dispose()
    {
        _resolver?.Dispose();
        _disposable?.Dispose();
    }
}

Here is an example of a state, the GameBootState.

public class GameBootState : BaseGameState
{
    // Trying to use addressables
    private AsyncOperationHandle<SceneInstance> _gameBootSceneHandle;

    public override async void Enter()
    {
        LoadSceneResponse response = await LoadSceneRequestHandler.InvokeAsync(new LoadSceneRequest
        {
            SceneReference = SceneReferences.MainMenuScene,
        });

        // Poor error handling
        if (!response.IsSuccess)
        {
            Debug.LogError("GameBootState failed to load GameScene.");
            return;
        }

        _gameBootSceneHandle = response.Handle;
        await _gameBootSceneHandle.Result.ActivateAsync();
    }

    public override void Tick() { }

    public override async void Exit()
    {
        await Addressables.UnloadSceneAsync(_gameBootSceneHandle).ToUniTask(CoroutineRunner);
    }
}

MessagePipe in action

Pub / Sub

So, how does it work ?

In the above code sample, where do the LoadSceneRequest, LoadSceneResponse and GameStateTransitionMessage come from ?
It starts with creating messages for some data-sharing. Messages can be simple structs.

public struct GameStateTransitionMessage
{
    public BaseGameState GameState { get; set; }
}

To be able to Inject the ISubscriber<GameStateTransitionMessage> and IPublisher<GameStateTransitionMessage>, we need to register them in the GameLifetimeScope.

private void RegisterMessagePipe(IContainerBuilder builder)
{
    /*
        Register MessagePipe
    */

    // ISubscriber and IPublisher are registered using RegisterMessageBroker
    builder.RegisterMessageBroker<GameStateTransitionMessage>(options);
}

I chose to make child lifetimeScopes Publish the GameStateTransitionMessage when they are done with their job.
Here is an example with the MainMenuEntryPoint (which "lives" in a child lifetimeScope: MainMenuLifetimeScope).

public class MainMenuEntryPoint : IStartable, IDisposable
{
    [Inject] private MainMenuView _mainMenuView;
    [Inject] private IPublisher<GameStateTransitionMessage> _gameStateTransitionPublisher;
    [Inject] private IObjectResolver _resolver;

    public void Start()
    {
        _mainMenuView.PlayButton.onClick.AddListener(OnPlayButtonClicked);
    }

    private void OnPlayButtonClicked()
    {
        _gameStateTransitionPublisher.Publish(new GameStateTransitionMessage()
        {
            GameState = _resolver.Resolve<GamePlayState>(),
        }); 
    }

    public void Dispose()
    {
        _mainMenuView.PlayButton.onClick.RemoveListener(OnPlayButtonClicked);
        _resolver?.Dispose();
    }
}

That's a pretty bare main menu, but you get the idea.

When the PlayButton is clicked, the MainMenuEntryPoint publishes a GameStateTransitionMessage with the GamePlayState as the new state.
The GameEntryPoint is listening to GameStateTransitionMessage and will switch to the GamePlayState when it receives it.

The Mediator Pattern

The AsyncRequestHandler<LoadSceneRequest, LoadSceneResponse> works in a sligthly different way. It is a pattern called the "Mediator Pattern".

LoadSceneRequest and LoadSceneResponse are simple structs, too.

public struct LoadSceneRequest
{
    public SceneReference SceneReference { get; set; }
}

public struct LoadSceneResponse
{
    public bool IsSuccess { get; set; }
    // Using addressables, we need to keep track of the handle
    public AsyncOperationHandle<SceneInstance> Handle { get; set; }
}

Then, we need to create a handler for the request.


public class SceneAssetAsyncLoadingHandler 
    : IAsyncRequestHandler<LoadSceneRequest, LoadSceneResponse>
{
    // Extending the IAsyncRequestHandler interface
    public async UniTask<LoadSceneResponse> InvokeAsync(LoadSceneRequest request, CancellationToken cancellationToken = new CancellationToken())
    {
        // load the scene
        // get back the handle
        // omit error handling :D
        return new LoadSceneResponse
        {
            IsSuccess = true,
            Handle = handle,
        };

    }
}

Finally, we need to register the handler in the GameLifetimeScope.

// registration in GameLifetimeScope
private void RegisterMessagePipe(IContainerBuilder builder)
{
    /*** Register MessagePipe ***/
    // Register the AsyncRequestHandler
    builder
        .RegisterAsyncRequestHandler<
            LoadSceneRequest,
            LoadSceneResponse,
            SceneAssetAsyncLoadingHandler>(options);
}

Conclusion

I hope I haven't bored you to death with this article. It was a bit heavy on code, but I think it was necessary to illustrate the concepts I wanted to talk about.

Next time, if there is a next time, I'd like to take a break from architecture and talk about something else. Maybe the AssetPostprocessor ?

Unity game architecture Part 1

Clément L. — Mon, 25 Sep 2023 11:08:34 +0000

DI, Entry Point(s), MV(C,P,CS)

As your Unity game scales, you may find yourself struggling with spaghetti code or situations where it becomes harder and harder to debug. I’d like to share here some tips and practices that helped me while working on Bill . This first draft was greatly inspired by an article written by Rubén Torres Bonet at The GameDev Guru and by my own reflections while trying to be a better game craftsman.

Let’s sum up what Rubén said.

1. Dependency Injection

If you are not sure what is “dependency injection” or “DI” for short, I’ll let you read the Wikipedia article about it…

I’m kidding. Simply put:

It allows to write less code (less code, less bugs).
if following the “SRP” (Single Responsibility Principle), you should know that your classes are supposed to be responsible to do their small chunk of tasks. These tasks should not include fetching their dependencies.

With great power comes great responsibility

DI is a very powerful pattern. To avoid using it badly and end up with more spaghettis, try to keep in mind the SRP.

As of 2023, lots of DI frameworks are available for Unity. I picked VContainer as it is still actively maintained and “promotes” itself as 5 to 10 times faster than Zenject. Plus, it integrates really well with popular libraries like UniRx or UniTask.

2. A single entry point

I should mention the single entry point now because it pairs really well with DI.

The entry point should “simply” bootstrap the game:

Load services (ads, audio, save system, etc…).
Build the dependency graph.
Load the game.
It could conditionally load some “debug overlay” scene in dev mode.

3. Additive scene loading

Rubén already wrote some good points about additive scene loading and the performances issues with prefabs. Personally, I found it easier and cleaner to increment this way.

Getting started and refactoring Bill

I’d like to fix some “mistakes” I’ve made while working on Bill. As progress was made through the development of the game, my skills as a programmer progressed too. I realized that some choices I’ve made were hard to maintain, then tried another solution to solve this problem… while not being 100% convinced, thus, not applying these solutions to what was already coded… And switching again.

I have created an “experimental” branch to apply these patterns and will give here some things I’ve learnt on the way to achieving Clean(er) Code.

First, I have created a temporary Scene just to create a prefab. This prefab is one Game Object with one script. I then created a VContainer Settings asset and set its Root Lifetime Scope field to this prefab.

[AddComponentMenu("Bill/Containers/Game Lifetime Scope")]
    [DefaultExecutionOrder(-100)]
    public class GameLifetimeScope : LifetimeScope
    {
        [SerializeField] private BillSceneReferences sceneReferences;

        protected override void Configure(IContainerBuilder builder)
        {
            builder.RegisterInstance(sceneReferences);
            builder.Register<ISaveSystemService, SaveSystemService>(Lifetime.Singleton);
            builder.Register<ISceneLoaderService, SceneLoaderService>(Lifetime.Singleton);
            builder.Register<CommandFactory>(Lifetime.Singleton);
            builder.RegisterEntryPoint<GameEntryPoint>();
        }
    }

The script in question is pretty simple. It is some kind of “pre-entry-point”. It needs a ScriptableObject (BillSceneReferences) which holds, you guessed it, references to game scenes assets (thanks to Eflatun.Scenereference). It then registers the first needed dependencies: scene references, the Command Factory (well, actually a Pooled Command Factory, coming to this later) as a Singleton and the game’s Entry Point.

Here is the bare GameEntryPoint class:

public class GameEntryPoint : IAsyncStartable
{
    [Inject] private CommandFactory commandFactory;
    [Inject] private BillSceneReferences sceneReferences;

    public async UniTask StartAsync(CancellationToken cancellation)
    {
        await UniTask.Create(() => UniTask.WaitForSeconds(.1f, cancellationToken: cancellation));
    }
}

The [Inject] attribute kind of magically sets these fields as long as they were registered in the GameLifetimeScope. VContainer provides an IAsyncStartable interface which, in this case, is pretty handy for loading scenes.
This class, at this point, does not do anything. 😄

Next is the main menu setup. It is a pretty simple scene.

Francesco is a fantastic artist ! (@francescocrisci.art)

Top to bottom:

Main Menu Scope holds a script that registers dependencies for this specific scene. It is a child scope of GameLifetimeScope.
Main Menu View : Here comes the MVP pattern.
And then, the usual UI stuff.

Here is the Main Menu Scope Game Object. It is a child scope of GameLiftimeScope.

And the Main Menu View that holds references to the two main menu Buttons.

Some code:

[AddComponentMenu("Bill/Containers/Main Menu Lifetime Scope")]
public class MainMenuLifetime : LifetimeScope
{
    [SerializeField] private MainMenuView mainMenuView;

    protected override void Configure(IContainerBuilder builder)
    {
        builder.RegisterEntryPoint<MainMenuPresenter>(Lifetime.Scoped);
        builder.Register<IMainMenuService, MainMenuService>(Lifetime.Scoped);
        builder.RegisterComponent(mainMenuView);
    }
}

LifetimeScope extends MonoBehaviour so it needs to be attached to a game object. There are other ways to create child scopes dynamically though. In this case, the main menu, it needs a reference to the MainMenuView to inject it into plain C# classes.

[AddComponentMenu("Bill/Components/Main Menu View")]
public class MainMenuView : MonoBehaviour
{
    [SerializeField] private Button startButton;
    [SerializeField] private Button quitButton;
        [SerializeField] private Button loadButton;

    public Button StartButton => startButton;
    public Button QuitButton => quitButton;
        public Button LoadButton => loadButton;
}

The MainMenuView. KISS (Keep It Simple, Stupid) view (just before overengineering the behavior 😀)

[UsedImplicitly]
public class MainMenuPresenter : IStartable, IDisposable
{
    private readonly CompositeDisposable disposables = new CompositeDisposable();

    private readonly MainMenuView mainMenuView;
    private readonly IMainMenuService mainMenuService;
    private readonly ISaveSystemService saveSystemService;

    public MainMenuPresenter(MainMenuView mainMenuView, IMainMenuService mainMenuService, ISaveSystemService saveSystemService)
    {
        this.mainMenuView = mainMenuView;
        this.mainMenuService = mainMenuService;
        this.saveSystemService = saveSystemService;
    }

    public void Start()
    {
        mainMenuView.StartButton.OnClickAsObservable()
            .Subscribe(_ => mainMenuService.OnPlayButtonClicked())
            .AddTo(disposables);

        mainMenuView.QuitButton.OnClickAsObservable()
            .Subscribe(_ => mainMenuService.OnQuitButtonClicked())
            .AddTo(disposables);

        mainMenuView.LoadButton.OnClickAsObservable()
            .Subscribe(_ => mainMenuService.OnLoadButtonClicked())
            .AddTo(disposables);

        saveSystemService.HasSaveData().SubscribeToInteractable(mainMenuView.LoadButton)
            .AddTo(disposables);
    }

    public void Dispose()
    {
        disposables.Dispose();
    }
}

Here we go. The MainMenuPresenter is registered as an Entry Point. Implementing the IStartable interface will make it Start like a Monobehaviour. Dependencies are injected via Constructor Injection. Upon starting, it registers callbacks for button-clicking. I used some UniRx in there just because (it removes some boilerplate code like unsubscribing to events)

public interface IMainMenuService
{
    Task OnPlayButtonClicked();
    void OnQuitButtonClicked();
    void OnLoadButtonClicked();
}

I’m the guy who was bitching at the software architect : “Why do you even need all these interfaces for everything ?!”

[UsedImplicitly]
public class MainMenuService : IMainMenuService
{
    private readonly ISceneLoaderService sceneLoaderService;

    public MainMenuService(ISceneLoaderService sceneLoaderService)
    {
        this.sceneLoaderService = sceneLoaderService;
    }

    public async Task OnPlayButtonClicked()
    {
        LoadCinematicSceneTransaction loadCinematicSceneTransaction = new LoadCinematicSceneTransaction(this, sceneLoaderService);
        await sceneLoaderService.ExecuteTransactionAsync(loadCinematicSceneTransaction);
        UnloadMainMenuSceneTransaction unloadMainMenuSceneTransaction = new UnloadMainMenuSceneTransaction(this, sceneLoaderService);
        await sceneLoaderService.ExecuteTransactionAsync(unloadMainMenuSceneTransaction);
    }

    public void OnQuitButtonClicked()
    {
        // TODO: Exit the game gracefully.
        Application.Quit();
    }

    public void OnLoadButtonClicked()
    {
        // TODO: Opens the load game menu.
        throw new NotImplementedException();
    }

Finally, the MainMenuServicecode. Same steps, mostly. First, setup for DI. Second, actually do the things!

To make things more convoluted, instead of using the Command Pattern here, I went with a transactional / contractual system.

Why ?

I’m pretty sure there are a lot of ways to handle this but I’ve run with this to make what is happening clearer to me. Let’s say you are using an Event Bus or Scriptable Objects events. At some point, things start to get messy. You get all these decoupled events that are hard to track. Who sent the event ? Who intercepted it ? That’s especially useful in this kind of game state-changing operations.

I’ll have to take a break at this point of the story and, maybe, start working on Part 2.

This is my first article. I hope it is useful to you. Feedbacks are more than welcome.

Last words: a BIG thank you to Charlie de St Jores (@Marijenburg) for giving me his full trust on handling the coding-side of Bill. It’s an awesome opportunity for me to work on something I care for and to learn, learn, learn and learn more.