AndEngine for Android Game Development Cookbook

Please refer to the class named PacktRecipesActivity in the code bundle.

The AndEngine life cycle includes a few methods that we are responsible for defining directly. These methods include creating the EngineOptions object, creating the Scene object, and populating the scene with child entities. These methods are called in the following order:

The code found in this recipe's class is the foundation for any AndEngine game. We've set up a main activity class which serves as the entry point into our application. The activity contains the four main methods included in AndEngine's activity life cycle that we are responsible for, beginning with creating the EngineOptions options, creating the resources, creating the scene, and populating the scene.

In the first step, we are overriding the Engine's onCreateEngineOptions() method. Inside this method, our main focus is to instantiate our Camera object as well as our EngineOptions object. These two object's constructors allow us to define the display properties of our application. Additionally, we've disabled the screen from automatically turning off during application inactivity via the engineOptions.setWakeLockOptions(WakeLockOptions.SCREEN_ON) method call.

In step two, we continue to override the onCreateResources() method, which gives us a specified method for creating and setting up any resources needed within our game. These resources may include textures, sounds and music, and fonts. In this step and the following two, we are required to make a call to the respective method callbacks in order to proceed through the application's life cycle. For the onCreateResources() method, we must call pOnCreateResourcesCallback.onCreateResourcesFinished(), which should be included at the end of the method.

Step three involves instantiating and setting up the Scene object. Setting up the Scene can be as simple as displayed in this recipe, or for more complex projects, it may include setting up touch event listeners, update handlers, and more. Once we've finished setting up the Scene, we must make a call to the pOnCreateSceneCallback.onCreateSceneFinished(mScene) method, passing our newly created mScene object to the Engine to be displayed on the device.

The final step to take care of includes defining the onPopulateScene() method. This method is in place specifically for attaching child entities to the Scene. As with the previous two steps, we must make a call to pOnPopulateSceneCallback.onPopulateSceneFinished() in order to proceed with the remaining AndEngine life cycle calls.

In the following list, we will cover the life cycle methods in the order they are called from the start up of an activity to the time it is terminated.

The life cycle calls during launch are as follows:

The life cycle calls during minimzation/termination are as follows:

In the following image, we can see what the life cycle looks like in action when the game is created, minimized, or destroyed:

In the previous section of this recipe, we covered the main BaseGameActivity class. The following classes can be used as alternatives to the BaseGameActivity class, each providing their own slight differences.

@Override
public void onCreateResourcesAsync(IProgressListener pProgressListener)
    throws Exception {

  // Load texture number one
  pProgressListener.onProgressChanged(10);

  // Load texture number two
  pProgressListener.onProgressChanged(20);

  // Load texture number three
  pProgressListener.onProgressChanged(30);

  // We can continue to set progress to whichever value we'd like
  // for each additional step through onCreateResourcesAsync...
}

Carry out the Know the life cycle recipe in this chapter to get a basic AndEngine project set up in our IDE, then continue on to the How to do it... section.

In order for us to properly define a specific Engine object for our game to use, we must override the onCreateEngine() method, which is part of AndEngine's startup process. Add the following code to any base AndEngine activity in order to handle the Engine's creation manually:

/* The onCreateEngine method allows us to return a 'customized' Engine object
* to the Activity which for the most part affects the way frame updates are 
* handled. Depending on the Engine object used, the overall feel of the 
* gameplay can alter drastically. 
*/
@Override
public Engine onCreateEngine(EngineOptions pEngineOptions) {
  return super.onCreateEngine(pEngineOptions);
  /* The returned super method above simply calls:
      return new Engine(pEngineOptions);
  */
}

The following is an overview of the various Engine objects available in AndEngine, as well as a brief code snippet displaying how to set up each of the Engine objects:

The resolution policy that we choose to adhere to must be included as a parameter in the EngineOptions constructor which is created in the onCreateEngineOptions() method of AndEngine's life cycle. The following code creates our EngineOptions object using the FillResolutionPolicy class, which will be explained later in the chapter:

EngineOptions engineOptions = new EngineOptions(true,
    ScreenOrientation.LANDSCAPE_FIXED, new FillResolutionPolicy(),
    mCamera); 

We can select a different resolution policy by simply passing another variation of the resolution policy classes to this constructor.

The following is an overview of AndEngine's BaseResolutionPolicy subtypes. These policies are used to specify how AndEngine will handle our application's display width and height based on various factors:

Please refer to the class named ObjectFactory in the code bundle.

In this recipe, we're using the ObjectFactory class as a way for us to easily create and return subtypes of the BaseObject class. However, in a real-world project, the factory would not normally contain inner classes.

In the first step of this recipe, we are creating a BaseObject class. This class includes two member variables called mX and mY, which we can imagine would define the position on the device's display if we are dealing with AndEngine entities. Once we've got our base class set up, we can start creating subtypes of the base class. The BaseObject class in this recipe has two inner classes which extend it, one named LargeObject and the other, SmallObject. The object factory's job is to determine which subtype of the base class that we need to create, as well as define the object's properties, or mX and mY member variables in this instance.

In the second step, we are taking a look at the ObjectFactory code. This class should contain any and all variations for object creation relating to the specific object-types that the factory deals with. In this case, the two separate objects simply require an mX and mY variable to be defined. In a real-world situation, we may find it helpful to create a SpriteFactory class. This class might contain a few different methods for creating ordinary sprites, button sprites, or tiled sprites, via SpriteFactory.createSprite(), SpriteFactory.createButtonSprite(), and SpriteFactory.createTiledSprite(). On top of that, each of these methods would probably require parameters that define the position, scale, texture region, color, and more. The most important aspect to this class is that its methods return a new subtype of an object as this is the whole purpose behind the factory class.

Please refer to the class named GameManager in the code bundle.

The game manager we're going to introduce will be following the singleton design pattern. This means that we will only create a single instance of the class throughout the entire application life cycle and we can access its methods across our entire project. Follow these steps:

Depending on the type of game being created, the game manager is bound to have different tasks. This recipe's GameManager class is meant to resemble that of a certain emotional bird franchise. We can see that the tasks involved in this particular GameManager class are limited, but as gameplay becomes more complex, the game manager will often grow as it has more info to keep track of.

In the first step for this recipe, we're setting up the GameManager class as a singleton. The singleton is a design pattern that is meant to ensure that there is only one static instance of this class that will be instantiated throughout the entire application's life cycle. Being static, this will allow us to make calls to the game manager's methods on a global level, meaning we can reach its methods from any class in our project without having to create a new GameManager class. In order to retrieve the GameManager class' instance, we can call GameManager.getInstance() in any of our project's classes. Doing so will assign a new GameManager class to INSTANCE, if the GameManager class has not yet been referenced. The INSTANCE object will then be returned, allowing us to make calls to the GameManager class' data-modifying methods, for example, GameManager.getInstance().getCurrentScore().

In step two, we create the getter and setter methods that will be used to modify and obtain the data being stored in the GameManager class. The GameManager class in this recipe contains three int values that are used to keep track of important gameplay data; mCurrentScore, mBirdCount, and mEnemyCount. Each of these variables have their own corresponding getters and setters that allow us to easily make modifications to the game data. During gameplay, if an enemy happened to be destroyed then we could call GameManager.getInstance().decrementEnemyCount() along with GameManager.getInstance().incrementScore(pValue), where pValue would likely be provided by the enemy object being destroyed.

The final step involved in setting up this game manager is to provide a reset method for game data. Since we are working with a singleton, whether we move from gameplay to the main menu, to the shop, or any other scene, our GameManager class' data will not automatically revert back to default values. This means that any time a level is reset, we must reset the game manager's data as well. In the GameManager class, we've set up a method called resetGame(), whose job is to simply revert data back to original values.

