write about the entity model

README.org

@@ -6,6 +6,7 @@
   - [[#dots-packages][DOTS Packages]]
 - [[#platform-packages][Platform Packages]]
 - [[#builds][Builds]]
+- [[#entities][Entities]]
 
 * Preface, "Why?"
 Unity is in the midst of a transformation that will fundamentally change the way
@@ -56,3 +57,49 @@ platform through the asset manager:
 
 From now on you must build the project by selecting this configuration and using
 the options shown in the inspector.
+* Entities
+In the standard OOP model of game development, functionality is tied to
+individual instances of objects. Each Monobehaviour (the class that from which
+all standard scripts inherit) has its own ~Start()~, ~Update()~, similar and
+accompanying methods. The engine will run all of these sequentially.
+
+In this model, each game object is treated as a collection of data (the entity),
+with this data organised into "components". These components are analogous to a
+struct in C, they are mutable collections of data, they do not have their own
+functionality in the form of methods.
+
+It is the job of a =System= to read and transform the data of the entities. For
+example you may have many entities with a ~Character~ component, each with an
+~hp~ variable. This will include all players, enemies and NPCs. Characters may
+be poisoned during the game, adding a ~Poison~ component to their entity. This
+component will contain a value ~float rate~ to determine how much damage to deal
+each second, and a ~float duration~ to determine how long the character will be
+poisoned for.
+
+You may define a ~StatusSystem~, which manages status effects (in this case
+poisoning). It will operate on all of the entities with a ~Character~ /and/ a
+~Poison~ component, and update the ~hp~ variable based on the data related to
+the poison.
+
+What will this look like? Within the StatusSystem's ~OnUpdate()~ method:
+#+begin_src csharp :exports code
+float dT = Time.DeltaTime;
+
+Entities
+  .WithAll<Character, Poison>()
+  .ForEach(
+      // define the lambda that transforms the data
+    (ref Character ch, ref Poison poison, in Entity entity) => {
+      ch.hp -= poison.rate * dT;
+      poison.duration -= dT;
+      if (poison.duration <= 0) // remove the poison component if it has expired
+          EntityManager.RemoveComponent<Poison>(entity);
+    })
+  .ScheduleParallel();
+#+end_src
+
+Some keywords are used in the lambda definition that relate to C#'s implementation:
++ ~ref~ creates a mutable reference to the given argument
++ ~in~ creates an immutable reference to the argument (here we are not modifying
+  ~entity~, only passing the reference to the ~EntityManager~ in order to remove
+  the component)