Undocumented (but public) DefaultExecutionOrder attribute

There's an undocumented DefaultExecutionOrder attribute for which I don't find any documentation. Is it supposed to work or is it considered internal and subject to change?

Code (CSharp):

1. [DefaultExecutionOrder(100)]
2. public class SomeClass : MonoBehaviour
3. {
4. }

 

It works, I'm using it right now. I googled it because I want to know if the default is 0, why is it undocumented? Weird.

 

The employees should put this in documentation because when I search this, there are very few results and even the top result is not even showing that it can be used in the script!

 

I can confirm that the default value is 0.

Awake () of a script with [DefaultExecutionOrder(-1)] runs before Awake () of the rest, in the same frame, for example.

This is great for managers.

 

This is used in the NavMeshComponents high level API.
I am guessing it is some sort of ranking order for when to run scripts.
This one is collecting a bunch of meshes and terrains into lists so it can dynamically build a navmeshes on them at runtime.
It chooses [DefaultExecutionOrder(-200)] as its rank, although I could swear I have seen some with [DefaultExecutionOrder(10000)], so I think [DefaultExecutionOrder(10000)] means as "last" as possible, and [DefaultExecutionOrder(-10000)] means as "first" as possible.

I think the numbering is done "roughly", as it is rarely explicitly queued more than once or twice anyway, so no need to try to keep track of integers.

this is the first result from Bing
https://docs.unity3d.com/Manual/ExecutionOrder.html

 

Official Unity FAQ from the NavMeshComponent high level API:
https://github.com/Unity-Technologies/NavMeshComponents

Q: What's the deal with the 'DefaultExecutionOrder' attribute?
A: It gives a way of controlling the order of execution of scripts - specifically it allows us to build a NavMesh before the (native) NavMeshAgent component is enabled.

 

It's still undocumented in the built-in attributes section. Some other attributes might be too, I'm not sure.
Here is an example of one that is documented:
https://docs.unity3d.com/ScriptReference/HideInInspector.html
On the left you can see others documented but some are missing.

How can I add documentation? Is that even possible?
Edit: I submitted it as a suggestion on the docs page.

 

I think this attribute is incredibly useful and should be documented.

Specifically in my case, i actively searched for a way to set the execution order from code, because sometimes unity crashes and some gamobject's scripts need to be re-added. If these are also part of the script execution order, they get removed from it.
Having it in code is safer, but the script execution order documentation page does not show a way of determining the order in code in any way.

 

obviously they should, when is this getting fixed?

 

That's a joke right? It has to be a joke because "it works but the effect is hidden" is an extremely good reason to document something, not an excuse to skip it. Documentation needs to answer questions such as "My script with a [DefaultExecutionOrder] is not showing in the Execution Order window so is it actually working?" and "This attribute is undocumented so how do I know if it's reliable?". If you don't properly document things like then every individual user needs to waste time testing it to make sure it does what they want (and then they just have to hope it will reliably keep working).

Yeah, I wish.

Take a look at this bug report: https://issuetracker.unity3d.com/issues/iserializationcallbackreceiver-example

The person handling the bug report took the time to figure out exactly what needs to be changed to fix it ... but evidently that's not enough detail because they marked the issue as "Won't Fix".

Does that make sense to you? You have an example that is known to not work and the documentation team couldn't even be bothered to copy and paste some code. So instead, you again waste the time of everyone who tries to use that example as well as more QA time if anyone else sees it and reports another bug.

I'm pretty sure I also re-reported the issue using the suggestion function at the bottom of the page, but there's no record of that and it was years ago now so I can't be sure. I guess encouraging people to do it that way instead of reporting bugs through the engine is a convenient way of avoiding the need to tell people that you're ignoring their reports.

 

It would be a simple fix for them to have it show up in the UI as well. Just update the Script Execution Order data to have a private

isSetFromCode

