Before starting my next Unity project there were a couple of new features I wanted to add to my open source library Unity Atoms — a library that utilizes ScriptableObjects to make your code more modular, testable and easier to work with and make changes to. If you are not familiar with Unity Atoms you should before continuing read my previous posts about it:

• Unity Atoms — Tiny modular pieces utilizing the power of Scriptable Objects
• Announcing Unity Atoms v2

Even though that Unity Atoms in previous versions has been a solid solution for state management in Unity there have been a couple of workflows and situations that have not had a clear cut solution, for example there have not been a great solution for state associated with prefabs getting dynamically spawned at runtime. Being able to use the same code and design patterns, regardless if the asset is instantiated at runtime or statically baked into the scene, is of course preferable. I’m therefore REALLY excited to say that this has finally been addressed in Unity Atoms v4 🎉 Version 4 also implements some other cool features like Event Replays (same as Rx’s ReplaySubject), Finite State Machines and Pre Change Transformers. Below I will discuss the new features implemented in Unity Atoms, how they work and some uses cases for them. Let’s dive into it!

(For those who are wondering what happened to v3 of Unity Atoms, the answer is that I basically did a rewrite of Unity Atoms two times. I rewrote and released the library a first time (version 3), but soon after release I realized a few flaws in the design, which led me to rewrite it a second time. Creating a new major for the second rewrite made sense to me. So here we are with Unity Atoms v4!)

💿 Collections & Lists

Collections and Lists are ScriptableObjects grouping Variables and Constants. Think of a Collection as a C# Dictionary, but as a ScriptableObject with strings (StringReferences) as keys and Variables or Constants as values. You can think of a List as, if you have not already guessed it, a C# List containing Variables and Constants. The values stored in both Collections and Lists are not type specific, so you can store an Int Variable in the same Collection / List as a String Constant. Another nifty thing is that Collections and Lists are in themselves also Variables and they can therefore be nested, eg. a Collection can contain a List that contains a Collection.

There are three Events associated with both Collections and Lists and they are:

• Added — Triggered when an Atom is added to the Collection / List.
• Removed — Triggered when an Atom is removed from the Collection / List.
• Cleared — Triggered when the Collection / List is cleared of all Atoms.

Furthermore, the Value of a Collection or a List is a reference to an actual List or Collection, eg:

_collection.Value and _list.Value

List’s Value is actually deriving from the C#’s generic List and the Collection’s Value implements C#’s IDictionary, IEnumerable and ICollection. This means that the you can for example can use it in a foreach loop and use it together with LINQ.

One last thing to note is that Lists were actually a thing in v2 of Unity Atoms. They have however in version 4 changed name to (Atom) Value Lists, and the new List described above have taking its former name.

🧬 Variable & Event Instancers

Variable and Event Instancers are MonoBehaviours that takes a base, a Variable or an Event of a specific type, and creates an in memory copy of that base on OnEnable at runtime. And what good is this for you might ask? This is the basis of enabling using Unity Atoms in prefabs instantiated at runtime. We will take a closer look at that workflow further down in this post. Note that there are also Instancers for Lists and Collections (enabled by the fact that they are themselves Variables).

Sync Variable Instancer To Collection is a MonoBehaviour class related to Instancers. It takes a Variable Instancer as input and adds it to a List or a Collection on OnEnable and removes it on OnDestroy. The List or Collection could be a regular one or a reference to one instantiated at runtime by a Collection or List Instancer. This script is also essential for the dynamic workflow explained later in this post.

🗒️ Event References

If you have used Unity Atoms before then you will recognize that Event References are the same thing as References, but for Events. An Event Reference is a regular Serializable C# class that has a reference to an Event, and you can from the Inspector choose one of three sources:

• Event —Uses a regular Unity Atoms Event.
• Event Instancer — Uses the in memory Event created by the Event Instancer.
• Variable — Uses the Changed / Changed With History Event associated with the provided Variable.
• Variable Instancer — Uses the Changed / ChangedWithHistory Event associated with the in memory Variable created by the Instancer.

Furthermore, Listeners are now using Event References instead of regular Events.

📹 Replay Atom Events

All Events in Unity Atoms v4 have a property called Replay Buffer Size, which defines the size of a buffer that stores Event values emitted by the Event. For example, if an Int Event raises the values [1, 2, 3, 4, 5], in that order, and the replay buffer size is 3, then the buffer will contain [3, 4, 5]. Next time someone registers to the Event, then the Event will emit the last 3 values, [3, 4, 5], to that listener. Like mentioned in the introduction, this is the same behaviour as ReplaySubjects in ReactiveX.

🏋️‍♂️ Pre Change Transformers

Pre Change Transformers are Functions that are called and applied to Variables before its value changes. Pre Change Transformers takes the new value as a parameter, performs its logic, and then returns a value of the same type. This enables for example clamping of Int and Float Variables, which is provided by default in Unity Atoms v4. However, this functionality could be used and extended for other features, for example capitalizing a String Variable.

🤖 New Package — FSM

Unity Atoms now have a light weight implementation of a Finite State Machine (FSM). The state machine is made up of a list of states (strings) and a list of transitions expressing how the state machine can change from one state to another. In order to go from one state to another you need to dispatch a command. The FSM in Unity Atoms is actually an extension of the String Variable, so it will have all the functionality that a String Variable posses. Unity Atoms FSM was inspired by this package and the following example is taken from there:

This FSM represents states and transitions of a door. It has the following states:

• OPEN
• CLOSED
• LOCKED.

It also has 4 transitions:

• From OPEN to CLOSED when dispatching the command CLOSE.
• From CLOSED to LOCKED when dispatching the command LOCK.
• From LOCKED to CLOSED when dispatching the command UNLOCK.
• From CLOSED to OPEN when dispatching the command OPEN.

This how the above FSM would be expressed in Unity Atoms:

State explained

