Official Entities 0.17 changelog

Whoohoo, looking forward to it. Just got done porting to 0.16 / Physics 0.51....

Seriously, thanks for continuing to move this forward, I know it's taken a slight step back for the 2021 roadmap, but I very much believe my game is only really possible a the scale I envision with DOTS (at least in Unity3d, that is).

So... it's been of the most chaotic, challenging, but also rewarding learning journeys I had in over 10 years since I first touched Unity.

Code (CSharp):

1. New EntityCommandBuffer methods that affect a set of entities matching a query.
2. EntityManager.Debug.GetEntitiesForAuthoringObject
3. Entities.WithFilter(NativeArray<Entity> filteredEntities)

And these are amazing.

Code (CSharp):

1. Update burst to 1.4.1.

Is this accurate? Burst is shown to me as "R" (Verified?) at 1.4.3, is there anything we'd need to downgrade for?

Code (CSharp):

1. Made SystemBase/JobComponentSystem classes partial in preparation of use of Roslyn source generators.

Halelujah!

 

Is there any method for skipping patching for EntityCommandBuffer.AddComponent()? It is impossible to modify every referenced class to sealed class if it is from other pre-compiled library, like UnityEngine.dll.

 

Not released yet?

 

Do we have an ETA? Waiting to check struct System and burst generic job regression fix.
And looks like per component enable/disable is not in the release?

 

Appreciate you posting the change log ahead of release though. Massively prefer this compared to having to download the package and see.

 

I didn't understand what patching of entity references means. And I didn't understand when the regression will occur.
For example, I have the following managed component:

Code (CSharp):

1.     public class ComponentMesh : ISystemStateComponentData {
2.         public Mesh mesh;      
3.         public MaterialPropertyBlock block;
4.         public int layer;
5.         public ShadowCastingMode shadowCastingMode;
6.         public LightProbeUsage lightProbeUsage;
7.         public bool recieveShadows;
8. }

Will there be a performance regression in this case?

 

When you realize the patch notes are one month old and 0.17 is still not available ...

 

Release should be soon after one last notable bug is fixed. Enabled bits are being worked on, but we can't make any guarantees at this point of what exactly lands or when.

1.4.1 is accurate, and it's the version the other packages in the release have been tested against.

When you create an entity via an ECB, you get back a temporary Entity value (which has a negative index) because the entity isn't yet created. In playback of an ECB, temporary Entity values recorded in the commands get 'fixed-up' (mapped to the appropriate real Entity value).

For a managed IComponentData, the class itself and all class type fields would have to be sealed. Both Mesh and MaterialPropertyBlock are sealed, so you should just have to seal ComponentMesh itself.

 

Thank you very much for the clarification.

 

Can we get a .WithSingleton<T>() method for Entities.ForEach? I do always a lookup on the singleton, then pass it to the foreach queries... its "ugly" and i would prefer a more clever way of doing it:

maybe like this?

Code (CSharp):

1. Entities.WithSingleton<CoolSingletonClass>()
2. .ForEach((ref CoolSingletonClass csc) => {
3. etc
4. })

 

Isn't

GetSingleton<T>()

for struct based

IComponentData

in system (and

this.GetSingleton<T>() 

for class based

IComponentData

) not enough for you?

 

Is the concern verbosity? Clarity? Job safety? The current way doesn't seem any more verbose to me:

Code (CSharp):

1.  
2. var csc = this.GetSingleton<CoolSingletonClass>();
3.  
4. Entities..ForEach(() => {
5.      // ... lambda captures csc
6. }).Schedule();

 

Really looking forward to this update!

Can someone from Unity please make a comment here on the day when Entities 0.17 is released?

 

Maybe this is just my crappy understanding of the underlying technology, but i thought that stuff that is "Scheduled" can be run in parallel with other .Schedule() methods if they dont have dependencies on each other. The scheduling will also be deferred to "sometimes later" (-> not in the onUpdate method itself)?

Now when i capture singletons, i dont know when the capture will happen. Does the capture happen the moment the onupdate method runs? Or does it happen when the scheduled job is executing?

If i need to add the singleton to the foreach, its totally clear that the capture will happen the moment the scheduled method is executing.

But i guess from the backlash in this thread there is no deferred execution of jobs so it doesnt matter. I thought the onupdate method is just defining the jobs and via code generation the jobs are generated. So i dont know how the singleton stuff "works" with that

 

var csc = this.GetSingleton<CoolSingletonClass>();
is executed instantaneously. After the function returns it is assigned directly to the local (captured) variable csc.
As all ECS components are a struct (a value types) it can be used in Burst'ed Jobs. So when the scheduled lambda inside the ForEach() is executed deferred it uses the value assigned to csc in the outer scope.

 

