LibGDX Notes. Using BlueJ. LibGDX Notes

Transcription

1 LibGDX Notes These notes assume that you have a familiarity with Java programming. If you do program in Java you probably use an integrated development environment (IDE) already. There are many possible choices for IDE s, for beginners we have: BlueJ ( DrJava ( For more advanced programmers there is: Eclipse (eclipse.org) NetBeans (netbeans.org) IntelliJ IDEA ( The first book I am tackling is Beginning Java Game Development with LibGDX which uses BlueJ. I will detail the steps to get the same hello world program with LibGDX up and running on BlueJ, Eclipse and NetBeans. Using BlueJ 1. Obtain a copy of BlueJ at Figure BlueJ has a download installer for Windows, Mac OS X, Ubuntu/Debian, Raspbian Linux. 1

2 Since I already have Java JDK installed I will select BlueJ Installer How to tell if you have Java JDK installed. Open a command prompt window Enter java version If you do not see the above response you probably do not have Java installed or in the PATH The Window version for BlueJ is a *.msi file that you can install by double-clicking on it. After installation you should see a desktop icon for BlueJ what does it look like? Figure 2 - Desktop Icon 3. Double-click the desktop icon to get BlueJ started. The application window for BlueJ is rather basic and simple especially for all you developers that use Eclipse and NetBeans! Figure 3 illustrates what the screen looks like when first started. 1 I am assuming you know how to detect what Java version you have and how to set it up on your computer s path. If you need more guidance than I suggest you check out the HTML TRAINING notes we have on brainycode.com. It details how to set up Java and NetBeans (for HTML5 development) for the complete beginner. 2

3 Figure 3 - BlueJ Start Screen 4. From the menu select Project New Project 5. A New Project file dialog opens up. Navigate to the location of your BlueJ projects. I decided to place all my BlueJ projects under a directory named BLUEJ and for this specific project to create a directory named HELLO_WORLD. The screen will now appear as: Figure 4 - Folder organization for my BlueJ projects 3

4 Figure 5 - IDE after creating HELLO_WORLD project The page icon you see on the screen is a README.TXT file you can use to detail the specifics of the project you are creating. We will examine this file later. 6. Create a new class by clicking on the New Class button. 4

5 Figure 6 - Enter name of the new class "HelloWorld" 7. Enter the class name HelloWorld and click on Ok Figure 7 - Updated BlueJ IDE with new class You will see a new rectangular icon labeled HelloWorld added to your IDE. The diagonal lines indicate that the Java class file needs to be compiled. 8. Double-click on the HelloWorld rectangle or right-click over the rectangle and select Open Editor You will see that the class has a lot of template code already inserted for you! 5

6 Figure 8 - HelloWorld with template code 9. Delete all the code and enter the following code: Table 1 - HelloWorld.java code /** * Write a description of class HelloWorld here. * Lorraine Figueroa May */ public class HelloWorld { public static void main() { System.out.println("Hello, World!"); } } The IDE should look like this: 6

7 10. Click on the Compile button Figure 9 - Our HelloWorld program You should see the following message at the bottom of the IDE in the status screen. Figure 10 - Status message after compilation Note: If you do not see the message above check and compare the text to find any possible typos. When you return to the main IDE screen you will the HelloWorld icon now has the compiled rectangle icon. 11. Return to the main screen with the HelloWorld rectangle. Right-click and select void main() 7

8 Figure 11 - Running the class main() A terminal window will open up with the results of running the program: Figure 12 - Result of running our HelloWorld program To the left of your HelloWorld class as illustrated in Figure 13 is a README.TXT file that automatically got created when we created our BlueJ project. 12. Double-click on the README.TXT file in order to open up the contents of the file in a text editor. 8

9 Figure 13 - Our Hello World Project The original contents of the README.TXT file is shown below: Table 2 - Original README.TXT file This is the project README file. Here, you should describe your project. Tell the reader (someone who does not know anything about this project) all he/she needs to know. The comments should usually include at least: PROJECT TITLE: PURPOSE OF PROJECT: VERSION or DATE: HOW TO START THIS PROJECT: AUTHORS: USER INSTRUCTIONS: A good programmer will make sure that the README.TXT is updated and accurate so that years from now others will be able to find out the purpose of the project and know how to execute it. 9

10 Table 3 - Update README.TXT file PROJECT TITLE: HelloWorld PURPOSE OF PROJECT: This is a test project to get acquainted with BlueJ VERSION or DATE: 05/28/2016 HOW TO START THIS PROJECT: Execute the main in the class HelloWorld AUTHORS: L. Figueroa USER INSTRUCTIONS: N If you plan on using BlueJ I highly recommend that you obtain the reference manual at and spend 15 to 20 minutes going over it in order to get an idea what features the IDE has and for future reference. 13. Head over to to download the jar file for the LibGDX library. Figure 14 - LibGDX banner The Java framework library can be used to create programs for desktops, Android devices, ios and HTML5. Learning to use frameworks that work on many different platforms your Windows OS, your Samsung phone, a Mac, an iphone and from any device that supports a browser that also supports JavaScript/WebGL means that you can build your application one time and be assured that it can run just about anywhere! 14. Click the Download icon and head over to the Releases download folder and find the latest file in the format libgdx-x.x.x.zip. Figure 15 - Downloading the latest LibGDX zip file 15. Unzip the contents of the zip file into a location we will use to add LibGDX to all our projects (and across IDEs). I will place it at C:\LibGDX You will find several jar files in the folder you extracted the zip file into: 10

11 Figure 16 - Jar files in LibGDX The files we want to use are: gdx.jar gdx-natives.jar gdx-backend-lwjgl.jar gdx-backend-lwjgl-natives.jar Since we want to use these files across many BlueJ projects let s put the files in a location that will be available to all our BlueJ projects 16. Find the location of where BlueJ was installed. On my Windows system it was C:\Program Files (x86)\bluej. Figure 17 - Location of BlueJ installation 11

12 17. Copy the jar file noted above into the BlueJ \lib\userlib folder. Figure 18 - Moving LibGDX jar file into BlueJ 18. Start or re-start BlueJ IDE. Close the old HelloWorld project if it automatically opened up. 19. Create a new project called ViewImage 20. Create a new class ViewImage with the contents as shown below: Table 4 - ViewImage.java /** * Write a description of class ViewImage here. * Lorraine Figueroa 5/29/2016 */ import com.badlogic.gdx.game; import com.badlogic.gdx.gdx; import com.badlogic.gdx.files.filehandle; import com.badlogic.gdx.graphics.gl20; import com.badlogic.gdx.graphics.g2d.spritebatch; import com.badlogic.gdx.graphics.texture; public class ViewImage extends Game { private Texture texture; private SpriteBatch batch; public void create() { FileHandle worldfile = Gdx.files.internal("pong.png"); 12

13 } texture = new Texture(worldFile); batch = new SpriteBatch(); public void render() { Gdx.gl.glClearColor(1, 1, 1, 1); Gdx.gl.glClear(GL20.GL_COLOR_BUFFER_BIT); } } batch.begin(); batch.draw(texture, 0, 120); batch.end(); A file in LibGDX is represented by an instance of the FileHandle class. A FileHandle has a type which defines where the file is located. 13

14 In the program above we use: Figure 19 - The availability and location of each file type for each platform FileHandle worldfile = Gdx.files.internal("pong.png"); 14

15 An image is converted from its original format (e.g *.png file) and saved as a Texture. LibGDX uses OpenGL therefore every image needs to be transformed into a Texture. A Texture is nothing more than a decoded image loaded into the GPU s memory in raw format. To display textures (images) on the screen, a few things have to be done first. A mesh, usually a rectangular polygon is used to describe the geometry for the texture mapping to be made on. Texture mapping is the process of working out where in space the texture (image) will be applied. In the code we use the following line to convert the file image into a Texture. texture = new Texture(worldFile); LibGDX comes with SpriteBatch which takes care of all the steps needed to achieve texture mapping and displaying texture mapped rectangles on the screen. It is a convenience class which makes drawing onto the screen extremely easy and it is also optimized. The render method uses the SpriteBatch object batch to draw our image to the screen batch.begin(); batch.draw(texture, 0, 120); batch.end(); It works with screen coordinates and uses pixel perfect screen resolution. The lower left corner is the origin (0,0) with the X axis pointing right and the Y axis pointing up. The above draws our image starting at X = 0 and Y = 120. Note: The information above comes frm the github wiki: Create another new class named GameLauncher with the contents: Table 5 - GameLauncher.java /** * Write a description of class GameLauncher here. * Lorraine Figueroa 5/29/2016 */ import com.badlogic.gdx.backends.lwjgl.lwjglapplication; public class GameLauncher { public static void main(string[] args) 15

16 } { } ViewImage myprogram = new ViewImage(); LwjglApplication launcher = new LwjglApplication(myProgram); All our applications will use a game launcher class to trigger our game class. 22. Compile both programs and Run GameLauncher. 23. Just click OK Figure 20 - Executing GameLauncher Figure 21 - Result of running GameLauncher 16

17 The bottom left of our image is location (0, 120), where the bottom left of the window or screen is (0,0). The nice feature in BlueJ is that you can see the relationship between files in the IDE. Figure 22 - BlueJ class relationships The image above makes it clear that the GameLauncher invokes or includes a reference to the ViewImage object. None of the methods in myprogram are actually invoked by ViewImage. It passes the myprogram object to another class LwjglApplication that manages to get the methods in ViewImage invoked so we see our image. There are several advantages to using LibGDX as your Java game framework: It has methods for handling user input from the keyboard, mouse, game pad or touch screens It can be used to render 2D graphics It has methods to play sound effects or play music It allows you to easily integrate other third party tools It has methods to render 3D graphics and even load 3D models. 17

18 Figure 23 - Soldier 3D model At this time I will admit that using BlueJ for my IDE Java Development does not feel like a good idea. I will now detail how to get the ViewImage project constructed using Eclipse. Using Eclipse I will have to admit that BlueJ seems simple and I could see how it can be quite appealing for students who are starting to learn how to program in Java but as a Java programmer I am used to having to do less work with respect to getting my imports in and also NOT having to compile every file after I made a change (Eclipse automatically does this for us). So I will step through how to recreate the LibGDX ViewImage using Eclipse. 1. Open Eclipse and create a new workspace to hold all our LibGDX project. Figure 24 - Creating a workspace Note: I am using a 64-bit OS (Windows 7), with 64-bit Java SDK and 64-bit version of Eclipse. 18

19 2. Enter the workspace and create a new Java Project ViewImage by right-clicking in the Project Explorer and selecting New Project Java Project and click on Next>. Figure 25 - Creating new Java Project 3. Enter the project name ViewImage and click on Finish. Figure 26 - Our Eclipse Project Explorer 4. Highlight the src folder (as shown above) and right-click on New Package and enter the name: com.att.brainycode.libgdx.examples. Click on Finish. 19

20 Figure 27 - Project with new package Before we add our first class let s add the same four jars files we identified to the project Right-click the ViewImage project icon. Select Properties from the menu and the Java Build Path option Figure 28 - Java Build Path dialog 6. Click on Add External JARs button 7. Navigate to the location of the LibGDX jars and select (hold CTRL) the four jar files we want to add to the project. 2 We will have to add the same 4 LibGDX files to every Eclipse project we create until we start to use a cool build tool like Maven. 20

21 Figure 29 - Selecting the four LibGDX JAR files 8. Click Open. Figure 30 - Adding the JAR to the build 9. Click on OK 21

22 10. Highlight the package and create the Java class by right-clicking and selecting New Class. Figure 31 - Creating ViewImage class 11. Enter the Name and DO NOT forget to add Game as the superclass by clicking Browse and entering the name Game The file contexts for ViewImage will be the same as the version in BlueJ but with the package line. In addition, Eclipse will assist you when finding and adding the right imports to the file. Table 6 - Eclipse version of ViewImage.java package com.att.brainycode.libgdx.examples; import com.badlogic.gdx.game; import com.badlogic.gdx.gdx; import com.badlogic.gdx.files.filehandle; import com.badlogic.gdx.graphics.gl20; import com.badlogic.gdx.graphics.texture; import com.badlogic.gdx.graphics.g2d.spritebatch; public class ViewImage extends Game { 22

23 private Texture texture; private SpriteBatch public void create() { FileHandle worldfile = Gdx.files.internal("pong.png"); texture = new Texture(worldFile); batch = new SpriteBatch(); } public void render() { Gdx.gl.glClearColor(1, 1, 1, 1); Gdx.gl.glClear(GL20.GL_COLOR_BUFFER_BIT); } batch.begin(); batch.draw(texture, 0, 120); batch.end(); } 12. Create a new class named GameLauncher. Table 7 - Eclipse version of GameLauncher.java package com.att.brainycode.libgdx.examples; import com.badlogic.gdx.backends.lwjgl.lwjglapplication; public class GameLauncher { } public static void main(string[] args) { ViewImage myprogram = new ViewImage(); LwjglApplication launcher = new LwjglApplication(myProgram); } 23

24 13. Try to run the program (I know it will not work since we have not placed the pong.png image in a location that it can be found). To run either click on the Run icon. Figure 32- Eclipse run icon Figure 33 - Run As dialog 14. Select Run As Java Application You will see the following expected error message: Table 8- Eclipse console error message Exception in thread "LWJGL Application" com.badlogic.gdx.utils.gdxruntimeexception: Couldn't load file: pong.png at com.badlogic.gdx.graphics.pixmap.<init>(pixmap.java:140) at com.badlogic.gdx.graphics.texturedata$factory.loadfromfile(texturedata.java:98) at com.badlogic.gdx.graphics.texture.<init>(texture.java:100) at com.badlogic.gdx.graphics.texture.<init>(texture.java:92) 24

25 at com.att.brainycode.libgdx.examples.viewimage.create(viewimage.java:18) at com.badlogic.gdx.backends.lwjgl.lwjglapplication.mainloop(lwjglapplication.java:143) at com.badlogic.gdx.backends.lwjgl.lwjglapplication$1.run(lwjglapplication.java:120) Caused by: com.badlogic.gdx.utils.gdxruntimeexception: File not found: pong.png (Internal) at com.badlogic.gdx.files.filehandle.read(filehandle.java:136) at com.badlogic.gdx.files.filehandle.readbytes(filehandle.java:222) at com.badlogic.gdx.graphics.pixmap.<init>(pixmap.java:137)... 6 more 15. Highlight the project and create new folder New Folder. Name it res (for resources) 16. Copy the pong.png image to the res folder. Figure 34 - New "res" folder We will need to add this directory to the class path so that all our resources are located. 17. Again right-click the project and select Properties and Java Build Path. Click on Add External Class Folder button on the Libraries tab. 18. Navigate to the res folder in your project and click OK 25

26 Figure 35 - Navigating to the res project You will now see res added to the classpath: Figure 36 - Adding res to the classpath 19. Run GameLauncher again you will now see the pong image. 26

27 Figure 37 - Pong image from Eclipse. The eclipse IDE is more complicated that BlueJ but it provides too many advantages that I require when doing development. See Appendix A for how to use NetBeans with LibGDX. The LibGDX Framework The Game Loop One of the most fundamental design structures used in game programs is the game loop. A simple and basic game loop is the following 3 : boolean running = true; while (!running) { updategamestate(); displaygamestate(); } There are two things the program does in the game loop update and display. In the updategamestate() all the monsters are moved, killed, or made to appear and in the displaygamestate() the screen is updated with your new weapon being shown and the last monster slain now lays on the ground wincing in pain. The running flag is set to false when you win or lose or pause the game. Before the game enters the game loop the game resources are processed. For example, the images and sound effects are read in. This function is done in the create() method in our project. The game loop 3 From 27

28 above is captured in our render() method. The one issue is how often is the game loop executed? Usually most programs try for 60 loops per second or more commonly referred to as frames per second (FPS). An accurate view of the game loop is the following image 4 : Figure 38 - Game Loop As you can see the first step (outside the game loop itself) is the Initialize the Game Engine (the user may not be starting at Level 1) and load the resources (images, sounds, etc) and then we get into the game loop where we process input (check if the user clicked on jump button), simulate the game world (update positions) and then render or display the screen. We then check if the game should be still running (is the game over, did use pause, etc). When the game ends all the resources are unloaded and the game exits. The nice thing about the LibGDX framework is that it hides the game loop from us (since all games have it!) and we just have to create and fill in the relevant methods (e.g render()). The LibGDX Modules See: LibGDX consists of five interfaces that provide means to interact with the operating system. Application: runs the application and informs an API client about application level events, such as window resizing. Provides logging facilities and quering methods (e.g. memory usage)

29 Files: exposes the underlying file system(s) of the platform. Input: informs the API client of user input such as mouse, keyboard, touch or accelerometer events. The framework supports both polling and event driven processing. Net*: provides a mean to access resources via HTTP/HTTPS in a cross-platform way, as well as create TCP server and client sockets. Audio: provides a mean to playback sound effects and streaming music as well as directly accessing audio devices for PCM audio input/output. Graphics: exposes OpenGL ES 2.0 (where available) and allows quering/setting video modes and similar things. The only platform specific code are the starter classes (launcher classes). For each platform that is targeted, a piece of code will instantiate a concrete implementation of the Application interface. In our desktop example we have: Table 9- Desktop specific starter class ViewImage myprogram = new ViewImage(); LwjglApplication launcher = new LwjglApplication(myProgram); For an Android environment we would have: Figure 39 - Android starter class What is OpenGL ES? OpenGL for Embedded Systems (OpenGL ES or GLES) is a subset of the OpenGL computer graphics rendering application programming interface (API) for rendering 2D and 3D computer graphics. Typically we create computer or video games that are hardware-accelerated using graphics processing unit (GPU). The API is designed for embedded systems like smartphones, computer tablets, and video game consoles. The API is cross-language and multi-platform. From: 29

30 Using Texture From: An image is simply an array of colors, rendered in two dimensions. Let s take a close look at a very small image a heart sprite and a half-heart sprite. Figure 40 - Heart and half-heart sprite There a number of ways the above image(s) are stored on a computer. The most common format used is RGBA with 8-bits per channels. RGB stands for red, green and blue channels. A refers to the alpha (transparency) channel. Here are the three different ways of storing the color red: The RGBA byte array representing the above image (32x16 pixels) might look like this: Figure 41 - Byte array of heart image A single pixel is made up of four bytes. The size of the array is WIDTH * HEIGHT * BPP, where BPP stands for bytes per pixel. An array of bytes can be rather large that is why compression like PNG or JPEG is used. 30

31 In OpenGL ES we use textures to store image data. OpenGL ES textures do not only store image data; they are simply float arrays stored on the GPU, so they are also useful for shadow mapping and other advanced techniques. The basic steps of getting an image into a texture are as follows: 1. Decode into RGBA bytes 2. Get a new texture ID 3. Bind that texture 4. Set up any texture parameters 5. Upload the RGBA bytes to OpenGL Using LibGDX hides all the details for us. A Texture class decodes an image and loads it into GPU memory. The image file should be powers of two (16x16, 64x256, etc) for compatibility and performance reasons. Each texture is created and passed to a SpriteBatch to be drawn. A TextureRegion TODO Using SpriteBatch From: If you look up the JavaDoc for SpriteBatch you will read: Draws batched quads using indices. It probably does not have much meaning if you are not familiar with OpenGL. An image that has been decoded from its original format (e.g PNG) and uploaded to the GPU is called a texture. To draw a texture, geometry is described and the texture is applied by specifying where each vertex in the geometry corresponds on the texture. For example, the geometry could be a rectangle and the texture could be applied so that each corner of the rectangle corresponds to a corner of the texture. A rectangle that is a subnet of a texture is called a texture region. To do the actual drawing, first the texture is bound (i.e. made the current texture), then the geometry is given to OpenGL to draw. The size and position on the screen that the texture is drawn is determined by both the geometry and how the OpenGL viewport is configured. Many 2D games configure the viewport to match the screen resolution. This means that the geometry is specified in pixels, which makes it easy to draw textures in the appropriate size and position on the screen. It is very common to draw a texture mapped to rectangular geometry. It is also very common to draw the same texture or various regions of that texture many times. It would be inefficient to send each rectangle one at a time to the GPU to be drawn. Instead, many rectangles for the same texture can be described and sent to the GPU all at once. This is what the SpriteBatch class does. SpriteBatch is given a texture and coordinates for each rectangle to be drawn. It collects the geometry without submitting it to the GPU. If it is given a texture different than the last texture, then it 31

32 binds the last texture, submits the collected geometry to be drawn, and begins collecting geometry for the new texture. It is common to store many smaller images in a larger image and the draw regions for the larger image to both maximize geometry batching and avoid texture changes (e.g. using a sprite sheet). Figure 42 - Example use of SpriteBatch All SpriteBatch drawing class must be made between the begin and end methods. Non- SpriteBatch drawing cannot occur between begin and end. SpriteBatch assumes the active texture unit is 0. When using custom shaders and binding textures yourself, you can reset this with the following code: Figure 43 - resetting current texture KeyPresses and Moving an Object TODO: An example that moves an image on the screen Collision Detection TODO: An example where one image remains stable 32

33 The Sprite Class Custom Sprite Class The Stage Class The Actor Class TODO: An example using the Actor class and Stage. Implementing Animation The Action Class MathUtils Using a Camera Multiple Screens 33

34 34

35 References 1. Curry, Michael. Java Game Programming. Self-published. 2. Stemkoski, Lee. Beginning Java Game Development with LibGDX APRESS. 3. Nair, Suryakumar Balakrishan. Learning LibGDX Game Development Packt Publishing. 4. Marquez, David Saltares. LibGDX Cross-platform Game Development Cookbook Packt Publishing. 5. Cook, James. LibGDX Game Development By Example Packt Publishing. 6. Bose, Juwal. LibGDX Game Development Essentials Packt Publishing. 35

36 Appendix A Using NetBeans and LibGDX TODO 36