• Id — the state identifier as a string. The first state’s Id will be the default state of the FSM.
• Cooldown — if set to a number above 0 the state machine will loop on this state and re set the value with the duration specified by the cooldown (seconds). If for example cooldown is set to 1 and the state id is set to EXAMPLE, then the state machine will be set to EXAMPLE every second. This means that the FSM's Changed Event will be triggered every second as long as the FSM is in the state called EXAMPLE.
• Sub Machine — FSMs can be nested. If a sub machine is specified for a state it will take over when resolving the state value for that particular state.

Transitions explained

• From State — The state that we transition from.
• To State — The state that we transition to.
• Command — The command that needs to be dispatched in order to begin this transition.
• Test Condition — If specified this condition must be true in order to start the transition.
• Raise Event To Complete Transition — If set to true the transition will not complete automatically, Instead you will need to manually Raise the Complete Current Transition Event (specified above all states).

🦸‍♂️ Leveraging Your Newly Gained Powers

Imagine that you have enemies that you want to spawn dynamically at runtime and that you also would like to create health bars that are displayed above each enemy when they get instantiated. You would start by creating a new List called Enemies that will hold all the data about all the enemies in our scene. Using the new tools at our disposal you would then create an enemy prefab with the following:

• Collection Instancer — Creates a Collection at runtime that will hold all the data / Variables associated with this enemy.
• Sync Collection Instancer To Collection — Adds the Collection created in the above script to the Enemies List.
• Int Variable Instancer — Creates an in memory copy Variable representing the enemy’s health.
• Sync Int Variable Instancer to Collection — Adds the health Variable to the enemy data Collection created by the Collection Instancer.
• Vector 3 Instancer — Creates an in memory copy Variable representing the enemy’s position.
• Sync Vector3 Variable Instancer to Collection — Adds the position Variable to the enemy data Collection created by the Collection Instancer.
• A custom script for syncing the enemy’s position with the Variable created above.

After setting up the above we now have a List of enemy data that gets populated at runtime. A list of 3 enemies could be visualized like this:

We can now use the Enemies List’s Added and Removed Events to, in a data driven manner, add, remove and position health bars above the enemies in the scene. The code for that would look like this:

For the full-fledged version of the above you should checkout the InfiniteWaves demo scene in the Examples project on Github.

🏠 Minor and Internal Changes

Here follows some minor and internal changes made in v4 of Unity Atoms.

🎧 Listeners

Most Listeners are now referred to as Event Reference Listeners for the simple reason that they are utilizing Event References instead of just regular Events. This means that you can drag in an Event, Event Instancer, Variable or Variable Instancer as the Listener’s source.

👫 Pairs

The Changed With History Event is no longer raising an Event x 2 / Action<T,T>, Unity Atoms is instead generating Pair structs and is emitting those pairs in a regular Event / Action<T>. The most important aspect of this change is that when you are using Listeners (for pairs / Changed With History), your Responses will have one Pair parameter instead of two parameters of the value type. The reason for using Pairs is to make the code base for Unity Atoms more flexible, clean and DRY.

📦 New package — Base Atoms

Base atoms (eg. Int Variables, String Variables, etc.) are moved from Core into a new package called Base Atoms. This enables faster experimentation and development of Unity Atoms. This means that you are required to drag in both Core and Base Atoms in order to leverage Unity Atoms in your project.

👀 A Look Into The Future

The main focus going forward will be to create more and better documentation around Unity Atoms and the ecosystem. This means that the API references will be polished and the website documentation refined. Furthermore, I believe that my blog posts have helped a lot of people getting into Unity Atoms, but there might be some other channels going forward, for example it might make sense to create a video tutorial series making a simple game using Unity Atoms (let me know if you would be interested in this).

A huge thing coming up in Unity 2020 is serialization of generics. This will greatly reduce the code size of Unity Atoms, improve the readability of the code and enable faster iterations of new features added to the library.

Would love feedback on the new version of Unity Atoms, so take it for a spin and let me know what you think about it. Join the Discord if you want to chat and sign up for my mailing list to get future updates on Unity Atoms and other development related news. If you liked this post give it some 👏 and follow me on twitter. Thanks for reading 💜

I’m the author of an open source library for the game engine Unity called Unity Atoms. The library is inspired by this talk by Ryan Hipple from Unite 2017. I started working on the project in October 2018 and back then it was meant for internal use in my current game side project. Since then it has, after many late nights of work, grown and become a full fleshed solution for working with Scriptable Objects within Unity. Today I’m proud to finally announce that version 2 of Unity Atoms is released 🎉

❓ So what is it and how do I use it?

At its core, Unity Atoms makes Variables, Events, Listeners, Actions and Functions into modular reusable pieces of code by leveraging the power of Scriptable Objects. Together with Unity’s inspector this makes your code much more modular and testable. Below follows a simple example on how this looks in practice.

First create a MonoBehaviour with an IntVariable called Health describing the health of our game’s player:

The IntVariable is a Scriptable Object (.asset file) that could be injected via Unity’s inspector:

The IntVariable will look like this when inspecting it:

We can now use and reference the Player’s health in other scripts by just injecting the IntVariable via the Inspector:

No more direct dependencies between your MonoBehaviours, eg. doing this in your health bar script: player.GetComponent<PlayerHealth>().Health -= 10f;. Hurray! 🥳

For a more detailed description of how to use the library, read my Unity Atoms announcement blog post. When you are done reading the blog post you can head over to the brand new website for more tips and tricks.

🚀 New features

The goal of Unity Atoms version 2 has been to improve the overall developer experience and to polish the APIs making it easier to work with. Here are some of the highlights included in version 2:

• Mono repo: The project has been made into a mono repo and the code has been split up into 6 different packages: core, mono-hooks, tags, mobile, scene-mgmt and ui. You can now pick and choose exactly what you need for your project.
• Code generator: Unity Atoms version 2 includes a powerful code generator that can be accessed from the top menu bar: Tools/Unity Atoms/Generator. This makes it a breeze to create your own Atoms specific to your project.
• UniRx support: Events (OnEvent), Variable Events (Changed and ChangedWithHistory) and List Events (Cleared, Added and Removed) can now be turned into IObservables<T> making Unity Atoms work great with UniRx.
• Custom PropertyDrawers: All Atoms now have custom PropertyDrawers.
• Custom editor icons: All Atoms now have custom editor icons.
• New website: As part of making Unity Atoms more available to developers we have launched a new website full of examples and documentation.

🔮 What’s next?

Version 2 is a great step forward for the library, but we want to take things even further. Here follows a list of things that we are currently looking into:

• Polishing up the Editors and PropertyDrawers even more.
• Investigate how Unity Atoms could integrate with DOTS.
• Variable post processors, eg. clamp value (int, float, etc.).
• Improve debugging.
• More generator options, eg. generation of multi value Atoms.

We also want to listen to the community and implement features that you find valuable. If you got an enhancement that you want to add to Unity Atoms then head over to the issues pages on Github.

We are also looking for more contributors and maintainers for Unity Atoms. Please contact us if you to help the project by becoming one.

Thanks for reading! If you liked what you just read and want to see more of this in the future, then give the post some 👏 and follow me on twitter.

Checkout this demo app using the concepts from this blog post.

This spring (2019) I went to React Europe, a really great conference dedicated to React development. John Watson had a talk there where he introduced an internationalization (i18n) framework called FBT, which is used over at Facebook. I only had prior experience using react-intl, so when the time came to translate my companies’ website I wanted to give FBT a go. This article is going to go through my findings using FBT for the first time and will be show casing examples that you can follow in order to add FBT to your own React application.

🤔 Why should I use FBT?

FBT has a couple of features that stands out compared to other similar frameworks (for example react-intl):

• Translatable text resides inline with the rest of your JSX. This means that you can search for English text strings in your text editor and directly find the React component where it’s used.
• It supports plural variations out of the box.
• It supports enums!
• Adjust translations based on pronouns.

🍖 The meat

Note: the steps below assumes your is using Babel, Webpack and yarn. It also assumes that you are developing in an UNIX environment. If you don’t have an existing app and instead want to start a new one, you can use the template app created in my other blog post Setting up a React app from scratch.

Install Dependencies

Start by installing fbt and fbt-easy-setup to your project. Open your terminal, navigate to the root of your project (where your package.json resides) and type the following:

yarn add fbt fbt-easy-setup --save

fbt-easy-setup is a package that I have created to make life easier adding fbt to a React app. It provides you with an init function, a LocaleProvider and a LocaleConsumer (see React’s documentation on Context). Check out the docs for fbt-easy-setup here.

Continue by installing the following dev dependencies:

yarn add babel-plugin-fbt babel-plugin-fbt-runtime @babel/node @babel/core fbt-generate-translations --dev

babel-plugin-fbt and babel-plugin-fbt-runtime are two Babel plugins that are required in order to run FBT. See more info here regarding those two plugins. Both @babel/node @babel/core are needed in order for the plugins to run properly. fbt-generate-translations is a script that I have made in order to generate translations from the output from FBT’s collect script and consumed by FBT’s translate script. This step would otherwise be manual (ugh!). More on the different scripts and steps later in this post.

Configure Babel

Add the babel plugins installed above to your babel config file. If you are going to use enums the babel-plugin-fbt should be fed a path to the generated enums manifest (more on what this is later in the post). You also might need to add sourceType to be unambiguous (at least I did) in order for the mix between commonjs modules and ES modules to transpile correctly. Here is an example of what to you need to add to your Babel config:

Add locales

Let’s add the locales that you want your app to support! Start by creating a file defining the locales and add it to a folder called i18n:

mkdir i18n && touch ./i18n/locales.js

Open up locales.js in your favourite text editor and add your locales of choice using the following format:

Add scripts

When first getting into the FBT demo, the scripts was the most confusing part to me. There are 3 scripts in the FBT demo app, and I have added another one in order to reduce the manual work needed:

• manifest-fbts — Creates two json files, the first one (.src_manifest.json) keeps track of every file that imports FBT (and therefore might contain translations) and the other one (.enum_manifest.json) keeps track of all FBT enums used in the project.
• collect-fbts — Given the output from the last step, it collects all the texts to translate and generate corresponding hashes. See this for more info.
• fbt-generate-translations / fbt-generate-translations-single-file — Given the output from collect-fbts, it generates translation files (could also just be a single file) that could be consumed by translate-fbts (see below). The file / files generated are then supposed to be manually edited with translations for each locale.
• translate-fbts / translate-fbts-single-file — Takes the output from the step above and creates the translation object that should be passed to FBT’s init function at runtime.

It is also useful to add scripts to clean the generated files (see clean-fbts below) and to do all the steps of above in one go (see prepare-fbts below). If you got scripts to build and start the app it might also be useful to add pre-scripts that runs all the steps above one go (see prestart and prebuild below). My scripts ended up like this:

As a side note: FBT supports having all translations in one file (using the *-single-file script above) or dividing the translations by locale into several files.

Initialize FBT

In order for FBT to work you need to provide translations. This needs to happen before any of the React components containing translations load. You also need to pass your locales and default locale to the this function. Mine ended up like this:

Since initialization needs to be done before the translations are used in any React component, add it to your Webpack config’s entry:

Add the Provider and the Consumer

The next step is to add the LocaleProvider and theLocaleConsumer to your app. Start by wrapping your app with the LocaleProvider:

Now you can use the LocaleConsumer where applicable. For example you can create a component that toggles between English and Swedish like this:

Add your text

You are now all setup to add translations to you app! Hurray!

You can now for example add a fancy translatable paragraph component:

FBT’s docs for how to add translatable text to your JSX is actually really good. Check it out here!

Git ignore

All git users out there should also add the following to.gitgnore:

Workflow

When you have added all the translatable text you want to your JSX you should run yarn prepare-fbts. After that you can add the translations for each locale to the generated file(s) (either in translations_input.json or in the files located in the translations folder). The typical workflow for translations (using the setup from this blog post) will look like this:

• Add FBT JSX to your app.
• Run your scripts to generate translation files.
• Add and modify translations in the generated files from the above step.
• Build and run your app that now contains the new translations.

However, there are endless possibilities on how to improve this process. For example it is possible (with the help of some custom scripts) to fetch translations from a remote location (eg. a translations API) and merge them with your translation file(s). This process could for example be a part of your build pipe. This is actually how Facebook is using it:

Some notes on shared enumerations

Something that is not documented when it comes to shared enums is that you need to add the suffix $FbtEnum.js to the filename of the module that defines it.

Another thing to note is that due to some issues regarding the babel plugin (eg. see this issue for example), you need to use require and not ES imports when using the module that defines the shared enum:

const SharedEnum = require('Shared$FbtEnum');

You also might notice that the shared enum above is required using an absolute path. Due to a bug in the babel plugin this is required, otherwise it throws. In order for the absolute path to work you will need to add a resolve entry to your Webpack config:

😝 Still stuck?

If you have followed this post you should have a working app with translations. However, if you for some reason is stuck you can check out the source on Github of this demo app.

🌦️ Conclussions

FBT promises some really awesome features like inlining translatable JSX text (which makes the text searchable in your text editor), support for plural variations, enums and pronouns. For the most part this works really well (after the initial setup has been made). However, the problems with enums shines light on some FBT’s rough edges. It feels like FBT needs some more users and maintainers in order to get some of these issues discovered and fixed. So if you are not afraid to dig in to some open source work, I definitely think that FBT is great candidate for managing i18n in your next React app.

Let me know what you think about this post in the comments below and hit that 👏 button if you liked what you read. You can also find me on Twitter if you got any further questions or comments on what you just read.

Delegates and extension methods are tools in your C# toolbox that, if used right, can greatly enhance the quality of your code, improve its reusability and readability. But what are delegates and extensions? Here is an explanation of what delegates are from one of the first hits on Google:

A delegate in C# is similar to a function pointer in C or C++. Using a delegate allows the programmer to encapsulate a reference to a method inside a delegate object. The delegate object can then be passed to code which can call the referenced method, without having to know at compile time which method will be invoked. — akadia.com

In other words, a delegate declaration describes a method signature (a method’s return type and its argument types), while an instance of that delegate can be assigned, referenced and invoke a method matching that signature. You have probably encountered Action, Func and EventHandler before, they are all examples of delegates. If you have ever used functions like Array.Find or List.ForEach, then you have also used delegates. Here is an example of a delegate that takes an int as a parameter and returns a bool:

Extension methods are explained like this in the official .NET C# documentation:

Extension methods enable you to “add” methods to existing types without creating a new derived type, recompiling, or otherwise modifying the original type. Extension methods are a special kind of static method, but they are called as if they were instance methods on the extended type.

The most commonly used extension methods are the ones from LINQ. However, there is nothing stopping you from adding your own extension methods. Below follows an example of adding a chainable add method to the generic List class:

🦄 The good

Great, so now you know what delegates and extensions are! But why should you use them in your code? Here is a quick list of advantages of using delegates and extensions:

• Encapsulation and code reusability
• Extensibility of your functions and built in C# types and classes
• Code that is easier to understand, maintain and read

Let’s show this in an example. I usually find myself in my games iterating over a collection of items and perform an action or change its state depending on a condition. Imagine that you have an Unicorn that likes to give hugs:

And let’s say that you also have an unicorn controller class (shame on you) that iterates over the unicorns and makes them hug your player if it comes too close:

It works and all, but an approach like this soon becomes really messy, especially when we need to expand on the logic. An alternative to this would be to create an extension method that is using delegates for iterating a List:

You can now rewrite your previous unicorn controller class to this:

From my experience these kind of patterns are used over and over again and writing those extension methods are worth while your time. The extension methods could also be reused, not only in this project, but in your other projects as well (maybe by creating your own Unity package), which will save you a lot of time in the long run. Having the implementation for the ForEach method only defined once makes your code base also more maintainable. Furthermore, I find the second approach much easier to read and grasp at first glance.

👾 The bad

That is all great! However, there are also some potential pitfalls using delegates and extensions like this in Unity:

• Learning curve
• Unintentional creation of garbage (GC)

Many people finds it hard to wrap their head around delegates and why they are sometimes preferred over regular function calls. There is an initial learning curve, but once you get passed it they are easy to grasp. If you are creating a library of extension methods using delegates it can also become hard for new developer to understand the code right away (good names for your extension methods are really key here). You can always point to this blog post in order to get rid off the learning curve problem 😊 However, the unintentional creation of garbage is worse of a problem and could potentially create a world of hurt…

💩 The ugly

I came across this blog post by Jackson Dunstan the other day. It explains really well how easy it is to unintentionally create garbage while using delegates when coding C# in Unity. Head over to Jackson’s blog post and read it while I will wait here for you.

When reading the blog post I was surprised by two things. First, that passing an instance method to a method that takes a delegate actually creates garbage every time you call that method. Second, I was expecting that a lambda function passed as a delegate would create garbage every time it was used, but the C# compiler actually caches the lambda function for you. However, if the lambda function (or an anonymous method) is using variables or data from the outside scope, it won’t be cached and will instead create garbage each call, just like the use of instance methods. Here follows some tips for what to avoid when using delegates in Unity:

• Don’t pass instance methods directly to methods taking a delegate as a parameter. There are two alternatives 1) use lambdas, static or anonymous methods or 2) you can cache the instance method in a variable and pass that variable.
• When relying on the C# compiler to cache your delegate (when passing lambdas or anonymous functions directly), then never reach for variables that are outside the method’s own scope. Think of those methods as static (or pure / functional).

Jackson is further talking about the expense of branching. There is a difference between if you pass a method directly to a method taking a delegate versus if you cache your delegate in a variable and pass that variable instead. In the former there will be a check against the C# compiler’s own cache and we will always do a cache check (that according to Jackson can hurt performance) while in the latter the compiler will still keep its cache field meaning that there are duplicate cache fields (yours and the compiler’s). I would argue that the performance difference between these are in general too small to care about. When I was benchmarking this on my computer I could not see a big difference in execution time. So I will personally in most cases just not cache my delegates until it actually becomes a real problem.

🤔 Conclusion

There are some great benefits of using delegates and extension methods in this way, which makes your code reusable, readable and more concise. Just keep in mind how to avoid creating unintentional garbage. Let me know what you think in the comments below and hit that 👏 button if you found what you just read interesting. You can also hit me up on Twitter if you got any questions or comments on what you just read.

I’ve been working with Unity for several years, creating mobile games for iOS and Android as well as using it during several Ludum Dare game jams. I generally really like Unity and everything that you get for free using it. However, seeing myself as a programmer first, I have always struggled finding a good way of creating a modular and maintainable code base. The general approach of building scripts in Unity (shown in most tutorials online) often yields very tightly coupled and monolithic scripts. This makes the code cumbersome to test, hard to debug and tricky to understand. It gets even worse when many developers are working together on a larger project. The problems described above have always bothered me and made me less motivated when working on my games and has sometimes even made me a sad developer 😢

The Revelation of ScriptableObject

Seeing this talk by Richard Fine during Unite 2016 really opened up my eyes to the use of Scriptable Objects in Unity. Ryan Hipple’s talk from Unite 2017 took the use of Scriptable Objects further and introduced the audience to the concept of shared state variables as Scriptable Objects and a nifty event-listener pattern. I really recommend watching both talks above as well as reading this article about game architecture and Scriptable Objects.

Even though I really believe that you should watch the videos above and wrap your head around Scriptable Objects before continuing, I understand that it is a big commitment. Therefore, I will try to explain and summarize why Scriptable Objects is a great tool in the Unity toolbox by listing some of its properties that makes it powerful, but also what makes it different from MonoBehaviours:

• Unlike MonoBehaviours, Scriptable Objects do not live in a scene, are not attached to GameObjects and do not have a transform component.
• Can be saved as .asset files, but can also be instantiated at runtime and live in memory.
• Gets serialized in the Unity editor and are therefore viewable in the Unity Inspector.
• Do not have most lifecycle callbacks that you are used to on MonoBehaviours, besides OnEnable and OnDisable.
• Excellent for data storage.

All these features of Scriptable Objects make them extremely suited for replacing state and functionality that otherwise would live in MonoBehaviours. By defining small pieces of state (eg. just a variable), breaking out tiny reusable functions to Scriptable Objects and at the same time viewing Unity’s Inspector as a way of inject dependency, we can build modular pieces of code and state that can be reused and injected to our MonoBehaviours.

⚛️ Unity Atoms

Unity Atoms is an open source library that I have started to develop during the development of my current game project. It is based and derived from Ryan Hipple’s talk from Unite 2017 mentioned above. The library is still in its infancy and implementations are therefore due to change over the course of the game’s development. The main idea is to create a set of reusable building blocks that could be reused between projects and shared with others in the Unity community. My philosophy is that ideas and concepts thrives when they are shared and worked on together, so hit me up if you get excited about Unity Atoms and want to contribute or discuss new ideas to implement.

But enough about that. Lets dig into Unity Atoms! There are four fundamental building blocks of Unity Atoms that are essential to understand when working with the library: Variables, Game Events, Game Event Listeners and Responses. Below we will unfold what each of them do and how they interact with each other.

📦 Variables

Variables are storing data, for example primitives, reference types or structs as Scriptable Objects. Because Variables are stored as Scriptable Objects they are not part of any scene, but could instead be seen as part of the game’s global shared state. Variables are designed to make it easy to inject them (via the Unity Inspector) and share them between your MonoBehaviours. Lets see an example!

Imagine you have a PlayerHealth.cs script that contains the health of the game’s player. We will attach the script to a GameObject with a SpriteRenderer, BoxCollider2D and a Rigidbody2D called Player. The health is represented by an int, which corresponds to an IntVariable in Unity Atoms. The script will look like this:

In the game the player’s health will decrease when hitting something harmful. We will attach this Harmful.cs script to a GameObject called Harmful that also has a SpriteRenderer and a BoxCollider2D (as a trigger):

Finally we will add an UI HealthBar.cs script that we attach to a GameObject (inside a UI Canvas) with a RectTransforn, CanvasRenderer and UI Image component. The HealthBar.cs script will update the Image representing the HealthBar when the player’s health is changing:

Both Health and MaxHealth are global variables stored as .assets files that are (or could be) shared between scripts. To create these .assets files we can right click somewhere in the Project window, and go Create / Unity Atoms / Int / Variable. Variables look like this in the Unity Inspector:

The Developer Description is a text describing the Variable in order to document it, the Value is the actual value of the Variable, and Old Value is the last value the Variable had after it was changed via code. Changed and Changed With History will be explained in the Game Events section further down in this post.

We name the IntVariables created to Health and MaxHealth and set both their initial value (in this case 100). After they are created we can drop them on the PlayerHealth and HealthBar components via Unity’s inspector like this:

Variables gives us a way of separating our game’s shared state from the actual implementation. It also makes our code less coupled since we do not need to reference other MonoBehaviours in our scripts, eg. we do not need to reference the PlayerHealth.cs script in our HealthBar.cs script like this:

[SerializeField]
private Player player;

Hurray for less coupled code! 🎉

❗️Game Events

Game Events are things that happens in our game that other scripts or entities could listen and subscribe to. Game Events are (like Variables) also Scriptable Objects that lives outside of a specific scene. In Unity Atoms Game Events can be of different types and thereby pass a long data to listeners. Variables do by default have the possibility to raise two specific Game Events:

• Changed — raised every time a Variable’s value is changed. The Game Event contains the new value.
• Changed With History — also raised every time a Variable’s value is changed. However, this Game Event contains both the new and the old value.

This makes it easier to make our game more data driven than just using Variables. Lets take a look at how that looks in our last example. We can create a new IntEvent as a .asset file by right clicking and go Create / Unity Atoms / Int / Event and name it HealthChangedEvent:

And then drop it on our IntVariable for the player’s health like this:

We can then modify our HealthBar.cs script to look like this (do not worry about the IGameEventListener<int> stuff for now):

And then inject the HealthChangedEvent to our HealthBar component:

We now react to global state changes instead of checking the Variable value each Update tick. In other words we only update our Image component when we actually need to. That is pretty sweet!

👂Game Event Listeners

There is still an issue that the HealthBar.cs script is in charge of registering itself as a listener and at the same time defining what happens when a Game Event is raised. We need to seperate its concerns! This brings us to the third concept of Unity Atoms, Game Event Listeners. A Game Event Listener listens (sometimes also referred to as observes or subscribes) to a Game Event and responds by firing off zero to many responses. Game Event Listeners are MonoBehaviours and therefore lives in a scene. They can be seen as the glue between Game Events and Responses (see the next section of this post).

The HealthBar.cs script from our last example is actually a Game Event Listener, but a very specific implementation of it. We can do better than that! Lets create a GameObject in our scene and call it HealthListener. Unity Atoms comes with some predefined Game Event Listeners. In this case we want to listen to an IntEvent so we will press the Add Component button on our HealthListener, create an IntListener and drop in the HealthChangedEvent:

We can now shave off some of the code in our HealthBar.cs script to look like this:

And then go back to our HealthListener’s IntListener component, press the + to add an Unity Event Response, drop in the HealthBar component (from the scene) and under the dynamic dropdown section select the HealthChanged function defined above:

The HealthBar.cs script is now only responsible for what happens when our player’s health is changing. Pretty great, huh?

💌 Responses

The HealthChanged function created above is actually a Response of type Unity Event. However, in Unity Atoms there is also the possibility to create Responses as Scriptable Objects called Game Actions. A Game Action is a function as a Scriptable Object that does not return a value. As a side note there are also Game Functions in Unity Atoms, which are exactly like Game Actions but does return a value. To demonstrate the concept of a Game Action as a Response lets create a Game Action called HealthLogger.cs that gives some love to the console and logs the player’s health whenever it changes:

It is possible to create the HealthLogger by right clicking and go Create / Unity Atoms / Examples / Intro / Game Actions / Health Logger (this is available due to the call to CreateAssetMenu). When created HealthLogger we can add it as a Game Action Response to the HealthListener:

Every time the player’s health is changed we now log out the player’s health. This particular example is pretty simple, but I’m sure you can come up with lots of other use cases for it (for example play a sound or emit some particles).

That is it! We have covered the four most fundamental core pieces of Unity Atoms. Next we will dive into some other handy tools included in the library.

🎣 Mono Hooks

When you start thinking about this event-listener-response pattern you will soon realize that everything in your game can be expressed this way. The native Unity lifecycle methods can actually be thought of as events that we listen and react to. The bridge between Unity’s lifecycle methods and Game Events is called MonoHooks.

In our example we can use the MonoHook OnTriggerEnter2DHook to replace the Harmful.cs script completely. We will start by removing the Harmful.cs script from our project and remove its component on the Harmful GameObject. Next we will add two new components to the Harmful GameObject, OnTriggerEnter2DHook and Collider2DListener (both predefined in Unity Atoms). Then we will create a Collider2DEvent (Create / Unity Atoms / Collider2D / Event) and call it HarmfulTriggerEvent. We will drop the HarmfulTriggerEvent on the Event for both the OnTriggerEnter2DHook and Collider2DListener that we just created. Lastly we will create a new Collider2DAction called DecreasePlayersHealth.cs that looks like this:

We can then create a DecreasePlayersHealth.asset file (Create / Unity Atoms / Examples / Intro / Game Actions / Decrease Players Health) and inject it as a Game Action Response on our Harmful GameObject:

We can also add the MonoHook OnStartHook to set the initial value of our Health variable when the scene starts. To do so we will start by creating a new GameObject in our scene and add a OnStartHook component and a VoidListener component to it (both included by default in Unity Atoms). Then we will create a Game Event of type void and add it to Event for both of the components. Finally we can create a predefined Game Action called SetIntVariable (Create / Unity Atoms / Int / Set Variable) that will actually set the value on our Health variable and name it SetPlayerHealth:

This will properly set the player’s health to 100 when the scene starts.

Some further notes about MonoHooks: Event With GO Ref is a Game Event that will be raised just like the regular Event, but with a reference to the GameObject that has the OnStartHook component on it (by default). If Select GO Ref is defined we can select what GameObject will be referenced by the Event With GO Ref. This could be useful when we for example want to reference a parent or a child of the GameObject with the MonoHook component.

©️ Constants

A Constant is a stripped version of a Variable. It doesn’t contain any Game Events for when the value is changed neither the Old Value field. It is not possible to change a Constant’s value via code. The thought is to use Constants for global shared values that are not due to change, eg. tags, layer names, multipliers, etc. In our example it would be preferable for MaxHealth to be a constant:

And to change the player tag in our DecreasePlayersHealth.cs script:

®️ References

