Blog

I said we’d most likely revisit Actor Oriented Design in Unity, and here we are! This time we’ll be focused on Actor Eventing/Messaging/Cues. To catch up on the first installment, please read more here

State Machines + Messaging ≈ Actor Oriented Design

State Machines plus Messaging doesn’t quite equal Actor Oriented Design, but it’s awfully close. Actors in our scene will enter different states of action such as telling the camera zoom in, fire a projectile, or display a new ship. When an actor in our scene enters a state, they can create events/messages/cues for other actors in the scene to take up a new states in the scene. Those other actors “listen” for those events/messages/cues, then enter the appropriate state.

So what’s different from our original approach?

Our first approach to Actor Oriented Design involved only the state machines; we explicitly called other actors in our scene to enter specific states. This works for very small, very simple systems, but as systems grow, this creates a typical software issue known as “tight coupling”. This means that our actors have to know about each other and their states. This causes several issues as your project begins the grow. Most namely, that actors will have to have references to each other in order to instruct one another to enter different states.

This example is how a tightly-coupled piece of code would act. You’ll see, all the asteroids have a reference to our Player Ship for the purpose of registering a score on the Player Ship. It’s easy for our Asteroid to register a score for our Player Ship, but it requires each asteroid to “know” about the Player Ship in order to increase the score. There is nothing functionally wrong with this approach, but it is a design flaw.

So when we applied this solution to Spaceschuter McGavin it became problematic over time. In Spaceschuter McGavin we have 1000+ asteroids needing to get a reference to our Player Ship. Each asteroid is responsible for instructing the Player Ship to register a new score if is shot down. We also have to update that reference for each of the 100’s of asteroids each time the player changes ships.

As I mentioned, this racks up a lot of time in the Update and FixedUpdate methods, constantly checking if a player blows an asteroid up. It’s better to apply a loosely-coupled solution based on a event/messaging/cue system to relay this information.

Loosely-Coupled vs. Tightly-Coupled

Here we’ll see the difference between tightly coupled and loosely coupled Actor Oriented Design code.

A seasoned programming mind might realize we’re not avoiding tightly coupled objects all together. We’re still introducing tight coupling, but through a third object (Actor Cues). Actor Cues only job is to couple objects together that need to communicate. The idea is to control the coupling through this third object when you need to facilitate communication, but otherwise the objects take care of themselves.

This loosely-coupled example is broken into 2 parts: Publishing an event/message/cue and Subscribing to a event/message/cue. An event/message/cue is nothing more than “something that has happened in the scene”. That’s it. The asteroids are simply screaming out to any actor that will listen that an Asteroid Actor has been shot down. If no actor is listening at the moment, the event/message/cue dies and nothing changes. However if some actor is listening for the “Shot Down” cue, they will react in whichever way they choose.

The benefits of loosely coupled code goes beyond code fragmentation. It supports the SOLID coding principle, namely the Dependency inversion principle: Depend upon abstractions, not concretions. That’s a lot of tech-talk for meaning “the code is in good form and should perform/change well over time”. That’s the crux of what we’re getting at; designing code in a manner that reduces further redesigns down the road.

I talk in abstracts a lot, so how about some code?

Dear reader, I agree, but be warned: I will glaze over my use of C# generics as this is meant to be demonstrative in nature and not a course on the C# language.

ActorCues

using System;
using System.Collections.Generic;
using System.Linq;

namespace Assets.Scripts.Utility
{
    public interface IActor
    { }

    public interface IActorCue<T> where T : IActor
    {
        T actor { get; }
    }

    public interface IActorCueCollection
    { }

    public interface ICueSubscriber<T> where T : IActor
    {
        public void OnCue(IActorCue<T> cue);
    }

    public class ActorCues
    {
        private Dictionary<Type, IActorCueCollection> actorCueCollections = new Dictionary<Type, IActorCueCollection>();

        public void Subscribe<TActor, TCue>(ICueSubscriber<TActor> cueSubscriber) where TActor : IActor
            where TCue : IActorCue<TActor>
        {
            var actorType = typeof(TActor);
            if (!actorCueCollections.ContainsKey(actorType))
                actorCueCollections.Add(actorType, new ActorCues<TActor>());

            var cues = actorCueCollections[actorType] as ActorCues<TActor>;
            cues.Subscribe<TCue>(cueSubscriber);
        }

