Skip to content

Commit eaec923

Browse files
committed
GameConfig docs
1 parent 3944e58 commit eaec923

1 file changed

Lines changed: 98 additions & 80 deletions

File tree

src/boot/Config.js

Lines changed: 98 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -24,76 +24,76 @@ var ValueToColor = require('../display/color/ValueToColor');
2424
/**
2525
* @callback BootCallback
2626
*
27-
* @param {Phaser.Game} game - [description]
27+
* @param {Phaser.Game} game - The game.
2828
*/
2929

3030
/**
3131
* @typedef {object} InputConfig
3232
*
33-
* @property {(boolean|KeyboardInputConfig)} [keyboard=true] - [description]
34-
* @property {(boolean|MouseInputConfig)} [mouse=true] - [description]
35-
* @property {(boolean|TouchInputConfig)} [touch=true] - [description]
36-
* @property {(boolean|GamepadInputConfig)} [gamepad=false] - [description]
37-
* @property {integer} [activePointers=1] - [description]
33+
* @property {(boolean|KeyboardInputConfig)} [keyboard=true] - Keyboard input configuration. `true` uses the default configuration and `false` disables keyboard input.
34+
* @property {(boolean|MouseInputConfig)} [mouse=true] - Mouse input configuration. `true` uses the default configuration and `false` disables mouse input.
35+
* @property {(boolean|TouchInputConfig)} [touch=true] - Touch input configuration. `true` uses the default configuration and `false` disables touch input.
36+
* @property {(boolean|GamepadInputConfig)} [gamepad=false] - Gamepad input configuration. `true` enables gamepad input.
37+
* @property {integer} [activePointers=1] - The maximum number of touch pointers. See {@link Phaser.Input.InputManager#pointers}.
3838
*/
3939

4040
/**
4141
* @typedef {object} MouseInputConfig
4242
*
43-
* @property {*} [target=null] - [description]
44-
* @property {boolean} [capture=true] - [description]
43+
* @property {*} [target=null] - Where the Mouse Manager listens for mouse input events. The default is the game canvas.
44+
* @property {boolean} [capture=true] - Whether mouse input events have preventDefault() called on them.
4545
*/
4646

4747
/**
4848
* @typedef {object} KeyboardInputConfig
4949
*
50-
* @property {*} [target=window] - [description]
50+
* @property {*} [target=window] - Where the Keyboard Manager listens for keyboard input events.
5151
*/
5252

5353
/**
5454
* @typedef {object} TouchInputConfig
5555
*
56-
* @property {*} [target=null] - [description]
57-
* @property {boolean} [capture=true] - [description]
56+
* @property {*} [target=null] - Where the Touch Manager listens for touch input events. The default is the game canvas.
57+
* @property {boolean} [capture=true] - Whether touch input events have preventDefault() called on them.
5858
*/
5959

6060
/**
6161
* @typedef {object} GamepadInputConfig
6262
*
63-
* @property {*} [target=window] - [description]
63+
* @property {*} [target=window] - Where the Gamepad Manager listens for gamepad input events.
6464
*/
6565

6666
/**
6767
* @typedef {object} BannerConfig
6868
*
69-
* @property {boolean} [hidePhaser=false] - [description]
70-
* @property {string} [text='#ffffff'] - [description]
71-
* @property {string[]} [background] - [description]
69+
* @property {boolean} [hidePhaser=false] - Omit Phaser's name and version from the banner.
70+
* @property {string} [text='#ffffff'] - The color of the banner text.
71+
* @property {string[]} [background] - The background colors of the banner.
7272
*/
7373

7474
/**
7575
* @typedef {object} FPSConfig
7676
*
77-
* @property {integer} [min=10] - [description]
78-
* @property {integer} [target=60] - [description]
79-
* @property {boolean} [forceSetTimeOut=false] - [description]
80-
* @property {integer} [deltaHistory=10] - [description]
77+
* @property {integer} [min=10] - The minimum acceptable rendering rate, in frames per second.
78+
* @property {integer} [target=60] - The optimum rendering rate, in frames per second.
79+
* @property {boolean} [forceSetTimeOut=false] - Use setTimeout instead of requestAnimationFrame to run the game loop.
80+
* @property {integer} [deltaHistory=10] - Calculate the average frame delta from this many consecutive frame intervals.
8181
* @property {integer} [panicMax=120] - [description]
8282
*/
8383

