Learning AndEngine

Go to http://developer.android.com/sdk/. If you are on Windows, click on the Download Eclipse ADT with the Android SDK for Windows button. If you are using a different operating system, the page should autodetect it and offer you the link for your OS. In case it doesn't detect it correctly, there is a link called VIEW ALL DOWNLOADS AND SIZES that will expand a list of available platforms. Choose the right platform for you. Be careful when choosing 32-bit or 64-bit software. If you are running a 32-bit Java on a 64-bit system, choose the 32-bit software. Accept the license agreement and save the file to your hard drive. The examples in this chapter are from the 32-bit version for Windows.

The downloaded file will be a ZIP archive called something like adt-bundle-windows-x86-20131030.zip. The filename indicates the selected platform and the date of release. To install the software, simply unpack the archive to any folder.

You should find the following in the folder where you have unpacked the archive:

First, run the SDK Manager.exe file. It might take a while to start, and it doesn't show any splash screen. You will be presented with a window similar to the one in the following screenshot:

Check for any packages that have updates available. Note that you only need the latest SDK, which at the time this book was written was SDK 19 for Android 4.4. The latest version is always bundled with the Android SDK. You should also check the Google USB Driver option.

Optionally, you can install the Android emulator system images for older Android versions. This is useful for testing. However, AndEngine can't be deployed to an Android emulator with Android versions 2.x. For now, do not install anything else but the updates and the USB driver. Install the selected packages and close the SDK manager. The installation might take a while, because the packages are downloaded from the Internet.

Now, run the Eclipse IDE. From the eclipse folder, run the eclipse.exe file. After the splash, the first thing you will see is the workspace selection window. This is shown in the following screenshot:

If you have never worked with Eclipse, note that a workspace is both a virtual space on your screen (the layout) and a directory where your projects and some metadata that Eclipse keeps about your projects are stored. Choose any directory you want, but make sure it is one with easy access. You can have multiple workspaces. If you check the Use this as the default and do not ask again checkbox, you will be working with this workspace by default and this dialog box won't appear again at the start.

After the start, close the Welcome screen and you will be presented with the Eclipse default layout. Parts of the layout can be dragged and dropped to different locations. Also, you can have different perspectives (presets of the opened windows and tabs) for each workspace. We will be using the Java perspective for most of the time but we will also use Dalvik Debug Monitor Server (DDMS) and the Debug perspective for debugging and tuning our application. The perspectives are available by navigating to Window | Open Perspective.

Stay in the Java perspective, but go to Window | Show View | Other… and search for LogCat, as shown in the following screenshot:

LogCat is a log console. The Android system has a logging system that allows developers to print categorized text messages to LogCat from their apps. This is very useful for game developers because the text output to the screen can be very limited. The ADT takes care of getting the LogCat output from the connected Android device.

The Eclipse IDE can be a bit difficult to grasp from the start. However, as a Java developer, you have probably used it before or have used a similar one. Most of the IDEs nowadays are very similar. Try to familiarize yourself with Eclipse before proceeding to the next step.

Android uses OpenGL ES to display accelerated graphics. OpenGL ES is a free API for full-function 2D and 3D graphics on embedded systems. There are several versions of OpenGL ES, namely versions 1.x, 2.x, and recently 3.x.

A repository can also contain multiple branches. Think of a branch as an alternative version of the project. AndEngine is split into three branches. The GLES1 branch uses OpenGL ES 1.0 and it is the oldest. I don't recommend using it. GLES2 is newer and GLES2-AnchorCenter is the newest. They both use OpenGL ES 2. Use the GLES2-AnchorCenter branch if you haven't used AndEngine before. The GLES2-AnchorCenter branch's biggest difference from the GLES2 branch is the fact that point [0, 0] is now in the lower-left corner of the screen. This is the same as in OpenGL and that's why it's recommended.

For the purpose of this book, we are going to exclusively use the GLES2-AnchorCenter branch.

AndEngine is split into a main project simply called AndEngine and many extensions called, for example, AndEngineMultiplayerExtension, which are dependent on the main project. Each project resides in its own repository.

For our game, we need the main AndEngine project and a 2D physics extension called AndEnginePhysicsBox2DExtension. This extension adds a very popular 2D physics simulation framework called Box2D to AndEngine. A lot of popular games use this framework.

