Phaser tutorial: How to balance random booleans for game

 

Follow @SBC_Games


Previous Phaser tutorials and articles:
Phaser tutorial: Fun with bitmap fonts
Phaser tutorial: Using Spriter player for Phaser
Phaser tutorial: Merging fonts into sprite atlas
Phaser: Typescript defs for Phaser Box2D plugin
Phaser tutorial: Spriter Pro features added to Spriter player for Phaser
Phaser tutorial: Using Phaser signals
Phaser tutorial: Breaking the (z-order) law!
Phaser tutorial: Phaser and Spriter skeletal animation
Phaser tutorial: DronShooter - simple game in Typescript - Part 3
Phaser tutorial: DronShooter - simple game in Typescript - Part 2
Phaser tutorial: adding 9-patch image support to Phaser
Phaser tutorial: DronShooter - simple game in Typescript - Part 1
Phaser tutorial: custom easing functions for tweening and easing functions with parameters
Phaser tutorial: sprites and custom properties for atlas frames
Phaser tutorial: manage different screen sizes
Phaser tutorial: How to wrap bitmap text

Introduction

 Last year I worked on many small games, were obstacles were generated procedurally on the fly. Getting random numbers from random numbers generator played big role in it. Unfortunately, randomness can be sometimes pretty ... random. Let's say you just want to get randomly true or false to place some obstacle to the right or left. Be sure, that very quickly you will encounter situations, when you will not like the result. Sometimes, there will be too many obstacles on one or other side and game may get boring for long time periods.
 Fast fix may be to add some counters to check if not too many obstacles is on one or other side.
 I was solving this often and to make situation worse, clients had requests like: "I want first 5 obstacles to be left and right in turns, so it will be kind of tutorial for player."

Solution

 So, I decided to solve it once and forever with small class, which I named RandomBooleanBalancer. Here is complete code for it in TypeScript:

namespace Helper {

    export class RandomBooleanBalancer {

        private _rnd: Phaser.RandomDataGenerator;
        private _lbound: number;
        private _ubound: number;
        private _currentBalance: number;

        // -------------------------------------------------------------------------
        // balancer - how many consecutive same values maximally
        public constructor(rnd: Phaser.RandomDataGenerator, balancer: number) {
            this._rnd = rnd;
            this.reset(balancer);
        }

        // -------------------------------------------------------------------------
        public reset(balancer: number): void {
            --balancer;

            let lbound = Math.ceil(balancer / 2);
            this._lbound = -lbound;
            this._ubound = balancer - lbound;

            this._currentBalance = balancer === 0 ? this._rnd.integerInRange(-1, 0) : 0;
        }

        // -------------------------------------------------------------------------
        public getBoolean(): boolean {

            let result = this._currentBalance + this._rnd.integerInRange(this._lbound, this._ubound);

            //console.log("lbound = " + (this._lbound + this._currentBalance) + ", ubound = " + (this._ubound + this._currentBalance) +
            //    ", currentBalance = " + this._currentBalance + ", value = " + (result >= 0));

            this._currentBalance += result >= 0 ? -1 : 1;

            return result >= 0;
        }
    }
}

 In constructor it takes random numbers generator and "magic number" called balancer. This number is your request, how many consecutive same values it shall return when you repeatedly call getBoolean() method.

 For example, if you want true or false maximally two times after each other, then set it to 2.

 reset() method allows you to change this request during runtime.

Test

 Let's do some tests. Our test code will be simple loop with 50 iterations - it just prints string with 50 comma separated results, where true / false is converted to 1 / 0 to shorten output. We will start with balancer value equal 1:

            let randomBalancer = new Helper.RandomBooleanBalancer(this.rnd, 1);
            let result = "";
            for (let i = 0; i < 50; i++) {
                result += (randomBalancer.getBoolean() ? "1" : "0") + (i < 50 - 1 ? ", " : "");
            }
            console.log(result);

 Here is output from console:

0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1

 As our request was to have maximally 1 consecutive true or false, we got them switching regularly. If you run this test multiple times, you will notice, that whole sequence starts randomly with true or false.

 Now, change number in constructor to 2 and run the test again. This is console output:

0, 1, 0, 1, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 0, 1, 1, 0, 1, 0, 1, 0, 1, 0, 0, 1, 0, 1, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1

 As you can see, returned values are random, but you get maximally two randoms of the same value after each other.

 Now, change requested value in constructor to 5. You may get something like this:

1, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 0, 0, 1, 0, 1, 0, 1, 0, 1, 0, 0, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 1, 0, 0, 1, 1, 1, 0, 0, 0

 In my run I did not get any sequence of 5 ones or zeroes. This is another nice feature of this class. As you get more and more, let's say, ones, there is decreasing probability, that next random will be also one. It is more and more probable it will be zero. But of course, it is possible to get true or false 5 times in row - but this is cap, as you requested: "5 times true or false in row, but no more".

Conclusion

 I hope this small code snippet will make your life easier. If you are interested in how it works, you can uncomment debug output in getBoolean() method and watch it after each call.

Phaser tutorial: Fun with bitmap fonts

 

Follow @SBC_Games


Previous Phaser tutorials and articles:
Phaser tutorial: Using Spriter player for Phaser
Phaser tutorial: Merging fonts into sprite atlas
Phaser: Typescript defs for Phaser Box2D plugin
Phaser tutorial: Spriter Pro features added to Spriter player for Phaser
Phaser tutorial: Using Phaser signals
Phaser tutorial: Breaking the (z-order) law!
Phaser tutorial: Phaser and Spriter skeletal animation
Phaser tutorial: DronShooter - simple game in Typescript - Part 3
Phaser tutorial: DronShooter - simple game in Typescript - Part 2
Phaser tutorial: adding 9-patch image support to Phaser
Phaser tutorial: DronShooter - simple game in Typescript - Part 1
Phaser tutorial: custom easing functions for tweening and easing functions with parameters
Phaser tutorial: sprites and custom properties for atlas frames
Phaser tutorial: manage different screen sizes
Phaser tutorial: How to wrap bitmap text

Introduction

 Very often I need to display some information for player in GUI in my games. It is usually composed of some text and icon. And it also often takes some time to fine tune positioning of text and icon. Things get complicated if part of it can change width like number on following image:

 Then, if you update number, you also have to update position of icon. Making some longer text, like the one on image bellow, with small images inside of it, is tedious work and usually needs lot of code.

Solution

 Fortunately, solution is easy. We can add images as special characters into font and then print whole text, including images, in one call in code.

 Let's say you have font called "Font" and atlas called "Game". Font is made of texture with characters and xml metadata file. It can be font made with Littera or any other font tool. Atlas is standard atlas with your game images.

 After these are loaded in your preload function - for example like this:

            this.load.atlas("Game", "assets/Game.png", "assets/Game.json");
            this.load.bitmapFont("Font", "assets/Font.png", "assets/Font.xml");

 you can start your adjustments in create function. First we get reference to our loaded assets:

            let atlas = this.cache.getImage("Game", true);
            let font = this.cache.getBitmapFont("Font");

 Next we get reference to loaded font xml data and also reference to capital "A" character. Reason for this is, that we will center added images on the same level as center of "A" is.

            let fontData = font.font;
            let charA = fontData.chars[65];

 Now, in my case, I have 7 gem images in atlas with names Gem1 ... Gem7. I will add them as special characters. First, I have to choose character code for them. Here I chose 5000 for Gem1, 5001 for Gem2 ...

            for (let i = 0; i < 7; i++) {
                let f = this.cache.getFrameByName("Game", "Gem" + (i + 1));

                fontData.chars[5000 + i] = {
                    x: f.x,
                    y: f.y,
                    width: f.width,
                    height: f.height,
                    xOffset: 1,
                    yOffset: charA.yOffset + Math.floor((charA.height - f.height) / 2),
                    xAdvance: f.width + 2,
                    kerning: [],
                    texture: new PIXI.Texture(atlas["base"], new PIXI.Rectangle(f.x, f.y, f.width, f.height)) 
                };
            }

 First, we get Phaser.Frame from atlas, so we will have access to position and dimensions of image within atlas. Next, we add new object with all font metadata to current font characters data at position of character code we chose before. For yOffset we are doing small calculation to center added images relative to "A" - we want center of A and added images on the same level. xOffset is 1 and it says, that there will be 1 pixel space after previous character. xAdvance then says how much has font renderer step to draw next character. We set this to width + 2 (= xOffset + width + 1). On last line, we are setting texture property. Here you may get error - just head to phaser.d.ts and change BMFontChar interface to use PIXI.Texture instead of PIXI.BaseTexture.

