Solarus quests  1.5
Quest maker's reference
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.

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

  • 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: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.

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

  • x (number): X offset to set.
  • y (number): Y offset to set.

drawable:get_movement()

Returns the current movement of this drawable object.

  • Return value (movement): The current movement, or nil if the drawable object is not moving.

drawable:stop_movement()

Stops the current movement of this drawable object if any.