Simple tutorial for using e3roid 2D OpenGL framework for Android


SDK Version: 
M3

First we need to install e3roid game framework. Download the latest e3roid source distribution(e3roid-source-X.X.zip) from Google code project page and unzip it to appropriate directory. We can find more detailed informations about the installing at the e3roid blog.

After the preparations let's create a new Android Application. At first we need a new Activity which extends the E3Activity to declare using e3roid framework. This is the base activity class of the engine.

  1. public class OpenGLDemoActivity extends E3Activity
  2. {
  3.     ...
  4. }

In the onCreate() method we detect the display parameters of the mobile device because the width and height values needed to create the game engine.

  1. @Override
  2. protected void onCreate( Bundle savedInstanceState )
  3. {
  4.         Display display = getWindowManager().getDefaultDisplay();
  5.         width = display.getWidth();
  6.         height = display.getHeight();
  7.  
  8.         super.onCreate( savedInstanceState );
  9. }

The E3Engine a base engine for the framework that is responsible for rendering.

  1. @Override
  2. public E3Engine onLoadEngine()
  3. {
  4.         E3Engine engine = new E3Engine( this, width, height );
  5.         engine.requestFullScreen();
  6.         engine.requestPortrait();
  7.         return engine;
  8. }

After initializing e3roid engine by overriding onLoadEngine(), we can add resources (sprite, shape, etc) by overriding onLoadResources(). The example shows how to instantiate the textures. If we use AssetTexture class, images must be saved into the “assets” folder. Transparent PNG image can be used if the sprite needs transparency. Transparent GIF image is currently not supported.

  1. @Override
  2. public void onLoadResources()
  3. {
  4.         //texture for the droid
  5.         robotTexture = new AssetTexture( "gfx/droid.png", this );
  6.         //background's texture
  7.         Bitmap tile = BitmapUtil.getTileBitmapFromAsset(
  8.                 "gfx/bg.png", 64, 64, 0, 0, 0, this );
  9. }

After initializing sprites, we can create e3roid’s “scene” and move the robot sprite into the scene. The scene width and height can be obtained by calling getWidth and getHeight. The example shows how to instantiate and add on center of the screen the sprite. After moving sprites, we must “add” the sprite to the scene.

  1. @Override
  2. public E3Scene onLoadScene()
  3. {
  4.         E3Scene scene = new E3Scene();
  5.         scene.addEventListener( this );
  6.  
  7.         Background background = new Background(
  8.                 tile, getWidth(), getHeight(), this );
  9.         scene.getTopLayer().setBackground( background );
  10.  
  11.         int centerX = (getWidth() - robotTexture.getWidth()) / 2;
  12.         int centerY = (getHeight() - robotTexture.getHeight()) / 2;
  13.  
  14.         robot = new Sprite( robotTexture, centerX, centerY );
  15.         scene.getTopLayer().add( robot );
  16.         Toast.makeText(
  17.                 this, "Touch screen to move the sprite.", Toast.LENGTH_LONG )
  18.         .show();
  19.  
  20.         return scene;
  21. }

To handle user’s interactions, add event listener to the scene first. By adding listener to the scene, the onSceneTouchEvent method will be called when user touches the screen.

  1. @Override
  2. public E3Scene onLoadScene()
  3. {
  4.         E3Scene scene = new E3Scene();
  5.         scene.addEventListener( this );
  6.         // snip ...
  7. }

And then override onSceneTouchEvent method and implement it like below. The example below moves the sprite on the center of the touched position. Remember that the location we can get from motion event(getX,getY) is the actual device’s raw pointer location. To adjust the coordinates that fit with the screen size defined in the E3Engine’s constructor, use getTouchEventX and getTouchEventY method.

  1. @Override
  2. public boolean onSceneTouchEvent( E3Scene scene, MotionEvent motionEvent )
  3. {
  4.         if( robot != null )
  5.         {
  6.                 if( motionEvent.getAction() == MotionEvent.ACTION_DOWN )
  7.                 {
  8.                         int x = getTouchEventX( scene, motionEvent ) -
  9.                                   (robotTexture.getWidth() / 2);
  10.                         int y = getTouchEventY( scene, motionEvent ) -
  11.                                   (robotTexture.getHeight() / 2);
  12.                         robot.move( x, y );
  13.                 }
  14.         }
  15.         return false;
  16. }

The result should look like this:

screenshot

I hope you find useful this tutorial. If you interested in more detailed examples, please visit the official website of the e3roid open source Android 2D game library.