When starting a new level, we can call GameManager.getInstance().resetGame() in order to quickly revert all data back to the initial values. However, this is a general GameManager class and it is entirely up to the developer which data should be reset pending level reset or level loading. If the GameManager class is storing credit/currency data, it might be wise not to reset that particular variable back to default for use in a shop, for example.

Complete the Know the life cycle recipe given in this chapter, so that we've got a basic AndEngine project set up in our IDE. Additionally, we should create a new subfolder in our project's assets/ folder. Name this folder as sfx and add a sound file named sound.mp3 and another named music.mp3. Once this is done, continue on to the How to do it... section.

Perform the following steps to set up a game to use the Sound and Music objects. Note that Sound objects are meant for sound effects, such as explosions, collisions, or other short audio playback events. The Music objects are meant for long audio playback events such as looping menu music or game music.

In the first step for this recipe, we are required to let the Engine know whether we will be taking advantage of AndEngine's ability to play Sound or Music objects. Failing to address this step will cause an error in the application, so before we move forward in implementing audio into our game, make sure this step is done before returning EngineOptions in the onCreateEngineOptions() method.

In the second step, we are visiting the onCreateResources() method of the application's life cycle. Firstly, we are setting the base path of both SoundFactory and MusicFactory. As mentioned in the Getting ready section, we should have a folder for our audio files in the assets/sfx folder in our project, which includes all of our audio files. By calling setAssetBasePath("sfx/") on each of the two factory classes used for audio, we are now pointing to the proper folder to look for audio files. Once this is done, we can load our Sound objects through the use of the SoundFactory class and Music objects through the use of the MusicFactory class. The Sound and Music objects require us to pass the following parameters: mEngine.getSoundManager() or mEngine.getMusicManager() depending on the type of audio object we're loading, the Context class which is BaseGameActivity, or this activity, and the name of the audio file in string format.

In the third step, we can now call the play() method on the audio object that we wish to play. However, this method should only be called after the onCreateResources()callback has been notified that all resources have been loaded. To be safe, we should simply not play any Sound or Music objects until after the onCreateResources() portion of AndEngine's life cycle.

In the final step, we are setting up our Music object to call its play() method when our activity starts up and onResumeGame() is called from the life cycle. On the other end, during onPauseGame(), the Music object's pause() method is called. It is best practice in most cases to set our Music objects up this way, especially due to the eventual inevitability of application interruptions, such as phone calls or accidental pop-up clicking. This approach will allow our Music object to automatically be paused when the application leaves focus and start back up once we return from minimization, including execution.

AndEngine uses Android native sound classes to provide audio entertainment within our games. These classes include a few additional methods aside from play() and pause() that allow us to have more control over the audio objects during runtime.

Perform the Know the life cycle recipe given in this chapter, so that we've get a basic AndEngine project set up in our IDE. Additionally, this recipe will require three images in PNG format. The first rectangle will be named rectangle_one.png, at 30 pixels wide by 40 pixels in height. The second rectangle named rectangle_two.png, is 40 pixels wide by 30 pixels in height. The final rectangle is named rectangle_three.png, at 70 pixels wide by 50 pixels in height. Once these rectangle images have been added to the project's assets/gfx/ folder, continue on to the How to do it... section.

There are two main components involved when building a texture in AndEngine. In the following steps, we will be creating what is known as a texture atlas that will store three texture regions out of the three rectangle PNG images mentioned in the Getting ready section.

