C++ loader



The C++ loader for scenes exported from R.U.B.E uses the 'b2dJson' tool available at www.iforce2d.net/b2djson (opens default browser). A full explanation of the usage of this tool is available online, and an example use case can be found in the sampleLoaders/box2d-testbed-(C++) 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. This is a total of 7 files, arranged as below. You can find these files under the sampleLoaders/box2d-testbed-(C++) folder, or (for jsoncpp) at http://jsoncpp.sourceforge.net/ (opens default browser).

To load your scene, include b2dJson.h... 
    #include "b2dJson.h"
... create a b2dJson 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. 
    b2dJson json;
    string errorMsg;
    b2World* world = json.readFromFile( "rubeRawInfoOutput.json", errorMsg );
    if ( ! world )
        printf("Could not load JSON file : %s\n", errorMsg.c_str());
Please see http://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 b2dJsonImage class, and you can get a list of these from the b2dJson instance after the file has been successfully loaded. The images will be in order of ascending 'renderOrder' property. 
    vector<b2dJsonImage*> images;
    json.getAllImages(images);
The method used to render the images will depend on your program. The b2dJsonImage 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. The example in the sampleLoaders/box2d-testbed-(C++) folder uses OpenGL to load and draw the images and may be useful as a reference.


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<b2Body*> enemies;
    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: 
    b2Fixture* 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 an optional 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: 
    bool hasCategory = json.hasCustomString(body, "category");
    
    //returns zero if the property does not exist
    int region = json.getCustomInt(body, "region");
    
    //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, b2Vec2(0,0), empty string, or false (whichever is applicable to the property type being requested).