References can be toggled between use constant or use variable via the Unity Inspector. When a reference is set to use constant it functions exactly like a regular serialized variable in a MonoBehaviour script. However, when it is set to use variable it functions exactly like a Variable. This is something that is copied directly from Ryan Hipple’s Unite 2017 talk.

📋 Lists

A list is an array of values that is stored as a Scriptable Object. There is a possibility to add Game Events to a List when the following happens:

• An item is added to the list.
• An item is removed from the list.
• The list is cleared.

Lists are perfect for storing data or references to Game Objects that need to get tracked and created at runtime.

📇 Some Final Words

Unity Atoms is open source and can be downloaded from Github and used in your project by going here. The project contains the final version of the example used throughout this post.

The idea from here on is to add more features and more general Game Actions and Game Functions that could be reused in not only my current game, but in future ones or yours as well. If it is possible to reuse well tested modular pieces of code proven to work instead of writing all functionality from scratch in your game it will result in less bugs (less code = less bugs). Some examples of reusable snippets that I have already created are:

• GetUnusedGameObject — A Game Function that queries a GameObject List for an unused GameObject. If it finds one it returns it, otherwise it Instantiate a new one using a given prefab and adds it to the list.
• ChangeScene — A Game Action that loads a scene by string name.

I hope that you have enjoyed reading this blog post and that you after reading it have realized all the great things that are possible using Scriptable Objects. Would love to hear what you think about this post in the comments below. Thanks for reading! 💚 Give me some 👏 and follow me on twitter if you liked what you just read. Cheers!

Before starting, the final repo can be found here on Github.

For the creation of my new website I wanted to skip using one of the many great boilerplate repos out there (for example React Boilerplate or Create React App) and instead setting everything up myself. The main reason was that I wanted to dive deeper and get a better understanding of all the parts needed. Learning how frameworks and libraries works and being able to put them in a larger context is something that I really enjoy and is one of the things that gets me motivated and makes me grow as a developer.

There are many different choices of what techniques to use when setting up an app like this, and its therefore also a large number of different personal preferences of what to use out there. For that reason I will show how to setup a bare-boned base using React, webpack, Babel, ESLint and Prettier. From there it is easy to add the libraries you want to work with. But enough with the mumbo jumbo, lets jump into the steps to setup a React app from scratch!

Prerequisites: You need to install yarn and node on your machine in order to follow along this post. You will also need a code editor (for example VSCode).

Let there be light

The first thing we need to do is to create a directory for your project. Open your terminal and change directory to where you want your project to reside. Then create your project directory (changing “react-from-scratch” to the name of your project) and initialize a new package.json:

mkdir react-from-scratch && cd react-from-scratch && yarn init -y

Linting and code formatting

Linting and code formatting is a great way to improve the quality of the code you write, keep a common code style throughout the project and to prevent unnecessary bugs. It is a good idea to add linting and code formatting the first thing you do, so that everything created afterwards is styled and formatted correctly right away. We will use ESLint, Prettier and EditorConfig to aid us with this. ESLint is the most popular linter for javascript while Prettier is an opinionated code formatter. Prettier helps us with code style while ESLint will mainly help with errors in the code (but can also check for code style). Since both Prettier and ESLint can check for code styles it is important to be aware that it is possible to configure them with conflicting rules. Lastly, the EditorConfig file will define configuration for the editor itself. Here is a great post on StackOverflow explaining the differences between ESLint, Prettier and EditorConfig and how they work together.

Start by creating an .editorconfig file in the root folder:

touch .editorconfig

Note that some of the settings in this file will be used by Prettier and will take precedence over Prettier’s own config, for example indent_style and indent_size. Add the configurations that you want to your .editorconfig file using the docs. My config ended up like this:

Continue by installing ESLint, Prettier and some useful plugins / configs (like Airbnb’s ESLint rules) as dev dependencies to the project:

yarn add eslint prettier eslint-config-airbnb eslint-config-prettier eslint-plugin-import eslint-plugin-jsx-a11y eslint-plugin-prettier eslint-plugin-react babel-eslint --dev

Next we will add a prettier config file:

touch prettier.config.js

Add the options that you want by looking at the prettier docs. Export the options as an object in the prettier.config.js file. I used these settings:

Continue by adding an ESLint config file:

touch .eslintrc.js

This file will define all the linting rules in the project. The config file will also define that we will let ESLint run Prettier for us. Prettier’s website contains great information about integrating with ESLint. The important thing here is to add the Prettier plugin, import the prettier config created above and pass it to the rules section of the config. It is also a great idea to extend the eslint-prettier-config in order to disable conflicting rules between Prettier and ESLint. Continue by extending the Airbnb and React configs, add the React and jsx-a11y plugins, and add any other ESLint rules you want to use. I created my .eslintrc.js file by basing it of react-boilerplate’s eslint config. It ended up like this:

Tip: If you are using VSCode and are having troubles getting it setup then this is a great video to help you get it working properly.

Bundling with webpack

I chose to use webpack for bundling my React app, mainly because it is one of the most widely used out there. Start by installing the following dev dependencies:

yarn add webpack webpack-cli --dev

Side note: For a smaller web app a great alternative to webpack is Parcel. It has gained a lot of attention for its zero-configuration, something that webpack later adopted in webpack 4.

To test that bundling works create a folder called src/ and add a file called index.js. This file will serve as the entry point for the app.

mkdir src && touch ./src/index.js

Add a simple console.log statement to index.js and save the file. If you run one of the following commands webpack will now bundle your app using its default configuration for either development or production mode:

webpack --mode development
webpack --mode production

Go to the generated dist/ folder in the root of your project to take a look at the result of the bundling. Neat, we have now setup basic bundling with webpack!

Add React

Lets add React and React Dom as dependencies to your project:

yarn add react react-dom --save

In the index.js created in the last section remove the console.log statement and create a minimal React component that looks something like this:

Continue by creating an index.html file in the src/ folder.

