Experimental Entities 0.51 is Available

Hi everyone! A new experimental version of Entities and other ECS-based packages are now available, making them usable with both Unity 2020 LTS and Unity 2021 LTS.

If you are just getting started, refer to our installation & setup guide. For those who will be upgrading from Entities 0.17 to Entities 0.51, we have put together an upgrade guide that includes common tips during that process.

Minimum requirements:

  • Unity 2021.3.4+
  • Unity 2020.3.30+

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

What’s new
The main update in this release is compatibility with both Unity 2020 LTS and Unity 2021 LTS. We have also fixed several issues since the Entities 0.50 release in March. 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:

Again, thank you to everyone who has taken the time to report issues since the Entities 0.50 release. A lot of the changes and fixes in this release were a direct result of your feedback, and we will continue to release patches with bug fixes as they get resolved.

Known Issues
IL2CPP requires the use of generic sharing to work when using Unity 2021 LTS. This can be enabled via Project Settings > Player > Configuration Section > IL2CPP Code Generation > Faster (smaller) builds. Depending on how generic types are used by your game, there will be an additional runtime cost in IL2CPP builds with generic sharing enabled. We are actively looking into this issue; please share any feedback you have to help guide our efforts towards addressing this.

We will also follow up with those of you who have already reported issues. If you encounter a bug, please submit a bug via Help > Report a Bug in the Unity Editor. This will help ensure we have the information needed to properly investigate the issue.

Notable Highlights
For those who have been waiting for compatibility with Unity 2021 LTS, here is a recap of updates since the Entities 0.17 release.

Entity Authoring

  • The Entity Debugger window has been replaced with several new windows that are now more embedded within the Editor:

  • Entities, Components, and Systems windows to search, select, and inspect via the Inspector

  • A Hierarchy window that shows the full Entities hierarchy and allows for selection of entities

  • Archetypes window to show all current archetypes and details for each

  • Two new Profiler modules to profile ECS structural changes and memory:

  • 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

  • Entities Journaling to record and explore ECS events, using static APIs and the IDE Watch window, and understand data lifecycles and debug your game

  • Note: The com.unity.dots.editor package has been merged with com.unity.entities

System and Entities API Improvements

  • A new simplified SystemBase type that allows for implicit job scheduling and the ability to schedule jobs to run both sequentially and in parallel
  • Entities.WithFilter(NativeArray<Entity> entities) allows filtering Entities.ForEach so that it only iterates over a set of entities
  • New IJobEntity job interface, for implementing re-usable and burstable jobs that iterate over entities
  • The list of chunks matching an EntityQuery is now automatically cached internally, significantly improving the performance of most EntityQuery operations between structural changes (especially in titles with high empty archetype counts)

Improved Debugging

  • Visibility into the generated C# code for inspection and debugging
  • The most commonly-used Entities types now have debugger type proxies, significantly improving the ease of inspecting their state during in-IDE debugging sessions
  • More debug functionality is available in standalone builds, including debug checks and per-Entity debug names

Netcode Updates

  • Physics can be predicted, making it possible to build games where players are directly interacting with and affecting physics objects in the world.
  • Ghosts can switch between being interpolated and predicted at runtime. This allows a client to dynamically predict everything that is close or important without paying the cost of predicting everything.
  • Improved support for streaming sub-scenes and loading prefabs on demand across various client-server configurations.
  • Commands can be sent without explicitly setting the command target on the connection, enabling a client to control multiple ghosts. This also enables changing which ghost a client is controlling at runtime - for example when entering a vehicle.
  • The code-gen has changed to source-generators, making them more robust and less likely to go out of sync.

Rendering Updates

  • Hybrid Renderer V2 (HRV2) is now the default option and replaces Hybrid Renderer V1 (HRV1), which has been removed. This ensures users are now supported with a GPU-persistent data model, removing the main thread bottleneck of HRV1, and improving render thread performance.
  • HVR2 also has a broader compatibility with a range of shaders, and equips users with previously missing HDRP and URP features.

Unity Physics and Havok Updates

  • Collision and trigger events now share a common interface, and simulation systems have been refactored to allow multiple physics worlds.
  • Integration between Unity Physics and the Universal Render Pipeline (URP) has been improved, with new shaders in the sampler, and URP compliant materials.

