com.unity.entities@1.3.9

## [1.3.9] - 2025-01-16

### Added

* Enabled content downloads from the Editor while in Playmode.

### Fixed

* Entities Hierarchy shows content for _Dont Destroy On Load_ scene in playmode.
* Prefab reference disappears after instantiating the prefab in runtime and rebaking.
* Entity inspector now differentiate editors for component types when type names are the same but namespaces are different.
* compile error when using 'unsafe' in one partial system (that's generated) but not another
* compile error when having mismatched using statements in one partial system that's different than another
* Fixed an error where an `EntityQuery` whose `WithAny` list contained a mix of enableable and disableable components would fail to match entities with at least one of the non-enableable components, if all of its enableable Any components were disabled. As a side effect, queries with `WithAny` constraints should now have slightly faster matching.
* For empty scene sections, `SceneSectionData.BoundingVolume` will no longer contain NaN values, and the `BoundingVolume.IsValid` property will return `true` as expected. Note that converting this field to an `AABB` will still result in NaN values; for now, this case will need special-case handling in user code.
* Massively reduced reflection on startup in player builds by moving work to an ILPostProcessor.
* Unit test Instability (memory corruption) caused by dynamically registering new types with the TypeManager.

### Security

Author: Unity Technologies

CHANGELOG.md

@@ -4,6 +4,27 @@ uid: changelog
 
 # Changelog
 
+## [1.3.9] - 2025-01-16
+
+### Added
+
+* Enabled content downloads from the Editor while in Playmode.
+
+### Fixed
+
+* Entities Hierarchy shows content for _Dont Destroy On Load_ scene in playmode.
+* Prefab reference disappears after instantiating the prefab in runtime and rebaking.
+* Entity inspector now differentiate editors for component types when type names are the same but namespaces are different.
+* compile error when using 'unsafe' in one partial system (that's generated) but not another
+* compile error when having mismatched using statements in one partial system that's different than another
+* Fixed an error where an `EntityQuery` whose `WithAny` list contained a mix of enableable and disableable components would fail to match entities with at least one of the non-enableable components, if all of its enableable Any components were disabled. As a side effect, queries with `WithAny` constraints should now have slightly faster matching.
+* For empty scene sections, `SceneSectionData.BoundingVolume` will no longer contain NaN values, and the `BoundingVolume.IsValid` property will return `true` as expected. Note that converting this field to an `AABB` will still result in NaN values; for now, this case will need special-case handling in user code.
+* Massively reduced reflection on startup in player builds by moving work to an ILPostProcessor.
+* Unit test Instability (memory corruption) caused by dynamically registering new types with the TypeManager.
+
+### Security
+
+
 ## [1.3.8] - 2024-11-08
 
 ### Removed
@@ -14,7 +35,8 @@ uid: changelog
 
 * Disable "new empty subscene" menu item on default untitled scene.
 * Fix invalid queries generated for `IJobEntity` with `[WithPresent(typeof(T))]` and `EnabledRef<T>` and/or `in T` in the same job.
-	
+
+
 
 ## [1.3.5] - 2024-10-04
 

DocCodeSamples.Tests/TransformsCustom.cs

@@ -4,7 +4,7 @@
 using Unity.Mathematics;
 using Unity.Transforms;
 
-namespace Miscellaneous.CustomTransforms
+namespace Doc.CodeSamples.Tests
 {
     #region Transform2DAuthoring
     public class Transform2DAuthoring : MonoBehaviour

Documentation~/TableOfContents.md

@@ -1,6 +1,6 @@
-# Allocators overview
+# Memory allocators overview
 
-Entities and the [Collections package](https://docs.unity3d.com/Packages/com.unity.collections@latest) has different allocators that you can use to manage memory allocations. The different allocators organize and track their memory in different ways. These are the allocators available:
+Entities and the [Collections package](https://docs.unity3d.com/Packages/com.unity.collections@latest) have different allocators that you can use to manage memory allocations. The different allocators organize and track their memory in different ways. These are the allocators available:
 
 * [Allocator.Temp](https://docs.unity3d.com/Packages/com.unity.collections@latest/index.html?subfolder=/manual/allocation.html): A fast allocator for short-lived allocations, which is created on every thread.
 * [Allocator.TempJob](https://docs.unity3d.com/Packages/com.unity.collections@latest/index.html?subfolder=/manual/allocation.html): A short-lived allocator, which must be deallocated within 4 frames of their creation.

Documentation~/allocators-overview.md

@@ -8,7 +8,6 @@ Blob assets represent immutable binary data. Because blob assets are immutable,
 
 Blob assets can be referenced by [component](concepts-components.md) on an [entity](concepts-entities.md). 
 
-
 ## Supported data
 
 Blob assets mustn't contain any managed data such as regular arrays, strings, or any other managed object. Blob asset data is read-only, which means that it doesn't change at runtime. 

Documentation~/blob-assets-concept.md

@@ -1,6 +1,6 @@
-# Blob assets
+# Store immutable data with blob assets
 
-This section contains information about what blob assets are, how to create them and how to use them in Baking.
+This section contains information about using blob assets to store immutable data.
 
 |**Topic**|**Description**|
 |---|---|

Documentation~/blob-assets-intro.md

@@ -1,56 +1,65 @@
-# Common Errors
-This section lists some of the causes and solutions for common errors coming from [the safety system](concepts-safety.md).
+# Common error messages
+This section lists some causes and solutions for common errors coming from [the safety system](concepts-safety.md).
 
 ## Errors related to the Dependency property
-The [`Dependency`](xref:Unity.Entities.SystemState.Dependency) property is used to record the handles of all jobs a system is scheduling. This is important so that later systems can pass the right dependencies into their jobs to avoid data races. The safety system makes a best effort attempt to detect cases where a job has not been assigned to the `Dependency` property. In these cases, you will see an error such as:
+The [`Dependency`](xref:Unity.Entities.SystemState.Dependency) property is used to record the handles of all jobs a system is scheduling. This is important so that later systems can pass the right dependencies into their jobs to avoid data races. The safety system makes a best effort attempt to detect cases where a job isn't assigned to the `Dependency` property. In these cases, the following error is produced:
+
 ```
 The system <SYSTEM NAME> reads <COMPONENT NAME> via <JOB NAME> but that type was not assigned to the Dependency property. To ensure correct behavior of other systems, the job or a dependency must be assigned to the Dependency property before returning from the OnUpdate method.
 ```
 
 Common causes for this error are:
- - Your code does not assign the `JobHandle`s of the jobs it is scheduling to the `Dependency` property.
- - The safety system could not determine which component types your system is using. This can happen when you use [`EntityQueries`](xref:Unity.Entities.EntityQuery) that were not created using [`GetEntityQuery`](xref:Unity.Entities.SystemState.GetEntityQuery). Your system must not use any query that it did not create itself using `GetEntityQuery`. In particular, do not create entity queries using the `EntityManager`.
- - An exception elsewhere in the system update is causing `OnUpdate` to terminate before the `Dependency` property is assigned (in which case, you should see the real exception logged to the console as well, and this error is a red herring).
+ - Your code doesn't assign the `JobHandle`s of the jobs it's scheduling to the `Dependency` property.
+ - The safety system could not determine which component types your system used. This can happen when you use [`EntityQueries`](xref:Unity.Entities.EntityQuery) that weren't created with [`GetEntityQuery`](xref:Unity.Entities.SystemState.GetEntityQuery*). Your system must not use any query that it didn't create itself using `GetEntityQuery`. In particular, do not create entity queries using the `EntityManager`.
+ - An exception elsewhere in the system update is causing `OnUpdate` to terminate before the `Dependency` property is assigned. In this case, the real exception is logged to the console, meaning that the previous error is misleading and can be ignored.
 
 ## Errors related to parallel writing
-You may sometimes encounter errors such as:
+
+You might sometimes encounter errors such as:
+
 ```
 InvalidOperationException: <JOB FIELD> is not declared [ReadOnly] in a IJobParallelFor job. The container does not support parallel writing. Please use a more suitable container type.
 ```
-This error means that you are using a parallel job and this job is accessing something in parallel in a way that may be unsafe. Parallel jobs in the Entities package include [`IJobChunk`](xref:Unity.Entities.IJobChunk) and [`IJobEntity`](xref:Unity.Entities.IJobEntity).
 
-It is generally unsafe to access data concurrently, unless your job is only reading that data. However, sometimes you may know through domain specific knowledge that your concurrent writes are safe. This is for example the case if you know that no two threads will ever access the same value in parallel.
+This error means that a parallel job is accessing something in parallel in a way that might be unsafe. Parallel jobs in the Entities package include [`IJobChunk`](xref:Unity.Entities.IJobChunk) and [`IJobEntity`](xref:Unity.Entities.IJobEntity), and [`ParallelFor` and `ParallelForTransform`](xref:um-job-system-jobs) in the core engine.
+
+It's generally unsafe to write the same data concurrently from multiple threads. However, sometimes you might know through domain specific knowledge that your concurrent writes are safe. This is for example the case if you know that no two threads will ever access the same value in parallel.
 
 Common causes for this error are:
  - You are actually only reading from this data. In this case, adding the [`ReadOnly`](https://docs.unity3d.com/ScriptReference/Unity.Collections.ReadOnly.html) attribute is the correct fix. 
  - You are using a native container in a parallel job without the [`ReadOnly`](https://docs.unity3d.com/ScriptReference/Unity.Collections.ReadOnly.html) attribute.
- - You are using a [`ComponentLookup`](xref:Unity.Entities.ComponentLookup) in a parallel job without [`ReadOnly`](https://docs.unity3d.com/ScriptReference/Unity.Collections.ReadOnly.html) attribute.
+ - You are using a [`ComponentLookup`](xref:Unity.Entities.ComponentLookup`1) in a parallel job without the [`ReadOnly`](https://docs.unity3d.com/ScriptReference/Unity.Collections.ReadOnly.html) attribute.
 
-If you can guarantee that your access is safe, you may use the [`NativeDisableParallelForRestriction`](https://docs.unity3d.com/ScriptReference/Unity.Collections.NativeDisableParallelForRestrictionAttribute.html) attribute to silence the error.
+If you can guarantee that your access is safe, you can use the [`NativeDisableParallelForRestriction`](https://docs.unity3d.com/ScriptReference/Unity.Collections.NativeDisableParallelForRestrictionAttribute.html) attribute to silence the error.
 
 ## Errors related to missing dependencies on previously scheduled jobs
-When the safety system detects that a job is missing a dependency on another job, you will see an error such as this:
+
+When the safety system detects that a job is missing a dependency on another job, it produces an error such as this:
+
 ```
 InvalidOperationException: The previously scheduled job <JOB NAME> writes to the <OBJECT TYPE> <FIELD IN JOB>. You are trying to schedule a new job <OTHER JOB NAME>, which writes to the same <OBJECT TYPE> (via <FIELD IN OTHER JOB>). To guarantee safety, you must include <JOB NAME> as a dependency of the newly scheduled job.
 ```
-The safety system will flag all cases where the same component type is used in multiple jobs that may run concurrently. In some cases, it may still be safe for these jobs to be executing in parallel as long as you can guarantee that the entities the concurrent jobs operate on do not overlap.
+
+The safety system will flag all cases where the same component type is used in multiple jobs that could run concurrently. Sometimes, it's still safe for these jobs to be executing in parallel as long as you can guarantee that the entities the concurrent jobs operate on don't overlap.
 
 A common cause for this error is that you are scheduling multiple copies of the same job, each on a query with different shared component values. This is safe, as queries with different values for the same shared component type never overlap. You can use the [`NativeDisableContainerSafetyRestriction`](https://docs.unity3d.com/ScriptReference/Unity.Collections.LowLevel.Unsafe.NativeDisableContainerSafetyRestrictionAttribute.html) attribute on affected fields to disable this error.
 
 ## Errors related to safety handles
-When the safety system detects that a job is reading a resource that it doesn't have access to, you may see an error such as:
+
+When the safety system detects that a job is reading a resource that it doesn't have access to, an error like the following might be produced:
+
 ```
 InvalidOperationException: The <JOB FIELD> has been declared as [WriteOnly] in the job, but you are reading from it.
 ```
-In practice, `[WriteOnly]` resources are extremely uncommon. A more likely cause for this error is that the read in question is occurring from a job that was launched from within another job. Launching jobs from jobs is not currently supported, and the resulting safety handles won't be set up correctly. This includes less obvious cases like using `.job.Run()` from inside of an `Entities.ForEach().Run()` lambda function, which is itself implemented as a main-thread job. 
+In practice, `[WriteOnly]` resources are rare. A more likely cause for this error is that the read in question is occurring from a job that was launched from within another job. Launching jobs from jobs is not currently supported, and the resulting safety handles won't be set up correctly. This includes obscure cases like using `.job.Run()` from inside of an `Entities.ForEach().Run()` lambda function, which is itself implemented as a main-thread job. 
 
 ## Errors related to system type definitions
-The Entities package makes extensive use of source generators to implement core features like `IJobEntity`, `ISystem`,
-and `SystemAPI`. One requirement this imposes is that all system types and `IJobEntity` implementations must have the
-`partial` keyword, so that the source generators can extend the types with additional generated methods. It's easy to
-forget to add the `partial` keyword, which may lead to the following compiler error:
+
+All system types and `IJobEntity` implementations must have the `partial` keyword, so that the source generators can extend the types with additional generated methods. If you forget to add the `partial` keyword, it might lead to the following compiler error:
+
 ```
 error CS0101: The namespace <NAMESPACE> already contains a definition for <SYSTEM/JOB TYPE>
 ```
-Also note that a system deriving from the managed `SystemBase` interface should be a `class`,
+
+Also note that a system deriving from the managed `SystemBase` interface must be a `class`,
 while an unmanaged system implementing the `ISystem` interface must be a `struct`.

Documentation~/common-errors.md

@@ -2,29 +2,21 @@
 uid: components-buffer-introducing
 ---
 
-# Introducing dynamic buffer components
+# Dynamic buffer components introduction
 
 A dynamic buffer component is a component that acts as a resizable array of unmanaged structs. You can use it to store array data for an entity, such as waypoint positions for the entity to navigate between.
 
 Alongside the data, each buffer stores a `Length`, a `Capacity`, and an internal pointer:
 
 * The `Length` is the number of elements in the buffer. It starts at `0` and increments when you append a value to the buffer.
 * The `Capacity` is the amount of storage in the buffer. It starts out matching the internal buffer capacity. Setting `Capacity` resizes the buffer.
-* The pointer indicates where the dynamic buffer data is. Initially it is `null` to signify that the data is in the chunk with the entity, and if Unity moves the data outside the chunk, the pointer is set to point to the new array. For more information on how Unity stores dynamic buffer components, see [Capacity](#capacity).
+* The pointer indicates where the dynamic buffer data is. The pointer is initially `null` to signify that the data is in the chunk with the entity, and if Unity moves the data outside the chunk, the pointer is set to point to the new array. For more information on how Unity stores dynamic buffer components, refer to [Set the capacity of a dynamic buffer](components-buffer-set-capacity.md).
 
-## Capacity
+## Dynamic buffer capacity
 
-The initial capacity of a dynamic buffer is defined by the type that the buffer stores. By default, the capacity defaults to the number of elements that fit within 128 bytes. For more information, see [`DefaultBufferCapacityNumerator`](xref:Unity.Entities.TypeManager.DefaultBufferCapacityNumerator). You can specify a custom capacity using the [`InternalBufferCapacity`](xref:Unity.Entities.InternalBufferCapacityAttribute) attribute. For information on how to create a dynamic buffer component type, see [Create a dynamic buffer component type](components-buffer-create.md).
+The initial capacity of a dynamic buffer is defined by the type that the buffer stores. By default, the capacity defaults to the number of elements that fit within 128 bytes. For more information on dynamic buffer capacity, refer to [Set the capacity of a dynamic buffer](components-buffer-set-capacity.md). 
 
-Initially, Unity stores the dynamic buffer data directly in the chunk of the entity that the component belongs to. If the length of a dynamic buffer is ever greater than the capacity, Unity copies the dynamic buffer data to an array outside of the chunk. If the length of the dynamic buffer later shrinks to less than the capacity, Unity still stores the data outside of the chunk; if Unity moves dynamic buffer data outside of a chunk, it never moves the data back into the chunk.
-
-The original internal buffer capacity is part of the chunk and Unity only deallocates it when Unity deallocates the chunk itself. This means if the dynamic buffer length exceeds the internal capacity and Unity copies the data outside of the chunk, there is wasted space within the chunk. It's best practice to use the data in the chunk when possible. To do this, make sure most of your entities don't exceed the buffer capacities, but also don't set the capacity too high if the entities don't use it. If the size of a dynamic buffer changes too much, it's best practice to store its data outside of the chunk. To do this, set the `InternalBufferCapacity` to `0`.
-
-There are other options available to store array data:
-
-* [Blob assets](xref:Unity.Entities.BlobBuilder): Stores tightly-packed read-only structured data, including arrays, and multiple entities can share a single blob asset. Because they're read-only, you can access them from multiple threads simultaneously.
-* [Managed components](components-managed.md): Stores arrays of native or managed objects. However, accessing managed component data is more restrictive and less performant than dynamic buffer component data. Also you need to manually clone and dispose of the array data.
-* [Shared components](components-shared.md): Similar to managed components, they store arrays of native or managed objects and your entities can store indices into these larger arrays. They have the same restrictions and performance considerations as managed components.
+You can also use the [`InternalBufferCapacity`](xref:Unity.Entities.InternalBufferCapacityAttribute) attribute to specify a custom capacity. For more information, refer to [Create a dynamic buffer component type](components-buffer-create.md).
 
 ## Structural changes
 
@@ -49,13 +41,11 @@ public void DynamicBufferExample(Entity e)
 ```
 ## Comparison to native containers in components
 
-Dynamic buffers are often preferable to using [nativecontainers on components](components-nativecontainers.md) because they are free
-of the job scheduling restrictions on the latter, and because they can optionally be stored inline inside a chunk, which helps reduce
-memory bandwidth usage.
+Dynamic buffers don't have the job scheduling restrictions that [native containers on components](components-nativecontainers.md) have, so it's usually preferable to use dynamic buffers in your code where possible. Dynamic buffers can also be stored inline inside a [chunk](concepts-archetypes.md#archetype-chunks), which helps reduce memory bandwidth usage.
 
-In general, when there is more than one entity that needs a collection on it, it probably merits a dynamic buffer. If there's only one,
-it might work well as a singleton with a native container on it. 
+In general, when there's more than one entity that needs a collection on it, use a dynamic buffer. If there's only one, it might work well as a [singleton component](components-singleton.md) with a native container on it. 
 
 ## Additional resources
 
-* [Create a dynamic buffer component](components-buffer-create.md)
+* [Create a dynamic buffer component](components-buffer-create.md)
+* [Set the capacity of a dynamic buffer](components-buffer-set-capacity.md)