bool. That way if this bool is set, then during compilation Unity can check whether those marked classes still have the attribute or not, or if the value has changed.

This would not be a breaking change to Unity either, since upon script recompile, the private bool would get updated accordingly for any classes that currently have this attribute, and from then on if attribute is removed, entry is removed from script execution order UI. This shouldn't affect any existing systems...

 

MAYBE just maybe try and make the results visible in the window then???

It's been 14 months since I reported it in the Show Us Your Pain thread. How quickly are we talking about?

 

Please add docs to this thing.

 

I'm searching and searching but looks like it is still not in Manual.
Is it safe to use this attribute ?

 

Yes, lots of assets use it.

 

How's that real work coming along?

 

I have a question about this.

I don't always BUILD my game project from the Editor for some reasons not relevant to this discussion, I often just work from Visual Studio and hit the Build button there to compile my game's main DLL.

Will the Attribute work? or this Attribute works together WITH the Editor and make some Shenanigans behind the scenes adding stuff into the game data?

Because I had a massive issue with this, related to the Input system, which ONLY WORKS when building from the Editor because it serializes a lot of stuff.

So, for my use case, will this Attribute respect the code, or will it look for a Serialized list in the game's data file?

 

I wish everything we do in the Editor was POSSIBLE to do from code ALWAYS, I find it extremely bad that things need to get serialized by the Editor in the moment of Build. It makes the game Static and immutable, which is sad. :-\

 

I'm no expert on this but I think Unity should do the compiling and not Visual Studio. In the context of the editor, Unity is the compiler, not Visual Studio, which is mostly a glorified text editor.

If you need the .dlls for your project they live in the library folder.

 

I am 99% sure you misunderstood me, but like you said, I guess I probably should not ask you.

 

You are 50% correct, Unity uses the same compiler Visual Studio does, for the C# code. CSC.

What the Editor "compiles" is the Serialized metadata that goes with the game, and a lot of things goes into this meta data, including the Execution Order, which makes it impossible to be changed after the game has been built.

This is what I am referring to, perhaps you don't know enough or I was not clear enough in my question for you to be able to answer me.

 

Haha sorry, I know this sounds Unorthodox, but we need to go out of the Box some times and do things in ways that are not expected.

So the workflow goes like this.

I make the game in Unity Editor and then build it with the Script Order already set.

My game have Mod Capability, and that works by loading up custom made DLLs using a specific Interface.

I want to use that Attribute to add to the Order the class that is made in that said Mod.

I already know that this wont work, because as I said before, Unity serializes this Order list inside the game's Metadata, and that is Read Only.

What I wanted, was that the Attribute was actually something that would be considered when the Game starts, and not be a Read Only list serialized in the Game's metadata.

I hope this is easier to be understood now.

 

I solved this in my own way, by just making my own Update() methods list, so I can set their Order of Execution myself and centralize and remove the C++ Cross Barrier cost in the process.

All I was asking was for a Flexible Unity way to solve this, but it does not exist, even tho the Attribute exists, it is only for the Editor, not for Runtime.

 

@MelvMay Thanks for all that you've already done on this Issue. I know you have other things to worry about, but unfortunately you do seem to offer the community's only visibility into the state of this issue... Anyway, looks like

DefaultExecutionOrder

is still not documented in the Unity manual or in the XML docs of UnityEngine's API. Do you happen to know if there's been any progress on this documentation ticket?

 

And a year later we still don't have it documented and the ticket is still hanging around a year and a bit later.

Honestly, I don't know how many people make up the documentation team or what their priorities are, but in the last few years I have seen how small tasks like this or even smaller ones (example: typo), take more than a year to be done.

 

Anyone know how long a similiar small issue in UE takes to get fixed?

 

I mean, UE doesn't even document most of its code, so I'm not sure these are the greatest comparisons. Unity's documentation is miles ahead of UE, despite this tiny niche issue here.

 

