t1k:unity:dots-core:jobs-burst
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | high |
| Tools | — |
Keywords: burst, DOTS, EntityIndexInQuery, ForEach-migration, IJobEntity, jobs, parallel, partial-struct, performance, ScheduleParallel, source-generator, WithReadOnly
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:jobs-burstUnity DOTS Jobs, Burst & Collections
Section titled “Unity DOTS Jobs, Burst & Collections”Terminology
Section titled “Terminology”- DOTS — Data-Oriented Technology Stack
- ECS — Entity Component System
- ECB — EntityCommandBuffer
- SIMD — Single Instruction, Multiple Data
Skill Purpose
Section titled “Skill Purpose”Reference for Unity’s high-performance layer: Job System scheduling, Burst native compilation, Collections memory management, and Mathematics shader-like API. Complements t1k-unity-dots-core-ecs (components, systems, queries).
Package Versions
Section titled “Package Versions”com.unity.burst1.8.28com.unity.mathematics1.3.2com.unity.collections— do not pin. Since Unity 6000.5 it is a builtin package resolved at the editor’s own version; pinning a registry version can force a downgrade from whatever the editor ships.
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.
When This Skill Triggers
Section titled “When This Skill Triggers”- Writing
IJobEntity,IJobChunk,IJob, orIJobParallelForstructs - Adding
[BurstCompile]to jobs or static methods - Allocating
NativeArray,NativeList,NativeHashMap,NativeQueue, etc. - Using
Unity.Mathematicstypes such asfloat3,quaternion,math.* - Scheduling jobs, chaining
JobHandledependencies, callingScheduleParallel - Asking about allocator lifetimes:
Temp,TempJob,Persistent - Burst restrictions: managed types, try-catch, virtual calls
- Using
SharedStatic,FunctionPointer, or[BurstDiscard]
Quick Reference
Section titled “Quick Reference”| Topic | Reference File |
|---|---|
| IJobEntity, IJobChunk, IJob, IJobParallelFor, scheduling, dependencies | jobs-guide.md (references/jobs-guide.md) |
| BurstCompile, restrictions, SharedStatic, FunctionPointer, BurstDiscard | burst-guide.md (references/burst-guide.md) |
| NativeArray, NativeList, NativeHashMap, allocators, disposal patterns | collections-guide.md (references/collections-guide.md) |
| float2/3/4, quaternion, math.*, Random, noise | mathematics-guide.md (references/mathematics-guide.md) |
| Advanced Burst — SIMD intrinsics, profile-guided optimization, platform tuning | burst-advanced-guide.md (references/burst-advanced-guide.md) |
| Advanced Collections — custom allocators, unsafe containers, parallel patterns | collections-advanced-guide.md (references/collections-advanced-guide.md) |
| IJobEntity source-gen expansion, field attributes, EntityIndexInQuery, schedule variants, ForEach migration | ijobentity-source-gen.md (references/ijobentity-source-gen.md) |
| EntityManager Burst-safety in Entities 1.x, when to still prefer ECB, structural-change invalidation | entitymanager-burst-compatibility.md (references/entitymanager-burst-compatibility.md) |
| Schedule/ScheduleParallel dependency auto-wiring by source-gen, when the implicit form is not fire-and-forget | parallel-scheduling-patterns.md (references/parallel-scheduling-patterns.md) |
Documentation
Section titled “Documentation”- Burst Manual
- Collections Manual
- Mathematics Manual
- Context7 libraries:
/needle-mirror/com.unity.burst(112 snippets),/websites/unity3d_packages_com_unity_collections_2_6(647 snippets)
Performance Anti-Patterns (NEVER DO)
Section titled “Performance Anti-Patterns (NEVER DO)”| Anti-Pattern | Why It’s Bad | Fix |
|---|---|---|
Managed API in [BurstCompile] | Silently prevents ISystem registration — no error, no warning | Use private const, SharedStatic, or Burst-safe math |
Debug.Log in Burst code | Managed call breaks compilation | Use [BurstDiscard] wrapper (NOT [Conditional] — Burst still analyzes method body) |
string operations in jobs | Managed heap allocation | Use FixedString32Bytes/64/128/512 |
List<T> in jobs | GC allocation | Use NativeList<T> with proper allocator |
Allocator.Temp in jobs | Only valid on main thread, not in jobs | Use Allocator.TempJob (frame-scoped) or Allocator.Persistent |
Complete() then Dispose() | Blocks main thread waiting for job | Use container.Dispose(jobHandle) for async disposal |
Missing [ReadOnly] on job fields | Prevents parallelization — safety system assumes write access | Add [ReadOnly] to all read-only NativeContainer fields |
Schedule() when ScheduleParallel() works | Single-threaded when could be parallel | Use ScheduleParallel for IJobEntity when no write conflicts |
Run() for heavy work | Runs on main thread, blocks frame | Use Schedule/ScheduleParallel for >100 entities |
| Boxing value types | Hidden GC allocation | Avoid casting structs to object or interfaces |
UnityEngine.Physics.gravity | Managed API, breaks Burst | private const float Gravity = -9.81f |
UnityEngine.Random | Managed, not Burst-safe | Unity.Mathematics.Random with entity-derived seed |
Mathf.* functions | Managed UnityEngine namespace | Unity.Mathematics.math.* equivalents |
Fifteen more narrow, incident-backed anti-patterns (illegal Burst entry points for int2/float2 | ||
statics and native-container params, managed-interface calls in OnUpdate, DynamicBuffer<T> by | ||
value, FixedString literal concat, a Debug.Log* format specifier outside G/g/D/d/X/x | ||
(BC1343), a managed string built from +-joined literals whose reflexive [BurstDiscard] fix | ||
| silently no-ops the log in the Burst path (and its test can pass or fail by whether the Editor | ||
actually Burst-compiled the call that turn), CreateArchetype params overload, one BC1028 silently | ||
disabling Burst project-wide, IJobEntity accumulator NRE, removing Unity.Burst from an | ||
all-managed asmdef, a structural change sharing an OnUpdate with a query over the same archetype, | ||
a BufferLookup<T>-triggered codegen defect corrupting an unrelated exception’s type data, | ||
SystemAPI.GetComponent<T>(entity) silently returning wrong data under Burst, and reading | ||
burst_abort_deferred() NRE breadth as a compiler-service health signal before blaming the named | ||
| system) with full error | ||
codes, root cause, and fix: references/burst-advanced-guide.md | ||
| § “Anti-pattern incident detail”. |
Key Conventions
Section titled “Key Conventions”Jobs
- To use
IJobEntity, declare apartial structand add[BurstCompile] - To filter entities, apply
[WithAll],[WithNone],[WithAny]on the struct - To chain job dependencies, always pass and assign
state.Dependency - To update
ComponentTypeHandle, do so every frame inOnUpdate, notOnCreate - Prefer
ScheduleParalleloverSchedule— split work across worker threads - Prefer
IJobEntityoverIJobChunk— cleaner API, same performance, source-generated query - Never borrow another system’s barrier — direct
ComponentLookup/BufferLookupaccess on a type a job elsewhere writes needs your OWNstate.Dependency.Complete(); relying on group sort order to make it safe breaks silently (and repeats every frame, uncaught byDOTSTestBase) on the next reorder. See jobs-guide.md (references/jobs-guide.md) § “Gotcha: Borrowed Barrier”
Burst
- To compile a job, annotate the struct with
[BurstCompile] - To share mutable data with Burst, use
SharedStaticinitialized in a C# static constructor - To pass callbacks into Burst, use
FunctionPointercompiled once and cached - To exclude a method from Burst, use
[BurstDiscard]withvoidreturn; useout/reffor output - CRITICAL — No managed calls in [BurstCompile] ISystem: Any managed API call (e.g.,
UnityEngine.Physics.gravity,Debug.Log,stringconcatenation,List<T>) inside a[BurstCompile]-attributed method causes Burst source generators to silently fail. ForISystemstructs, this means the system never registers in the ECS world — no error, no warning, just missing. Always useprivate const,SharedStatic, or Burst-safe math alternatives instead of managed Unity APIs - [DisableAutoCreation] + [BurstCompile] cross-assembly warning: Systems tagged
[DisableAutoCreation]are NOT registered in Unity’s system pipeline at startup — Burst cannot discover them as entry points until the owning library (e.g., BDP) instantiates them at runtime. If such a system’sOnCreate/OnUpdatereference types from assemblies not guaranteed to be loaded at that moment, Burst emits “not a known Burst entry point” warnings. Fix: keep[BurstCompile]on the ISystem when all referenced types are from always-loaded assemblies (Unity.Entities, Unity.Transforms, your core assembly). If warnings appear for a new[DisableAutoCreation]system, move exotic cross-assembly type access into theIJobEntity— the ISystem is a scheduling wrapper with negligible Burst benefit on its own. - Allowed in Burst: primitive types, structs, enums, pointers,
NativeArray/List/HashMap,float2/3/4,quaternion,math.*,FixedString*,BlobAssetReference - NOT allowed in Burst:
string,class,List<T>,Dictionary<K,V>,try/catch,virtualcalls,LINQ,foreachon managed collections,Debug.Log, anyUnityEngine.*managed APIs - [BurstCompile] is per-method, not struct-level — annotating the ISystem struct does NOT automatically Burst-compile OnUpdate/OnCreate/OnDestroy; each method requires its own
[BurstCompile]attribute. Audit (260520-R1) found 12 systems with struct-level annotation only, running managed code silently. Source: review-260520-round1-burst.md §X1
Collections
- To use a collection inside a job, choose
Allocator.TempJoborAllocator.Persistent; neverAllocator.Temp - To write from parallel jobs, use the
.AsParallelWriter()accessor - To dispose after a job, call
array.Dispose(jobHandle)instead of blocking withComplete() - To avoid allocation leaks, guard disposal with
if (container.IsCreated) container.Dispose() - Use
World.UpdateAllocatorfor frame-scoped allocations that auto-dispose — avoids manual disposal
Mathematics
- To seed
Randomin a job, store it as a struct field and derive the seed from chunk or entity index - To safely normalize, check
math.lengthsq(v) > 0.0001fbefore callingmath.normalize - To convert between
UnityEngine.Vector3andUnity.Mathematics.float3, use explicit cast — avoid in jobs - Always use
Unity.Mathematics.math— neverUnityEngine.Mathf(managed namespace, not Burst-safe)
A struct-level [BurstCompile] is NOT a guarantee that every method inside compiles through Burst
The attribute marks intent at the type level. Burst compilation is resolved per method — a method needs its own [BurstCompile], and a managed call anywhere in its body takes it off the Burst path regardless of what the enclosing struct declares. (The per-method bullet under Burst above states the rule; this entry supplies the check to run and two verified sites.)
So check the specific method, never the enclosing struct’s attribute. Verified example — both structs carry [BurstCompile], both of these methods lack the per-method attribute, and both call the fully managed NavProviderRegistry.Register() (it takes an INavProvider interface, throws, and reads a string DisplayName), so neither is Burst-compiling today:
| Site | Struct attr | Method attr | Managed call in body |
|---|---|---|---|
FlowFieldNavProviderBootstrapSystem.OnUpdate | ✅ | ❌ | NavProviderRegistry.Register(...) |
ProjectDawnNavProviderBootstrapSystem.OnCreate | ✅ | ❌ | NavProviderRegistry.Register(...) |
Adding a managed conversion (e.g. a FixedString64Bytes) at either site is zero-risk — nothing there is on the Burst path to begin with.
⚠️ Read this together with the static-init constraint below — the pair is the point. Same project, same day, two sites, opposite correct answers. There, three constant tables feed genuinely Burst-compiled consumers, so they had to be pinned literals; here, a struct-level attribute over managed-calling methods means a direct managed call is free. An author who reasons from the struct attribute will be wrong roughly half the time. Neither half generalises on its own — only the per-method check distinguishes them.
Burst restricts statics initialized by a static ctor — pin LITERALS, guard with a derivation test
A static readonly field whose initializer calls a helper (static readonly float4 X = Convert(...)) compiles into a static constructor. Burst’s support for that is restricted enough that a [BurstCompile] consumer can fail to compile, or read a different value than the same field read outside a job — and the divergence is undiscoverable without a live compile.
So for any constant read from inside a Burst-compiled job or system:
// Pinned literal — safe under Burstpublic static readonly float4 WaterTint = new float4(0.0144f, 0.1274f, 0.4179f, 1f);and add a derivation test asserting the literal equals what the helper would produce, so the two can never drift silently. The literal is the shipped value; the test is the proof it is the right one.
Apply it only where the risk exists. Check each consumer individually rather than blanket-applying — a Baker<T>.Bake() runs in the managed baking pipeline and a bootstrap MonoBehaviour never sees Burst, so both can call the helper directly. Adding the literal-form workaround there buys nothing and costs a derivation test guarding against a risk that isn’t present. Worked case: 5 Burst-compiled consumers needed literals; 2 bakers + 1 bootstrap were confirmed Burst-free and call the helper directly (The1Studio/unity-dots-library#72).
Related rules
Section titled “Related rules”docs/library-feature-discovery-protocol.md— run the corpus-first reuse search before implementing new functionality; always update this skill with what you find (or with the new code if you implement it)rules/kit-wide-fix-discipline.md— if you manually inject library/API knowledge into a teammate brief, that knowledge belongs in this skill, not the brief