Quick Start: Part 1

Before we start you’ll want to download the latest version and probably the generated javadoc as well. It’s assumed you’ve already got a basic game working that you want to add the resource system to and you’ve added the Rebirth.jar library to your project’s classpath.

It’s assumed that your game is laid out something like this:

  /ProjectName
    /Data
      ...game data files...
    /Libs
      ...library jars...
    /Source
      ...java source...

where all your data files (images, sounds, etc.) are within the ‘Data’ directory.

Initialisation, Update and Shutdown

First we’ll need to create a resource pool to work with. The easiest is to use Resources.createPool() somewhere in your game’s initialisation:

 
import com.triangularpixels.rebirth.resources.*;
 
ResourcePool resources = Resources.createPool("Data", Resources.DecoderGroup.CORE, true);
resources.parse("resources.xml");

“Data” is the base directory for all resource operations, relative to the current working directory, change this if your project is set up differently. The other two arguments specify that you want the core decoders and that files should be watched for modifications.

The second line loads the resources from “resources.xml” straight away. For now, we’ll just create an empty resources.xml in your ‘Data’ directory:

 
  <resources>
  </resources>

Somewhere in your game loop, you’ll want to call ResourcePool.update() at least once:

 
resources.update();

And when you eventually shut down your game, make sure to call destroy():

 
resources.destroy();

If you’ve got everything set up right you can now start your game. A resource pool will be created, parse the empty file and be shutdown when your game exits.

Your First Resource

Say your game has a Tank the player can drive around – you’ll probably have a bunch of constants like speed and turn radius embedded in your code to control how it moves. That’s awkward to change and tweek so we’ll pull it out into a new resource type.

First, define the class to hold the new data:

 
package yourgame;
 
import org.w3c.dom.Element;
 
import com.triangularpixels.rebirth.resources.AutoResource;
 
public class TankTemplate extends AutoResource
{
  public float moveSpeed;
  public float rotateSpeed;
}

Here we inherit from AutoResource to do all the heavy lifting for us. Next we need to edit our resources.xml:

 
<resources>
  <!-- Maps the class we just created onto the tag name 'TankTemplate' -->
<map name="TankTemplate" class="yourgame.TankTemplate" />
 
  <!-- Create a new TankTemplate resource -->
  <TankTemplate name="player.tank"
                moveSpeed="1.5"
                rotateSpeed="4.0"
  />
</resources>

Important points:

• The ‘map’ tag needs a fully qualified path to your new resource class (in this case, “yourgame.TankTemplate”).
• Every resource needs a unique ‘name’ attribute. The ‘.tank’ extension isn’t required but makes things easier to manage.
• The resource attributes map directly onto the names of the variables in our TankTemplate class.

Once we’ve done this we need to retrieve our newly created resource in-game and use it:

 
  ResourceHandle<TankTemplate> tankHandle;
 
  // Fetch the handle to our resource
  tankHandle = resources.forceCreate(TankTemplate.class, "player.tank");
 
  // Actually get the TankTemplate object out of the handle
  TankTemplate tankTemplate = tankHandle.get();
 
  // Print our our tank values
  System.out.println("move speed: " + tankTemplate.moveSpeed);
  System.out.println("rotate speed: " + tankTemplate.rotateSpeed);

Important: you should refetch the TankTemplate object every frame with the get() method. The usual way to do this is to retrieve the resource handle in your Tank constructor and then call get() within whatever method you need it in (like your tank movement code).

Now you should be able to run your game and have the tank xml automatically parsed into your TankTemplate object. Because you refetch the actual object every frame with get() you should be able to change your resource.xml and see the changes instantly and automatically reflected in your game.

Want more? Read part two.