Test

 To test our gem images in text add this code:

            let text = "Hi, " + String.fromCharCode(5000, 5005, 5006) + " there!\n\nHow are you? " + String.fromCharCode(5001, 5002);
            let bmText = new Phaser.BitmapText(this.game, 0, 0, "Font", text, 110);
            bmText.anchor.x = 0.5;
            this.world.add(bmText);

 To include gems we make string from character codes with call to String.fromCharCode(). You should see this on screen:

Draw calls

 While everything works, there is small issue you should be aware of. As our font images and gem images are in different textures, there can be more draw calls. In above case there are four draw calls to draw this single piece of text.

 Fortunately, there is also solution for this. Merge your font into atlas as described in one of previous tutorials. Code changes only very little:

            let font = this.cache.getBitmapFont("Font");
            let fontData = font.font;
            let charA = fontData.chars[65];

            for (let i = 0; i < Level.MAX_GEM; i++) {
                let f = this.cache.getFrameByName("Game", "Gem" + (i + 1));

                fontData.chars[5000 + i] = {
                    x: f.x,
                    y: f.y,
                    width: f.width,
                    height: f.height,
                    xOffset: 1,
                    yOffset: charA.yOffset + Math.floor((charA.height - f.height) / 2),
                    xAdvance: f.width + 2,
                    kerning: [],
                    texture: new PIXI.Texture(font.base, new PIXI.Rectangle(f.x, f.y, f.width, f.height)) 
                };
            }

 You do not need reference to atlas, because gem images are in the same texture as font characters and in last line you can get base texture from font data.

 This reduces draw calls to one.

Conclusion

 With presented solution you can easily mix text with icons. If you merge font with atlas, there are no additional costs in terms of draw calls.

Phaser tutorial: Using Spriter player for Phaser

 

Follow @SBC_Games


Previous Phaser tutorials and articles:
Phaser tutorial: Merging fonts into sprite atlas
Phaser: Typescript defs for Phaser Box2D plugin
Phaser tutorial: Spriter Pro features added to Spriter player for Phaser
Phaser tutorial: Using Phaser signals
Phaser tutorial: Breaking the (z-order) law!
Phaser tutorial: Phaser and Spriter skeletal animation
Phaser tutorial: DronShooter - simple game in Typescript - Part 3
Phaser tutorial: DronShooter - simple game in Typescript - Part 2
Phaser tutorial: adding 9-patch image support to Phaser
Phaser tutorial: DronShooter - simple game in Typescript - Part 1
Phaser tutorial: custom easing functions for tweening and easing functions with parameters
Phaser tutorial: sprites and custom properties for atlas frames
Phaser tutorial: manage different screen sizes
Phaser tutorial: How to wrap bitmap text

