I have no clue how to read the API!

[byviolet]

I'm super new to phaser and new to html development in general. I'm sort of just looking at code and trying to figure out things as I go. One big problem I have is that I cannot decipher the API. For example, if I see a line of code that says  "game.state.add('Boot', BasicGame.Boot)", I cannot find a reference in the API. I see this link: http://docs.phaser.io/Phaser.State.html

What is Phaser.state? Why is it not game.state? If I click on add it takes me to http://docs.phaser.io/Phaser.GameObjectFactory.html. Ok, cool. Where is the part where it explains the .add() function? 

It's just very confusing to me. Coming from someone who totally understands MDN's layout and explanation for js, I have no clue where to find the resources I need to figure anything out

[rich]

    //  When a State is added to Phaser it automatically has the following properties set on it, even if they already exist:

    this.game;      //  a reference to the currently running game (Phaser.Game)

    this.add;       //  used to add sprites, text, groups, etc (Phaser.GameObjectFactory)

    this.camera;    //  a reference to the game camera (Phaser.Camera)

    this.cache;     //  the game cache (Phaser.Cache)

    this.input;     //  the global input manager. You can access this.input.keyboard, this.input.mouse, as well from it. (Phaser.Input)

    this.load;      //  for preloading assets (Phaser.Loader)

    this.math;      //  lots of useful common math operations (Phaser.Math)

    this.sound;     //  the sound manager - add a sound, play one, set-up markers, etc (Phaser.SoundManager)

    this.stage;     //  the game stage (Phaser.Stage)

    this.time;      //  the clock (Phaser.Time)

    this.tweens;    //  the tween manager (Phaser.TweenManager)

    this.state;     //  the state manager (Phaser.StateManager)

    this.world;     //  the game world (Phaser.World)

    this.particles; //  the particle manager (Phaser.Particles)

    this.physics;   //  the physics manager (Phaser.Physics)

    this.rnd;       //  the repeatable random number generator (Phaser.RandomDataGenerator)

    //  You can use any of these from any function within this State.

    //  But do consider them as being 'reserved words', i.e. don't create a property for your own game called "world" or you'll over-write the world reference.

[Dumtard]

game.state.add is not Phaser.State.add it is Phaser.StateManager.add.

To read the documentation start at the base and work your way up. Start at Phaser.Game then find its state variable which is a Phaser.StateManager then you can find it's add method.

[JUL]

I've started to learn phaser with this game, it's a ghosts'n goblins clone made with phaser.

http://www.html5gamedevs.com/topic/7164-ghostsn-goblins-made-with-phaser/

 

 

 

http://www.int33h.com/test/gng/

 

 

All the code is in one big file if memory serves.

For starters it's very useful I think, very straight forward, preloading screen included.

 

It's with version 2.0.5 nonetheless...

[eguneys]

I think Phaser docs lacks some information. However If you want to really learn Phaser, I recommend start with Pixi, use it to build a fairly complete game, implement your own object pooling, and state management and things like that, so you will have a better understanding what problems Phaser is solving for you. Specifically I started with this tutorial and implementing this sample game which uses Flixel, that is the Phaser equivalent in AS3. And here's my implementation of canabalt using only Pixi.

[lewster32]

That seems like a crazy way to do it eguneys! Phaser builds on top of pixi to make all of that stuff much easier. If you're able to implement all of those things yourself, you'd probably not need to use Phaser, and you'd certainly not be struggling to understand the API! I could see people mastering Phaser and wanting to get 'closer to the metal' by moving on to pixi, but the other way around seems a pretty illogical scenario to me.

[eguneys]

@lewster32, I am not talking about a goal to implement next Phaser, I am talking about struggling your way to the goal to learn along the way. Of course your solutions to object pooling will be crappy and inefficient, but once you switch to Phaser, you will have a better understanding and appreciation what Phaser provides. I didn't made up that story, it's my real story. You can check out my sample canabalt game using Pixi, it has three different implementations of simple physics, and weird collision detection, but it doesn't matter.

 

