Android Tutorial Introduction to the libGDX library

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:

Dim Graphics As lgGraphics
Graphics = lGdx.Graphics

but you can write:

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.:

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:

Dim lGdx_GL20 As lgGL20 = lGdx.Graphics.GL20

or better (includes also the constants):

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 :

Dim lGdx As libGDX

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

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 :

If lGdx.IsInitialized Then lGdx.Resume

In Activity_Pause, add the following line :

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:

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:

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:

Dim lGdx_ScrMgr As lgScreenManager
Dim lGdx_Screen(2) As lgScreen

Then add these lines in the Create event handler:

'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:

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:

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):

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

And add the event handlers that you need:

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.

.....

 

[MarcTG]

It is not planned in the near future.
The current owner of the wrapped library is Anywhere Software (Erel) so I won't take big decisions about it and, personally, I don't have neither the time nor the desire to work on these classes.
Please note that it already exists a library for 3D objects: jPCT-AE.

Thanks Fred, i did not know that this library existed.This might be a silly question, but can this 3d library be used in libgdx lwp? If not, can we even use it in any lwp in b4a?

Thanks

 

[Informatix]

This might be a silly question, but can this 3d library be used in libgdx lwp? If not, can we even use it in any lwp in b4a?

"No" to the first question. It's a completely different set of classes.
And "I don't know" for the second question. I never created anything in 3D, so I just tried once jpCT-AE to be sure that it works. Nothing more.

 

[KMatle]

Hi guys,

just started to play with libgdx. Very cool.

Some questions: As I see it, the lib has been adapted for b4a? If yes, what about updates (just to be sure)? Or is it the original lib and the tutorial shows how to implement it in b4a?

 

[Informatix]

Some questions: As I see it, the lib has been adapted for b4a? If yes, what about updates (just to be sure)? Or is it the original lib and the tutorial shows how to implement it in b4a?

This lib won't be updated in a near future. I explained why here. Just to give you an idea, there are more than 200 classes and several changes are commited every week in the official library. After a few weeks, there are so many changes that updating the lib takes a full day of work. I let you imagine after a few months. Contrary to what is done in the official project, I try to test every change and rewrite messy or unstable parts, so that needs time and I cannot afford this any longer.
You cannot use directly the original library (as the other libraries for B4A, it needs to be wrapped), and to speak frankly, I trust more my version than the official one.

 

[KMatle]

Thank's for that great work. My intention was to clear out what I expected anyway. And yes... more trust in your work: agree+++++

 

[wonder]

Hello Fred,

Once again I need your help....

Imagine I have a game with 100 levels, large textures.

Do I need to load everything at the Create event like this?

Sub LG_Create
    'Initializes the renderer
    Batch.Initialize   
   
    For iii = 0 To 99   
        stage_source(iii).Initialize(stage_source_file(iii))
        stage(iii).InitializeWithTexture(stage_source(iii))       
    Next
   
End Sub

or is there another way to load the assets along the game?

 

[Informatix]

Hello Fred,

Once again I need your help....

Imagine I have a game with 100 levels, large textures.

Do I need to load everything at the Create event like this?

Sub LG_Create
    'Initializes the renderer
    Batch.Initialize 
 
    For iii = 0 To 99 
        stage_source(iii).Initialize(stage_source_file(iii))
        stage(iii).InitializeWithTexture(stage_source(iii))     
    Next
 
End Sub

or is there another way to load the assets along the game?

Everything is possible. You can load all assets at the beginning of the game like a lot of games do (so there will be no loading time during the game) or you can load only the textures that you need, and replace them later by other textures. Maybe loading all textures at the beginning is too long and should be splitted. Only you have the answer.
To load your assets, I strongly recommend to use the Asset Manager.

 

[wonder]

Hello again,

I know this might be very simple to implement, but I'm currently having kind of a brain freeze.

This is my "load textures" (short version) code so far:

Sub Globals
    'These global variables will be redeclared each time the activity is created.
    'These variables can only be accessed from this module.
    Dim kkkkk As Float
    'GDX
        Dim lGdx As LibGDX
        Dim Gl As lgGL
        Dim Camera As lgOrthographicCamera
        Dim Batch As lgSpriteBatch
       
        Dim stage_source(number_of_stages) As lgTexture
        Dim actor_source(number_of_actors) As lgTexture
       
        Dim stage(number_of_stages) As lgTextureRegion
        Dim actor(number_of_actors) As lgTextureRegion
      
        Dim GLView As View
        Dim Animate = False As Boolean
End Sub


Sub LG_Create
    'Initializes the renderer   
    Batch.Initialize
    Set_First_Cycle
       
    For iii = 0 To (number_of_actors - 1)   
        actor_source(iii).Initialize(sprite_source(iii))
        actor(iii).InitializeWithTexture(actor_source(iii))        
    Next
End Sub


Sub Setup_Ryu   
    active_actor = Ryu
    actor_unique_ID(active_actor) = "RYU"
   
    actor_type(active_actor) = "PLAYER"
   
    sprite_source(active_actor) = "image1.png"
End Sub

What would be the best way to implement various "pages" of textures, where for example the frames for Punch Animation are located on the 1st page (image1.png) and the frames for the Jump Animation are located on the 2nd page (image2.png)?

 

[Informatix]

Hello again,

I know this might be very simple to implement, but I'm currently having kind of a brain freeze.

This is my "load textures" (short version) code so far:

Sub Globals
    'These global variables will be redeclared each time the activity is created.
    'These variables can only be accessed from this module.
    Dim kkkkk As Float
    'GDX
        Dim lGdx As LibGDX
        Dim Gl As lgGL
        Dim Camera As lgOrthographicCamera
        Dim Batch As lgSpriteBatch
      
        Dim stage_source(number_of_stages) As lgTexture
        Dim actor_source(number_of_actors) As lgTexture
      
        Dim stage(number_of_stages) As lgTextureRegion
        Dim actor(number_of_actors) As lgTextureRegion
     
        Dim GLView As View
        Dim Animate = False As Boolean
End Sub


Sub LG_Create
    'Initializes the renderer  
    Batch.Initialize
    Set_First_Cycle
      
    For iii = 0 To (number_of_actors - 1)  
        actor_source(iii).Initialize(sprite_source(iii))
        actor(iii).InitializeWithTexture(actor_source(iii))       
    Next
End Sub


Sub Setup_Ryu  
    active_actor = Ryu
    actor_unique_ID(active_actor) = "RYU"
  
    actor_type(active_actor) = "PLAYER"
  
    sprite_source(active_actor) = "image1.png"
End Sub

What would be the best way to implement various "pages" of textures, where for example the frames for Punch Animation are located on the 1st page (image1.png) and the frames for the Jump Animation are located on the 2nd page (image2.png)?

Create a texture atlas.

 

[wonder]

Thanks! I will look into it!

 

[Brizky]

What's up, folks.

I work with VB.NET on a daily basis, I'm relatively new to Basic4Android but it doesn't look like it'll be an issue. But I am new to programming games. I read through the intro to LibGDX and then briefly ran through the Developer Guide located at https://github.com/libgdx/libgdx/wiki .

The only problem I seem to be having is locating something like a CLASS REFERENCE guide for ligGDX. Reading through the intro I was often thinking "what does this parameter in the function do?" or "why use this function?". And the developer guide goes over some code via its examples but seems to explain some things as if you already know what you're doing.

Like I said, I'm completely new to programming games. So I'm looking for some kind of document that says "These are all the objects", "this is what each object is used for", "these are the methods for these objects", "these are the parameters for these methods, functions, subs and here's what each parameter does".

Is there any kind of document like that out there?

 

[Informatix]

What's up, folks.

I work with VB.NET on a daily basis, I'm relatively new to Basic4Android but it doesn't look like it'll be an issue. But I am new to programming games. I read through the intro to LibGDX and then briefly ran through the Developer Guide located at https://github.com/libgdx/libgdx/wiki .

