t1k:unity:dots-core:zlinq

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

Keywords: collections, LINQ, query, zero-allocation

How to invoke

/t1k:unity:dots-core:zlinq

ZLinq — Zero-Allocation LINQ

Reference for ZLinq v1.5.5+ — struct-based zero-allocation LINQ replacement. 3-10x faster than System.Linq, zero GC pressure during chain operations.

CRITICAL: NOT Burst-compatible. Burst cannot compile delegate chains or generic enumerator structs. Use in non-Burst code only: editor tools, UI, spawners, inventory, loot, tests.

Related skills: dots-ecs (ECS queries use foreach, not LINQ) · dots-jobs-burst (Burst jobs must use manual loops) · zstring (zero-alloc strings) · memorypack (zero-alloc serialization)

When This Skill Triggers

Using AsValueEnumerable() on arrays, lists, or NativeContainers
Replacing System.Linq with zero-allocation alternatives
Writing collection queries in non-Burst C# code (UI, editor, spawners)
Filtering/sorting NativeArray data outside of jobs
Any using ZLinq; or using Cysharp.ZLinq;

Installation

UPM Git URL (add to Packages/manifest.json):

{
  "dependencies": {
    "com.cysharp.zlinq": "https://github.com/Cysharp/ZLinq.git?path=src/ZLinq.Unity/Assets/ZLinq.Unity#v1.5.5"
  }
}

Or OpenUPM: openupm add com.cysharp.zlinq

Min Unity: 2022.3.12f1 (required for DropInGenerator support).

Optional define: ZLINQ_UNITY_COLLECTIONS_SUPPORT — enables NativeList, NativeQueue, NativeHashSet, NativeHashMap.

DropIn for NativeCollections (register in any asmdef):

[assembly: ZLinqDropInExternalExtension("ZLinq", "Unity.Collections.NativeArray`1", "ZLinq.Linq.FromNativeArray`1")]
[assembly: ZLinqDropInExternalExtension("ZLinq", "Unity.Collections.NativeList`1", "ZLinq.Linq.FromNativeList`1")]

Unity-specific: Transform tree traversal (LINQ to Tree):

// Zero-alloc hierarchy traversal
foreach (var child in transform.Children()) { }
foreach (var desc in transform.Descendants()) { }
foreach (var anc in transform.Ancestors()) { }

Core API

using ZLinq;

var result = myArray
    .AsValueEnumerable()
    .Where(x => x > 5)
    .Select(x => x * 2)
    .ToArray();  // Only allocation here

Supported Sources

Source	Fast Path	Notes
`T[]`, `List<T>`	Span	Always available
`NativeArray<T>`, `.ReadOnly`, `NativeSlice<T>`	Span	Always available
`NativeList<T>`, `NativeQueue<T>`, `NativeHashSet<T>`	Enumerator	Requires define

Common Operators (Zero-Alloc During Chain)

.Where(x => x.Health > 0)  .Select(x => x.Damage)  .SelectMany(x => x.Buffs)
.OrderBy(x => x.Priority)  .OrderByDescending(x => x.Distance)  .ThenBy(x => x.Name)
.Count()  .Sum(x => x.Value)  .Min()  .Max()  .Any(x => x.IsAlive)  .All(x => x.Health > 0)
.First()  .FirstOrDefault()  .Last()  .ElementAt(index)
.Union(other)  .Intersect(other)  .Except(other)
.Take(n)  .Skip(n)  .TakeWhile(x => x.Active)
.ToArray()  .ToList()  .ToDictionary(x => x.Id)  .ToHashSet()  // terminal — may allocate

Decision Matrix: ZLinq vs foreach

Context	Use ZLinq?	Why
`[BurstCompile]` ISystem	No	Burst can’t compile delegates
IJobEntity / IJobChunk	No	Jobs require Burst
SystemAPI.Query foreach	No	Already zero-alloc
Editor tools / scene setup	Yes	Readability, zero GC
UI MonoBehaviour	Yes	Clean queries, no GC spikes
Non-Burst managed system	Yes	If query logic is complex
Unit tests	Yes	Readability, assertions
NativeArray post-processing	Yes	If not in Burst context

Critical Gotchas

1. NOT Burst-Compatible (BLOCKER) — Never use AsValueEnumerable() in [BurstCompile] methods. Use manual loops instead.

2. Terminal ops may allocate — .ToArray(), .ToList(), .OrderBy() allocate the result. Chain itself is zero-alloc.

3. No SIMD in Unity — SIMD (Sum, Min, Max) requires .NET 8+. Unity uses .NET Standard 2.1 — no benefit.

4. Type explosion in long chains — Avoid chains > 5–6 operators. Split into intermediate .ToArray() if needed.

Reference Files

File	Contents
api-patterns-guide.md	Entry points, aggregation, grouping, NativeArray patterns, Editor tool patterns, performance notes