diff --git a/Docs/Documentation Checklist.xlsx b/Docs/Documentation Checklist.xlsx index a38b0512..292dcd33 100644 Binary files a/Docs/Documentation Checklist.xlsx and b/Docs/Documentation Checklist.xlsx differ diff --git a/src/core/Camera.js b/src/core/Camera.js index 9f34a911..22cdbe23 100644 --- a/src/core/Camera.js +++ b/src/core/Camera.js @@ -1,10 +1,16 @@ /** -* Phaser - Camera +* @author Richard Davey +* @copyright 2013 Photon Storm Ltd. +* @license https://github.com/photonstorm/phaser/blob/master/license.txt MIT License +* @module Phaser.Camera +*/ + +/** * * A Camera is your view into the game world. It has a position and size and renders only those objects within its field of view. * The game automatically creates a single Stage sized camera on boot. Move the camera around the world with Phaser.Camera.x/y * -* @class Phaser.Camera +* @class Camera * @constructor * @param {Phaser.Game} game game reference to the currently running game. * @param {number} id not being used at the moment, will be when Phaser supports multiple camera @@ -16,38 +22,60 @@ Phaser.Camera = function (game, id, x, y, width, height) { + /** + * A reference to the currently running Game. + * @property game + * @public + * @type {Phaser.Game} + */ this.game = game; + + /** + * A reference to the game world + * @property world + * @public + * @type {Phaser.World} + */ this.world = game.world; - this.id = 0; // reserved for future multiple camera set-ups - - // The view into the world we wish to render (by default the game dimensions) - // The x/y values are in world coordinates, not screen coordinates, the width/height is how many pixels to render - // Objects outside of this view are not rendered (unless set to ignore the Camera, i.e. UI?) + + /** + * reserved for future multiple camera set-ups + * @property id + * @public + * @type {number} + */ + this.id = 0; /** * Camera view. + * The view into the world we wish to render (by default the game dimensions) + * The x/y values are in world coordinates, not screen coordinates, the width/height is how many pixels to render + * Objects outside of this view are not rendered (unless set to ignore the Camera, i.e. UI?) * @property view - * @type {Rectangle} + * @public + * @type {Phaser.Rectangle} */ this.view = new Phaser.Rectangle(x, y, width, height); /** * Used by Sprites to work out Camera culling. * @property screenView - * @type {Rectangle} + * @public + * @type {Phaser.Rectangle} */ this.screenView = new Phaser.Rectangle(x, y, width, height); /** * Sprite moving inside this Rectangle will not cause camera moving. * @property deadzone - * @type {Rectangle} + * @type {Phaser.Rectangle} */ this.deadzone = null; /** * Whether this camera is visible or not. (default is true) * @property visible + * @public * @default true * @type {bool} */ @@ -63,10 +91,17 @@ Phaser.Camera = function (game, id, x, y, width, height) { /** * If the camera is tracking a Sprite, this is a reference to it, otherwise null * @property target - * @type {Sprite} + * @public + * @type {Phaser.Sprite} */ this.target = null; + /** + * Edge property + * @property edge + * @private + * @type {number} + */ this._edge = 0; }; @@ -82,7 +117,7 @@ Phaser.Camera.prototype = { /** * Tells this camera which sprite to follow. * @method follow - * @param target {Sprite} The object you want the camera to track. Set to null to not follow anything. + * @param target {Phaser.Sprite} The object you want the camera to track. Set to null to not follow anything. * @param [style] {number} Leverage one of the existing "deadzone" presets. If you use a custom deadzone, ignore this parameter and manually specify the deadzone after calling follow(). */ follow: function (target, style) { @@ -120,7 +155,7 @@ Phaser.Camera.prototype = { }, /** - * Move the camera focus to this location instantly. + * Move the camera focus to a location instantly. * @method focusOnXY * @param x {number} X position. * @param y {number} Y position. @@ -237,11 +272,11 @@ Phaser.Camera.prototype = { }, /** - * Sets the size of the view rectangle + * Sets the size of the view rectangle given the width and height in parameters * * @method setSize - * @param x {number} X position. - * @param y {number} Y position. + * @param width {number} the desired width. + * @param height {number} the desired height. */ setSize: function (width, height) { @@ -254,10 +289,17 @@ Phaser.Camera.prototype = { Object.defineProperty(Phaser.Camera.prototype, "x", { + /** + * @method x + * @return {Number} The x position + */ get: function () { return this.view.x; }, - + /** + * @method x + * @return {Number} Sets the camera's x position and clamp it if it's outside the world bounds + */ set: function (value) { this.view.x = value; this.checkWorldBounds(); @@ -267,10 +309,18 @@ Object.defineProperty(Phaser.Camera.prototype, "x", { Object.defineProperty(Phaser.Camera.prototype, "y", { + /** + * @method y + * @return {Number} The y position + */ get: function () { return this.view.y; }, + /** + * @method y + * @return {Number} Sets the camera's y position and clamp it if it's outside the world bounds + */ set: function (value) { this.view.y = value; this.checkWorldBounds(); @@ -280,10 +330,18 @@ Object.defineProperty(Phaser.Camera.prototype, "y", { Object.defineProperty(Phaser.Camera.prototype, "width", { + /** + * @method width + * @return {Number} The width of the view rectangle, in pixels + */ get: function () { return this.view.width; }, + /** + * @method width + * @return {Number} Sets the width of the view rectangle + */ set: function (value) { this.view.width = value; } @@ -292,10 +350,18 @@ Object.defineProperty(Phaser.Camera.prototype, "width", { Object.defineProperty(Phaser.Camera.prototype, "height", { + /** + * @method height + * @return {Number} The height of the view rectangle, in pixels + */ get: function () { return this.view.height; }, + /** + * @method height + * @return {Number} Sets the height of the view rectangle + */ set: function (value) { this.view.height = value; } diff --git a/src/core/Stage.js b/src/core/Stage.js index 5a4e07e6..eefe3ded 100644 --- a/src/core/Stage.js +++ b/src/core/Stage.js @@ -1,15 +1,15 @@ /** - * Stage - * - * The Stage controls the canvas on which everything is displayed. It handles display within the browser, - * focus handling, game resizing, scaling and the pause, boot and orientation screens. - * - * @package Phaser.Stage - * @author Richard Davey - * @copyright 2013 Photon Storm Ltd. - * @license https://github.com/photonstorm/phaser/blob/master/license.txt MIT License - +* @author Richard Davey +* @copyright 2013 Photon Storm Ltd. +* @license https://github.com/photonstorm/phaser/blob/master/license.txt MIT License +* @module Phaser.Stage +*/ +/** +* +* The Stage controls the canvas on which everything is displayed. It handles display within the browser, +* focus handling, game resizing, scaling and the pause, boot and orientation screens. +* * @class Stage * @constructor * @param game {Phaser.Game} game reference to the currently running game. @@ -17,33 +17,81 @@ * @param height {number} height of the canvas element */ Phaser.Stage = function (game, width, height) { - + + /** + * A reference to the currently running Game. + * @property game + * @public + * @type {Phaser.Game} + */ this.game = game; /** * Background color of the stage (defaults to black). Set via the public backgroundColor property. + * @property _backgroundColor + * @private * @type {string} */ this._backgroundColor = 'rgb(0,0,0)'; - // Get the offset values (for input and other things) + /** + * Get the offset values (for input and other things) + * @property offset + * @public + * @type {Phaser.Point} + */ this.offset = new Phaser.Point; - + + /** + * reference to the newly created element + * @property canvas + * @public + * @type {HTMLCanvasElement} + */ this.canvas = Phaser.Canvas.create(width, height); this.canvas.style['-webkit-full-screen'] = 'width: 100%; height: 100%'; - - // The Pixi Stage which is hooked to the renderer + + /** + * The Pixi Stage which is hooked to the renderer + * @property _stage + * @private + * @type {PIXI.Stage} + */ this._stage = new PIXI.Stage(0x000000, false); this._stage.name = '_stage_root'; - + + /** + * The current scaleMode + * @property scaleMode + * @public + * @type {Phaser.StageScaleMode} + */ this.scaleMode = Phaser.StageScaleMode.NO_SCALE; + + /** + * The scale of the current running game + * @property scale + * @public + * @type {Phaser.StageScaleMode} + */ this.scale = new Phaser.StageScaleMode(this.game, width, height); + + /** + * aspect ratio + * @property aspectRatio + * @public + * @type {number} + */ this.aspectRatio = width / height; }; Phaser.Stage.prototype = { + /** + * Initialises the stage and adds the event listeners + * @method boot + */ boot: function () { Phaser.Canvas.getOffset(this.canvas, this.offset); @@ -68,6 +116,8 @@ Phaser.Stage.prototype = { /** * This method is called when the document visibility is changed. + * @method visibilityChange + * @param event [Event] its type will be used to decide whether the game should be paused or not */ visibilityChange: function (event) { @@ -93,10 +143,19 @@ Phaser.Stage.prototype = { Object.defineProperty(Phaser.Stage.prototype, "backgroundColor", { + /** + * @method backgroundColor + * @return {string} returns the background color of the stage + */ get: function () { return this._backgroundColor; }, + /** + * @method backgroundColor + * @param {string} the background color you want the stage to have + * @return {string} returns the background color of the stage + */ set: function (color) { this._backgroundColor = color; diff --git a/src/core/World.js b/src/core/World.js index 36319967..a0e79906 100644 --- a/src/core/World.js +++ b/src/core/World.js @@ -1,5 +1,11 @@ /** - * World +* @author Richard Davey +* @copyright 2013 Photon Storm Ltd. +* @license https://github.com/photonstorm/phaser/blob/master/license.txt MIT License +* @module Phaser.World +*/ + +/** * * "This world is but a canvas to our imagination." - Henry David Thoreau * @@ -7,11 +13,6 @@ * by stage limits and can be any size. You look into the world via cameras. All game objects live within * the world at world-based coordinates. By default a world is created the same size as your Stage. * - * @package Phaser.World - * @author Richard Davey - * @copyright 2013 Photon Storm Ltd. - * @license https://github.com/photonstorm/phaser/blob/master/license.txt MIT License - * @class World * @constructor * @param game {Phaser.Game} reference to the current game instance. @@ -19,38 +20,55 @@ Phaser.World = function (game) { /** - * Local reference to Game. - */ + * A reference to the currently running Game. + * @property game + * @public + * @type {Phaser.Game} + */ this.game = game; /** - * Bound of this world that objects can not escape from. - * @type {Rectangle} - */ + * Bound of this world that objects can not escape from. + * @property bounds + * @public + * @type {Phaser.Rectangle} + */ this.bounds = new Phaser.Rectangle(0, 0, game.width, game.height); /** - * Camera instance. - * @type {Camera} - */ + * Camera instance. + * @property camera + * @public + * @type {Phaser.Camera} + */ this.camera = null; /** - * Reset each frame, keeps a count of the total number of objects updated. - * @type {Number} - */ + * Reset each frame, keeps a count of the total number of objects updated. + * @property currentRenderOrderID + * @public + * @type {Number} + */ this.currentRenderOrderID = 0; /** - * Object container stores every object created with `create*` methods. - * @type {Group} - */ + * Object container stores every object created with `create*` methods. + * @property group + * @public + * @type {Phaser.Group} + */ this.group = null; }; Phaser.World.prototype = { + + /** + * Initialises the game world + * + * @method boot + */ boot: function () { this.camera = new Phaser.Camera(this.game, 0, 0, 0, this.game.width, this.game.height); @@ -62,8 +80,9 @@ Phaser.World.prototype = { }, /** - * This is called automatically every frame, and is where main logic happens. - */ + * This is called automatically every frame, and is where main logic happens. + * @method update + */ update: function () { this.camera.update(); @@ -134,10 +153,18 @@ Phaser.World.prototype = { Object.defineProperty(Phaser.World.prototype, "width", { + /** + * @method width + * @return {Number} The current width of the game world + */ get: function () { return this.bounds.width; }, + /** + * @method width + * @return {Number} Sets the width of the game world + */ set: function (value) { this.bounds.width = value; } @@ -146,10 +173,18 @@ Object.defineProperty(Phaser.World.prototype, "width", { Object.defineProperty(Phaser.World.prototype, "height", { + /** + * @method height + * @return {Number} The current height of the game world + */ get: function () { return this.bounds.height; }, + /** + * @method height + * @return {Number} Sets the width of the game world + */ set: function (value) { this.bounds.height = value; } @@ -158,6 +193,10 @@ Object.defineProperty(Phaser.World.prototype, "height", { Object.defineProperty(Phaser.World.prototype, "centerX", { + /** + * @method centerX + * @return {Number} return the X position of the center point of the world + */ get: function () { return this.bounds.halfWidth; } @@ -166,6 +205,10 @@ Object.defineProperty(Phaser.World.prototype, "centerX", { Object.defineProperty(Phaser.World.prototype, "centerY", { + /** + * @method centerY + * @return {Number} return the Y position of the center point of the world + */ get: function () { return this.bounds.halfHeight; } @@ -174,6 +217,10 @@ Object.defineProperty(Phaser.World.prototype, "centerY", { Object.defineProperty(Phaser.World.prototype, "randomX", { + /** + * @method randomX + * @return {Number} a random integer which is lesser or equal to the current width of the game world + */ get: function () { return Math.round(Math.random() * this.bounds.width); } @@ -182,6 +229,10 @@ Object.defineProperty(Phaser.World.prototype, "randomX", { Object.defineProperty(Phaser.World.prototype, "randomY", { + /** + * @method randomY + * @return {Number} a random integer which is lesser or equal to the current height of the game world + */ get: function () { return Math.round(Math.random() * this.bounds.height); } diff --git a/src/gameobjects/Button.js b/src/gameobjects/Button.js index 9aea5634..b5335152 100644 --- a/src/gameobjects/Button.js +++ b/src/gameobjects/Button.js @@ -1,3 +1,10 @@ +/** +* @author Richard Davey +* @copyright 2013 Photon Storm Ltd. +* @license https://github.com/photonstorm/phaser/blob/master/license.txt MIT License +* @module Phaser.Button +*/ + /** * Create a new Button object. * @class Button @@ -15,6 +22,7 @@ */ Phaser.Button = function (game, x, y, key, callback, callbackContext, overFrame, outFrame, downFrame) { + x = x || 0; y = y || 0; key = key || null; @@ -69,7 +77,6 @@ Phaser.Button.prototype.constructor = Phaser.Button; * @param [outFrame] {string|number} This is the frame or frameName that will be set when this button is in an out state. Give either a number to use a frame ID or a string for a frame name. * @param [downFrame] {string|number} This is the frame or frameName that will be set when this button is in a down state. Give either a number to use a frame ID or a string for a frame name. */ - Phaser.Button.prototype.setFrames = function (overFrame, outFrame, downFrame) { if (overFrame !== null)