Matter Physics timestep adjustments (getDelta, step, set60Hz, etc)

photonstorm · photonstorm · commit e7a1e3190a18 · 2018-03-27T15:15:05.000+01:00
* Matter Physics now has a new config property `getDelta` which allows you to specify your own function to calculate the delta value given to the Matter Engine when it updates.
* Matter Physics has two new methods: `set60Hz` and `set30Hz` which will set an Engine update rate of 60Hz and 30Hz respectively. 60Hz being the default.
* Matter Physics has a new config and run-time property `autoUpdate`, which defaults to `true`. When enabled the Matter Engine will update in sync with the game step (set by Request Animation Frame). The delta value given to Matter is now controlled by the `getDelta` function.
* Matter Physics has a new method `step` which manually advances the physics simulation by one iteration, using whatever delta and correction values you pass in to it. When used in combination with `autoUpdate=false` you can now explicitly control the update frequency of the physics simulation and unbind it from the game step.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,13 +1,16 @@
 # Change Log
 
-## Version 3.3.1 - Tetsuo - In Development
+## Version 3.4.0 - In Development
 
 ### New Features
 
 * A new property was added to Matter.World, `correction` which is used in the Engine.update call and allows you to adjust the time
 being passed to the simulation. The default value is 1 to remain consistent with previous releases.
 * Group.destroy has a new optional argument `destroyChildren` which will automatically call `destroy` on all children of a Group if set to true (the default is false, hence it doesn't change the public API). Fix #3246 (thanks @DouglasLapsley)
-
+* Matter Physics now has a new config property `getDelta` which allows you to specify your own function to calculate the delta value given to the Matter Engine when it updates.
+* Matter Physics has two new methods: `set60Hz` and `set30Hz` which will set an Engine update rate of 60Hz and 30Hz respectively. 60Hz being the default.
+* Matter Physics has a new config and run-time property `autoUpdate`, which defaults to `true`. When enabled the Matter Engine will update in sync with the game step (set by Request Animation Frame). The delta value given to Matter is now controlled by the `getDelta` function.
+* Matter Physics has a new method `step` which manually advances the physics simulation by one iteration, using whatever delta and correction values you pass in to it. When used in combination with `autoUpdate=false` you can now explicitly control the update frequency of the physics simulation and unbind it from the game step.
 
 ### Bug Fixes
 
diff --git a/src/physics/matter-js/MatterPhysics.js b/src/physics/matter-js/MatterPhysics.js
@@ -145,6 +145,8 @@ var MatterPhysics = new Class({
      *
      * @method Phaser.Physics.Matter.MatterPhysics#enableAttractorPlugin
      * @since 3.0.0
+     * 
+     * @return {Phaser.Physics.Matter.MatterPhysics} This Matter Physics instance.
      */
     enableAttractorPlugin: function ()
     {
@@ -159,6 +161,8 @@ var MatterPhysics = new Class({
      *
      * @method Phaser.Physics.Matter.MatterPhysics#enableWrapPlugin
      * @since 3.0.0
+     * 
+     * @return {Phaser.Physics.Matter.MatterPhysics} This Matter Physics instance.
      */
     enableWrapPlugin: function ()
     {
@@ -194,6 +198,72 @@ var MatterPhysics = new Class({
         return this.world.resume();
     },
 
+    /**
+     * Sets the Matter Engine to run at fixed timestep of 60Hz and enables `autoUpdate`.
+     * If you have set a custom `getDelta` function then this will override it.
+     *
+     * @method Phaser.Physics.Matter.MatterPhysics#set60Hz
+     * @since 3.4.0
+     *
+     * @return {Phaser.Physics.Matter.MatterPhysics} This Matter Physics instance.
+     */
+    set60Hz: function ()
+    {
+        this.world.getDelta = this.world.update60Hz;
+        this.world.autoUpdate = true;
+
+        return this;
+    },
+
+    /**
+     * Sets the Matter Engine to run at fixed timestep of 30Hz and enables `autoUpdate`.
+     * If you have set a custom `getDelta` function then this will override it.
+     *
+     * @method Phaser.Physics.Matter.MatterPhysics#set30Hz
+     * @since 3.4.0
+     *
+     * @return {Phaser.Physics.Matter.MatterPhysics} This Matter Physics instance.
+     */
+    set30Hz: function ()
+    {
+        this.world.getDelta = this.world.update30Hz;
+        this.world.autoUpdate = true;
+
+        return this;
+    },
+
+    /**
+     * Manually advances the physics simulation by one iteration.
+     * 
+     * You can optionally pass in the `delta` and `correction` values to be used by Engine.update.
+     * If undefined they use the Matter defaults of 60Hz and no correction.
+     * 
+     * Calling `step` directly bypasses any checks of `enabled` or `autoUpdate`.
+     * 
+     * It also ignores any custom `getDelta` functions, as you should be passing the delta
+     * value in to this call.
+     *
+     * You can adjust the number of iterations that Engine.update performs internally.
+     * Use the Scene Matter Physics config object to set the following properties:
+     *
+     * positionIterations (defaults to 6)
+     * velocityIterations (defaults to 4)
+     * constraintIterations (defaults to 2)
+     *
+     * Adjusting these values can help performance in certain situations, depending on the physics requirements
+     * of your game.
+     *
+     * @method Phaser.Physics.Matter.MatterPhysics#step
+     * @since 3.4.0
+     *
+     * @param {number} [delta=16.666] - [description]
+     * @param {number} [correction=1] - [description]
+     */
+    step: function (delta, correction)
+    {
+        this.world.step(delta, correction);
+    },
+
     /**
      * [description]
      *
diff --git a/src/physics/matter-js/World.js b/src/physics/matter-js/World.js
@@ -128,10 +128,52 @@ var World = new Class({
          * @name Phaser.Physics.Matter.World#correction
          * @type {number}
          * @default 1
-         * @since 3.3.1
+         * @since 3.4.0
          */
         this.correction = GetValue(config, 'correction', 1);
 
+        /**
+         * This function is called every time the core game loop steps, which is bound to the
+         * Request Animation Frame frequency unless otherwise modified.
+         * 
+         * The function is passed two values: `time` and `delta`, both of which come from the game step values.
+         * 
+         * It must return a number. This number is used as the delta value passed to Matter.Engine.update.
+         * 
+         * You can override this function with your own to define your own timestep.
+         * 
+         * If you need to update the Engine multiple times in a single game step then call
+         * `World.update` as many times as required. Each call will trigger the `getDelta` function.
+         * If you wish to have full control over when the Engine updates then see the property `autoUpdate`.
+         *
+         * You can also adjust the number of iterations that Engine.update performs.
+         * Use the Scene Matter Physics config object to set the following properties:
+         *
+         * positionIterations (defaults to 6)
+         * velocityIterations (defaults to 4)
+         * constraintIterations (defaults to 2)
+         *
+         * Adjusting these values can help performance in certain situations, depending on the physics requirements
+         * of your game.
+         *
+         * @name Phaser.Physics.Matter.World#getDelta
+         * @type {function}
+         * @since 3.4.0
+         */
+        this.getDelta = GetValue(config, 'getDelta', this.update60Hz);
+
+        /**
+         * Automatically call Engine.update every time the game steps.
+         * If you disable this then you are responsible for calling `World.step` directly from your game.
+         * If you call `set60Hz` or `set30Hz` then `autoUpdate` is reset to `true`.
+         *
+         * @name Phaser.Physics.Matter.World#autoUpdate
+         * @type {boolean}
+         * @default true
+         * @since 3.4.0
+         */
+        this.autoUpdate = GetValue(config, 'autoUpdate', true);
+
         /**
          * [description]
          *
@@ -604,12 +646,70 @@ var World = new Class({
      */
     update: function (time, delta)
     {
-        if (this.enabled)
+        if (this.enabled && this.autoUpdate)
         {
-            Engine.update(this.engine, delta, this.correction);
+            Engine.update(this.engine, this.getDelta(time, delta), this.correction);
         }
     },
 
+    /**
+     * Manually advances the physics simulation by one iteration.
+     * 
+     * You can optionally pass in the `delta` and `correction` values to be used by Engine.update.
+     * If undefined they use the Matter defaults of 60Hz and no correction.
+     * 
+     * Calling `step` directly bypasses any checks of `enabled` or `autoUpdate`.
+     * 
+     * It also ignores any custom `getDelta` functions, as you should be passing the delta
+     * value in to this call.
+     *
+     * You can adjust the number of iterations that Engine.update performs internally.
+     * Use the Scene Matter Physics config object to set the following properties:
+     *
+     * positionIterations (defaults to 6)
+     * velocityIterations (defaults to 4)
+     * constraintIterations (defaults to 2)
+     *
+     * Adjusting these values can help performance in certain situations, depending on the physics requirements
+     * of your game.
+     *
+     * @method Phaser.Physics.Matter.World#step
+     * @since 3.4.0
+     *
+     * @param {number} [delta=16.666] - [description]
+     * @param {number} [correction=1] - [description]
+     */
+    step: function (delta, correction)
+    {
+        Engine.update(this.engine, delta, correction);
+    },
+
+    /**
+     * Runs the Matter Engine.update at a fixed timestep of 60Hz.
+     *
+     * @method Phaser.Physics.Matter.World#update60Hz
+     * @since 3.4.0
+     *
+     * @return {number} The delta value to be passed to Engine.update.
+     */
+    update60Hz: function ()
+    {
+        return 1000 / 60;
+    },
+
+    /**
+     * Runs the Matter Engine.update at a fixed timestep of 30Hz.
+     *
+     * @method Phaser.Physics.Matter.World#update30Hz
+     * @since 3.4.0
+     *
+     * @return {number} The delta value to be passed to Engine.update.
+     */
+    update30Hz: function ()
+    {
+        return 1000 / 30;
+    },
+
     /**
      * [description]
      *
