Merge branch 'new-observable-approach'

Author: grofit

docs/architecture/high-level-architecture.md

@@ -0,0 +1,47 @@
+# High Level Architecture
+
+From a high level perspective EcsRx is built on top of SystemsRx, we make use of SystemRx's `ISystemsExecutor` and `ISystem` notions while adding our own custom handlers and ECS paradigms on top.
+
+If we were to look at the highest level of what the MAIN architectural components were it would look something like this:
+
+![](../diagrams/high-level-architecture.png)
+
+## Systems Executor
+
+As you can see we have the `Systems Executor` section which is where all systems end up within the framework, they are all setup internally by registered `System Handlers` which understand how to process certain kinds of system and wire up dependencies.
+
+> In the real world most of the handlers are `IConventionalSystemHandler` implementations and you can make your own versions of these if you want
+
+### Observable Groups
+
+As systems use groups as their contracts we have `Observable Group` objects which deal with maintaining a list of applicable entities and notify any subscribers when they change in any way.
+
+> There is a plugin which extends this further with the notion of `IComputedGroup` which wraps an observable group and filters/constrains it further.
+
+### Observable Group Trackers
+
+The last part of the `System Executor` section is the `Observable Group Trackers` which watch entity collections and notify when entities add/leave a group, this makes the `Observable Group` the storage of what entities are actually in the group, and the trackers just notify it when to change.
+
+> There are various flavours of `ObservableGroupTracker` implementations, we use the Collection based one here but there are ones for individual entity tracking against groups or batched ones too.
+
+## Entity Database
+
+So the entity database contains all entity collections and acts as a sort of proxy to let you query into all collections if you need to, however in most cases you would deal with individual collections directly.
+
+### Entity Collection
+
+These objects just store entities and notify any listeners when entities are added/removed or components change, you can find out more [Here](entity-collections.md).
+
+### Entities
+
+Entities are the main thing developers interact with as they are the data containers that get bounced around the system, to find out more look in the [Entity Docs](../framework/entities.md).
+
+## Component Database
+
+The component database stores all the actual component data in large arrays, this allows us to more quickly access component data.
+
+> Historically components were stored on entities but it causes the memory to become extremely fragmented so this gives a large performance benefit without anyone really needing to know whats going on.
+
+### Component Pools
+
+These are the large arrays (simply speaking) that contain all the actual component data.

docs/diagrams/diagrams.eddx