There is also a repository called AndEngineExamples. It is not an extension but an application that includes all of the other AndEngine libraries and extensions and illustrates their use.

You can download the sources from Nicolas Gramlich's original repository at https://github.com/nicolasgramlich/.

However, there is a danger that the codes will be changed any time in the future. For that reason, I recommend to download the sources from my forked repository, which is guaranteed to work with the sources in this book.

The easiest way is to download the complete repository as a ZIP archive, which can be done with the help of the following steps:

In Eclipse, navigate to File | Import and choose Existing Projects into Workspace (under the General folder). Browse to your workspace directory. You should see two projects. Check them both and import them by clicking on the Finish button. This is shown in the following screenshot:

If you have installed the ADT bundle with Android SDK 19, you should see no errors. In case there are errors, try cleaning and building all projects again. Simply click on the Project drop-down menu in Eclipse's main menu and select the Clean… option while having the Build Automatically option checked.

It is possible that when you were installing the ADT bundle, it contained a different SDK version from 19, or maybe you are, for some other reason, using a different version. In that case, you will see messages like the following in the console:

[2014-01-14 15:36:11 - AndEngine] Unable to resolve target 'android-19'

Right-click on the project, select the Properties option, and then choose the Android option. Make sure that the Android SDK version of your choice (or simply the latest) is selected. This is shown in the following screenshot. You will probably have to clean the project to make the error disappear. We have to do this because the project was saved with SDK 19 selected. Do it for both projects.

To create a simple Android application, we will follow these steps:

You need to enable the USB debugging option under Developer options on your phone or tablet in order to deploy the application from Eclipse. The configuration differs across Android versions, and it can even differ for the same version on a different device or brand.

Connect the device using a USB cable. You should see a notification of USB debugging connected on your phone or tablet.

Finally, in Eclipse, select the project and click on the drop-down arrow next to the run icon in the Eclipse top bar. Navigate to Run As | Android Application. This is shown in the following screenshot:

A pop-up window named Android Device Chooser will show the list of connected devices. Select your device. You can also check the Use same device for future launches option, which will remember your device for this session and will use it as the default target when you run the application the next time. Your device must run the project's minimum Android SDK or higher.

Have a look at the following screenshot:

After clicking on the OK button, Eclipse will build the application and create an APK. All applications have to be signed using a certificate before publishing to the Google Play store. For development purposes, all APKs are signed using a debug certificate.

The APK is then uploaded to the device and the main activity, in our case GameActivity, is started. You should see a simple one-screen application with Hello World text on the display. This is a default Hello World Android application created by Eclipse.

We need to add the AndEngine and AndEnginePhysicsBox2DExtension libraries to our app and change the GameActivity.

Adding the required projects

AndEngine and all the extensions are library projects. That means they can be added to our application as dependencies, similar to adding an external library JAR file. Eclipse will then build and package the library project along with our application to the final APK.

Right-click on the project, select Properties, and choose Android. Click on the Add button in the Library subsection and select AndEngine. Also add the AndEnginePhysicsBox2DExtension project similarly. This is shown in the following screenshot:

Changing the GameActivity to an AndEngine activity

AndEngine extends the basic Android Activity class because it needs to take care of a lot of initializing and loading of resources for the game engine. AndEngine gives us several hooks that we can use to perform our own initializations.

Understanding the activity lifecycle

It is important to understand the lifecycle of an Android application and activities. For a basic game, a single activity is usually enough, making things simpler. The following diagram describes the most basic activity lifecycle:

When you start your application, it goes through different states and the callback methods onCreate, onStart, and onResume are called. Notice that the onResume method is called even on the first start.

An activity is paused typically when the screen is locked or a dialog activity is brought to the front. Imagine a low battery warning for example. An activity is stopped when another activity completely covers your activity. This can be an incoming call. Note that the onStop method doesn't have to be called. This can happen when the system doesn't have enough resources for another activity and decides to kill your activity right away. The final method, onDestroy, is called when your activity is finished and cleared from the memory. Again, it is not guaranteed to be called.

The lifecycle is more complex than this and there are even more hooks that can be overridden and used. For our purposes, this will be enough. In fact, AndEngine takes care of most of the methods and gives us a few convenient methods to use instead.

The BaseGameActivity class

