Remember to have the sample projects imported into your Eclipse workspace by right-clicking on the Package Explorer panel, selecting Import, and then clicking on Gradle Project again. Go back to Chapter 1, Diving into Libgdx, if you need some assistance.

The code for this recipe is in the CustomLoaderSample.java file within the [cookbook]/samples folder. It will lean on the com.cookbook.animation package.

The initial decision to make is whether your type will be loaded synchronously or asynchronously. As mentioned in the preceding recipes, using the synchronous loader means blocking the application (rendering thread) until the resource is loaded. On the other hand, an asynchronous loader allows your game to be responsive because the load will be performed on a secondary thread. Base your decision on the loading speed of your asset.

To carry out the implementation of custom loaders, Libgdx provides us with two abstract classes to extend, AsynchronousAssetLoader<T, P> and SynchronousAssetLoader<T, P>, where T represents the type to load, and P an extended type of the AssetLoaderParameters interface. As mentioned in the first recipe of this chapter, AssetLoaderParameters class allows you to load the data type with some initialization parameters.

A custom SynchronousAssetLoader class will have to override the load(...) method, whereas AsynchronousAssetLoader will do likewise with loadAsync(...) and loadSync(...).

It is important to understand that the example shown in this recipe is just to illustrate, with a practical case, the process to follow when creating your custom asset loader. Focusing on the idea is the best perspective to adopt in the next sections.

public class SpriteAnimationData {
...
Texture texture = null;
int rows = 0;
int columns = 0;
float frameDuration = 0.0f;
ObjectMap<String, Animation> animations = new ObjectMap<String, Animation>();
Animation defaultAnimation = null; 

public class SpriteAnimationLoader extends AsynchronousAssetLoader<SpriteAnimationData, SpriteAnimationLoader.AnimationParameter> {
...
}

Static public class AnimationParameter extends AssetLoaderParameters<SpriteAnimationData> { }

private SpriteAnimationData animationData = null;

public SpriteAnimationLoader(FileHandleResolver resolver) {
   super(resolver);
}

@Override
public SpriteAnimationData loadSync(AssetManager manager, String filename, FileHandle, AnimationParameter parameter) {
   return animationData;
}

{
   "rows": "2",
   "columns": "5",
   "frameDuration": "0.025f",
   "animations" : [
     {
      "name": "walk",
      "frames": "0,1,2,3,4,5,6"
     }
   ]
}

Both AsynchronousAssetLoader and SynchronousAssetLoader extend the AssetLoader abstract class, which is really the one in charge of calling the resolve(...) method from its set FileHandleResolver, already discussed in the first recipe of this chapter.

Here is a table with a classification of built-in type loaders:

TextureLoader is an OpenGL-descendant part that is performed on the rendering thread. BitmapFontLoader, SkinLoader, TextureAtlasLoader, and ModelLoader are AssetManagers that will load its dependencies before the actual asset.

As seen in Chapter 4, Detecting User Input, note that music resources are streamed, so it won't have to load the whole thing.

Custom asset loading is not fully covered in this chapter because there are some particular cases where dependencies exist between resources. To deal with this scenario, the assets loader abstract classes provide us with the getDependencies(...) method, which when applied to the SpriteAnimationLoader context, result in the following:

@Override
public Array<AssetDescriptor> getDependencies( String filename, fileHandle file, AnimationParameter parameter) {
   Array<AssetDescriptor> dependencies = new Array<AssetDescriptor>();
   dependencies.add(new AssetDescriptor<Texture>(stripExtension(filename) + ".png", Texture.class));

   return dependencies;
   ...
}

The first thing to pay attention to here is the dependency on the animation sheet image file. However, if you look beyond it, there is a seemingly new concept to describe, and this is AssetDescriptor. As its name suggests, it describes an asset with its filename, type, and parameters, which will be used in the asset's subsequent load. In fact, it is not new at all as it is used in the already mentioned AssetLoadingTask class. Moreover, this class contains two methods, handleSynchLoader and handleAsynchLoader, which are in charge of injecting the dependencies.