8484
/**
8585
* @typedef {object} RenderConfig
8686
*
87-
* @property {boolean} [antialias=true] - [description]
88-
* @property {boolean} [pixelArt=false] - [description]
87+
* @property {boolean} [antialias=true] - When set to `true`, WebGL uses linear interpolation to draw scaled or rotated textures, giving a smooth appearance. When set to `false`, WebGL uses nearest-neighbor interpolation, giving a crisper appearance. `false` also disables antialiasing of the game canvas itself, if the browser supports it, when the game canvas is scaled.
88+
* @property {boolean} [pixelArt=false] - Sets `antialias` and `roundPixels` to true. This is the best setting for pixel-art games.
8989
* @property {boolean} [autoResize=true] - Automatically resize the Game Canvas if you resize the renderer.
90-
* @property {boolean} [roundPixels=false] - [description]
91-
* @property {boolean} [transparent=false] - [description]
92-
* @property {boolean} [clearBeforeRender=true] - [description]
93-
* @property {boolean} [premultipliedAlpha=true] - [description]
94-
* @property {boolean} [preserveDrawingBuffer=false] - [description]
95-
* @property {boolean} [failIfMajorPerformanceCaveat=false] - [description]
96-
* @property {string} [powerPreference='default'] - "high-performance", "low-power" or "default"
90+
* @property {boolean} [roundPixels=false] - Draw texture-based Game Objects at only whole-integer positions. Game Objects without textures, like Graphics, ignore this property.
91+
* @property {boolean} [transparent=false] - Whether the game canvas will be transparent.
92+
* @property {boolean} [clearBeforeRender=true] - Whether the game canvas will be cleared between each rendering frame.
93+
* @property {boolean} [premultipliedAlpha=true] - In WebGL mode, the drawing buffer contains colors with pre-multiplied alpha.
94+
* @property {boolean} [preserveDrawingBuffer=false] - In WebGL mode, the drawing buffer won't be cleared automatically each frame.
95+
* @property {boolean} [failIfMajorPerformanceCaveat=false] - Let the browser abort creating a WebGL context if it judges performance would be unacceptable.
96+
* @property {string} [powerPreference='default'] - "high-performance", "low-power" or "default". A hint to the browser on how much device power the game might use.
9797
* @property {integer} [batchSize=2000] - The default WebGL batch size.
9898
*/
9999

@@ -104,8 +104,8 @@ var ValueToColor = require('../display/color/ValueToColor');
104104
* @property {(integer|string)} [height=768] - The base height of your game.
105105
* @property {integer} [zoom=1] - The zoom value of the game canvas.
106106
* @property {number} [resolution=1] - The rendering resolution of the canvas.
107-
* @property {any} [parent] - The parent DOM element.
108-
* @property {integer} [mode=0] - The scale mode to apply to the canvas.
107+
* @property {(HTMLElement|string)} [parent] - The DOM element that will contain the game canvas, or its `id`. If null (the default) or if the named element doesn't exist, the game canvas is inserted directly into the document body.
108+
* @property {integer} [mode=0] - The scale mode to apply to the canvas. SHOW_ALL, EXACT_FIT, USER_SCALE, or RESIZE.
109109
* @property {integer} [minWidth] - The minimum width the canvas can be scaled down to.
110110
* @property {integer} [minHeight] - The minimum height the canvas can be scaled down to.
111111
* @property {integer} [maxWidth] - The maximum width the canvas can be scaled up to.
@@ -115,22 +115,22 @@ var ValueToColor = require('../display/color/ValueToColor');
115115
/**
116116
* @typedef {object} CallbacksConfig
117117
*
118-
* @property {BootCallback} [preBoot=NOOP] - [description]
119-
* @property {BootCallback} [postBoot=NOOP] - [description]
118+
* @property {BootCallback} [preBoot=NOOP] - A function to run at the start of the boot sequence.
119+
* @property {BootCallback} [postBoot=NOOP] - A function to run at the end of the boot sequence. At this point, all the game systems have started and plugins have been loaded.
120120
*/
121121

