When a bug consistently reproduces for one person but never does for another, or it appears in a build but not in editor or vice-versa, it may be from an undefined script order of execution bug. These bugs occur regularly if using Unity normally, and the cause is subtle. The inconsistency also makes them a pain to track down and fix. These are easily the worst type of bug out there due to their inconsistent nature. This document will explain how these bugs happen, demonstrate the reasons for inconsistency in whether they occur or not, methods for fixing them, and ways of designing your code so there’s no room for these bugs to manifest in the first place. To start, here's a simplified example of a script execution order bug, shown below:
|
class CharacterUI : MonoBehaviour
{
public UiImage activeSkill; //set in inspector
public Skills characterSkills; //set in inspector
void Start()
{
activeSkill.sprite = characterSkills.skillsKnown.primarySkill.sprite;
}
}
class Skills : MonoBehaviour
{
SkillData skillsKnown; //initialized from Resources.Load
void Start()
{
skillsKnown = Resources.Load<SkillData>();
}
}
|
For someone testing the game, they may always, consistently, get a null reference exception in Start() of CharacterUI, resulting in a broken-looking UI. For the developer and several other testers, the bug may absolutely never happen. The bug may also never happen for anyone in-editor, but does happen for some people in builds.
Why does this happen?
First, let’s establish that the CharacterUI’s Start() depends on Skills running Start() before it. Otherwise, when it would access the data within characterSkills.skillsKnown, skillsKnown would be null. With that in mind, for the above case, what actually defines the order the two Start() methods run? The order of execution for Start() between these two classes is completely undefined. Because it’s undefined, if these two objects are created at the same time at scene startup, Unity determines this order arbitrarily, and it varies between in-editor sessions and builds, and per machine! For some people the bug may always happen in editor and never in build, and others it may always in the build and never in editor, and for others it may never happen at all. This all depends on whether, for a given machine and build/editor session, Unity happens to decide if Skills runs before CharacterUI, or CharacterUI runs before Skills. While we work through the example, consider that for an actual codebase in a game, the classes involved in such a bug will be more numerous and complex.
Solutions
There's a few solutions available for our contrived example. One solution would be changing Skills to initialize on Awake(), which will always run before anything else’s Start(). But what if for your case’s current logic, both need to use Awake() or both must use Start() due to other dependencies from other classes? If both use Awake, you'd run into the same issue, as the order between the two Awake calls are undefined. If both must use Start, it’s the same as the example undefined order problem.
The general solution requires explicitly defining the script's priority/order. There's a way to do this in the project's script settings, but it's a pain to manage it there (and gets out of hand as you get into hundreds of classes), so you can instead use an attribute on the class, which looks something like [DefaultExecutionOrder(150)]. Below I show the attribute applied to the classes to fix the bug.
|
[DefaultExecutionOrder(10)]
class CharacterUI : MonoBehaviour {
public UiImage activeSkill; //set in inspector
public Skills characterSkills; //set in inspector
void Start()
{
activeSkill.sprite = characterSkills.skillsKnown.primarySkill.sprite;
}
}
[DefaultExecutionOrder(-5)]
class Skills : MonoBehaviour {
SkillData skillsKnown; //initialized from Resources.Load
void Start()
{
skillsKnown = Resources.Load<SkillData>();
}
}
|
The lower the order value, the earlier its mono methods like Start() are executed relative to other monobehaviours. Now, the execution order for the Start() calls has been defined, so Skills Start() will always run before CharacterUI's Start(). Note, this execution order affects Start, Awake, Update (and all other types of update like FixedUpdate, LateUpdate), as well as OnEnable, OnDisable. For example, the Skills’ class OnEnable() would run before CharacterUI’s OnEnable().
Note: if just one class had its order defined, such as CharacterUI’s, the bug could still occur as Skills’ order relative to it is still undefined.
Preferred Solution - Avoiding this Problem By Design
The above solution of using the DefaultExecutionOrder attribute is fine if the damage is already done and the code can’t be refactored. However, the ideal solution is to design your code in a way where this issue doesn’t have room to occur in the first place.
Solutions for this problem at a design level involves avoiding using Start() or Awake() for anything which depends on another game object's state. Instead, you should have some dedicated code in another class responsible for initializing your objects and using them together, rather than having your individual objects cross-referencing each other. As a red flag, if you require your Start() or Awake() methods to run in very particular orders between separate objects of classes in order for them to function properly, they should be redesigned so they are initialized explicitly by hand in another class. The thought process behind this is that if their initialization order is so important for them to function at all, this order deserves to be explicitly defined by hand, line-by-line, in one location, and not spread out throughout the codebase by using the DefaultExecutionOrder attribute. Let’s look into an example.
For a contrived example, imagine you have classes A, B, C, D, and E which all depend on each other in different ways in their Start() and Awake() methods. If you need to understand the order which they initialize and you’re using the DefaultExecutionOrder attribute, you’d need to go between each class and make note of their order number, then organize those order numbers lowest to highest, then separately consider how for this order their Awake()s run first, followed by their Start()s, and some classes may be missing one and have the other. There is a much clearer way - just introducing one simple class, which takes references to each involved class and explicitly initializes them in a manually defined order, passing their dependencies as arguments.
|
e.Initialize();
d.Initialize(e);
c.Initialize(d, e);
b.Initialize(e, c, d)
a.Initialize(b, c);
|
Now, the order of initialization to a developer is extremely clear by just looking at it, the dependencies between classes are also extremely clear, and very importantly, there’s also no room for undefined execution order bugs because you have explicitly defined the initialization order by hand.
Note that when defining initialization orders by hand, you may encounter things called cyclic dependencies. For example, if system A requires B to be initialized, and B requires C to be initialized, and C requires A to be initialized, there’s no possible valid order to initialize them in. Resolving cyclic dependencies can be complicated and requires some sort of refactoring, so it’s outside of the scope of this document. Resolving cyclic dependencies is the expression you’d want to use when researching solutions.
