com.artromskiy.deltaecs.unity 0.0.47 → 0.0.52

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.0.52
+
+- Published with the matching DeltaECS NuGet packages.
+
+## 0.0.51
+
+- Published with the matching DeltaECS NuGet packages.
+
 ## 0.0.47
 
 - Published with the matching DeltaECS NuGet packages.

package/README.md

@@ -18,7 +18,7 @@ Add the npm-compatible registry and package to the Unity project's
     }
   ],
   "dependencies": {
-    "com.artromskiy.deltaecs.unity": "0.0.47"
+    "com.artromskiy.deltaecs.unity": "0.0.52"
   }
 }
 ```
@@ -75,5 +75,29 @@ public struct Position
 }
 ```
 
+## Initialize views when they are bound
+
+Implement `IEntityView` on a `MonoBehaviour` when a view needs to receive its
+entity after binding. `OnBind` receives an `EntityContext` containing the
+owning world and entity:
+
+```csharp
+using Delta.ECS.Unity;
+using UnityEngine;
+
+public sealed class UnitView : MonoBehaviour, IEntityView
+{
+    private EntityContext _context;
+
+    public void OnBind(EntityContext context) => _context = context;
+}
+```
+
+The binder calls `OnBind` for implementations on the view and its child
+GameObjects, including inactive children. It runs after the view is associated
+with the entity and after the ECS query has finished, so the callback can use
+the regular `World` API. A stored context can later be checked with
+`context.IsAlive` before using its entity.
+
 See the [DeltaECS documentation](https://github.com/Artromskiy/DeltaECS/wiki)
 for the runtime and generator APIs.

package/Runtime/EntityContext.cs

@@ -0,0 +1,121 @@
+#nullable enable
+
+using System;
+using Delta.ECS;
+
+namespace Delta.ECS.Unity
+{
+    /// <summary>A stable entity handle paired with the world that owns it.</summary>
+    public readonly struct EntityContext
+    {
+        /// <summary>Gets the entity handle.</summary>
+        public Entity Entity { get; }
+
+        /// <summary>Gets the owning world, or <see langword="null"/> when this is the default context.</summary>
+        public World? World { get; }
+
+        /// <summary>Gets whether this context refers to a live entity.</summary>
+        public bool IsAlive => World != null && World.IsAlive(Entity);
+
+        /// <summary>Reports whether the entity owns the specified component registration.</summary>
+        public bool Has(ComponentId componentId) => World?.Has(Entity, componentId) ?? false;
+
+        /// <summary>Reports whether the entity owns the primary registration for <typeparamref name="T"/>.</summary>
+        public bool Has<T>() => World?.Has<T>(Entity) ?? false;
+
+        /// <summary>Reports whether the entity owns the specified registration of <typeparamref name="T"/>.</summary>
+        public bool Has<T>(ComponentId componentId) => World?.Has<T>(Entity, componentId) ?? false;
+
+        /// <summary>Attempts to read the primary component for <typeparamref name="T"/>.</summary>
+        public bool TryGet<T>(out T value)
+        {
+            World? world = World;
+            if (world is null)
+            {
+                value = default!;
+                return false;
+            }
+
+            return world.TryGet(Entity, out value);
+        }
+
+        /// <summary>Attempts to read the specified registration of <typeparamref name="T"/>.</summary>
+        public bool TryGet<T>(ComponentId componentId, out T value)
+        {
+            World? world = World;
+            if (world is null)
+            {
+                value = default!;
+                return false;
+            }
+
+            return world.TryGet(Entity, componentId, out value);
+        }
+
+        /// <summary>Reads the primary component for <typeparamref name="T"/> or throws when it is missing.</summary>
+        public T Get<T>() => GetWorld().Get<T>(Entity);
+
+        /// <summary>Reads the specified component registration as <typeparamref name="T"/> or throws when it is missing.</summary>
+        public T Get<T>(ComponentId componentId) => GetWorld().Get<T>(Entity, componentId);
+
+        /// <summary>Gets a writable reference to the primary component for <typeparamref name="T"/>.</summary>
+        public ref T GetRef<T>() => ref GetWorld().GetRef<T>(Entity);
+
+        /// <summary>Gets a writable reference to the specified registration of <typeparamref name="T"/>.</summary>
+        public ref T GetRef<T>(ComponentId componentId) => ref GetWorld().GetRef<T>(Entity, componentId);
+
+        /// <summary>Gets a read-only reference to the primary component for <typeparamref name="T"/>.</summary>
+        public ref readonly T GetReadRef<T>() => ref GetWorld().GetReadRef<T>(Entity);
+
+        /// <summary>Gets a read-only reference to the specified registration of <typeparamref name="T"/>.</summary>
+        public ref readonly T GetReadRef<T>(ComponentId componentId) => ref GetWorld().GetReadRef<T>(Entity, componentId);
+
+        /// <summary>Attempts to read the stamp for the primary component of <typeparamref name="T"/>.</summary>
+        public bool TryGetComponentStamp<T>(out Stamp stamp)
+        {
+            World? world = World;
+            if (world is null)
+            {
+                stamp = default;
+                return false;
+            }
+
+            return world.TryGetComponentStamp<T>(Entity, out stamp);
+        }
+
+        /// <summary>Attempts to read the stamp for the specified component registration.</summary>
+        public bool TryGetComponentStamp(ComponentId componentId, out Stamp stamp)
+        {
+            World? world = World;
+            if (world is null)
+            {
+                stamp = default;
+                return false;
+            }
+
+            return world.TryGetComponentStamp(Entity, componentId, out stamp);
+        }
+
+        /// <summary>Attempts to read the stamp for the specified registration of <typeparamref name="T"/>.</summary>
+        public bool TryGetComponentStamp<T>(ComponentId componentId, out Stamp stamp)
+        {
+            World? world = World;
+            if (world is null)
+            {
+                stamp = default;
+                return false;
+            }
+
+            return world.TryGetComponentStamp<T>(Entity, componentId, out stamp);
+        }
+
+        internal EntityContext(World world, Entity entity)
+        {
+            World = world;
+            Entity = entity;
+        }
+
+        private World GetWorld()
+            => World ?? UnityThrowHelpers.ThrowMissingEntityContextWorld();
+    }
+}

package/Runtime/EntityContext.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 7d9c2a99dcf04bc7a88de3c1468ef821

package/Runtime/SceneWorld.cs

@@ -32,6 +32,7 @@ namespace Delta.ECS.Unity
         public World World => _world;
         internal IEcsWorld Integration => _integration;
         internal SceneData SceneData => _sceneData;
+        internal Scene UnityScene => _authoring != null ? _authoring.gameObject.scene : default;
         internal bool IsBound => !_disposed;
 
         /// <summary>Returns the integration-owned runtime context for a loaded Unity scene.</summary>

package/Runtime/SceneWorldExtensions.cs

@@ -9,6 +9,23 @@ namespace Delta.ECS.Unity
 {
     public static class SceneWorldExtensions
     {
+        /// <summary>Returns the live ECS context bound to this GameObject, or the default context when unbound.</summary>
+        public static EntityContext GetEntity(this GameObject? view)
+            => TryGetEntity(view, out EntityContext context) ? context : default;
+
+        /// <summary>Returns whether this GameObject is bound to a live ECS entity.</summary>
+        public static bool TryGetEntity(this GameObject? view, out EntityContext context)
+        {
+            if (view != null && SceneWorld.TryGetBoundEntity(view, out World world, out Entity entity))
+            {
+                context = new EntityContext(world, entity);
+                return true;
+            }
+
+            context = default;
+            return false;
+        }
+
         /// <summary>Returns the entity bound to this GameObject, or the default entity when no binding exists.</summary>
         /// <param name="world">The bound live ECS world, or <see langword="null"/> when no binding exists.</param>
         public static Entity GetEntity(this GameObject? view, out World? world)
@@ -40,6 +57,22 @@ namespace Delta.ECS.Unity
             return TryGetEntity(behaviour, out Entity entity, out world) ? entity : default;
         }
 
+        /// <summary>Returns the live ECS context bound to this MonoBehaviour, or the default context when unbound.</summary>
+        public static EntityContext GetEntity(this MonoBehaviour? behaviour)
+            => TryGetEntity(behaviour, out EntityContext context) ? context : default;
+
+        /// <summary>Returns whether this MonoBehaviour is bound to a live ECS entity.</summary>
+        public static bool TryGetEntity(this MonoBehaviour? behaviour, out EntityContext context)
+        {
+            if (behaviour != null)
+            {
+                return behaviour.gameObject.TryGetEntity(out context);
+            }
+
+            context = default;
+            return false;
+        }
+
         /// <summary>Returns whether this MonoBehaviour is bound to a live ECS entity.</summary>
         public static bool TryGetEntity(
             this MonoBehaviour? behaviour,

package/Runtime/ThrowHelpers.cs

@@ -1,6 +1,10 @@
+#nullable enable
+
 using System;
 using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
 using System.Runtime.ExceptionServices;
+using Delta.ECS;
 
 namespace Delta.ECS.Unity
 {
@@ -40,5 +44,10 @@ namespace Delta.ECS.Unity
             ExceptionDispatchInfo.Capture(exception).Throw();
             return default;
         }
+
+        [DoesNotReturn]
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        internal static World ThrowMissingEntityContextWorld()
+            => throw new InvalidOperationException("The default entity context does not reference a world.");
     }
 }

package/Runtime/ViewBindingSystem.cs

@@ -0,0 +1,119 @@
+#nullable enable
+
+using System.Collections.Generic;
+using Delta.ECS;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace Delta.ECS.Unity
+{
+    /// <summary>Creates and binds prefab views for entities carrying an unbound <see cref="ViewToken"/>.</summary>
+    public sealed class ViewBindingSystem
+    {
+        private readonly SceneWorld _sceneWorld;
+        private readonly World _world;
+        private readonly ViewPrefabCatalog _catalog;
+        private readonly ComponentId _viewBoundId;
+        private readonly EcsOperation<ForEachEntityOperationInvoker> _bindOperation;
+        private readonly List<Entity> _entitiesToBind = new();
+        private readonly List<MonoBehaviour> _viewBehaviours = new();
+
+        /// <summary>Creates a view binder for one scene world and prefab catalog.</summary>
+        public ViewBindingSystem(SceneWorld sceneWorld, ViewPrefabCatalog catalog)
+        {
+            _sceneWorld = sceneWorld ?? UnityThrowHelpers.ThrowArgumentNull<SceneWorld>(nameof(sceneWorld));
+            _catalog = catalog ?? UnityThrowHelpers.ThrowArgumentNull<ViewPrefabCatalog>(nameof(catalog));
+            _world = _sceneWorld.World;
+
+            ComponentId viewTokenId = _world.Layouts.GetPrimary<ViewToken>();
+            _viewBoundId = _world.Layouts.GetPrimary<ViewBound>();
+            Query query = _world.WhereAll(stackalloc ComponentId[1] { viewTokenId })
+                .WhereNone(stackalloc ComponentId[1] { _viewBoundId });
+            _bindOperation = _world.ForEachEntity(in query, QueueViewBinding);
+        }
+
+        /// <summary>Binds views for currently unbound entities with a matching token.</summary>
+        public void BindPendingViews()
+        {
+            _entitiesToBind.Clear();
+            _bindOperation.Invoke();
+
+            for (int i = 0; i < _entitiesToBind.Count; i++)
+            {
+                BindView(_entitiesToBind[i]);
+            }
+
+            _entitiesToBind.Clear();
+        }
+
+        private void QueueViewBinding(EntityRef entityRef) => _entitiesToBind.Add(entityRef);
+
+        private void BindView(Entity entity)
+        {
+            if (!_world.IsAlive(entity) || _world.Has(entity, _viewBoundId))
+            {
+                return;
+            }
+
+            if (_sceneWorld.TryGetView(entity, out GameObject existingView))
+            {
+                _world.Add(entity, _viewBoundId);
+                NotifyViewBound(existingView, entity);
+                return;
+            }
+
+            ViewToken token = _world.Get<ViewToken>(entity);
+            if (!_catalog.TryGetPrefab(token.Id, out GameObject? prefab))
+            {
+                return;
+            }
+
+            Object instance = Object.Instantiate((Object)prefab);
+            GameObject? view = instance as GameObject;
+            if (view == null)
+            {
+                string instanceType = instance == null ? "null" : instance.GetType().ToString();
+                Debug.LogError(
+                    $"View prefab '{token.Id}' ({prefab.GetType()}) instantiated as '{instanceType}'.",
+                    prefab);
+                if (instance != null)
+                {
+                    Object.Destroy(instance);
+                }
+
+                return;
+            }
+
+            Scene scene = _sceneWorld.UnityScene;
+            if (scene.IsValid() && scene.isLoaded && view.scene != scene)
+            {
+                SceneManager.MoveGameObjectToScene(view, scene);
+            }
+
+            if (!_sceneWorld.BindView(entity, view))
+            {
+                Object.Destroy(view);
+                return;
+            }
+
+            _world.Add(entity, _viewBoundId);
+            NotifyViewBound(view, entity);
+        }
+
+        private void NotifyViewBound(GameObject view, Entity entity)
+        {
+            _viewBehaviours.Clear();
+            view.GetComponentsInChildren(true, _viewBehaviours);
+            EntityContext context = new EntityContext(_world, entity);
+            for (int i = 0; i < _viewBehaviours.Count; i++)
+            {
+                if (_viewBehaviours[i] != null && _viewBehaviours[i] is IEntityView entityView)
+                {
+                    entityView.OnBind(context);
+                }
+            }
+
+            _viewBehaviours.Clear();
+        }
+    }
+}

package/Runtime/ViewBindingSystem.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: a31d3098209444b0b8635a1874556c21

package/Runtime/ViewComponents.cs

@@ -0,0 +1,28 @@
+using Delta.ECS;
+
+namespace Delta.ECS.Unity
+{
+    /// <summary>Receives the entity context after a Unity view is bound to an entity.</summary>
+    public interface IEntityView
+    {
+        /// <summary>Initializes this view for its bound entity.</summary>
+        void OnBind(EntityContext context);
+    }
+
+    /// <summary>Selects the Unity prefab used to represent an entity.</summary>
+    [DeltaEcsComponent(SchemaId = 0x405B11F5A17E14A1UL)]
+    public readonly struct ViewToken
+    {
+        /// <summary>Gets the identifier of the view prefab in a <see cref="ViewPrefabCatalog"/>.</summary>
+        public string Id { get; }
+
+        /// <summary>Creates a token that selects a view prefab by identifier.</summary>
+        public ViewToken(string id) => Id = id;
+    }
+
+    /// <summary>Marks an entity whose Unity view has already been bound.</summary>
+    [DeltaEcsComponent(SchemaId = 0xB31CB42A81D3B164UL)]
+    public struct ViewBound
+    {
+    }
+}

package/Runtime/ViewComponents.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 18a1b2ddb0f34526b96a93e733879150

package/Runtime/ViewPrefabCatalog.cs

@@ -0,0 +1,68 @@
+#nullable enable
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using UnityEngine;
+
+namespace Delta.ECS.Unity
+{
+    /// <summary>Maps <see cref="ViewToken.Id"/> values to Unity view prefabs.</summary>
+    [CreateAssetMenu(fileName = "ViewPrefabCatalog", menuName = "Delta ECS/View Prefab Catalog")]
+    public sealed class ViewPrefabCatalog : ScriptableObject
+    {
+        [SerializeField] private List<ViewPrefabEntry> _entries = new();
+        [NonSerialized] private Dictionary<string, GameObject>? _prefabsById;
+
+        /// <summary>Resolves a token identifier to its configured prefab.</summary>
+        public bool TryGetPrefab(string id, [NotNullWhen(true)] out GameObject? prefab)
+        {
+            EnsureIndex();
+            if (!string.IsNullOrEmpty(id)
+                && _prefabsById!.TryGetValue(id, out prefab)
+                && prefab != null)
+            {
+                return true;
+            }
+
+            prefab = null;
+            return false;
+        }
+
+        private void OnValidate() => _prefabsById = null;
+
+        private void EnsureIndex()
+        {
+            if (_prefabsById != null)
+            {
+                return;
+            }
+
+            _prefabsById = new Dictionary<string, GameObject>(StringComparer.Ordinal);
+            _entries ??= new List<ViewPrefabEntry>();
+            for (int i = 0; i < _entries.Count; i++)
+            {
+                ViewPrefabEntry entry = _entries[i];
+                if (entry == null || string.IsNullOrEmpty(entry.Id) || entry.Prefab == null)
+                {
+                    continue;
+                }
+
+                if (!_prefabsById.TryAdd(entry.Id, entry.Prefab))
+                {
+                    Debug.LogError($"Duplicate view prefab identifier '{entry.Id}' in '{name}'.", this);
+                }
+            }
+        }
+
+        [Serializable]
+        private sealed class ViewPrefabEntry
+        {
+            [SerializeField] private string _id = string.Empty;
+            [SerializeField] private GameObject? _prefab;
+
+            internal string Id => _id;
+            internal GameObject? Prefab => _prefab;
+        }
+    }
+}

package/Runtime/ViewPrefabCatalog.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 91f157d4af3b4bd6b4d5beb36a1337a6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.artromskiy.deltaecs.unity",
-  "version": "0.0.47",
+  "version": "0.0.52",
   "displayName": "DeltaECS Unity",
   "description": "Unity scene authoring and editor integration for DeltaECS.",
   "unity": "6000.7",