122122
/**
123123
* @typedef {object} LoaderConfig
124124
*
125-
* @property {string} [baseURL] - [description]
126-
* @property {string} [path] - [description]
127-
* @property {integer} [maxParallelDownloads=32] - [description]
128-
* @property {(string|undefined)} [crossOrigin=undefined] - [description]
129-
* @property {string} [responseType] - [description]
130-
* @property {boolean} [async=true] - [description]
131-
* @property {string} [user] - [description]
132-
* @property {string} [password] - [description]
133-
* @property {integer} [timeout=0] - [description]
125+
* @property {string} [baseURL] - An URL used to resolve paths given to the loader. Example: 'http://labs.phaser.io/assets/'.
126+
* @property {string} [path] - An URL path used to resolve relative paths given to the loader. Example: 'images/sprites/'.
127+
* @property {integer} [maxParallelDownloads=32] - The maximum number of resources the loader will start loading at once.
128+
* @property {(string|undefined)} [crossOrigin=undefined] - 'anonymous', 'use-credentials', or `undefined`. If you're not making cross-origin requests, leave this as `undefined`. See {@link https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes}.
129+
* @property {string} [responseType] - The response type of the XHR request, e.g. `blob`, `text`, etc.
130+
* @property {boolean} [async=true] - Should the XHR request use async or not?
131+
* @property {string} [user] - Optional username for the XHR request.
132+
* @property {string} [password] - Optional password for the XHR request.
133+
* @property {integer} [timeout=0] - Optional XHR timeout value, in ms.
134134
*/
135135

136136
/**
@@ -143,72 +143,90 @@ var ValueToColor = require('../display/color/ValueToColor');
143143
/**
144144
* @typedef {object} ImagesConfig
145145
*
146-
* @property {string} [default] - [description]
147-
* @property {string} [missing] - [description]
146+
* @property {string} [default] - URL to use for the 'default' texture.
147+
* @property {string} [missing] - URL to use for the 'missing' texture.
148148
*/
149149

150+
/**
151+
* @typedef {object} PhysicsConfig
152+
*
153+
* @property {string} [default] - The default physics system. It will be started for each scene. Phaser provides 'arcade', 'impact', and 'matter'.
154+
* @property {ArcadeWorldConfig} [arcade] - Arcade Physics configuration.
155+
* @property {Phaser.Physics.Impact.WorldConfig} [impact] - Impact Physics configuration.
156+
* @property {object} [matter] - Matter Physics configuration.
157+
*/
158+
150159
/**
151160
* @typedef {object} PluginObjectItem
152161
*
153-
* @property {string} [key] - [description]
154-
* @property {*} [plugin] - [description]
155-
* @property {boolean} [start] - [description]
156-
* @property {string} [systemKey] - [description]
157-
* @property {string} [sceneKey] - [description]
158-
* @property {*} [data] - [description]
162+
* @property {string} [key] - A key to identify the plugin in the Plugin Manager.
163+
* @property {*} [plugin] - The plugin itself. Usually a class/constructor.
164+
* @property {boolean} [start] - Whether the plugin should be started automatically.
165+
* @property {string} [systemKey] - For a scene plugin, add the plugin to the scene's systems object under this key (`this.sys.KEY`, from the scene).
166+
* @property {string} [sceneKey] - For a scene plugin, add the plugin to the scene object under this key (`this.KEY`, from the scene).
167+
* @property {*} [data] - Arbitrary data passed to the plugin's init() method.
168+
*
169+
* @example
170+
* // Global plugin
171+
* { key: 'BankPlugin', plugin: BankPluginV3, start: true, data: { gold: 5000 } }
172+
* @example
173+
* // Scene plugin
174+
* { key: 'WireFramePlugin', plugin: WireFramePlugin, systemKey: 'wireFramePlugin', sceneKey: 'wireframe' }
159175
*/
160176

161177
/**
162178
* @typedef {object} PluginObject
163179
*
164-
* @property {?PluginObjectItem[]} [global] - [description]
165-
* @property {?PluginObjectItem[]} [scene] - [description]
166-
* @property {string[]} [default] - [description]
167-
* @property {*} [defaultMerge] - [description]
180+
* @property {?PluginObjectItem[]} [global] - Global plugins to install.
181+
* @property {?PluginObjectItem[]} [scene] - Scene plugins to install.
182+
* @property {string[]} [default] - The default set of scene plugins (names).
183+
* @property {string[]} [defaultMerge] - Plugins to *add* to the default set of scene plugins.
168184
*/
169185

