Official API usability

Here are some minor features I would like to see that cover up a few use cases.

1. DynamicBuffer.Fixed and/or IJobProcessBufferElement
While investigating this issue https://forum.unity.com/threads/silent-editor-crash-when-using-big-amounts-of-data.571501/ I tried to use DynamicBuffers like I would have a used a NativeArray. In that thread you can see that it didn't go very well.
I know that FixedArray is gone but I propose a DynamicBuffer.Fixed variant of some sort that can be read and written to from an IJobParallelFor like it was a NativeArray. That would cover the case where the buffer size is known up front and the elements can be processed in parallel.
On a higher level an IJobProcessBufferElement could then be offered as a convenience. Maybe such a Job could already work with the current DynamicBuffer implementation?

2. EntityCommandBuffer.CopyFrom(EntityCommandBuffer commandBuffer)
I recently tried implementing an AI System that would add or remove Components after decision making, to bring the AI Agents into the wanted state. Each AI decision system could be specified by only those Components and a few AI rules.
I would really like to be able to save an EntityCommandBuffer up front, pass it to a runtime instantiated AI System and then copy it to another buffer created in a BarrierSystem, inside a Job.
This way I could set up many AI systems from one generic class that would be differentiated by their EntityCommandBuffers.
A CopyFrom function that takes another buffer would be very helpful in this regard as currently the buffers cannot be created and associated with a BarrierSystem in separate.
I think this feature would prove useful in many other scenarios as well.

Edit: To clarify 2. I just want to copy an EntityCommandBuffer's contents to another ECB inside a Job. Preferably also with Concurrent buffers.

 

I'm getting started with the basics and looking at samples to set up a hybrid ECS. It seems like all the current samples, examples, and videos pretty much rely on the injection api but, as i understand it, that's getting removed. I also found the GetEntities<> way from Brackey's video, which i liked a lot more than inject because it feels less magical, but i think that's going away too?

What I found that was simple enough to get my head around was setting up a ComponentGroup in OnCreateManager. Seems simple enough, it just needs good bit of boilerplate code to get started. Biggest negative for my basic needs at the moment is that i can't do subtractive queries? I think i might be able to do it with EntityArchetypeQuery, but Intellisense isn't helping me and i can't find anything in the samples and docs for it

Finally, since there isn't a lot of examples out there on how to currently do this, i was wondering if this looked ok, or am I doing way more than i have to:

Code (CSharp):

1. using UnityEngine;
2. using Unity.Entities;
3. using UnityEngine.Experimental.Input;
4.  
5. public class CombatSystem : ComponentSystem
6. {
7.     ComponentGroup m_RecieverGroup;
8.  
9.     protected override void OnCreateManager()
10.     {
11.         m_RecieverGroup = GetComponentGroup(typeof(Transform), typeof(Health), typeof(Faction));
12.     }
13.  
14.     protected override void OnUpdate()
15.     {
16.         var transformArray = m_RecieverGroup.GetComponentArray<Transform>();
17.         var healthArray = m_RecieverGroup.GetComponentArray<Health>();
18.         var factionArray = m_RecieverGroup.GetComponentArray<Faction>();
19.  
20.         var count = transformArray.Length;
21.  
22.         for (var i = 0; i < count; i++)
23.         {
24.             var transform = transformArray[i];
25.             var health = healthArray[i];
26.             var faction = factionArray[i];
27.  
28.             if (faction.Value == Faction.Type.Player)
29.             {
30.                 if (Keyboard.current.eKey.wasJustPressed)
31.                 {
32.                     health.Value -= 10;
33.                 }
34.             }
35.         }
36.     }
37. }

This is where I was looking for help: https://github.com/Unity-Technologies/EntityComponentSystemSamples

But maybe there is a more up to date place i should be looking?

 

Code (CSharp):

1. new EntityArchetypeQuery()
2.         {
3.             Any = Array.Empty<ComponentType>(),
4.             All = new ComponentType[] { typeof(SomeComponent) },
5.             None= new ComponentType[] { typeof(SomeSubtractiveComponent) },
6.         }

"None" is exactly what is responsible for the subtraction.
In default ComponentGroup way you can do that like this:

Code (CSharp):

