Release 3

Author: fabriziounity

.editorconfig

@@ -0,0 +1,73 @@
+# see http://editorconfig.org/ for docs on this file
+
+root = true
+
+[*]
+# help with sharing files across os's (i.e. network share or through local vm)
+#end_of_line = lf
+#charset temporarily disabled due to bug in VS2017 changing to UTF-8 with BOM (https://favro.com/card/c564ede4ed3337f7b17986b6/Uni-17877)
+#charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+# formattable file extensions (keep in sync with format.ini from unity-meta repo)
+#
+# Note: We need to split the formattable files configs into shorter duplicate entries (logically grouped)
+# due to known issue in VS editorconfig extension where there is a limit of 51 characters (empirically determined).
+# see: https://github.com/editorconfig/editorconfig-visualstudio/issues/21
+#
+## uncrustify
+[*.{c,h,cpp,hpp,m,mm,cc,cs}]
+indent_style = space
+indent_size = 4
+
+## generic formatter (shaders)
+[*.{cg,cginc,glslinc,hlsl,shader,y,ypp,yy}]
+indent_style = space
+indent_size = 4
+
+## generic formatter (misc)
+[*.{asm,s,S,pch,pchmm,java,sh,uss}]
+indent_style = space
+indent_size = 4
+
+## perltidy
+[*.{pl,pm,t,it}]
+indent_style = space
+indent_size = 4
+
+## unity special
+[*.{bindings,mem.xml}]
+indent_style = space
+indent_size = 4
+
+# other filetypes we want to overwrite default configuration to preserve the standard
+[{Makefile,makefile}]
+# TAB characters are part of the Makefile format
+indent_style = tab
+
+[*.{md,markdown}]
+# trailing whitespace is significant in markdown (bad choice, bad!)
+trim_trailing_whitespace = false
+
+# keep these and the VS stuff below in sync with .hgeol's CRLF extensions
+[*.{vcproj,bat,cmd,xaml,tt,t4,ttinclude}]
+end_of_line = crlf
+
+# this VS-specific stuff is based on experiments to see how VS will modify a file after it has been manually edited.
+# the settings are meant to closely match what VS does to minimize unnecessary diffs. this duplicates some settings in *
+# but let's be explicit here to be safe (in case someone wants to copy-paste this out to another .editorconfig).
+[*.{vcxproj,vcxproj.filters,csproj,props,targets}]
+indent_style = space
+indent_size = 2
+end_of_line = crlf
+charset = utf-8-bom
+trim_trailing_whitespace = true
+insert_final_newline = false
+[*.{sln,sln.template}]
+indent_style = tab
+indent_size = 4
+end_of_line = crlf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = false

.gitignore

@@ -2,9 +2,8 @@
 **/Temp/
 **/obj/
 
-**/.vscode
+**/.vscode/
 **/.vs
-**/.editorconfig
 
 **/Assets/Plugins/*
 **/Assets/Plugins.meta
