sprites — Using image assets

Sprite reference

class sprites.Sprite(image_filepath)

Sprite instance represents an image. The constructor accepts a path to a file. Supported formats are png and jpg.

Sprites instances are immutable.

If you want to load just a fragment of the image from a file, use the Sprite.crop() method.

If the file contains a spritesheet with multiple frames, use a helper function split_spritesheet() to automatically create a Sprite for each frame.

If the file includes multiple spritesheets, use the combination of Sprite.crop() and split_spritesheet() to ‘cut’ all frames from their respective areas.

For information how to draw a Sprite on the screen or how to create animations, see here.

A full example:

import os
from kaa.sprites import Sprite
from kaa.engine import Engine, Scene
from kaa.geometry import Vector
from kaa.nodes import Node

class MyScene(Scene):

    def __init__(self):
        self.root.add_child(Node(position=Vector(100,100),
                                 sprite=Sprite(os.path.join('demos', 'assets', 'python_small.png'))))

    def update(self, dt):

        for event in self.input.events():
            if event.system and event.system.quit:
                self.engine.quit()

with Engine(virtual_resolution=Vector(400, 200)) as engine:
    scene = MyScene()
    engine.window.size = Vector(400, 200)
    engine.window.center()

    engine.run(scene)

Instance Properties

Sprite.size

Returns Sprite size (width and height), as geometry.Vector

Sprite.origin

If the sprite was a result of a crop, it will return crop’s origin point. Otherwise it’ll return Vector(0,0)

Instance methods

Sprite.crop(origin, dimensions)

Returns a new Sprite, by cropping the original sprite.

The origin parameter is the start position of the crop - pass geometry.Vector indicating the (x,y) coordinates of the start position

The dimensions determines is the width and height of the crop - pass geometry.Vector where x and y are desired width and height respectively.

from kaa.sprites import Sprite
from kaa.geometry import Vector

# inside a Scene's __init__:
sprite = Sprite('path/to/sprite.png')  # sprite.png being a 1000x1000 px file.
print(sprite.size) # V[1000x1000]
new_sprite = sprite.crop(Vector(150,200), Vector(20,30))  # crop a new (20x30) sprite, starting at (150,200)
print(new_sprite.size) # V[20,30]

split_spritesheet() reference

sprites.split_spritesheet(spritesheet, frame_dimensions, frames_offset=0, frames_count=None, frame_padding=None)

When an image file is a spritesheet you need to ‘cut’ it into individual Sprites (individual frames), which you can then use for making an animation using transitions.NodeSpriteTransition. This utility function does the cutting for you. It takes the following params:

• spritesheet - a Sprite instance holding your spritesheet

• frame_dimensions - dimensions of a single frame, expects geometry.Vector where x is frame width and y is frame height

• frames_offset - if you’re interested in getting a subset of the frames, pass the start frame index. Default offset is zero (start from the first frame)

• frames_count - if you’re interested in getting just a subset of the frames, pass the number of frames. By default the function will ‘cut’ as many frames as geometrically possible.

• frame_padding - some spritesheet tools can add a padding to each frame, if your spritesheet is using that feature pass a geometry.Vector where x is left+right padding and y is top+bottom padding. Example: if using 1-pixel padding on all sides, pass Vector(2,2)

The function will process the spritesheet going from left to right and from top to bottom, cutting out the individual frames, returning a list of Sprites.

# suppose a spritesheet.png is a 1000x1000 file with a hundred frames of 100x100 size
spritesheet = Sprite('path/to/spritesheet.png')
# cut all frames:
all_frames = split_spritesheet(spritesheet, Vector(100, 100))
# cut 10 frames, from 20 to 29
subset_of_frames = split_spritesheet(spritesheet, Vector(100, 100), frames_offset=20, frames_count=10)
# crop a 40x40 area starting from (20,20), and cut five frames starting from frame 3
another_subset_of_frames = split_spritesheet(spritesheet.crop(Vector(20,20), Vector(40,40)),
    frame_offset=3, frames_count=5)