Entity representation (#1393)

* Move assets out of Resources folder

* Add code changes for implementing Entity representation mapping

* Add Editor UI integration

* Fix tests

* Upgrade UI Builder package

* Add Entity representation mapping assets for clients and gamelogic

* Update upgrade guide

* Use XML and USS for EntityRepresentationMappingEditor

Author: zeroZshadow

.github/ClientPrefabMapping.PNG

@@ -6,6 +6,10 @@
 
 - All generated C# enums will now start from 0, being shifted to schema values on serialization and shifted back to C# values on deserialization. [#1412](https://github.com/spatialos/gdk-for-unity/pull/1412)
     - A warning will be generated when enums defined in schema do not start from 0.
+- GameObjectCreation feature module now links entity types with prefabs through EntityRepresentationMapping assets. [#1393](https://github.com/spatialos/gdk-for-unity/pull/1393)
+    - See the [upgrade guide](UPGRADE_GUIDE.md) for detailed upgrade instructions for this breaking change.
+    - `IEntityGameObjectCreator.PopulateEntityTypeExpectations` now only needs to specify what SpatialOS components it needs for spawning an entity, such as `Position`.
+    - `GameObjectCreationHelper.EnableStandardGameObjectCreation` now requires a non-null `EntityRepresentationMapping` to be passed in.
 
 ### Added
 
@@ -16,6 +20,7 @@
 - Added `Scripting Backend` option dropdown to the Build Configuration UI. [#1411](https://github.com/spatialos/gdk-for-unity/pull/1411)
 - Added `Allow Debug` toggle to the Build Configuration UI. [#1413](https://github.com/spatialos/gdk-for-unity/pull/1413)
     - Enabling the option allows .NET debuggers (Rider/Visual Studio) to use breakpoints while in the Unity Player.
+- Added `Authority` type field to `IComponentMetaclass`. [#1393](https://github.com/spatialos/gdk-for-unity/pull/1393)
 
 ### Changed
 

.github/ResourcesNew.PNG

@@ -2,6 +2,34 @@
 
 ## From `0.3.7` to `0.3.8`
 
+### Asset based entity representation
+
+The methods for mapping a Prefab to a type of entity have been changed since 0.3.8.
+
+To upgrade to the new method, please do the following steps for every worker type you have in your Unity project:
+
+1. Create an `Entity Representation Mapping` asset through the `Create > SpatialOS > Entity Representation Mapping` context menu.
+1. Name the asset accordingly, for example `ClientPrefabMapping` or `GamelogicPrefabMapping`.
+1. Select the asset in the Unity Inspector.
+1. For each entity type that needs to have a GameObject spawned for them.:
+    1. Select `New Entity Type`, and select the type of resolver you'd like to use:
+        * `SimpleEntityResolver` is a 1 to 1 mapping between entity type and prefab.
+        * `AuthoritativeEntityResolver` lets you map 2 prefabs, and picks the "Owned Prefab" based on your worker's authority over the given component ID.
+        * `OwningWorkerEntityResolver` lets you map 2 prefabs, and picks the "Owned Prefab" if the entity's `OwningWorker` component contains your worker's id. This uses the Player Lifecycle Feature Module.
+    1. Fill in the `Entity Type`, ensuring it matches the string used for the `Metadata` component.
+    1. Select the prefab(s) you'd like to use for this entity type.
+1. Update your `WorkerConnector` script to pass the `Entity Representation Mapping` asset along to `GameObjectCreationHelper.EnableStandardGameObjectCreation`.
+
+For example, the `ClientPrefabMapping` in our playground project looks like:
+
+![Prefab mapping for Client worker](.github/ClientPrefabMapping.PNG)
+
+With this change, you can now put prefabs for entities anywhere in your Unity project, instead of being restricted to the `Resources` folder.
+
+| Old project prefab layout                      | New project prefab layout                      |
+| :--------------------------------------------- | :--------------------------------------------- |
+| ![Old prefab folder](.github/ResourcesOld.PNG) | ![New prefab folder](.github/ResourcesNew.PNG) |
+
 ### Scripting Backend in Project Settings is now overwritten by the Build Configuration
 
 The Scripting Backend defined in the Unity Project Settings is now overwritten by the Build Configuration Asset. More information can be found on the [Build Configuration UI](https://documentation.improbable.io/gdk-for-unity/v0.3.8/docs/build-configuration#section-build-configuration-ui) wiki page.
@@ -439,14 +467,14 @@ The equality operators `==` and `!=` have also been implemented for the `EdgeLen
 New methods are exposed for conversion of `Coordinates`, `EdgeLength`, `FixedPointVector3` and `CompressedQuaternion` to and from native Unity `Vector3` and `Quaternion` types.
 
 | Static Method                                            | Result Type            | Module Dependency |
-|----------------------------------------------------------|------------------------|-------------------|
+| -------------------------------------------------------- | ---------------------- | ----------------- |
 | `Coordinates.FromUnityVector(Vector3 v)`                 | `Coordinates`          | -                 |
 | `EdgeLength.FromUnityVector(Vector3 v)`                  | `EdgeLength`           | -                 |
 | `FixedPointVector3.FromUnityVector(Vector3 v)`           | `FixedPointVector3`    | Transform Sync    |
 | `CompressedQuaternion.FromUnityQuaternion(Quaternion q)` | `CompressedQuaternion` | Transform Sync    |
 
 | Type                   | Method                      | Result Type            | Module Dependency |
-|------------------------|-----------------------------|------------------------|-------------------|
+| ---------------------- | --------------------------- | ---------------------- | ----------------- |
 | `Vector3`              | `.ToCoordinates()`          | `Coordinates`          | Transform Sync    |
 | `Vector3`              | `.ToFixedPointVector3()`    | `FixedPointVector3`    | Transform Sync    |
 | `Vector3`              | `.ToEdgeLength()`           | `EdgeLength`           | QBI Helper        |
@@ -629,13 +657,13 @@ In order to replicate the `DefaultWorkerConnector` behaviour exactly:
 
 Previously, there were a set of virtual methods on the `WorkerConnector` class that changed the behaviour of some of the connection flows. These methods now live in their respective connection flow objects (and are still virtual). You can inherit from the flow object and override the methods to achieve the same behaviour. See the table below for a mapping of where these methods currently exist.
 
-| Method | Class |
-| --- | --- |
-| `SelectDeploymentName(DeploymentList deployments)` | `LocatorFlow` |
-| `GetPlayerId()` | `AlphaLocatorFlow` |
-| `GetDisplayName()` | `AlphaLocatorFlow` |
-| `string SelectLoginToken(List<LoginTokenDetails> loginTokens)` | `AlphaLocatorFlow` |
-| `string GetDevelopmentPlayerIdentityToken(string authToken, string playerId, string displayName)` | `AlphaLocatorFlow` |
+| Method                                                                                             | Class              |
+| -------------------------------------------------------------------------------------------------- | ------------------ |
+| `SelectDeploymentName(DeploymentList deployments)`                                                 | `LocatorFlow`      |
+| `GetPlayerId()`                                                                                    | `AlphaLocatorFlow` |
+| `GetDisplayName()`                                                                                 | `AlphaLocatorFlow` |
+| `string SelectLoginToken(List<LoginTokenDetails> loginTokens)`                                     | `AlphaLocatorFlow` |
+| `string GetDevelopmentPlayerIdentityToken(string authToken, string playerId, string displayName)`  | `AlphaLocatorFlow` |
 | `List<LoginTokenDetails> GetDevelopmentLoginTokens(string workerType, string playerIdentityToken)` | `AlphaLocatorFlow` |
 
 #### Mobile setup

.github/ResourcesOld.PNG

@@ -0,0 +1,44 @@
+%YAML 1.1
+%TAG !u! tag:unity3d.com,2011:
+--- !u!114 &11400000
+MonoBehaviour:
+  m_ObjectHideFlags: 0
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInstance: {fileID: 0}
+  m_PrefabAsset: {fileID: 0}
+  m_GameObject: {fileID: 0}
+  m_Enabled: 1
+  m_EditorHideFlags: 0
+  m_Script: {fileID: 11500000, guid: f0598980a22146e5bb63df7b024cf2b0, type: 3}
+  m_Name: ClientPrefabMapping
+  m_EditorClassIdentifier: 
+  EntityRepresentationResolvers:
+  - id: 0
+  - id: 1
+  - id: 2
+  references:
+    version: 1
+    00000000:
+      type: {class: SimpleEntityResolver, ns: Improbable.Gdk.Core.Representation.Types,
+        asm: Improbable.Gdk.Core}
+      data:
+        entityType: Cube
+        prefab: {fileID: 1119241936791015974, guid: 3095f262424c6314a9a2487e12d1e1e2,
+          type: 3}
+        requiredComponents: 
+    00000001:
+      type: {class: SimpleEntityResolver, ns: Improbable.Gdk.Core.Representation.Types,
+        asm: Improbable.Gdk.Core}
+      data:
+        entityType: Character
+        prefab: {fileID: 1292271339760838, guid: 34f6f8ff026facf49bbc20f4663b8209,
+          type: 3}
+        requiredComponents: 
+    00000002:
+      type: {class: SimpleEntityResolver, ns: Improbable.Gdk.Core.Representation.Types,
+        asm: Improbable.Gdk.Core}
+      data:
+        entityType: Spinner
+        prefab: {fileID: 1198430049189278, guid: 913515e03e128a0489711fdead38a227,
+          type: 3}
+        requiredComponents: 

CHANGELOG.md

@@ -0,0 +1,44 @@
+%YAML 1.1
+%TAG !u! tag:unity3d.com,2011:
+--- !u!114 &11400000
+MonoBehaviour:
+  m_ObjectHideFlags: 0
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInstance: {fileID: 0}
+  m_PrefabAsset: {fileID: 0}
+  m_GameObject: {fileID: 0}
+  m_Enabled: 1
+  m_EditorHideFlags: 0
+  m_Script: {fileID: 11500000, guid: f0598980a22146e5bb63df7b024cf2b0, type: 3}
+  m_Name: GamelogicPrefabMapping
+  m_EditorClassIdentifier: 
+  EntityRepresentationResolvers:
+  - id: 0
+  - id: 1
+  - id: 2
+  references:
+    version: 1
+    00000000:
+      type: {class: SimpleEntityResolver, ns: Improbable.Gdk.Core.Representation.Types,
+        asm: Improbable.Gdk.Core}
+      data:
+        entityType: Cube
+        prefab: {fileID: 5737430427132324103, guid: b59182166209b9b4b80225bae2aadf2d,
+          type: 3}
+        requiredComponents: 
+    00000001:
+      type: {class: SimpleEntityResolver, ns: Improbable.Gdk.Core.Representation.Types,
+        asm: Improbable.Gdk.Core}
+      data:
+        entityType: Character
+        prefab: {fileID: 1292271339760838, guid: 34f6f8ff026facf49bbc20f4663b8209,
+          type: 3}
+        requiredComponents: 
+    00000002:
+      type: {class: SimpleEntityResolver, ns: Improbable.Gdk.Core.Representation.Types,
+        asm: Improbable.Gdk.Core}
+      data:
+        entityType: Spinner
+        prefab: {fileID: 1198430049189278, guid: 913515e03e128a0489711fdead38a227,
+          type: 3}
+        requiredComponents: 

UPGRADE_GUIDE.md

@@ -1,4 +1,5 @@
 using Improbable.Gdk.Core;
+using Improbable.Gdk.Core.Representation;
 using Improbable.Gdk.GameObjectCreation;
 using Improbable.Gdk.PlayerLifecycle;
 using Improbable.Gdk.TransformSynchronization;
@@ -12,12 +13,12 @@ public static class WorkerUtils
         public const string UnityGameLogic = "UnityGameLogic";
         public const string MobileClient = "MobileClient";
 
-        public static void AddClientSystems(World world)
+        public static void AddClientSystems(World world, EntityRepresentationMapping entityRepresentationMapping)
         {
             AddLifecycleSystems(world);
             TransformSynchronizationHelper.AddClientSystems(world);
             PlayerLifecycleHelper.AddClientSystems(world);
-            GameObjectCreationHelper.EnableStandardGameObjectCreation(world);
+            GameObjectCreationHelper.EnableStandardGameObjectCreation(world, entityRepresentationMapping);
             world.GetOrCreateSystem<ProcessColorChangeSystem>();
             world.GetOrCreateSystem<LocalPlayerInputSync>();
             world.GetOrCreateSystem<MoveLocalPlayerSystem>();
@@ -28,12 +29,12 @@ public static void AddClientSystems(World world)
             world.GetOrCreateSystem<MetricSendSystem>();
         }
 
-        public static void AddGameLogicSystems(World world)
+        public static void AddGameLogicSystems(World world, EntityRepresentationMapping entityRepresentationMapping)
         {
             AddLifecycleSystems(world);
             TransformSynchronizationHelper.AddServerSystems(world);
             PlayerLifecycleHelper.AddServerSystems(world);
-            GameObjectCreationHelper.EnableStandardGameObjectCreation(world);
+            GameObjectCreationHelper.EnableStandardGameObjectCreation(world, entityRepresentationMapping);
 
             world.GetOrCreateSystem<TriggerColorChangeSystem>();
             world.GetOrCreateSystem<ProcessLaunchCommandSystem>();

workers/unity/Assets/Playground/Config/ClientPrefabMapping.asset

@@ -0,0 +1,63 @@
+%YAML 1.1
+%TAG !u! tag:unity3d.com,2011:
+--- !u!1001 &1120208426435537710
+PrefabInstance:
+  m_ObjectHideFlags: 0
+  serializedVersion: 2
+  m_Modification:
+    m_TransformParent: {fileID: 0}
+    m_Modifications:
+    - target: {fileID: 1019506993461512, guid: a29ccfb5b715bd844a4a424e137bdfed, type: 3}
+      propertyPath: m_Name
+      value: CubeClient
+      objectReference: {fileID: 0}
+    - target: {fileID: 4711983361604210, guid: a29ccfb5b715bd844a4a424e137bdfed, type: 3}
+      propertyPath: m_RootOrder
+      value: 0
+      objectReference: {fileID: 0}
+    - target: {fileID: 4711983361604210, guid: a29ccfb5b715bd844a4a424e137bdfed, type: 3}
+      propertyPath: m_LocalEulerAnglesHint.x
+      value: 0
+      objectReference: {fileID: 0}
+    - target: {fileID: 4711983361604210, guid: a29ccfb5b715bd844a4a424e137bdfed, type: 3}
+      propertyPath: m_LocalEulerAnglesHint.y
+      value: 0
+      objectReference: {fileID: 0}
+    - target: {fileID: 4711983361604210, guid: a29ccfb5b715bd844a4a424e137bdfed, type: 3}
+      propertyPath: m_LocalEulerAnglesHint.z
+      value: 0
+      objectReference: {fileID: 0}
+    - target: {fileID: 23914295514298150, guid: a29ccfb5b715bd844a4a424e137bdfed,
+        type: 3}
+      propertyPath: m_Materials.Array.data[0]
+      value: 
+      objectReference: {fileID: 2100000, guid: 3609e6235e10ee04c89865c54f3b1fce, type: 2}
+    - target: {fileID: 54117405590287678, guid: a29ccfb5b715bd844a4a424e137bdfed,
+        type: 3}
+      propertyPath: m_IsKinematic
+      value: 1
+      objectReference: {fileID: 0}
+    - target: {fileID: 54117405590287678, guid: a29ccfb5b715bd844a4a424e137bdfed,
+        type: 3}
+      propertyPath: m_UseGravity
+      value: 0
+      objectReference: {fileID: 0}
+    - target: {fileID: 114079472425749956, guid: a29ccfb5b715bd844a4a424e137bdfed,
+        type: 3}
+      propertyPath: ReceiveStrategies.Array.size
+      value: 2
+      objectReference: {fileID: 0}
+    - target: {fileID: 114079472425749956, guid: a29ccfb5b715bd844a4a424e137bdfed,
+        type: 3}
+      propertyPath: ReceiveStrategies.Array.data[0]
+      value: 
+      objectReference: {fileID: 11400000, guid: 7e00873dd53438245919187ebd00e937,
+        type: 2}
+    - target: {fileID: 114079472425749956, guid: a29ccfb5b715bd844a4a424e137bdfed,
+        type: 3}
+      propertyPath: ReceiveStrategies.Array.data[1]
+      value: 
+      objectReference: {fileID: 11400000, guid: d3eeea3be1ea96949b63c46a6353d4d1,
+        type: 2}
+    m_RemovedComponents: []
+  m_SourcePrefab: {fileID: 100100000, guid: a29ccfb5b715bd844a4a424e137bdfed, type: 3}