Image Loaded Event

This is the sub event that will be triggered by any resource call-backs received.

This event is triggered when you load an image into GameMaker: Studio, as long as you have used a valid URL or path with the applicable load file function. For example say you want to load a background image, and only change the current background to the new one when it has loaded. Well you would have something like this in a create event or an alarm event (for example):

back = background_add("", 0, 0);

This will now start to load the image into the device or the browser, but it will not block GameMaker: Studio while it waits for the file to be loaded. Instead GameMaker: Studio will keep running as normal until the image is loaded and the call back triggers the Image Loaded event, where a ds_map (more commonly known as a "dictionary") is created and stored in the special variable async_load. The map contains the following information:

  1. "filename": The complete path to the file you requested.

  2. "id": The ID of the resource that you have loaded. This will be the same as the variable that you have assigned the resource to.

  3. "status": Returns a value of less than 0 for an error.

You would then assign the newly loaded image to a background in this event. The above is also true for sprites and sounds, with a ds_map being generated for each of these resources as shown above, and the following code example demonstrates how the returned information would be used in this event:

if ds_map_find_value(async_load, "id") == back
   if ds_map_find_value(async_load, "status") >= 0
      background_index[0] = back

The above code will first check the id of the ds_map that has been created, then check the status of the callback. If the value is greater than or equal to 0 (signalling success) the result from the callback will then be used to set the background index to the newly loaded image.

NOTE: The variable async_load is only valid in these events, as the ds_map that is points to is created at the start of the event, then deleted again at the end, with this variable being reset to a value of -1.

Back: More About Async Events
Next: HTTP Event
© Copyright YoYo Games Ltd. 2015 All Rights Reserved