Love2D SmileBASIC Library

Welcome to the library documentation! Here you can find out what you can do with this library! Enough padding, here's the table of contents:

  1. Getting Started
  2. What about smilebasic.lua?
  3. General Functions
  4. Sprite Functions
  5. Background Functions
  6. Text Functions

Getting Started

Want to start making things, but don't want to read through the entire documentation? Here's a small starter program I wrote for you. Replace the game.lua file in the base directory with this, and you'll get some text that prints every frame!

-- This only happens once
function setup()
	-- Make a table to hold all the elements we want to update and draw each frame
	sb = {}
	-- Make a text screen
	t =, 30) -- Make a 50x30 text screen
	table.insert(sb, t) -- Add its reference to the "sb" table.
	t:fakeBoot() -- Add a fake boot screen.
	t:color(0, 15) -- Make the text transparent on a background of white.
	-- Print some test text to the text screen
	-- Note that this does not have a second argument, so it will put a line break at the end.
	t:print("This is an example script showcasing the Love2D SmileBASIC Library, a library for constructing Love2D games with a SmileBASIC aesthetic.")
	-- Make a bunch of sprites
	for i = 0, 63 do
		s = -- Make a sprite
		table.insert(sb, s) -- Add its reference to the "sb" table.
		s:offset(8 + (i % 16) * 16, 72 + math.floor(i / 16) * 16) -- Show it in a grid
		s:home(8, 8) -- Set sprite's home to center of sprite
	-- Make a background
	b =, 15) -- It's 25x15 tiles
	table.insert(sb, b) -- Add its reference to the "sb" table.
	b:print("FAKE BACKGROUND TEXT!", 0, 12) -- Special command for writing characters

-- Every frame, do this
function update()
	-- We didn't lose the text reference, so print some text every few frames
	if window.frames % 8 == 0 then -- My "built-in" frames variable
		t:print("Hello, world! ", false) -- We don't want a line break, so put false at the end.
	-- Handle callbacks and animations, neither of which you're currently using. Still useful.
	for i = 1, #sb do

-- When it's time to draw the frame, do this
function draw()
	-- Yes, you have to manually clear the screen., 0, 0)
	-- Z-sort everything you added
	for i = 1, #sb do

What's the deal with smilebasic.lua?

smilebasic.lua is a sort of abstract class written by a person who doesn't understand abstract classes, that is only used internally. Please don't use it.

If you're wondering what it does, it contains one function: SmileBASIC.add(). This function will add some functions and variables to a table given to it. It adds properties like color, offset, scale, and rotation. It also adds some helper functions, such as sb:offset(), sb:scale(), and sb:runCallbacks(). These functions will be explained in the General functions section. Oh, that seems to be the next one!

General Functions

o:offset(x?, y?, z?) -> x, y, z
This moves an object around the screen. It takes an x, y, and z coordinate (in pixels), and returns the current x, y, and z coordinates.
o:home(x?, y?) -> x, y
This sets the home of an object. It takes an x and y coordinate pair, and returns the current x and y coordinate pair.
o:rotation(r?) -> r
This sets the rotation of an object. It takes a rotation in degrees and returns the rotation in degrees.
o:color(r?, g?, b?, a?) -> r, g, b, a
This sets the color of an object. It takes r, g, b, and a values (from 0 to 1), and returns them too.
o:scale(x?, y?) -> x, y
This sets the size of an object, in coefficients. This means that if you have a 16x16 object and set the scale to (2, 2), it becomes a 32x32 object. Note that if you set only the x value, the y value won't be set along with it. Returns x and y values.
This adds a callback to the object. On sprites, backgrounds, and text objects, these are called every o:update().
This removes a callback to the object. The callback must be the same as the one you added. This means you can't remove anonymous functions, so if you ever want to remove a callback you must name it.
o:variable(index, value?) -> value
This, if given a value, will set the given index to that value. By default there are 8 internal variables. It doesn't matter if you use an index that doesn't exist. Heck, it's sorta encouraged. If you supply a value or not, the current value will be returned.
This kills the object.

Sprite Functions

Background Functions

Text Functions