Introduction

 Some time ago I published here article about Spriter player for Phaser. I made the code freely available at GitHub. Player is written in Typescript and GitHub code contained both the player and small example on how to use it in one project. I thought it would be easy for others to use it, but I was wrong - for some coders it would be better if there was separate .js file and also there was lack of information on usage. But if you want to have nice animations in your game like the parrot above, small obstacles should not discourage you!
 
 So, I made a few changes - check GitHub:

• player itself and example are both separated from each other,
• there is added Build folder, where you can grab either spriter.js or spriter.min.js files ready to be used in your project.

 Splitting player and example also forced creation of Typescript defs for player. It can be found in spriter.d.ts file in Build directory.

Example

 I assume you are familiar with Phaser states. On GitHub go into Test/src/States. In Preloader.ts file I am loading export from Spriter program with standard Phaser loader. Export can by either .xml (.scml) od .json (scon). I am also loading atlas with all part visual parts of animation (for test use files from assets folder):

            // load assets
            var path: string = Global.assetsPath;

            // test
            this.load.atlas("TEST", path + "Atlas.png", path + "Atlas.json");
            this.load.xml("TESTXml", path + "TEST.xml");
            this.load.json("TESTJson", path + "TEST.json");

 You will need only to load either xml or json. Both lines are here only to show both possibilities. 

 What is important, Spriter exports list of visual parts with file extension like "head.png". Spriter player cuts the extension off and uses only part name (like "head"). Some tools for making sprite atlases export names with and some without extension. Make sure, that you create atlas with names without extension.

 When your data are loaded you can move to file Test.ts, where we will use it.

 First, we will do some basic setup. Data we loaded in previous step are either .xml or .json. But we need to turn it into some structure player is familiar with. To do it there is Spriter.Loader class. This class takes Spriter.SpriteFile (which can be Spriter.SpriterXml or Spriter.Spriter.JSON) and outputs complete Spriter.Spriter data structure. Loader can process as many files as you need - you do not need to create it for every single processing. All Spriter player classes are in Spriter namespace, so I will not further write it here.

 Let's create loader:

            // create Spriter loader - class that can change Spriter file into internal structure
            var spriterLoader = new Spriter.Loader();

 Now, we will create SpriterFile that loader can proces. It is one of derived classes - SpriterXml or SproterJSON (this time I will choose JSON and leave XML commented out):

            // create Spriter file object - it wraps XML/JSON loaded with Phaser Loader
            //var spriterFile = new Spriter.SpriterXml(this.cache.getXML("TESTXml"));
            var spriterFile = new Spriter.SpriterJSON(this.cache.getJSON("TESTJson"));

 Spriter files are way how to wrap data, so single loader class can ask for information so different formats like JSON or XML in some uniform way. (By the way, there is also possibility to load special binary format through SpriterBin, but this feature is not currently working as I have to add Spriter Pro features into it.)

 In next step we will pass our spriter file to loader and in output we get "unpacked" structure with all objects needed for animation (which sprites it uses, what charmaps are available, list of entities, animations, timelines, ...). This structure is "read only" and no data are stored in it. It means you can use it for many animations running simultaneously on screen.

 In last step we will create the animation itself. For this, player has SpriterGroup object. It extends standard Phaser.Group class. So, everything you can do with Phaser.Group, you can also do with SpriterGroup (scale, rotate, blend, ...). SpriterGroup is main class of Spriter player and most of the things you will need is done through this class (create _spriterGroup variable, so you can reference your animation later):

            // create actual renderable object - it is extension of Phaser.Group
            this._spriterGroup = new Spriter.SpriterGroup(this.game, spriterData, "TEST", "Hero", 0, 100);
            this._spriterGroup.position.setTo(420, 400);

            // adds SpriterGroup to Phaser.World to appear on screen
            this.world.add(this._spriterGroup);

 To tick animation add this into update method:

        update() {
            this._spriterGroup.updateAnimation();
        }

 This is little stupid, because Phaser calls update on Phaser.Group automatically. So, if animation update was in update method of SpriterGroup and not in updateAnimation, then this call would not be needed. I will probably change it in future. Until, you have to tick your animations explicitly.

 Running the example now, you should have animated character on screen. If you used assets from test, you will see this boy:

SpriterGroup features

 As already said, main class is SpriterGroup. So, I will go through its features here. I will use Typescript syntax as it includes type information, but it should be perfectly readable also for JS developers (take it as pseudocode).

 In example above we created new SpriterGroup like this:

this._spriterGroup = new Spriter.SpriterGroup(this.game, spriterData, "TEST", "Hero", 0, 100);

 Here is what these parameters mean:

        constructor(game: Phaser.Game, spriter: Spriter, texutreKey: string, entityName: string,
            animation?: string | number, animationSpeedPercent?: number);

 You need to pass Phaser.Game like for many other Phaser gameobjects. Next you have to pass Spriter animation structure that you processed with Spriter Loader class. Third is name of atlas with visual parts of animation. Last mandatory parameter is name of entity. Spriter file can have one or more entities. When you create SpriterGroup you have to pass which entity you want to use. You can not change this later.

 If you omit animation then first animation for entity is started. Every entity has one or more animations. Animations within entity can be switched. Last parameter is speed of animation in percent. default value is 100.

 SpriterGroup can inform you on a few events. This is done through standard Phaser.Signals. Here is list of signals you can use:

        // onLoop(SpriterGroup);
        onLoop: Phaser.Signal;
        // onFinish(SpriterGroup);
        onFinish: Phaser.Signal;

        // onSound(SpriterGroup, string); // string for line name which equals soud name without extension
        onSound: Phaser.Signal;
        // onEvent(SpriterGroup, string); // string for line name which equals event name
        onEvent: Phaser.Signal;
        // onTagChange(SpriterGroup, string, boolean); // string for tag name, boolean for change (true = set / false = unset)
        onTagChange: Phaser.Signal;
        // onVariableSet(SpriterGroup, Variable); // Variable is Spriter variable def with access to value
        onVariableSet: Phaser.Signal;

• onLoop - subscribers are notified when animation loops,
• onFinish - if animation does not loop, subscribers are notified on finishing,
• onSound - Spriter Pro animations can have soundline, which allows great synchronization between animation and sounds. Spriter player does not actually play sounds, but notifies subscribers when sound shall be played. Signal dispatches SpriterGroup that fired event and name of  sound to play. In this way it is just specific sound event,
• onEvent - in this Spriter player implementation it is the same as onSound, but not sound specific. Also here, name of the event is dispatched,
• onTagChange - tags in Spriter animation says that something is on or off. When this changes you can read it through this signal. Imagine for example starting / stopping particle rain from sky when wizard casts spell (during "castRain" tag on). In this signal you get not only name of tag, but also its on/off state in next parameter,
• onVariableSet - Spriter Pro animations can have variables, that are set in certain points to certain values. These variables are integers, floats and strings. Current implementation does not interpolate integer and float variables. Currently, it is only set to new value. You can listen to these events when variable is set and do something with its value. You can treat it as "event with value". Here you get Variable object that holds name, type and value.

 Here are few properties you can read:

        // get loaded Spriter structure
        spriter: Spriter;
        // get Spriter entity
        entity: Entity;
        // number of animations for current entity
        animationsCount: number;
        // name of current animation
        currentAnimationName: string;

 pause can be read and set:

        // is anim paused?
        paused: boolean;

 To play or change animation, set its playing speed and to update (tick) whole SpriterGroup, use these methods:

        // set speed of animation in percent (default = 100)
        setAnimationSpeedPercent(animationSpeedPercent: number): void;
        // play animation by Spriter animation id
        playAnimationById(aAnimationId: number): void;
        // play animation by name
        playAnimationByName(aAnimationName: string): void;
        // call this on every frame to tick animation
        updateAnimation(): void;

 Next set of method allows you to work with charmaps. Charmaps are sets of alternative visuals for animation (you can replace only some visuals). These charmaps can be stacked on each other. As a result you can achieve high variability with small amount of assets. Imagine evil orc as base character and charmap for replacing club with rusty sword and another charmap for helmet.

        // add charmap on top of charmap stacky by name
        pushCharMap(charMapName: string): void;
        // remove charmap from stack by name
        removeCharMap(charMapName: string): void;
        // remove all charmaps from charmap stack
        clearCharMaps(): void;

 With last set of methods you can question tags and variables:

        // check if animation tag with given name is on or off
        isTagOn(tagName: string): boolean;
        // check if animation tag with given id is on or off
        isTagOnById(tagId: number): boolean;
        // get animation variable by name
        getVariable(varName: string): Variable;
        // get animation variable by id
        getVariableById(varId: number): Variable;
        // get Spriter object by name - Spriter object contain actual Phaser.Sprite
        getObject(objectName: string): SpriterObject;

