phaser/src/gameobjects/text/TextFactory.js

60 lines
2.8 KiB
JavaScript
Raw Normal View History

2018-02-12 16:01:20 +00:00
/**
* @author Richard Davey <rich@photonstorm.com>
2022-02-28 14:29:51 +00:00
* @copyright 2022 Photon Storm Ltd.
2019-05-10 15:15:04 +00:00
* @license {@link https://opensource.org/licenses/MIT|MIT License}
2018-02-12 16:01:20 +00:00
*/
var Text = require('./Text');
var GameObjectFactory = require('../GameObjectFactory');
2018-02-07 00:18:22 +00:00
/**
* Creates a new Text Game Object and adds it to the Scene.
*
2018-09-15 09:31:10 +00:00
* A Text Game Object.
*
2018-09-15 09:31:10 +00:00
* 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.
*
2018-09-15 09:31:10 +00:00
* 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.
*
2018-09-15 09:31:10 +00:00
* 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.
2018-02-07 00:18:22 +00:00
*
* Note: This method will only be available if the Text Game Object has been built into Phaser.
*
* @method Phaser.GameObjects.GameObjectFactory#text
* @since 3.0.0
*
* @param {number} x - The horizontal position of this Game Object in the world.
* @param {number} y - The vertical position of this Game Object in the world.
2018-03-20 14:56:31 +00:00
* @param {(string|string[])} text - The text this Text object will display.
2020-08-01 11:34:37 +00:00
* @param {Phaser.Types.GameObjects.Text.TextStyle} [style] - The Text style configuration object.
2018-03-20 14:56:31 +00:00
*
2018-02-07 00:18:22 +00:00
* @return {Phaser.GameObjects.Text} The Game Object that was created.
*/
GameObjectFactory.register('text', function (x, y, text, style)
{
return this.displayList.add(new Text(this.scene, x, y, text, style));
});
// When registering a factory function 'this' refers to the GameObjectFactory context.
2018-03-20 14:56:31 +00:00
//
// There are several properties available to use:
2018-03-20 14:56:31 +00:00
//
// this.scene - a reference to the Scene that owns the GameObjectFactory
// this.displayList - a reference to the Display List the Scene owns
// this.updateList - a reference to the Update List the Scene owns