Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time
634 lines (448 sloc) 15.2 KB

Game Editor API Documentation



The Collection Game Editor limits the base functions available to you for two reasons:

  • Providing a simpler environment for you to make cool stuff with
  • Making sure you don't break the environment

In consequence, most of the functions available to you come directly from Sugarcoat, while love and all its functions are banished. castle and its functions are also banished, as our game framework needs exclusivity over their features to function properly.

In addition to this, here are some quirks resulting from the design of the game framework and the use of Sugarcoat:

  • The only assets you may use are the glyphs provided by the framework. You cannot use external assets. However you may use primitive drawing functions.
  • You may only use the colors from the palette provided by the framework. When drawing glyphs or primitive shapes, you can use any color by passing its index in the palette.
  • The game's resolution is fixed to 256x192 pixels.
  • You may only use the inputs defined manually in the "Game Info" panel.

Framework functions


gameover(score, [stats])

  • Ends the game.
  • score is the player's final score. It should be between 0 (terrible, player didn't even try) and 100. (perfect)
  • stats (optional) is a table of up-to-5 strings, to be displayed on the gameover. You may use this to give the player more information on how they did in the game.

glyph(n, x, y, width, height, angle, color_a, color_b, [anchor_x = 8, anchor_y = 8])

  • Draws the glyph n at the coordinates x, y, stretched to width, height, rotated by angle full turns, using color_a as main color and color_b as secondary color, centered on the point anchor_x, anchor_y on the glyph. (in pixel coordinates, default is 8, 8)
  • Every glyph's original size is 16x16.
  • color_b is mostly used for anti-alias and details on the glyphs.
  • angle is counted in turns, meaning 1 results in a full rotation, while 0.5 results in a half rotation. (180 degrees, Pi radians)