Conclusion

 I hope this tutorial helped to clarify some point, that were not clear before. Using Spriter animation as just another Phaser gameobject should be convenient. More, you can use all Phaser.Group methods with it.

Phaser tutorial: Merging fonts into sprite atlas

 

Follow @SBC_Games


Previous Phaser tutorials and articles:
Phaser: Typescript defs for Phaser Box2D plugin
Phaser tutorial: Spriter Pro features added to Spriter player for Phaser
Phaser tutorial: Using Phaser signals
Phaser tutorial: Breaking the (z-order) law!
Phaser tutorial: Phaser and Spriter skeletal animation
Phaser tutorial: DronShooter - simple game in Typescript - Part 3
Phaser tutorial: DronShooter - simple game in Typescript - Part 2
Phaser tutorial: adding 9-patch image support to Phaser
Phaser tutorial: DronShooter - simple game in Typescript - Part 1
Phaser tutorial: custom easing functions for tweening and easing functions with parameters
Phaser tutorial: sprites and custom properties for atlas frames
Phaser tutorial: manage different screen sizes
Phaser tutorial: How to wrap bitmap text

Introduction

 Everybody with at least short experience in game development came across sprite atlases. Its benefits are in merging multiple sprites into one large bitmap and so decreasing draw calls. We can simplify draw call as request to GPU to draw something with some set of parameters. One of these parameters is also texture. Changing any of parameters results into quite expensive setup on GPU side (flushing current work and doing setup for different set of parameters) - this is reason why to build larger textures made from individual sprites.

 Currently there is lot of tools, that help you with creating sprite atlas from individual sprites. But, when it comes to fonts, the situation starts to get complicated.

 For creating fonts I am using on-line tool Littera. This tool is great, but when you are exporting your font, you already get some atlas that contains your font characters. Alongside, you get file with characters metadata saying where in atlas is character positioned, how big it is, ... 

 Export from Littera can look like this:

 With metadata like this:

<font>
  <info face="MapNormal" size="40" bold="0" italic="0" charset="" unicode="" stretchH="100" smooth="1" aa="1" padding="2,2,2,2" spacing="0,0" outline="0"/>
  <common lineHeight="75" base="24" scaleW="42" scaleH="252" pages="1" packed="0"/>
  <pages>
    <page id="0" file="MapNormal.png"/>
  </pages>
  <chars count="10">
    <char id="48" x="2" y="2" width="18" height="24" xoffset="2" yoffset="3" xadvance="19" page="0" chnl="15"/>
    <char id="49" x="2" y="28" width="15" height="24" xoffset="0" yoffset="3" xadvance="13" page="0" chnl="15"/>
    <char id="50" x="2" y="54" width="21" height="25" xoffset="0" yoffset="2" xadvance="19" page="0" chnl="15"/>
    <char id="51" x="22" y="2" width="18" height="26" xoffset="1" yoffset="1" xadvance="17" page="0" chnl="15"/>
    <char id="52" x="2" y="81" width="20" height="25" xoffset="2" yoffset="3" xadvance="18" page="0" chnl="15"/>
    <char id="53" x="2" y="108" width="18" height="25" xoffset="1" yoffset="2" xadvance="16" page="0" chnl="15"/>
    <char id="54" x="2" y="135" width="20" height="27" xoffset="1" yoffset="0" xadvance="18" page="0" chnl="15"/>
    <char id="55" x="2" y="164" width="19" height="26" xoffset="1" yoffset="2" xadvance="12" page="0" chnl="15"/>
    <char id="56" x="2" y="192" width="19" height="28" xoffset="1" yoffset="1" xadvance="16" page="0" chnl="15"/>
    <char id="57" x="2" y="222" width="19" height="28" xoffset="1" yoffset="3" xadvance="18" page="0" chnl="15"/>
    <char id="32" x="0" y="0" width="0" height="0" xoffset="1" yoffset="3" xadvance="11" page="0" chnl="15"/>
  </chars>
  <kernings count="0"/>
</font>

 

Problem

 So, let's have some sprite atlas and above font created in Littera. Let's also imagine we have some object, that is made from sprites and text. This is exactly what map screen with map spots is in our upcoming game Pirates! - the match three game (graphics is made by Tomáš Kopecký):

 Every single map spot is object made from sprites and text (level number). Scene graph for it looks like this:

 Map has 65 level spots and drawing it takes 136 draw calls. 130 (65 * 2) of them is for map spots. It is very bad, but it is impact of switching between atlas with sprites and atlas with fonts. On above picture it is clear, that every time renderer renders single map spot, it has to switch texture twice.

 What we need is somehow merge font into our sprite atlas and keep valid font metadata. Then we will get rid of that texture switching and we will be able to decrease draw calls.

 

Solution

 Long time ago I made tool for creating sprite atlases. It is very old and it has messy code inside, not too good GUI and also name is messy - I call it sometimes PicOpt and more recently Spritor. Anyway, it has some nice features and I used it for all games I made. You can get it for free here. One of these nice features is, that it can do what we need. So, download it and follow next steps:

 Open Spritor tool and pres Ctrl+N to create new project. Give it name (it is not saved, it only created new project):

 

 Press Ctrl+A to add some sprites (individual .png images):

 Your screen should look similar to this:

 Now, pres Ctrl+A again and open you Littera font atlas. You need to have Littera .xml/.fnt file in the same directory. Also, do not forget to check "Is font" in bottom of dialog window:

 This will add Littera font atlas into your project. It will read through Littera metadata in .xml/.fnt and cut Littera font atlas into individual sprites. The role of metadata is not finished yet. It will play important role once again during export. You can now select type of export. To have one compatible with TexturePacker export, select format in top bar as this:

 (Btw, export just one line below ("JSON - TP + Properties") is adding custom properties, that you can add to your sprites in Spritor tool, into final export). You can now save your project by pressing Ctrl+S.

 It's time to make atlas. Go to menu and select Optimize -> Best Place:

 

 After some short time for optimiaztion, there will be created folder with name "export" and you will find several files there:

• your atlas image,
• your atlas metadata (in TexturePacker format),
• one Littera metadata file (.xml or .fnt) for every font you merged into atlas. This file already has all character specs adjusted to positions in new atlas.

 This is how atlas from our walkthrough looks like:

Not finished yet - Phaser part

 As we have our assets ready, we can load it into Phaser and see what happes.

 Normally, you would load your font and atlas in preload method with code like:

this.load.atlas("Atlas", "assets/Atlas.png", "assets/Atlas.json");
this.load.bitmapFont("Font", "assets/Font.png", "assets/Font.xml");

 But in our case we already have fonts merged into atlas, so we do not need to load "Font.png" file. So, we will first change this to:

