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):

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

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: 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: (new SomeJob().Schedule(someCombinedHandle))
  • If you schedule an IJobEntity constructed with an initialization expression that invokes a SystemAPI method, such as: 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: 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!

48 Likes

is a 1.0 preview package for havok in the works(noticed one doesnt appear available yet)?

Is there something new to animate characters?

3 Likes

[quote=“thelebaron”, post:2, topic: 895383]
is a 1.0 preview package for havok in the works(noticed one doesnt appear available yet)?
[/quote]

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

2 Likes

omg thank unity, we wait for that for a long time

1 Like

Hello, just wondering if this means we can’t upgrade if we’re using physics or netcode, or does it mean that it’s just a bit suboptimal for now? I gather it’s the later due to upgrade physics and netcode packages? But unsure what the impact of this incompatibility actually is.

Lubberly Jubberly Rodney. Going to be pukka.

1 Like

I see the last screenshot is from the Rival FPS Character Controller (https://assetstore.unity.com/packages/tools/physics/rival-dots-character-controller-for-unity-225129). Any idea on when that package will be upgraded to support the experimental 1.0 release?

2 Likes

[quote=“laurentlavigne”, post:3, topic: 895383]
Is there something new to animate characters?
[/quote]
no =))

[quote=“Shinyclef”, post:6, topic: 895383]
Hello, just wondering if this means we can’t upgrade if we’re using physics or netcode, or does it mean that it’s just a bit suboptimal for now? I gather it’s the later due to upgrade physics and netcode packages? But unsure what the impact of this incompatibility actually is.
[/quote]
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.

1 Like

https://github.com/Unity-Technologies/EntityComponentSystemSamples
We need updated sample projects. It will say more than document.

7 Likes

Is the new transform component intended to be deterministic across machines?
The other document says transform will be 8 floats so I'm thinking we'll still have indeterminism across multiplayer simulations but just wanted to ask since determinism would be such a great checkmark.

How to group entities in dots hierachy? Previously I could add Parent component (from transforms) and it would group them, however new transform system has query that picks Parent every update and generates unnecessary overhead.

I guess a "group" that isn't in the the same archetype would also incur a memory lookup, maybe the cost is similar? Does seem weird they'd change that though.

Is this feature in preview and not recommended to use since 2019?

Hi, I am a little concerned how job system picks his dependencies to finish right now, even without using SystemBases dependency, other parts of code are randomly completing our jobs. For instance job scheduled parallel in simulation group if active will be completed on MeshRendererFinilizeUpdate. I would like to know if this is intentional since it didn't behave that way on 0.51f.

I am trying with Unity 2022.2.0b8.3023 but got this error:

Library\PackageCache\com.unity.entities@1.0.0-exp.8\Unity.Entities.Editor\Inspector\Aspects\TransformAspectInspector.cs(11,11): error CS0315: The type 'Unity.Transforms.TransformAspect' cannot be used as type parameter 'TAspect' in the generic type or method 'EntityAspectContainer'. There is no boxing conversion from 'Unity.Transforms.TransformAspect' to 'Unity.Entities.IAspectCreate'.

Any idea how to fix this?

[quote=“Kichang-Kim”, post:11, topic: 895383]
https://github.com/Unity-Technologies/EntityComponentSystemSamples
We need updated sample projects. It will say more than document.
[/quote]
8472533--1126031--upload_2022-9-28_16-13-54.png

6 Likes

@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).

Ooooof it's time to another huge refactoring of our game? :hushed: Well, probably no, not this time, as we heavily rely on runtime conversion and addressables, and that's not the good idea to apply such core changes to production game...Seems with Diplomacy is Not an Option, we stuck on 0.51 :smile: It's been a fun ride from the beginning to nearly the end of experimental stage of Entities, thanks DOTS team for that! But for our new projects (which is already in development) we can safely start to use Entities 1.0!;)

20 Likes