        public void Unsubscribe<TActor, TCue>(ICueSubscriber<TActor> cueSubscriber) where TActor : IActor
            where TCue : IActorCue<TActor>
        {
            var actorType = typeof(TActor);
            if (!actorCueCollections.ContainsKey(actorType))
                actorCueCollections.Add(actorType, new ActorCues<TActor>());

            var cues = actorCueCollections[actorType] as ActorCues<TActor>;
            cues.Unsubscribe<TCue>(cueSubscriber);
        }

        public void Publish<TActor, TCue>(IActorCue<TActor> cue) where TActor : IActor
            where TCue : IActorCue<TActor>
        {
            var actorType = typeof(TActor);
            if (!actorCueCollections.ContainsKey(actorType))
                actorCueCollections.Add(actorType, new ActorCues<TActor>());

            var cues = actorCueCollections[actorType] as ActorCues<TActor>;
            cues.Publish(cue);
        }
    }

    public class ActorCues<TActor> : IActorCueCollection where TActor : IActor
    {
        private Dictionary<Type, HashSet<ICueSubscriber<TActor>>> subscribers = new Dictionary<Type, HashSet<ICueSubscriber<TActor>>>();
        private Type ActorType { get => typeof(TActor); }

        public void Subscribe<TCue>(ICueSubscriber<TActor> cueSubscriber) where TCue : IActorCue<TActor>
        {
            var type = typeof(TCue);
            if (!subscribers.ContainsKey(type))
                subscribers.Add(type, new HashSet<ICueSubscriber<TActor>>());

            if (!subscribers[type].Contains(cueSubscriber))
                subscribers[type].Add(cueSubscriber);
        }

        public void Unsubscribe<TCue>(ICueSubscriber<TActor> cueSubscriber) where TCue : IActorCue<TActor>
        {
            var type = typeof(TCue);
            if (subscribers.ContainsKey(type))
                if (subscribers[type].Contains(cueSubscriber))
                    subscribers[type].Remove(cueSubscriber);
        }

        public void Publish(IActorCue<TActor> cue)
        {
            var type = cue.GetType();

            if (subscribers.ContainsKey(type))
                foreach (var subscriber in subscribers[type].ToList())
                {
                    subscriber.OnCue(cue);
                }
        }
    }
}

It all starts with Actor Cues. This serves as our messaging bus to which events/messages/cues are published and subscribed to. It’s important to know that PubSub implementation, such as this one can be accomplished many ways, some solutions can even involve the Unity Messaging system. It’s a kind of “developer’s choice”. In our use case, my events/messages/cues include a reference to the object that published the event/mesasge/cue. Don’t worry if this code seems confusing, we won’t be modifying it beyond its current state, but instead consuming it by Publishing and Subscribing to it from various actors. We’ll host the ActorCues in our GameManager

public class GameManager : MonoBehaviour
{
    public ActorCues actorCues = new ActorCues();
}

Publishing

using Assets.Scripts.Utility;

namespace Assets.Scripts.Asteroid.Cues
{
    public class ShotDownCue : IActorCue<AsteroidObject>
    {
        public ShotDownCue(AsteroidObject actor)
        { this.actor = actor; }

        public AsteroidObject actor { get; }
    }

public class AsteroidObject : MonoBehaviour, IActor
{
    public GameManager gameManager;
    public int shotDownScore = 100;
    public OnDestroyAsteroid()
    {
        gameManager.actorCues.Publish<AsteroidObject, ShotDownCue>(this);
    }
}

So here we have a simple AsteroidObject and ShotDownCue object. Notice that the Asteroid object implements the IActor interface. When prompted to blow up, the asteroid will publish the ShotDownCue for our listeners to subscribe to. Easy peasy.

Subscribing

public class PlayerShipObject : MonoBehaviour, ICueSubscriber<ObstacleObject>
{
    public GameManager gameManager;
    private score = 0;

    private OnEnable()
    {
        gameManager.actorCues.Subscribe<AsteroidObject, ShotDownCue>(this);
    }

