phaser-ce/src/animation/AnimationParser.js

Phaser CE (Community Edition) is a fast, free and fun HTML5 Game Framework for Desktop and Mobile web browsers.

/**
 * @author       Richard Davey <rich@photonstorm.com>
 * @copyright    2016 Photon Storm Ltd.
 * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
 */

/**
 * Responsible for parsing sprite sheet and JSON data into the internal FrameData format that Phaser uses for animations.
 *
 * @class Phaser.AnimationParser
 * @static
 */
Phaser.AnimationParser = {

    /**
     * Parse a Sprite Sheet and extract the animation frame data from it.
     *
     * @method Phaser.AnimationParser.spriteSheet
     * @param {Phaser.Game} game - A reference to the currently running game.
     * @param {string|Image} key - The Game.Cache asset key of the Sprite Sheet image or an actual HTML Image element.
     * @param {number} frameWidth - The fixed width of each frame of the animation.
     * @param {number} frameHeight - The fixed height of each frame of the animation.
     * @param {number} [frameMax=-1] - The total number of animation frames to extract from the Sprite Sheet. The default value of -1 means "extract all frames".
     * @param {number} [margin=0] - If the frames have been drawn with a margin, specify the amount here.
     * @param {number} [spacing=0] - If the frames have been drawn with spacing between them, specify the amount here.
     * @param {number} [skipFrames=0] - Skip a number of frames. Useful when there are multiple sprite sheets in one image.
     * @return {Phaser.FrameData} A FrameData object containing the parsed frames.
     *
     * @see Phaser.Loader#spritesheet
     */
    spriteSheet: function (game, key, frameWidth, frameHeight, frameMax, margin, spacing, skipFrames)
    {
        if (frameMax === undefined) { frameMax = -1; }
        if (margin === undefined) { margin = 0; }
        if (spacing === undefined) { spacing = 0; }
        if (skipFrames === undefined) { skipFrames = 0; }

        var img = key;

        if (typeof key === 'string')
        {
            img = game.cache.getImage(key);
        }
        else
        {
            key = img.name;
        }

        if (img === null)
        {
            return null;
        }

        if (frameWidth <= 0 || frameHeight <= 0)
        {
            console.error('Spritesheet "%s": frameWidth (%s) and frameHeight (%s) values must be positive', key, frameWidth, frameHeight);

            return null;
        }

        var width = img.width;
        var height = img.height;

        if (width === 0 || height === 0)
        {
            console.error('Spritesheet "%s": Texture width (%s) or height (%s) is zero', key, width, height);

            return null;
        }

        if (width < frameWidth || height < frameHeight)
        {
            console.error('Spritesheet "%s": Texture width (%s) or height (%s) is less than the given frameWidth (%s) or frameHeight (%s)', key, width, height, frameWidth, frameHeight);

            return null;
        }

        var row = Math.floor((width - margin) / (frameWidth + spacing));
        var column = Math.floor((height - margin) / (frameHeight + spacing));
        var total = row * column;
        var totalAvailable = total;
        var lastAvailable = total - 1;
        var firstFrame = 0;
        var lastFrame = lastAvailable;

        if (skipFrames > total || skipFrames < -total)
        {
            console.error('Spritesheet "%s": skipFrames=%s is larger than the frame total %s', key, skipFrames, total);

            return null;
        }

        if (frameMax > -1)
        {
            total = frameMax;
            lastFrame = total - 1;
        }

        if (row < 1)
        {
            console.warn(
                'Spritesheet "%s": Texture has width %d, but it should be at least %d (frameWidth=%s, margin=%s, spacing=%s)',
                key, width, frameWidth + margin + spacing, frameWidth, margin, spacing
            );
        }

        if (column < 1)
        {
            console.warn(
                'Spritesheet "%s": Texture has height %d, but it should be at least %d (frameHeight=%s, margin=%s, spacing=%s)',
                key, height, frameHeight + margin + spacing, frameHeight, margin, spacing
            );
        }

        if (totalAvailable === 0)
        {
            console.error('Spritesheet "%s": zero frames were produced', key);

            return null;
        }

        if (skipFrames > 0)
        {
            // Offset from start
            firstFrame = skipFrames;
            total = Math.min(total, totalAvailable - skipFrames);
            lastFrame = firstFrame + total - 1;
        }
        else if (skipFrames < 0)
        {
            // Offset from end
            lastFrame = lastAvailable + skipFrames;
            total = Math.min(total, totalAvailable + skipFrames);
            firstFrame = lastFrame - total + 1;
        }

        if (firstFrame < 0)
        {
            console.error('Spritesheet "%s": There is no frame at index %s', key, firstFrame);

            return null;
        }

        if (lastFrame > lastAvailable)
        {
            console.warn('Spritesheet "%s": There is no frame at index %s. Last frame found is index %s', key, lastFrame, lastAvailable);

            return null;
        }

        //  Let's create some frames then
        var data = new Phaser.FrameData();
        var x = margin;
        var y = margin;
        var frameIndex = 0;

        for (var i = 0; i < totalAvailable; i++)
        {
            if (i > lastFrame)
            {
                break;
            }

            if (i >= firstFrame)
            {
                data.addFrame(new Phaser.Frame(frameIndex++, x, y, frameWidth, frameHeight, ''));
            }

            x += frameWidth + spacing;

            if (x + frameWidth > width)
            {
                x = margin;
                y += frameHeight + spacing;
            }
        }

        return data;
    },

    /**
     * Parse the JSON data and extract the animation frame data from it.
     *
     * @method Phaser.AnimationParser.JSONData
     * @param {Phaser.Game} game - A reference to the currently running game.
     * @param {object} json - The JSON data from the Texture Atlas. Must be in Array format.
     * @return {Phaser.FrameData} A FrameData object containing the parsed frames.
     */
    JSONData: function (game, json)
    {
        //  Malformed?
        if (!json.frames)
        {
            console.warn('Phaser.AnimationParser.JSONData: Invalid Texture Atlas JSON given, missing \'frames\' array');
            console.log(json);
            return;
        }

        //  Let's create some frames then
        var data = new Phaser.FrameData();

        //  By this stage frames is a fully parsed array
        var frames = json.frames;
        var newFrame;

        for (var i = 0; i < frames.length; i++)
        {
            newFrame = data.addFrame(new Phaser.Frame(
                i,
                frames[i].frame.x,
                frames[i].frame.y,
                frames[i].frame.w,
                frames[i].frame.h,
                frames[i].filename
            ));

            if (frames[i].trimmed)
            {
                newFrame.setTrim(
                    frames[i].trimmed,
                    frames[i].sourceSize.w,
                    frames[i].sourceSize.h,
                    frames[i].spriteSourceSize.x,
                    frames[i].spriteSourceSize.y,
                    frames[i].spriteSourceSize.w,
                    frames[i].spriteSourceSize.h
                );
            }

            if (frames[i].rotated)
            {
                newFrame.rotated = true;
            }
        }

        return data;
    },

    /**
     * Parse the JSON data and extract the animation frame data from it.
     *
     * @method Phaser.AnimationParser.JSONDataPyxel
     * @param {Phaser.Game} game - A reference to the currently running game.
     * @param {object} json - The JSON data from the Texture Atlas. Must be in Pyxel JSON format.
     * @return {Phaser.FrameData} A FrameData object containing the parsed frames.
     */
    JSONDataPyxel: function (game, json)
    {
        //  Malformed? There are a few keys to check here.
        var signature = [ 'layers', 'tilewidth','tileheight','tileswide', 'tileshigh' ];

        signature.forEach(function (key)
        {
            if (!json[key])
            {
                console.warn('Phaser.AnimationParser.JSONDataPyxel: Invalid Pyxel Tilemap JSON given, missing "' + key + '" key.');
                console.log(json);
                return;
            }
        });

        // For this purpose, I only care about parsing tilemaps with a single layer.
        if (json.layers.length !== 1)
        {
            console.warn('Phaser.AnimationParser.JSONDataPyxel: Too many layers, this parser only supports flat Tilemaps.');
            console.log(json);
            return;
        }

        var data = new Phaser.FrameData();

        var tileheight = json.tileheight;
        var tilewidth = json.tilewidth;

        var frames = json.layers[0].tiles;
        var newFrame;

        for (var i = 0; i < frames.length; i++)
        {
            newFrame = data.addFrame(new Phaser.Frame(
                i,
                frames[i].x,
                frames[i].y,
                tilewidth,
                tileheight,
                'frame_' + i // No names are included in pyxel tilemap data.
            ));

            // No trim data is included.
            newFrame.setTrim(false);
        }

        return data;
    },

    /**
     * Parse the JSON data and extract the animation frame data from it.
     *
     * @method Phaser.AnimationParser.JSONDataHash
     * @param {Phaser.Game} game - A reference to the currently running game.
     * @param {object} json - The JSON data from the Texture Atlas. Must be in JSON Hash format.
     * @return {Phaser.FrameData} A FrameData object containing the parsed frames.
     */
    JSONDataHash: function (game, json)
    {
        //  Malformed?
        if (!json.frames)
        {
            console.warn('Phaser.AnimationParser.JSONDataHash: Invalid Texture Atlas JSON given, missing \'frames\' object');
            console.log(json);
            return;
        }

        //  Let's create some frames then
        var data = new Phaser.FrameData();

        //  By this stage frames is a fully parsed array
        var frames = json.frames;
        var newFrame;
        var i = 0;

        for (var key in frames)
        {
            newFrame = data.addFrame(new Phaser.Frame(
                i,
                frames[key].frame.x,
                frames[key].frame.y,
                frames[key].frame.w,
                frames[key].frame.h,
                key
            ));

            if (frames[key].trimmed)
            {
                newFrame.setTrim(
                    frames[key].trimmed,
                    frames[key].sourceSize.w,
                    frames[key].sourceSize.h,
                    frames[key].spriteSourceSize.x,
                    frames[key].spriteSourceSize.y,
                    frames[key].spriteSourceSize.w,
                    frames[key].spriteSourceSize.h
                );
            }

            if (frames[key].rotated)
            {
                newFrame.rotated = true;
            }

            i++;
        }

        return data;
    },

    /**
     * Parse the XML data and extract the animation frame data from it.
     *
     * @method Phaser.AnimationParser.XMLData
     * @param {Phaser.Game} game - A reference to the currently running game.
     * @param {object} xml - The XML data from the Texture Atlas. Must be in Starling XML format.
     * @return {Phaser.FrameData} A FrameData object containing the parsed frames.
     */
    XMLData: function (game, xml)
    {
        //  Malformed?
        if (!xml.getElementsByTagName('TextureAtlas'))
        {
            console.warn('Phaser.AnimationParser.XMLData: Invalid Texture Atlas XML given, missing <TextureAtlas> tag');
            return;
        }

        //  Let's create some frames then
        var data = new Phaser.FrameData();
        var frames = xml.getElementsByTagName('SubTexture');
        var newFrame;

        var name;
        var frame;
        var x;
        var y;
        var width;
        var height;
        var frameX;
        var frameY;
        var frameWidth;
        var frameHeight;

        for (var i = 0; i < frames.length; i++)
        {
            frame = frames[i].attributes;

            name = frame.name.value;
            x = parseInt(frame.x.value, 10);
            y = parseInt(frame.y.value, 10);
            width = parseInt(frame.width.value, 10);
            height = parseInt(frame.height.value, 10);

            frameX = null;
            frameY = null;

            if (frame.frameX)
            {
                frameX = Math.abs(parseInt(frame.frameX.value, 10));
                frameY = Math.abs(parseInt(frame.frameY.value, 10));
                frameWidth = parseInt(frame.frameWidth.value, 10);
                frameHeight = parseInt(frame.frameHeight.value, 10);
            }

            newFrame = data.addFrame(new Phaser.Frame(i, x, y, width, height, name));

            //  Trimmed?
            if (frameX !== null || frameY !== null)
            {
                newFrame.setTrim(true, width, height, frameX, frameY, frameWidth, frameHeight);
            }
        }

        return data;
    }

};