outlined_glyph(n, x, y, width, height, angle, color_a, color_b, outline_color, [anchor_x = 8, anchor_y = 8])

  • Same as glyph(...) above, except a 1-pixel-thick outline is drawn around the glyph, using the color outline_color.


  • Saves a screenshot of the game to %appdata%\LOVE\Castle if on Windows, and to /Users/user/Library/Application Support/LOVE/Castle if on Mac.
  • The file's name will be [game title].png.


  • Shakes the screen with power intensity.
  • The intensity will be affected by the 'screenshake' user setting. (accessible in the game's pause panel once published)


  • Returns the state (true/false) of the input input.
  • input has to have been set in the "Game Info" panel.
  • Correspondance between kayboard and controller is automated. Both will trigger the same defined inputs.
  • You may use the following inputs: (as are available in the "Game Info" panel)
    • right
    • down
    • left
    • up
    • A (Z or Shift on a keyboard)
    • B (X or Ctrl on a keyboard)
    • cur_x
    • cur_y
    • cur_lb
    • cur_rb


  • "btnp" is short for "button press".
  • Returns whether the input input is active but wasn't during the previous frame.


  • "btnr" is short for "button release".
  • Returns whether the input input was active the previous frame but isn't anymore.


  • "btnv" is short for "button value".
  • Returns a decimal number representing the state of the input.
  • Particularly useful for cur_x and cur_y: btnv("cur_x") will give you the X mouse coordinate for example.
  • Simple button inputs (keyboard keys for example) will return 1 when pressed and 0 when not.

Sugarcoat functions



log(str, [prefix])

  • Puts a new line in the log with the information 'str'.
  • If prefix is set, prints it in front of str instead of the default prefix. (.)
  • prefix can only be up to 3 characters.


  • Puts a new warning line in the log with the information 'str'.


  • Puts a new error line in the log with the information 'str'.

assert(condition, str)

  • Checks the condition and crashes if it isn't true. Logs and outputs the message 'str' on crash.


  • Writes 'str' to the system clipboard.


  • Reads the system clipboard.
  • Returns the clipboard's content as a string.



  • Returns:
    • the width of the screen resolution. (always 256 here)
    • the height of the screen resolution. (always 192 here)


  • Returns the width of the screen resolution. (always 256 here)


  • Returns the height of the screen resolution. (always 192 here)

camera([x = 0, y = 0])

  • Sets a coordinate offset of {-x, -y} for the following draw operations.
  • Calling camera() resets this.

camera_move(dx, dy)

  • Offsets the coordinate offset so that it becomes {-x-dx, -y-dy}


  • Gets the current(inversed) drawing coordinate offset.
  • Returns:
    • camera_x
    • camera_y

clip(x, y, w, h)

  • Sets the clip area so that nothing gets drawn outside of it.


  • Gets the current clip area.
  • Returns:
    • clip_x
    • clip_y
    • clip_w
    • clip_h


  • Sets the color to use for drawing functions to i.
  • i is an index to a color in the currently used palette.

pal(ca, cb, [flip_level = false])

  • Swaps the color ca with the color cb in the following draw operations. (if flip_level is false)
  • ca and cb are both indexes in the currently used palette.
  • If flip_level is true, the swap will only take effect on display.

clear([c = 0])

  • Clears the screen with the color c.

cls([c = 0])

  • Alias for clear(c).

rectfill(xa, ya, xb, yb, [c])

  • Draws a filled rectangle.

rect(xa, ya, xb, yb, [c])

  • Draws an empty rectangle.

circfill(x, y, r, [c])

  • Draws a filled circle.

circ(x, y, r, [c])

  • Draws an empty circle.

trifill(xa, ya, xb, yb, xc, yc, [c])

  • Draws a filled triangle.

tri(xa, ya, xb, yb, xc, yc, [c])

  • Draws an empty triangle.

line(xa, ya, xb, yb, [c])

  • Draws a line.

pset(x, y, [c])

  • Sets the color of one pixel.


  • Returns the width in pixels of the string str as it would be rendered.
  • Font defaults to the current active font.

print(str, x, y, [c])

  • Draws the string str on the screen at the coordinates {x; y}.

printp(a, b, c, d)

  • Defines the print pattern for pprint(...).
  • a, b, c, d are to be defined as such:
  printp( 0x3330,
          0x3330 )
  • The text will be drawn multiple times, with offsets according to the numbers' positions on the pattern, with the colors defined in printp_color(...). 2 will be drawn on top of 3, and 1 will be drawn on top of 2.

printp_color(c1, c2, c3)

  • Sets the colors for pprint(...).

pprint(str, x, y, c1, c2, c3)

  • Draw text with the pattern defined by the last printp(...) call.



  • Returns the cosine of a as a turn-based angle.


  • Returns the sine of a as a turn-based angle.

atan2(x, y)

  • Converts {x; y} as an angle from 0 to 1. Returns that angle.

lerp(a, b, i)

  • Returns the linear interpolation from a to b with the parameter i.
  • For the intended use, i should be between 0 and 1. However it is not limited to those value.


  • Returns the closest integer that is equal or below a.


  • Returns the closest integer that is equal or above a.


  • Returns the closest integer to a.


  • Returns 1 if a is positive.
  • Returns -1 if a is negative.
  • Returns 0 if a is zero.


  • Returns a * a.


  • Returns a * a * a.

pow(a, b)

  • Returns the result of a to the power of b.
  • pow(a, 2) is much slower than sqr(a).


  • Returns the square root of a.


  • Returns the absolute (positive) value of a.

min(a, b)

  • Returns the lower value between a and b.

max(a, b)

  • Returns the higher value between a and b.

mid(a, b, c)

  • Returns the middle value between a, b and c.
  • mid(1, 3, 2) will return 2.

angle_diff(a1, a2)

  • Returns the difference between the turn-based angle a1 and the turn-based angle a2.

dist(x1, y1, [x2, y2])

  • If x2 and y2 are set, returns the distance between {x1; y1} and {x2; y2}.
  • Otherwise, returns the distance between {0; 0} and {x1; y1}.

sqrdist(x, y)

  • Returns the squared distance between {0; 0} and {x1; y1}.
  • Is faster than dist(...).


  • Sets the seed for the random number generation.


  • Returns a random number.
  • Always returns an integer.


  • Returns a random decimal number between 0 (included) and n (excluded).


  • Returns a random integer number between 0 (included) and n (excluded).


  • Takes an ordered table (with linear numeral keys) as parameter.
  • Returns a random element from the table.



  • Returns the time in seconds since the program's start-up.


  • Alias for t().


  • Returns the time between this frame and the previous one.


  • Alias for dt().


  • Stops the program for sec seconds.
  • Using this function will not affect dt().


  • Get the system time in the local time zone.
  • Returns, in this order:
    • seconds (0 - 59)
    • minutes (0 - 59)
    • hour (0 - 23)
    • day (1 - 31)
    • month (1 - 12)
    • year (full year)
    • week day (1 - 7)


  • Get the system time as UTC time.
  • Returns, in this order:
    • seconds (0 - 59)
    • minutes (0 - 59)
    • hour (0 - 23)
    • day (1 - 31)
    • month (1 - 12)
    • year (full year)
    • week day (1 - 7)



  • To use with for to iterate through the elements of the ordered table ar.
  • e.g:
local tab = {1, 2, 3}
for n in all(tab) do
-- > 1   2   3

del(ar, val)

  • Finds and removes the first occurence of val in the ordered table ar.
  • If ar does not contain val, nothing happens.

del_at(ar, n)

  • Removes the item at position n in the ordered table ar.

add(ar, v)

  • Adds the item v to the end of the ordered table ar.


  • Sorts the ordered table ar.

merge_tables(dst, src)

  • Copies all the keys from the table src into the table dst.
  • Returns dst.

copy_table(tab, [deep])

  • Returns a copy of the table tab.
  • If deep is true, the copy will have copies of any tables found inside tab and so will those.
  • /!\ Avoid setting deep to true when operating on tables linking to other tables in your structure, especially if you're working with double-linked tables, as that would create an infinite loop.

Standard functions

Those standard package and functions are also available to you:

  • table

  • string

  • bit

  • network (actually a Castle package)

  • unpack

  • select

  • pairs

  • ipairs

  • type

  • getmetatable

  • setmetatable

  • error

  • tostring

  • tonumber

You will find documentation for any of those packages and functions with a simple online search along the lines of "lua [package/function]".