Our GameActivity class extends the BaseGameActivity class, which implements basic game activity behavior for us. For example, it implements the onCreate method that configures the engine and the surface view. The surface view is a dedicated drawing surface for our game that we can use through AndEngine.

When you created the empty GameActivity, it looked like the following code (it can differ based on the Eclipse and ADT versions):

package is.kul.learningandengine;

import android.os.Bundle;
import android.app.Activity;
import android.view.Menu;

public class GameActivity extends Activity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_game);
  }

  @Override
  public boolean onCreateOptionsMenu(Menu menu) {
    // Inflate the menu; this adds items to the action bar if it is present.
    getMenuInflater().inflate(R.menu.game, menu);
    return true;
  }

}

Delete both the onCreate and onCreateOptionsMenu methods. Change the parent of the GameActivity class from android.app.Activity to org.andengine.ui.activity.BaseGameActivity.

BaseGameActivity is an abstract class, and it will make you implement the onCreateEngineOptions, onCreateResources, onCreateScene, and onPopulateScene methods. The lifecycle methods are all handled by AndEngine.

Tip

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

The onCreateEngineOptions method

1. First, define the onCreateEngineOptions method. This method is called from the onCreate method and it is run first. You are supposed to configure AndEngine's engine in this method. The following is a typical example:

   public static final int CAMERA_WIDTH = 480;
   public static final int CAMERA_HEIGHT = 800;
   
   @Override
   public EngineOptions onCreateEngineOptions() {
     Camera camera = new Camera(0, 0, CAMERA_WIDTH, CAMERA_HEIGHT);
     IResolutionPolicy resolutionPolicy = new FillResolutionPolicy();
     EngineOptions engineOptions = new EngineOptions(true, ScreenOrientation.PORTRAIT_FIXED, resolutionPolicy, camera);
     engineOptions.getAudioOptions().setNeedsMusic(true).setNeedsSound(true);
     engineOptions.setWakeLockOptions(WakeLockOptions.SCREEN_ON);
     Debug.i("Engine configured");
     return engineOptions;
   }

   We have defined two static constants that define the resolution of our view port. AndEngine will then take care of scaling the final picture on the device.

2. In the method itself, we start with the camera definition. The Camera object defines the part of the scene that will be visible. It takes four parameters: the first two are the bottom-left coordinates in the scene and the third and fourth are the width and height of the visible area.

3. Next, we define a resolution policy. The Android platform suffers from a variety of different screen sizes and ratios. AndEngine tries to deal with this by letting you specify one resolution and then scaling the resulting picture to any device.

4. You don't need to care whether the screen size of the phone is bigger or smaller than your desired resolution. AndEngine can enlarge your scene or shrink the picture. You place your objects at coordinates in your resolution. However, you still have to hint AndEngine about how the resulting picture should be scaled, and that's what the resolution policy is for.

5. In the example, we are using the FillResolutionPolicy. As the name suggests, this policy fills the whole screen with your scene. Your picture will be resized but the aspect ratio will not be kept, unless the phone and your scene have the same ratio. Pixels can become taller or wider.

6. Then, we create the EngineOptions object. This is the final object that will be passed to the engine. It takes four parameters, as follows:

   • Fullscreen: This option is set to true, as we want our game to cover the whole screen.

   • Screen orientation: For this, the possible values are PORTRAIT_SENSOR, PORTRAIT_FIXED, LANDSCAPE_SENSOR, and LANDSCAPE_FIXED. The sensor variant will flip the picture upside down when you flip the device.

   • Resolution policy: This is explained earlier.

   • Camera: This is explained earlier.

7. We also set the audio options simply to indicate that we will be using both sound and music.

8. Last, we set the wake lock to SCREEN_ON. This simply means that the device will not enter sleep mode due to inactivity. This is important because you can have a period in your game without user input when you don't want the screen to turn off by itself. This can be a cutscene for example.

9. The line Debug.i("Engine configured"); is optional. This will print the Engine configured message to LogCat. Use this kind of debug message to check whether the method ran successfully.

   Tip

   The messages can have different levels: error, warning, info, debug, and verbose. Each level has its own method, such as Debug.e or Debug.d. These are used to differentiate the severity of the method as LogCat allows filtering by the level. You can use Debug.i("MyTag", "Engine configured"); in your code to further categorize your messages based on tags.

