Android Game Development Tutorial in AndEngine - Part 3 - Game Activity

From now on, the coding starts. At the end of each part, you should have an app that you can run on your phone.

First, you need to setup your environment. For the purpose of this tutorial I expect you already have Eclipse and AndEngine libraries. If not, you can check my Getting Started with AndEngine tutorial.

It doesn't matter if you download zipped versions or use the GitHub tutorial to get the AndEngine sources.

Note: I use GLES2-AnchorCenter branch of AndEngine for this tutorial.

In this part I will show you the basic activity that I am going to use. The activity class should take care of initializing the game engine and managers. You can see plenty of examples where the activity takes care of the game too. But try to separate functionality - rule of thumb: You should be able to describe the class responsibility by one sentence. If you need to use more than one, it's time to split the class.

Now go ahead and create new Android Application Project (Eclipse -> New).

Click next. Don't bother with the icon now and leave there the default. Next again and let the wizard create a blank activity for you. I like to call it GameActivity. It will be the name of your java class as well.

Go to project properties and add AndEngine as android library. Again, go to Getting Started to see how if you need to.

Game Activity class

Right now your GameActivity extends Activity, which is a basic Android activity class. We will change it to BaseGameActivity which is AndEngine's basic activity class. BaseGameActivity implements the default Android behaviour and forces you to implement hooks for Engine Options, Engine, Resources and Scene creation. When you do that, you will notice that you get an error and you have to implement abstract methods from BaseGameActivity.


public class GameActivity extends BaseGameActivity  {
}

Now implement these methods by adding empty bodies first. Notice that I have selected to override few more methods:


package is.kul.squongtutorial;

import java.io.IOException;
import org.andengine.engine.Engine;
import org.andengine.engine.options.EngineOptions;
import org.andengine.entity.scene.Scene;
import org.andengine.ui.activity.BaseGameActivity;

import android.view.KeyEvent;

public class GameActivity extends BaseGameActivity  {
  @Override
  public synchronized void onResumeGame() {
    super.onResumeGame();
  }

  @Override
  public synchronized void onPauseGame() {
    super.onPauseGame();
  }
  
  @Override
  public EngineOptions onCreateEngineOptions() {
    return null;
  }

  @Override
  public Engine onCreateEngine(EngineOptions pEngineOptions) {
    return super.onCreateEngine(pEngineOptions);
  }

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

  @Override
  public void onCreateScene(OnCreateSceneCallback pOnCreateSceneCallback)
      throws IOException {
    pOnCreateSceneCallback.onCreateSceneFinished(null);
  }

  @Override
  public void onPopulateScene(Scene pScene,
      OnPopulateSceneCallback pOnPopulateSceneCallback)
      throws IOException {
    pOnPopulateSceneCallback.onPopulateSceneFinished();
  }
  
  @Override
  public boolean onKeyDown(int keyCode, KeyEvent event) {
    return super.onKeyDown(keyCode, event);
  }

}

Now we are going to implement some of the methods. Start by adding basic contants (screen size) and the camera object. Notice that I am using 720x1200 pixels. AndEngine will take care of the scaling this to any screen.

Camera defines which part of the scene will be shown. Scene can be 5000px wide, and if your camera is 1200 pixels wide, then about 1/4 of the scene is shown.


  public static final int CW = 720;
  public static final int CH = 1200;
  Camera camera;

Next implement the following method. AndEngine will call it first to ask us, what options do we want in the Engine.

Engine is taking care of the game loop. It will call the current scene to render all objects, make necessary calculations and repeat. It also takes care of how is the scene rendered on screen etc.

Create new camera here (same dimensions as the screen, easiest). Then I selected fullscreen (the first true) and RatioResolutionPolicy for screen. More about policies here.. Then fixed portrait orientation, and pass the camera in. Audio both music and sounds, wake lock means that the screen will not turn off when playing.


  @Override
  public EngineOptions onCreateEngineOptions() {
    camera = new Camera(0, 0, CW, CH);
    IResolutionPolicy resolutionPolicy = new RatioResolutionPolicy(CW, CH);
    EngineOptions engineOptions = new EngineOptions(true, ScreenOrientation.PORTRAIT_FIXED, resolutionPolicy, camera);
    engineOptions.getAudioOptions().setNeedsMusic(true).setNeedsSound(true);
    engineOptions.setWakeLockOptions(WakeLockOptions.SCREEN_ON);
    return engineOptions;
  }

We will create an engine that will render maximum 60 frames per second. This saves battery. You can use as less as 30 FPS and still get smooth gameplay. Experiment with this number. It's also nice to have a constant for FPS to easily change it. Add it and implement the method body:


  public static final int FPS_LIMIT = 60;

  @Override
  public Engine onCreateEngine(EngineOptions pEngineOptions) {
    Engine engine = new LimitedFPSEngine(pEngineOptions, FPS_LIMIT);
    return engine;
  }

Notice some methods are implemented and they call some callbacks. These methods are there to notify the engine that certain part has finished. We are going to implement resource and scene creation in next part.

Right now you can run the app and see nice black screen. Thanks to the resolution policy and the fact that we have created non-standard 720x1200 pixels area on the screen, you should see white stripes either on the left and right or top and bottom. That's how AndEngine deals with different resolutions. Don't worry about it, in this tutorial, we will hide the white stripes.

Next part

In the next part I will explain my take on SceneManagement.

Greetings!

Tuesday 22 October 2013