In AndEngine development, there are two main components we will use in order to create textures for our projects. The first component is known as BitmapTextureAtlas, which can be thought of as a flat surface with a maximum width and height that can store sub-textures within its width and height boundaries. These sub-textures are called texture regions, or ITextureRegion objects in AndEngine to be specific. The purpose of the ITextureRegion object is to act solely as a reference to a specific texture in memory, which is located at position x and y within a BitmapTextureAtlas atlas. One way to look at these two components is to picture a blank canvas, which will represent a texture atlas, and a handful of stickers, which will represent the texture regions. A canvas would have a maximum size, and within that area we can place the stickers wherever we'd like. With this in mind, we place a handful of stickers on the canvas. We've now got all of our stickers neatly laid out on this canvas and accessible to grab and place wherever we'd like. There is a little bit more to it as well, but that will be covered shortly.

With the basics of BitmapTextureAtlas and ITextureRegion objects out of the way, the steps involved in creating our textures should now make more sense. As mentioned in the first step, setting the base path of the BitmapTextureAtlasTextureRegionFactory class is completely optional. We are simply including this step as it saves us from having to repeat saying which folder our images are in once we move on to creating the ITextureRegion objects. For example, if we were not to set the base path, we'd have to reference our images as gfx/rectangle_one.png, gfx/rectangle_two.png, and so on.

In the second step, we are creating our BitmapTextureAtlas object. This step is pretty straightforward as we must simply specify the Engine's TextureManager object which will handle the loading of textures, as well as a width and height for the texture atlas, in that order. Since we're only dealing with three small images in these steps, 120 x 120 pixels will be just fine.

One important thing to keep in mind about texture atlases is to never create excessive texture atlases; as in do not create an atlas that is 256 x 256 for holding a single image which is 32 x 32 pixels for example. The other important point is to avoid creating texture atlases which are larger than 1024 x 1024 pixels. Android devices vary in their maximum texture sizes and while some may be able to store textures up to 2048 x 2048 pixels, a large number of devices have a maximum limit of 1024 x 1024. Exceeding the maximum texture size will either cause a force-closure on startup or simply fail to display proper textures depending on the device. If there is no other option and a large image is absolutely necessary, see Background stitching in Chapter 4, Working with Cameras.

In the third step of this recipe, we are creating our ITextureRegion objects. In other words, we are applying a specified image to the mBitmapTextureAtlas object as well as defining where, exactly, that image will be placed on the atlas. Using the BitmapTextureAtlasTextureRegionFactory class, we can call the createFromAsset(pBitmapTextureAtlas, pContext, pAssetPath, pTextureX, pTextureY) method, which makes creating the texture region a piece of cake. In the order the parameters are listed from left to right, the pBitmapTextureAtlas parameter specifies the texture atlas which we'd like the ITextureRegion object to be stored in. The pContext parameter allows the class to open the image from the gfx/ folder. The pAssetPath parameter defines the name of the specific file we're looking for; example, rectangle_one.png. And the final two parameters, pTextureX and pTextureY, define the location on the texture atlas in which to place the ITextureRegion object. The following image represents what the three ITextureRegion objects would look like as defined in step three. Note that the positions are consistent between the code and image:

In the previous image, notice that there is a minimum gap of 10 pixels between each of the rectangles and the texture edge. The ITextureRegion objects are not spaced out like this to make things more understandable, although it helps. They are actually spaced out in order to add what is known as texture atlas source spacing. What this spacing does is that it prevents the possibility of texture overlapping when a texture is applied to a sprite. This overlapping is called texture bleeding. Although creating textures as seen in this recipe does not completely mitigate the chance of texture bleeding, it does reduce the likelihood of this issue when certain texture options are applied to the texture atlas.

See the Applying texture options recipe given in this chapter for more information on texture options. Additionally, the There's more... section in this topic describes another method of creating texture atlases, which completely solves the texture bleeding issue! It is highly recommended.

There is an abundance of different approaches we can take when it comes to adding textures into our game. They all have their own benefits and some even have negative aspects involved.

/* Create a buildable bitmap texture atlas - same parameters required
* as with the original bitmap texture atlas */
BuildableBitmapTextureAtlas mBuildableBitmapTextureAtlas = new BuildableBitmapTextureAtlas(mEngine.getTextureManager(), 120, 120);

