Release 2

Author: fabriziounity

Documentation/content/cheatsheet.md

@@ -0,0 +1,79 @@
+# ECS Cheat Sheet
+
+Here is a quick reference of the common classes, interfaces, structs, and attributes that have been introduced in this documentation by [ECS](#ecs-related), [Burst compiler](#burst-compiler-related) and the [C# job system](#c#-job-system-related). Click the links below for more information from the Unity Manual and Scripting API.
+
+> Note: This is not an exhaustive list and can be added to over time as ECS, and its related documentation, expands. Check the ECSJobDemo code and the [Scripting API]() under the namespaces mentioned below for more examples.
+
+## C# job system related
+
+> Note: These can also be used by ECS code, but they are part of the main Unity 2018.1 release and not part of the ECS packages.
+
+| Namespace | Name | Type |
+| :-------------: |:-------------:| :-----:|
+| Unity.Collections | [NativeArray](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.NativeArray_1.html) | Struct |
+| Unity.Collections | [NativeContainer](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.LowLevel.Unsafe.NativeContainerAttribute.html) | Unsafe Class | 
+| Unity.Collections | [NativeSlice](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.NativeSlice_1.html) | Struct | 
+| Unity.Jobs | [IJob](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Jobs.IJob.html) | Interface | 
+| Unity.Jobs | [IJobParallelFor](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Jobs.IJobParallelFor.html) | Interface |
+| Unity.Jobs | [JobHandle](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Jobs.JobHandle.html) | Interface |
+| Unity.Jobs | [JobsUtility](https://docs.unity3d.com/es/2018.1/ScriptReference/Unity.Jobs.LowLevel.Unsafe.JobsUtility.html) | Unsafe Class |
+
+### Attributes
+
+* [[ReadOnly]](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.ReadOnlyAttribute.html)
+* [[WriteOnly]](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.WriteOnlyAttribute.html)
+
+## ECS related
+
+| Namespace | Name | Type |
+| :-------------: |:-------------:| :-----:| 
+| Unity.Collections | [NativeHashMap](../../ECSJobDemos/Packages/com.unity.collections/Unity.Collections/NativeHashMap.cs) | Unsafe Struct |
+| Unity.Collections | [NativeList](../../ECSJobDemos/Packages/com.unity.collections/Unity.Collections/NativeList.cs) | Unsafe Struct |
+| Unity.Collections | [NativeQueue](../../ECSJobDemos/Packages/com.unity.collections/Unity.Collections/NativeQueue.cs) | Unsafe Struct |
+| Unity.Entities | [ComponentDataArray](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/Iterators/ComponentDataArray.cs) | Unsafe Struct |
+| Unity.Entities | [ComponentDataFromEntity](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/Iterators/ComponentDataFromEntity.cs) | Unsafe Struct |
+| Unity.Entities | [ComponentGroup](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/Iterators/ComponentGroup.cs) | Unsafe Class |
+| Unity.Entities | [ComponentSystem](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/ComponentSystem.cs) - [ECS Docs](./getting_started.md#what-is-ecs?) | Abstract Class |
+| Unity.Entities | [ComponentType](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/Types/ComponentType.cs) | Struct |
+| Unity.Entities | [Entity](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/EntityManager.cs) | Struct |
+| Unity.Entities | [EntityArchetype](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/EntityManager.cs) | Unsafe Struct |
+| Unity.Entities | [EntityCommandBuffer](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/EntityCommandBuffer.cs) | Unsafe Struct |
+| Unity.Entities | [EntityManager](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/EntityManager.cs) | Unsafe Class |
+| Unity.Entities | [ExclusiveEntityTransaction](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/ExclusiveEntityTransaction.cs) | Unsafe Struct |
+| Unity.Entities | [GameObjectEntity](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities.Hybrid/GameObjectEntity.cs) | Class |
+| Unity.Entities | [IComponentData](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/IComponentData.cs) - [ECS Docs](./ecs_in_detail.md#icomponentdata) | Interface |
+| Unity.Entities | [IJobProcessComponentData](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/IJobProcessComponentData.cs) | Interface |
+| Unity.Entities | [ISharedComponentData](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/IComponentData.cs) - [ECS Docs](./ecs_in_detail.md#shared-componentdata) | Interface |
+| Unity.Entities | [JobComponentSystem](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/ComponentSystem.cs) | Abstract Class |
+| Unity.Entities | [World](../../ECSJobDemos/Packages/com.unity.entities/Unity.Entities/Injection/World.cs) | Class |
+| Unity.Jobs | [IJobParallelForBatch](../../ECSJobDemos/Packages/com.unity.jobs/Unity.Jobs/IJobParallelForBatch.cs) | Interface |
+| Unity.Jobs | [IJobParallelForFilter](../../ECSJobDemos/Packages/com.unity.jobs/Unity.Jobs/IJobParallelForFilter.cs) | Interface |
+| Unity.Rendering | [MeshInstanceRendererComponent](../../ECSJobDemos/Packages/com.unity.entities/Unity.Rendering.Hybrid/MeshInstanceRendererComponent.cs) | Class |
+| Unity.Transforms | [PositionComponent](../../ECSJobDemos/Packages/com.unity.entities/Unity.Transforms/PositionComponent.cs) | Class |
+| Unity.Transforms | [CopyInitialTransformFromGameObjectComponent](../../ECSJobDemos/Packages/com.unity.entities/Unity.Transforms.Hybrid/CopyInitialTransformFromGameObjectComponent.cs) | Class |
+| Unity.Transforms | [TransformMatrixComponent](../../ECSJobDemos/Packages/com.unity.entities/Unity.Transforms/TransformMatrixComponent.cs) | Class |
+
+### Attributes
+
+* [Inject]
+
+#### Unsafe attributes 
+
+* [[NativeContainer]](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.LowLevel.Unsafe.NativeContainerAttribute.html)
+* [[NativeContainerIsAtomicWriteOnly]](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.LowLevel.Unsafe.NativeContainerIsAtomicWriteOnlyAttribute.html) 
+* [[NativeContainerSupportsMinMaxWriteRestriction]](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.LowLevel.Unsafe.NativeContainerSupportsMinMaxWriteRestrictionAttribute.html) 
+* [[NativeContainerNeedsThreadIndex]](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.LowLevel.Unsafe.NativeContainerNeedsThreadIndexAttribute.html)
+* [[NativeContainerSupportsDeallocateOnJobCompletion]](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.LowLevel.Unsafe.NativeContainerSupportsDeallocateOnJobCompletionAttribute.html)
+* [[NativeDisableUnsafePtrRestriction]](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.LowLevel.Unsafe.NativeDisableUnsafePtrRestrictionAttribute.html)
+* [[NativeSetClassTypeToNullOnSchedule]](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Collections.LowLevel.Unsafe.NativeSetClassTypeToNullOnScheduleAttribute.html)
+
+### Other
+
+* \#if ENABLE_UNITY_COLLECTIONS_CHECKS ... #endif
+
+## Burst compiler related
+
+### Attributes
+
+* [[BurstDiscard]](https://docs.unity3d.com/2018.1/Documentation/ScriptReference/Unity.Burst.BurstDiscardAttribute.html)
+* [ComputeJobOptimization]

Documentation/content/ecs_concepts.md

@@ -1,6 +1,6 @@
 # ECS concepts
 
-If you are familiar with [Entity-component-system](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system) concepts, you might see the potential for naming conflicts with Unity's existing __GameObject__/__Component__ setup. Below is a list comparing how ECS concepts map to Unity's implementation:
+If you are familiar with [Entity-component-system](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system) (ECS) concepts, you might see the potential for naming conflicts with Unity's existing __GameObject__/__Component__ setup. Below is a list comparing how ECS concepts map to Unity's implementation:
 
 ### Entity → Entity
 

Documentation/content/ecs_in_detail.md

@@ -174,11 +174,11 @@ See [ExclusiveEntityTransaction](#exclusiveentitytransaction) for more on avoidi
 
 ## Shared ComponentData
 
-IComponentData is appropriate for data that varies between Entities, such as storing a world position. __ISharedComponentData__ is useful when many Entities have something in common, for example in the boid demo we instantiate many Entities from the same Prefab and thus the __InstanceRenderer__ between many boid Entities is exactly the same. 
+IComponentData is appropriate for data that varies between Entities, such as storing a world position. __ISharedComponentData__ is useful when many Entities have something in common, for example in the boid demo we instantiate many Entities from the same Prefab and thus the __MeshInstanceRenderer__ between many boid Entities is exactly the same. 
 
 ```cs
 [System.Serializable]
-public struct InstanceRenderer : ISharedComponentData
+public struct MeshInstanceRenderer : ISharedComponentData
 {
  public Mesh mesh;
  public Material material;
@@ -188,7 +188,7 @@ public struct InstanceRenderer : ISharedComponentData
 }
 ```
 
-In the boid demo we never change the InstanceRenderer component, but we do move all the Entities __TransformMatrix__ every frame.
+In the boid demo we never change the MeshInstanceRenderer component, but we do move all the Entities __TransformMatrix__ every frame.
 
 The great thing about ISharedComponentData is that there is literally zero memory cost on a per Entity basis.
 

Documentation/content/ecs_principles_and_vision.md

@@ -1,4 +1,6 @@
-# ECS principles and vision
+# Entity Component System principles and vision
+
+The Entity Component System is built on a set of principles. These principles provide a good context for what we are trying to achieve. Some of the principles are clearly reflected in the code. Others are simply goals that we set for ourselves.
 
 ## Performance by default
 
@@ -8,10 +10,11 @@ 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.
 
-* Multicore - TODO
-* SIMD - TODO
-* Data layout & iteration - TODO
-* Instantiation speed - TODO
+* 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.
+* 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.
 
 At Unite Austin we showcased a demo with 100.000 individual units in a massive battle simulation running at 60 FPS. All game code was running multicore.
 [See ECS performance demo [Video]](https://www.youtube.com/watch?v=0969LalB7vw)
@@ -45,17 +48,18 @@ We are focused on providing best of class network engine support for hosted game
 * FPS - Simulation on the server
 * RTS - Deterministic lock step simulation
 * Arcade games - GGPO
-TODO: More detail / Links (maybe a game type example of what you would use each network architecture for)
+
+> Note: To set expectations right, we are not yet shipping any networking code on top of Entity Component System. It is work in progress.
 
 ## Determinism
 
 Our build pipeline must be [deterministic](https://en.wikipedia.org/wiki/Deterministic_algorithm). Users can choose if all simulation code should run deterministically.
 
-This is important for networking, replay features and even advanced debugging tools.
+You should always get the same results with the same inputs, no matter what device is being used. This is important for networking, replay features and even advanced debugging tools.
 
-We will leverage our Burst compiler to produce exact floating point math between different platforms. Imagine a linux server & iOS device running the same floating point math code. This is useful for many scenarios particularly for connected games, but also debugging, replay etc.
+To do this we will leverage our Burst compiler to produce exact floating point math between different platforms. Imagine a linux server & iOS device running the same floating point math code. This is useful for many scenarios particularly for connected games, but also debugging, replay etc. 
 
-TODO - link/explain the floating math problem a little before the burst compiler solved it (so those who are unaware of the fp math issue get the point.) Is this a good reference I'm not sure: https://hal.archives-ouvertes.fr/file/index/docid/281429/filename/floating-point-article.pdf
+> Note: Floating point math discrepancies is a problem that Unity decided to tackle head on. This issue has been known about for some time, but so far there has not been a need great enough to encourage people to solve it. For some insight into this problem, including some of the workarounds needed to avoid solving it, consider reading [Floating-Point Determinism by Bruce Dawson](https://randomascii.wordpress.com/2013/07/16/floating-point-determinism/).
 
 ## Sandbox