Skip to content

Latest commit

 

History

History
92 lines (66 loc) · 10.9 KB

collections.md

File metadata and controls

92 lines (66 loc) · 10.9 KB
Raw

Unity.Collections cheat sheet

The collections provided by this package fall into three categories:

  • The collection types in Unity.Collections whose names start with Native- have safety checks for ensuring that they're properly disposed and are used in a thread-safe manner.
  • The collection types in Unity.Collections.LowLevel.Unsafe whose names start with Unsafe- do not have these safety checks.
  • The remaining collection types are not allocated and contain no pointers, so effectively their disposal and thread safety are never a concern. These types hold only small amounts of data.

Allocators

  • Allocator.Temp: The fastest allocator. For very short-lived allocations. Temp allocations cannot be passed into jobs.
  • Allocator.TempJob: The next fastest allocator. For short-lived allocations (4-frame lifetime). TempJob allocations can be passed into jobs.
  • Allocator.Persistent: The slowest allocator. For indefinite lifetime allocations. Persistent allocations can be passed into jobs.

Array-like types

A few key array-like types are provided by the core module, including Unity.Collections.NativeArray<T> and Unity.Collections.NativeSlice<T>. This package itself provides:
NativeList A resizable list.
UnsafeList A resizable list.
UnsafePtrList A resizable list of pointers.
NativeStream A set of append-only, untyped buffers.
UnsafeStream A set of append-only, untyped buffers.
UnsafeAppendBuffer An append-only untyped buffer.
NativeQueue A resizable queue.
UnsafeRingQueue A fixed-size circular buffer.
FixedList32Bytes A 32-byte list, including 2 bytes of overhead, so 30 bytes are available for storage. Max capacity depends upon the type parameter.
FixedList64Bytes A 64-byte list, including 2 bytes of overhead, so 62 bytes are available for storage. Max capacity depends upon the type parameter.
FixedList128Bytes A 128-byte list, including 2 bytes of overhead, so 126 bytes are available for storage. Max capacity depends upon the type parameter.
FixedList512Bytes A 512-byte list, including 2 bytes of overhead, so 510 bytes are available for storage. Max capacity depends upon the type parameter.
FixedList4096Bytes A 4096-byte list, including 2 bytes of overhead, so 4094 bytes are available for storage. Max capacity depends upon the type parameter.

There are no multi-dimensional array types, but you can simply pack multi-dimensional data into a single-dimension: for example, for an int[4][5] array, use an int[20] array instead (because 4 * 5 is 20).

When using the Entities package, a DynamicBuffer component is often the best choice for an array- or list-like collection.

See also NativeArrayExtensions, ListExtensions, NativeSortExtension.

Map and set types
NativeParallelHashMap An unordered associative array of key-value pairs.
UnsafeParallelHashMap An unordered associative array of key-value pairs.
NativeParallelHashSet A set of unique values.
UnsafeParallelHashSet A set of unique values.
NativeMultiHashMap An unordered associative array of key-value pairs. The keys do not have to be unique, i.e. two pairs can have equal keys.
UnsafeMultiHashMap An unordered associative array of key-value pairs. The keys do not have to be unique, i.e. two pairs can have equal keys.

See also HashSetExtensions, Unity.Collections.NotBurstCompatible.Extensions, and Unity.Collections.LowLevel.Unsafe.NotBurstCompatible.Extensions

Bit arrays and bit fields
BitField32 A fixed-size array of 32 bits.
BitField64 A fixed-size array of 64 bits.
NativeBitArray An arbitrary-sized array of bits.
UnsafeBitArray An arbitrary-sized array of bits.

String types
NativeText A UTF-8 encoded string. Mutable and resizable.
FixedString32Bytes A 32-byte UTF-8 encoded string, including 3 bytes of overhead, so 29 bytes available for storage.
FixedString64Bytes A 64-byte UTF-8 encoded string, including 3 bytes of overhead, so 61 bytes available for storage.
FixedString128Bytes A 128-byte UTF-8 encoded string, including 3 bytes of overhead, so 125 bytes available for storage.
FixedString512Bytes A 512-byte UTF-8 encoded string, including 3 bytes of overhead, so 509 bytes available for storage.
FixedString4096Bytes A 4096-byte UTF-8 encoded string, including 3 bytes of overhead, so 4093 bytes available for storage.

See also FixedString and FixedStringMethods.

Other types
NativeReference A reference to a single value. Functionally equivalent to an array of length 1.
UnsafeAtomicCounter32 A 32-bit atomic counter.
UnsafeAtomicCounter64 A 64-bit atomic counter.

Enumerators

Most of the collections have a GetEnumerator method, which returns an implementation of IEnumerator<T>. The enumerator's MoveNext method advances its Current property to the next element.

Parallel readers and writers

Several of the collection types have nested types for reading and writing from parallel jobs. For example, to write safely to a NativeList<T> from a parallel job, you need a NativeList<T>.ParallelWriter.