Official Experimental Entities 1.0 is available

Hi everyone! We’ve just published a new experimental version of Entities and other ECS-based packages, including a suite of new features and compatibility with Unity 2022.2 beta Tech Stream. This milestone brings us one step closer to supporting Entities and its compatible packages for production, like any other feature of Unity, where its APIs would remain stable for the duration of the Unity LTS cycle.

As a reminder: Experimental releases are not supported or recommended for production, but they provide early access for those who want to try out Entities in their projects. This also helps us make progress on development through your feedback.

Getting started
If you are just getting started, refer to our installation and setup guide in our documentation to help with project setup. The release is compatible with Unity 2022.2.0b8, but we recommend using Unity 2022.2.0b11+, which includes various fixes for IL2CPP and the Entities Graphics package, reducing a significant number of crashes experienced in the editor. You can find the changelog for the latest editor version here.

We also published a guide that contains:

• A summary and video overview of important ECS concepts
• A simple tutorial to learn the basics of using ECS and the Job System
• A set of cheat sheets across API topics

What’s new
As part of this Entities 1.0 release, the following packages have been tested together with Unity 2022.2 beta Tech Stream. For a full list of changes in each package, refer to the changelogs in our documentation (linked below):

• com.unity.entities
• com.unity.entities.graphics
• com.unity.netcode
• com.unity.physics

We have also updated the following packages, which are automatically included when installing the Entities package:

• com.unity.burst
• com.unity.collections
• com.unity.logging (included when installing com.unity.netcode)

Thank you to everyone who has taken the time to share feedback since the Entities 0.51 release. Please continue to engage with us as we approach our next development milestone!

Notable highlights


Streamlined ECS workflows
Leverage existing Unity expertise and assets to create even more ambitious games. This includes ECS workflows that provide a familiar authoring experience, and are compatible with GameObjects and current GameObject-based systems.

• A suite of dedicated Editor tools help you profile, analyze, and debug entity data that are fully inter-operational and allow you to approach solving problems from any angle. We have introduced a new Journaling window that lets you record and explore ECS events directly from the Editor, allowing you to follow every single transformation a specific entity went through without requiring any complicated debugging setup. Read our documentation to learn more about these tools, and check out this overview of our authoring & debugging workflows at GDC 2022 earlier this year.
• We have introduced data modes, which are a brand new paradigm for working, in-place, with data that has wildly different representations at authoring time and at runtime. You can learn more about this in our documentation.
• We have introduced non-destructive editing of subscenes while in Play mode, allowing you to make permanent changes to your game while playing, and in a safe manner. You can learn more about this in our documentation.
• We have completely reengineered the conversion pipeline, which is now referred to as the Baking system. Leveraging the benefits of ECS, this improved conversion pipeline is much faster, and ensures performant conversion in projects with massive scenes. You can learn more about this in our documentation, and read this post for more context about these changes.
• Support for the Unity build window brings back the familiar build workflow that many developers are used to.
• Specific ECS settings have been moved from the top-level menus to the Preferences window. You can learn more about these settings in our documentation.

Adaptive game architecture
Leverage Unity’s ECS framework to avoid the drawbacks of object-oriented programming. This includes a better way to collaborate on gameplay features, write optimized game code, and write reusable game code.

• We have introduced a new feature called Aspects, which provides a simpler (and more optimized) interface to sets of component data as an easier way to organize and maintain game code. Read here to learn about our motivations behind this new feature, and read our documentation for more information on how to create and use Aspects.
• Significant improvements to the Transform system delivers a simpler, cheaper, and more robust Transform data protocol. Read here for more details about these changes.
• Idiomatic foreach is the recommended improvement to

  Entities.ForEach.Run

  , with fewer edge-cases where APIs that work outside of a loop don't work inside. Read here for more details about this change.

Control & determinism
Publish demanding games to the widest range of devices through complete control over data layout and processing. This includes deterministic processing and complete memory control to allow optimizing production budgets based on target platforms.

