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.

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.

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 is called from the onCreateResourcesCallback object when you call the Finished method. It is used to create a scene object or objects.

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 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();
}