1.09.03 - Sprites

A sprite is an animated image. It is managed by an animation set. The animation set defines which animations are available and describes, for each animation, a sequence of images in each direction.

A sprite has the following properties:

The animation set of a sprite is composed of one or several PNG images that store all the frames, and a data file that describes how frames are organized in the PNG images. The data file also indicates the delay to make between frames when animating them and other properties like whether the animation should loop. See the sprites syntax for more information about the format of sprites.

We describe here the Lua API that you can use to show sprites during your game or your menus.

Functions of sol.sprite

sol.sprite.create(animation_set_id)

Creates a sprite.

Methods inherited from drawable

Sprites are particular drawable objects. Therefore, they inherit all methods from the type drawable.

See Methods of all drawable types to know these methods.

Methods of the type sprite

The following methods are specific to sprites.

sprite:get_animation_set()

Returns the name of the animation set used by this sprite.

sprite:get_animation()

Returns the name of the current animation of this sprite.

sprite:set_animation(animation_name, [next_action])

Sets the current animation of this sprite.

sprite:has_animation(animation_name)

Returns whether the specified animation exists on a sprite.

sprite:get_direction()

Returns the current direction of this sprite.

sprite:set_direction(direction)

Sets the current direction of this sprite.

sprite:get_num_directions([animation_name])

Returns the number of direction of an animation of this sprite.

sprite:get_frame()

Returns the index of the current frame of this sprite.

sprite:set_frame(frame)

Sets the current frame of this sprite.

sprite:get_num_frames([animation_name, direction])

Returns the number of frames of this sprites in an animation and direction.

sprite:get_frame_delay([animation_name])

Returns the delay between two frames of this sprite in an animation.

The delay of the current animation may be overriden by set_frame_delay().

sprite:set_frame_delay(delay)

Changes the delay between two frames of this sprite in the current animation.

Use this function if you want to override the normal delay (the one defined in the sprite data file).

sprite:get_size([animation_name, direction])

Returns the frame size of this sprite in an animation and direction.

sprite:get_origin([animation_name, direction])

Returns the coordinates of the origin point of this sprite in an animation and direction, relative to the upper left corner of a frame.

The origin is the point of synchronization for sprites that have several animations or directions of different sizes, and for entity sprites that are larger than the entity itself.

See entity:get_origin() for more details.

In a given animation and direction of a sprite, the origin point is the same for all frames.

sprite:get_frame_src_xy([animation_name, direction, frame])

Returns the coordinates of a frame in its source image.

sprite:is_paused()

Returns whether this sprite is paused.

sprite:set_paused([paused])

Pauses or resumes the animation of this sprite.

sprite:set_ignore_suspend([ignore])

During a game, sets whether the animation should continue even when the map is suspended.

sprite:synchronize([reference_sprite])

Synchronizes the frames of this sprite with the frames of a reference sprite. The synchronization will be performed whenever both animation names match. The current sprite will no longer apply its normal frame delay: instead, it will now always set its current frame to the current frame of its reference sprite.

Events of the type sprite

Events are callback methods automatically called by the engine if you define them.

The following events are specific to sprites.

sprite:on_animation_finished(animation)

Called when the current animation of this sprite is finished.

If the animation loops, this function is never called. Unless you start another animation, the sprite is no longer shown.

sprite:on_animation_changed(animation)

Called whenever the animation of this sprite has changed.

sprite:on_direction_changed(animation, direction)

Called whenever the direction of this sprite has changed.

sprite:on_frame_changed(animation, frame)

Called whenever the frame of this sprite has changed.