Added new SetValue function for property setting to any depth

Author: photonstorm

CHANGELOG.md

@@ -96,6 +96,7 @@ Notes:
 * The `Container.setScrollFactor` method has a new optional argument `updateChildren`. If set, it will change the `scrollFactor` values of all the Container children as well as the Container. Fix #4466 #4475 (thanks @pinkkis @enriqueto)
 * There is a new webpack config `FEATURE_SOUND` which is set to `true` by default, but if set to `false` it will exclude the Sound Manager and all of its systems into the build files. Fix #4428 (thanks @goldfire)
 * `Scene.Systems.renderer` is a new property that is a reference to the current renderer the game is using.
+* `Utils.Objects.SetValue` is a new function that allows you to set a value in an object by specifying a property key. The function can set a value to any depth by using dot-notation for the key, i.e. `SetValue(data, 'world.position.x', 100)`.
 
 ### Updates
 

src/utils/object/SetValue.js

@@ -0,0 +1,77 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * Sets a value in an object, allowing for dot notation to control the depth of the property.
+ * 
+ * For example:
+ * 
+ * ```javascript
+ * var data = {
+ *   world: {
+ *     position: {
+ *       x: 200,
+ *       y: 100
+ *     }
+ *   }
+ * };
+ * 
+ * SetValue(data, 'world.position.y', 300);
+ * 
+ * console.log(data.world.position.y); // 300
+ * ```
+ *
+ * @function Phaser.Utils.Objects.SetValue
+ * @since 3.17.0
+ *
+ * @param {object} source - The object to set the value in.
+ * @param {string} key - The name of the property in the object. If a property is nested, the names of its preceding properties should be separated by a dot (`.`)
+ * @param {any} value - The value to set into the property, if found in the source object.
+ *
+ * @return {boolean} `true` if the property key was valid and the value was set, otherwise `false`.
+ */
+var SetValue = function (source, key, value)
+{
+    if (!source || typeof source === 'number')
+    {
+        return false;
+    }
+    else if (source.hasOwnProperty(key))
+    {
+        source[key] = value;
+
+        return true;
+    }
+    else if (key.indexOf('.') !== -1)
+    {
+        var keys = key.split('.');
+        var parent = source;
+        var prev = source;
+
+        //  Use for loop here so we can break early
+        for (var i = 0; i < keys.length; i++)
+        {
+            if (parent.hasOwnProperty(keys[i]))
+            {
+                //  Yes it has a key property, let's carry on down
+                prev = parent;
+                parent = parent[keys[i]];
+            }
+            else
+            {
+                return false;
+            }
+        }
+
+        prev[keys[keys.length - 1]] = value;
+
+        return true;
+    }
+    
+    return false;
+};
+
+module.exports = SetValue;

src/utils/object/index.js

@@ -21,6 +21,7 @@ module.exports = {
     HasValue: require('./HasValue'),
     IsPlainObject: require('./IsPlainObject'),
     Merge: require('./Merge'),
-    MergeRight: require('./MergeRight')
+    MergeRight: require('./MergeRight'),
+    SetValue: require('./SetValue')
 
 };