Managing resources

Beginner Getting started

So far in this "getting started" tutorial series, we have been storing loaded resources into a global struct. This was just for simplicity and you can keep this approach if you like, but BBMOD comes with a resource manager, that keeps track of loaded resources, frees loaded resources and also supports asynchronnous loading (which is required on the HTML5 platform). In this tutorial, we are going to have a look at how to use the resource manager.

Adding a resource manager
Loading resources
Releasing resources
Freeing all resources
Persistent resources
Adding custom resources

Adding a resource manager

BBMOD comes with a pre-created resource manager and it can be accessed via the BBMOD_RESOURCE_MANAGER macro. If you would like to make your own one, you can do so by creating a new instance of BBMOD_ResourceManager (e.g. manager = new BBMOD_ResourceManager()). In this tutorial we are going to use the macro.

To make the resource manager work properly, we need to call its methods async_image_loaded_update and async_save_load_update in appropriate events:

/// @desc Async - Image Loaded event
BBMOD_RESOURCE_MANAGER.async_image_loaded_update(async_load);

/// @desc Async - Save/Load event
BBMOD_RESOURCE_MANAGER.async_save_load_update(async_load);

Simply add the code above into one of your objects that is present in all rooms that require resource loading.

Loading resource

With our resource manager ready, we can start loading resources. To do so, use the load method. This method takes the path to the resource to be loaded as the first argument and optionally its expected SHA1 (loading will fail if the actual SHA1 does not match) and a callback function that is executed only once when the resource is first loaded. If you do not wish to do a SHA1 check, you can either set the argument to undefined or simply ommit it and provide the callback function as the second argument.

/// @desc Create event
model = BBMOD_RESOURCE_MANAGER.load("Data/Rock.bbmod", function (_error, _model) {
    if (_error)
    {
        // TODO: Loading failed! Handle error...
    }
    else
    {
        // Here you can for example freeze the model after it's loaded
        _model.freeze();
    }
});

If given resource is already loaded, then the load method simply increases its reference counter and returns the resource. This means you can for example call the code above in the create event of all instances of a rock object and only the first one will actually load it and others will simply share the same resource.

Note: In the code above the model is not loaded until the callback function is called! You can check whether a resource is loaded using its IsLoaded property. It is possible to create an animation player for a model that is not loaded yet, or call its submit method; or play an animation that has not been loaded yet.

While there are any resources left to be loaded, the manager's Loading is set to true. This could be used for example to make a loading screen at the start of the room.

Releasing resources

When you are done using a resource, you can call its method free to release it. This decreses its reference counter and when it reaches 0, the resource is freed from memory.

/// @desc Clean Up event
model.free();
model = undefined;

Freeing all resources

Sometimes it can be useful to free all loaded resources, for example when going from one room to another. To do this, simply call the manager's method clear:

/// @desc Room End event
BBMOD_RESOURCE_MANAGER.clear();

Persistent resources

It is also possible to make a resource persistent, in which case free does not decrease its resource counter, and therefore it is not destroyed. To make a resource persistent, simply set its property Persistent to true:

model.Persistent = true;

Adding custom resources

The last thing worth mentioning about resource managers is that you can also add custom resources to them, without using the load method. To do so, you can use function add method, which takes a unique name of the resource and an instance of a BBMOD_Resource. To check if a resource manager has a resource with given name, use the method has. To get a resource with given name (and increase its reference counter), use the method get. There is also a combination of add and get operations available under the get_or_add method. This method takes a unique name and a callback function that creates and returns the resource if it is not present in the resource manager:

material = resourceManager.get_or_add("material", function () {
    var _mat = BBMOD_MATERIAL_DEFAULT.clone();
    _mat.BaseOpacity = sprite_get_texture(SprBaseOpacity, 0);
    return _mat;
});

Tutorials