luma.core.sprite_system

Simplified sprite animation framework.

Note

This module is an evolving “work-in-progress” and should be treated as such until such time as this notice disappears.

class luma.core.sprite_system.dict_wrapper(d)

Bases: object

Helper class to turn dictionaries into objects.

class luma.core.sprite_system.framerate_regulator(fps=16.67)

Bases: object

Implements a variable sleep mechanism to give the appearance of a consistent frame rate. Using a fixed-time sleep will cause animations to be jittery (looking like they are speeding up or slowing down, depending on what other work is occurring), whereas this class keeps track of when the last time the sleep() method was called, and calculates a sleep period to smooth out the jitter.

Parameters:

fps (float) – The desired frame rate, expressed numerically in frames-per-second. By default, this is set at 16.67, to give a frame render time of approximately 60ms. This can be overridden as necessary, and if no FPS limiting is required, the fps can be set to zero.

average_transit_time()

Calculates the average transit time between the enter and exit methods, and return the time in milliseconds.

Returns:

The average transit in milliseconds.

Return type:

float

effective_FPS()

Calculates the effective frames-per-second - this should largely correlate to the desired FPS supplied in the constructor, but no guarantees are given.

Returns:

The effective frame rate.

Return type:

float

class luma.core.sprite_system.spritesheet(image, frames, animations)

Bases: object

A sprite sheet is a series of images (usually animation frames) combined into a larger image. A dictionary is usually spread into the object constructor parameters with the following top-level attributes:

Parameters:

• image (str) – A path to a sprite map image.

• frames (dict) –

  A dictionary of settings that defines how to extract individual frames from the supplied image, as follows

  • width & height are required and specify the dimensions of the frames

  • regX & regY indicate the registration point or “origin” of the frames

  • count allows you to specify the total number of frames in the spritesheet; if omitted, this will be calculated based on the dimensions of the source images and the frames. Frames will be assigned indexes based on their position in the source images (left to right, top to bottom).

• animations (dict) –

  A dictionary of key/value pairs where the key is the name of of the animation sequence, and the value are settings that defines an animation sequence as follows:

  • frames is a list of frame to show in sequence. Usually this comprises of frame numbers, but can refer to other animation sequences (which are handled much like a subroutine call).

  • speed determines how quickly the animation frames are cycled through compared to the how often the animation sequence yields.

  • next is optional, but if supplied, determines what happens when the animation sequence is exhausted. Typically this can be used to self-reference, so that it forms an infinite loop, but can hand off to any other animation sequence.

Loosely based on https://www.createjs.com/docs/easeljs/classes/SpriteSheet.html

animate(seq_name)

Returns a generator which “executes” an animation sequence for the given seq_name, inasmuch as the next frame for the given animation is yielded when requested.

Parameters:

seq_name (str) – The name of a previously defined animation sequence.

Returns:

A generator that yields all frames from the animation sequence.

Raises:

AttributeError – If the seq_name is unknown.