1. var group = GetComponentGroup(typeof(SomeComponent),  ComponentType.Subtractive<SomeSubtractiveComponent>());

 

Why not apply the KISS principle...

Code (csharp):

1. ForEach((ref Spawner spawner, in Position position) =>
2. {
3.     Spawner instance = spawner.Entity.Instantiate();
4.     instance.position = position;
5.     instance.CharacterDef.Name = "Player3";
6. });

 

Could we use Tuples as Archetypes?

 

I would prefer something like this:

Code (CSharp):

1. foreach(var spawner in GetEntity<Spawner>())
2. {
3.     var instance = EntityManager.Instantiate(spawner.Entity);
4.     instance.SetComponent<Position>(spawner.position);
5.     instance.GetComponent<CharacterDef>().Name = "Player3";
6. }

The lambda way seems fine, but could get awkward if you want to keep your entity in an array for later iteration.

 

Lambda or not my main point was direct/clean access to data within the inner loop, using a function to access or change data is inherently slow and unintuitive.

 

Ah, I see

I feel like that might not be possible tho, like it's currently not possible to access any component on a GameObject without GetComponent(). I think the Instantiate in this case would return you a ComponentGroup like structure, rather than a specific custom made struct.

 

I'm currently running into some issues where I don't have a good way to create an entity with some default values, like a prefab would be able to. As far as I can tell, the closest I can get is to create an archetype, and build a helper function that passes in all the values and manually setting all those values via SetComponentData calls.

There also isn't a way to clone an entity, which seems like it should be much easier for the EntityManager to be able to do than me trying to do it manually somehow.

 

A bit random, but can DeallocateOnJobCompletion be renamed to DisposeOnJobCompletion?

The justification being that to deallocate a NativeArray (or any native data structure) you call Dispose(), so DisposeOnJobCompletion is a more discoverable and consistent name.

other names:
DiposeOnComplete - we're already in the context of a job so Job is redundant
Dispose - mirrors ReadOnly, WriteOnly
JobDispose - like Dispose but more closely associated with a job

 

DeallocateOnJobCompletion is best and fully reflects the meaning.

 

Some threads like "Is it possible to use Hybrid and Pure at the same time?" or "How do you combine a hybrid ECS with a pure ECS?" (But not "Who is using hybrid right now with the end goal of going pure once unity's engine features catch up?") is suggesting that some user are misunderstanding that it is a hard paradigm shift to choose from, like in the sense of HDRP / LWRP, you cannot have both because only one is activated at the time, all the shaders becomes incompatible, etc.

But actually, hybrid is just some extension/helper C# methods to pure Entity API which adds some game object interaction + wrap MonoBehaviour data to ECS. I think we need some refactoring in the document/terminology so that one does not "choose" hybrid or pure but "use" hybrid methods, when needed. Hybrid must be used with pure, at the same time.

And then there is this "hybrid" status that sounds like a stigma, which currently defined as having touched hybrid methods from the hybrid namespace.

e.g. My game is technically hybrid because I touched some GameObjectArray/GameObjectEntity, but all the important logic which calculate where to move is all in ECS. The hybrid part is important, cannot be removed for sure, but a small piece in the whole design. Trying to go "pure" (for my game) is just an achievement of status, but not much gain. The main block to the pure-ness is just positioning and drawing the mesh. Also! the "pure" example uses SharedComponentDataWrapper (a hybrid part of the lib) to take the mesh in the scene to ECS world on bootstrap.

"Stay pure" is such an elusive goal, but not much different from "a hybrid ECS game" having touch hybrid methods for only a moment while heavy calculations all in pure. Contrary to LWRP and HDRP, it make sense to "stay LWRP" to gain the benefit and not using high definition lighting settings, etc.

But when new comers come to read the docs they are faced with (fake) difficult decision whether to go pure or hybrid. I think it might be good to abstract out these terms?

 

To be honest I blame the confusion on the various videos and docs Unity has pushed about ECS during its early stages (ie: Brackeys, its early space ship tutorial videos, the vague docs).

But with time the confusions will disappear really. There just aren't enough people using ECS yet to give out proper layman examples and patterns.

 

