Initial PR

en/manual/engine/entity-component-model/introduction.md

@@ -0,0 +1,47 @@
+# ECS (Entity Component System) Introduction
+
+# Problem
+> `Dog` is a subclasses of `Animal`.
+
+This example is often used as an example of inheritance
+in introductions to programming. However, when things get more complex,
+we get problems:
+- `Dog` and `Fish` can swim, so we create `SwimmingAnimal` as a class in between
+- `Bee` and `Bird` can fly, so we create `FlyingAnimal`
+- What do we now do with the `Duck`, who can do both?
+
+We have the exact same problem in video games.  
+Enemies can walk, shoot, fly - but not all of them can do everything.  
+Even something basic like hitpoints is not universal, as some enemies are indestructible.
+
+# Solution
+
+
+> Entity component system (ECS) is a software architectural pattern mostly used in video game development for the representation of game world objects. An ECS comprises entities composed from components of data, with systems which operate on entities' components.  
+> _-[Wikipedia](https://en.wikipedia.org/wiki/Entity_component_system)_
+
+
+The general idea of an ECS is that an _entity_ - an "object" in your virtual world -
+does not really do anything. It is mostly just a "bag of components".
+
+The selection of components on an entity decides what it does.
+An entity with a collider component can collider, an entity with a sound component can make a noise, etc.
+
+## Differing opinions
+
+For the "System" part of the term, there are two interpretations:
+
+A) "Entity-and-Component System"  
+...in which the components contain the data they need, and also the functionality that works with that data.
+
+B) "Entity, Component, System"  
+...in which a component only contains data, while a third part - the system -
+contains the functionality.
+
+Stride allows working in both ways. A) can be achieved by using
+[scripts](https://doc.stride3d.net/latest/en/manual/scripts/index.html)
+while the usage of B) is described in this section of the manual.
+
+### Which one to choose?
+
+![media/ecs-choice.jpg](media/ecs-choice.jpg) 

en/manual/engine/entity-component-model/media/ecs-choice.jpg

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a54e019040ee38ba3e8bd22db06bf72d66da05e44ad5e41ca73a2671ec22ab1c
+size 37751

en/manual/engine/entity-component-model/usage.md

@@ -0,0 +1,91 @@
+# ECS Usage
+
+## Classes
+
+The three parts of "Entity Component System" map to the following classes:
+
+- Entity - [`Stride.Engine.Entity`](https://doc.stride3d.net/latest/en/api/Stride.Engine.Entity.html)
+- Component - [`Stride.Engine.EntityComponent`](https://doc.stride3d.net/latest/en/api/Stride.Engine.EntityComponent.html)
+- System - [`Stride.Engine.EntityProcessor`](https://doc.stride3d.net/latest/en/api/Stride.Engine.EntityProcessor.html)
+
+
+## Minimal Setup
+
+A component can be defined by deriving a class from `EntityComponent`.
+
+By adding the attribute `DefaultEntityComponentProcessor` to an `EntityComponent`,  
+an `EntityProcessor` can be assigned to it. This will automatically set up and run  
+the `EntityProcessor` if the `EntityComponent` is in the scene.
+
+An `EntityComponent` also needs to indicate that it can be serialized  
+by adding the attribute `DataContract` to it.
+
+A system can be defined by deriving a class from `EntityProcessor`. 
+
+
+### Code
+
+#### Component
+```csharp
+[DataContract(nameof(MyComponent))]
+[DefaultEntityComponentProcessor(typeof(MyProcessor))]
+public class MyComponent : EntityComponent
+{
+    public int MyValue { get; set; }
+}
+```
+
+#### System
+```csharp
+public class MyProcessor : EntityProcessor<MyComponent>
+{
+    public override void Update(GameTime time)
+    {
+        foreach (var myComponent in ComponentDatas.Values)
+        {
+            Console.WriteLine($"myComponent with value {myComponent.MyValue} at {time.Total.TotalSeconds}");
+        }
+    }
+}
+```
+
+### Additional Note
+An `EntityComponent` can currently not be drag-dropped onto an entity in Game Studio.  
+t has to be added by selecting an entity, and then clicking the "Add component" button  
+in the property grid.
+
+Alternatively, this can also be done in [code via `entity.Add(entityComponent)`](https://doc.stride3d.net/latest/en/api/Stride.Engine.Entity.html#Stride_Engine_Entity_Add_Stride_Engine_EntityComponent_).
+
+
+## Advanced Features
+
+### More Component Attributes
+
+#### Display
+By adding the `Display` attribute, a nicer name can be shown in Game Studio.
+```csharp
+[Display("My better name")]
+```
+
+#### ComponentCategory
+By default, your components will be listed in the category "Miscellaneous".  
+By adding the `ComponentCategory` attribute, a different category can be chosen.  
+If the chosen name does not exist yet, it ill be added to the list in Game Studio.  
+```csharp
+[ComponentCategory("My own components")]
+```
+
+#### ComponentOrder
+By adding the `ComponentOrder` attribute, the order in which  
+components are listed in Game Studio can be changed.  
+```csharp
+[ComponentOrder(2001)]
+```
+
+### Separation of EntityComponent and Data
+
+`EntityProcessor<TComponent>` is a shortcut for `EntityProcessor<TComponent, TComponent>`.
+
+By explicitly using `EntityProcessor<TComponent, TData>` instead, a different type can be chosen  
+for the actual data. This way, the `EntityComponent` can e.g. have "heavier" startup data and  
+references, while the data object that needs to be processed every frame can be kept small.