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.

dst_surface (surface): The destination surface.
x (number, optional): X coordinate of where to draw this object (default 0).
y (number, optional): Y coordinate of where to draw this object. (default 0).

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.

region_x (number): X coordinate of the subrectangle to draw.
region_y (number): Y coordinate of the subrectangle to draw.
region_width (number): Width of the subrectangle to draw.
region_height (number): Height of the subrectangle to draw.
dst_surface (surface): The destination surface.
x (number, optional): X coordinate of where to draw this rectangle on the destination surface (default 0).
y (number, optional): Y coordinate of where to draw this rectangle. on the destination surface (default 0).

drawable:get_rotation()

Returns the rotation angle of this object around its transformation origin. The rotation angle is in radians and goes in trigonometric direction.

Return value (number): The rotation angle in radians around the transformation origin. 0 means no rotation.

drawable:set_rotation(rotation)

Sets the rotation angle of this object around its transformation origin. The rotation angle is in radians and goes in trigonometric direction.

rotation (number): The rotation angle in radians around the transformation origin. 0 means no rotation.

drawable:get_scale()

Returns the scaling factors of this drawable object.

Return value 1 (number): Scale factor in the X dimension.
Return value 2 (number): Scale factor in the Y dimension.

drawable:set_scale(x, y)

Set the scale factors for this drawable object. A scale of 1 corresponds to a normal size. A negative scale will flip the drawable in the corresponding axis. Scaling is performed around the transformation origin.

x (number) : Scale factor in the X dimension.
y (number) : Scale factor in the Y dimension.

drawable:get_transformation_origin()

Returns the transformation origin of this drawable object. The tranformation origin point is the pivot point used for rotation and scaling.

The transformation point is relative to the origin point of the drawable object, which is always the upper-left corner for surfaces and text surfaces, and the sprite origin point for sprites.

Return value 1 (number): X coordinate of the transform point.
Return value 2 (number): Y coordinate of the transform point.

drawable:set_transformation_origin(x, y)

Set the transformation origin point of this drawable object. The tranformation origin point is the pivot point used for rotation and scaling.

The transformation point is relative to the origin point of the drawable object, which is always the upper-left corner for surfaces and text surfaces, and the sprite origin point for sprites.

x (number): X coordinate of the transformation origin.
y (number): Y coordinate of the transformation origin.

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().

Return value (string): The blend mode. See drawable:set_blend_mode() for the possible values.

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().

blend_mode (string): The blend mode. Can be one of:
- "none": No blending. The destination surface is replaced by the pixels of this drawable object.
  dstRGBA = srcRGBA
- "blend" (default): This drawable object is alpha-blended onto the destination surface.
  dstRGB = (srcRGB * srcA) + (dstRGB * (1 - srcA))
  dstA = srcA + (dstA * (1 - srcA))
- "add": This drawable object is drawn onto the destination surface with additive blending. The clarity of the destination surface is kept. Useful to color and lighten the destination surface.
  dstRGB = (srcRGB * srcA) + dstRGB
- "multiply": Color modulation. Can be used to darken the destination surface without degrading its content.
  dstRGB = srcRGB * dstRGB

drawable:get_shader()

Returns the shader applied to this object.

Return value (shader): The shader, or nil if no shader is set.

drawable:set_shader(shader)

Sets the shader used to draw this object.

Default drawing is done with no shader.

shader (shader): The shader to set, or nil to reset drawing to normal.

drawable:get_opacity()

Returns the opacity of this drawable.

Return value (integer): The opacity: 0 (transparent) to 255 (opaque).

drawable:set_opacity(opacity)

Sets the opacity of this drawable.

All drawables are initially opaque.

opacity (integer): The opacity: 0 (transparent) to 255 (opaque).

drawable:get_color_modulation()

Returns the color multiplier of this drawable.

Return value (table): The color as an array of RGBA values

drawable:set_color_modulation(color)

Sets the color modulator of this drawable, default is plain white {255,255,255,255}. When the drawable is draw, all the pixels are multiplied by this color (white as no effect). Alpha channel and drawable opacity are multiplied together.

color (table): The color multiplier, as an array of RGBA values.

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.

delay (number, optional): Delay in milliseconds between two frames of the fade-in animation (default 20).
callback (function, optional): A function to call when the fade-in effect finishes.

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.

delay (number, optional): Delay in milliseconds between two frames of the fade-out animation (default 20).
callback (function, optional): A function to call when the fade-out effect finishes.

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().

Return value 1 (number): X offset of the drawable object.
Return value 2 (number): Y offset of the drawable object.

drawable:set_xy(x, y)

Sets the offset added where this drawable object is drawn.