Btw you haven't commented on my lose your marbles game, make sure to check it out.

[lewster32]

No you get me wrong - I understand that people can (and indeed have, in your case) go down this route, but it's very counter-intuitive and I certainly wouldn't recommend it if given the choice. Phaser makes working with pixi a lot easier from a newcomer's point of view (hence why there's a large community of first-time JavaScript users on this forum) but when people get comfortable with how it works, then sometimes (like in my case) they can start delving into the 'lower level' stuff that is pixi itself.

 

Oh and I'll be sure to check your game out - I've been very busy lately with game jams and such

[byviolet]

I guess what I'm wondering is that I can't figure out where everything is organized. When you go to MDN's directory for example, if I look at a push() function you can immediately tell that push is a prototype of array, which is a standard object in javascript. They tell me what it does, and gives clear simple examples. If I search up phaser.game in the docs I'm immediately confused. What's new Game(width,height,renderer,parent,state,transparent,antialias,physicsConfig)? Of course I know what it is after I read a guide on making a phaser game but I feel this information should be readily available in the docs itself.  Then I'm more confused by the 'members'. What's a member? Why is 'game' a member? Does this mean I can do something like Game.StateManager.add() and expect it to do something? What are methods (if they are the same as in vanilla js even?) and why are they different from members? If I find a method called clearCurrentstate() how do I use it? do I still have to do something like game.state.clearCurrentstate()? 

 

What does StateManager come in? etc etc, I'm just confused towards the organization and how to use the docs and all of the guides simply tell you how something works, they don't tell you how to read the docs. I can't figure out how to piece everything together.

[Glaydur]

As a fellow newbie, I'm also find the docs really hard to navigate. The quick search bar just isn't what I need, it's pretty useless. So what I have been using is google instead. Like so: KEYWORD site:docs.phaser.io and that usually does the job. Of course you can replace KEYWORD with anything you like.

 

As to how everything works, I find that you learn it with time(at least for me). The doc can't teach you that. It's just a reference if you need to remember something. I went through a lot of tutorials before finally making my own game. Be sure to go through the phaser examples too, they're a great help

[ram64]

I guess what I'm wondering is that I can't figure out where everything is organized. When you go to MDN's directory for example, if I look at a push() function you can immediately tell that push is a prototype of array, which is a standard object in javascript. They tell me what it does, and gives clear simple examples. If I search up phaser.game in the docs I'm immediately confused. What's new Game(width,height,renderer,parent,state,transparent,antialias,physicsConfig)? Of course I know what it is after I read a guide on making a phaser game but I feel this information should be readily available in the docs itself.  Then I'm more confused by the 'members'. What's a member? Why is 'game' a member? Does this mean I can do something like Game.StateManager.add() and expect it to do something? What are methods (if they are the same as in vanilla js even?) and why are they different from members? If I find a method called clearCurrentstate() how do I use it? do I still have to do something like game.state.clearCurrentstate()? 

 

What does StateManager come in? etc etc, I'm just confused towards the organization and how to use the docs and all of the guides simply tell you how something works, they don't tell you how to read the docs. I can't figure out how to piece everything together.

 

Those are OOP terms, you should dive a bit in object oriented programming to understand the terminology.

 

