1.09 - Drawable objects

Drawable objects are things that can be drawn on a destination surface. They include the following types: surface, text surface and sprite. This page describes the methods common to those types.

Methods of all drawable types

These methods exist in all drawable types.

drawable:draw(dst_surface, [x, y])

Draws this object on a destination surface.

drawable:draw_region(region_x, region_y, region_width, region_height, dst_surface, [x, y])

Draws a subrectangle of this object on a destination surface.

drawable:get_blend_mode()

Returns the blend mode of this drawable object.

The blend mode defines how this drawable object will be drawn on other surfaces when you call drawable:draw() or drawable:draw_region().

drawable:set_blend_mode(blend_mode)

Sets the blend mode of this drawable object.

The blend mode defines how this drawable object will be drawn on other surfaces when you call drawable:draw() or drawable:draw_region().

drawable:fade_in([delay], [callback])

Starts a fade-in effect on this object.

You can specify a callback function to be executed when the fade-in effect finishes.

If the drawable object is a sprite attached to a map entity during a game, the fade-in effect gets the lifetime of that entity. The behavior is probably what you expect: the fade-in effect gets suspended when the entity gets suspended, and it gets canceled (that is, the callback is never executed) when the map entity is destroyed.

Note
When your drawable object does not belong to a map entity (typically in a title screen before a game is started, or in your pause menu), the fade-in effect continues until the drawable object is garbage-collected. In other words, the callback can be executed even if you have stopped using the drawable object in the meantime. Therefore, you should use the callback parameter with care. In these situations, using a timer for your callback is easier because timers have an explicit lifetime.

drawable:fade_out([delay], [callback])

Starts a fade-out effect on this object.

You can specify a callback function to be executed when the fade-out effect finishes.

If the drawable object is a sprite attached to a map entity during a game, the fade-out effect gets the lifetime of that entity. The behavior is probably what you expect: the fade-out effect gets suspended when the entity gets suspended, and it gets canceled (that is, the callback is never executed) when the map entity is destroyed.

Note
When your drawable object does not belong to a map entity (typically in a title screen before a game is started, or in your pause menu), the fade-out effect continues until the drawable object is garbage-collected. In other words, the callback can be executed even if you have stopped using the drawable object in the meantime. Therefore, you should use the callback parameter with care. In these situations, using a timer for your callback is easier because timers have an explicit lifetime.

drawable:get_xy()

Returns the offset added where this drawable object is drawn.

This value is initially 0,0. It is added to whatever coordinates the object is drawn at.

They can be modified by a movement or by drawable:set_xy().

drawable:set_xy(x, y)

Sets the offset added where this drawable object is drawn.

This value is initially 0,0. It is added to whatever coordinates the object is drawn at.

drawable:get_movement()

Returns the current movement of this drawable object.

drawable:stop_movement()

Stops the current movement of this drawable object if any.