The base for building an AndEngine application is the BaseGameActivity class, which we'll use instead of the standard Activity class. The former provides the base functionality, which we'll need in our application. There's also the SimpleBaseGameActivity class, which exists for compatibility with GLES1. Unlike GLES2's BaseGameActivity, it does not use callbacks—methods called by AndEngine that we define ourselves—and uses a more basic setup and configuration model. As we're not using GLES1, we are not interested in using this class.

The BaseGameActivity class has four functions that we override for our own functionality:

The advantage of the GLES2 base class is that through the calling of the callback in each overridden function, you can explicitly proceed to the next function in the list instead of implicitly having all of them called. Other than this, very little changes. In the onCreateEngineOptions() function, we still create a Camera object and assign it together with the parameters for the screen orientation and ratio to an EngineOptions object, which is returned. No callback is called here yet.

The remaining three functions respectively load the resources for the application, create the scene, and populate the said scene. A basic application skeleton thus looks like this:

public class MainActivity extends BaseGameActivity {
  private Scene mScene;
  private static final int mCameraHeight = 480;
  private static final int mCameraWidth = 800;

  @Override
  public EngineOptions onCreateEngineOptions() {
    Camera mCamera = new Camera(0, 0, mCameraWidth, mCameraHeight);
    final EngineOptions engineOptions = new EngineOptions(true, ScreenOrientation.LANDSCAPE_FIXED, new RatioResolutionPolicy(
            mCameraWidth, mCameraHeight), mCamera);
    return engineOptions;
  }

  @Override
  public void onCreateResources(
      OnCreateResourcesCallback pOnCreateResourcesCallback)
      throws IOException {
    // Load any resources here
    pOnCreateResourcesCallback.onCreateResourcesFinished();		
  }