170186
/**
171187
* @typedef {object} GameConfig
172188
*
173-
* @property {(integer|string)} [width=1024] - [description]
174-
* @property {(integer|string)} [height=768] - [description]
175-
* @property {number} [zoom=1] - [description]
176-
* @property {number} [resolution=1] - [description]
177-
* @property {number} [type=CONST.AUTO] - [description]
178-
* @property {*} [parent=null] - [description]
189+
* @property {(integer|string)} [width=1024] - The width of the game, in game pixels.
190+
* @property {(integer|string)} [height=768] - The height of the game, in game pixels.
191+
* @property {number} [zoom=1] - Simple scale applied to the game canvas. 2 is double size, 0.5 is half size, etc.
192+
* @property {number} [resolution=1] - The size of each game pixel, in canvas pixels. Values larger than 1 are "high" resolution.
193+
* @property {number} [type=CONST.AUTO] - Which renderer to use. Phaser.AUTO, Phaser.CANVAS, Phaser.HEADLESS, or Phaser.WEBGL. AUTO picks WEBGL if available, otherwise CANVAS.
194+
* @property {(HTMLElement|string)} [parent=null] - The DOM element that will contain the game canvas, or its `id`. If null (the default) or if the named element doesn't exist, the game canvas is inserted directly into the document body.
179195
* @property {HTMLCanvasElement} [canvas=null] - Provide your own Canvas element for Phaser to use instead of creating one.
180-
* @property {string} [canvasStyle=null] - [description]
196+
* @property {string} [canvasStyle=null] - CSS styles to apply to the game canvas instead of Phaser's default styles.
181197
* @property {CanvasRenderingContext2D} [context] - Provide your own Canvas Context for Phaser to use, instead of creating one.
182-
* @property {object} [scene=null] - [description]
183-
* @property {string[]} [seed] - [description]
184-
* @property {string} [title=''] - The title of the game.
185-
* @property {string} [url='http://phaser.io'] - The url of the game.
186-
* @property {string} [version=''] - The version of the game.
187-
* @property {boolean} [autoFocus=true] - Automatically call window.focus() when the game boots.
188-
* @property {(boolean|InputConfig)} [input] - [description]
189-
* @property {boolean} [disableContextMenu=false] - [description]
190-
* @property {(boolean|BannerConfig)} [banner=false] - [description]
198+
* @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 }.
199+
* @property {string[]} [seed] - Seed for the random number generator.
200+
* @property {string} [title=''] - The title of the game. Shown in the browser console.
201+
* @property {string} [url='http://phaser.io'] - The URL of the game. Shown in the browser console.
202+
* @property {string} [version=''] - The version of the game. Shown in the browser console.
203+
* @property {boolean} [autoFocus=true] - Automatically call window.focus() when the game boots. Usually necessary to capture input events if the game is in a separate frame.
204+
* @property {(boolean|InputConfig)} [input] - Input configuration, or `false` to disable all game input.
205+
* @property {boolean} [disableContextMenu=false] - Disable the browser's default 'contextmenu' event (usually triggered by a right-button mouse click).
206+
* @property {(boolean|BannerConfig)} [banner=false] - Configuration for the banner printed in the browser console when the game starts.
191207
* @property {DOMContainerConfig} [dom] - The DOM Container configuration object.
192-
* @property {FPSConfig} [fps] - [description]
193-
* @property {RenderConfig} [render] - [description]
194-
* @property {(string|number)} [backgroundColor=0x000000] - [description]
195-
* @property {CallbacksConfig} [callbacks] - [description]
196-
* @property {LoaderConfig} [loader] - [description]
197-
* @property {ImagesConfig} [images] - [description]
198-
* @property {object} [physics] - [description]
199-
* @property {PluginObject|PluginObjectItem[]} [plugins] - [description]
208+
* @property {FPSConfig} [fps] - Game loop configuration.
209+
* @property {RenderConfig} [render] - Game renderer configuration.
210+
* @property {(string|number)} [backgroundColor=0x000000] - The background color of the game canvas. The default is black.
211+
* @property {CallbacksConfig} [callbacks] - Optional callbacks to run before or after game boot.
212+
* @property {LoaderConfig} [loader] - Loader configuration.
213+
* @property {ImagesConfig} [images] - Images configuration.
214+
* @property {object} [physics] - Physics configuration.
215+
* @property {PluginObject|PluginObjectItem[]} [plugins] - Plugins to install.
200216
*/
201217

202218
/**
203219
* @classdesc
204-
* [description]
220+
* The active game configuration settings, parsed from a {@link GameConfig} object.
205221
*
206222
* @class Config
207223
* @memberOf Phaser.Boot
208224
* @constructor
209225
* @since 3.0.0
210226
*
211227
* @param {GameConfig} [GameConfig] - The configuration object for your Phaser Game instance.
228+
*
229+
* @see Phaser.Game#config
212230
*/
213231
var Config = new Class({
214232

@@ -614,9 +632,9 @@ var Config = new Class({
614632
* { key: 'WireFramePlugin', plugin: WireFramePlugin, systemKey: 'wireFramePlugin', sceneKey: 'wireframe' }
615633
* ],
616634
* default: [], OR
617-
* defaultMerge: {
635+
* defaultMerge: [
618636
* 'ModPlayer'
619-
* }
637+
* ]
620638
* }
621639
*/
622640

0 commit comments

Comments
 (0)