Android Tutorial Introduction to the libGDX library

Informatix · Sep 12, 2013

Introduction to the libGDX library

What is libGDX ?

libGDX is a game engine. As we saw in the first tutorial, a game engine provides a framework to create games and covers all aspects (rendering, animation, input, music, networking, physics, ...) of various kinds of games.

libGDX is considered as one of the best and fastest engine for the Android world. It is free, rich-featured, reliable, and proved its efficiency in a lot of well-known games (Ingress, Zombie Smasher, Apparatus, Monsterama Park, Clash of the Olympians, Bumbledore, etc.)

It’s a layered framework: it goes from low-level classes for OpenGL experts to high-level classes, easy to use by beginners. It includes a scene graph (Scene2D classes), a physics engine (Box2D classes), a particle system, a map renderer, a sprite batcher, an extensive set of mathematics classes… more than 200 classes in total.

For technical reasons, the version for Basic4Android cannot be multi-platform, and by choice, the current release doesn't include the 3D classes (except the ones for the perspective camera and for the decals) and the Daydream class.

libGDX was created in 2010 by Mario Zechner (badlogicgames.com) and is maintained by M. Zechner, Nathan Sweet (esotericsoftware.com) and a community of developers.

Minimum requirements

OpenGL ES 2.0
Android Froyo (API 8)

Hardware acceleration

libGDX does not require that you enable hardware acceleration on your device because it is based on OpenGL, which interacts directly with the GPU.

Debugging

You cannot use the debugger of B4A with libGDX because most of the code of the library runs in a different thread. You have to use the Log() function to debug your game.

The library provides a debug renderer for Box2D (lgBox2DDebugRenderer), a debug renderer for Scene2D (lgScn2DDebugRenderer) and a profiler for OpenGL (lgGLProfiler).

A word about the classes

The main class is LibGDX. All other classes are prefixed by lg.
All Box2D classes are prefixed by lgBox2D. All Scene2D classes are prefixed by lgScn2D. All Map classes are prefixed by lgMap. All Math classes are prefixed by lgMath.

The LibGDX class gives access to five interfaces: Audio (lgAudio), Files (lgFiles), Graphics (lgGraphics), Input (lgInput), and Net (lgNet). You will use the Input interface, for example, to get the input from the accelerometer.

With some classes (e.g. the five interfaces), you cannot create a new instance with Dim. You have to use an instance returned by the library. For example, you cannot write:

B4X:

Dim Graphics As lgGraphics
Graphics = lGdx.Graphics

but you can write:

B4X:

Dim Graphics As lgGraphics = lGdx.Graphics

Some classes cannot be instantiated at all because they are generic classes (e.g. com.badlogic.gdx.scenes.scene2d.utils.Drawable or com.badlogic.gdx.maps.tiled.TiledMapTile). In this case, either you store their instance as an Object or you use a subclass, e.g.:

B4X:

Dim objTile As Object = CurrentLayer.GetCell(X, Y).Tile
Dim staticTile As lgMapStaticTiledMapTile = CurrentLayer.GetCell(X, Y).Tile

OpenGL ES

I explained what OpenGL is in the previous tutorial and I won't discuss it further here because the main advantage to use a game engine like libGDX is to benefit from the abstraction layer above OpenGL. However, if you need (or want) to call directly OpenGL, here's how to get access to the classes and functions:

B4X:

Dim lGdx_GL20 As lgGL20 = lGdx.Graphics.GL20

or better (includes also the constants):

B4X:

Dim GL As lgGL

Note: libGDX uses the 2D coordinate system and the color encoding of OpenGL ES, so the Y-axis is pointing upwards and each color value ranges from 0 to 1.

The libGDX life-cycle

An important thing to keep in mind about libGDX is that it runs in its own thread. Your Basic4Android application runs most of the time in a different thread called the UI thread, or main thread. That means you cannot access the other views of your activity and change their properties from the libGDX thread. Fortunately, there's a function in the LibGDX class that passes the runnable (the piece of code to execute) from a thread to the other: CallSubUI. So if you want to change the activity title, set a label text or show a MsgBox from the libGDX thread, don't forget to use this function to avoid a crash!

Since libGDX runs in a different thread, you have to inform its library of the events of your activity : Create, Pause and Resume. First, create an instance of libGDX in Globals :

B4X:

Dim lGdx As libGDX

In Activity_Create (and nowhere else), add the Initialize function :

B4X:

lGdx.Initialize(False, "LG") 'fills the activity with the libGDX surface, uses OpenGL 1 for compatibility and prefixes the events with LG

In Activity_Resume, add the following line :

B4X:

If lGdx.IsInitialized Then lGdx.Resume

In Activity_Pause, add the following line :

B4X:

If lGdx.IsInitialized Then lGdx.Pause

You could initialize libGDX differently. For example, it could be limited to a view with InitializeView. You could also define a configuration (lgConfiguration class) and pass it to libGDX. Example:

B4X:

Dim Config As lgConfiguration

'Disables the accelerometer and the compass
Config.useAccelerometer = False
Config.useCompass = False

'Uses a WakeLock (the device will stay on)
Config.useWakelock = True

'Creates the libGDX surface
lGdx.Initialize2(Config, "LG")

Once done, your library is ready to raise the events of its life-cycle : Create, Resize, Render, Pause, Resume, Dispose. These events are the place to put all the code of your game. Don't put anything in the usual activity events. They are reserved for your other views and are raised by the UI thread.

Create :

Create is the first raised event. It is raised soon after the initialization of the library and the creation of the OpenGL surface.
In this event, initialize your renderer and your input processors, load your resources (we'll see that in detail later) and initialize your game data.

Resize :

Resize is raised when the size of the libGDX surface changes. Under Android, that should only happen when you start the application and when it is restarted after a rotation or resumed.
It is raised at least once, after Create, and, when the application is resumed, just before Resume.
In this event, initialize the camera viewport. It's probably the only use you will find for it.
This event returns the new width and height in pixels.

Render :

Render is raised as soon as possible after Create and Resize.
It's where things are drawn. It's also where you have to put the logic of your game, but I would not recommend putting hundreds of lines of code here. Instead, create new subs and new modules and call them from this event.
The first lines in Render should be to clear the screen. Example:

B4X:

lGdx_GL.glClearColor(0, 0, 1, 1) 'Blue background
lGdx_GL.glClear(lGdx_GL.GL10_COLOR_BUFFER_BIT)

Pause :

Pause is raised when the activity is sent in the background, rotated or exited.
It's the right place to save your game data.
Note that the OpenGL context is destroyed when the app goes in the background, so all your unmanaged textures and pixmaps have to be reloaded or recreated in the Resume event when the app returns to the foreground.

Resume :

Contrary to the Resume event of your activity, this one is not raised after Create, only when the application returns from a pause.
As the OpenGL context is destroyed when the app goes in the background, all your unmanaged* textures and pixmaps have to be reloaded or recreated when this event is raised. More info here. *Not loaded by an asset manager.

Dispose :

Dispose is called when the activity is exited, after Pause, or when the device is rotated.
In this event, release all the used resources by calling the Dispose function of objects (if they have one).

The life-cycle :

Multiple screens

A game is made of many screens. You could create an activity for each one, but that would not be very convenient because you'd have to reinitialize the library in each activity and reload some resources. Moreover, that would not ease any graphical transition between screens. In fact, most games are made with a very small number of activities and make use of a screen manager instead. The screen manager stores the reference of the different screens and allows switching between them. Each screen has its own life-cycle.
To create a screen manager with two screens, for example, declare them in Globals:

B4X:

Dim lGdx_ScrMgr As lgScreenManager
Dim lGdx_Screen(2) As lgScreen

Then add these lines in the Create event handler:

B4X:

'Creates two screens
lGdx_ScrMgr.Initialize(lGdx)
lGdx_Screen(0) = lGdx_ScrMgr.AddScreen("LGS1")
lGdx_Screen(1) = lGdx_ScrMgr.AddScreen("LGS2")

Show the first screen:

B4X:

lGdx_ScrMgr.CurrentScreen = lGdx_Screen(0)

When you want to change the current screen, just change the value of the CurrentScreen property. That will raise the Hide event of the previous screen and the Show event of the new one.

The screens have the same life-cycle as the library, and thus the same events except that Create is named Show and Dispose is named Hide.

Input processor and gesture detector

To get the input events raised by your players, you have to declare input processors. libGDX has an input processor for keyboard and touch events (lgInputProcessor) and a specialized input processor for gestures (lgGestureDetector).
Start by declaring them in Globals:

B4X:

Dim lGdx_IP As lgInputProcessor
Dim lGdx_GD As lgGestureDetector

Initialize them in the Create event (or the Show event of a screen if you want different processors for different screens):

B4X:

lGdx_IP.Initialize("IP")
lGdx_GD.Initialize("GD")

And add the event handlers that you need:

B4X:

Sub IP_KeyDown(KeyCode As Int) As Boolean
   Return False
End Sub

Sub IP_KeyUp(KeyCode As Int) As Boolean
   Return False
End Sub

Sub IP_KeyTyped(Character As Char) As Boolean
   Return False
End Sub

Sub IP_TouchDown(ScreenX As Int, ScreenY As Int, Pointer As Int) As Boolean
   Return False
End Sub

Sub IP_TouchDragged(ScreenX As Int, ScreenY As Int, Pointer As Int) As Boolean
   Return False
End Sub

Sub IP_TouchUp(ScreenX As Int, ScreenY As Int, Pointer As Int) As Boolean
   Return False
End Sub

Sub GD_TouchDown(X As Float, Y As Float, Pointer As Int) As Boolean
   Return False
End Sub

Sub GD_Fling(VelocityX As Float, VelocityY As Float) As Boolean
   Return False
End Sub

Sub GD_LongPress(X As Float, Y As Float) As Boolean
   Return False
End Sub

Sub GD_Pan(X As Float, Y As Float, DeltaX As Float, DeltaY As Float) As Boolean
   Return False
End Sub

Sub GD_Pinch(InitialPointer1 As lgMathVector2, InitialPointer2 As lgMathVector2, Pointer1 As lgMathVector2, Pointer2 As lgMathVector2) As Boolean
   Return False
End Sub

Sub GD_Tap(X As Float, Y As Float, Count As Int) As Boolean
   Return False
End Sub

Sub GD_Zoom(InitialDistance As Float, Distance As Float) As Boolean
    Return False
End Sub

Description of events :

Fling: The user quickly dragged a finger across the screen, then lifted it. Useful to implement swipe gestures.
Pan: The user is dragging a finger across the screen. The detector reports the current touch coordinates as well as the delta between the current and previous touch positions. Useful to implement camera panning in 2D.
Pinch: Similar to zoom. The detector reports the initial and current finger positions instead of the distance. Useful to implement camera zooming and more sophisticated gestures such as rotation.
Tap: The user touched the screen and lifted the finger. The finger must not move outside a specified square area around the initial touch position for a tap to be registered. Multiple consecutive taps will be detected if the user performs taps within a specified time interval.
Zoom: The user has placed two fingers on the screen and is moving them together/apart. The detector reports both the initial and current distance between fingers in pixels. Useful to implement camera zooming.

The other events are self-explanatory.

.....

Informatix · Aug 2, 2016

wonder said:
Yep this and also making sure that, if you're using floats or doubles for your tile placement, the drawing "step" must be constant.

In my case:
BAD (before):
- Calculate tile placement (x, y) As Double
- Draw at (x, y)

GOOD (after):
- Calculate the placement of the first tile (x, y)
- Draw all the remainng tiles at (double) FirstTile_Offset(x, y) + (int) TileIterator(x, y) * (int) TileSize(x, y)

Example:

B4X:

FirstTileX = 23.56 FirstTileY = 87.489 Dim w, h as Int Dim x, y as Double For ix = 0 To (maxHorizontalTilesOnScreen - 1) For iy = 0 To (maxVerticalTilesOnScreen - 1) w = TileWidth h = TileHeight x = FirstTileX + (ix * w) y = FirstTileY + (iy * h) Batch.DrawRegion2(tile, x, y, w, h) Next Next

libGDX almost never uses double values, only float values. If you limit your computations to two or three decimal places after the dot, Float is enough and saves a bit of memory. And since the pixels cannot be divided, you should use only integers with your method; you place the first tile at (intX, intY), then you place other tiles at (intX+intOffsetX, intY+intOffsetY). This is how proceeds the OrthogonalTiledMapRenderer class.

wonder · Aug 2, 2016

You're right about doubles being overkill when LibGDX uses only floats... It's just an old habit of mine to favor Doubles over Floats.

Nonetheless, I do experience difference behaviour (movement) when switching between Ints and Doubles/Floats. At first, it made no sense to me as well. After all, there is indeed no such thing as a half-pixel.

Soon, however, I came to realize that Photoshop, for example, does allow you to place guides at pixel locations with decimal places. Googling around, my curiosity took me to this webpage, which has it demonstrated pretty well (at least for CSS): http://atirip.com/2013/09/22/yes-we-can-do-fraction-of-a-pixel/

So long story short, (EDIT: If your game has a lot of movement) I think it's okay (and I even recommend) to use pixel values with decimal places (Float).
I can make a comprasion video of Ints vs Floats, if necessary.

Informatix · Aug 2, 2016

wonder said:
You're right about doubles being overkill when LibGDX uses only floats... It's just an old habit of mine to favor doubles to floats.

Nonetheless, I do experience difference behaviour (movement) when switching between Ints and Doubles/Floats. At first, it made no sense to me as well. After all, there is indeed no such thing as a half-pixel.

Soon, however, I came to realize that Photoshop, for example, does allow you to place guides at pixel locations with decimal places. Googling around, my curiosity took me to this webpage, which as it explained pretty well: http://atirip.com/2013/09/22/yes-we-can-do-fraction-of-a-pixel/

So long story short, I think it's okay (and I even recommend) to use pixel values with decimal places (Float). I can make a comprasion video of Ints vs Floats, if necessary.

I considered that your camera unit was the pixel. It could be something very different (especially if you use Box2D) and my advice would be stupid indeed. However I think that you misunderstood me. I suggested to use integers only when you draw your tiles, not everywhere. In my apps, I use floats also to store X and Y, and to do all computations. You could get very inaccurate results if you used only integers (e.g. when you scale something).
Anyway, if you use another unit than the pixel for your camera, you can forget my advice.

wonder · Aug 2, 2016

True, I might have misunderstood you, I was thinking about a "tile" being something like a moving spaceship...
Well, as long as it "feels great, looks good and plays well", there's no need to overthink subject too much.

ilan · Oct 31, 2016

hi,

i need a little bit help and i really searched before in the forum and also tried all libgdx examples but i could not figure out how to solve my problem

i am looking for a view that i can handle touch down and touch up.
the lgScn2DButton only recognize a click but what i need is a view that on touch an action will perform and on release that action will stop like a Gas Pedal in a racing game.

and also if i exit that view the touch up should fire like if i touch it down and then hold down and move my finger out of the screen while it is touching the screen then the touch up should be fired. is there such a view in libgdx?

thanx, ilan

Informatix · Oct 31, 2016

ilan said:
hi,

i need a little bit help and i really searched before in the forum and also tried all libgdx examples but i could not figure out how to solve my problem

i am looking for a view that i can handle touch down and touch up.
the lgScn2DButton only recognize a click but what i need is a view that on touch an action will perform and on release that action will stop like a Gas Pedal in a racing game.

and also if i exit that view the touch up should fire like if i touch it down and then hold down and move my finger out of the screen while it is touching the screen then the touch up should be fired. is there such a view in libgdx?

thanx, ilan

Add an lgScn2DInputListener (or a lgScn2DGestureListener) to your view so you can handle the TouchDown/TouchUp events.
This is explained at the beginning of this thread in the Scene2D chapters.

ilan · Oct 31, 2016

Informatix said:
Add an lgScn2DInputListener (or a lgScn2DGestureListener) to your view so you can handle the TouchDown/TouchUp events.

thank you informatix so i could use an lgScn2DImage and add to it an lgScn2DInputListener?
hmm why i have not think of it?

Informatix · Oct 31, 2016

ilan said:
thank you informatix so i could use an lgScn2DImage and add to it an lgScn2DInputListener?
hmm why i have not think of it?

Yes.

ilan · Oct 31, 2016

another question please, to make a level selcetion menu should i add all Actors (lgScn2DImage or lgScn2DButton) to a Stage and like this i could animate the whole stage with interpolation?

Informatix · Oct 31, 2016

ilan said:
another question please, to make a level selcetion menu should i add all Actors (lgScn2DImage or lgScn2DButton) to a Stage and like this i could animate the whole stage with interpolation?

I'm not sure to understand the question. First because all actors are always added to a stage (or they are useless) and second because you can animate any group of actors, not only the stage.

ilan · Oct 31, 2016

Informatix said:
or they are useless

ok, i didnot knew that. this is the first time i am going to work with stages.

Informatix · Oct 31, 2016

ilan said:
ok, i didnot knew that. this is the first time i am going to work with stages.

The stage is like the activity. You place all your actors on the stage, either directly or in a group (= a panel).

ilan · Oct 31, 2016

ok i have managed to add a stage with an actor to it and add a inputlistner to the actor.

what i have noticed is that the lgInputProcessor events will still fire if i touch the actor.
so i get now 2 logs (1 touch down from the lginputprocessor and 1 from the inputlistner of the actor)
is there a way to avoid the lginputprocessor to fire when i touch the actor?

another thing i noticed is that if i touchdown the actor and slide my finger out of it the touchup will not fire until i stop touching the screen even i am out of the actor bounds.
is there a way to get the touch up event fire when i am out of the actor bounds?

thanks a lot, ilan

EDIT: ok i solved issue nr. 1, it depends what you intialize first. if you intialize the inputlistner then the lginputprocessor will not fire.

Informatix · Nov 1, 2016

ilan said:
ok i have managed to add a stage with an actor to it and add a inputlistner to the actor.

what i have noticed is that the lgInputProcessor events will still fire if i touch the actor.
so i get now 2 logs (1 touch down from the lginputprocessor and 1 from the inputlistner of the actor)
is there a way to avoid the lginputprocessor to fire when i touch the actor?

another thing i noticed is that if i touchdown the actor and slide my finger out of it the touchup will not fire until i stop touching the screen even i am out of the actor bounds.
is there a way to get the touch up event fire when i am out of the actor bounds?

thanks a lot, ilan

EDIT: ok i solved issue nr. 1, it depends what you intialize first. if you intialize the inputlistner then the lginputprocessor will not fire.

There's no reason to trigger a TouchUp while the finger is still down (or the event has a meaningless name). If you want to know if the finger is out of the actor bounds, use the Exit event.

ilan · Nov 3, 2016

hi, (again a small question )

i am working on a box2d + libgdx game.
i am using several lgScn2DStage in my game but the problem is that the last stage is blocking other stage actor getting touch events.

so the stage that is intialized last will get all touch. how can i disable a stage so i can move another stage and click on his Actors?

EDIT: i tried gamestage0.UnfocusAll but i still cannot touch on actors in other stage.

Informatix · Nov 3, 2016

ilan said:
hi, (again a small question )

i am working on a box2d + libgdx game.
i am using several lgScn2DStage in my game but the problem is that the last stage is blocking other stage actor getting touch events.

so the stage that is intialized last will get all touch. how can i disable a stage so i can move another stage and click on his Actors?

If you have more than one stage per screen, there's something wrong in your design. The stage is like an activity. Would you create many activities for the same screen in a standard app?

ilan · Nov 3, 2016

Informatix said:
If you have more than one stage per screen, there's something wrong in your design. The stage is like an activity. Would you create many activities for the same screen in a standard app?

but i need more then 1 stage.
1 stage is for the buttons and they are static but another stage is the same size like my world (box2d) and i add actors to it so i can add interpolation to them (coins flying).
and it is working fine. now i wanted to add another stage as the menu but if it is not possible i will use the same stage as for the controls (that are static) also for the menu and draw everything on the right time (ingame = true or inmenu = true)

can i add interpolation to a box2d body?

ilan · Nov 3, 2016

btw this is what i did so far: https://www.b4x.com/android/forum/threads/my-platform-game.72618/

Informatix · Nov 3, 2016

ilan said:
but i need more then 1 stage.
1 stage is for the buttons and they are static but another stage is the same size like my world (box2d) and i add actors to it so i can add interpolation to them (coins flying).
and it is working fine. now i wanted to add another stage as the menu but if it is not possible i will use the same stage as for the controls (that are static) also for the menu and draw everything on the right time (ingame = true or inmenu = true)

and i add interpolation to a box2d body?

Be aware that the library is not designed for more than one stage per screen, so you will probably face troubles. I cannot guarantee that the event system will work reliably in such a context.
I'm sorry but I can't see the reason to have a stage for the buttons, a stage for the menu, a stage for the Box2D world, etc. Why don't you use the same stage for everything? The distinction between static and dynamic actors is absolutely not relevant. I could understand that you want to support different coordinate systems, with multiple cameras and viewports, but that sounds a bit complicated to manage and simplicity is probably better.
I made three "complex" games, with two of them having heavily loaded stages, and I did not see any reason to have more than one stage, so you're in an uncharted territory for me.

ilan · Nov 3, 2016

thank you a lot fred for your explanation. i thought i could use a stage like a panel but u r right i will redesign my game.
i will use only 1 stage and for the coin flying effect i will just apply a force or set the Linear Velocity of the body instead of using interpolation on an actor.

2 small question please.

1. can i group lgscnactors together? and move them around or do i have to do it for each actor?
2. hiding the actor will prevent calling the listener touch event when clicking on that area (like a normal android button)?

thank you, your help is very much appreciated

Android Tutorial Introduction to the libGDX library

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Expert

Similar Threads

Privacy & Transparency

Privacy & Transparency