    private OnDisable()
    {
        gameManager.actorCues.Unsubscribe<AsteroidObject, ShotDownCue>(this);
    }

    public void OnCue(IActorCue<ObstacleObject> cue)
    {
        if (cue is ShotDownCue)
            AddScore(cue.actor.shotDownScore)
    }

    private void AddScore(int addedScore) 
    { 
        score = score + addedScore;
    }
}

Here’s our Player Ship subscribing to the AsteroidObject‘s ShotDownCue. When a event/message/cue is received, it will adjust the score accordingly. Notice how we unsubscribe and subscribe to the event/message/cue on OnEnable and OnDisable? That’s so if this ship is disabled it will no longer receive updates for a score! Useful if the Player changes ships or dies before an asteroid is shot down. All those features in a tiny little bundle of code.

That’s a lot more code

Sadly, yes, with good design comes more code. As I stated in my previous article. The Messaging System was not authored because it wasn’t quite “needed” yet. That word: “Need” is a tough term to define in this instance. For me it meant: My actors aren’t chatty enough yet with each other (tightly coupled) to warrant a redesign.

Spaceschuter McGavin is a prototype that’s evolving into our final product. That means I purposely take shortcuts at times to get something quickly into prototyping. IF that prototype passes playtesting and ages, I refactor the code to take more permanent residence using good design measures. Add in the fact that I have several prototyped features all aging at different rates, and the result is I have to be selective in what I redesign. It’s a balancing act as we learn more and do more.

I’d be remiss if I didn’t say I wish I had fully implemented Actor Oriented Design with the messaging component in tact. Refactoring any amount of code is typically more bug prone than starting from scratch with the new code. However, I strategically picked a point in time where I knew I had to refactor my prototype code to adopt events/messages/cues before tight-coupling became an issue. For me, this became evident because I ran into a limitation with my tight-coupling I purposely put in place. A kind of bookmark0 to where I knew if I ran into that known limitation, it was time to refactor code before I pursued.

What’s the right choice for me?

If you’re reading this blog to learn about Actor Oriented Design in Unity, I recommend following the full pattern. Our experience with software architecture and the C# language is high so we’re able to plan phased roll-outs of designs. If you’re reading this blog to learn about HOW TO INTRODUCE Actor Oriented Design to your project, I’d recommend implementing the StateMachine first. THEN work on messaging after you feel you have a firm grasp on the StateMachine portion. However if you notice immediate coupling of actors in your scene, I wouldn’t hesitate to introduce the Event/Message/Cue system.

In Conclusion

Actor Oriented Design in Unity is a perfect match in our minds here at Delightful Games. Unity works well with any amount of Actor Oriented Design, so use as sparingly or aggressively as you will. Actor Oriented Design approach provides a powerful, organized programming platform you can grow into as your projects grow.

Blog

Here at Delightful Games we believe in a wholesome experience. So in following that guidance we’ve begun a development blog! Delightful Games will host weekly(-ish) posts diving a bit deeper into the various pieces that makes our games tick. Keep reading for our first installment: Actor Oriented Design in Unity for Spaceschuter McGavin!

Note: This blog is meant for intermediate/advanced programmers. It will not cover common/basic software design patterns in great detail; There is plenty of free information on software design patterns already available online. Same goes for Unity specific functionality; it will likely go uncovered in this blog. Instead, this blog will feature time-saving / future-proofing techniques that we have employed in our game already or are building. I am not a professional Unity programmer, so I don’t guarantee I’ll have the best approach. However, I am a professional C# programmer and have several decades of experience in enterprise programming environments.

Unity & Actor Oriented Design

So here in Spaceschuter McGavin, we’re essentially collecting flight recorder/ black-box data from 9 ships, across one kilometer. It makes for several thousand data points! However, when collected and applied correctly, the number of data points isn’t difficult to manage. The core of our Unity development is based on a concept called Actor Oriented Design (AOD). Through this design pattern, you will find it’s simpler to “bolt on” a new feature/behavior for the actors in your scene.

State Machines

Actors are mostly empty Unity MonoBehavior scripts . They contain a State Machine that governs which behaviors are active. State machines come in several flavors, most notable being the Finite-State-Machine. However, “finite” state machines don’t allow for new states and transitions to be easily added to them. So we’re opting for a simple state machine that will only be concerned with the current state. GameObjects can transition states with or without conditions.

So above we have an example GameObject called PlayerObject. It contains some pseudo-code of what will be present in our MonoBehavior class. You’ll notice that Update(), LateUpdate(), and FixedUpdate() only have a single call to an identically named method in the stateMachine. Inside each “Behavior” there will exist EnterState(), ExitState(), Update(), FixedUpdate(), & LateUpdate(). This allows a specific Behavior to focus on a specific script of instructions without needing to worry about other states’ functionalities bleeding over into its state.

This unfortunately happens a lot when you have a single object that’s responsible for several behaviors. The behaviors then co-exist in a single Update() method! This can make leaking of states as well reducing readability of your code. Of course you could develop the multiple behaviors in multiple MonoBehavior scripts, but then you’ll need to turn off and on specific scripts based on your “current state”. It’s a situation that cries for a stateMachine.

Our tiny little stateMachine

Notice inside our SetState() methods we have:

stateMachine.ChangeState(new IdleState(stateMachine, this));

We pass a reference to the stateMachine so our Behavior can further change its Actor’s state if necessary, and a reference to the MonoBehavior itself. This allows our Behaviors to access other unity components as necessary; such as Rigid Body, Mesh Renderer, Sprite, etc. I sometimes think of Actors’ Behaviors as “MiniBehaviors” of the MonoBehavior **chuckle** because these MiniBehaviors exhibit the same commons traits that a regular MonoBehavior has. And if I needed new functionalities (e.g. stateMachine.Awake()) I can easily add it.

But Wait!

It’s important to know that not all our objects in our scenes are Actors. When GameObjects need to have more than two states they are upgraded to be an Actor. The only downside is AOD requires additional programming to be supported properly (At the time of this writing we had around ~400K lines of code). I find it to be fairly boilerplate, but you may not depending on your experience.

We’ve also purposely violated one of the tenants of Actor Oriented Design: Actors should be the only entity allowed to change their own states. This means other actors aren’t allowed to directly change an actor’s state. Instead, objects are expected to “message” an actor, and the actor may change its state. The reason for this is that we didn’t want to make a whole messaging subsystem to manage state changes. Instead we allow Actors to “cue” one another into their next behavior. This is where the public SetPlayState(), SetIdleState(), & SetShipSelectState() methods come into play: Actors can cue one another by calling each other’s Set*State() methods. This is a shortcut, but one that meets our needs perfectly so far.

This has enabled us to treat Unity GameObjects like Actors in a scene such as a movie. The GameManager directs the actors to do things, and they cue one another and react to one another until the director yells “cut!” and gives the actors new instructions.

Ok… that’s great, but what about the statistics?

Well, the Actor and stateMachine explainations are crucial since all our GhostSystem does is observe interesting Actors (yes in some cases using an actual Observer pattern) and record them when they’re in a specific state. Kind of like a camera man that only records when the actors are ready. Since the GhostSystem is our camera man, he has one job: record and observe. And that’s a model of software that fits perfectly into our story telling system. Now just think, a tutorial (think of them as an assistant director) that has the ability to tell actors to freeze their position for a moment, then continue gameplay the next. Did you think of it? Good, because that’s how we handle the Tutorial as well! This is the power Actor Oriented Design has offered us so far.

Now that’s not the only shortcut we’ve employed with statistics. The GhostSystem could not observe the thousands of Actors our game presents. At least, not in an efficient manner; It increased load times by over 200%. So now our thousands of Actors report behaviors to a central StatsSystem. These Actors report statistics such as “shots fired” and “obstacles destroyed”. The StatsSystem then combines that data with the GhostSystem data and shows you the Game Statistics screen seen at the beginning of the post.

This breaks the SOLID principle, but GameObjects are merely reporting about things they know, just not in a generic fashion. The truth is, it may in the future, but for now, as protype code goes, this works perfectly fine. I’m sure this won’t be the last time post about Actor Oriented Design in Unity, or Actor Oriented Design in Spaceschuter McGavin for that matter.