Any time you call

GetSingleton<CoolSingletonClass>

on the main thread you are immediately forcing all jobs that use that component to complete (AFAIK). To prevent that you would do

Code (CSharp):

1. var cscEntity = GetSingletonEntity<CoolSingletonClass>();
2. Entities.ForEach((Entity e)=>
3. {
4.     var csc = GetComponent/GetBuffer(cscEntity);
5. }).Schedule();

This way there's no component access until your job actually runs. I don't think that's much more verbose than your presented alternative though.

 

It was on track for this month, but some notable bugs have pushed it back. Last I heard, the new target is mid-January.

 

A ForEach that calls Schedule or ScheduleParallel is scheduled as a job, yes, and so the work is not yet finished (or even necessarily started) when Schedule or ScheduleParallel returns. In that sense, yes, they are deferred.

Sarkahn makes a good point:

While any ECS jobs are on the queue, it's safe to query for entities, but it's not always safe to read or write component values. GetSingletonEntity just runs a query that finds the one entity having a particular component, but GetSingleton retrieves that component's actual value, so GetSingleton has to complete all outstanding jobs that write to that component:

Code (CSharp):

1. public T GetSingleton<T>() where T : struct, IComponentData
2.         {
3.             var typeIndex = TypeManager.GetTypeIndex<T>();
4.          
5.             // Complete all outstanding jobs that write to the singleton component:
6.             _Access->DependencyManager->CompleteWriteDependencyNoChecks(typeIndex);
7.  
8.              // ...
9.  

So there is some merit to the original suggestion because, if a singleton is only used in a ForEach, it would be better to wait to read the value when the ForEach job actually runs. In other words, already scheduled jobs that write to the singleton should just be made dependencies of the ForEach job instead of being immediately completed.

I can't say for sure whether this is something we can or will do, but thanks, I'll pass along the idea! (Come to think of it, this arguably is a specific case of a more general problem: creating ForEach jobs that operate on entities of multiple queries. So maybe this is part of a broader discussion.)

 

Oh... That makes sense, but I did not realize this at all. So to be clear, should one always capture the entity outside of Schedule() and do a GetComponent inside?

Edit: If there is more than one job scheduled, then is is better to do a straight GetSingleton outside of all of the schedules?

Edit2: Would this pattern be loosing some performance because each execution for each entity is forced to get the singleton by themselves? This whole thing seems to have a lot more caveats than I thought...

 

Yes, essentially you end up paying the GetComponent/GetBuffer cost (which is NOT cheap btw) for every single entity you're iterating over. You have a couple of options though - if you manually write an IJobChunk you can then move your GetComponent/GetBuffer call outside of the for loop. You then end up paying the cost for every chunk being iterated over, rather than every entity. Alternatively you can run an initial job to gather up all the data you need into some native container then pass that container into the next job.

I'd love to see some kind API to make this faster/easier for buffers in particular, since personally I end up with a lot of cases where I want to access a buffer (representing my map, for example) throughout a lot of different jobs within a single frame.

 

Well, there is always rather verbose version of doing it async:

Code (CSharp):

1.  
2.             var                 singletonEntity    = GetSingletonEntity<YourSingletonComponent>();
3.             var singleton = new NativeArray<YourSingletonComponent>(1, Allocator.TempJob);
4.             Job.WithCode(() => { singleton[0] = GetComponent<YourSingletonComponent>(playerEntity); })
5.                .Schedule();
6.  
7.             Entities
8.                .WithDisposeOnCompletion(singleton)
9.                .ForEach((ref Whatever    whatever) =>
10.                 {
11.                             // Access your singleton here
12.                    
13.                 })
14.                .Schedule();
15.  

You can even make the array persistent so it doesn't allocate ever frame

 

Can you just write an extension method, something like this?

Code (CSharp):

1. public static class SystemBaseExtensions
2. {
3.     public static JobHandle GetSingleton<T>(this SystemBase system, JobHandle dependency, Allocator allocator, out NativeReference<T> singleton)
4.         where T : unmanaged, IComponentData
5.     {
6.         singleton = new NativeReference<T>(allocator);
7.  
8.         return new GetSingletonJob<T>
9.         {
10.             Entity = system.GetSingletonEntity<T>(),
11.             GetComponent = system.GetComponentDataFromEntity<T>(true),
12.             Singleton = singleton,
13.         }.Schedule(dependency);
14.     }
15.  
16.     [BurstCompile] // probably won't be bursted anyway atm
17.     private struct GetSingletonJob<T> : IJob
18.         where T : unmanaged, IComponentData
19.     {
20.         public Entity Entity;
21.         [ReadOnly] public ComponentDataFromEntity<T> GetComponent;
22.  
23.         [WriteOnly]
24.         public NativeReference<T> Singleton;
25.  
26.         public void Execute()
27.         {
28.             Singleton.Value = GetComponent[Entity];
29.         }
30.     }
31. }

and just use it like

Code (CSharp):

1. Dependency = this.GetSingletonAsync<Translation>(Dependency, Allocator.TempJob, out var singleton);

Disclaimer: haven't tested it

 

What are the replacements for `ComponentDataFromEntity.Exists` and `BufferFromEntity.Exists`?

 

HasComponent

Code (CSharp):

1.  
2. [Obsolete("Use HasComponent() instead. Exists() will be (RemovedAfter 2020-08-20). (UnityUpgradable) -> HasComponent(*)")]
3. public bool Exists(Entity entity)

 

I wonder what was wrong with Exists... but I've been using HasComponent for as long as I could think.

PS: I guess what's wrong was that Exists wasn't verbose enough /s

 

It's for consistency with EntityManager, where Exists() tests for existence of an entity and HasComponent() tests for presence of a component on an entity.

EDIT: I guess it's actually to make ComponentDataFromEntity consistent with SystemBase, which has no Exists method. HasComponent early returns false if the entity doesn't exist, so it's not any more expensive than Exists would be. I'll ask though if there's a rationale for omitting Exists.

 

Hi @BrianWill. Can u make sure this bug will be fixed when 0.17 is released? This bug is still persist at current latest 0.16. One thing I need to note here is it's reproducible on Editor, Android, Windows Standalone and I believe it's also reproducible on other platforms as well. It's not like the description of this issue tracker. https://issuetracker.unity3d.com/is...rms-when-converting-gameobjects-in-a-subscene

 

0.17 is about 2 month old and not released. The next public release will probably be 0.18 or 0.19

 

Whats the source for this? I believe the last time Unity commented on it, 0.17 was still slated for release in mid January, pending a few blocker bugs being addressed.

...I sincerely hope this is still the plan. I’ve been waiting nearly 4 months now for a show stopping issue to be fixed, and it’s already fixed in 0.17...

 

Unity hasn't said anything, but whenever they encounter a shipstopping issue that takes longer than a couple of weeks to resolve, they typically skip a release. They did that for 0.12 and 0.15. This time around they were kind enough to share the release notes and new targets in advance, which are really helpful.

I'm not sure whether we will see 0.17 or 0.18 next, but I am guessing 0.18.

 

(Case 1279727) [Entities 0.14.0-preview.19] Subscene instantiate classic game object that shouldn't instantiate

 

Fwiw, I was referring to this:

 

Ping

 

Ding

 

I was also really hoping for it today. Ah well...

@Brian_Will, thank you for making this post, regardless of when it comes out. Please do it for later builds as well.

 

Also eagerly waiting the update and appreciate the communication on expected changes.

Also, I don't think it really needs a new post, but, someone please clean up the stickies. There are 18 stickied threads which take up 75% of the screen before we can see a normal post. Some of the posts can either be unstickied or the information should be combined into a single place(4 threads relating to samples?).

 

Subforums will solve this easily

 

Nope. I just give u the bug report case number generated from Unity FogBugz. I believe you are able to access it since I always give case number for Unity developer to look into the bug report.

 

Will the release have a getting started document by chance. I am finally making the hop to DOTS.

VR Architect

 

Will we be able to implement ISystemBase on managed classes such as Monobehaviour or ScriptableObject descendants, instead of just structs?

(doesn't need to burst compile, just looking for user friendly ways to inject asset references into certain systems)

 

Can you provide some more info on how and when this can/should be used?

 

Should be used wherever possible as it'll speed up main thread code (such as scheduling etc), and unless dramatically changed recently, it's used something like this

Code (CSharp):

1. struct MySystem : ISystemBase
2. {
3.     void OnUpdate(ref SystemState state)
4.     {
5.         var jobHandle = new MyJob
6.         {
7.  
8.         }.Schedule();
9.     }
10. }

I'm not sure if they've managed to add lambda job support to it yet or not (hoping so.) Find out soon enough.

 

Whenever I close a subscene I get this error:

"Failed to import entity scene because the automatically generated SceneAndBuildConfigGUID asset was not present: 'Assets/Scenes/Island/IslandLevel.unity' -> ''
UnityEngine.Debug:LogError (object)"

I tried googling but not a single result comes up... Anyone seen this before?

EDIT: Deleting the SceneDependencyCache folder fixed it.

 

Finally! Its here + Other DOTs packages.