• Custom allocators provide full control over memory allocation throughout the engine enabling high performance, controllable, hierarchical memory allocation.
• We have made improvements to the Collections package to simplify method calls.
• Debugging bursted code with managed debuggers works transparently without any extra steps required.
• The Unity Profiler includes two Entities Profiler modules that you can use to track and collect data on the performance of your Entities code. You can learn more about these modules in our documentation:
  • Entities Structural Changes profiler module can record which world/system produced a structural change, and how much time it cost per frame
  • Entities Memory profiler module can record which world/system allocates memory chunks, with additional details per archetype

Native code performance
Achieve performance targets with more ambitious content. The use of Entities, the Job System, and the Burst Compiler provides the simplicity of C# while achieving near native code performance and multicore processing.

• Added support throughout Entities packages to make ISystem and IJobEntity more useful than ever, meaning that you can write simple and expressive burst-compatible code in your systems to achieve near native code performance.
• Enableable components can be efficiently enabled and disabled at runtime without triggering a structural change, and are ideal for high-frequency state changes. You can learn more in our documentation, and read this post for context behind this feature.
• Multiple systems are now Burst compilable - Collections, OnUpdate, Job System

Massive data streaming
Leverage Unity’s ECS framework to achieve spikeless streaming and memory-efficient large-scale rendering. This includes memory-optimized scene loading and a high-performant entities graphics system.

• Subscenes provide dynamic scene loading and unloading that simplify the creation of vibrant worlds. You can learn more about subscenes in our documentation.
• Performant rendering across a wide range of devices with Entities Graphics (formerly known as Hybrid Renderer), and compatibility with most URP and HDRP features out-of-the-box. Read here for information on our motivations behind the name change.
• Significantly updated experimental Occlusion Culling system that allows users to render more, with less performance overhead.

Unprecedented simulation scale
Unleash performant, large scale simulations with a robust physics and simulation toolkit. This includes the Unity Physics and Havok Physics systems.

• New features like motors and breakable joints allow for more dynamic physics behaviors.
• Scalable debug visualization enables a better understanding of physics behaviors in complex scenes.
• A new cohesive experience for Havok Physics for Unity is being rolled out, and will be included in Unity Pro, Unity Enterprise and Unity Industrial Collection offerings. New license purchases and renewals for the Havok Physics for Unity experimental package will be unavailable from October 13. Users who have purchased a license previously can continue to use the license until expiry. If you need assistance with your ongoing subscription, please reach out to support@unity.com

Large multiplayer games
Turn projects into ambitious multiplayer experiences with a netcode solution capable of supporting large competitive multiplayer action games.

• Our ECS-based networking library supports a higher number of players, and powers scalable networking strategies for prediction and ghosting. Leveraging ECS also allows for a high number of networked objects, provides frame independent network synchronization, and efficient data processing for complex rollback needs.
• Debugging capabilities support debugging multiple clients/server in the same process.

Known issues

• We are still working on making the physics and netcode systems compatible with the improved transform system.
• Currently, experimental deformations (skinning and blendshapes) do not leverage frustum or occlusion culling.
• We are still iterating on the UX around data mode to make them easier to grasp. Expect changes in that area in future releases.
• We have received several reports of crashes in IL2CPP builds. While we work to investigate and fix this issue, we do not recommend using IL2CPP.
• There is a separate known GPU crash (also exhibited in our testing with the MegaCity project) when using Entities Graphics alongside DX12. As we investigate the root cause, we recommend using DX11 as a workaround.
• You may experience a crash when entering Play mode while burst is compiling. As we investigate the root cause of this issue, we recommend waiting for burst to finish compiling before entering Play mode.
• There is Native/UnsafeStream memory leak when using multiple writers.
• Valid compilation errors can cause additional

  CS0282

  warnings from source-generated partial types:

  There is no defined ordering between fields in multiple declarations of partial struct.

  These are typically suppressed with a diagnostic suppressor for generated types, but an issue with the Roslyn compiler can prevent these from being suppressed if other compilation errors occur. This can result in many of these warnings in the Unity console. These can also be suppressed by adding -

  nowarn:0282

  to a Unity rsp file (see this link for details).