- members refer to member properties of the class (maybe here's the confusion, as everything part of a class is a member):

"A member variable is a member of a class (class variable) or amember of an object instantiated from that class (instance variable). It must be declared within a class, but not within the body of a method of the class."

 

- methods are functions of the class:

"A method (or a member function) in OOP is a subroutine associated with an object of a class that forms its interface through which the outside members of the class (other objects) can access its private members (mainly the encapsulated data)."

 

You will find most OOP terms with their definitions and other details on Wikipedia.

 

Other than that you should go through the examples to see how thing are working, the documentation alone isn't enough. I agree that it should be better organized and have further details (maybe code samples) but it still can give you details about usage.

[Sebi]

The best advice that I can give is to take just a few hours 1 day per week to study the phaser source.

Try to understand what is going on in the background. It really is not that complicated.

That will allow you to organize your code better, improve your coding style and you will be able to get things done faster.

On top of that, you will learn how to find the solutions to your problems in a matter of minutes instead of googling hours.

This has always been the difference between people who only use a framework and people who undertand it.

Most people are like "I have spent days just to find out why my tilemap is not working correctly" and similiar problems, but if you spend the same amount of time on studying the source, you will not run into that kind of problem anymore and in the long run this will not only save you a lot of time but also money.

[Arcanorum]

Personally I think that content of the docs would be more useful in more of a wiki format, where people can add/expand/refine definitions, add examples, use cases, common problems and their solutions, etc.

 

Maybe a HTML5 Game Dev wiki with a section for Phaser or (your framework of choice)?

[mwatt]

I too had a great deal of initial confusion.  Much of this surrounded the usage of multiple states vs. single states and the usage of a global game variable vs. accessing methods and members via the syntax used within states.  However, I was confused about a lot of things - and I am a seasoned JavaScript developer.  Like you, I found that the docs, while extensive, where not as helpful as I would have liked while I was in a heavy learning phase.

 

If you are interested in using multiple states, It doesn't help that nearly all examples, demos, short games, etc. use a single state approach.  This includes "official" Phaser examples as well as those provided by the community.  There seem to be a number of people who experience discomfort over the State mechanism.  On the other hand, there seem to be a large number of people who are fine with it, or perhaps many don't use it.

 

To help someone "booting up" with Phaser, the docs would have been much more helpful if they had examples.  Granted, there is a disconnected (not linked to the documentation) suite of runnable examples available which are helpful, but they are snippets of code and very fine-grained.  They also do not show things in the context of a multi-state approach. 

 

The basal problem is that there is a tremendous amount of work in creating and growing a game engine / API.  Creating and maintaining good documentation while this happens is prohibitively difficult.  Rich can only do so much at once. He is however, working on a series of focused books that you can buy online very cheaply.  This will help (two are already available and one on State Manager is possibly in the offing).

 

Something that helped me tremendously, again very cheaply, is an online course at Zenva (https://academy.zenva.com): "HTML5 Mobile Game Development with Phaser".  The course was pretty clear and offered a nice mix of basic concepts and in-depth information.  The game that you build throughout the tutorial takes a full multi-state approach.  Aside from a small number of idiosyncracies, it was very good - well worth the small amount of cash you have to pony up.

[MichaelD]

Its true what others have said, Phaser documentation doesn't look like or could look like the MDN docs, but it is more closely related to the Java Api Docs because of its Object Oriented nature.

Truth is it gets a little while to get used to it, but in time it will become more clear and helpful. 

 

However a global search for "keywords" should come in handy in any case, or some linkage between the classes and their parents/children.

[omnivibe]

Coming most recently from Flash/Starling and Unity to HTML5/Phaser, the Phaser docs *really* need some love and attention in terms of readability.

 

The information is all there (thanks!)- it just some better separation of description and sections and headers...

 

Just compare these pages on RenderTexture:

 

http://docs.unity3d.com/ScriptReference/RenderTexture.html (Unity)

 

vs.

 

http://doc.starling-framework.org/core/starling/textures/RenderTexture.html (Flash/Starling)

 

vs. 

 

http://docs.phaser.io/Phaser.RenderTexture.html (Phaser)

[rich]

Compare the company / team size / turn-over of Unity (and Adobe) to ... well, me. As no-one else helps that much with the docs. If someone feels like donating a significant pile of cash to the project then I'll gladly invest it in documentation authors.

[omnivibe]

I definitely hear that, and thanks for making it as good as it is! Hope you can find the investors to make it even better