Filtering exported items and properties

In the Scene settings dialog, the 'Properties to include in exported JSON files' setting lets you exclude some properties from the exported file completely.

However, what if you want to exclude properties for some items in the scene, but keep them for other items? And what if you want to exclude some items but not others? You can do this by using a script to determine which items and properties to export.

This 'property export filter' script is set in the Scene settings dialog under the Export options tab:

The contents of the file must follow a special format, so to create a new script with the format already prepared, you can click the second button to the right of the text input.

For convenience, there is also a third button button which will open the given file in the script panel for editing (this button will only be enabled if the script file actually exists):

After initializing a new script, you will see that it contains a bunch of commented out functions. You can uncomment these functions to customize the export behavior as necessary:

To apply the changes after editing the script file, click the save button in the script panel:

Customization examples
During the export process, the application will call the shouldExportItem function in the script for every item, to let the script decide if it should be exported. The item in question is passed as a function parameter.

As an example, we could say that only bodies with a mass greater than 5 should be exported:

bool shouldExportItem( body b ) {
    return b.getMass() > 5;
}

If an item successfully passes the shouldExportItem check, then the shouldExportProperty function will be called for each of its properties, to let the script decide if the property should be exported for that item. The item and the property name are passed as function parameters.

As an example, we could say that the name property of a body should only be exported if it does not start with 'body', to avoid exporting names for bodies that we did not name explicitly (the default names given to bodies by RUBE are body0, body1, body2, etc) and will most likely not be necessary when loading the scene:

bool shouldExportProperty( body b, const string& in propertyName ) {
    if ( propertyName == "name" )
        return b.getName().findFirst("body") != 0;
    return true;
}

Note that we have to check the propertyName parameter to know which property the application is asking about.

Tip
Using a custom property is a convenient way to toggle exporting on and off for items, without editing the script file any further. First, set up a boolean custom property to act as a switch - let's try this for fixtures as an example:

Then you can use the value of that property in the export filter:

bool shouldExportItem( fixture f ) {
    return ! f.getCustomBool("excludeFromExport");
}