Samples Repository on GitHub is best information place (with documentation in repo), examples and patterns, with reverseingeniring current systems code (like TransformSystem, MeshInstanceRenderer etc.) you get all what you need for learning. In current state ECS not for very begginers in coding, but for peoples who know how to find information and explore other code

 

I don't think we were talking about experienced programmers or where to find good docs.. but more why are there so many people asking questions such as:

You can point them to the Unity examples and say "reverse engineer it ya dummy" but that doesn't help against the misinformation that's out there.

 

It's exactly about we talk Causal relationship

 

The proper answer is: You're too beginner to use it. It's in preview, the code is shifting and the API is changing, you need to mine answers from the source code. End of story.

(And Unity told this countless times now, so I blame the people who does not listen and later come to the forums and ask for documentation and timeline and all kind of things, instead of waiting for the release)

 

What? This is completely beside the point. What I'm talking about is people that go see videos like Brackey's video that confuse people about "Hybrid" / "Pure" ECS that UNITY™ also pushed through their own "ECS Tutorial Mini Series" and then ask these questions. It's not crazy that we're now seeing these posts of people that are confused.

How can you blame them for that?

 

I don't know anything about "Brackey" (I will check up on him), but Unity does not have "ECS Tutorial Series" AFAIK. They have though a "Intro To The Entity Component System And C# Job System", which is merely an introduction what's what and which end is the handle of that sword, it's far from a full tutorial series. As the title says: introduction. Nothing more.

And I repeat, I blame the people who doesn't read and/or listen to the advice, not the people who try to hint what's happening, and what kind of things we will be able to use in the future.

It's kind of similar if you were blaming Salinger for the death of John Lennon.

 

Only thing about the samples is i believe stuff like Inject and GetEntity(might be wrong on this one) are going away and the samples only use these two throughout - which pretty much coincide with the out of date unity sponsored videos and tutorials that you can find out there. You can find stuff on ComponentGroups in the docs, but i don't know how you'd know to look for that without catching a mention of it in a multi-hour long video.

One thing that's lost on me is performance implication of what i'm doing. I have a decent idea of what will hurt/help me in monobehavior land, but in ECS land i'm very confused. Do you have any tips/knowledge there?

 

One thing that I'd like to see are visual debug tools like Gizmos in ECS land. I want to setup a projectile system and play with various trajectories and patterns, but not have to deal with all the scaffolding (hybrid ECS) i have to add to instantiate prefabs. I imagine that'd be handy to visualize a lot of quick testing

 

Watch samples in repo better, every update uses latest features.
+

+

 

https://github.com/Unity-Technologies/EntityComponentSystemSamples/tree/master/Samples/Assets

We’re talking about these samples right? Or is there another batch i should be looking at? Because the latest updates in these still use Inject.

I personally found the new FPS sample to be helpful when i was looking for info on how to get started with the current recommended api. Could be a decent place to point people in the meantime if they need a little api guidance

 

Could we look at synonyms for the longer words in the API to shorten it and make it easier to work with. I'm getting a very strong verbosity vibe from it all.

Entity - Item
Component - Data (prevents Unity from adding Data to all the API names e.g. ISharedComponetData -> ISharedData)
System - Loop
Archetype - Type (EntityArchetype -> ItemType)
Chunk - BitOf
Barrier - Wall

So ECS would be IDL an Item Data Loop...

OK this is a bit satirical and there are probable reserved words in C# forcing some of these naming conventions but 'ComponentData' is surely in this context like TextString or FloatNumber...

And also making the API as simple as possible is also handling the verbosity of the API, don't take my word for it ask any Java programmer...

 

I don't care, there is an IDE which will type the long words for me. I vote for the more verbose and more clear naming convention, preferably what is used in the industry.

Oh, and I'm a "Java programmer" too. And I have an IDE for Java too which does the typing...

 

It was explained why interface is called IComponentData instead of IComponent. It is due too Component class. It would be confusing. Changing name from entity to item would be silly.

 

FPSSample uses [Inject] which is already deprecated so it's not yet a good example of how to use the api in the future.

 

For cloning you can use EntityManager.Instantiate or CommandBuffer.Instantiate. So nothing prevents you from setting up your prefabs (entities) at bootstrap and then just cloning them whenever you need.

 