  @Override
  public void onCreateScene(OnCreateSceneCallback pOnCreateSceneCallback) 
      throws IOException {
    mScene = new Scene();
    pOnCreateSceneCallback.onCreateSceneFinished(mScene);
}

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

To finish this basic application, we will be implementing a simple scene that merely creates a single sprite. For this, we will use the Scene object created in the code shown earlier. This object forms the root of the scene tree to which all the objects, such as sprites in the scene, attach. Before we can create the sprite, we need to set up the bitmap logic to load and handle textures. As we know, a sprite is more or less just a bitmap image. To display it, we first fetch the required image from the application's resources. Probably, you have already preloaded these in the onCreateResources() function, a procedure that, in general, is a very good idea for reducing load times later on in the application in order to prevent slowdowns.

An efficient way of using textures with OpenGL ES is to have only a single texture loaded at any given time. Since any given scene is likely to have more than one texture, we have to merge our textures into a single large texture. Here, we have two options:

The texture atlas is the traditional approach, whereby you create a single, blank texture and place smaller textures on it. The texture atlas must have dimensions of powers of 2, and is limited in size by the memory buffer of the graphics processor of the device. Generally, sticking to an upper limit of 1,024 for either dimension is advisable.

The texture packer is a relatively new approach. It uses an external application to create a texture atlas, which is then output together with a XML file that maps the textures on the atlas. The advantages of this method are less code in the resource loading section and a more visual approach to the atlas creation process. The TexturePack APIs are then used within the AndEngine application to load the XML file. It is important to note here that starting with the GLES2-AnchorCenter branch of AndEngine, the TexturePack API extension (AndEngineTexturePackerExtension) is integrated, and thus available by default.

To access the individual textures in the texture atlas, we create texture region instances, which are a mapping of a specific region of the said atlas. Once all is said and done, these texture regions are essentially our textures, as we use them within a scene. After the loading stage of the resources and the creation of the atlas and texture regions, we can pretty much ignore these details and use the texture regions without considering the implementation.

For the sample application that we are developing in this chapter, we will use the former approach of creating the texture atlas in code, as we have only a single sprite to display. Briefly, we first create the atlas:

this.mFaceTexture = new AssetBitmapTexture(this.getTextureManager(), this.getAssets(), "gfx/helloworld.png");
this.mFaceTextureRegion = TextureRegionFactory.extractFromTexture(
                  this.mFaceTexture);

This code loads a PNG file called helloworld.png from the assets folder of the Android application into a texture that we use as the texture atlas. Next, we create a texture region out of it, as we'll need this to actually reference the texture. Then we load the texture atlas into the memory buffer of the video processor:

this.mFaceTexture.load();

Leaving the onCreateResources() function, we move on to onPopulateScene(), in which we basically add sprites to the scene, one sprite in this particular case. After setting the background color of the Scene object to a nice shade of gray using the RGB values in floating-point format (three times 0.8f), we determine the center of the camera's view:

final float centerX = mCameraWidth / 2;
final float centerY = mCameraHeight / 2;

Finally, we create the sprite using the texture region we created before, and add it to the scene:

final Sprite sprite = new Sprite(centerX, centerY, this.mFaceTextureRegion, this.getVertexBufferObjectManager());
pScene.attachChild(sprite);

When we run the application, we see the following appear on the screen:

That's it! We're now ready to build and launch the application. You should look at the sample project (AndEngineOnTour) for this chapter and try to get it running. We will be building upon it in the coming chapters.

When it comes to running Android applications, we get to choose between using a real device (phone or tablet) and an emulator Android Virtual Device (AVD) as the target. Both have their advantages and drawbacks. While Android devices offer the complete experience at full speed, their disadvantages include the following:

AVDs do not have these disadvantages, but they have the following limitations:

Beyond these differences, devices and AVDs are quite similar. Which one to use depends largely on your needs. However, any verification and non-simple debugging should, as a rule of thumb, always be done on a device. While an AVD approaches the functionality of a real device, it is still so different and limited that its results should not be relied upon as real device behavior.

That said, both can be used in an identical fashion with ADB, or the Android Debug Bridge. ADB is a client-server program that consists of a server running on the Android device or AVD, and a client running on the system accessing it. The ADB client can either be run as a command-line tool or be used from within an IDE such as Eclipse for purposes such as uploading applications to the Android device or AVD, uploading and downloading files, and viewing system and application logs in real time.

Especially the ability to view logs in real time for any running application is very helpful to us when we try to debug an application, as we can output any debug messages to the log.

As mentioned before, the easiest way to debug an Android application running on either a device or an AVD instance is to output debug messages to the log output (LogCat) so that they can be read via ADB. The API in Android for this purpose is the Log class. It uses various categories to distinguish between the importance of the messages, ranging from verbose to error.

For example, to output a debug string to LogCat, we use the following code in Java:

Log.d("AndEngineOnTour", "This is debug output.");

The first part is the tag for the application or class that we output from, and the second part is the actual message. The tag is used in filtering to, for example, only see the output from our own application. We can also use a filter on the log category.

When writing native code in C/C++ using the Native Development Kit (NDK), we may also want to use LogCat. Here, we just have to include one header and use a slightly modified function call, like this:

#include <android/log.h>
__android_log_print(ANDROID_LOG_DEBUG, "AndEngineOnTour", "This is debug output");

Finally, we can use a debugger. For Java, this is easy, with IDEs such as Eclipse/ADT offering ready-to-use debugging functionality with full integration. This allows easy debugging, adding of breakpoints, and the like. For native code, this is slightly more complex, as we have to resort to using gdb.

The gdb tool is part of the GNU Compiler Collection (GCC), which also contains the compiler used to compile the native code for an Android application. In this case, we want to use its gdb debugger to attach to the native code process on the Android device or AVD so that we can set breakpoints and otherwise monitor the execution.

For gdb to be able to work with such a process, we need to compile the native code with debug symbols enabled, and modify the Android manifest. This involves the following steps:

The NDK contains a script called ndk-gdb that automates the process of setting up gdb, but the essence of what is involved is that we need to push the gdbserver instance onto the device or AVD that we intend to debug on, and connect to this server remotely with gdb. The details of this procedure are beyond the scope of this book, however.

By the end of this book, you will have gained the advanced skills needed to make the most complex AndEngine-based games. These skills will also be useful for other game engines, whether Android-based or not. We will have built a full game application that demonstrates the full possibilities of using AndEngine as the base platform.

These possibilities include advanced graphics options, multiplayer, 3D effects, scene transitions, and user interfaces. With the knowledge gained, you should be able to create your own games with ease, or cooperate with others to make even larger and more complex games.

In this chapter, we went over the basics of Android development, as well as the setting up of a basic AndEngine application. We covered the debugging techniques for both Java-based and native code, and explored the advantages and disadvantages of hardware Android devices and emulated devices. Finally, we looked ahead to what our goals for the coming chapters are, including the development of an application that demonstrates the lessons of these chapters.

In the next chapter, we will build on this basic framework as we extend it to support three-dimensional objects (meshes) in our project.