diff --git a/src/components/GameObjects.ts b/src/components/GameObjects.ts index df0d185c..e84dbfc7 100644 --- a/src/components/GameObjects.ts +++ b/src/components/GameObjects.ts @@ -4,31 +4,21 @@ import type { FC } from 'react'; import type { GameObjectProps as Props } from '../types'; /** - * 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. + * 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. * - * To create a BitmapText data files you need a 3rd party app such as: + * This shape supports both fill and stroke colors. * - * 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/ + * 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. * - * 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 + * 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. */ -export const BitmapText = GameObjects.BitmapText as unknown as FC< - Props ->; +export const Arc = GameObjects.Arc as unknown as FC>; /** * 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. @@ -39,8 +29,8 @@ export const BitmapText = GameObjects.BitmapText as unknown as FC< * * 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 */ -export const DynamicBitmapText = GameObjects.DynamicBitmapText as unknown as FC< - Props +export const BitmapText = GameObjects.BitmapText as unknown as FC< + Props >; /** @@ -98,6 +88,19 @@ export const Container = GameObjects.Container as unknown as FC< Props >; +/** + * The Curve 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. + * + * To render a Curve Shape you must first create a Phaser.Curves.Curve object, then pass it to the Curve Shape in the constructor. + * + * The Curve 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. + */ +export const Curve = GameObjects.Curve as unknown as FC< + Props +>; + /** * DOM Element Game Objects are a way to control and manipulate HTML Elements over the top of your game. * @@ -140,6 +143,40 @@ export const DOMElement = GameObjects.DOMElement as unknown as FC< Props >; +/** + * 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 + */ +export const DynamicBitmapText = GameObjects.DynamicBitmapText as unknown as FC< + Props +>; + +/** + * 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. + */ +export const Ellipse = GameObjects.Ellipse as unknown as FC< + Props +>; + /** * An Extern Game Object is a special type of Game Object that allows you to pass rendering off to a 3rd party. * @@ -186,6 +223,15 @@ export const Graphics = GameObjects.Graphics as unknown as FC< Props >; +/** + * The Grid 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 only fill colors and cannot be stroked. + * + * A Grid Shape allows you to display a grid in your game, where you can control the size of the grid as well as the width and height of the grid cells. You can set a fill color for each grid cell as well as an alternate fill color. When the alternate fill color is set then the grid cells will alternate the fill colors as they render, creating a chess-board effect. You can also optionally have an outline fill color. If set, this draws lines between the grid cells in the given color. If you specify an outline color with an alpha of zero, then it will draw the cells spaced out, but without the lines between them. + */ +export const Grid = GameObjects.Grid as unknown as FC>; + /** * A Group is a way for you to create, manipulate, or recycle similar Game Objects. * @@ -206,6 +252,32 @@ export const Image = GameObjects.Image as unknown as FC< Props >; +/** + * The IsoBox 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 only fill colors and cannot be stroked. + * + * An IsoBox is an 'isometric' rectangle. Each face of it has a different fill color. You can set the color of the top, left and right faces of the rectangle respectively. You can also choose which of the faces are rendered via the showTop, showLeft and showRight properties. + * + * You cannot view an IsoBox from under-neath, however you can change the 'angle' by setting the projection property. + */ +export const IsoBox = GameObjects.IsoBox as unknown as FC< + Props +>; + +/** + * The IsoTriangle 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 only fill colors and cannot be stroked. + * + * An IsoTriangle is an 'isometric' triangle. Think of it like a pyramid. Each face has a different fill color. You can set the color of the top, left and right faces of the triangle respectively You can also choose which of the faces are rendered via the showTop, showLeft and showRight properties. + * + * You cannot view an IsoTriangle from under-neath, however you can change the 'angle' by setting the projection property. The reversed property controls if the IsoTriangle is rendered upside down or not. + */ +export const IsoTriangle = GameObjects.IsoTriangle as unknown as FC< + Props +>; + /** * A Layer Game Object. * @@ -240,241 +312,159 @@ export const Layer = GameObjects.Layer as unknown as FC< >; /** - * A particle emitter represents a single particle stream. It controls a pool of Particles and is controlled by a Particle Emitter Manager. + * A Scene plugin that provides a Phaser.GameObjects.LightsManager for the Light2D pipeline. */ -export const ParticleEmitter = GameObjects.Particles - .ParticleEmitter as unknown as FC< - Props +export const Light = GameObjects.Light as unknown as FC< + Props >; /** - * A PathFollower Game Object. + * The Line 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. * - * A PathFollower is a Sprite Game Object with some extra helpers to allow it to follow a Path automatically. + * This shape supports only stroke colors and cannot be filled. * - * Anything you can do with a standard Sprite can be done with this PathFollower, such as animate it, tint it, scale it and so on. + * A Line Shape allows you to draw a line between two points in your game. You can control the stroke color and thickness of the line. In WebGL only you can also specify a different thickness for the start and end of the line, allowing you to render lines that taper-off. * - * PathFollowers are bound to a single Path at any one time and can traverse the length of the Path, from start to finish, forwards or backwards, or from any given point on the Path to its end. They can optionally rotate to face the direction of the path, be offset from the path coordinates or rotate independently of the Path. + * If you need to draw multiple lines in a sequence you may wish to use the Polygon Shape instead. + * + * Be aware that as with all Game Objects the default origin is 0.5. If you need to draw a Line between two points and want the x1/y1 values to match the x/y values, then set the origin to 0. */ -export const PathFollower = GameObjects.PathFollower as unknown as FC< - Props ->; +export const Line = GameObjects.Line as unknown as FC>; /** - * The Point Light Game Object provides a way to add a point light effect into your game, without the expensive shader processing requirements of the traditional Light Game Object. + * A Mesh Game Object. * - * The difference is that the Point Light renders using a custom shader, designed to give the impression of a point light source, of variable radius, intensity and color, in your game. However, unlike the Light Game Object, it does not impact any other Game Objects, or use their normal maps for calcuations. This makes them extremely fast to render compared to Lights and perfect for special effects, such as flickering torches or muzzle flashes. + * The Mesh Game Object allows you to render a group of textured vertices and manipulate the view of those vertices, such as rotation, translation or scaling. * - * For maximum performance you should batch Point Light Game Objects together. This means ensuring they follow each other consecutively on the display list. Ideally, use a Layer Game Object and then add just Point Lights to it, so that it can batch together the rendering of the lights. You don't have to do this, and if you've only a handful of Point Lights in your game then it's perfectly safe to mix them into the dislay list as normal. However, if you're using a large number of them, please consider how they are mixed into the display list. + * Support for generating mesh data from grids, model data or Wavefront OBJ Files is included. * - * The renderer will automatically cull Point Lights. Those with a radius that does not intersect with the Camera will be skipped in the rendering list. This happens automatically and the culled state is refreshed every frame, for every camera. + * Although you can use this to render 3D objects, its primary use is for displaying more complex Sprites, or Sprites where you need fine-grained control over the vertice positions in order to achieve special effects in your games. Note that rendering still takes place using Phasers orthographic camera. As a result, all depth and face tests are done in orthographic space. * - * The origin of a Point Light is always 0.5 and it cannot be changed. + * The rendering process will iterate through the faces of this Mesh and render out each face that is considered as being in view of the camera. No depth buffer is used, and because of this, you should be careful not to use model data with too many vertices, or overlapping geometry, or you'll probably encounter z-depth fighting. The Mesh was designed to allow for more advanced 2D layouts, rather than displaying 3D objects, even though it can do this to a degree. * - * Point Lights are a WebGL only feature and do not have a Canvas counterpart. - */ -export const PointLight = GameObjects.PointLight as unknown as FC< - Props ->; - -/** - * A Render Texture. + * In short, if you want to remake Crysis, use a 3D engine, not a Mesh. However, if you want to easily add some small fun 3D elements into your game, or create some special effects involving vertex warping, this is the right object for you. Mesh data becomes part of the WebGL batch, just like standard Sprites, so doesn't introduce any additional shader overhead. Because the Mesh just generates vertices into the WebGL batch, like any other Sprite, you can use all of the common Game Object components on a Mesh too, such as a custom pipeline, mask, blend mode or texture. * - * A Render Texture is a special texture that allows any number of Game Objects to be drawn to it. You can take many complex objects and draw them all to this one texture, which can they be used as the texture for other Game Object's. It's a way to generate dynamic textures at run-time that are WebGL friendly and don't invoke expensive GPU uploads. + * Note that the Mesh object is WebGL only and does not have a Canvas counterpart. * - * Note that under WebGL a FrameBuffer, which is what the Render Texture uses internally, cannot be anti-aliased. This means that when drawing objects such as Shapes to a Render Texture they will appear to be drawn with no aliasing, however this is a technical limitation of WebGL. To get around it, create your shape as a texture in an art package, then draw that to the Render Texture. + * The Mesh origin is always 0.5 x 0.5 and cannot be changed. */ -export const RenderTexture = GameObjects.RenderTexture as unknown as FC< - Props ->; +export const Mesh = GameObjects.Mesh as unknown as FC>; /** - * The Shape Game Object is a base class for the various different shapes, such as the Arc, Star or Polygon. You cannot add a Shape directly to your Scene, it is meant as a base for your own custom Shape classes. + * A particle emitter represents a single particle stream. It controls a pool of Particles and is controlled by a Particle Emitter Manager. */ -export const Shape = GameObjects.Shape as unknown as FC< - Props +export const ParticleEmitter = GameObjects.Particles + .ParticleEmitter as unknown as FC< + Props >; /** - * A Sprite Game Object. + * A PathFollower Game Object. * - * A Sprite Game Object is used for the display of both static and animated images in your game. Sprites can have input events and physics bodies. They can also be tweened, tinted, scrolled and animated. + * A PathFollower is a Sprite Game Object with some extra helpers to allow it to follow a Path automatically. * - * The main difference between a Sprite and an Image Game Object is that you cannot animate Images. As such, Sprites take a fraction longer to process and have a larger API footprint due to the Animation Component. If you do not require animation then you can safely use Images to replace Sprites in all cases. + * Anything you can do with a standard Sprite can be done with this PathFollower, such as animate it, tint it, scale it and so on. + * + * PathFollowers are bound to a single Path at any one time and can traverse the length of the Path, from start to finish, forwards or backwards, or from any given point on the Path to its end. They can optionally rotate to face the direction of the path, be offset from the path coordinates or rotate independently of the Path. */ -export const Sprite = GameObjects.Sprite as unknown as FC< - Props +export const PathFollower = GameObjects.PathFollower as unknown as FC< + Props >; /** - * 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. - * - * Important: The font name must be quoted if it contains certain combinations of digits or special characters, either when creating the Text object, or when setting the font via setFont or setFontFamily, e.g.: - * - * ```js - * this.add.text(0, 0, 'Hello World', { fontFamily: 'Georgia, "Goudy Bookletter 1911", Times, serif' }); - * ``` - * - * ```js - * this.add.text(0, 0, 'Hello World', { font: '"Press Start 2P"' }); - * ``` - * - * 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 this compatibility table for the available default fonts across mobile browsers. + * The Point Light Game Object provides a way to add a point light effect into your game, without the expensive shader processing requirements of the traditional Light Game Object. * - * 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. - */ -export const Text = GameObjects.Text as unknown as FC>; - -/** - * A TileSprite is a Sprite that has a repeating texture. + * The difference is that the Point Light renders using a custom shader, designed to give the impression of a point light source, of variable radius, intensity and color, in your game. However, unlike the Light Game Object, it does not impact any other Game Objects, or use their normal maps for calcuations. This makes them extremely fast to render compared to Lights and perfect for special effects, such as flickering torches or muzzle flashes. * - * The texture can be scrolled and scaled independently of the TileSprite itself. Textures will automatically wrap and are designed so that you can create game backdrops using seamless textures as a source. + * For maximum performance you should batch Point Light Game Objects together. This means ensuring they follow each other consecutively on the display list. Ideally, use a Layer Game Object and then add just Point Lights to it, so that it can batch together the rendering of the lights. You don't have to do this, and if you've only a handful of Point Lights in your game then it's perfectly safe to mix them into the dislay list as normal. However, if you're using a large number of them, please consider how they are mixed into the display list. * - * You shouldn't ever create a TileSprite any larger than your actual canvas size. If you want to create a large repeating background that scrolls across the whole map of your game, then you create a TileSprite that fits the canvas size and then use the tilePosition property to scroll the texture as the player moves. If you create a TileSprite that is thousands of pixels in size then it will consume huge amounts of memory and cause performance issues. Remember: use tilePosition to scroll your texture and tileScale to adjust the scale of the texture - don't resize the sprite itself or make it larger than it needs. + * The renderer will automatically cull Point Lights. Those with a radius that does not intersect with the Camera will be skipped in the rendering list. This happens automatically and the culled state is refreshed every frame, for every camera. * - * An important note about Tile Sprites and NPOT textures: Internally, TileSprite textures use GL_REPEAT to provide seamless repeating of the textures. This, combined with the way in which the textures are handled in WebGL, means they need to be POT (power-of-two) sizes in order to wrap. If you provide a NPOT (non power-of-two) texture to a TileSprite it will generate a POT sized canvas and draw your texture to it, scaled up to the POT size. It's then scaled back down again during rendering to the original dimensions. While this works, in that it allows you to use any size texture for a Tile Sprite, it does mean that NPOT textures are going to appear anti-aliased when rendered, due to the interpolation that took place when it was resized into a POT texture. This is especially visible in pixel art graphics. If you notice it and it becomes an issue, the only way to avoid it is to ensure that you provide POT textures for Tile Sprites. - */ -export const TileSprite = GameObjects.TileSprite as unknown as FC< - Props ->; - -/** - * A Video Game Object. + * The origin of a Point Light is always 0.5 and it cannot be changed. * - * This Game Object is capable of handling playback of a previously loaded video from the Phaser Video Cache, or playing a video based on a given URL. Videos can be either local, or streamed. + * Point Lights are a WebGL only feature and do not have a Canvas counterpart. */ -export const Video = GameObjects.Video as unknown as FC< - Props +export const PointLight = GameObjects.PointLight as unknown as FC< + Props >; /** - * A Zone Game Object. - * - * A Zone is a non-rendering rectangular Game Object that has a position and size. It has no texture and never displays, but does live on the display list and can be moved, scaled and rotated like any other Game Object. - * - * Its primary use is for creating Drop Zones and Input Hit Areas and it has a couple of helper methods specifically for this. It is also useful for object overlap checks, or as a base for your own non-displaying Game Objects. The default origin is 0.5, the center of the Zone, the same as with Game Objects. - */ -export const Zone = GameObjects.Zone as unknown as FC>; - -/** - * 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. + * The Polygon 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. - */ -export const Arc = GameObjects.Arc as unknown as FC>; - -/** - * The Curve 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. + * The Polygon Shape is created by providing a list of points, which are then used to create an internal Polygon geometry object. The points can be set from a variety of formats: * - * To render a Curve Shape you must first create a Phaser.Curves.Curve object, then pass it to the Curve Shape in the constructor. + * - A string containing paired values separated by a single space: '40 0 40 20 100 20 100 80 40 80 40 100 0 50' + * - An array of Point or Vector2 objects: [new Phaser.Math.Vector2(x1, y1), ...] + * - An array of objects with public x/y properties: [obj1, obj2, ...] + * - An array of paired numbers that represent point coordinates: [x1,y1, x2,y2, ...] + * - An array of arrays with two elements representing x/y coordinates: [[x1, y1], [x2, y2], ...] * - * The Curve 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. + * By default the x and y coordinates of this Shape refer to the center of it. However, depending on the coordinates of the points provided, the final shape may be rendered offset from its origin. */ -export const Curve = GameObjects.Curve as unknown as FC< - Props +export const Polygon = GameObjects.Polygon as unknown as FC< + Props >; /** - * 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. + * The Rectangle 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. + * You can change the size of the rectangle by changing the `width` and `height` properties. */ -export const Ellipse = GameObjects.Ellipse as unknown as FC< - Props +export const Rectangle = GameObjects.Rectangle as unknown as FC< + Props >; /** - * The Grid 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 only fill colors and cannot be stroked. - * - * A Grid Shape allows you to display a grid in your game, where you can control the size of the grid as well as the width and height of the grid cells. You can set a fill color for each grid cell as well as an alternate fill color. When the alternate fill color is set then the grid cells will alternate the fill colors as they render, creating a chess-board effect. You can also optionally have an outline fill color. If set, this draws lines between the grid cells in the given color. If you specify an outline color with an alpha of zero, then it will draw the cells spaced out, but without the lines between them. - */ -export const Grid = GameObjects.Grid as unknown as FC>; - -/** - * The IsoBox 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 only fill colors and cannot be stroked. + * A Render Texture. * - * An IsoBox is an 'isometric' rectangle. Each face of it has a different fill color. You can set the color of the top, left and right faces of the rectangle respectively. You can also choose which of the faces are rendered via the showTop, showLeft and showRight properties. + * A Render Texture is a special texture that allows any number of Game Objects to be drawn to it. You can take many complex objects and draw them all to this one texture, which can they be used as the texture for other Game Object's. It's a way to generate dynamic textures at run-time that are WebGL friendly and don't invoke expensive GPU uploads. * - * You cannot view an IsoBox from under-neath, however you can change the 'angle' by setting the projection property. + * Note that under WebGL a FrameBuffer, which is what the Render Texture uses internally, cannot be anti-aliased. This means that when drawing objects such as Shapes to a Render Texture they will appear to be drawn with no aliasing, however this is a technical limitation of WebGL. To get around it, create your shape as a texture in an art package, then draw that to the Render Texture. */ -export const IsoBox = GameObjects.IsoBox as unknown as FC< - Props +export const RenderTexture = GameObjects.RenderTexture as unknown as FC< + Props >; /** - * The IsoTriangle 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. + * A Rope Game Object. * - * This shape supports only fill colors and cannot be stroked. + * The Rope object is WebGL only and does not have a Canvas counterpart. * - * An IsoTriangle is an 'isometric' triangle. Think of it like a pyramid. Each face has a different fill color. You can set the color of the top, left and right faces of the triangle respectively You can also choose which of the faces are rendered via the showTop, showLeft and showRight properties. + * A Rope is a special kind of Game Object that has a texture that repeats along its entire length. Unlike a Sprite, it isn't restricted to using just a quad and can have as many vertices as you define when creating it. The vertices can be arranged in a horizontal or vertical strip and have their own color and alpha values as well. * - * You cannot view an IsoTriangle from under-neath, however you can change the 'angle' by setting the projection property. The reversed property controls if the IsoTriangle is rendered upside down or not. + * A Ropes origin is always 0.5 x 0.5 and cannot be changed. */ -export const IsoTriangle = GameObjects.IsoTriangle as unknown as FC< - Props ->; +export const Rope = GameObjects.Rope as unknown as FC>; /** - * The Line 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 only stroke colors and cannot be filled. - * - * A Line Shape allows you to draw a line between two points in your game. You can control the stroke color and thickness of the line. In WebGL only you can also specify a different thickness for the start and end of the line, allowing you to render lines that taper-off. - * - * If you need to draw multiple lines in a sequence you may wish to use the Polygon Shape instead. + * A Shader Game Object. * - * Be aware that as with all Game Objects the default origin is 0.5. If you need to draw a Line between two points and want the x1/y1 values to match the x/y values, then set the origin to 0. + * This Game Object allows you to easily add a quad with its own shader into the display list, and manipulate it as you would any other Game Object, including scaling, rotating, positioning and adding to Containers. Shaders can be masked with either Bitmap or Geometry masks and can also be used as a Bitmap Mask for a Camera or other Game Object. They can also be made interactive and used for input events. */ -export const Line = GameObjects.Line as unknown as FC>; +export const Shader = GameObjects.Shader as unknown as FC< + Props +>; /** - * The Polygon 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. - * - * The Polygon Shape is created by providing a list of points, which are then used to create an internal Polygon geometry object. The points can be set from a variety of formats: - * - * - A string containing paired values separated by a single space: '40 0 40 20 100 20 100 80 40 80 40 100 0 50' - * - An array of Point or Vector2 objects: [new Phaser.Math.Vector2(x1, y1), ...] - * - An array of objects with public x/y properties: [obj1, obj2, ...] - * - An array of paired numbers that represent point coordinates: [x1,y1, x2,y2, ...] - * - An array of arrays with two elements representing x/y coordinates: [[x1, y1], [x2, y2], ...] - * - * By default the x and y coordinates of this Shape refer to the center of it. However, depending on the coordinates of the points provided, the final shape may be rendered offset from its origin. + * The Shape Game Object is a base class for the various different shapes, such as the Arc, Star or Polygon. You cannot add a Shape directly to your Scene, it is meant as a base for your own custom Shape classes. */ -export const Polygon = GameObjects.Polygon as unknown as FC< - Props +export const Shape = GameObjects.Shape as unknown as FC< + Props >; /** - * The Rectangle 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. + * A Sprite Game Object. * - * This shape supports both fill and stroke colors. + * A Sprite Game Object is used for the display of both static and animated images in your game. Sprites can have input events and physics bodies. They can also be tweened, tinted, scrolled and animated. * - * You can change the size of the rectangle by changing the `width` and `height` properties. + * The main difference between a Sprite and an Image Game Object is that you cannot animate Images. As such, Sprites take a fraction longer to process and have a larger API footprint due to the Animation Component. If you do not require animation then you can safely use Images to replace Sprites in all cases. */ -export const Rectangle = GameObjects.Rectangle as unknown as FC< - Props +export const Sprite = GameObjects.Sprite as unknown as FC< + Props >; /** @@ -500,47 +490,57 @@ export const Triangle = GameObjects.Triangle as unknown as FC< >; /** - * A Rope Game Object. + * A Text Game Object. * - * The Rope object is WebGL only and does not have a Canvas counterpart. + * 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. * - * A Rope is a special kind of Game Object that has a texture that repeats along its entire length. Unlike a Sprite, it isn't restricted to using just a quad and can have as many vertices as you define when creating it. The vertices can be arranged in a horizontal or vertical strip and have their own color and alpha values as well. + * 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. * - * A Ropes origin is always 0.5 x 0.5 and cannot be changed. + * Important: The font name must be quoted if it contains certain combinations of digits or special characters, either when creating the Text object, or when setting the font via setFont or setFontFamily, e.g.: + * + * ```js + * this.add.text(0, 0, 'Hello World', { fontFamily: 'Georgia, "Goudy Bookletter 1911", Times, serif' }); + * ``` + * + * ```js + * this.add.text(0, 0, 'Hello World', { font: '"Press Start 2P"' }); + * ``` + * + * 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 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. */ -export const Rope = GameObjects.Rope as unknown as FC>; +export const Text = GameObjects.Text as unknown as FC>; /** - * A Shader Game Object. + * A TileSprite is a Sprite that has a repeating texture. * - * This Game Object allows you to easily add a quad with its own shader into the display list, and manipulate it as you would any other Game Object, including scaling, rotating, positioning and adding to Containers. Shaders can be masked with either Bitmap or Geometry masks and can also be used as a Bitmap Mask for a Camera or other Game Object. They can also be made interactive and used for input events. + * The texture can be scrolled and scaled independently of the TileSprite itself. Textures will automatically wrap and are designed so that you can create game backdrops using seamless textures as a source. + * + * You shouldn't ever create a TileSprite any larger than your actual canvas size. If you want to create a large repeating background that scrolls across the whole map of your game, then you create a TileSprite that fits the canvas size and then use the tilePosition property to scroll the texture as the player moves. If you create a TileSprite that is thousands of pixels in size then it will consume huge amounts of memory and cause performance issues. Remember: use tilePosition to scroll your texture and tileScale to adjust the scale of the texture - don't resize the sprite itself or make it larger than it needs. + * + * An important note about Tile Sprites and NPOT textures: Internally, TileSprite textures use GL_REPEAT to provide seamless repeating of the textures. This, combined with the way in which the textures are handled in WebGL, means they need to be POT (power-of-two) sizes in order to wrap. If you provide a NPOT (non power-of-two) texture to a TileSprite it will generate a POT sized canvas and draw your texture to it, scaled up to the POT size. It's then scaled back down again during rendering to the original dimensions. While this works, in that it allows you to use any size texture for a Tile Sprite, it does mean that NPOT textures are going to appear anti-aliased when rendered, due to the interpolation that took place when it was resized into a POT texture. This is especially visible in pixel art graphics. If you notice it and it becomes an issue, the only way to avoid it is to ensure that you provide POT textures for Tile Sprites. */ -export const Shader = GameObjects.Shader as unknown as FC< - Props +export const TileSprite = GameObjects.TileSprite as unknown as FC< + Props >; /** - * A Scene plugin that provides a Phaser.GameObjects.LightsManager for the Light2D pipeline. + * A Video Game Object. + * + * This Game Object is capable of handling playback of a previously loaded video from the Phaser Video Cache, or playing a video based on a given URL. Videos can be either local, or streamed. */ -export const Light = GameObjects.Light as unknown as FC< - Props +export const Video = GameObjects.Video as unknown as FC< + Props >; /** - * A Mesh Game Object. - * - * The Mesh Game Object allows you to render a group of textured vertices and manipulate the view of those vertices, such as rotation, translation or scaling. - * - * Support for generating mesh data from grids, model data or Wavefront OBJ Files is included. - * - * Although you can use this to render 3D objects, its primary use is for displaying more complex Sprites, or Sprites where you need fine-grained control over the vertice positions in order to achieve special effects in your games. Note that rendering still takes place using Phasers orthographic camera. As a result, all depth and face tests are done in orthographic space. - * - * The rendering process will iterate through the faces of this Mesh and render out each face that is considered as being in view of the camera. No depth buffer is used, and because of this, you should be careful not to use model data with too many vertices, or overlapping geometry, or you'll probably encounter z-depth fighting. The Mesh was designed to allow for more advanced 2D layouts, rather than displaying 3D objects, even though it can do this to a degree. - * - * In short, if you want to remake Crysis, use a 3D engine, not a Mesh. However, if you want to easily add some small fun 3D elements into your game, or create some special effects involving vertex warping, this is the right object for you. Mesh data becomes part of the WebGL batch, just like standard Sprites, so doesn't introduce any additional shader overhead. Because the Mesh just generates vertices into the WebGL batch, like any other Sprite, you can use all of the common Game Object components on a Mesh too, such as a custom pipeline, mask, blend mode or texture. + * A Zone Game Object. * - * Note that the Mesh object is WebGL only and does not have a Canvas counterpart. + * A Zone is a non-rendering rectangular Game Object that has a position and size. It has no texture and never displays, but does live on the display list and can be moved, scaled and rotated like any other Game Object. * - * The Mesh origin is always 0.5 x 0.5 and cannot be changed. + * Its primary use is for creating Drop Zones and Input Hit Areas and it has a couple of helper methods specifically for this. It is also useful for object overlap checks, or as a base for your own non-displaying Game Objects. The default origin is 0.5, the center of the Zone, the same as with Game Objects. */ -export const Mesh = GameObjects.Mesh as unknown as FC>; +export const Zone = GameObjects.Zone as unknown as FC>;