Up to several years. UE has worse documentation overall, and (IIRC) for a time they didn't even store archive of the docs for previous engine versions, only for the latest. That was "fun".

By the way the record time for a responding to a bug I personally witnessed was several years. At some point I submitted a bug report to Qt, and it took 3 years for them to respond.

 

Still undocumented....

 

It's not like they have to write it themselves anymore either...

Spoiler: GPT-3.5 generated documentation

DefaultExecutionOrder Attribute
The [DefaultExecutionOrder] attribute sets the default execution order of a script in Unity. When a script with this attribute is attached to a GameObject, Unity will assign it an execution order value based on the value specified in the attribute.

Syntax

Code (csharp):

1. [DefaultExecutionOrder(order)]

Description
The [DefaultExecutionOrder] attribute is used to ensure that scripts that depend on each other are executed in the correct order.

Parameters

• order (int): The execution order value to assign to the script.

Remarks

• When multiple scripts have the same execution order value, Unity will use the script's name to determine the final execution order.
• The execution order can be set to any integer value, including negative values.

Examples
Setting the default execution order of a script

Code (csharp):

1. using UnityEngine;
2.  
3. [DefaultExecutionOrder(1)]
4. public class MyScript : MonoBehaviour
5. {
6.    // ...
7. }

In this example, the MyScript class has been assigned an execution order value of 1. When attached to a GameObject, it will be executed before any scripts with a higher execution order value.

Setting the default execution order of a script based on the name

Code (csharp):

1. using UnityEngine;
2.  
3. [DefaultExecutionOrder(-1)]
4. public class CameraController : MonoBehaviour
5. {
6.    // ...
7. }

In this example, the CameraController class has been assigned an execution order value of -1. When attached to a GameObject, it will be executed after any scripts with a lower execution order value. If there are multiple scripts with an execution order value of -1, Unity will use the script's name to determine the final execution order.

See Also

• Execution Order of Event Functions
• Script Execution Order

 

You'd still need a human to check generated docs for hallucinations.

 

Did someone from Unity QA opened Script Execution order settings in the real project?



First of all you simply can't scroll this list.
Secondly, I have like 2000+ classes in the project. How on earth I should use this interface, to find a class that I need?

 

Well, first of all as Melv said this wasn't the topic of this thread. Apart from that you actually can scroll that list by moving your mouse on the very bottom of that list (there's a small down arrow, at the top is an up pointing arrow). However as you said the usage of those context menu style selection is not very convenient.

Though if someone is looking for a way to add scripts in an easier way, you can use this quick and dirty editor window:

Spoiler: ExecutionOrderEditor.cs

Code (CSharp):

