{"id":80872,"date":"2018-09-17T22:28:52","date_gmt":"2018-09-17T22:28:52","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=80872"},"modified":"2021-07-29T19:44:12","modified_gmt":"2021-07-29T19:44:12","slug":"introducing-the-unity-job-system","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/development\/dotnet-development\/introducing-the-unity-job-system\/","title":{"rendered":"Introducing the Unity Job System"},"content":{"rendered":"

Made available to everyone starting with Unity 2018.1, the C# Job System allows users to write multithreaded code that interacts well with Unity. For many Unity users, this was a big deal. Better performance is so important to many people playing video games that players will often set their game’s graphics settings to something low so that the game will run optimally. But who says you have to force players to tweak their game’s settings to get the performance they want? Why not have peak performance from the start?<\/p>\n

\nWith Unity’s C# jobs, this is made much easier for the developer. This is especially true if you plan to create a game that requires many objects in the game\u2019s world, with all of them doing something at the same time. Normally, this would be incredibly taxing for the machine running this game, but thanks to the newly implemented Job System, you can now more easily achieve this scenario without taking a performance hit. Unity’s C# jobs have been touched on before back when Unity 2018.1 was first released<\/a>, but it only went skin deep. This time jobs will be explained in much more detail along with a tutorial showing you how to create a job that moves 3,000 cubes around in a scene. Note: you may need to adjust this number depending on the power of your computer.<\/p>\n

Setting Up<\/h2>\n

Once you’ve started Unity, create a new project.<\/p>\n

<\/p>\n

Figure 1: Creating a new project.<\/p>\n

After that, name the project 3000Cubes. <\/em>Then set your file path of choice. You’ll also want to make sure you’re using the 3D project template. After this has been done, click Create Project<\/em>.<\/p>\n

<\/p>\n

Figure 2: Setting project name, location, and template.<\/p>\n

Unity will then do some work, then present you with a blank project like that shown in Figure 3.<\/p>\n

<\/p>\n

Figure 3: A new blank project<\/p>\n

Believe it or not, there are only two things that need to be done before jumping into the code. First, in the Hierarchy <\/em>menu, click the Create <\/em>button and select Create Empty <\/em>to create a new object.<\/p>\n

<\/p>\n

Figure 4: Creating a new object.<\/p>\n

Name this object JobObject<\/em>. After that, with JobObject<\/em> selected in the Hierarchy<\/em>, click the Add Component <\/em>button in the Inspector <\/em>window. In the window that appears, scroll to the very bottom and select New Script<\/em>.<\/p>\n

<\/p>\n

Figure 5: Creating and adding a new script component.<\/p>\n

In the next window, name this script CubeMovementJob, <\/em>then click Create and Add<\/em>.<\/p>\n

<\/p>\n

Figure 6: Naming the script and creating it.<\/p>\n

With that finished, JobObject <\/em>should now look like what’s shown in Figure 7.<\/p>\n

<\/p>\n

Figure 7: JobObject <\/em>with the new script attached.<\/p>\n

Setup is now complete! Yes, even the process of setting up a project is made faster thanks to Unity jobs. In the Inspector <\/em>window, double click the Script <\/em>field in the newly added Cube Movement Job <\/em>component to open up Visual Studio and create your new C# job!<\/p>\n

The Code<\/h2>\n

This project aims to show you two things: the first is to show how to create jobs. The second is to show off how much of a boost using C# jobs can give you compared to what you might usually do. Before declaring variables and creating your first job, you will need to enter some using statements. At the top of the script, before the class declaration, add the following lines of code:<\/p>\n

using UnityEngine.Jobs;\r\nusing Unity.Collections;\r\nusing Unity.Jobs;<\/pre>\n
UnityEngine.Jobs<\/code> and Unity.Jobs<\/code> are required to access and utilize the job functionality in your script. They’ll also be required for certain variables you will declare later. Unity.Collections<\/code> allow you to make use of the NativeArray<><\/code> struct type, which will be required when working with C# jobs. Next, declare the following variables:<\/p>\n
public int count = 3000;\r\npublic float speed = 20;\r\npublic int spawnRange = 50;\r\npublic bool useJob;\r\nprivate Transform[] transforms;\r\nprivate Vector3[] targets;\r\nprivate List<GameObject> cubes = new List<GameObject>();\r\nprivate TransformAccessArray transAccArr;\r\nprivate NativeArray<Vector3> nativeTargets;<\/pre>\n
The first four public variables will be used to dictate how many cubes will be spawned, the speed at which it moves, the range that the cubes can be spawned in, and, finally, if you wish to use C# jobs or not. They have been made public so that they can be edited later from within the Unity editor in case you wish to add more cubes or increase the area they can spawn in. After these have been declared, a handful of private arrays will be created. The first two, transforms<\/code> and targets<\/code>, <\/em>are arrays that will store the transform<\/code> and Vector3<\/code> data of the various cubes you create.<\/p>\n
Next, you’ll have a new List <\/em>named cubes<\/em>, followed by the creation of the TransformAccessArray<\/code> and a NativeArray<Vector3><\/code>. Cubes<\/code> will simply be a list kept of all the cubes spawned and will be used later when creating the same project in non-job code. Then there’s transAccArr<\/code> and nativeTargets<\/code>. <\/em>These two arrays will store the information gathered from transforms<\/code> and targets<\/code> and send them to the job you shall soon create. But why can’t we use the transforms<\/code> and targets<\/code> arrays instead? This is because, according to Unity’s own debugger, the type of Transform<\/code> and Vector3<\/code> is not a value type, and jobs cannot contain any reference types. Put simply, jobs can only work with other structs, which Transform<\/code> and Vector3<\/code> are not.<\/p>\n
So now you may be wondering why you would declare those first two arrays at all? They will be needed to fill the transAccArr<\/code> and nativeTargets<\/code> arrays, as you cannot simply add a new item to a TransformAccessArray<\/code> and NativeArray<\/code>. Instead, you will fill the transforms<\/code> and targets<\/code> arrays then hand the data over to transAccArr<\/code> and NativeTargets<\/code> to put to use in the job. In addition, you’ll also want them for later in the project when you use non-job code to perform the same task.<\/p>\n
Quite a bit of explanation to be done here! Let’s take a break and see where your code should be now.<\/p>\n
<\/p>\n
Figure 8: All using statements and variable declarations.<\/p>\n
Now seems like a good time to create the C# job. Underneath your variable declarations, add the following:<\/p>\n
struct MovementJob : IJobParallelForTransform\r\n{\r\n\tpublic float deltaTime;\r\n\tpublic NativeArray<Vector3> Targets;\r\n\tpublic float Speed;\r\n\tpublic void Execute(int i, TransformAccess transform)\r\n\t{\r\n\t\ttransform.position = Vector3.Lerp(transform.position, Targets[i], deltaTime \/ Speed);\r\n\t}\r\n}<\/pre>\n
Let’s break this down. For starters, all jobs are structs<\/code> and must inherit from either IJob<\/code>, <\/em>IJobParallelFor<\/code> or <\/em>IJobParallelForTransform<\/code>. In this case, it\u2019s inheriting from IJobParallelForTransform<\/code> because you will use this job to move objects, which IJobParallelForTransform<\/code> allows you to do.<\/p>\n
Next, a few variables are declared. The first, deltaTime<\/code>, <\/em>will simply keep track of what is currently in Time<\/code>.<\/em>deltaTime<\/code>. You can’t simply say Time<\/code>.<\/em>deltaTime<\/code> in the job, so you get the value of deltaTime<\/code> and store it as a float <\/em>in the job. Next is a NativeArray<\/code> that will store an array of Vector3s<\/code> called Targets<\/code>. Finally, there’s another float<\/code> named Speed<\/code>, <\/em>which will simply get the value of the public variable speed<\/code>.<\/p>\n
Then comes the interesting part. Execute<\/code> is a function all jobs are required to have. As you may have guessed, whatever is inside Execute<\/code> is what the job will actually do. In this case, you have the job doing a simple task. It will get all the cube objects and have them Lerp<\/code> (meaning to smoothly move from one position to the next) from one point to another at a certain speed. Within the () <\/em>of the Execute<\/code> function lies two parameters, an integer simply named i<\/code>,<\/em> and a TransformAccess<\/code> simply named transform<\/code>.<\/em> The variable i<\/code> will be treated much like i<\/code> would if this were a for loop<\/code>, and transform<\/code> will contain a given object’s transform.<\/p>\n
At this point, the script should now look something like what’s shown in Figure 9.<\/p>\n
<\/p>\n
Figure 9: Your new C# job!<\/p>\n
Before working on the Start<\/code> and Update<\/code> functions, there are two more variables to declare, and they’re both important to the job you just created. Beneath your new job and above the Start<\/code> method, enter these lines:<\/p>\n
private MovementJob job;\r\nprivate JobHandle newJobHandle;<\/pre>\n
The first variable is pretty simple. You’re simply declaring a reference to the MovementJob<\/code>. <\/em>After that you declare a JobHandle<\/code> that you’ll just call newJobHandle<\/code>. A JobHandle<\/code> is almost exactly what it sounds like. It handles jobs, doing so by scheduling and completing the jobs you assign it. With everything declared and ready to roll, it’s time to work on the Start<\/code> function.<\/p>\n
transforms = new Transform[count];\r\nfor (int i = 0; i < count; i++)\r\n{\r\n\tGameObject obj = GameObject.CreatePrimitive(PrimitiveType.Cube);\r\n\tcubes.Add(obj);\r\n\tobj.transform.position = new Vector3(Random.Range(-spawnRange, spawnRange), Random.Range(-spawnRange, spawnRange), Random.Range(-spawnRange, spawnRange));\r\n\tobj.GetComponent<MeshRenderer>().material.color = Color.green;\r\n\ttransforms[i] = obj.transform;\r\n}\r\ntargets = new Vector3[transforms.Length];\r\nStartCoroutine(GenerateTargets());<\/pre>\n
You create the Start<\/code> function by first taking the transforms<\/code> array and creating a new array of Transform<\/code> with count<\/code> defining the number of elements in the array. Count<\/code> is the variable that keeps track of how many cubes you will spawn. Speaking of which, the next part of the function has you creating a for loop<\/code>. Within this for loop<\/code>, you create a cube<\/code>, add it to the cubes<\/code> list, give it a random starting position, and give it a green color. Of course, feel free to change the color if you wish.<\/p>\n
After that, the transforms<\/code> array gets its next value by getting the recently created cube’s transform. This process continues until every cube is spawned. Then, the targets<\/code> array gets a new array of Vector3<\/code> using transforms<\/code>.<\/em>Length<\/code> to define the number of elements within this array. Finally, a Coroutine<\/code> will be run to fill the targets<\/code> array. But that Coroutine<\/code> has not yet been defined, so no doubt Visual Studio will start telling you it has no idea what this is. It’s now time to create this Coroutine<\/code>, but first, check to make sure your code looks like Figure 10 below.<\/p>\n
<\/p>\n
Figure 10: The Start <\/em>function and the final variable declarations.<\/p>\n
A Coroutine<\/code> is created by creating an IEnumerator<\/code>. <\/em>It then operates very similarly to a function except that it can pause execution and return control to Unity, but then carry on wherever it left off on the next frame. It is required that a yield return statement is included somewhere within the body of the Coroutine<\/code>. <\/em>The yield return line is the point when an execution pauses and can be resumed in the following frame. Now that you know what a Coroutine<\/code> is, it’s time to create one! Place the following code underneath the Update<\/code> function.<\/p>\n
public IEnumerator GenerateTargets()\r\n{\r\n\tfor (int i = 0; i < targets.Length; i++)\r\n\t\ttargets[i] = new Vector3(Random.Range(-spawnRange, spawnRange), Random.Range(-spawnRange, spawnRange), Random.Range(-spawnRange, spawnRange));\r\n\tyield return new WaitForSeconds(2);\r\n}<\/pre>\n
In this case, your GenerateTargets<\/code> coroutine will simply create the cubes within the range you specify. This is among one of the simpler tasks you can do with coroutines. You can also create a typewriter effect with text and more using coroutines. Now, move on to the Update<\/code> function and input this code.<\/p>\n
transAccArr = new TransformAccessArray(transforms);\r\nnativeTargets = new NativeArray<Vector3>(targets, Allocator.Temp);\r\nif (useJob == true)\r\n{\r\n\tjob = new MovementJob();\r\n\tjob.deltaTime = Time.deltaTime;\r\n\tjob.Targets = nativeTargets;\r\n\tjob.Speed = speed;\r\n\tnewJobHandle = job.Schedule(transAccArr);\r\n}\r\nelse\r\n{\r\n\tfor (int i = 0; i < transAccArr.length; i++)\r\n\t\tcubes[i].transform.position = Vector3.Lerp(cubes[i].transform.position, targets[i], Time.deltaTime \/ speed);\r\n}<\/pre>\n
Your Update<\/code> function will do one of two things depending on the value of the useJob<\/code> boolean<\/code>. If you set it to true, then your project will utilize the job you created to move the various cubes around the scene. When using jobs, you create a new instance of MovementJob<\/code> and assign the different variables in the job. Next, you utilize the JobHandle<\/code> called newJobHandle<\/code> to schedule the job you created. When scheduling the job, you give transAccArr<\/code> as the TransformAccessArray<\/code> that the job will use in its Execute<\/code> function.<\/p>\n
If you set useJob<\/code> to false, then the program will instead accomplish the same task without using the C# job system. You’ll see later that, especially with many objects in the scene at once, that using jobs can greatly improve your project’s performance at runtime. Once you’re finished, the Update<\/code> function and GenerateTargets<\/code> coroutine should look similar to the figure below.<\/p>\n
<\/p>\n
Figure 11: The Update <\/em>function and GenerateTargets <\/em>coroutine.<\/p>\n
There is still one last task to complete before you can test out the project. Between the Update<\/code> function and GenerateTargets<\/code> coroutine, create a new function called LateUpdate<\/code> and give it the following code.<\/p>\n
private void LateUpdate()\r\n{\r\n\tnewJobHandle.Complete();\r\n\ttransAccArr.Dispose();\r\n\tnativeTargets.Dispose();\r\n}<\/pre>\n
There’s not much to this code, but it’s important to include this function to properly finish jobs and prevent memory leaks. LateUpdate<\/code> is called whenever all Update<\/code> functions have been called. It can be useful to order script execution. Some examples of where LateUpdate<\/code> can be used include moving a camera or, in your case, disposing native collections. There’s also the act of calling newJobHandle's<\/code> Complete<\/code> function. This function simply ensures that the job has been completed before moving on to another job you may give Unity. Once you’ve added this code, your script should look like this:<\/p>\n
<\/p>\n
Figure 12: Script with LateUpdate <\/em>added.<\/p>\n
The time has now come to finish this project. Save your code and return to the Unity editor.<\/p>\n
Finishing the Project<\/h2>\n
Much like the setup, finishing the project has very little to it. Select jobObject <\/em>in the Hierarchy <\/em>window, then navigate to the Inspector <\/em>window and check out the Cube Movement Job <\/em>script component. All the variables shown dictate the number of cubes spawned, how quickly they move, and the range that they can spawn in. There is also a checkbox that toggles your useJob <\/em>boolean to true or false. For the moment, leave this boolean<\/code> as false (unchecked). The rest of the variables can be left at their default values if you wish, but the example will assume you kept the cube count at 3,000.<\/p>\n
<\/p>\n
Figure 13: The complete CubeMovementJob <\/em>script component.<\/p>\n
Before playing the project, it would be helpful to open the Profiler <\/em>window to view the performance of your project. To do this, click Window->Analysis->Profiler <\/em>or simply press Ctrl + 7. Place the profiler anywhere you wish on your screen.<\/p>\n
<\/p>\n
Figure 14: Opening the Profiler <\/em>window.<\/p>\n
After you’ve pulled up the Profiler <\/em>window, save your project. If your computer finds itself unable to handle 3,000 cubes, it could lead to Unity crashing. Saving the project will, therefore, prevent any time and effort being lost. Should Unity crash, lower the number of cubes created. Begin the project by clicking the Play <\/em>button at the top of the editor.<\/p>\n
<\/p>\n
Figure 15: Starting the project.<\/p>\n
While the project runs, click anywhere in the top part of the Profiler <\/em>window to view more information about how much time it takes to do specific tasks. The blue area in the Profiler <\/em>window represents how much CPU usage is going towards performing the tasks in your script.<\/p>\n
<\/p>\n
Figure 16: Unity Profiler when not using jobs. Time to finish script functions is 4.2 ms.<\/p>\n
Remember, you should have it set up where you are currently not using jobs. Now, either pause the project or stop it to go back and set the useJob <\/em>boolean to true, then run your program again to see the difference.<\/p>\n
<\/p>\n
Figure 17: Unity Profiler while using jobs. Time to finish script functions is now 2.89 ms.<\/p>\n
Notice how when using jobs, the amount of time the CPU takes to complete the task is cut almost in half. The difference is even more noticeable when increasing the number of cubes to spawn. On my computer, when increasing the number of cubes to 10,000 and not using jobs, the process could take 18 ms. Utilizing jobs in the same set of circumstances brought that time down to 13 ms. Of course, how much of a performance improvement one sees can depend on their individual CPU and what its capabilities are. Regardless, there’s no denying the improved performance that came once C# jobs entered the picture.<\/p>\n
<\/p>\n
Figure 18: The finished project in action.<\/p>\n
Conclusion<\/h2>\n
Multi-threaded code offers better performance to the developer though can be difficult to write. Thanks to Unity Technologies’ latest offerings, creating multi-threaded code is more easily achievable for the developer. Though situations demanding the C# job system may vary, the performance boost it can bring is immense. Another new tech for Unity, the Entity Component System, can also be utilized to further increase performance. \u2019Performance by default\u2019 is the tagline for Unity 2018, and it’s easy to see why.<\/p>\n
Some examples of where the job system can be put to great use include battle simulators, ocean simulators, and more. This example shows the job system moving around objects in a scene but can also be used to deform meshes and other tasks. Many tasks with a heavy load on your CPU can be lightened thanks to C# jobs, and it all starts by simply creating a struct and inheriting from a job interface.<\/p>\n","protected":false},"excerpt":{"rendered":"
Performance is important to video game players. If a game is slow, the player may experience unintended difficulties in timing, positioning, and much more. Unity added a job system with the 2018.1 update which allows multithreaded code which can improve performance. In this article, Lance Talbert walks you through using the new job system.…<\/p>\n","protected":false},"author":317499,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[143538,53],"tags":[],"coauthors":[52549],"class_list":["post-80872","post","type-post","status-publish","format-standard","hentry","category-dotnet-development","category-featured"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/80872","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/317499"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=80872"}],"version-history":[{"count":4,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/80872\/revisions"}],"predecessor-version":[{"id":80892,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/80872\/revisions\/80892"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=80872"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=80872"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=80872"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=80872"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}