Javascript loader (box2dweb)

Javascript source code is available to create a box2dweb world from scenes exported by R.U.B.E. An example using an HTML5 canvas can be found in the sampleLoaders/box2dweb-testbed-(Javascript) 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 to include box2dweb and the 'loadrube.js' files in your page. You can find these under the sampleLoaders/box2dweb-testbed-(Javascript) folder. The Box2Dweb homepage is here: http://code.google.com/p/box2dweb/ (opens default browser).

The simplest way to load a scene is to export it to a .json file, and add a global variable declaration to the beginning of the file. The variable declaration is necessary to give you some way to reference the object.

For example, suppose you export a scene that you want to refer to as 'myRubeScene'. You would add one line to the beginning of the .json file like:

   var myRubeScene = // Add this line

    // The rest of the file remains as exported by R.U.B.E
    {
       "allowSleep" : true,
       "autoClearForces" : true,
        ... etc

After then including the file (with <script> tag) in your main page, you can load the contents of it like this:

    var world = loadWorldFromRUBE( myRubeScene );
    if ( ! world )
        console.log("Failed to load RUBE scene");

Loading scenes via ajax
You can also load scenes via ajax as they are required rather than loading them up-front when the page loads. This can make the initial page load quicker, and allows interesting possibilities such as serving dynamic worlds.

The simplest way to achieve this is with jQuery:

   jQuery.get("myRubeScene.json", function(data) {
        var world = loadWorldFromRUBE( data );
        if ( ! world ) {
            //load images etc
        }
        else
            console.log("Failed to load RUBE scene");
    });

The above example assumes that the webserver is serving .json files as the application/json mime type. If it's not, you may have to parse the returned data to JSON first:

   var world = loadWorldFromRUBE( jQuery.parseJSON(data) );

Loading images
As well as information for the physics world, the exported data contains information about images. After loading the scene, you can access the image information in the 'images' member of the loaded Box2D world. For example, to load the images into Javascript image object, you could do this:

    if ( world.images ) {
        for (var i = 0; i < world.images.length; i++) {
            var imageObj = new Image();
            imageObj.src = world.images[i].file;
            world.images[i].imageObj = imageObj;
        }
    }

A full listing of the properties in the image objects is available at www.iforce2d.net/rube/json-structure (opens default browser).

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 getXXXByCustomProperty() functions. The XXX part will be one of Bodies, Fixtures, Joints, or Images. For example, to get a list of all bodies in the scene with custom string property "category" matching "enemy", you would do:

   var enemies = getBodiesByCustomProperty(world, "string", "category", "enemy");

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:

    var fixture = getFixtureByCustomProperty(world, "int", "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:

    var hasCategory = hasCustomProperty(body, "string", "category");
    
    //returns 100 if the property does not exist
    var health = getCustomProperty(body, "float", "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).