Merge pull request phaserjs#4469 from samme/docs/scenes

Docs for scene config and optional scene methods

Author: photonstorm

src/core/Config.js

@@ -17,7 +17,7 @@ var ValueToColor = require('../display/color/ValueToColor');
 
 /**
  * @classdesc
- * The active game configuration settings, parsed from a {@link GameConfig} object.
+ * The active game configuration settings, parsed from a {@link Phaser.Core.Types.GameConfig} object.
  *
  * @class Config
  * @memberof Phaser.Core

src/core/typedefs/GameConfig.js

@@ -11,7 +11,7 @@
  * @property {HTMLCanvasElement} [canvas=null] - Provide your own Canvas element for Phaser to use instead of creating one.
  * @property {string} [canvasStyle=null] - CSS styles to apply to the game canvas instead of Phaser's default styles.
  * @property {CanvasRenderingContext2D} [context] - Provide your own Canvas Context for Phaser to use, instead of creating one.
- * @property {object} [scene=null] - A scene or scenes to add to the game. If several are given, the first is started; the remainder are started only if they have { active: true }.
+ * @property {(Phaser.Scene|Phaser.Scene[]|Phaser.Scenes.Types.SettingsConfig|Phaser.Scenes.Types.SettingsConfig[]|Phaser.Scenes.Types.CreateSceneFromObjectConfig|Phaser.Scenes.Types.CreateSceneFromObjectConfig[]|function|function[])} [scene=null] - A scene or scenes to add to the game. If several are given, the first is started; the remainder are started only if they have `{ active: true }`. See the `sceneConfig` argument in {@link Phaser.Scenes.SceneManager#add}.
  * @property {string[]} [seed] - Seed for the random number generator.
  * @property {string} [title=''] - The title of the game. Shown in the browser console.
  * @property {string} [url='http://phaser.io'] - The URL of the game. Shown in the browser console.

src/scene/Scene.js

@@ -269,9 +269,9 @@ var Scene = new Class({
 
     /**
      * Should be overridden by your own Scenes.
+     * This method is called once per game step while the scene is running.
      *
      * @method Phaser.Scene#update
-     * @override
      * @since 3.0.0
      *
      * @param {number} time - The current time. Either a High Resolution Timer value if it comes from Request Animation Frame, or Date.now if using SetTimeout.
@@ -282,27 +282,33 @@ var Scene = new Class({
     }
 
     /**
-     * Should be overridden by your own Scenes.
+     * Can be defined on your own Scenes.
+     * This method is called by the Scene Manager when the scene starts, before `preload()` and `create()`.
      *
      * @method Phaser.Scene#init
-     * @override
      * @since 3.0.0
+     *
+     * @param {object} data - Any data passed via `ScenePlugin.add()` or `ScenePlugin.start()`. Same as Scene.settings.data.
      */
 
     /**
-     * Should be overridden by your own Scenes.
+     * Can be defined on your own Scenes. Use it to load assets.
+     * This method is called by the Scene Manager, after `init()` and before `create()`, only if the Scene has a LoaderPlugin.
+     * After this method completes, if the LoaderPlugin's queue isn't empty, the LoaderPlugin will start automatically.
      *
      * @method Phaser.Scene#preload
-     * @override
      * @since 3.0.0
      */
 
     /**
-     * Should be overridden by your own Scenes.
+     * Can be defined on your own Scenes. Use it to create your game objects.
+     * This method is called by the Scene Manager when the scene starts, after `init()` and `preload()`.
+     * If the LoaderPlugin started after `preload()`, then this method is called only after loading is complete.
      *
      * @method Phaser.Scene#create
-     * @override
      * @since 3.0.0
+     *
+     * @param {object} data - Any data passed via `ScenePlugin.add()` or `ScenePlugin.start()`. Same as Scene.settings.data.
      */
 
 });

src/scene/SceneManager.js

@@ -312,7 +312,7 @@ var SceneManager = new Class({
      * @since 3.0.0
      *
      * @param {string} key - A unique key used to reference the Scene, i.e. `MainMenu` or `Level1`.
-     * @param {(Phaser.Scene|Phaser.Scenes.Types.SettingsConfig|function)} sceneConfig - The config for the Scene
+     * @param {(Phaser.Scene|Phaser.Scenes.Types.SettingsConfig|Phaser.Scenes.Types.CreateSceneFromObjectConfig|function)} sceneConfig - The config for the Scene
      * @param {boolean} [autoStart=false] - If `true` the Scene will be started immediately after being added.
      * @param {object} [data] - Optional data object. This will be set as Scene.settings.data and passed to `Scene.init`.
      *
@@ -710,7 +710,7 @@ var SceneManager = new Class({
      * @since 3.0.0
      *
      * @param {string} key - The key of the Scene.
-     * @param {(string|Phaser.Scenes.Types.SettingsConfig)} sceneConfig - The Scene config.
+     * @param {(string|Phaser.Scenes.Types.SettingsConfig|Phaser.Scenes.Types.CreateSceneFromObjectConfig)} sceneConfig - The Scene config.
      *
      * @return {Phaser.Scene} The created Scene.
      */

src/scene/ScenePlugin.js

@@ -430,7 +430,7 @@ var ScenePlugin = new Class({
      * @since 3.0.0
      *
      * @param {string} key - The Scene key.
-     * @param {(Phaser.Scene|Phaser.Scenes.Types.SettingsConfig|function)} sceneConfig - The config for the Scene.
+     * @param {(Phaser.Scene|Phaser.Scenes.Types.SettingsConfig|Phaser.Scenes.Types.CreateSceneFromObjectConfig|function)} sceneConfig - The config for the Scene.
      * @param {boolean} autoStart - Whether to start the Scene after it's added.
      * @param {object} [data] - Optional data object. This will be set as Scene.settings.data and passed to `Scene.init`.
      *

src/scene/typedefs/CreateSceneFromObjectConfig.js

@@ -0,0 +1,11 @@
+/**
+ * @typedef {object} Phaser.Scenes.Types.CreateSceneFromObjectConfig
+ * @since 3.17.0
+ *
+ * @property {function} [init] - See {@link Phaser.Scene#init}.
+ * @property {function} [preload] - See See {@link Phaser.Scene#preload}.
+ * @property {function} [create] - See {@link Phaser.Scene#create}.
+ * @property {function} [update] - See {@link Phaser.Scene#update}.
+ * @property {any} [extend] - Any additional properties, which will be copied to the Scene after it's created (except `data` or `sys`).
+ * @property {any} [extend.data] - Any values, which will be merged into the Scene's Data Manager store.
+ */