Loading Resources with Bundles

Simplify the process of loading your program's resources using a resource bundle. This file lists the different resources you want loaded, which can then be loaded and freed as a group.
Written by: Various Authors
Last updated: November 2024

---

Games often require a large number of resources. With different levels, characters, animations, music, and sound effects, it can be cumbersome to have to load each of these individually in your code. To help overcome this, SplashKit provides bundles.

Preparing Resources

To use resources effectively in SplashKit, you need to organise your resource files in the correct structure. Follow these steps to create the necessary resources folder:

1. Open your terminal and navigate to your project directory.
2. Run the following command to generate the resources folder and its subfolders:

skm resources

This command creates the resources folder, which organises different types of assets needed for your project. This includes images, sounds, animations, fonts, and JSON files. For instance, the json subfolder is where you place any JSON files you intend to use.

---

Bundle Contents

The bundle scripts are located in the Resources/bundles folder. Each script is a text file that contains the details of the resources to load. Each line of the file describes a single resource, with comma separated fields. The first field contains the type of resource to load being one of the following:

• ANIM to load an animation
• BITMAP to load an image
• BUNDLE to load another bundle
• FONT to load a font
• MUSIC to load music
• SOUND to load a sound effect
• TIMER to create a timer.

Following the resource kind is the resources name and the associated filename for the resource. The name is used to access the resource once the bundle is loaded, while the filename indicates which resource to load. You need to ensure that the names are unique for each resource otherwise some of the resources will not be accessible.

---

Extra Details

Bitmap and font resources also require additional information.

BITMAP can optionally be followed by bitmap cell details useful for animations. This is in the format: BITMAP, name, filename, width, height, cellCols, cellRows, cellCount. Once the bitmap is loaded the bundle will set the cell details from the information given.

See Using Animations guide for more details, and example code and files to test.

FONT must be followed by the point size for the font.

---

Example

The following is an example of a bundle script file, it includes an example of each resource kinds you can load in SplashKit.

BITMAP,mySpriteSheet,image1_name.png, 500, 100, 10, 2, 19
BITMAP,myBitmap,image2_name.png
ANIM,myAnimation,anim_name.txt
SOUND,mySound,sound_name.wav
MUSIC,myMusic,music_name.ogg
FONT,myFont,font_name.ttf,14
BUNDLE,myBundle,bundle_name.txt

As you can see from the example, bundles can load a variety of resources including other bundles. Bitmaps can be loaded with cells and without cells.

---

Testing Resources

Once your resources are organised and your bundle script is created, you can load and use them in your code. Here’s how you can test loading resources:

Example Code

This is demonstrated in the following code example:

Note

These examples use functions such as Load Resources Bundle and Free Resource Bundle.

To test the code below you can download these Resources.

C++

#include "splashkit.h"

int main()
{
  open_window("Using Resource Bundles", 315, 330);

  // Load resources from a file
  load_resource_bundle("My Bundle", "myBundle.txt");

  bitmap myBitmap = bitmap_named("myBitmap");

  clear_screen(rgb_color(67, 80, 175));
  draw_bitmap(myBitmap, 50, 50);
  refresh_screen(60);
  delay(5000);

  // Free the resources loaded from the bundle
  free_resource_bundle("My Bundle");

  return 0;
}

C#

Top-level Statements

using static SplashKitSDK.SplashKit;
using SplashKitSDK;

OpenWindow("Using Resource Bundles", 315, 330);

// Load resources from a file
LoadResourceBundle("My Bundle", "myBundle.txt");

Bitmap myBitmap = BitmapNamed("myBitmap");

ClearScreen(RGBColor(67, 80, 175));
DrawBitmap(myBitmap, 50, 50);
RefreshScreen(60);
Delay(5000);

// Free the resources loaded from the bundle
FreeResourceBundle("My Bundle");

Object-Oriented

using SplashKitSDK;

namespace ResourceBundle
{
  public class Program
  {
    public static void Main()
    {
      SplashKit.OpenWindow("Using Resource Bundles", 315, 330);

      // Load resources from a file
      SplashKit.LoadResourceBundle("My Bundle", "myBundle.txt");

      Bitmap myBitmap = SplashKit.BitmapNamed("myBitmap");

      SplashKit.ClearScreen(SplashKit.RGBColor(67, 80, 175));
      SplashKit.DrawBitmap(myBitmap, 50, 50);
      SplashKit.RefreshScreen(60);
      SplashKit.Delay(5000);

      // Free the resources loaded from the bundle
      SplashKit.FreeResourceBundle("My Bundle");
    }
  }
}

Python

from splashkit import *

open_window("Using Resource Bundles", 315, 330)

# Load resources from a file
load_resource_bundle("My Bundle", "myBundle.txt")

my_bitmap = bitmap_named("myBitmap")

clear_screen(rgb_color(67, 80, 175))
draw_bitmap(my_bitmap, 50, 50)
refresh_screen()
delay(5000)

# Free the resources loaded from the bundle
free_resource_bundle("My Bundle")

Output

Follow these steps and examples to load and manage resources efficiently in your SplashKit project.