@@ -23,3 +22,4 @@
 .vs/
 build/*
 TwoStickShooter/Pure/Library/AnnotationManager
+*.rsp

Documentation/content/custom_job_types.md

@@ -30,11 +30,11 @@ The final parameter is the schedule mode. There are two scheduling modes to choo
 Once the schedule parameters are created we actually schedule the job. There are three ways to schedule jobs depending on their type:
 ```C#
 JobHandle Schedule(ref JobScheduleParameters parameters);
-JobHandle ScheduleParallelFor(ref JobScheduleParameters parameters, int arrayLength, int innerloopBatchCount);
-JobHandle ScheduleParallelForTransform(ref JobScheduleParameters parameters, IntPtr transfromAccesssArray);
+JobHandle ScheduleParallelFor(ref JobScheduleParameters parameters, int arrayLength, int innerLoopBatchCount);
+JobHandle ScheduleParallelForTransform(ref JobScheduleParameters parameters, IntPtr transfromAccessArray);
 ```
 Schedule can only be used if the __ScheduleParameters__ are created with __JobType.Single__, the other two schedule functions require __JobType.ParallelFor__.
-The __arrayLength__ and __innerloopBatchCount__ parameter passed to __ScheduleParallelFor__ are used to determine how many indices the jobs should process and how many indices it should handle in the inner loop (see the section on [__Execution__ and __JobRanges__](#execution-and-jobranges) for more information on the inner loop count).
+The __arrayLength__ and __innerLoopBatchCount__ parameter passed to __ScheduleParallelFor__ are used to determine how many indices the jobs should process and how many indices it should handle in the inner loop (see the section on [__Execution__ and __JobRanges__](#execution-and-jobranges) for more information on the inner loop count).
 __ScheduleParallelForTransform__ is similar to ScheduleParallelFor, but it also has access to a __TransformAccessArray__ that allows you to modify __Transform__ components on __GameObjects__. The number of indices and batch size is inferred from the TransformAccessArray.
 
 ## Execution and JobRanges
@@ -51,7 +51,7 @@ The JobRanges contain the batches and indices a ParallelFor job is supposed to p
 ```C#
 JobsUtility.GetWorkStealingRange(ref ranges, jobIndex, out begin, out end)
 ```
-This continues until it returns `false`, and after calling it process all items with index between begin and end.
+This continues until it returns `false`, and after calling it process all items with index between __begin__ and __end__.
 The reason you get batches of items, rather than the full set of items the job should process, is that Unity will apply [work stealing](https://en.wikipedia.org/wiki/Work_stealing) if one job completes before the others. Work stealing in this context means that when one job is done it will look at the other jobs running and see if any of them still have a lot of work left. If it finds a job which is not complete it will steal some of the batches that it has not yet started; to dynamically redistribute the work.
 
 Before a ParallelFor job starts processing items it also needs to limit the write access to NativeContainers on the range of items which the job is processing. If it does not do this several jobs can potentially write to the same index which leads to race conditions. The NativeContainers that need to be limited is passed to the job and there is a function to patch them; so they cannot access items outside the correct range. The code to do it looks like this:

Documentation/content/ecs_in_detail.md

@@ -27,7 +27,7 @@ IComponentData structs may not contain references to managed objects. Since the
 
 An __EntityArchetype__ is a unique array of __ComponentType__. __EntityManager__ uses EntityArchetypes to group all Entities using the same ComponentTypes in chunks.
 
-```
+```C#
 // Using typeof to create an EntityArchetype from a set of components
 EntityArchetype archetype = EntityManager.CreateArchetype(typeof(MyComponentData), typeof(MySharedComponent));
 
@@ -98,7 +98,8 @@ The ComponentData for each Entity is stored in what we internally refer to as a
 
 A chunk is always linked to a specific EntityArchetype. Thus all Entities in one chunk follow the exact same memory layout. When iterating over components, memory access of components within a chunk is always completely linear, with no waste loaded into cache lines. This is a hard guarantee.
 
-__ComponentDataArray__ is essentially an iterator over all EntityArchetypes compatible with the set of required components; for each EntityArchetype iterating over all chunks compatible with it and for each chunk iterating over all Entities in that chunk.
+__ComponentDataArray__ is essentially a convenience index based iterator for a single component type;
+First we iterate over all EntityArchetypes compatible with the ComponentGroup; for each EntityArchetype iterating over all chunks compatible with it and for each chunk iterating over all Entities in that chunk.
 
 Once all Entities of a chunk have been visited, we find the next matching chunk and iterate through those Entities.
 
@@ -115,6 +116,22 @@ By default we create a single World when entering Play Mode and populate it with
 
 > Note: We are currently working on multiplayer demos, that will show how to work in a setup with separate simulation & presentation Worlds. This is a work in progress, so right now have no clear guidelines and are likely missing features in ECS to enable it. 
 
+## System update order
+
+In ECS all systems are updated on the main thread. The order in which the are updated is based on a set of constraints and an optimization pass which tries to order the system in a way so that the time between scheduling a job and waiting for it is as long as possible.
+The attributes to specify update order of systems are ```[UpdateBefore(typeof(OtherSystem))]``` and ```[UpdateAfter(typeof(OtherSystem))]```. In addition to update before or after other ECS systems it is possible to update before or after different phases of the Unity PlayerLoop by using typeof([UnityEngine.Experimental.PlayerLoop.FixedUpdate](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Experimental.PlayerLoop.FixedUpdate.html)) or one of the other phases in the same namespace.
+
+The UpdateInGroup attribute will put the system in a group and the same __UpdateBefore__ and __UpdateAfter__ attributes can be specified on a group or with a group as the target of the before/after dependency.
+
+To use __UpdateInGroup__ you need to create and empty class and pass the type of that to the __UpdateInGroup__ attribute
+```cs
+public class UpdateGroup
+{}
+
+[UpdateInGroup(typeof(UpdateGroup))]
+class MySystem : ComponentSystem
+```
+
 ## Automatic job dependency management (JobComponentSystem)
 
 Managing dependencies is hard. This is why in __JobComponentSystem__ we are doing it automatically for you. The rules are simple: jobs from different systems can read from IComponentData of the same type in parallel. If one of the jobs is writing to the data then they can't run in parallel and will be scheduled with a dependency between the jobs.
@@ -294,7 +311,7 @@ Lastly you can also inject a reference to another system. This will populate the
 
 ## ComponentGroup
 
-The ComponentGroup is foundation class on top of which all iteration methods are built (Injection, foreach, IJobProcessComponetnData etc)
+The ComponentGroup is foundation class on top of which all iteration methods are built (Injection, foreach, IJobProcessComponentData etc)
 
 Essentially a ComponentGroup is constructed with a set of required components, subtractive components. 
 
@@ -348,7 +365,9 @@ class PositionToRigidbodySystem : ComponentSystem
 The Entity struct identifies an Entity. If you need to access component data on another Entity, the only stable way of referencing that component data is via the Entity ID. EntityManager provides a simple get & set component data API for it.
 ```cs
 Entity myEntity = ...;
-var position = EntityManager.SetComponentData<LocalPosition>(entity);
+var position = EntityManager.GetComponentData<LocalPosition>(entity);
+...
+EntityManager.SetComponentData(entity, position);
 ```
 
 However EntityManager can't be used on a C# job. __ComponentDataFromEntity__ gives you a simple API that can also be safely used in a job.
@@ -364,10 +383,78 @@ var position = m_LocalPositions[myEntity];
 
 ## ExclusiveEntityTransaction
 
-EntityTransaction is an API to create & destroy entities from a job. The purpose is to enable procedural generation scenarios where construction of massive scale instantiation must happen on jobs. This API is very much a work in progress.
+EntityTransaction is an API to create & destroy entities from a job. The purpose is to enable procedural generation scenarios where instantiation on big scale must happen on jobs. As the name implies it is exclusive to any other access to the EntityManager.
+
+ExclusiveEntityTransaction should be used on manually created world that acts as a staging area to construct & setup entities.
+After the job has completed you can end the EntityTransaction and use ```EntityManager.MoveEntitiesFrom(EntityManager srcEntities);``` to move the entities to an active world.
+
 
 ## EntityCommandBuffer
 
+The command buffer class solves two important problems:
+
+1. When you're in a job, you can't access the entity manager
+2. When you access the entity manager (to say, create an entity) you invalidate all injected arrays and component groups
+
+The command buffer abstraction allows you to queue up changes to be performed (from either a job or from the main thread) so that they can take effect later on the main thread. There are two ways to use a command buffer:
+
+1. `ComponentSystem` subclasses which update on the main thread have one available automatically called `PostUpdateCommands`. To use it, simply reference the attribute and queue up your changes. They will be automatically applied to the world immediately after you return from your system's `Update` function.
+
+Here's an example from the two stick shooter sample:
+
+```cs
+PostUpdateCommands.CreateEntity(TwoStickBootstrap.BasicEnemyArchetype);
+PostUpdateCommands.SetComponent(new Position2D { Value = spawnPosition });
+PostUpdateCommands.SetComponent(new Heading2D { Value = new float2(0.0f, -1.0f) });
+PostUpdateCommands.SetComponent(default(Enemy));
+PostUpdateCommands.SetComponent(new Health { Value = TwoStickBootstrap.Settings.enemyInitialHealth });
+PostUpdateCommands.SetComponent(new EnemyShootState { Cooldown = 0.5f });
+PostUpdateCommands.SetComponent(new MoveSpeed { speed = TwoStickBootstrap.Settings.enemySpeed });
+PostUpdateCommands.AddSharedComponent(TwoStickBootstrap.EnemyLook);
+```
+
+As you can see, the API is very similar to the entity manager API. In this mode, it is helpful to think of the automatic command buffer as a convenience that allows you to prevent array invalidation inside your system while still making changes to the world.
+
+2. For jobs, you must request command buffers from a `Barrier` on the main thread, and pass them to jobs. The barriers will play back in the created order on the main thread when the barrier system updates. This extra step is required so that memory management can be centralized and determinism of the generated entities and components can be guaranteed.
+
+Again let's look at the two stick shooter sample to see how this works in practice.
+
+First, a barrier system is declared:
+
+```cs
+public class ShotSpawnBarrier : BarrierSystem
+{}
+```
+
+There's no code in a barrier system, it just serves as a synchronization point.
+
+Next, we inject this barrier into the system that will request command buffers from it:
+
+```cs
+[Inject] private ShotSpawnBarrier m_ShotSpawnBarrier;
+```
+
+Now we can access the barrier when we're scheduling jobs and ask for command
+buffers from it via `CreateCommandBuffer()`:
+
+```cs
+return new SpawnEnemyShots
+{
+ // ...
+ CommandBuffer = m_ShotSpawnBarrier.CreateCommandBuffer(),
+ // ...
+}.Schedule(inputDeps);
+```
+
+In the job, we can use the command buffer normally:
+
+```cs
+CommandBuffer.CreateEntity(ShotArchetype);
+CommandBuffer.SetComponent(spawn);
+```
+
+When the barrier system updates, it will automatically play back the command buffers. It's worth noting that the barrier system will take a dependency on any jobs spawned by systems that access it (so that it can now that the command buffers have been filled in fully). If you see bubbles in the frame, it may make sense to try moving the barrier later in the frame, if your game logic allows for this.
+
 ## GameObjectEntity
 
 ECS ships with the __GameObjectEntity__ component. It is a MonoBehaviour. In __OnEnable__, the GameObjectEntity component creates an Entity with all components on the GameObject. As a result the full GameObject and all its components are now iterable by ComponentSystems.

Documentation/content/ecs_principles_and_vision.md

@@ -11,7 +11,7 @@ We measure ourselves against the performance that can be achieved in C++ with ha
 We are using a combination of compiler technology (Burst), containers (Unity.Collections), data layout of components (ECS) to make it easy to write efficient code by default.
 
 * Data layout & iteration - The Entity Component System gurantees linear data layout when iterating entities in chunks by default. This is a critical part of the performance gains provided by the Entity Component System.
-* The C# job system lets you write multithreaded code in a simple way. It also safe. The C# Job Debugger detects any race conditions.
+* The C# job system lets you write multithreaded code in a simple way. It is also safe. The C# Job Debugger detects any race conditions.
 * Burst is our compiler specifically for C# jobs. C# job code follows certain patterns that we can use to produce more efficient machine code. Code is compiled & optimized for each target platforms taking advantage of SIMD instructions.
 
 An example of this is the performance of Instantiation. Comparing to the theoretical limit, of instantiating 100.000 entities with 320 bytes of a memcpy takes 9ms. Instantiating those entities via the Entity Component System takes 10ms. So we are very close to the theoretical lmit.