Sharing feedback
As mentioned earlier, a lot of the changes in this experimental release are a direct result of shared feedback. This forum is the best place to open discussions and ask questions. If you encounter a bug, use the Unity Bug Reporter in the Unity Editor, accessible via Help > Report a Bug. Please include the name of the package (with version number) in the title to help our team triage things appropriately.

We have also enjoyed seeing what the community has created so far. Continue sharing your projects in this thread!

Looking ahead
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.

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

23 Likes

I just want to say: Thank You! You’re heading Right with your communication & connection to the community. Keep it that way, guys! :smile:

5 Likes

We just landed June update for our game and now can safely migrate to 0.51. Thanks DOTS team, just in time!

9 Likes

Hi, I have not tested Entities yet, and frankly feel much intimidated to do so,
But I just want to say from what I’ve seen in this post:

Is there any chance of packing everything above in as little windows as possible?
-For instance, add Components and Systems as drop down items in the Hierarchy for each Entity.
-Making Archetypes and all analysis in a single compact window.
-Somehow merge Entities with GOs and toggle between them.
-And get rid of boiler plate to get as close to previous C# starter file as possible.

Doing this would be fantastic and would insure maximum number of adoption for the new system when it gets out!
-Thanks in advance.

I find that quite counter-intuitive and cumbersome, less is better!

1 Like

You can arrange any windows as you like. Pin them, move to side, group, make floating group.
Also, there is many cases, when for example you don’t to want to track systems execution, when working with entities, or vice versa.

Old entity debugger had completely different purpose and it was expected to be eventually obsolete.

1 Like

Hi, is it possible that the ECS samples do not work with this version? Thanks.

DOTS samples should be compatible with Entities 0.50 / 0.51, Unity 2021.3.4f1

3 Likes

If Entities are analogous with GameObjects, we split everything into their proper dedicated windows for the same reason why GameObjects have different windows for their various views and workflows. You wouldn’t expect a Hierarchy, Scene, Inspector, and Profilers for GameObjects all locked together into a static monolithic EditorWindow. This is all further developed in our Entities 1.0 hybrid GO/Entitiy workflows (see below) that would not be possible if we stayed with the Entity Debugger approach.

This will be the case for Entities 1.0! See the complete workflow in action here:

https://www.youtube.com/watch?v=p4ct4vHWYt0

8 Likes

Tangentially related but I do hope that there are plans or designs on better window and workflow management down the road, its getting quite tedious going to window > multitude of nesting subwindows to choose from. Similarly Assets > Create > Huge dropdown list that is a pain in my small project, assuming its a pain in big projects too.

Just about every other 3d DCC program has better workflows regarding how this is tackled. Maya has its workspaces, blender has its tabs, zbrush has its palettes(I know a lot of people hate its ui but its extremely customizable through drag and drop).

I did see this teased a while back on some roadmap talk a long time ago(sadly I think years). I know I can technically program something but that only helps me and ideally this is something that everyone could benefit from.

Unity has right approach for what they do.
There is no issue here, since you got all tabs and you can adjust your menu’s as you like. Having tabs sections as you like. You open it and keep it open as long you need.

Having opened too many stuff at once as you propose, displaying everything, specially what is not needed at given use case, is a major workflow issue.

For example old EntityDebugger shows many things, but in many cases, like just viewing entities, chunks and systems are unnecessary and slows down the debugging process.

In the top right corner, you have also Layout selection
8236779--1076736--upload_2022-6-27_23-15-53.png
You can save any layouts as you need. So you don’t need click so many things once is saved.

7 Likes

Maybe place 3~ layout buttons besides the layout dropdown? It’s not like there is no space there for that, but if you just have to click a button rather than navigate a drop down, maybe people will be more inclined to actually use the layouts feature? Somehow I made my uber layout that has everything all at once and just settled for that, even knowing that I could do better with the feature.

Separate from DOTS, there are indeed designs and plans to extend the existing Layouts feature in the Editor and have it become more of a workspace management feature. But no ETA on this currently. For now, I found it helpful to eagerly create my own Layouts for working with Entities. You can even save them to a file and add them to version control for the rest of the team to use.

7 Likes

Now that you added more modes to the scene view, simplicity is muddled so we need:

  • a special color around the scene view frame to indicate authoring
  • click in the game view to select objects in authoring view
1 Like

Sorry for the negativity but I can’t stop feeling that unity is trying to sell us a “sorry, we couldn’t achieve parity with existing workflows” product as something “look at this new awesome workflows that increase productivity so much”.