The only problem I seem to be having is locating something like a CLASS REFERENCE guide for ligGDX. Reading through the intro I was often thinking "what does this parameter in the function do?" or "why use this function?". And the developer guide goes over some code via its examples but seems to explain some things as if you already know what you're doing.

Like I said, I'm completely new to programming games. So I'm looking for some kind of document that says "These are all the objects", "this is what each object is used for", "these are the methods for these objects", "these are the parameters for these methods, functions, subs and here's what each parameter does".

Is there any kind of document like that out there?

You can browse the complete list of classes and functions with this tool: B4x Object Browser
or you can read the Java documentation here: http://libgdx.badlogicgames.com/nightlies/docs/api/
To learn the basics of programming a game, you should look at my tutorial on this matter.

 

[Brizky]

You can browse the complete list of classes and functions with this tool: B4x Object Browser
or you can read the Java documentation here: http://libgdx.badlogicgames.com/nightlies/docs/api/
To learn the basics of programming a game, you should look at my tutorial on this matter.

I did read through this post before when I was trying to learn about the gaming thing. But I'll hit it again and take it real slow this time. Thanks, man.

 

[Sia]

Hi,
how can give me sample of drawing a surface.
fist of all i tried draw it with canvas and drawline and then tried to draw surface with Body3D and now @Informatix tell me it's better to use libgdx and i think it's better
but i can't find any sample in internet
i tried to draw very easy sample mesh but i can't
i find lgMesh in this library but i can't find any solution for drawing x,y,z
please give me sample of drawing a surface.

very thanks.

 

[Malky]

Hi informatix, (correct thread this time).

I am just trying a few tests to make sure I have a handle on this, but I'm getting a java error:-
com.badlogic.gdx.utils.GdxRuntimeException: Texture width and height must be powers of two: 398x500

Sub LG_Create
    'Sets the InputProcessor
    IP.Initialize("IP")
    ScreenW = lGdx.Graphics.Width
    ScreenH = lGdx.Graphics.Height
    Batch.Initialize
    myBacking.InitializeWithFile(lGdx.Files.internal("day_background.png"))
    '...
End Sub

Trying to initialize the myBacking image is the problem?
It seems any image I try to load gives the same error (obviously with the different files sizes). Am I missing something obvious?

Malk

 

[Informatix]

Hi informatix, (correct thread this time).

I am just trying a few tests to make sure I have a handle on this, but I'm getting a java error:-
com.badlogic.gdx.utils.GdxRuntimeException: Texture width and height must be powers of two: 398x500

Sub LG_Create
    'Sets the InputProcessor
    IP.Initialize("IP")
    ScreenW = lGdx.Graphics.Width
    ScreenH = lGdx.Graphics.Height
    Batch.Initialize
    myBacking.InitializeWithFile(lGdx.Files.internal("day_background.png"))
    '...
End Sub

Trying to initialize the myBacking image is the problem?
It seems any image I try to load gives the same error (obviously with the different files sizes). Am I missing something obvious?

Malk

What's the version of your libGDX library ?

 

[Malky]

What's the version of your libGDX library ?

0.95

 

[Informatix]

0.95

You should update it.

 

[Malky]

You should update it.

Will do, thanks for that. I haven't been using b4a since last May with work and maintenance stuff, so trying to get back into it. Never even knew it had been updated. Thanks you very much for your prompt replies.

Malk

 

[Malky]

Hi again Informatix, sorry to bother you again. Has anything else changed in the new version I am unaware of?

I now get this error:-
java.lng.NullPointer Exception
at com.badlogic.gdx.graphics.g2d.SpriteBatch.flush(SourceFile:958)
with this line of code
Batch.DrawTex2(pandaFrontTexture,mypanda.x,mypanda.y,ScreenW*0.08,ScreenH*0.2)

I had all this working before I thought about trying the gestures instead of buttons.

EDIT: Meant to say this line is in the LG_Render function!