• If an exception happens in the entity iteration blocks

  Entities.ForEach

  or the idiomatic foreach loop in

  SystemAPI.Query

  , then ECS doesn't clean up the exception if the calling code isn't from a derived system method such as

  OnCreate

  ,

  OnUpdate

  ,

  OnDestroy

  ,

  OnStartRunning

  , or

  OnStopRunning

  . This causes further exceptions to be erroneously reported.
• You can't schedule an

  IJobEntity

  that takes any argument directly constructed from a method invocation. For example, the following code doesn't work:
  Code (CSharp):

  1. new SomeJob().Schedule(JobHandle.CombineDependecies(handle1, handle2))
  To fix this, store the argument in a local variable and use that as the argument. For example:
  Code (CSharp):

  1. (new SomeJob().Schedule(someCombinedHandle))
• If you schedule an

  IJobEntity

  constructed with an initialization expression that invokes a

  SystemAPI

  method, such as:
  Code (CSharp):

  1. SomeJob{targetLookup = SystemAPI.GetComponentLookup<Target>()}.Schedule()
  This causes the following runtime error:

  No suitable code replacement generated, this is either due to generators failing, or lack of support in your current context.

  To fix this, put in a local variable first. For example, the following works:
  Code (CSharp):

  1. var targetLookup = SystemAPI.GetComponentLookup<Target>(); new SomeJob{targetLookup = targetLookup}.Schedule()
• Calling

  SystemAPI

  methods from static methods in a system causes the following runtime error:

  No suitable code replacement generated, this is either due to generators failing, or lack of support in your current context.

• NativeMultiHashMap

  should be named

  NativeParallelMultiHashMap

Sharing feedback
This forum is the best place to open discussions and ask questions.

• If you encounter a bug, please use the Unity Bug Reporter in the Unity Editor, accessible via Help > Report a Bug. Include the name of the package (with version number) in the title to help our team triage things appropriately.
• To learn more about what we are working on, you can refer to this post and our public roadmap where you can share feedback and submit ideas.
• If you want to discuss the motivations behind new features and key improvements with our development team, join the conversation here.
• If you want to discuss the motivations behind renaming the Hybrid Renderer to Entities Graphics, join the conversation here.
• If you have any questions about the Entities 1.0 experimental release specifically, ask us here.

Thank you again to everyone who has continued to take the time to share feedback. We look forward to hearing from you!

 

Naw. Plan is to land it properly directly with the pre-release and skip the beta phase. You can learn more here.

 

No, upgrading is fine, just when you upgrade to a later version which has the new transform system everywhere, you might need to rejigger your transform-related code a bit. I imagine that upgrade will be much less significant than the 0.51->1.0 upgrade.

 

@snoche do you happen to have any other compilation errors? I would also check your Editor.log for anything that might block source generators from completing.

We add the IAspectCreate interface to the TransformAspect with sourcegen. If previous errors keep generators from running I could see this happening (but otherwise cannot repro myself with com.unity.entities@1.0.0-exp.8 and Unity 2022.2.0b8).

 

Note that for accessing system data directly, you lose thread safety and lifetime guarantees (basically anything that is risky with direct pointer access). With that said, ISystems can still be directly accessed like

• systemState.WorldUnmanaged.GetUnsafeSystemRef<MySystemType>(systemState.SystemHandle)

There are some options here (following examples assume from within an ISystem).
If using the entity backing a system:

• SystemAPI.GetComponent<MyComponent>(systemState.SystemHandle)
• systemState.EntityManager.GetComponentData<MyComponent>(systemState.SystemHandle)

If using singleton entity components:

• SystemAPI.GetSingleton<MyComponent>()
• any other normal means of accessing singletons

It's worth pointing out that singleton entity components and system entity components are slightly different. They can both be used to store system data, but singleton entity components are not tied to system lifetimes internally, and of course singleton entities must be explicitly created, whereas system entities are created implicitly with system creation.

 

You can pre-Bake a Prefab into Entity data and load that Entity prefab at runtime as its own asset in DOTS Addressables, which will be there for 1.0 release, but I need to double check if it made it into this experimental release or not. Either way, it will be there for 1.0 final.

 

No

 

Hey there! We're still working on providing more robust documentation going into the pre-release of ECS for Unity 2022. In the meantime, feel free to join in on the conversation here with the team working on Burst Occlusion Culling.