@@ -15,6 +15,10 @@ IComputedGroup        		<-  This acts as another layer of filtration on an IObse
                           		i.e Top 5 entities with PlayerComponent sorted by Score
 ```
 
+Here is a diagram which shows at a high level how they all hook together.
+
+![](../diagrams/event-propagation.png)
+
 ## IObservableGroupManager
 
 The observable group manager maintains a collection of `IObservableGroup` so if you have 5 systems which all use the same group, there will only actually be 1 instance of the `IObservableGroup` that is shared between them all. 
@@ -23,10 +27,14 @@ The observable group manager maintains a collection of `IObservableGroup` so if
 
 The observable group is created within and maintained by an `IEntityCollectionManager` and exposes all entities which match the associated group. It also exposes observables to represent when an entity has been added or removed from the underlying group.
 
-Under the hood, the observable group watches entities to see when they are added/removed from pools as well as when their components change. When this occurs it will check to see if it effects the current group and if so it updates it internal list accordingly.
+Under the hood, the observable group watches entities (via `IObservableGroupTrackers`) to see when they are added/removed from pools as well as when their components change. When this occurs it will check to see if it effects the current group and if so it updates it internal list accordingly.
 
 This has a huge performance benefit as it will stop you needing to evaluate linq chains into the underlying pools and just give you a cached list of all entities currently matching, given also that these observable groups are shared between any systems that require the same underlying components it can save a lot of resources.
 
+## IObservableGroupTracker
+
+This acts as the notifying mechanism for Observable groups to know when changes happen to the underlying entity data.
+
 ## IComputedGroup
 
 The computed group is created manually and requires an `IObservableGroup` for it to use for the basis of its queries. It is provided to allow you to filter past the group level and get more specific data sets without having to hard code the logic for the lookup in various systems.
@@ -45,7 +53,7 @@ This implementation has caching built in so it will try to keep a pre-evaluted l
 
 > This now needs the `EcsRx.Plugins.Computeds` nuget package, as the computed functionality has been moved there.
 
-## Querys
+## Query Object
 
 So up to this point we have discussed the general filtration process, however there are some extension methods which let you do more ad-hoc queries on data, these are not cached in any way but allow you to drill down into a subset of data in a pre-defined way, this overlaps a bit with the `IComputedGroup` but lets you query directly at the pool level or accessor level.
 

docs/diagrams/event-propagation.png

@@ -0,0 +1,68 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using BenchmarkDotNet.Attributes;
+using EcsRx.Components;
+using EcsRx.Entities;
+using EcsRx.Examples.ExampleApps.Performance.Components.Specific;
+using EcsRx.Examples.ExampleApps.Performance.Helper;
+using EcsRx.Extensions;
+using SystemsRx.Extensions;
+
+namespace EcsRx.Benchmarks.Benchmarks
+{
+    [BenchmarkCategory("Entities")]
+    public class EntityAddComponentsBenchmark : EcsRxBenchmark
+    {
+        private Type[] _availableComponentTypes;
+        private List<IEntity> _entities = new List<IEntity>();
+        private IComponent[] _components;
+        private readonly RandomGroupFactory _groupFactory = new RandomGroupFactory();
+
+        [Params(1000)]
+        public int EntityCount;
+
+        [Params(1, 25, 50)]
+        public int ComponentCount;
+
+        public EntityAddComponentsBenchmark()
+        {
+            var componentNamespace = typeof(Component1).Namespace;
+            _availableComponentTypes = _groupFactory.GetComponentTypes
+                .Where(x => x.Namespace == componentNamespace)
+                .ToArray();
+        }
+
+        public override void Setup()
+        {
+            for (var i = 0; i < EntityCount; i++)
+            {
+                var entity = new Entity(i, ComponentDatabase, ComponentTypeLookup);
+                _entities.Add(entity);
+            }
+
+            _components = _availableComponentTypes
+                .Take(ComponentCount)
+                .Select(x => Activator.CreateInstance(x) as IComponent)
+                .ToArray();
+        }
+
+        public override void Cleanup()
+        {
+            _entities.ForEach(x => x.RemoveAllComponents());
+            _entities.Clear();
+        }
+
+        [Benchmark]
+        public void EntitiesBatchAddComponents()
+        {
+            _entities.ForEach(x => x.AddComponents(_components));
+        }
+        
+        [Benchmark]
+        public void EntitiesAddIndividualComponents()
+        {
+            _entities.ForEach(x => _components.ForEachRun(y => x.AddComponents(y)));
+        }
+    }
+}

docs/diagrams/high-level-architecture.png

@@ -0,0 +1,69 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using BenchmarkDotNet.Attributes;
+using EcsRx.Components;
+using EcsRx.Entities;
+using EcsRx.Examples.ExampleApps.Performance.Components.Specific;
+using EcsRx.Examples.ExampleApps.Performance.Helper;
+using EcsRx.Extensions;
+using EcsRx.Groups;
+
+namespace EcsRx.Benchmarks.Benchmarks
+{
+    [BenchmarkCategory("Groups", "Entities")]
+    public class EntityGroupMatchingBenchmark : EcsRxBenchmark
+    {
+        private LookupGroup _lookupGroup;
+        private List<IEntity> _entities = new List<IEntity>();
+        private Type[] _availableComponentTypes;
+
+        private IComponent[] _components;
+
+        private readonly RandomGroupFactory _groupFactory = new RandomGroupFactory();
+        
+        [Params(1000, 10000)]
+        public int EntityCount;
+        
+        [Params(1, 25, 50)]
+        public int ComponentCount;
+
+
+        public EntityGroupMatchingBenchmark() : base()
+        {
+            var componentNamespace = typeof(Component1).Namespace;
+            _availableComponentTypes = _groupFactory.GetComponentTypes
+                .Where(x => x.Namespace == componentNamespace)
+                .ToArray();
+            
+            _lookupGroup = new LookupGroup(_availableComponentTypes
+                .Select(ComponentTypeLookup.GetComponentTypeId)
+                .ToArray(), Array.Empty<int>());
+        }
+        
+        public override void Setup()
+        {
+            _components = _availableComponentTypes
+                .Take(ComponentCount)
+                .Select(x => Activator.CreateInstance(x) as IComponent)
+                .ToArray();
+            
+            for (var i = 0; i < EntityCount; i++)
+            {
+                var entity = new Entity(i, ComponentDatabase, ComponentTypeLookup);
+                entity.AddComponents(_components);
+                _entities.Add(entity);
+            }
+        }
+
+        public override void Cleanup()
+        {
+            _entities.ForEach(x => x.RemoveAllComponents());
+            _entities.Clear();
+        }
+
+        [Benchmark]
+        public void EntitiesMatchGroup()
+        { _entities.ForEach(x => _lookupGroup.Matches(x)); }
+    }
+}

docs/framework/observable-groups.md

@@ -0,0 +1,101 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using BenchmarkDotNet.Attributes;
+using EcsRx.Components;
+using EcsRx.Entities;
+using EcsRx.Examples.ExampleApps.Performance.Components.Specific;
+using EcsRx.Examples.ExampleApps.Performance.Helper;
+using EcsRx.Extensions;
+
+namespace EcsRx.Benchmarks.Benchmarks
+{
+    [BenchmarkCategory("Entities")]
+    public class EntityRetrievalBenchmark : EcsRxBenchmark
+    {
+        private IComponent[] _availableComponents;
+        private Type[] _availableComponentTypes;
+        private List<IEntity> _entities = new List<IEntity>();
+        private readonly RandomGroupFactory _groupFactory = new RandomGroupFactory();
+        
+        [Params(1000, 10000, 100000)]
+        public int EntityCount;
+
+        public EntityRetrievalBenchmark() : base()
+        {
+            var componentNamespace = typeof(Component1).Namespace;
+            _availableComponentTypes = _groupFactory.GetComponentTypes
+                .Where(x => x.Namespace == componentNamespace)
+                .ToArray();
+            
+            _availableComponents = _availableComponentTypes
+                .Select(x => Activator.CreateInstance(x) as IComponent)
+                .ToArray();
+        }
+
+        public void ProcessEntity(IEntity entity)
+        {
+            entity.GetComponent<Component1>();
+            entity.GetComponent<Component2>();
+            entity.GetComponent<Component3>();
+            entity.GetComponent<Component4>();
+            entity.GetComponent<Component5>();
+            entity.GetComponent<Component6>();
+            entity.GetComponent<Component7>();
+            entity.GetComponent<Component8>();
+            entity.GetComponent<Component9>();
+            entity.GetComponent<Component10>();
+            entity.GetComponent<Component11>();
+            entity.GetComponent<Component12>();
+            entity.GetComponent<Component13>();
+            entity.GetComponent<Component14>();
+            entity.GetComponent<Component15>();
+            entity.GetComponent<Component16>();
+            entity.GetComponent<Component17>();
+            entity.GetComponent<Component18>();
+            entity.GetComponent<Component19>();
+            entity.GetComponent<Component20>();
+        }
+
+        public override void Setup()
+        {
+            for (var i = 0; i < EntityCount; i++)
+            {
+                var entity = new Entity(i, ComponentDatabase, ComponentTypeLookup);
+                entity.AddComponents(_availableComponents);
+                _entities.Add(entity);
+            }
+        }
+
+        public override void Cleanup()
+        {
+            _entities.ForEach(x => x.RemoveAllComponents());
+            _entities.Clear();
+        }
+
+        [Benchmark]
+        public void EntitiesGetComponents()
+        {
+            for (var i = 0; i < EntityCount; i++)
+            { ProcessEntity(_entities[i]); }
+        }
+        
+        [Benchmark]
+        public bool EntitiesHasAllComponents()
+        {
+            var ignore = false;
+            for (var i = 0; i < EntityCount; i++)
+            { ignore = _entities[i].HasAllComponents(_availableComponentTypes); }
+            return ignore;
+        }
+        
+        [Benchmark]
+        public bool EntitiesHasAnyComponents()
+        {
+            var ignore = false;
+            for (var i = 0; i < EntityCount; i++)
+            { ignore = _entities[i].HasAnyComponents(_availableComponentTypes); }
+            return ignore;
+        }
+    }
+}