1. // /Editor/ExecutionOrderEditor.cs
2. namespace B83.UnityEditorStuff
3. {
4.     using System.Collections.Generic;
5.     using UnityEngine;
6.     using UnityEditor;
7.  
8.     public class MonoScriptItem
9.     {
10.         public MonoScript script;
11.         public int execOrder;
12.         public string ns, className, classNameLower;
13.         public string GetName(bool aLower) => aLower ? classNameLower : className;
14.         public MonoScriptItem(MonoScript aScript)
15.         {
16.             script = aScript;
17.             execOrder = MonoImporter.GetExecutionOrder(aScript);
18.             var t = script.GetClass();
19.             ns = t.Namespace;
20.             className = t.Name;
21.             classNameLower = className.ToLower();
22.         }
23.     }
24.  
25.     public class ExecutionOrderEditor : EditorWindow
26.     {
27.         [MenuItem("Tools/B83/ScriptExecutionOrder")]
28.         public static void Init()
29.         {
30.             GetWindow<ExecutionOrderEditor>();
31.         }
32.         List<MonoScriptItem> m_Scripts = new List<MonoScriptItem>();
33.  
34.         private void OnEnable()
35.         {
36.             titleContent = new GUIContent("Execution Order");
37.             minSize = new Vector2(350, 100);
38.             var scripts = MonoImporter.GetAllRuntimeMonoScripts();
39.             m_Scripts.Clear();
40.             foreach (var ms in scripts)
41.             {
42.                 if (typeof(Component).IsAssignableFrom(ms.GetClass()))
43.                     m_Scripts.Add(new MonoScriptItem(ms));
44.             }
45.             m_Scripts.Sort((a, b) => a.className.CompareTo(b.className));
46.         }
47.         Vector2 pos;
48.         string filter = "";
49.         bool caseSensitive = false;
50.         void OnGUI()
51.         {
52.             float w = position.width * 0.3333f;
53.             string f = filter;
54.             if (!caseSensitive)
55.                 f = f.ToLower();
56.             bool colorToggle = false;
57.             var oldColor = GUI.backgroundColor;
58.             GUILayout.BeginHorizontal();
59.             filter = EditorGUILayout.TextField("Filter", filter);
60.             caseSensitive = GUILayout.Toggle(caseSensitive, "CaseSensitive", GUILayout.Width(100));
61.             GUILayout.EndHorizontal();
62.  
63.             GUILayout.BeginHorizontal("box");
64.             GUILayout.Label("Namespace", GUILayout.Width(w));
65.             GUILayout.Label("Classname");
66.             GUILayout.EndHorizontal();
67.  
68.             pos = GUILayout.BeginScrollView(pos);
69.             foreach (var s in m_Scripts)
70.             {
71.                 if (filter.Length > 0)
72.                 {
73.                     if (!s.GetName(!caseSensitive).Contains(f))
74.                         continue;
75.                 }
76.                 GUI.backgroundColor = colorToggle ? oldColor * 1.5f : oldColor;
77.                 colorToggle = !colorToggle;
78.                 GUILayout.BeginHorizontal("box");
79.                 GUILayout.Label(s.ns, GUILayout.Width(w));
80.                 EditorGUILayout.ObjectField(s.script, typeof(MonoScript), false);
81.                 EditorGUI.BeginChangeCheck();
82.                 s.execOrder = EditorGUILayout.DelayedIntField(s.execOrder, GUILayout.Width(100));
83.                 if (EditorGUI.EndChangeCheck())
84.                     MonoImporter.SetExecutionOrder(s.script, s.execOrder);
85.                 GUILayout.EndHorizontal();
86.             }
87.             GUILayout.EndScrollView();
88.         }
89.     }
90. }

When you open this editor window through the Tools menu, you will see a list of all scripts that are derived from Component. I'm sure there are some included which should not be there, but that doesn't really matter. You will notice that most scripts have an execution order value of "0". As soon as you assign any non-zero value to one of the scripts, it will show up in the usual script execution order settings window where you could move them around as well. Note that I added a simple search / filter at the top. So you can simply type a part of the class name you're looking for and it should show up.

Alternatively I could have just made a drag and drop area where you could drop a MonoScript in order to have it added to the list with a non-zero value. I thought that in the past the script execution order settings window actually allowed this. However it seems it doesn't (anymore?!?). Maybe my memory is messed up here. I barely used it anyways.

 

I complained about this in the Show Us Your Pain thread over a year ago and still nothing has been done. Instead of saying where we shouldnt post this complain, please share where we should post it so it results in someone fixing the F***ing thing.

 

@Innovine They said to create your own thread. Here's a link to create a new thread in this same Scripting category. Also the Unity teams are finite and have a lot on their plate (particularly after the recent layoffs I'm sure), so you can't expect them to handle every specific issue immediately.

 

The size of a team is usually not a problem. The priorities of the team and their expertise are. Otherwise other game engines would simply not exist, because Unity had one of the biggest teams on the planet for developing a game engine.

Anyway, thank god, this undocumented attribute exists and it solved my problem, so that broken UI can stay the way it is.

 

I'd like to point out that it 5 years have passed since the initial post.