/* Create the three ITextureRegion objects. Notice that when using 
 * the BuildableBitmapTextureAtlas, we do not need to include the final
 * two pTextureX and pTextureY parameters. These are handled automatically! */
ITextureRegion mRectangleOneTextureRegion = BitmapTextureAtlasTextureRegionFactory.createFromAsset(mBuildableBitmapTextureAtlas, this, "rectangle_one.png");
ITextureRegion mRectangleTwoTextureRegion = BitmapTextureAtlasTextureRegionFactory.createFromAsset(mBuildableBitmapTextureAtlas, this, "rectangle_two.png");
ITextureRegion mRectangleThreeTextureRegion = BitmapTextureAtlasTextureRegionFactory.createFromAsset(mBuildableBitmapTextureAtlas, this, "rectangle_three.png");

// Buildable bitmap texture atlases require a try/catch statement
try {
  /* Build the mBuildableBitmapTextureAtlas, supplying a BlackPawnTextureAtlasBuilder
    * as its only parameter. Within the BlackPawnTextureAtlasBuilder's parameters, we
    * provide 1 pixel in texture atlas source space and 1 pixel for texture atlas source
    * padding. This will alleviate the chance of texture bleeding.
    */
  mBuildableBitmapTextureAtlas.build(new BlackPawnTextureAtlasBuilder<IBitmapTextureAtlasSource, BitmapTextureAtlas>(0, 1, 1));
} catch (TextureAtlasBuilderException e) {
  e.printStackTrace();
}

// Once the atlas has been built, we can now load
mBuildableBitmapTextureAtlas.load();

TiledTextureRegion

A tiled texture region is essentially the same object as a normal texture region. The difference between the two is that a tiled texture region allows us to pass a single image file to it and create a sprite sheet out of it. This is done by specifying the number of columns and rows within our sprite sheet. From there, AndEngine will automatically divide the tiled texture region into evenly distributed segments. This will allow us to navigate through each segment within the TiledTextureRegion object. This is how the tiled texture region will appear to create a sprite with animation:

Note

A real sprite sheet should not have outlines around each column and row. They are in place in the previous image to display how a sprite sheet is divided up into equal segments.

Let's assume that the previous image is 165 pixels wide and 50 pixels high. Since we have 11 individual columns and a single row, we could create the TiledTextureRegion object like so:

TiledTextureRegion mTiledTextureRegion = BitmapTextureAtlasTextureRegionFactory.createTiledFromAsset(mBitmapTextureAtlas, context,"sprite_sheet.png",11,1);

What this code does is it tells AndEngine to divide the sprite_sheet.png image into 11 individual segments, each 15 pixels wide (since 165 pixels divided by 11 segments equals 15). We can now use this tiled texture region object to instantiate a sprite with animation.

Perform the Working with different types of textures recipe given in this chapter, so that we've got a basic AndEngine project set up with BitmapTextureAtlas or BuildableBitmapTextureAtlas loading in place.

In order to modify a texture atlas' option and/or format, we need to add a parameter or two to the BitmapTextureAtlas constructor depending on whether we'd like to define either the options, format, or both. See the following code for modifying both, texture format and texture options:

BitmapTextureAtlas mBitmapTextureAtlas = new BitmapTextureAtlas(mEngine.getTextureManager(), 1024, 1024, BitmapTextureFormat.RGB_565, TextureOptions.BILINEAR);

From here on, all texture regions placed on this specific texture atlas will have the defined texture format and option applied to it.

AndEngine allows us to apply texture options and formats to our texture atlases. The various combination of options and formats applied to a texture atlas will affect the overall quality and performance impact that sprites have on our game. Of course, that is if the mentioned sprites are using ITextureRegion objects, which are related to the modified BitmapTextureAtlas atlas.

The base texture options available in AndEngine are as follows:

Take a look at the following figure to see a comparison between bilinear filtering and nearest filtering:

These two images are rendered in the highest bitmap format. The difference between nearest and bilinear filtering is very clear in this case. In the left-hand side of the image, the bilinear star has almost no jagged edges and the colors are very smooth. On the right-hand side, we've got a star rendered with the nearest filtering. The quality level suffers as jagged edges are more apparent and if observed closely, the colors aren't as smooth.

The following are a few additional texture options:

Repeating: The repeating texture option allows the sprite to "repeat" the texture assuming that the ITextureRegion object's width and height has been exceeded by the size of the sprite. In most games, the terrain is usually generated by creating a repeating texture and stretching the size of the sprite, rather than creating many separate sprites to cover the ground.

Let's take a look at how to create a repeating texture:

    /* Create our repeating texture. Repeating textures require width/height which are a power of two */
    BuildableBitmapTextureAtlas texture = new BuildableBitmapTextureAtlas(engine.getTextureManager(), 32, 32, TextureOptions.REPEATING_BILINEAR);
    
    // Create our texture region - nothing new here
    mSquareTextureRegion = BitmapTextureAtlasTextureRegionFactory.createFromAsset(texture, context, "square.png");

    try {
      // Repeating textures should not have padding
      texture.build(new BlackPawnTextureAtlasBuilder<IBitmapTextureAtlasSource, BitmapTextureAtlas>(0, 0, 0));
      texture.load();

    } catch (TextureAtlasBuilderException e) {
      Debug.e(e);
    }

The previous code is based on a square image which is 32 x 32 pixels in dimension. Two things to keep in mind when creating repeating textures are as follows:

Next, we have to create a sprite which uses this repeated texture:

/* Increase the texture region's size, allowing repeating textures to stretch up to 800x480 */
ResourceManager.getInstance().mSquareTextureRegion.setTextureSize(800, 480);
// Create a sprite which stretches across the full screen
Sprite sprite = new Sprite(0, 0, 800, 480, ResourceManager.getInstance().mSquareTextureRegion, mEngine.getVertexBufferObjectManager());

What we're doing here is increasing the texture region's size to 800 x 480 pixels in dimension. This doesn't alter the size of the image while the repeating option is applied to a texture, rather it allows the image to be repeated up to 800 x 480 pixels. This means that if we create a sprite and supply the repeating texture, we can scale the sprite up to 800 x 480 pixels in dimension, while still displaying a repeat effect. However, if the sprite exceeds the width or height dimensions of the texture region, no texture will be applied to the exceeding area.

Here's the outcome taken from a device screenshot:

Pre-multiply alpha: Lastly, we have the option to add the pre-multiply alpha texture option to our textures. What this option does is multiply each of the RGB values by the specified alpha channel and then apply the alpha channel in the end. The main purpose of this option is to allow us to modify the opacity of the colors without loss of color. Keep in mind, modifying the alpha value of a sprite directly may introduce unwanted effects when using pre-multiplied alpha values. Sprites will likely not appear fully transparent when this option is applied to sprites with an alpha value of 0.

When applying texture options to our texture atlases, we can choose either nearest or bilinear texture filtering options. On top of these texture filtering options, we can include either the repeating option, the pre-multiply alpha option, or even both.

Aside from texture options, AndEngine also allows us to set the texture format of each of our texture atlases. Texture formats, similar to texture options, are often decided upon depending on its purpose. The format of a texture can greatly affect both the performance and quality of an image even more noticeably than the texture options. Texture formats allow us to choose the available color ranges of the RGB values in a texture atlas. Depending on the texture format being used, we may also allow or disallow a sprite from having any alpha value which affects the transparency of the textures.

The texture format naming conventions are not very complicated. All formats have a name similar to RGBA_8888, where the left-hand side of the underscore refers to the color or alpha channels available to the texture. The right-hand side of the underscore refers to the bits available to each of the color channels.

Perform the Know the life cycle recipe given in this chapter, so that we've got a basic AndEngine project set up in our IDE, then continue on to the How to do it... section.

