Java loader (JBox2D)



The Java loader for scenes exported from R.U.B.E uses the Java version of the 'b2dJson' tool available at www.iforce2d.net/b2djson (opens default browser). An example use case can be found in the sampleLoaders/jbox2d-testbed-(Java) folder accompanying the R.U.B.E download.

This topic looks at the basics of using this method.

Minimal use case
To load the Box2D world, you will need the support files for parsing JSON, and the b2dJson files. You can find these under the 'json' and 'b2dJson' folders in the sampleLoaders/jbox2d-testbed-(Java) folder. The org.json source code can also be found at www.json.org/java (opens default browser).

To load your scene, import Jb2dJson...
    import org.iforce2d.Jb2dJson;
... create a Jb2dJson instance and use the readFromFile function to create a Box2D world from the file you exported. This function will return null if the scene could not be loaded.
    Jb2dJson json = new Jb2dJson();
    StringBuilder errorMsg = new StringBuilder();
    World world = json.readFromFile("rubeRawInfoOutput.json", errorMsg);
    if ( null == world )
        System.out.println(errorMsg);
Please see www.iforce2d.net/b2djson for details on accessing named items in the scene.


Loading images
As well as information for the physics world, the exported data contains information about images. The information for each image is held in a Jb2dJsonImage class, and you can get a list of these from the Jb2dJson instance after the file has been successfully loaded.
    Jb2dJsonImage[] images = json.getAllImages();
The method used to render the images will depend on your program. The Jb2dJsonImage class contains the filename of the image to load, the body it is attached to (if any), its orientation, scale, angle, and so on which can be used to render the image.


Loading custom properties
After loading a scene into your program, you can access information about custom properties. The main functions are: finding items by their custom property value, and getting the value of a custom property from an item.

You can retrieve a list of all items matching a given value with the getXXXByCustomYYY() functions. The XXX part will be one of Bodies, Fixtures, Joints, or Images. The YYY part will be one of Int, Float, String, Vector or Bool. For example, to get a list of all bodies in the scene with custom string property "category" matching "enemy", you would do:
    Vector<Body> enemies = new Vector<Body>();
    json.getBodiesByCustomString("category", "enemy", enemies);
There are also single item versions of these functions, which return only the first item found which matches the condition. For these single item versions, the XXX part of the function is the singular form, eg. Body, Fixture, Joint, Image. For example, to find a fixture in the scene with custom int property "damage" matching 5 you would do:
    Fixture f = json.getFixtureByCustomInt("damage", 5);
Note that this function returns the first matching item found, so if there is more than one matching item in the scene there is no guarantee which one it will be. You would usually use this when you know there is only one matching item in the scene.

To investigate the custom properties of items, you can use the functions hasCustomYYY and getCustomYYY, where the YYY part will be one of Int, Float, String, Vector or Bool. The getCustomYYY function takes a parameter to return a default value if the property does not exist. For example, you could check the custom properties of a body using functions like this:
    boolean hasCategory = json.hasCustomString(body, "category");
    
    //returns 100 if the property does not exist
    float health = json.getCustomFloat(body, "health", 100);
If no default value is given and the property does not exist, the default value will be zero, Vec2(0,0), empty string, or false (whichever is applicable to the property type being requested).