added Runner.create and Runner.tick

src/core/Runner.js

@@ -1,6 +1,9 @@
 /**
 * The `Matter.Runner` module is an optional utility which provides a game loop, 
 * that handles updating and rendering a `Matter.Engine` for you within a browser.
+* It is intended for demo and testing purposes, but may be adequate for simple games.
+* If you are using your own game loop instead, then you do not need the `Matter.Runner` module.
+* Instead just call `Engine.update(engine, delta)` in your own loop.
 * Note that the method `Engine.run` is an alias for `Runner.run`.
 *
 * See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js) 
@@ -18,41 +21,68 @@ var Runner = {};
         return;
     }
 
-    var _fps = 60,
-        _deltaSampleSize = _fps,
-        _delta = 1000 / _fps;
-
     var _requestAnimationFrame = window.requestAnimationFrame || window.webkitRequestAnimationFrame
                                       || window.mozRequestAnimationFrame || window.msRequestAnimationFrame 
-                                      || function(callback){ window.setTimeout(function() { callback(Common.now()); }, _delta); };
+                                      || function(callback){ window.setTimeout(function() { callback(Common.now()); }, 1000 / 60); };
    
     var _cancelAnimationFrame = window.cancelAnimationFrame || window.mozCancelAnimationFrame 
                                       || window.webkitCancelAnimationFrame || window.msCancelAnimationFrame;
 
     /**
-     * Provides a basic game loop that handles updating the engine for you.
+     * Creates a new Runner. The options parameter is an object that specifies any properties you wish to override the defaults.
-     * Calls `Engine.update` and `Engine.render` on the `requestAnimationFrame` event automatically.
+     * @method create
-     * Handles time correction and non-fixed dynamic timing (if enabled). 
+     * @param {} options
-     * Triggers `beforeTick`, `tick` and `afterTick` events.
+     */
+    Runner.create = function(options) {
+        var defaults = {
+            deltaSampleSize: 60,
+            counterTimestamp: 0,
+            frameCounter: 0,
+            deltaHistory: [],
+            timePrev: null,
+            timeScalePrev: 1
+        };
+
+        return Common.extend(defaults, options);
+    };
+
+    /**
+     * Continuously ticks a `Matter.Engine` by calling `Runner.tick` on the `requestAnimationFrame` event.
      * @method run
      * @param {engine} engine
      */
-    Runner.run = function(engine) {
+    Runner.run = function(runner, engine) {
-        var counterTimestamp = 0,
+        // create runner if engine is first argument
-            frameCounter = 0,
+        if (typeof runner.positionIterations !== 'undefined') {
-            deltaHistory = [],
+            engine = runner;
-            timePrev,
+            runner = Runner.create(engine);
-            timeScalePrev = 1;
+        }
 
         (function render(time){
+            engine.timing.frameRequestId = _requestAnimationFrame(render);
+
+            if (time && engine.enabled) {
+                Runner.tick(runner, engine, time);
+            }
+        })();
+
+        return runner;
+    };
+
+    /**
+     * A game loop utility that updates the engine and renderer by one step (a 'tick').
+     * Features delta smoothing, time correction and fixed or dynamic timing.
+     * Triggers `beforeTick`, `tick` and `afterTick` events on the engine.
+     * Consider just `Engine.update(engine, delta)` if you're using your own loop.
+     * @method tick
+     * @param {runner} runner
+     * @param {engine} engine
+     * @param {number} time
+     */
+    Runner.tick = function(runner, engine, time) {
         var timing = engine.timing,
-                delta,
+            correction = 1,
-                correction = 1;
+            delta;
-
-            timing.frameRequestId = _requestAnimationFrame(render);
-
-            if (!engine.enabled)
-                return;
 
         // create an event object
         var event = {
@@ -66,19 +96,19 @@ var Runner = {};
             delta = timing.delta;
         } else {
             // dynamic timestep based on wall clock between calls
-                delta = (time - timePrev) || timing.delta;
+            delta = (time - runner.timePrev) || timing.delta;
-                timePrev = time;
+            runner.timePrev = time;
 
             // optimistically filter delta over a few frames, to improve stability
-                deltaHistory.push(delta);
+            runner.deltaHistory.push(delta);
-                deltaHistory = deltaHistory.slice(-_deltaSampleSize);
+            runner.deltaHistory = runner.deltaHistory.slice(-runner.deltaSampleSize);
-                delta = Math.min.apply(null, deltaHistory);
+            delta = Math.min.apply(null, runner.deltaHistory);
             
             // limit delta
             delta = delta < timing.deltaMin ? timing.deltaMin : delta;
             delta = delta > timing.deltaMax ? timing.deltaMax : delta;
 
-                // time correction for delta
+            // time runner.correction for delta
             correction = delta / timing.delta;
 
             // update engine timing object
@@ -86,20 +116,20 @@ var Runner = {};
         }
 
         // time correction for time scaling
-            if (timeScalePrev !== 0)
+        if (runner.timeScalePrev !== 0)
-                correction *= timing.timeScale / timeScalePrev;
+            correction *= timing.timeScale / runner.timeScalePrev;
 
         if (timing.timeScale === 0)
             correction = 0;
 
-            timeScalePrev = timing.timeScale;
+        runner.timeScalePrev = timing.timeScale;
 
         // fps counter
-            frameCounter += 1;
+        runner.frameCounter += 1;
-            if (time - counterTimestamp >= 1000) {
+        if (time - runner.counterTimestamp >= 1000) {
-                timing.fps = frameCounter * ((time - counterTimestamp) / 1000);
+            timing.fps = runner.frameCounter * ((time - runner.counterTimestamp) / 1000);
-                counterTimestamp = time;
+            runner.counterTimestamp = time;
-                frameCounter = 0;
+            runner.frameCounter = 0;
         }
 
         Events.trigger(engine, 'tick', event);
@@ -121,7 +151,6 @@ var Runner = {};
         }
 
         Events.trigger(engine, 'afterTick', event);
-        })();
     };
 
     /**