Skip to content

t1k:unity:base:jobs-burst

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: burst inspector, burst without dots, burst without entities, c# job system, hot loop, ijobparallelfor, jobhandle, jobs without dots, tempjob, unity job system

/t1k:unity:base:jobs-burst

Not the DOTS skill. This covers Jobs and Burst used on their own, from ordinary MonoBehaviour code, in a project that does not use Entities. For IJobEntity, SystemAPI, EntityCommandBuffer, baking and SubScenes see t1k:unity:dots-core:jobs-burst.

Burst and the C# Job System do not require DOTS/ECS. They are standalone packages. You can [BurstCompile] a struct job and schedule it from an ordinary MonoBehaviour — no World, no ISystem, no baking, no SubScenes, no com.unity.entities.

Adopting ECS to get Burst is a large architecture change bought for a capability you already have. Check packages-lock.json before assuming you need to install anything: in a project depending on almost any TheOne package, com.unity.burst, com.unity.collections and com.unity.mathematics are usually already resolved transitively.

Declare the packages, even when they already resolve

Section titled “Declare the packages, even when they already resolve”

A transitive dependency (depth: 1 in packages-lock.json) is present by luck, not by contract. If the parent package ever drops or reshuffles it, every Burst job in the project stops compiling at once, on every machine, with no obvious cause and nothing in manifest.json explaining why.

Promote them to direct dependencies, pinned to the versions already resolving so the resolve result does not change:

"com.unity.burst": "1.8.29",
"com.unity.collections": "2.6.6",
"com.unity.mathematics": "1.3.3",

Note: the pins differ between t1k-unity-base-jobs-burst and t1k-unity-dots-core-jobs-burst. com.unity.collections is a registry package on 6000.3.x (observed); the do-not-pin note applies only from 6000.5 where it becomes builtin — verify against packages-lock.json.

Then add Unity.Burst, Unity.Collections, Unity.Mathematics to the references of the .asmdef that holds the jobs — and to the test asmdef too, which is the step people forget.

Per reproducible-on-every-machine-unity.md: everything the compiler needs is declared, or it is not reproducible.

This is why you cannot simply decorate existing gameplay code. A Burst job must be blittable:

Not allowed in a jobUse instead
class, any managed referencestruct with value fields
List<T>, Dictionary<K,V>, arraysNativeArray<T>, NativeList<T>, NativeHashMap<K,V>
stringFixedString64Bytes and friends
throw / try-catchreturn a sentinel, or validate before scheduling
virtual / interface dispatchconcrete static calls, or FunctionPointer<T>
UnityEngine.Object, transforms, componentscopy the values you need in before scheduling

Consequence: an existing system built on classes, List<T> and exceptions cannot be made Burst-compatible by attribute. Write a new job beside it that takes plain arrays, and keep the managed code as the caller. Attempting an in-place conversion is where this work usually stalls.

[BurstCompile]
public struct ScoreJob : IJobParallelFor
{
[ReadOnly] public NativeArray<int> Inputs; // ReadOnly lets Burst assume no aliasing
public NativeArray<float> Results; // each index written by exactly one worker
public void Execute(int index) => this.Results[index] = math.sqrt(this.Inputs[index]);
}

Scheduling, with the discipline that actually matters:

var results = new NativeArray<float>(count, Allocator.TempJob);
try
{
new ScoreJob { Inputs = inputs, Results = results }
.Schedule(count, innerBatchCount: 64)
.Complete();
}
catch { results.Dispose(); throw; } // dispose on the throwing path too

Rules that prevent the common failures:

  • One index, one writer. IJobParallelFor gives no ordering and no synchronisation. Two workers writing one index is a data race the safety system may not catch in a release build. Accumulating into a shared total needs NativeArray<T> per-worker slots plus a serial reduce, or [NativeDisableParallelForRestriction] only when you have proven the writes are disjoint.
  • Dispose everything you allocate, on every path. A leaked NativeArray surfaces as a leak report at domain reload, far from the code that caused it.
  • Pick innerBatchCount deliberately. Too small and scheduling overhead dominates the arithmetic; too large and the final worker straggles while the rest idle. 32–128 is a sane starting range for cheap per-item work.
  • Complete() before reading the output, or return the JobHandle and let the caller overlap real work with it. Never hand a caller an incomplete handle plus the array.
  • Allocator choice: Temp (1 frame, fastest, job-unsafe), TempJob (≤4 frames, the default for scheduled work), Persistent (lifetime-managed, slowest to allocate).

Compiling is not evidence the job was Burst-compiled — a job that silently fails to compile still runs, as slow managed code.

  1. Jobs → Burst → Open Inspector — if the job is absent, it is not being compiled.
  2. Jobs → Leak Detection → Enabled With Stack Trace while developing.
  3. Jobs → Burst → Safety Checks on in the editor, off when measuring.
  4. Measure on device, not in the editor. Editor timings include safety checks and no optimisation; t1k:unity:editor:profiling covers the on-device pass.

Burst also only pays off past a threshold — a few hundred elements of trivial arithmetic will lose to a plain for loop once scheduling overhead is counted. Measure before and after; if you cannot show the delta, do not keep the job.

  • Test assembly needs the refs too. Adding Unity.Burst to the runtime asmdef but not the test asmdef gives a green runtime build and a test assembly that will not compile.
  • internal job types are invisible to the test assembly unless the assembly ships InternalsVisibleTo. Match whatever the surrounding assembly already does rather than adding a lone exception.
  • math.sqrt is Unity.Mathematics, not System.Math. System.Math is managed and will not Burst-compile.
  • Burst compiles asynchronously by default, so the first call after a domain reload may run managed. Do not benchmark the first invocation.
  • New .cs files need their .meta committed. A .cs without its .meta gets a fresh GUID on every machine.
  • code-conventions-unity.md — this kit’s C# conventions
  • reproducible-on-every-machine-unity.md — why transitive deps get declared
  • t1k:unity:editor:profiling — on-device measurement
  • DOTS/ECS is a different subject. If you genuinely want Entities, ISystem, baking and SubScenes, that is t1k:unity:dots-core:jobs-burst (module dots-core), not this skill.