The SpriteMap class

A SpriteMap is an object used as an information source for sprites and fonts. It provides a UV map for a texture letting the engine know where named regions are. As such you should be aware that you do not directly interact with loaded SpriteMap objects. Rather You load them through the asset manager (which gives you an integer based id), then you pass that id to a sprite or font.

Combining With Sprites

The Sprite struct can use a SpriteMap in combination to draw a quads using a rectangular regions of pixels from a texture. You can have multiple reigions, and each region is named, which is really useful if you wish to store multiple graphics in a single texture. This is also a great way to specify frames for one or more animations.

The default SpriteMap parser expects JSON code structured as a list of named regions. Here is an example:

{
    "region_name1": {
        "x": 0.7734375,
        "y": 0.3671875,
        "width": 0.01953125,
        "height": 0.0859375
    },
    "region_name2": {
        "x": 0.59375,
        "y": 0.47265625,
        "width": 0.02734375,
        "height": 0.0859375,
    }
}

Top level keys are the region names, and should always be distinct. You can add extra fields to each region, however x, y, width & height fields are manditory, and describe coordinates in UV space.

Consider the example above, if we wished to create a sprite that uses the region region_name2, we’d write some code like this:

sprite = Sprite(texture1, 100, 10, 150, 150)
sprite.spritemap = spritemap1
sprite.region = "region_name2"

Then when we draw the sprite, only the area of pixels we selected by the region will be de drawn where the sprite is placed.

Generating the JSON needed for a SpriteMap can be complicated, so a tool exists to help you generate them. To access the tool, visit this link.

Combining With Fonts

Lets imagine we have a task of drawing some text in a game. We need a texture with all the characters drawn on, and we need a way to tell the engine which parts of that texture to use for each character drawn. The SpriteMap actually provides all of this as seen in the example above. However we instead need to assign the SpriteMap to a Font struct instance. Here’s an example:

    texture = assets.load_texture("arial_20.png", TX_RGBA, TX_CLAMP_TO_BORDER)
    spritemap = assets.load_spritemap("arial_20.json")
font = Font(texture, spritemap)

The file arial_20.json looks something like this:

{
    "32": {
        "text": " ",
        "x": 0.7734375,
        "y": 0.3671875,
        "width": 0.01953125,
        "height": 0.0859375,
        "baseline": 0.609375
    },
    "34": {
        "text": "\"",
        "x": 0.59375,
        "y": 0.47265625,
        "width": 0.02734375,
        "height": 0.0859375,
        "baseline": 0.50390625
    }
}

Notice it’s the same format with a little more information. Each of the region keys are actually instead keycodes, the text and baseline fields are non-important, but are usually generated by the official generator tool to hint at how the texture was created.

Speaking of which, you can access the Sprite Font Generator by visiting this link.