Skip to content

t1k:unity:dots-core:jobs-burst

FieldValue
Moduledots-core
Version3.56.1
Efforthigh
Tools—

Keywords: burst, DOTS, EntityIndexInQuery, ForEach-migration, IJobEntity, jobs, parallel, partial-struct, performance, ScheduleParallel, source-generator, WithReadOnly

/t1k:unity:dots-core:jobs-burst

  • DOTS — Data-Oriented Technology Stack
  • ECS — Entity Component System
  • ECB — EntityCommandBuffer
  • SIMD — Single Instruction, Multiple Data

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).

  • com.unity.burst 1.8.28
  • com.unity.mathematics 1.3.2
  • com.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.

  • Writing IJobEntity, IJobChunk, IJob, or IJobParallelFor structs
  • Adding [BurstCompile] to jobs or static methods
  • Allocating NativeArray, NativeList, NativeHashMap, NativeQueue, etc.
  • Using Unity.Mathematics types such as float3, quaternion, math.*
  • Scheduling jobs, chaining JobHandle dependencies, calling ScheduleParallel
  • Asking about allocator lifetimes: Temp, TempJob, Persistent
  • Burst restrictions: managed types, try-catch, virtual calls
  • Using SharedStatic, FunctionPointer, or [BurstDiscard]
TopicReference File
IJobEntity, IJobChunk, IJob, IJobParallelFor, scheduling, dependenciesjobs-guide.md (references/jobs-guide.md)
BurstCompile, restrictions, SharedStatic, FunctionPointer, BurstDiscardburst-guide.md (references/burst-guide.md)
NativeArray, NativeList, NativeHashMap, allocators, disposal patternscollections-guide.md (references/collections-guide.md)
float2/3/4, quaternion, math.*, Random, noisemathematics-guide.md (references/mathematics-guide.md)
Advanced Burst — SIMD intrinsics, profile-guided optimization, platform tuningburst-advanced-guide.md (references/burst-advanced-guide.md)
Advanced Collections — custom allocators, unsafe containers, parallel patternscollections-advanced-guide.md (references/collections-advanced-guide.md)
IJobEntity source-gen expansion, field attributes, EntityIndexInQuery, schedule variants, ForEach migrationijobentity-source-gen.md (references/ijobentity-source-gen.md)
EntityManager Burst-safety in Entities 1.x, when to still prefer ECB, structural-change invalidationentitymanager-burst-compatibility.md (references/entitymanager-burst-compatibility.md)
Schedule/ScheduleParallel dependency auto-wiring by source-gen, when the implicit form is not fire-and-forgetparallel-scheduling-patterns.md (references/parallel-scheduling-patterns.md)
Anti-PatternWhy It’s BadFix
Managed API in [BurstCompile]Silently prevents ISystem registration — no error, no warningUse private const, SharedStatic, or Burst-safe math
Debug.Log in Burst codeManaged call breaks compilationUse [BurstDiscard] wrapper (NOT [Conditional] — Burst still analyzes method body)
string operations in jobsManaged heap allocationUse FixedString32Bytes/64/128/512
List<T> in jobsGC allocationUse NativeList<T> with proper allocator
Allocator.Temp in jobsOnly valid on main thread, not in jobsUse Allocator.TempJob (frame-scoped) or Allocator.Persistent
Complete() then Dispose()Blocks main thread waiting for jobUse container.Dispose(jobHandle) for async disposal
Missing [ReadOnly] on job fieldsPrevents parallelization — safety system assumes write accessAdd [ReadOnly] to all read-only NativeContainer fields
Schedule() when ScheduleParallel() worksSingle-threaded when could be parallelUse ScheduleParallel for IJobEntity when no write conflicts
Run() for heavy workRuns on main thread, blocks frameUse Schedule/ScheduleParallel for >100 entities
Boxing value typesHidden GC allocationAvoid casting structs to object or interfaces
UnityEngine.Physics.gravityManaged API, breaks Burstprivate const float Gravity = -9.81f
UnityEngine.RandomManaged, not Burst-safeUnity.Mathematics.Random with entity-derived seed
Mathf.* functionsManaged UnityEngine namespaceUnity.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”.

Jobs

  • To use IJobEntity, declare a partial struct and 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 in OnUpdate, not OnCreate
  • Prefer ScheduleParallel over Schedule — split work across worker threads
  • Prefer IJobEntity over IJobChunk — cleaner API, same performance, source-generated query
  • Never borrow another system’s barrier — direct ComponentLookup/BufferLookup access on a type a job elsewhere writes needs your OWN state.Dependency.Complete(); relying on group sort order to make it safe breaks silently (and repeats every frame, uncaught by DOTSTestBase) 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 SharedStatic initialized in a C# static constructor
  • To pass callbacks into Burst, use FunctionPointer compiled once and cached
  • To exclude a method from Burst, use [BurstDiscard] with void return; use out/ref for output
  • CRITICAL — No managed calls in [BurstCompile] ISystem: Any managed API call (e.g., UnityEngine.Physics.gravity, Debug.Log, string concatenation, List<T>) inside a [BurstCompile]-attributed method causes Burst source generators to silently fail. For ISystem structs, this means the system never registers in the ECS world — no error, no warning, just missing. Always use private 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’s OnCreate/OnUpdate reference 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 the IJobEntity — 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, virtual calls, LINQ, foreach on managed collections, Debug.Log, any UnityEngine.* 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.TempJob or Allocator.Persistent; never Allocator.Temp
  • To write from parallel jobs, use the .AsParallelWriter() accessor
  • To dispose after a job, call array.Dispose(jobHandle) instead of blocking with Complete()
  • To avoid allocation leaks, guard disposal with if (container.IsCreated) container.Dispose()
  • Use World.UpdateAllocator for frame-scoped allocations that auto-dispose — avoids manual disposal

Mathematics

  • To seed Random in 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.0001f before calling math.normalize
  • To convert between UnityEngine.Vector3 and Unity.Mathematics.float3, use explicit cast — avoid in jobs
  • Always use Unity.Mathematics.math — never UnityEngine.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:

SiteStruct attrMethod attrManaged 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 Burst
public 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).

  • 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