libgdx and how i solved some problems i had

one has to keep him self busy, so this summer, as being away from the sea, i decided to go back to some android programming.
my initial idea was to create an app, but for UI i wanted to use a gaming framework. with the idea that it will provide me with many shortcuts of building a non-standard UI.

so where to start from?
I had some short experience with cocos2d and wanted to try something new. Unity seems to heavy-weight for my needs, so i flirted a bit with some of the complete tools, namely - GameSalad.
But it only lasted a few hours.

my developer self needed something more hands-on and then i read about libGdx.
So far i have great experience with it - setting it up is flawless, and the ability to immediately run on several platforms is, well, priceless.

the basic tutorial on the wiki gives good idea of what can be done, and there are some awesome other tutorials to hook input, physics (through box2d), graphics and gameplay:
* William Mora's A Running Game with libGDX give an excellent platform, code structure wise.
* the possibility to look in the code of an actual successful game, with full workflow comments, is priceless - many thanks to TheInvader360 for this
* the box2d tutorials from iforce2d were very deep and totally useful
* and of course the endless source of knowledge that is stackoverflow

sooo...i mixed it all in and went to the game that will conquer the gaming world.
one of the unique features would be that the user will swipe things from the screen with his fingers.

so i added the ActionGestureListener, hit Run and went clicking on my Actor, awaiting the debug messages in the console indication it has been hit.
but those messages never came.

alright...let see...Willam Mora's tutorial is very well structured - you have UserData, tied to Box2d bodies, added to the GameStage, twisting in the GameScene.
visually i hadn't implemented any sprites, relying on the wireframes to ensure the gameplay before adding any visual stunners.
and what i was seeing was some boxes moving around, firing things in the air and the box that i should be moving with fingers slowly descending. and not reacting in any way to my touch downs

ok, lets debug and see why touch events don't reach my Actor.
i hook into GameStage touchDown and eventually notice that it doesn't propage the event to the appropriate Actor.
Ah! so this is a bug in libGdx!
lets dig one more time, just a little deeper....wait, deciding whether Actor is hit checks some strange values...this cant be real, right? why my Actor has zeros for x, y; and for width, height as well?
definitely a bug in libGdx, and maybe in Box2d as well...crappy open source...or may be not?

box2d is actually doing all right - the bodies are moving around, falling as they are supposed to - magically and due to this amazing lib. so it is something about the Actor maybe?

then it hits me that the Actor x,y were only set initially at start and while box2d is doing all moving, it doesn't know about my actor, which is living in the libGdx world and i should be taking care of this myself.
alright - lets set the position of the actor.
where? this has to be in stage::update since this is where the code lands on every frame and every box2d step.
ok, but values to set the position to?
one of the biggest and most important advices is the keep everything in the same metric system. you see - box2d works and calculates in meters and kilograms as it tries to simulate the real world, while libGdx of course is more of a graphics library and so it needs to represent things in pixels.

so inevitably there will be problems transforming from box2d world to libgdx (screen/window) world.
so the actor is strictly tied to box2d bodies and in a way it also must live in box2d world, so its position x,y must be in box2d coordinates (usually floats).

at the same time the actor represent a screen entity - on screen it will be some sprite/picture and will need to react maybe to keypress, touch events. so these coordinates must somehow be related to the screen/pixel  coordinates. not to mention that keypress/touch events will send integer x,y to our handlers.

well, libGdx provides the invaluable unproject method. in the first versions of libGdx it was used via the camera, but later viewports were introduced and it should be access from there:

getViewport().unproject(touchPoint.set(x,y, 0));

the idea here is that touch/mouse events are received in screen coordinates - that is absolute x, y, according to the operating system, and the above unproject converts those to world coordinates - that is the world as libGdx sees it.
BUT
this is not enough!
libgdx coordinates are, simply put - integers - pixel coordinates, while our actor lives more in the box2d world; he's coordinates are more like (10f, 17f), while a mouse coordinates will be (339, 400).
luckily libgdx takes all this into account and if you debug into touchDown/hit you will see that the engine at each point converts to more and more specific coordinates in order to find the ultimate actor hit: screen to world, then world to stage and eventually parent to local; local being the coordinates with the shape bound to our body and to our actor's (rectangle?).

this is why it is very important to keep the actors' coordinates up current with the position of the box2d body.

but how to also keep them current in terms of positioning within the libgdx world?

for this the set up of the world must be created with box2d in mind:
say let the desired dimensions of screen are 800x480, then it would be nice box2d world to be 20f x 12f - notice the pixels and float dimensions - anyway, this gives us a nice ratio of 40 (800/20f) which is what we will use to convert actor's coordinates to world coordinates - so if the body is at (11f, 9f) and these are also actor's coordinates in box2d space, when we want to draw our actor's sprite, roughly what we need to do is multiply by the ratio above, giving us (440, 360) in libgdx coordinates - i'm not taking into account here center of object, width, height etc.

and now i notice that i wrote so much that this is turning into a small novel of my libgdx incompetence so it is about time i stopped.

hope this may help someone (as long as he/she's strong enough to read till the end...)