Skip to content
Documentation
♥ Lua
gifboy apps are written in Lua. All Lua language constructs, such as variables, tables and loops can be used. Furthermore, some gifboy-specific commands exist which are listed below.
If you need a basic crash course in Lua, check out this YouTube video or go to lua.org.
Note: Parameters with a '?' are optional.
Drawing
The following commands can be used to draw shapes to the screen.
| Command | Description |
|---|---|
| clear (color_number?) | Clears the screen to black. If a color_number is given, the screen will be cleared to the respective color. |
| point (x, y, color_number?) | Draws a point at position (x, y) with the current active color. If a color_number is specified, the draw color will be changed accordingly. |
| line (x1, y1, x2, y2, color_number?) | Draws a line from point at (x1, y1) to point at (x2, y2). If a color_number is specified, the draw color will be changed accordingly. |
| rect (x, y, w, h, color_number?) | Draws a rectangle outline at position (x, y) with width w and height h. If a color_number is specified, the draw color will be changed accordingly. |
| rectfill (x, y, w, h, color_number?) | Same logic as rect(), but a filled rectangle will be drawn to the screen. |
| circle (x, y, r, color_number?) | Draws a circle outline at position (x, y) with radius r. If a color_number is specified, the draw color will be changed accordingly. |
| circlefill (x, y, r, color_number?) | Same logic as circle(), but a filled circle will be drawn to the screen. |
| arc (x, y, r, start_angle, end_angle, color_number?) | Draws an arc outline at position (x, y) with radius r spanning from start_angle to end_angle. If a color_number is specified, the draw color will be changed accordingly. |
| arcfill (x, y, r, start_angle, end_angle, color_number?) | Same logic as arc(), but a filled arc will be drawn to the screen. |
| text (content, x?, y?, color_number?) or text (content, color_number?) | Draws text to the screen as specified in string 'content'. Text will be drawn at position (x, y), if provided. If a color_number is specified, the draw color will be changed accordingly. As convenience, you can also provide "left", "center" or "right" for x and "top", "center", "bottom" for y. The text will then be positioned automatically on the screen (also taking scaling into account). |
| textb (content, x, y, inner_color_number, outer_color_number) | Draws text to the screen with same logic as text(). However, text will be drawn with inner_color_number and a border of 1 pixel according to outer_color_number. |
| textwidth (content) | Will provide the width of the 'content' string in pixels. Can be used as helper function to position text on the screen. Please note: Width will be affected if screen is scaled. |
| textheight (content) | Will provide the height of the 'content' string in pixels. Will take line breaks into account. Can be used as helper function to position text on the screen. Please note: Height will be affected if screen is scaled. |
| icon (content, x?, y?, color_number?) or icon (content, color_number?) | Draws icon(s) to the screen as specified in string 'content'. Icon(s) will be drawn at position (x, y), if provided. If a color_number is specified, the draw color will be changed accordingly. The icons are based on the pixel font 'Pixel Icons Compilation'. See Font Meme - Pixel Icons Compilation Font for list of characters/icons. |
| sprite (data, row_size, x, y, tint_color_number?, tint_alpha?) | Draws a sprite based on the pixel colors provided in the string 'data' at position (x, y). row_size specifies the width of the sprite (i.e. how many pixel go into one row). For pixel data, the following characters can be used: • 0-F: pixel with colors from 0 to 15 • Space: transparent pixel • line breaks: will be interpreted as new rows for pixels • everything else: will be drawn as black pixel Additionally, tint_color_number and tint_alpha can be used to tint the sprite with a specific color. If no tint_alpha is used a value of 0.5 is used as default. |
Draw State
The following commands change the draw state, i.e. influence the screen and draw operations in general.
| Command | Description |
|---|---|
| color (color_number) | Sets the draw color for all subsequent draw operations to the specified color. A value from 0 to 15 must be given. Values > 15 will repeat the color scheme. See color palette for all possible colors. |
| alpha (a) | Sets the alpha value for all subsequent draw operations to a. Default value is 1.0. |
| linewidth (width) | Sets the width of all lines for all subsequent draw operations using lines (e.g. line(), rect(), circle() etc.). Default width is 1 pixel. |
| linedash (segment1, segment2, offset?) | Sets a dash pattern for all subsequent draw operations using lines, where segment1 is the number of pixels that are drawn and segment2 is the number of pixels that are omitted. If offset is provided, the pattern will be shifted by n pixels accordingly. |
| translate (x, y) | Moves the origin point of the draw state by (x, y) pixels. Useful for shifting repeated draw operations. Initial origin point is (0, 0). |
| rotate (angle) | Rotates all subsequent draw operations by angle (in degrees), around the origin point of the draw state. Can be used in conjunction with translate() to rotate the screen around a certain point. Default rotation is 0. |
| scale (x, y) or scale (x) | Scales the graphics output by x on the horizontal and y on the vertical axis. Initial scale is (1, 1). If only x value is provided, both x and y axis will be scaled by the same factor. translate() can be useful for relative positioning of draw operations. |
| transform (hscale, hskew, vskew, vscale, hmove, vmove, reset?) | Transforms the draw state by scaling, skewing and moving on the horizontal and vertical axis. With this command, the individual effects of translate(), rotate() and scale() can be achieved. Default transformation is (1, 0, 0, 1, 0, 0). If reset is set to true, existing transformations will be reset to default first, before applying a new transformation. |
| clip (x, y, w, h) or clip () | Clips the draw state within the rectangle defined by (x, y, w, h). All subsequent draw operations will only draw to the defined rectangle. Use clip() to reset the clipping to the initial state. |
| palette (color_number, color_hex) or palette (color_number, r, g, b) or palette () | Can be used to change a color_number (as accessible via color() command) to a new color. Color can be either provided as hex string (e.g. 'ff0000', do not use #!) or via RGB values. Use palette() (no arguments) to reset the palette to the default colors. See color palette for all possible colors. |
Paths
Paths can be used to draw complex shapes, by moving the pointer along a certain path before drawing something to the screen.
| Command | Description |
|---|---|
| path_begin () | Begins a new path. |
| path_move (x, y) | Moves the current position of the path to position (x, y). |
| path_line (x, y) | Draws a line from current position to position (x, y). |
| path_arc (x, y, r, start_angle, end_angle) | Draws an arc from current position to end position of arc. See arc() for parameter details. |
| path_corner (x1, y1, x2, y2, r) | Draws an rounded corner between position (x1, y1) and (x2, y2) with radius r. |
| path_quadratic (x, y, cpx, cpy) | Draws a quadratic curve from current position to position (x, y) with (cp1x, cp1y) as control point. |
| path_bezier (x, y, cp1x, cp1y, cp2x, cp2y) | Draws a bezier curve from current position to position (x, y) with control points (cp1x, cp1y) (cp2x, cp2y). |
| path_close () | Closes a path. The end point of the last segment will be connected with the start segment. |
| path_stroke (color_number?) | Draws the outline of the specified path. If a color_number is specified, the draw color will be changed accordingly. |
| path_fill (color_number?) | Fills the specified path. If a color_number is specified, the draw color will be changed accordingly. |
| path_clip () | Sets the specified path as the clipping area. Note: Using clear() afterwards will remove existing clipping area from this command. |
Pixel Level Commands
These are advanced commands where pixel regions of the draw state can be changed directly.
| Command | Description |
|---|---|
| pixel (x, y) | Returns the color_number of the pixel at position (x, y). Caution: Will not work properly, if an alpha <1 has been used for drawing or palette colors have been changed and old colors are still present in the draw state. In such cases, -1 will be returned for the given pixel. |
| pixelset (dest_address, color_number, length) | gifboy has a 160x160 pixel resolution. Thus, each individual pixel can be address by index 0 (top-left pixel) to 25599 (bottom-right pixel). pixelset sets a number of pixels starting from the dest_address to the given color_number. Can be used to directly set individual pixel values or continuous sequences of pixels. |
| pixelcpy (dest_address, src_address, length) | Copies a number of pixels starting from dest_address to src_address. Can be applied to reuse certain pixel sequences in the draw state. |
App Flow
These commands control the output of the resulting GIF animation.
| Command | Description |
|---|---|
| loop (num_of_loops) | Controls the looping behavior of the resulting GIF animation. Possible values are: -1: do not loop 0: loop forever any positive number: loop n times Default setting is 0 (loop forever). Caution: loop() must be called at the begin of the app (before first frames were drawn), otherwise loop() will not have an effect. |
| delay (time) | Sets the speed of frames / how long individual frames of a GIF are shown in milliseconds. Default value is 16 (i.e. 60 frames-per-second animation). |
| render () | Adds a frame based on the current draw state to the GIF animation. Can be used to manually control the creation of frames. Otherwise, a new frame is added at the end of the draw() function for each frame automatically. |
| frames () | Returns the number of the frame that is currently drawn. Can be useful to control the animation flow. |
| maxframes () | Sets the overall maximum length of an animation. Default value is 180 (= 3 seconds). Can be increased up to 1200 (= 20 seconds). |
| stop () | Stops the app and returns the GIF animation. This method is useful to stop the animation earlier in order to create a perfectly looping result or to avoid drawing unnecessary frames. |
Caveats
Since gifboy apps are called directly via a web URL, the following points should be taken into account:
- Do not use the # operator (length of a table), as the # character is reserved in browsers for page internal links. Instead use the len(t) function which has the same functionality.
- Using the ? character in your code is not allowed, as this will break the URLs of your images. The ? will be replaced by a space character upon code execution.
The Code Editor is your friend
The code editor on the homepage has auto-complete for all commands, incl. all command parameters. Just begin to type and see what happens.