Module Drawing
Functions for drawing images and text.
See here for more information: link
Functions
| addColor (r[, g=r[, b=g]]) | Changes the currently set color in an additive way. |
| adjustColor (r[, g=r[, b=g]]) | Assumes the input color is a color as intended to be displayed in light mode. |
| allocateFrameType () | Allocates a free frame type integer for use with Drawing.setFrameType. |
| drawCircle (x, y, w, h[, fillRatio=1[, startAngle=0[, endAngle=2*math.pi]]]) | Draws a circle in the specified rectangle. |
| drawImage (frame, x, y) | Draws a frame. |
| drawImageRect (frame, x, y, w, h) | Draws a frame into a specified rectangle. |
| drawImageRotated (frame, x, y, angle) | Draws a frame rotated around its image handle. |
| drawLine (x0, y0, x1, y1[, width=1]) | Draws a line. |
| drawNinePatch (frame, x, y, w, h[, sparse=false]) | Draws a nine patch into a specified rectangle. |
| drawQuad (x0, y0, x1, y1, x2, y2, x3, y3[, frame=nil]) | Draws a quad using four corner points. |
| drawRect (x, y, w, h) | Draws a filled rectangle. |
| drawText (text, x, y[, font=nil[, centerX=0[, centerY=0]]]) | Draws a text. |
| drawTileFrame (frame) | Draws a tile frame on the currently set tile. |
| drawTriangle (x0, y0, x1, y1, x2, y2[, frame=nil]) | Draws a triangle. |
| flowImage (frame) | Draws an image. |
| flowText (text) | Draws a text. |
| flush () | Flushes the drawing pipeline. |
| getAdditive () | Returns the current additive factor for drawing. |
| getAlpha () | Returns the current transparency for drawing. |
| getColor () | Returns the current drawing color. |
| getDaytime () | Returns the current part of the "visual day" with 0.5 being noon. |
| getDaytimeColor () | Returns the shading color that is used for the current day time. |
| getFlowHeight () | Returns the total height used by flow functions within the current text frame. |
| getFrameType () | Gets the currently set frame type. |
| getImageHandle (frame) | Returns the handle of an image/frame. |
| getImageSize (frame) | Returns the size of an image/frame. |
| getScale () | Returns the current scale factors set by setScale. |
| getSize () | Returns the current screen size width, height in pixels. |
| getTextSize (text[, font=nil]) | Queries the drawing size for a given text. |
| nl ([spacing=0.0]) | For flow text: starts a new line. |
| reset () | Resets all drawing properties. |
| resetClipping () | Resets clipping so that draw functions affect all pixels again. |
| setAdditive (additive) | Sets the additive factor used for additive drawing. |
| setAlpha (alpha) | Sets the transparency for drawing. |
| setClipping (x, y, w, h) | Sets the clipping rect to a specified rectangle. |
| setColor (r, g, b) | Sets the drawing color. |
| setDynamic (x, y, z[, offsetX=0[, offsetY=0[, localScaleX=1[, localScaleY=1]]]]) | Sets the drawing origin and scale to a position on the map. |
| setFont ([font=Font.DEFAULT]) | Sets the default font for drawText, getTextSize and text frame related functions. |
| setFrameType (frameType) | Sets a frame type that will be applied to the next drawn frames. |
| setScale (scaleX, scaleY) | Sets the scale for drawing (absolute). |
| setTextFrame (x, y, w, h) | Sets a text frame rectangle for flow text functions and resets the flow cursor. |
| setTile (tileX, tileY[, offsetX=0[, offsetY=0[, localScaleX=1[, localScaleY=1]]]]) | Sets the current drawing offset and scale to a certain tile on the map. |
| setUniform (name, v0[, v1[, v2[, v3]]]) | Sets a uniform float vector that can be used in shaders. |
Functions
- addColor (r[, g=r[, b=g]])
-
Changes the currently set color in an additive way.
This is useful to darken or lighten the current color in an easy way.
Parameters:
- r integer Red component of the color.
- g integer Green component of the color. (default r)
- b integer Blue component of the color. (default g)
- adjustColor (r[, g=r[, b=g]])
-
Assumes the input color is a color as intended to be displayed in light mode.
In case of light mode the input color gets returned.
In case of dark mode the color gets transformed for better visibility.
Returns the new color as a hex string.
New feature:
-
This is a new feature that was added in version 1.12.85
Parameters:
- r integer or string Red component of the color or a hex color string.
- g integer Green component of the color. (default r)
- b integer Blue component of the color. (default g)
Returns:
-
string
The resulting hex color.
- allocateFrameType ()
-
Allocates a free frame type integer for use with Drawing.setFrameType.
You should only call this function once during the lifecycle of the game to
prevent clutter.
Returns:
-
int
A fresh frame type identifier.
- drawCircle (x, y, w, h[, fillRatio=1[, startAngle=0[, endAngle=2*math.pi]]])
-
Draws a circle in the specified rectangle.
Parameters:
- x number
- y number
- w number
- h number
- fillRatio number (default 1)
- startAngle number (default 0)
- endAngle number (default 2*math.pi)
- drawImage (frame, x, y)
-
Draws a frame.
Parameters:
- frame integer or draft A frame or draft (that contains at least one frame).
- x number The x coordinate for drawing.
- y number The y coordinate for drawing.
- drawImageRect (frame, x, y, w, h)
-
Draws a frame into a specified rectangle.
Parameters:
- frame integer or draft A frame or draft (that contains at least one frame).
- x number The x coordinate for drawing.
- y number The y coordinate for drawing.
- w number The width for drawing.
- h number The height for drawing.
- drawImageRotated (frame, x, y, angle)
-
Draws a frame rotated around its image handle.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- frame integer or draft The frame or draft to draw.
- x number The x coordinate of the handle.
- y number The y coordinate of the handle.
- angle number Rotation in radians.
- drawLine (x0, y0, x1, y1[, width=1])
-
Draws a line.
Parameters:
- x0 number X component of the start point.
- y0 number Y component of the start point.
- x1 number X component of the end point.
- y1 number Y component of the end point.
- width number The width of the line. (default 1)
- drawNinePatch (frame, x, y, w, h[, sparse=false])
-
Draws a nine patch into a specified rectangle. A nine patch is a set of
9 frames that are used to draw a rectangle with borders. All parts except
the corners are stretched to match accordingly.
Parameters:
- frame integer or draft The base frame of the nine patch.
- x number The x coordinate for drawing.
- y number The y coordinate for drawing.
- w number The width for drawing.
- h number The height for drawing.
- sparse boolean If true the center frame will not be drawn. (default false)
- drawQuad (x0, y0, x1, y1, x2, y2, x3, y3[, frame=nil])
-
Draws a quad using four corner points.
If no frame is provided a white quad will be drawn.
Parameters:
- x0 number X component of the first point.
- y0 number Y component of the first point.
- x1 number X component of the second point.
- y1 number Y component of the second point.
- x2 number X component of the third point.
- y2 number Y component of the third point.
- x3 number X component of the fourth point.
- y3 number Y component of the fourth point.
- frame integer or draft A frame or draft (that contains at least one frame). (default nil)
- drawRect (x, y, w, h)
-
Draws a filled rectangle.
Parameters:
- x number The x coordinate for drawing.
- y number The y coordinate for drawing.
- w number The width for drawing.
- h number The height for drawing.
- drawText (text, x, y[, font=nil[, centerX=0[, centerY=0]]])
-
Draws a text.
Parameters:
- text string The text to draw.
- x number The x coordinate for drawing.
- y number The y coordinate for drawing.
- font font The font to use. (default nil)
- centerX number The relative x center for the pivot point (usually ranges from 0 to 1; 0.5 would be the center of the text). (default 0)
- centerY number The relative y center for the pivot point (usually ranges from 0 to 1; 0.5 would be the center of the text). (default 0)
- drawTileFrame (frame)
-
Draws a tile frame on the currently set tile. A tile frame is supposed
to lay flat on the ground. The magic of this function is to draw the frame
correctly on slopes. Use this function e.g. for drawing tool markers
on the ground.
Parameters:
- frame integer or draft A frame or draft (that contains at least one frame).
- drawTriangle (x0, y0, x1, y1, x2, y2[, frame=nil])
-
Draws a triangle. If no frame is provided a white triangle will be drawn.
As the game is optimized to draw quads it is more efficient to draw a quad
using Drawing.drawQuad rather than drawing two triangles.
Parameters:
- x0 number X component of the first point.
- y0 number Y component of the first point.
- x1 number X component of the second point.
- y1 number Y component of the second point.
- x2 number X component of the third point.
- y2 number Y component of the third point.
- frame integer or draft A frame or draft (that contains at least one frame). (default nil)
- flowImage (frame)
-
Draws an image. Uses the current set text frame properties to auto layout it.
This layout includes scaling the image to match the current font's height.
Parameters:
- frame
- flowText (text)
-
Draws a text. Uses the current set text frame properties to auto layout it.
Parameters:
- text
- flush ()
- Flushes the drawing pipeline. Can be used to synchronize when things are drawn. Normally frames are drawn in large batches for better performance.
- getAdditive ()
-
Returns the current additive factor for drawing.
Returns:
-
number
Additive factor ranging from 0 (not additive) to 1 (fully additive).
- getAlpha ()
-
Returns the current transparency for drawing.
Returns:
-
number
Transparency value ranging from 0 (transparent) to 1 (opaque).
- getColor ()
-
Returns the current drawing color.
Returns:
- integer Red component of the drawing color.
- integer Green component of the drawing color.
- integer Blue component of the drawing color.
- getDaytime ()
-
Returns the current part of the "visual day" with 0.5 being noon.
Returns:
-
number
A number 0..1 representing the visual day.
- getDaytimeColor ()
-
Returns the shading color that is used for the current day time.
Returns:
-
int,int,int
Three integers that represent the shading color.
- getFlowHeight ()
- Returns the total height used by flow functions within the current text frame.
- getFrameType ()
-
Gets the currently set frame type.
The frame type is a 0-255 integer number that can be accessed from within
the shader. The values 0-64 can be considered as reserved by the game.
Returns:
-
int
The currently set frame type.
- getImageHandle (frame)
-
Returns the handle of an image/frame.
Parameters:
- frame integer or draft A frame or draft (that contains at least one frame) for which the handle location will be queried.
Returns:
- number X handle of the frame (in pixels).
- number Y handle of the frame (in pixels).
- getImageSize (frame)
-
Returns the size of an image/frame.
Parameters:
- frame integer or draft A frame or draft (that contains at least one frame) for which the size will be queried.
Returns:
- number Width of the frame (in pixels).
- number Height of the frame (in pixels).
- getScale ()
-
Returns the current scale factors set by setScale.
Returns:
- number Scaling factor for x axis.
- number Scaling factor for y axis.
- getSize ()
-
Returns the current screen size width, height in pixels.
Note that the result may change over time due to resolution changes.
Returns:
- number Screen width.
- number Screen height.
- getTextSize (text[, font=nil])
-
Queries the drawing size for a given text.
Parameters:
- text string The text to calculate the size of (in pixels).
- font font The font to calculate the size for. (default nil)
Returns:
- number Width required to draw the text.
- number Height required to draw the text.
- nl ([spacing=0.0])
-
For flow text: starts a new line.
Parameters:
- spacing number Vertical spacing for the new line (default 0.0)
- reset ()
- Resets all drawing properties. It's good practice to call this function before using other Drawing functions.
- resetClipping ()
- Resets clipping so that draw functions affect all pixels again.
- setAdditive (additive)
-
Sets the additive factor used for additive drawing. Additive drawing
simply adds the colors to the background instead of mixing them.
Parameters:
- additive number The additivity factor to use. 0 being non additive, 1 being fully additive.
- setAlpha (alpha)
-
Sets the transparency for drawing.
Parameters:
- alpha number The transparency to use. 0 being fully transparent, 1 being fully opaque.
- setClipping (x, y, w, h)
-
Sets the clipping rect to a specified rectangle.
Consecutive calls to drawing functions will only affect pixels
within that rectangle.
Parameters:
- x number The x coordinate for clipping.
- y number The y coordinate for clipping.
- w number The width for clipping.
- h number The height for clipping.
- setColor (r, g, b)
-
Sets the drawing color. Component values range from 0 to 255 with 0,0,0
being black and 255,255,255 being white.
When drawing things the drawing color is applied in a multiplicative way.
So using white as drawing color won't alter the color of images when drawing.
Since version 1.12.17 you can provide a hex string as parameter r;
g and b must not be provided then.
Parameters:
- r integer or string Red component of the color.
- g integer Green component of the color.
- b integer Blue component of the color.
- setDynamic (x, y, z[, offsetX=0[, offsetY=0[, localScaleX=1[, localScaleY=1]]]])
-
Sets the drawing origin and scale to a position on the map. Unlike setTile,
fractional tile coordinates can be used to position drawings between tiles.
The z coordinate raises the drawing origin by 12 pixels per unit (before
the map's vertical scale is applied) which matches a usual terrain / road height step.
Terrain height is not applied.
Coordinates outside the map are allowed.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- x number X coordinate in tile units.
- y number Y coordinate in tile units.
- z number Height above the map; each unit raises the origin by 12 pixels.
- offsetX number Additional horizontal offset in pixels. (default 0)
- offsetY number Additional vertical offset in pixels. (default 0)
- localScaleX number Additional scaling factor for the x axis. (default 1)
- localScaleY number Additional scaling factor for the y axis. (default 1)
- setFont ([font=Font.DEFAULT])
-
Sets the default font for drawText, getTextSize and text frame related functions.
Parameters:
- font font The font to set. (default Font.DEFAULT)
- setFrameType (frameType)
-
Sets a frame type that will be applied to the next drawn frames.
The frame type is a 0-255 integer number that can be accessed from within
the shader. The values 0-64 can be considered as reserved by the game.
It is good practice to set the frame type to the previous value after you
are done with it.
You should only use frame types that are either defined by the game or
were previously allocated using Drawing.allocateFrameType().
If you try to draw frames whose Draft:getFrameType is non zero that frame
type will be used instead.
Parameters:
- frameType int The frame type to set.
Returns:
-
int
The previously set frame type.
- setScale (scaleX, scaleY)
-
Sets the scale for drawing (absolute). 1 for both of them would mean no
scaling at all while values greater than 1 will scale things up. Values
smaller than 1 will draw things smaller.
Parameters:
- scaleX number Scaling factor for x axis.
- scaleY number Scaling factor for y axis.
- setTextFrame (x, y, w, h)
-
Sets a text frame rectangle for flow text functions and resets the flow cursor.
Parameters:
- x number The x coordinate of the text frame.
- y number The y coordinate of the text frame.
- w number The width of the text frame.
- h number The height of the text frame.
- setTile (tileX, tileY[, offsetX=0[, offsetY=0[, localScaleX=1[, localScaleY=1]]]])
-
Sets the current drawing offset and scale to a certain tile on the map.
Parameters:
- tileX integer X coordinate of the tile.
- tileY integer Y coordinate of the tile.
- offsetX number X offset for drawing (in pixels). (default 0)
- offsetY number Y offset for drawing (in pixels). (default 0)
- localScaleX number Additional scaling factor for x axis. (default 1)
- localScaleY number Additional scaling factor for y axis. (default 1)
- setUniform (name, v0[, v1[, v2[, v3]]])
-
Sets a uniform float vector that can be used in shaders.
A uniform vector can hold up to 4 entries.
If no entries are provided the uniform will be deleted.
Parameters:
- name string The name of the uniform variable in the shader
- v0 float The first vector entry
- v1 float The second vector entry (optional)
- v2 float The third vector entry (optional)
- v3 float The fourth vector entry (optional)