touch ./src/index.html

Add the following markup to the index.html file:

Great you have created an entry point for your app that will render a super simple React component! However, before we can test the component we will need to setup Babel and use it together with webpack.

Setup Babel

Babel is used to transpile your javascript to syntax the target browsers will understand. For this setup we will use the new. Lets add the following dev dependencies:

yarn add @babel/core babel-loader @babel/preset-env @babel/preset-react --dev

…and babel-polyfill as a regular dependency :

yarn add @babel/polyfill --save

• @babel/core: Is doing the actual transformation of the code.
• babel-loader: Transpiling javascript files using babel-core and webpack.
• @babel/preset-env: A preset that lets you only include the polyfills and transforms needed for the browsers your app will support.
• @babel/preset-react: A preset for React plugins that for example transform JSX to function calls.
• @babel/polyfill: A polyfill that can be used to emulate a full ES2015+ environment.

If you are interested checkout this for further information about Babel plugins / presets.

Next we will create a configuration file for Babel. The configuration file will include all presets and plugins that we want to use, as well as options for the presets and plugins. Note that Babel 7 adds support for using javascript for the configuration file instead of JSON.

touch babel.config.js

Add the following to the configuration file:

The call to api.cache.invalidate tells Babel how we want to cache the configuration and will recreate plugins and discard the previous instance whenever something changes. We then specify the presets that we want to use (preset-env and preset-react). For preset-env we set useBuiltIns to usage, which means that Babel will polyfill features (using babel-polyfill) if they are used in the code and if they are not supported by the target environments (see below).

We also want to specify the browsers that we want to support. This can be done in the babel.config.js file, but it is recommended to use a .browserlistrc since it could be used by other packages. Lets create it:

touch .browserlistrc

Then add the following query to the file:

The query says that we want to support browser with a global usage percent greater than 0.25% and that are not dead. Here dead means that a browser has been without official support or updates for at least 24 months. Browserl.ist is a great resources for figuring out queries for your target browsers.

Custom webpack config

Even though webpack 4 does not require a config by default it gives one much more control over what is going on, like defining that we want to use Babel together with webpack. Start by installing the dev dependency html-webpack-plugin, which will be used to inject our javascript bundles to our index.html template created before.

yarn add html-webpack-plugin --dev

Lets continue my actually making the config files. In the root of your project, create a folder called internals and then a subfolder called webpack.

mkdir internals && cd internals && mkdir webpack && cd webpack

We will then create 3 files: webpack.base.js, webpack.dev.js and webpack.prod.js.

touch webpack.base.js webpack.dev.js webpack.prod.js

The reason behind creating 3 different configs is that we want to create different configurations for production and development, but also share some configuration that are common between the two (webpack.base.js). First of, the base config will look like this:

The config exports a function that takes options as a parameter (here we will later pass our development or production config) and returns a webpack config object. Here is an explanation of the different configuration options:

• mode: Tells webpack to optimize for development or production (default).
• entry: The entry point of the application.
• module: Defines how different modules in the project will be treated. Here we specify that we want to run and transform all javascript files in the project, excluding files in node modules, through Babel.
• devServer: Options used by webpack-dev-server.
• plugins: List of plugins that customize the webpack build process. Here we add html-webpack-plugin, which will inject a script tag referencing the main bundle to index.html.

Continuing, the webpack.dev.js will look like this:

Here we use the base config file and specify mode to development, pass options to the dev server (see below) that we want Hot Module Replacement (HMR) and add the actual plugin for hot module replacement. HMR exchanges, adds and removes modules while an application is running without a full reload, which speeds up development vastly. More info on HMR can be found here.

The initial setup for the production config looks like this:

Here we change mode to production, remove HMR from the dev server and add dist/ as the content base for the dev server, which means that the server will serve the static files from there. When defining content base like this a recompile will trigger when files in the src/ folders are modified and saved. At this point the advantage of the split between the development and production configs might not be crystal clear, but it will become useful while the project grows and we want to add new webpack plugins to the configs.

It is now possible to use the configs when bundling by running the following commands (from the root of the project):

webpack --config internals/webpack/webpack.dev.js
webpack --config internals/webpack/webpack.prod.js

Server

We need to setup a development server when developing the app. webpack provides a development server called webpack-dev-server that provides live reloading. Lets install it:

yarn add webpack-dev-server --dev

It is now possible to run the app on port 3000 with HMR (specified in the webpack.dev.js) by issuing the following command:

webpack-dev-server --config internals/webpack/webpack.dev.js

Or run the app in production mode:

webpack-dev-server --config internals/webpack/webpack.prod.js

Add scripts to package.json

It is a good idea to add the commands mentioned above to the script tag in your package.json. This makes it possible to run them using yarn <commmand>, eg. run yarn start to run the app in development mode. I added scripts for start, start:prod and build to my package.json.

Where to go from here

Hurray! 🎉 We have successfully created a very basic setup for a React app using webpack, Babel, Prettier and ESLint. This is of course a very bare-boned setup, but this is a good base to start from. Below I will provide some suggestion on where to go from here.

Styling

The most straight forward way of adding styling to your app is to install css-loader and style-loader as dev dependencies and add them to your webpack base config. I did left this out since I prefer using Styled Components for styling, which is a popular CSS in JS framework.

Routing

I would suggest using react-router for routing in your app. Its using a concept called “Dynamic Routing” instead of the more classic “Static Routing”. More info can be found here.

State management

When it comes to a global state container Redux is one of the most solid choices. My suggestion is to wait using Redux until you actually need it instead of throwing it in your app right away.

Unit testing

Jest is a great choice for unit testing. It is developed by Facebook so it is working well together with React. Here is a guide on how to set it up in a React app.

Like mentioned in the beginning of this post, the full project can be found here on Github.

That’s it! Slap that clap button if you found this post useful. Thanks for reading ❤