“Things changed in the scene during play mode are reverted upon leaving play mode”, this has been a rule since I have memory of unity (I started on v3). Now you are breaking that rule for part of unity, making us manually change between “modes” that are hard to differentiate, very easy to forget/miss the currently active one leading to things getting changed permanently without us realizing. (Which actually happens in the presentation)

“Changes to things in the scene outside of play mode stay until u close the scene, and u can save them” is another rule of… well not unity, but pretty much every software out there. Why challenge that behavior?

“The Scene View reflects what’s currently in your game but without the constrains of the player’s camera” is yet another well stablished and to be blunt, irreplaceable, workflow of unity (and other game engines). It allows us to easily check, understand and debug things as they happen. This new proposed workflow still show us the numbers in the inspector yes… because ofc I can tell at a glance that at its current Y=0.5 some object outside of the player’s camera frustum is penetrating another from bellow and causing some unwanted physic interactions… (sorry for the sarcasm but heck, it’s so obvious it hurts)

Prefabs instantiated on an scene can be changed (with some very specific limitations yes) and if u want to apply some of those changes to the prefab u have a nice menu to do so. Why not reuse this well stablished unity workflow for this too?

I know entities are not gameobjects. I know some things are really really hard or almost imposible to replicate. What I don’t like here is unity trying to sell it as it is better than the current go workflow when it clearly isn’t (at most they could be a match).
Maybe I’m just being over sensitive because well, u know, the original over-selling of DOTS and all the friction it created back in the day.

Sorry again for the rant tone but there are some legit questions there too.

2 Likes

Scene view modes have always existed. Definitely already there in 0.17. You could choose, via the DOTS menu, whether the Scene view is in Runtime mode (renders Entities, you see them moving in Play mode) or Authoring mode (renders GOs, and they don’t move in Play mode since GOs are stripped from the runtime after conversion). So this part is not new in 1.0. That said, we of course plan to add the same clarity to the Scene view regarding these modes as we did for the Hierarchy and Inspector. This will be done in future versions.

4 Likes

You will have the option to lock all the windows to always show Authoring-only data in Edit mode and Runtime-only data in Play mode - reproducing the exact same behavior as pure GO Unity today. The only difference you’ll see is that Runtime data is CLEARLY marked orange/red so it’s abundantly clear when a change will be lost when exiting Play mode. Something that is very much not clear today, especially for new users.

The opposite confusion, where users change values in Play mode without realizing and then having to redo that work after exiting Play mode, has been a problem this whole time. It’s why we added the full-Editor color tint feature for Play mode. This is the main problem we wanted to fix. Because this tint in itself is a lie. If you are in pink-tint Play mode and select a Prefab Asset, you can easily assume that changes in the Inspector will NOT be saved, but in fact, they will. So we had to do something here.

And adding this new way of working does not replace our goal to achieve parity between Entities and GOs. That’s still a long-term goal. In the meantime, it would be silly to not take advantage of the unique possibilities that the Entities offers and try something new. It’s not a guarantee this new Authoring vs. Runtime workflow will be an improvement, which is why it makes even more sense to try it out for Entities only, with a limited scope, before considering it for broader adoption.

How does this behavior change in the new workflow? If you’re referring to being able to enter Play mode with unsaved changes in your Scene and without being forced to save, this is also not new. You were always able to do that.

Please clarify. I’m not sure how the new workflow adds any relation between the camera and what you see in the Hierarchy. Like, what is the issue here? And again, you can force and lock the data mode of the Hierarchy to make it behave like it has always behaved in Unity.

Again, what is the issue here? What has changed the goes against this pattern? You can still modify Prefabs exactly the same way you could before.

The over-sell was all about performance. This topic, around Authoring vs. Runtime, has nothing to do with performance. It is all about our efforts to properly integrate Entities into the existing Unity Editor and achieve a reasonable balance between consistency with GOs workflows and taking advantage of new Entities possibilities. Going all the way and making Entities EXACTLY the same as GOs would have left way too much on the table and would have been essentially lying to users about what is actually happening under the hood.

14 Likes

Hi @uDamian . From what I understand, Entity Debugger will be deprecated and removed but at current dots 0.51 release the tooling at Windows > DOTS still can’t get equivalent tooling features at Entity Debugger as following:

  1. Chunk Info to visualize all the chunks sorted by archetype with chunk utilization, component read write and etc
  2. Filter the entity and chunk by selecting specific component and it will only show Entity and chunk that match with the selected component
  3. Select chunk and it will only show all the entities in that chunk

