Add DataDriver (experimental)

Author: shakiba

.changeset/gentle-colts-hunt.md

@@ -0,0 +1,5 @@
+---
+"planck": minor
+---
+
+Add DataDriver (experimental for demo use-case)

docs/pages/data-driver.md

@@ -0,0 +1,56 @@
+## Data Driver
+
+When developing a game or an application you often need a data-model to represent your game state and objects. A physics engine is useful for simulating the physical movements and interactions between objects, however it is not always the best tool for representing your game data-model. In addition, a physics engine has very complex internal state, which would add unnecessarily complexity to your game if physics engine internal state is directly combined with the game data-model.
+
+This is where the DataDriver comes in. A DataDriver translates your game data-model to physics engine objects, while keeping the two separate. This allows you to create a simple and clean game data-model, while still benefiting from the physics engine.
+
+Planck's DataDriver class is inspired by D3, and reactive-programming in general. Given two arrays of objects, and a key-function, it find the elements that are added or removed from the array, and calls the corresponding callback functions to map them to physics simulation.
+
+Another benefit of using a DataDriver is that you can simply use your game data-model to persist or transfer game state and objects, without serializing the physics engine state.
+
+Here is a simple example of how to use the DataDriver:
+
+```javascript
+const world = new World();
+
+// create a driver, with key and callback functions
+const driver = new DataDriver({
+  key: function(d) {
+    return d.id;
+  },
+  create: function(d) {
+    const body = world.createBody({
+      type: "dynamic",
+      angle: d.angle,
+      userData: d
+    });
+    body.createFixture({
+      shape: new Circle(),
+      density: 1.0
+    });
+    return body;
+  },
+  update: function(d, body) {
+    body.setAngle(d.angle);
+  },
+  destroy: function(d) {
+    world.destroyBody(d);
+  }
+});
+
+// this will create blue and red bodies
+driver.data([
+  { id: "player-blue", type: "player", angle: 0.12 * Math.PI },
+  { id: "player-red", type: "player", angle: 0.53 * Math.PI }
+]);
+
+// this will remove red, update blue, and create yellow
+driver.data([
+  { id: "player-red", type: "player", angle: 0.58 * Math.PI },
+  { id: "player-yellow", type: "player",  angle: 0.72 * Math.PI },
+]);
+```
+
+DataDriver is used in multiple demo games in the Planck.js repository, please see the /example directory for more information.
+
+DataDriver was introduced in Planck v1.3.