How do you read Phaser Documentation?

[DavidL]

Hi,

I've just started using Phaser and although I am creating things, my progress is quite slow. I am having trouble understanding how the documentation is meant to be used.

For example, I was creating a small game that involves the player clicking to move and double clicking to fire. So, I did something like this...

game.input.onTap.add(move);

function move() {
//Move the player
}

All seems to be well. Now, how do I detect a double click/tap? Wait! This is not my real question. I actually know the answer to this question, because I found an example here... http://phaser.io/examples/v2/input/on-tap

That shows me I can do this...

game.input.onTap.add(onTap, this);

function onTap(pointer, doubleTap) {

    if (doubleTap)
    {
        fire();        
    }
    else
    {
        move();
    }

}

So, my real question is, how was I to know that the function that onTap calls accepts these arguments (pointer and doubleTap in this case). As I say, I just happened to find the answer to this particular question in one of examples, but even now I know the answer, I can't find it mentioned in the documentation. The documentation here.. http://phaser.io/learn/chains mentions that the first argument when using game.input.onTap.add() should be 'The function to call when this Signal is dispatched', which is fine, but how do I know what arguments this function accepts? The API documentation gives me even less clues 'A Signal that is dispatched each time a pointer is tapped'.

Maybe I am missing something obvious but I feel that the documentation is really holding me back. What do/did others do when they first learnt Phaser?

Thanks,
DavidL

[carlosnufe]

PhaserJS is a heavy framework that gives us the power of to do awesome things, from simple to complex canvas creations (most commonly games). To address your question I need to say that you need to study the framework and understand how it works. There is no easy way, you will need to dive into the code and you will be able to link your question with the answer in a great number of times.

Firstly you need to see what the Input class does. When a new instance of Input is created are added two pointers.

(...)
Phaser.Input.prototype = {

    /**
    * Starts the Input Manager running.
    *
    * @method Phaser.Input#boot
    * @protected
    */
    boot: function () {

        this.mousePointer = new Phaser.Pointer(this.game, 0, Phaser.PointerMode.CURSOR);
        this.addPointer();
        this.addPointer();
(...)

So, you need to know or to search what the Pointer class methods can do. In this case the method stop() has the answer to your question.

(...)
/**
    * Called when the Pointer leaves the touchscreen.
    *
    * @method Phaser.Pointer#stop
    * @param {MouseEvent|PointerEvent|TouchEvent} event - The event passed up from the input handler.
    */
    stop: function (event) {

        var input = this.game.input;

        if (this._stateReset && this.withinGame)
        {
            event.preventDefault();
            return;
        }

        this.timeUp = this.game.time.time;

        if (input.multiInputOverride === Phaser.Input.MOUSE_OVERRIDES_TOUCH ||
            input.multiInputOverride === Phaser.Input.MOUSE_TOUCH_COMBINE ||
            (input.multiInputOverride === Phaser.Input.TOUCH_OVERRIDES_MOUSE && input.totalActivePointers === 0))
        {
            input.onUp.dispatch(this, event);

            //  Was it a tap?
            if (this.duration >= 0 && this.duration <= input.tapRate)
            {
                //  Was it a double-tap?
                if (this.timeUp - this.previousTapTime < input.doubleTapRate)
                {
                    //  Yes, let's dispatch the signal then with the 2nd parameter set to true
                    input.onTap.dispatch(this, true);
                }
                else
                {
                    //  Wasn't a double-tap, so dispatch a single tap signal
                    input.onTap.dispatch(this, false);
                }

                this.previousTapTime = this.timeUp;
            }
        }
(...)

As I said before it is not a easy way but never give up. Just keep calm and push again.

I hope I help you a little bit.

[drhayes]

You're right: the documentation for onTap isn't so great.

I have this problem with a lot of the Signals in Phaser. Whenever I find myself using a Signal I've never used before, I always do a "console.log(arguments);" in my listener function to see what arguments are getting sent its way. I also tend to read the source to find where the signals are dispatched by grepping the source directly. That led me here: https://github.com/photonstorm/phaser/blob/master/src/input/Pointer.js#L946

Not the best answer... although I'm fairly confident Rich would take a pull request on GitHub to improve the documentation for the onTap signal.