t1k:unity:dots-core:jobs-burst

Field	Value
Module	`dots-core`
Version	`2.3.2`
Effort	`high`
Tools	—

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

How to invoke

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

Unity DOTS Jobs, Burst & Collections

Terminology

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

Skill Purpose

Reference for Unity’s high-performance layer: Job System scheduling, Burst native compilation, Collections memory management, and Mathematics shader-like API. Complements dots-ecs-core (components, systems, queries).

Package Versions

com.unity.burst 1.8.28
com.unity.collections 2.6.5
com.unity.mathematics 1.3.2

When This Skill Triggers

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]

Quick Reference

Topic	Reference File
IJobEntity, IJobChunk, IJob, IJobParallelFor, scheduling, dependencies	jobs-guide.md
BurstCompile, restrictions, SharedStatic, FunctionPointer, BurstDiscard	burst-guide.md
NativeArray, NativeList, NativeHashMap, allocators, disposal patterns	collections-guide.md
float2/3/4, quaternion, math.*, Random, noise	mathematics-guide.md
Advanced Burst — SIMD intrinsics, profile-guided optimization, platform tuning	burst-advanced-guide.md
Advanced Collections — custom allocators, unsafe containers, parallel patterns	collections-advanced-guide.md
IJobEntity source-gen expansion, field attributes, EntityIndexInQuery, schedule variants, ForEach migration	ijobentity-source-gen.md

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)

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
`[BurstCompile]` on a pure static utility class whose methods take/return `int2`/`float2`/`float3` by value	BC1064 / BC1067 — illegal as an EXTERNAL Burst entry point. Breaks the project-wide Burst compile.	Leave it un-annotated — it inlines into Burst callers (one code-gen instantiation per call site = same perf). `DOTSCore.GridMath` / `StatMath` / `WeightedSampler` / `CooldownTickHelper` / `DeterministicRandom` are SSOT examples. See `references/burst-guide.md` § “pure static utility classes”.
`[BurstCompile]` on an `OnUpdate` that calls a managed interface (e.g. `IGachaItemResolver`, `IObjectPoolManager`)	BC1016 — virtual dispatch through a managed interface is not Burst-compatible.	Drop `[BurstCompile]` from the managed-touching method; keep the Burst-safe math (e.g. `WeightedSampler.Sample`) in a Burst job, resolve the managed step in a non-Burst path. See `dots-vcontainer-integration`.
`EntityManager.CreateArchetype(ComponentType.RW<A>(), ComponentType.RW<B>(), ...)` in `[BurstCompile]`	`params ComponentType[]` overload allocates a managed array → BC1028: Creating a managed array `Unity.Entities.ComponentType[]` is not supported. Compiles fine outside Burst, fails Burst-only.	Use the `NativeArray<ComponentType>` overload. Cache as `EntityArchetype` field, populate once in `OnCreate` with `new NativeArray<ComponentType>(N, Allocator.Temp)` + indexed assignment + `Dispose()`. Same pattern applies to `EntityManager.AddComponent(query, ComponentTypeSet)` when it exposes a `params` overload.
BC1028 (or any Burst error) in ONE file silently disables Burst for the WHOLE project — seemingly unrelated tests fail with `Expected: 1 But was: 0`	When Burst cannot compile any single ISystem in the project, `[BurstCompile]` ISystems across other assemblies may silently fail to register in the World. Tests for those unrelated systems then fail with empty queries / no spawns / no state changes — looking like test-setup bugs. Confirmed 2026-05-06: 12 EditMode failures in one combat package were caused by 3 BC1028 errors in an unrelated puzzle package. After fixing BC1028, all 12 tests passed without any test edits.	Always run `read_console` for `error` types BEFORE debugging “expected:1 was:0” test failures. If ANY Burst error exists anywhere in the project, fix that FIRST. Do NOT rewrite test fixtures based on “system query mismatch” hypotheses until the console is fully clean. Treat a project-wide clean compile as a hard precondition for trusting test-failure signals.

Key Conventions

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

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)

rules/library-feature-discovery-protocol.md — research the library 3× before implementing new functionality; always update this skill with what you find (or with the new code if you implement it)
rules/manual-correction-implies-skill-gap-unity.md — if you manually inject library/API knowledge into a teammate brief, that knowledge belongs in this skill, not the brief