The following code snippets display the four different options we have for creating preset, custom asset, preset stroke, and custom asset stroke font objects. Font creation should take place in the onCreateResources() method of our BaseGameActivity class.

As we can see, there are different approaches we can take to create our Font objects depending on how we'd like the font to look. However, all fonts share the need for us to define a texture width and texture height, whether it be directly as parameters in the FontFactory class' create methods or indirectly through the use of a BitmapTextureAtlas object. In the previous code snippets, we'd created all three Font objects using a texture size of 256 pixels in width by 256 pixels in height. Unfortunately, there is currently no easy way to automatically determine the texture size needed at runtime in order to support different languages, text sizes, stroke value, or font style.

For now, the most common approach is to set the texture width and height to about 256 pixels and make small adjustments upward or downward until the texture is just the right size so as to not cause artifacts in the Text objects. The font size plays the biggest role in determining the final texture size needed for the Font object, so exceedingly large fonts, such as 32 and higher, may need larger texture sizes.

Let's take a look at how each of the methods presented in the How to do it... section work:

The way the Font class is currently set up, it is best to preload the characters that we expect to display via a Text object. Unfortunately, AndEngine currently makes calls to the garbage collector when new letters are still to be drawn, so in order to avoid hiccups when a Text object is first getting "acquainted" with the letters, we can call the method:

mFont.prepareLetters("abcdefghijklmnopqrstuvwxyz".toCharArray())

This method call would prepare the lowercase letters from a to z. This method should be called during a loading screen at some point within the game in order to avoid any noticeable garbage collection. There's one more important class that we should discuss before moving off the topic of Font objects. AndEngine includes a class called FontUtils that allows us to retrieve information regarding a Text object's width on the screen via the measureText(pFont, pText) method. This is important when dealing with dynamically-changing strings as it gives us the option to relocate our Text object, assuming that the width or height of the string in pixels has changed.

Please refer to the class named ResourceManager in the code bundle.

The ResourceManager class is designed with the singleton design pattern in mind. This allows for global access to all of our game's resources through a simple call to ResourceManager.getInstance(). The main purpose of the ResourceManager class is to store resource objects, load resources, and unload resources. The following steps display how we can use ResourceManager to handle textures of one of our game's scenes.

By implementing a ResourceManager class into our project, we can easily load our various scene resources completely indepenently of one another. Because of this, we must make sure that our public class methods are synchronized in order to make sure that we're running in a thread-safe environment. This is especially important with the use of singletons, as we've only got one instance of the class, with the potential for multiple threads accessing it. On top of that, we now only require one line of code when it comes to loading our scene resources which helps greatly in keeping our main activity class more organized. Here is what our onCreateResources() methods should look like with the use of a resource manager:

@Override
public void onCreateResources(
    OnCreateResourcesCallback pOnCreateResourcesCallback) {
  
  // Load the game texture resources
  ResourceManager.getInstance().loadGameTextures(mEngine, this);
    
  // Load the font resources
  ResourceManager.getInstance().loadFonts(mEngine);
    
  // Load the sound resources
  ResourceManager.getInstance().loadSounds(mEngine, this);
    
  pOnCreateResourcesCallback.onCreateResourcesFinished();
}

In the first step, we are declaring all of our resources, including Font objects, ITextureRegion objects, and Sound/Music objects. In this particular recipe, we're only working with a limited number of resources, but in a fully-functional game, this class may include 50, 75, or even more than 100 resources. In order to obtain a resource from our ResourceManager class, we can simply include the following line into any class within our project:

ResourceManager.getInstance().mGameBackgroundTextureRegion.

In the second step, we create the loadGameTextures(pEngine, pContext) method which is used to load the Game scene textures. For every additional scene within our game, we should have a separate load method in place. This allows for easy loading of resources on the fly.