10. At the end, we return the engineOptions object.

The onCreateResources method

The onCreateResources method is called after the engine options are created, and it is used to initialize game resources such as graphics, sounds, and music. For now, we leave this method empty.

@Override
public void onCreateResources(OnCreateResourcesCallback pOnCreateResourcesCallback)throws IOException {
  pOnCreateResourcesCallback.onCreateResourcesFinished();
}

Notice the pOnCreateResourcesCallback parameter. This is used to indicate that you are done loading the resources and the control is given back to the engine. You have to call the onCreateResourcesFinished method, otherwise the engine will not continue.

The onCreateScene method

The onCreateScene method is called from the onCreateResourcesCallback object when you call the Finished method. It is used to create a scene object or objects.

Note

Every displayable object in AndEngine is an entity. That includes the scene, which is the parent of all the other entities currently displayed. The engine can display one scene at a time, and you will typically want to define multiple scenes, such as a menu scene and a game scene. You can also have child scenes, which are used to display a pause screen or a game over screen.

The following code describes the simplest scene. We only create an empty scene object and set its background to cyan color.

@Override
public void onCreateScene(OnCreateSceneCallback pOnCreateSceneCallback)throws IOException {
  Scene scene = new Scene();
  scene.getBackground().setColor(Color.CYAN);
  pOnCreateSceneCallback.onCreateSceneFinished(scene);
}

Again, you have to call the Finished method on the provided callback object to tell the engine you are done creating your scene.

The onPopulateScene method

The onPopulateScene method is the final method we need to implement, which is used to populate the scene with entities. For the simplest example, we are not going to add any. Leave the method body empty, but remember to return the Scene object. This method is called from the Scene callback and you have to call the next callback too. This is described in the following code:

@Override
public void onPopulateScene(Scene pScene,OnPopulateSceneCallback pOnPopulateSceneCallback)throws IOException {
  pOnPopulateSceneCallback.onPopulateSceneFinished();
}

Tip

There is an alternative to BaseGameActivity called SimpleBaseGameActivity which calls the callbacks for you at the end of each of the onCreateResources, onCreateScene, and onPopulateScene methods. It's up to you which one you want to use, but you should understand what the callbacks are doing.

This policy simply creates a renderable area of specified size. If your screen is 1280 x 768 px like on the Nexus shown in the following screenshot, the 800 x 480 px scene will be centered with a big border. If your screen size is exactly 800 x 480 px, your scene will perfectly fit on your display. If your device has a smaller resolution, the whole scene will be cropped. This policy keeps the aspect ratio of pixels (squares will be squares).

You can of course pass anything to your FixedResolutionPolicy. It doesn't have to be the same as the camera dimensions. You can measure the display size of the device and then manually position all elements based on this measurement. That's what this policy is for.

As mentioned earlier, the FillResolutionPolicy fills the screen but can distort the image because it doesn't keep the scene ratio.

You can see in the previous screenshot that on the Nexus 4, the difference is almost unnoticeable, because 800 x 480 px ratio is about 1.66, and the Nexus 4 screen ratio of 1280 x 768 is 1.66 too. But thanks to the soft buttons in the system bar, the usable portion has roughly 1.56 screen ratio, and that's why the squares are slightly taller.

You have to pass two floats to this policy, which are the percentages of width and height of the screen you want to use. So, if you pass (1, 1), it means give me the whole screen (the same as FillResolutionPolicy).

A ratio policy is probably the most commonly used in the examples. It keeps the aspect ratio and scales your scene to fit one dimension. The other dimension will be padded with the background color of your theme. It will create two bars.

They are highlighted with yellow in the following screenshot:

If you set your background theme to be black, the bars will be black. If you use this policy, try to match the theme background color to your game's background.

This policy was originally created by user jgibbs on the AndEngine forums. He called it CroppedResolutionPolicy. You will find a slightly modified version of it in my GitHub repository.

The crop policy is similar to the ratio policy, but instead of padding, it scales the scene while keeping the aspect ratio to cover the whole screen and crops the overflow. See the arrows in the following screenshot pointing to the areas that will be cropped:

This policy is not the easiest to use. You must place the objects relative to the edges. The center of the screen will still be the center, but you can't simply say: place sprite at [0, 0]. It might be in the overflow on some devices.