Honestly, I don't understand your complaining from a topic to a topic about Preview package ECS. If it so bad to you, don't use it then, or just wait until it will get out of preview. Don't get me wrong, but it is frustrating to see how often you spam the forum. Look, 14 threads in 2 weeks. Sometimes you post 2 times in a day, or almost 3 times. I remember times when reading ECS forum was pleasure, but not now.

 

Maybe the forum should have a filter system so you can hide any threads started by Arowx in this case, wait I think it has a blocking feature not sure if it would work at the thread or just the post level...

Give it a try and let me know (oh you won't be able to reply if it works) good luck!

My 2 cents is I'm trying to ensure the ECS is as simple as possible to use (so I can use it) and as good as it can be e.g. maximum chunk size/instruction size, built in messaging bus, so it becomes a powerful toolset.

PS the forum could add a column that allows consolidating threads by creator.

 

Renaming everything to use special names that no other ECS implementation uses, just to save a few letters won't help then.
It rather would probably hinder people who already worked with an ECS architecture.

Also, the Java mindset is basically the antithesis to DoD so I'd be very happy if Unity would not design the API with Java in mind.

 

I as a Java programmer (among other things) second this.

 

Awesome, that will be very helpful. Is it possible to instantiate entities from a different world into the active world? Seems like that would be a better approach than adding a subtractive tag to everything saying to ignore "prefabs"

 

ExclusiveEntityTransaction it's for moving entities between worlds (EntityManager.MoveEntitiesFrom(EntityManager srcEntities);), but anyway Prefab component ignored by default

 

Are there any ways to create an EntityArchetype from a GameObject prefab?

I've seen that you can instantiate a GameObject with EntityManagerExtensions.Instantiate(), but apparently you can only Instantiate things in limited contexts - or your risk invalidating your chunks (or whatever). So you have to use CommandBuffers and none of them support instantiating Prefabs, so i was hoping maybe i could just create an EntityArchetype from a prefab, no instantiation, and just keep a reference to that for later

If not, is there a way to Instantiate and then hide an Entity? I guess i would just have to instantiate hidden entities of what i need at the beginning of the scene and use that for later instantiation

 

The way I did it is by instantiating the original prefab with EntityManager once and then add a Prefab component to it. Then I just instantiate the new prefab with command buffers. I use pure ECS so haven't tried if the prefab has monobehaviours, guess it wont work.

 

Can ComponentType.Create be renamed to ReadWrite? For example,

Code (csharp):

1. _group = GetComponentGroup(
2.   ComponentType.ReadOnly<A>(),
3.   ComponentType.ReadOnly<B>(),
4.   ComponentType.WriteOnly<C>(),
5.   ComponentType.Create<D>());

This has symmetry with ReadOnly and WriteOnly. Create feels a bit arbitrary without strong semantic meaning behind it.

 

I find the system and world creation and refresh control confusing.
Here is a thread showing the confusion. https://forum.unity.com/threads/how-do-you-combine-a-hybrid-ecs-with-a-pure-ecs.575545/#post-3860020
If we could get our hand on a new version of the twin stick shooter that does a bit of world refresh control, that'd help a lot.

 

Thanks a lot, this works!

I spent an ungodly amount of time doing this:

Code (CSharp):

1. PostUpdateCommands.Instantiate(Bootstrap.EnemyEntityPrefab);
2. PostUpdateCommands.SetComponent(new Position() { Value = new float3(pos.x, 0, pos.y) });
3. PostUpdateCommands.SetComponent(new MoveSpeed() { Value = 2 });
4. PostUpdateCommands.RemoveComponent(Bootstrap.EnemyEntityPrefab, typeof(Prefab));

...Don't be like me! I was thinking i had to manually remove the prefab component, but Instantiate handles everything for you. That last line there cost me so much time

 

But "Create" make sense in an API like componentGroup.SetFilterChanged(ComponentType). Maybe we could keep the Create.

 

Any word on when a version of bool/boolx that works with IComponentData is making it's way into Mathematics?

 

But does that actually imply the data was created? iirc ReadOnly/WriteOnly also works there too, and the actual implication is that the chunk version changed, so maybe the data was created or maybe it just changed. So in that sense using Create is confusing (I've used typeof).

 

What about a cleaner API for singleton unique components? How about:

Code (CSharp):

1. EntityManager.SetUniqueComponentData(new SomeDataType() { /* Set Data Here */ });
2.  
3. // In another system:
4. var uniqueData = EntityManager.GetUniqueComponentData<SomeDataType>();

The EntityManager would manage the entity (or entities) that hold the unique components and ensure there's always exactly one of any set component type.

 

What about the immutability or readonly nature of get only properties, could this be used instead of the readonly keyword?

 

I like the idea of

ReadWrite<T>

instead of

Create<T>

for the ComponentType accessors. Fits in with how I've seen it elswhere, such as RO / WO / RW for data descriptions in slides, functions, parameters in other APIs.

 

Have name suffixes been considered in addition to/alternative of [ReadOnly], [WriteOnly]?

[ReadOnly] and [WriteOnly] are already very magical, so I think this fits in nicely as a usability improvement despite being magical. If the suffix is "Ro" imply [ReadOnly], if "Wo" imply [WriteOnly], and "Rw" could be ignored as it is today.

- for parity I have my own type called [ReadWrite] so that every member type is annotated
- with the low-level type/chunk API I've begun annotating types with 'Ro' and 'Rw', for example

Code (csharp):

1. [ReadOnly] public ArchetypeChunkComponentType<MovementAttributes> MovementAttributesTypeRo;
2. [ReadOnly] public ArchetypeChunkComponentType<Progress> ProgressRo;
3. [ReadOnly] public ArchetypeChunkComponentType<Radius> RadiusRo;
4. [ReadWrite] public ArchetypeChunkComponentType<CachedState> CachedStateRw;

Using suffixes reduces API verbosity since the annotations are no longer needed; it also makes it obvious everywhere the variable is used that it is mutable. So the above code would be

Code (csharp):

1. public ArchetypeChunkComponentType<MovementAttributes> MovementAttributesTypeRo;
2. public ArchetypeChunkComponentType<Progress> ProgressRo;
3. public ArchetypeChunkComponentType<Radius> RadiusRo;
4. public ArchetypeChunkComponentType<CachedState> CachedStateRw;

I find this very useful when setting up the job, as the name suffix makes it much more obvious if there is a read-write/read-only/write-only mismatch.

Code (csharp):

1. inputDeps = new Job {
2.   MovementAttributesTypeRo = GetArchetypeChunkComponentType<MovementAttributes>(isReadOnly: true),
3.   ProgressRo = GetArchetypeChunkComponentType<Progress>(isReadOnly: true),
4.   RadiusRo= GetArchetypeChunkComponentType<Radius>(isReadOnly: true),
5.   CachedStateRw= GetArchetypeChunkComponentType<CachedState>(isReadOnly: false),
6. }.Schedule(inputDeps);

 

Could we add default empty collections to EntityArchetypeQuery?

Code (CSharp):

1.     public class EntityArchetypeQuery
2.     {
3.         public ComponentType[] Any = Array.Empty<ComponentType>();
4.         public ComponentType[] None = Array.Empty<ComponentType>();
5.         public ComponentType[] All = Array.Empty<ComponentType>();
6.     }
7.  

It's not a big deal but writing Array.Empty<ComponentType>() gets quite repetitive

 

Wait, what happens if you just don’t include the field? Thats what i’ve been doing

 

Any = new ComponentType[],

 

@0fx360 I am getting this if any of these fields are not set:

Code (CSharp):

1. NullReferenceException: Object reference not set to an instance of an object
2. Unity.Entities.EntityManager.AddMatchingArchetypes (Unity.Entities.EntityArchetypeQuery query, Unity.Collections.NativeList`1[T] foundArchetypes) (at Library/PackageCache/com.unity.entities@0.0.12-preview.19/Unity.Entities/EntityManager.cs:956)
3. Unity.Entities.EntityManager.CreateArchetypeChunkArray (Unity.Entities.EntityArchetypeQuery query, Unity.Collections.Allocator allocator) (at Library/PackageCache/com.unity.entities@0.0.12-preview.19/Unity.Entities/EntityManager.cs:1012)

@wobes They are equivalent. What I would like to have is:

Code (CSharp):

1. new EntityArchetypeQuery{
2.         All = new ComponentType[] {typeof(Whatever}
3.  
4. };
5.  

Without having to write Any and None