In the final step, we're creating unload methods which handle unloading the resources corresponding to each of the load methods. However, if there are any number of resources which happen to be used throughout a number of our game's scenes, it might be necessary to create a load method which doesn't come with an accompanying unload method.

In larger projects, sometimes we may find ourselves passing main objects to classes very frequently. Another use for the resource manager is to store some of the more important game objects such as the Engine or Camera. This way we no longer have to continuously pass these objects as parameters, rather we can call respective get methods in order to get the game's Camera, Engine, or any other specific object we'll need to reference throughout the classes.

Please refer to the class named UserData in the code bundle.

In this recipe, we're setting up a UserData class that will store a Boolean variable to determine sound muting and an int variable that will define the highest, unlocked level a user has reached. Depending on the needs of the game, there may be more or less datatypes to include within the class for different reasons, be it high score, currency, or other game-related data. The following steps describe how to set up a class to contain and store user data on a user's device:

This class demonstrates just how easily we are able to store and retrieve a game's data and options through the use of the SharedPreferences class. The structure of the UserData class is fairly straightforward and can be used in this same fashion in order to adapt to various other options we might want to include in our games.

In the first step, we simply start off by declaring all of the necessary constants and member variables that we'll need to handle different types of data within our game. For constants, we have one String variable named PREFS_NAME that defines the name of our game's preference file, as well as two other String variables that will each act as references to a single primitive datatype within the preference file. For each key constant, we should declare a corresponding variable that preference file data will be stored to when it is first loaded.

In the second step, we provide a means of loading the data from our game's preference file. This method only needs to be called once, during the startup process of a game in order to load the UserData classes member variables with the data stored in the SharedPreferences file. By first calling context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE), we check to see whether or not a SharedPreference file exists for our application under the PREFS_NAME string, and if not, then we create a new one a—MODE_PRIVATE, meaning the file is not visible to other applications.

Once that is done, we can call getter methods from the preference file such as mUnlockedLevels = mSettings.getInt(UNLOCKED_LEVEL_KEY, 1). This will pass the data stored in the UNLOCKED_LEVEL_KEY key of the preference file to mUnlockedLevels. If the game's preference file does not currently hold any value for the defined key, then a default value of 1 is passed to mUnlockedLevels. This would continue to be done for each of the datatypes being handled by the UserData class. In this case, just the levels and sound.

In the third step, we set up the getter methods that will correspond to each of the datatypes being handled by the UserData class. These methods can be used throughout the game; for example, we could call UserData.getInstance().isSoundMuted() during level loading to determine whether or not we should call play() on the Music object.

In the fourth step, we create the methods that save data to the device. These methods are pretty straightforward and should be fairly similar regardless of the data we're working with. We can either take a value from a parameter as seen with setSoundMuted(pEnableSound) or simply increment as seen in unlockNextLevel().

When we want to finally save the data to the device, we use the mEditor object, using putter methods which are suitable for the primitive datatype we wish to store, specifying the key to store the data as well as the value. For example, for level unlocking, we use the method, mEditor.putInt(UNLOCKED_LEVEL_KEY, mUnlockedLevels) as we are storing an int variable. For a boolean variable, we call putBoolean(pKey, pValue), for a String variable, we call putString(pKey, pValue), and so on..

Unfortunately, when storing data on a client's device, there's no way of guaranteeing that a user will not have access to the data in order to manipulate it. On the Android platform, most users will not have access to the SharedPreferences file that holds our game data, but users with rooted devices on the other hand will be able to see the file and make changes as they see fit. For the sake of explanation, we used obvious key names, such as soundKey and unlockedLevels. Using some sort of misconstruction can help to make the file look more like gibberish to an average user who had accidentally stumbled upon the game data with their rooted device.

If we feel like going further to protect the game data, then the even more secure approach would be to encrypt the preference file. Java's javax.crypto.* package is a good place to start, but keep in mind that encryption and decryption does take time and will likely increase the duration of loading times within the game.