this.load.atlas("Atlas", "assets/Atlas.png", "assets/Atlas.json");
this.load.xml("Font", "assets/Font.xml");

 Then, when assets are loaded, in create method we have to build our font from loaded atlas and xml metadata. At first, it looks like easy task:

this.cache.addBitmapFont("MyFont", null, this.cache.getImage("Atlas"), this.cache.getXML("Font"), "xml");

 If you do above and run your game, You will see, that you can use "MyFont" in your game. It is taking characters from atlas, that is common with other sprites, but number of draw calls did not decreased! Something went wrong.

 Let's look into Phaser source. Method for addBitmapFont has this in the beginning:

    addBitmapFont: function (key, url, data, atlasData, atlasType, xSpacing, ySpacing) {

        var obj = {
            url: url,
            data: data,
            font: null,
            base: new PIXI.BaseTexture(data)
        };
           :
           :
           :

 And if we dive a little bit deeper into PIXI.WebGLSpriteBatch.prototype.flush() method we find this (shortened and lots of code omitted for clarity):

              :
              :
            nextTexture = sprite.texture.baseTexture;
              :
              :
        if ((currentBaseTexture !== nextTexture && !nextTexture.skipRender) || blendSwap || shaderSwap)
        {
            this.renderBatch(currentBaseTexture, batchSize, start);
              :
              :

 Batches are flushed based not on underlaying atlas image, but on baseTexture. As we have one atlas we have to achieve somehow to have the same baseTexture for atlas as well as for font. For this we will create our custom method that will add functionality to Phaser Cache class. Let's call it addBitmapFontFromImage. Code for it is mostly copy of original addBitmapFont:

* update for Phaser 2.7.3 and later * - when using jsonBitmapFont and xmlBitmapFont in code below, you have to pass two additional parameters for frame (null) and resolution (1).

module Utils {

    export class PhaserUtils {

        // -------------------------------------------------------------------------
        public static AddBitmapFontAddMethod(): void {

            Phaser.Cache.prototype["addBitmapFontFromImage"] = function addBitmapFont(key: string, url: string,
                imageName: string, atlasData: any, atlasType: string, xSpacing?: number, ySpacing?: number): void {

                var img = this.getImage(imageName, true);

                var obj = {
                    url: url,
                    data: img.data,
                    font: null,
                    base: img.base
                };

                if (xSpacing === undefined) { xSpacing = 0; }
                if (ySpacing === undefined) { ySpacing = 0; }

                if (atlasType === 'json') {
                    obj.font = Phaser.LoaderParser.jsonBitmapFont(atlasData, obj.base, xSpacing, ySpacing, null, 1);
                }
                else {
                    obj.font = Phaser.LoaderParser.xmlBitmapFont(atlasData, obj.base, xSpacing, ySpacing, null, 1);
                }

                this._cache.bitmapFont[key] = obj;

                this._resolveURL(url, obj);
            }
        }
    }
}

 Our new method is wrapped in special PhaserUtils class. Btw, I have this class filled with other small engine tweaks and in the very beginning of the game I call one or more static methods to apply these tweaks. You have to do the same - do it before you create game object!:

Utils.PhaserUtils.AddBitmapFontAddMethod();

 Now, replace line for creating font in create method with call to our new method:

this.cache["addBitmapFontFromImage"]("MyFont", null, "Atlas", this.cache.getXML("Font"), "xml");

 Call is using square brackets as we did not add our method into phaser.d.ts file. If you used standard call, you would get Typescript complaints.

 If you run your game now, you should see that number of draw calls decreased. In my case it went down from 136 to 6!!!

 

 Conclusion

 In our game we have in fact three different fonts for map spots - depends on whether spot is normal, finished, special battle spot... All three fonts contain only numbers. Instead of having three font atlases and one for sprites, we have only one for everything.

 This helps us to save resources, reduce draw calls and as the process of creating atlas is easy we do not get any overhead.