Completing Game Object jsdocs

Author: photonstorm

src/gameobjects/bitmaptext/dynamic/DynamicBitmapText.js

@@ -31,7 +31,31 @@ var Render = require('./DynamicBitmapTextRender');
 
 /**
  * @classdesc
- * [description]
+ * BitmapText objects work by taking a texture file and an XML or JSON file that describes the font structure.
+ * 
+ * During rendering for each letter of the text is rendered to the display, proportionally spaced out and aligned to
+ * match the font structure.
+ * 
+ * Dynamic Bitmap Text objects are different from Static Bitmap Text in that they invoke a callback for each
+ * letter being rendered during the render pass. This callback allows you to manipulate the properties of
+ * each letter being rendered, such as its position, scale or tint, allowing you to create interesting effects
+ * like jiggling text, which can't be done with Static text. This means that Dynamic Text takes more processing
+ * time, so only use them if you require the callback ability they have.
+ *
+ * BitmapText objects are less flexible than Text objects, in that they have less features such as shadows, fills and the ability
+ * to use Web Fonts, however you trade this flexibility for rendering speed. You can also create visually compelling BitmapTexts by
+ * processing the font texture in an image editor, applying fills and any other effects required.
+ *
+ * To create multi-line text insert \r, \n or \r\n escape codes into the text string.
+ *
+ * To create a BitmapText data files you need a 3rd party app such as:
+ *
+ * BMFont (Windows, free): http://www.angelcode.com/products/bmfont/
+ * Glyph Designer (OS X, commercial): http://www.71squared.com/en/glyphdesigner
+ * Littera (Web-based, free): http://kvazars.com/littera/
+ *
+ * For most use cases it is recommended to use XML. If you wish to use JSON, the formatting should be equal to the result of
+ * converting a valid XML file through the popular X2JS library. An online tool for conversion can be found here: http://codebeautify.org/xmltojson
  *
  * @class DynamicBitmapText
  * @extends Phaser.GameObjects.BitmapText

src/gameobjects/bitmaptext/dynamic/DynamicBitmapTextFactory.js

@@ -9,6 +9,32 @@ var GameObjectFactory = require('../../GameObjectFactory');
 
 /**
  * Creates a new Dynamic Bitmap Text Game Object and adds it to the Scene.
+ * 
+ * BitmapText objects work by taking a texture file and an XML or JSON file that describes the font structure.
+ * 
+ * During rendering for each letter of the text is rendered to the display, proportionally spaced out and aligned to
+ * match the font structure.
+ * 
+ * Dynamic Bitmap Text objects are different from Static Bitmap Text in that they invoke a callback for each
+ * letter being rendered during the render pass. This callback allows you to manipulate the properties of
+ * each letter being rendered, such as its position, scale or tint, allowing you to create interesting effects
+ * like jiggling text, which can't be done with Static text. This means that Dynamic Text takes more processing
+ * time, so only use them if you require the callback ability they have.
+ *
+ * BitmapText objects are less flexible than Text objects, in that they have less features such as shadows, fills and the ability
+ * to use Web Fonts, however you trade this flexibility for rendering speed. You can also create visually compelling BitmapTexts by
+ * processing the font texture in an image editor, applying fills and any other effects required.
+ *
+ * To create multi-line text insert \r, \n or \r\n escape codes into the text string.
+ *
+ * To create a BitmapText data files you need a 3rd party app such as:
+ *
+ * BMFont (Windows, free): http://www.angelcode.com/products/bmfont/
+ * Glyph Designer (OS X, commercial): http://www.71squared.com/en/glyphdesigner
+ * Littera (Web-based, free): http://kvazars.com/littera/
+ *
+ * For most use cases it is recommended to use XML. If you wish to use JSON, the formatting should be equal to the result of
+ * converting a valid XML file through the popular X2JS library. An online tool for conversion can be found here: http://codebeautify.org/xmltojson
  *
  * Note: This method will only be available if the Dynamic Bitmap Text Game Object has been built into Phaser.
  *

src/gameobjects/bitmaptext/static/BitmapText.js

@@ -55,7 +55,25 @@ var Render = require('./BitmapTextRender');
 
 /**
  * @classdesc
- * [description]
+ * BitmapText objects work by taking a texture file and an XML or JSON file that describes the font structure.
+ * 
+ * During rendering for each letter of the text is rendered to the display, proportionally spaced out and aligned to
+ * match the font structure.
+ *
+ * BitmapText objects are less flexible than Text objects, in that they have less features such as shadows, fills and the ability
+ * to use Web Fonts, however you trade this flexibility for rendering speed. You can also create visually compelling BitmapTexts by
+ * processing the font texture in an image editor, applying fills and any other effects required.
+ *
+ * To create multi-line text insert \r, \n or \r\n escape codes into the text string.
+ *
+ * To create a BitmapText data files you need a 3rd party app such as:
+ *
+ * BMFont (Windows, free): http://www.angelcode.com/products/bmfont/
+ * Glyph Designer (OS X, commercial): http://www.71squared.com/en/glyphdesigner
+ * Littera (Web-based, free): http://kvazars.com/littera/
+ *
+ * For most use cases it is recommended to use XML. If you wish to use JSON, the formatting should be equal to the result of
+ * converting a valid XML file through the popular X2JS library. An online tool for conversion can be found here: http://codebeautify.org/xmltojson
  *
  * @class BitmapText
  * @extends Phaser.GameObjects.GameObject

src/gameobjects/bitmaptext/static/BitmapTextFactory.js

@@ -9,6 +9,26 @@ var GameObjectFactory = require('../../GameObjectFactory');
 
 /**
  * Creates a new Bitmap Text Game Object and adds it to the Scene.
+ * 
+ * BitmapText objects work by taking a texture file and an XML or JSON file that describes the font structure.
+ * 
+ * During rendering for each letter of the text is rendered to the display, proportionally spaced out and aligned to
+ * match the font structure.
+ * 
+ * BitmapText objects are less flexible than Text objects, in that they have less features such as shadows, fills and the ability
+ * to use Web Fonts, however you trade this flexibility for rendering speed. You can also create visually compelling BitmapTexts by
+ * processing the font texture in an image editor, applying fills and any other effects required.
+ *
+ * To create multi-line text insert \r, \n or \r\n escape codes into the text string.
+ *
+ * To create a BitmapText data files you need a 3rd party app such as:
+ *
+ * BMFont (Windows, free): http://www.angelcode.com/products/bmfont/
+ * Glyph Designer (OS X, commercial): http://www.71squared.com/en/glyphdesigner
+ * Littera (Web-based, free): http://kvazars.com/littera/
+ *
+ * For most use cases it is recommended to use XML. If you wish to use JSON, the formatting should be equal to the result of
+ * converting a valid XML file through the popular X2JS library. An online tool for conversion can be found here: http://codebeautify.org/xmltojson
  *
  * Note: This method will only be available if the Bitmap Text Game Object has been built into Phaser.
  *

src/gameobjects/shape/arc/Arc.js

@@ -14,6 +14,21 @@ var Shape = require('../Shape');
 
 /**
  * @classdesc
+ * The Arc Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * When it renders it displays an arc shape. You can control the start and end angles of the arc,
+ * as well as if the angles are winding clockwise or anti-clockwise. With the default settings
+ * it renders as a complete circle. By changing the angles you can create other arc shapes,
+ * such as half-circles.
+ * 
+ * Arcs also have an `iterations` property and corresponding `setIterations` method. This allows
+ * you to control how smooth the shape renders in WebGL, by controlling the number of iterations
+ * that take place during construction.
  *
  * @class Arc
  * @extends Phaser.GameObjects.Shape

src/gameobjects/shape/arc/ArcFactory.js

@@ -11,6 +11,18 @@ var GameObjectFactory = require('../../GameObjectFactory');
  * Creates a new Arc Shape Game Object and adds it to the Scene.
  *
  * Note: This method will only be available if the Arc Game Object has been built into Phaser.
+ * 
+ * The Arc Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * When it renders it displays an arc shape. You can control the start and end angles of the arc,
+ * as well as if the angles are winding clockwise or anti-clockwise. With the default settings
+ * it renders as a complete circle. By changing the angles you can create other arc shapes,
+ * such as half-circles.
  *
  * @method Phaser.GameObjects.GameObjectFactory#arc
  * @since 3.13.0

src/gameobjects/shape/ellipse/Ellipse.js

@@ -12,6 +12,21 @@ var Shape = require('../Shape');
 
 /**
  * @classdesc
+ * The Ellipse Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * When it renders it displays an ellipse shape. You can control the width and height of the ellipse.
+ * If the width and height match it will render as a circle. If the width is less than the height,
+ * it will look more like an egg shape.
+ * 
+ * The Ellipse shape also has a `smoothness` property and corresponding `setSmoothness` method.
+ * This allows you to control how smooth the shape renders in WebGL, by controlling the number of iterations
+ * that take place during construction. Increase and decrease the default value for smoother, or more
+ * jagged, shapes.
  *
  * @class Ellipse
  * @extends Phaser.GameObjects.Shape

src/gameobjects/shape/ellipse/EllipseFactory.js

@@ -11,6 +11,22 @@ var GameObjectFactory = require('../../GameObjectFactory');
  * Creates a new Ellipse Shape Game Object and adds it to the Scene.
  *
  * Note: This method will only be available if the Ellipse Game Object has been built into Phaser.
+ * 
+ * The Ellipse Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * When it renders it displays an ellipse shape. You can control the width and height of the ellipse.
+ * If the width and height match it will render as a circle. If the width is less than the height,
+ * it will look more like an egg shape.
+ * 
+ * The Ellipse shape also has a `smoothness` property and corresponding `setSmoothness` method.
+ * This allows you to control how smooth the shape renders in WebGL, by controlling the number of iterations
+ * that take place during construction. Increase and decrease the default value for smoother, or more
+ * jagged, shapes.
  *
  * @method Phaser.GameObjects.GameObjectFactory#ellipse
  * @since 3.13.0

src/gameobjects/text/static/Text.js

@@ -18,7 +18,28 @@ var TextStyle = require('../TextStyle');
 
 /**
  * @classdesc
- * [description]
+ * A Text Game Object.
+ * 
+ * Text objects work by creating their own internal hidden Canvas and then renders text to it using
+ * the standard Canvas `fillText` API. It then creates a texture from this canvas which is rendered
+ * to your game during the render pass.
+ * 
+ * Because it uses the Canvas API you can take advantage of all the features this offers, such as
+ * applying gradient fills to the text, or strokes, shadows and more. You can also use custom fonts
+ * loaded externally, such as Google or TypeKit Web fonts.
+ *
+ * You can only display fonts that are currently loaded and available to the browser: therefore fonts must
+ * be pre-loaded. Phaser does not do ths for you, so you will require the use of a 3rd party font loader,
+ * or have the fonts ready available in the CSS on the page in which your Phaser game resides.
+ *
+ * See {@link http://www.jordanm.co.uk/tinytype this compatibility table} for the available default fonts
+ * across mobile browsers.
+ * 
+ * A note on performance: Every time the contents of a Text object changes, i.e. changing the text being
+ * displayed, or the style of the text, it needs to remake the Text canvas, and if on WebGL, re-upload the
+ * new texture to the GPU. This can be an expensive operation if used often, or with large quantities of
+ * Text objects in your game. If you run into performance issues you would be better off using Bitmap Text
+ * instead, as it benefits from batching and avoids expensive Canvas API calls.
  *
  * @class Text
  * @extends Phaser.GameObjects.GameObject

src/gameobjects/text/static/TextFactory.js

@@ -9,6 +9,29 @@ var GameObjectFactory = require('../../GameObjectFactory');
 
 /**
  * Creates a new Text Game Object and adds it to the Scene.
+ * 
+ * A Text Game Object.
+ * 
+ * Text objects work by creating their own internal hidden Canvas and then renders text to it using
+ * the standard Canvas `fillText` API. It then creates a texture from this canvas which is rendered
+ * to your game during the render pass.
+ * 
+ * Because it uses the Canvas API you can take advantage of all the features this offers, such as
+ * applying gradient fills to the text, or strokes, shadows and more. You can also use custom fonts
+ * loaded externally, such as Google or TypeKit Web fonts.
+ *
+ * You can only display fonts that are currently loaded and available to the browser: therefore fonts must
+ * be pre-loaded. Phaser does not do ths for you, so you will require the use of a 3rd party font loader,
+ * or have the fonts ready available in the CSS on the page in which your Phaser game resides.
+ *
+ * See {@link http://www.jordanm.co.uk/tinytype this compatibility table} for the available default fonts
+ * across mobile browsers.
+ * 
+ * A note on performance: Every time the contents of a Text object changes, i.e. changing the text being
+ * displayed, or the style of the text, it needs to remake the Text canvas, and if on WebGL, re-upload the
+ * new texture to the GPU. This can be an expensive operation if used often, or with large quantities of
+ * Text objects in your game. If you run into performance issues you would be better off using Bitmap Text
+ * instead, as it benefits from batching and avoids expensive Canvas API calls.
  *
  * Note: This method will only be available if the Text Game Object has been built into Phaser.
  *