t1k:unity:base:jobs-burst
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| Tools | — |
Keywords: burst inspector, burst without dots, burst without entities, c# job system, hot loop, ijobparallelfor, jobhandle, jobs without dots, tempjob, unity job system
How to invoke
Section titled “How to invoke”/t1k:unity:base:jobs-burstUnity Jobs + Burst Without DOTS
Section titled “Unity Jobs + Burst Without DOTS”Not the DOTS skill. This covers Jobs and Burst used on their own, from ordinary
MonoBehaviourcode, in a project that does not use Entities. ForIJobEntity,SystemAPI,EntityCommandBuffer, baking and SubScenes seet1k:unity:dots-core:jobs-burst.
The thing most people get wrong
Section titled “The thing most people get wrong”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.
What Burst refuses to compile
Section titled “What Burst refuses to compile”This is why you cannot simply decorate existing gameplay code. A Burst job must be blittable:
| Not allowed in a job | Use instead |
|---|---|
class, any managed reference | struct with value fields |
List<T>, Dictionary<K,V>, arrays | NativeArray<T>, NativeList<T>, NativeHashMap<K,V> |
string | FixedString64Bytes and friends |
throw / try-catch | return a sentinel, or validate before scheduling |
| virtual / interface dispatch | concrete static calls, or FunctionPointer<T> |
UnityEngine.Object, transforms, components | copy 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.
The shape
Section titled “The shape”[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 tooRules that prevent the common failures:
- One index, one writer.
IJobParallelForgives 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 needsNativeArray<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
NativeArraysurfaces as a leak report at domain reload, far from the code that caused it. - Pick
innerBatchCountdeliberately. 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 theJobHandleand let the caller overlap real work with it. Never hand a caller an incomplete handle plus the array.Allocatorchoice:Temp(1 frame, fastest, job-unsafe),TempJob(≤4 frames, the default for scheduled work),Persistent(lifetime-managed, slowest to allocate).
Verify it is actually Bursting
Section titled “Verify it is actually Bursting”Compiling is not evidence the job was Burst-compiled — a job that silently fails to compile still runs, as slow managed code.
- Jobs → Burst → Open Inspector — if the job is absent, it is not being compiled.
- Jobs → Leak Detection → Enabled With Stack Trace while developing.
- Jobs → Burst → Safety Checks on in the editor, off when measuring.
- Measure on device, not in the editor. Editor timings include safety checks and no
optimisation;
t1k:unity:editor:profilingcovers 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.
Hard rules
Section titled “Hard rules”- Test assembly needs the refs too. Adding
Unity.Burstto the runtime asmdef but not the test asmdef gives a green runtime build and a test assembly that will not compile. internaljob types are invisible to the test assembly unless the assembly shipsInternalsVisibleTo. Match whatever the surrounding assembly already does rather than adding a lone exception.math.sqrtisUnity.Mathematics, notSystem.Math.System.Mathis 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
.csfiles need their.metacommitted. A.cswithout its.metagets a fresh GUID on every machine.
Related
Section titled “Related”code-conventions-unity.md— this kit’s C# conventionsreproducible-on-every-machine-unity.md— why transitive deps get declaredt1k:unity:editor:profiling— on-device measurement- DOTS/ECS is a different subject. If you genuinely want Entities,
ISystem, baking and SubScenes, that ist1k:unity:dots-core:jobs-burst(moduledots-core), not this skill.