I hope dots 1.0 release will get similar tooling features when removing Entity Debugger. Currently there is Archetypes windows but lacking the tooling features I mention.

If that will be an option then I don’t have any further complaint with the mode changes.

Yes but I think that is a lot less likely. Selecting things in the scene and selecting assets is a clear different action from our side so different behaviors are perfectly reasonable (having a background color change in the inspector to clearly differentiate when we have a go or an asset is welcome though).
The only odd ball there are materials inside a renderer component of a go which will edit the material asset… that is a “surprise” factor that works against UX.

Good to know.

I was trying to say that having a manual persistence mode and a transient mode is quite unconventional. Not inherently bad, just weird.

Seems I missed the part where its said that changing modes in the scene view allows it to render the “current real time state” of the scene.

I was trying to suggest (in a poor way) the use of this behavior for all scene objects in play mode instead of the mode change. So, changing something in play mode generates an “override” that we can then chose to permanently apply to the GO (well, not permanent permanent, just add the change to the scene file which in turns then needs to be manually saved for a real permanent change.) Upon leaving play mode, unapplied overrides are discarded and forgotten.
Sorry for being extremely unclear.

Fair enough.

Thx for taking the time to answer to my long and “ranty” post.

Hi.

Updated to 0.51 and latest 2021 LTS and during game play I constantly receive errors similar to the following:

IndexOutOfRangeException: Index 15 is out of range of '15' Length.
Unity.Collections.NativeArray`1[T].FailOutOfRangeError (System.Int32 index) (at <4a31731933e0419ca5a995305014ad37>:0)
Unity.Collections.NativeArray`1[T].CheckElementReadAccess (System.Int32 index) (at <4a31731933e0419ca5a995305014ad37>:0)
Unity.Collections.NativeArray`1[T].get_Item (System.Int32 index) (at <4a31731933e0419ca5a995305014ad37>:0)
Unity.Rendering.SimpleCullingJob.Execute (Unity.Entities.ArchetypeChunk archetypeChunk, System.Int32 chunkIndex, System.Int32 firstEntityIndex) (at Library/PackageCache/com.unity.rendering.hybrid@0.51.0-preview.32/Unity.Rendering.Hybrid/HybridV2Culling.cs:351)
Unity.Entities.JobChunkExtensions+JobChunkProducer`1[T].ExecuteInternal (Unity.Entities.JobChunkExtensions+JobChunkWrapper`1[T]& jobWrapper, System.IntPtr bufferRangePatchData, Unity.Jobs.LowLevel.Unsafe.JobRanges& ranges, System.Int32 jobIndex) (at Library/PackageCache/com.unity.entities@0.51.0-preview.32/Unity.Entities/IJobChunk.cs:401)
Unity.Entities.JobChunkExtensions+JobChunkProducer`1[T].Execute (Unity.Entities.JobChunkExtensions+JobChunkWrapper`1[T]& jobWrapper, System.IntPtr additionalPtr, System.IntPtr bufferRangePatchData, Unity.Jobs.LowLevel.Unsafe.JobRanges& ranges, System.Int32 jobIndex) (at Library/PackageCache/com.unity.entities@0.51.0-preview.32/Unity.Entities/IJobChunk.cs:368)

Since these errors are all occurring within the Entities/HybridV2 packages and the stack trace does not lead back to any of my code I have no idea what is causing it or how to fix it.

The issue appears to be due to an invalid index reference for the variable finalindex into the chunkInstanceBounds array within the SimpleCullingJob struct of HybridV2Culling.cs. See below:

                                var finalIndex = (j << 6) + bitIndex;

                                scratch[instanceOutputOffset] = processedInstanceCount + finalIndex;
                                // IndexList[batchOutputOffset + batchOutputCount] = processedInstanceCount + finalIndex;
                                // Debug.Log($"DEBUGCULLING Partial {externalBatchIndex}: [{batchOutputOffset + batchOutputCount}] = {processedInstanceCount + finalIndex}");

                                int advance = FrustumPlanes.Intersect2(Planes, chunkInstanceBounds[finalIndex].Value) !=
                                    FrustumPlanes.IntersectResult.Out
                                    ? 1
                                    : 0;

Has anyone else had this issue and were able to fix?