love

audio

data

event

filesystem

graphics

image

joystick

keyboard

math

mouse

physics

sound

system

thread

timer

touch

window

This is an unofficial one-page reference for the LÖVE 11.3 API.

Please note that this reference may not be complete or accurate! For the most up-to-date documentation go to love2d.org/wiki

To save this page for offline viewing: Ctrl-S then select "Web Page, HTML only" instead of "Web Page, complete"

love

Types

Callbacks

Input

Window

Error handling

Functions

love.getVersion

Gets the current running version of LÖVE.

major, minor, revision, codename = love.getVersion()

For LÖVE versions below 0.9.1, the following variables can be used instead (and still work in 0.9.2 and newer):

love._version_major

love._version_minor

love._version_revision

major number The major version of LÖVE, i.e. 0 for version 0.9.1.
minor number The minor version of LÖVE, i.e. 9 for version 0.9.1.
revision number The revision version of LÖVE, i.e. 1 for version 0.9.1.
codename string The codename of the current version, i.e. 'Baby Inspector' for version 0.9.1.

love.hasDeprecationOutput

Gets whether LÖVE displays warnings when using deprecated functionality. It is disabled by default in fused mode, and enabled by default otherwise.

When deprecation output is enabled, the first use of a formally deprecated LÖVE API will show a message at the bottom of the screen for a short time, and print the message to the console.

enabled = love.hasDeprecationOutput()

enabled boolean Whether deprecation output is enabled.

love.setDeprecationOutput

Sets whether LÖVE displays warnings when using deprecated functionality. It is disabled by default in fused mode, and enabled by default otherwise.

When deprecation output is enabled, the first use of a formally deprecated LÖVE API will show a message at the bottom of the screen for a short time, and print the message to the console.

love.setDeprecationOutput( enable )

enable boolean Whether to enable or disable deprecation output.

love.conf

If a file called conf.lua is present in your game folder (or .love file), it is run before the LÖVE modules are loaded. You can use this file to overwrite the love.conf function, which is later called by the LÖVE 'boot' script. Using the love.conf function, you can set some configuration options, and change things like the default size of the window, which modules are loaded, and other stuff.

love.conf( t )

t table The love.conf function takes one argument: a table filled with all the default values which you can overwrite to your liking. If you want to change the default window size, for instance, do: function love.conf(t) t.window.width = 1024 t.window.height = 768 end If you don't need the physics module or joystick module, do the following. function love.conf(t) t.modules.joystick = false t.modules.physics = false end Setting unused modules to false is encouraged when you release your game. It reduces startup time slightly (especially if the joystick module is disabled) and reduces memory usage (slightly). Note that you can't disable love.filesystem; it's mandatory. The same goes for the love module itself. love.graphics needs love.window to be enabled.
t.identity (nil) string This flag determines the name of the save directory for your game. Note that you can only specify the name, not the location where it will be created: t.identity = "gabe_HL3" -- Correct t.identity = "c:/Users/gabe/HL3" -- Incorrect Alternatively love.filesystem.setIdentity can be used to set the save directory outside of the config file.
t.appendidentity (false) boolean This flag determines if game directory should be searched first then save directory (true) or otherwise (false)
t.version ("11.3") string t.version should be a string, representing the version of LÖVE for which your game was made. It should be formatted as "X.Y.Z" where X is the major release number, Y the minor, and Z the patch level. It allows LÖVE to display a warning if it isn't compatible. Its default is the version of LÖVE running.
t.console (false) boolean Determines whether a console should be opened alongside the game window (Windows only) or not. Note: On OSX you can get console output by running LÖVE through the terminal.
t.accelerometerjoystick (true) boolean Sets whether the device accelerometer on iOS and Android should be exposed as a 3-axis Joystick. Disabling the accelerometer when it's not used may reduce CPU usage.
t.externalstorage (false) boolean Sets whether files are saved in external storage (true) or internal storage (false) on Android.
t.gammacorrect (false) boolean Determines whether gamma-correct rendering is enabled, when the system supports it.
t.audio table Audio options.
t.audio.mic (false) boolean Request microphone permission from the user. When user allows it, love.audio.getRecordingDevices will lists recording devices available. Otherwise, love.audio.getRecordingDevices returns empty table and a message is shown to inform user when called.
t.audio.mixwithsystem (true) boolean Sets whether background audio / music from other apps should play while LÖVE is open. See love.system.hasBackgroundMusic for more details.
t.window table It is possible to defer window creation until love.window.setMode is first called in your code. To do so, set t.window = nil in love.conf (or t.screen = nil in older versions.) If this is done, LÖVE may crash if any function from love.graphics is called before the first love.window.setMode in your code. The t.window table was named t.screen in versions prior to 0.9.0. The t.screen table doesn't exist in love.conf in 0.9.0, and the t.window table doesn't exist in love.conf in 0.8.0. This means love.conf will fail to execute (therefore it will fall back to default values) if care is not taken to use the correct table for the LÖVE version being used.
t.window.title ("Untitled") string Sets the title of the window the game is in. Alternatively love.window.setTitle can be used to change the window title outside of the config file.
t.window.icon (nil) string A filepath to an image to use as the window's icon. Not all operating systems support very large icon images. The icon can also be changed with love.window.setIcon.
t.window.width (800) number Sets the window's dimensions. If these flags are set to 0 LÖVE automatically uses the user's desktop dimensions.
t.window.height (600) string Sets the window's dimensions. If these flags are set to 0 LÖVE automatically uses the user's desktop dimensions.
t.window.borderless (false) boolean Removes all border visuals from the window. Note that the effects may wary between operating systems.
t.window.resizable (false) boolean If set to true this allows the user to resize the game's window.
t.window.minwidth (1) number Sets the minimum width and height for the game's window if it can be resized by the user. If you set lower values to window.width and window.height LÖVE will always favor the minimum dimensions set via window.minwidth and window.minheight.
t.window.minheight (1) number Sets the minimum width and height for the game's window if it can be resized by the user. If you set lower values to window.width and window.height LÖVE will always favor the minimum dimensions set via window.minwidth and window.minheight.
t.window.fullscreen (false) boolean Whether to run the game in fullscreen (true) or windowed (false) mode. The fullscreen can also be toggled via love.window.setFullscreen or love.window.setMode.
t.window.fullscreentype ("desktop") string Specifies the type of fullscreen mode to use (normal or desktop). Generally the desktop is recommended, as it is less restrictive than normal mode on some operating systems.
t.window.usedpiscale (true) boolean Sets whetever to enable or disable automatic DPI scaling.
t.window.vsync (true) number Enables or deactivates vertical synchronization. Vsync tries to keep the game at a steady framerate and can prevent issues like screen tearing. It is recommended to keep vsync activated if you don't know about the possible implications of turning it off. Before LÖVE 11.0, this value was boolean (true or false). Since LÖVE 11.0, this value is number (1 to enable vsync, 0 to disable vsync, -1 to use adaptive vsync when supported). Note that in iOS, vertical synchronization is always enabled and cannot be changed.
t.window.depth (nil) number The number of bits per sample in the depth buffer (16/24/32, default nil)
t.window.stencil (nil) number Then number of bits per sample in the depth buffer (generally 8, default nil)
t.window.msaa (0) number The number of samples to use with multi-sampled antialiasing.
t.window.display (1) number The index of the display to show the window in, if multiple monitors are available.
t.window.highdpi (false) boolean See love.window.getPixelScale, love.window.toPixels, and love.window.fromPixels. It is recommended to keep this option disabled if you can't test your game on a Mac or iOS system with a Retina display, because code will need tweaking to make sure things look correct.
t.window.x (nil) number Determines the position of the window on the user's screen. Alternatively love.window.setPosition can be used to change the position on the fly.
t.window.y (nil) number Determines the position of the window on the user's screen. Alternatively love.window.setPosition can be used to change the position on the fly.
t.modules table Module options.
t.modules.audio (true) boolean Enable the audio module.
t.modules.event (true) boolean Enable the event module.
t.modules.graphics (true) boolean Enable the graphics module.
t.modules.image (true) boolean Enable the image module.
t.modules.joystick (true) boolean Enable the joystick module.
t.modules.keyboard (true) boolean Enable the keyboard module.
t.modules.math (true) boolean Enable the math module.
t.modules.mouse (true) boolean Enable the mouse module.
t.modules.physics (true) boolean Enable the physics module.
t.modules.sound (true) boolean Enable the sound module.
t.modules.system (true) boolean Enable the system module.
t.modules.timer (true) boolean Enable the timer module.
t.modules.touch (true) boolean Enable the touch module.
t.modules.video (true) boolean Enable the video module.
t.modules.window (true) boolean Enable the window module.
t.modules.thread (true) boolean Enable the thread module.

love.directorydropped

Callback function triggered when a directory is dragged and dropped onto the window.

love.directorydropped( path )

Paths passed into this callback are able to be used with love.filesystem.mount, which is the only way to get read access via love.filesystem to the dropped directory. love.filesystem.mount does not generally accept other full platform-dependent directory paths that haven't been dragged and dropped onto the window.

path string The full platform-dependent path to the directory. It can be used as an argument to love.filesystem.mount, in order to gain read access to the directory with love.filesystem.

love.displayrotated

Called when the device display orientation changed, for example, user rotated their phone 180 degrees.

love.displayrotated( index, orientation )

index number The index of the display that changed orientation.
orientation DisplayOrientation The new orientation.

love.draw

Callback function used to draw on the screen every frame.

love.draw()

love.errorhandler

The error handler, used to display error messages.

love.errorhandler( msg )

msg string The error message.

love.filedropped

Callback function triggered when a file is dragged and dropped onto the window.

love.filedropped( file )

file DroppedFile The unopened File object representing the file that was dropped.

love.focus

Callback function triggered when window receives or loses focus.

love.focus( focus )

focus boolean True if the window gains focus, false if it loses focus.

love.gamepadaxis

Called when a Joystick's virtual gamepad axis is moved.

love.gamepadaxis( joystick, axis, value )

joystick Joystick The joystick object.
axis GamepadAxis The virtual gamepad axis.
value number The new axis value.

love.gamepadpressed

Called when a Joystick's virtual gamepad button is pressed.

love.gamepadpressed( joystick, button )

joystick Joystick The joystick object.
button GamepadButton The virtual gamepad button.

love.gamepadreleased

Called when a Joystick's virtual gamepad button is released.

love.gamepadreleased( joystick, button )

joystick Joystick The joystick object.
button GamepadButton The virtual gamepad button.

love.joystickadded

Called when a Joystick is connected.

love.joystickadded( joystick )

This callback is also triggered after love.load for every Joystick which was already connected when the game started up.

joystick Joystick The newly connected Joystick object.

love.joystickaxis

Called when a joystick axis moves.

love.joystickaxis( joystick, axis, value )

joystick Joystick The joystick object.
axis number The axis number.
value number The new axis value.

love.joystickhat

Called when a joystick hat direction changes.

love.joystickhat( joystick, hat, direction )

joystick Joystick The joystick object.
hat number The hat number.
direction JoystickHat The new hat direction.

love.joystickpressed

Called when a joystick button is pressed.

love.joystickpressed( joystick, button )

joystick Joystick The joystick object.
button number The button number.

love.joystickreleased

Called when a joystick button is released.

love.joystickreleased( joystick, button )

joystick Joystick The joystick object.
button number The button number.

love.joystickremoved

Called when a Joystick is disconnected.

love.joystickremoved( joystick )

joystick Joystick The now-disconnected Joystick object.

love.keypressed

Callback function triggered when a key is pressed.

love.keypressed( key, scancode, isrepeat )

Scancodes are keyboard layout-independent, so the scancode 'w' will be generated if the key in the same place as the 'w' key on an American keyboard is pressed, no matter what the key is labelled or what the user's operating system settings are.

Key repeat needs to be enabled with love.keyboard.setKeyRepeat for repeat keypress events to be received. This does not affect love.textinput.

key KeyConstant Character of the pressed key.
scancode Scancode The scancode representing the pressed key.
isrepeat boolean Whether this keypress event is a repeat. The delay between key repeats depends on the user's system settings.

love.keypressed( key, isrepeat )

Key repeat needs to be enabled with love.keyboard.setKeyRepeat for repeat keypress events to be received.

key KeyConstant Character of the key pressed.
isrepeat boolean Whether this keypress event is a repeat. The delay between key repeats depends on the user's system settings.

love.keyreleased

Callback function triggered when a keyboard key is released.

love.keyreleased( key, scancode )

Scancodes are keyboard layout-independent, so the scancode 'w' will be used if the key in the same place as the 'w' key on an American keyboard is pressed, no matter what the key is labelled or what the user's operating system settings are.

key KeyConstant Character of the released key.
scancode Scancode The scancode representing the released key.

love.load

This function is called exactly once at the beginning of the game.

love.load( arg, unfilteredArg )

In LÖVE 11.0, the passed arguments excludes the game name and the fused command-line flag (if exist) when runs from non-fused LÖVE executable. Previous version pass the argument as-is without any filtering.

arg table Command-line arguments given to the game.
unfilteredArg table Unfiltered command-line arguments given to the executable (see #Notes).

love.lowmemory

Callback function triggered when the system is running out of memory on mobile devices.

Mobile operating systems may forcefully kill the game if it uses too much memory, so any non-critical resource should be removed if possible (by setting all variables referencing the resources to '''nil'''), when this event is triggered. Sounds and images in particular tend to use the most memory.

love.lowmemory()

love.mousefocus

Callback function triggered when window receives or loses mouse focus.

love.mousefocus( focus )

focus boolean Whether the window has mouse focus or not.

love.mousemoved

Callback function triggered when the mouse is moved.

love.mousemoved( x, y, dx, dy, istouch )

If Relative Mode is enabled for the mouse, the '''dx''' and '''dy''' arguments of this callback will update but '''x''' and '''y''' are not guaranteed to.

x number The mouse position on the x-axis.
y number The mouse position on the y-axis.
dx number The amount moved along the x-axis since the last time love.mousemoved was called.
dy number The amount moved along the y-axis since the last time love.mousemoved was called.
istouch boolean True if the mouse button press originated from a touchscreen touch-press.

love.mousepressed

Callback function triggered when a mouse button is pressed.

love.mousepressed( x, y, button, istouch, presses )

Use love.wheelmoved to detect mouse wheel motion. It will not register as a button press in version 0.10.0 and newer.

x number Mouse x position, in pixels.
y number Mouse y position, in pixels.
button number The button index that was pressed. 1 is the primary mouse button, 2 is the secondary mouse button and 3 is the middle button. Further buttons are mouse dependent.
istouch boolean True if the mouse button press originated from a touchscreen touch-press.
presses number The number of presses in a short time frame and small area, used to simulate double, triple clicks

love.mousereleased

Callback function triggered when a mouse button is released.

love.mousereleased( x, y, button, istouch, presses )

x number Mouse x position, in pixels.
y number Mouse y position, in pixels.
button number The button index that was released. 1 is the primary mouse button, 2 is the secondary mouse button and 3 is the middle button. Further buttons are mouse dependent.
istouch boolean True if the mouse button release originated from a touchscreen touch-release.
presses number The number of presses in a short time frame and small area, used to simulate double, triple clicks

love.quit

Callback function triggered when the game is closed.

r = love.quit()

r boolean Abort quitting. If true, do not close the game.

love.resize

Called when the window is resized, for example if the user resizes the window, or if love.window.setMode is called with an unsupported width or height in fullscreen and the window chooses the closest appropriate size.

love.resize( w, h )

Calls to love.window.setMode will '''only''' trigger this event if the width or height of the window after the call doesn't match the requested width and height. This can happen if a fullscreen mode is requested which doesn't match any supported mode, or if the fullscreen type is 'desktop' and the requested width or height don't match the desktop resolution.

Since 11.0, this function returns width and height in DPI-scaled units rather than pixels.

w number The new width.
h number The new height.

love.run

The main function, containing the main loop. A sensible default is used when left out.

mainLoop = love.run()

mainLoop function Function which handlers one frame, including events and rendering when called.

love.textedited

Called when the candidate text for an IME (Input Method Editor) has changed.

The candidate text is not the final text that the user will eventually choose. Use love.textinput for that.

love.textedited( text, start, length )

text string The UTF-8 encoded unicode candidate text.
start number The start cursor of the selected candidate text.
length number The length of the selected candidate text. May be 0.

love.textinput

Called when text has been entered by the user. For example if shift-2 is pressed on an American keyboard layout, the text '@' will be generated.

love.textinput( text )

Although Lua strings can store UTF-8 encoded unicode text just fine, many functions in Lua's string library will not treat the text as you might expect. For example, #text (and string.len(text)) will give the number of ''bytes'' in the string, rather than the number of unicode characters. The Lua wiki and a presentation by one of Lua's creators give more in-depth explanations, with some tips.

The utf8 library can be used to operate on UTF-8 encoded unicode text (such as the text argument given in this function.)

On Android and iOS, textinput is disabled by default; call love.keyboard.setTextInput to enable it.

text string The UTF-8 encoded unicode text.

love.threaderror

Callback function triggered when a Thread encounters an error.

love.threaderror( thread, errorstr )

thread Thread The thread which produced the error.
errorstr string The error message.

love.touchmoved

Callback function triggered when a touch press moves inside the touch screen.

love.touchmoved( id, x, y, dx, dy, pressure )

The identifier is only guaranteed to be unique for the specific touch press until love.touchreleased is called with that identifier, at which point it may be reused for new touch presses.

The unofficial Android and iOS ports of LÖVE 0.9.2 reported touch positions as normalized values in the range of 1, whereas this API reports positions in pixels.

id light userdata The identifier for the touch press.
x number The x-axis position of the touch inside the window, in pixels.
y number The y-axis position of the touch inside the window, in pixels.
dx number The x-axis movement of the touch inside the window, in pixels.
dy number The y-axis movement of the touch inside the window, in pixels.
pressure number The amount of pressure being applied. Most touch screens aren't pressure sensitive, in which case the pressure will be 1.

love.touchpressed

Callback function triggered when the touch screen is touched.

love.touchpressed( id, x, y, dx, dy, pressure )

The identifier is only guaranteed to be unique for the specific touch press until love.touchreleased is called with that identifier, at which point it may be reused for new touch presses.

The unofficial Android and iOS ports of LÖVE 0.9.2 reported touch positions as normalized values in the range of 1, whereas this API reports positions in pixels.

id light userdata The identifier for the touch press.
x number The x-axis position of the touch press inside the window, in pixels.
y number The y-axis position of the touch press inside the window, in pixels.
dx number The x-axis movement of the touch press inside the window, in pixels. This should always be zero.
dy number The y-axis movement of the touch press inside the window, in pixels. This should always be zero.
pressure number The amount of pressure being applied. Most touch screens aren't pressure sensitive, in which case the pressure will be 1.

love.touchreleased

Callback function triggered when the touch screen stops being touched.

love.touchreleased( id, x, y, dx, dy, pressure )

The identifier is only guaranteed to be unique for the specific touch press until love.touchreleased is called with that identifier, at which point it may be reused for new touch presses.

The unofficial Android and iOS ports of LÖVE 0.9.2 reported touch positions as normalized values in the range of 1, whereas this API reports positions in pixels.

id light userdata The identifier for the touch press.
x number The x-axis position of the touch inside the window, in pixels.
y number The y-axis position of the touch inside the window, in pixels.
dx number The x-axis movement of the touch inside the window, in pixels.
dy number The y-axis movement of the touch inside the window, in pixels.
pressure number The amount of pressure being applied. Most touch screens aren't pressure sensitive, in which case the pressure will be 1.

love.update

Callback function used to update the state of the game every frame.

love.update( dt )

dt number Time since the last update in seconds.

love.visible

Callback function triggered when window is minimized/hidden or unminimized by the user.

love.visible( visible )

visible boolean True if the window is visible, false if it isn't.

love.wheelmoved

Callback function triggered when the mouse wheel is moved.

love.wheelmoved( x, y )

x number Amount of horizontal mouse wheel movement. Positive values indicate movement to the right.
y number Amount of vertical mouse wheel movement. Positive values indicate upward movement.

love.conf

If a file called conf.lua is present in your game folder (or .love file), it is run before the LÖVE modules are loaded. You can use this file to overwrite the love.conf function, which is later called by the LÖVE 'boot' script. Using the love.conf function, you can set some configuration options, and change things like the default size of the window, which modules are loaded, and other stuff.

love.conf( t )

t table The love.conf function takes one argument: a table filled with all the default values which you can overwrite to your liking. If you want to change the default window size, for instance, do: function love.conf(t) t.window.width = 1024 t.window.height = 768 end If you don't need the physics module or joystick module, do the following. function love.conf(t) t.modules.joystick = false t.modules.physics = false end Setting unused modules to false is encouraged when you release your game. It reduces startup time slightly (especially if the joystick module is disabled) and reduces memory usage (slightly). Note that you can't disable love.filesystem; it's mandatory. The same goes for the love module itself. love.graphics needs love.window to be enabled.
t.identity (nil) string This flag determines the name of the save directory for your game. Note that you can only specify the name, not the location where it will be created: t.identity = "gabe_HL3" -- Correct t.identity = "c:/Users/gabe/HL3" -- Incorrect Alternatively love.filesystem.setIdentity can be used to set the save directory outside of the config file.
t.version ("11.1") string t.version should be a string, representing the version of LÖVE for which your game was made. It should be formatted as "X.Y.Z" where X is the major release number, Y the minor, and Z the patch level. It allows LÖVE to display a warning if it isn't compatible. Its default is the version of LÖVE running.
t.console (false) boolean Determines whether a console should be opened alongside the game window (Windows only) or not. Note: On OSX you can get console output by running LÖVE through the terminal.
t.accelerometerjoystick (true) boolean Sets whether the device accelerometer on iOS and Android should be exposed as a 3-axis Joystick. Disabling the accelerometer when it's not used may reduce CPU usage.
t.externalstorage (false) boolean Sets whether files are saved in external storage (true) or internal storage (false) on Android.
t.gammacorrect (false) boolean Determines whether gamma-correct rendering is enabled, when the system supports it.
t.window table It is possible to defer window creation until love.window.setMode is first called in your code. To do so, set t.window = nil in love.conf (or t.screen = nil in older versions.) If this is done, LÖVE may crash if any function from love.graphics is called before the first love.window.setMode in your code. The t.window table was named t.screen in versions prior to 0.9.0. The t.screen table doesn't exist in love.conf in 0.9.0, and the t.window table doesn't exist in love.conf in 0.8.0. This means love.conf will fail to execute (therefore it will fall back to default values) if care is not taken to use the correct table for the LÖVE version being used.
t.window.title ("Untitled") string Sets the title of the window the game is in. Alternatively love.window.setTitle can be used to change the window title outside of the config file.
t.window.icon (nil) string A filepath to an image to use as the window's icon. Not all operating systems support very large icon images. The icon can also be changed with love.window.setIcon.
t.window.width (800) number Sets the window's dimensions. If these flags are set to 0 LÖVE automatically uses the user's desktop dimensions.
t.window.height (600) string Sets the window's dimensions. If these flags are set to 0 LÖVE automatically uses the user's desktop dimensions.
t.window.borderless (false) boolean Removes all border visuals from the window. Note that the effects may wary between operating systems.
t.window.resizable (false) boolean If set to true this allows the user to resize the game's window.
t.window.minwidth (1) number Sets the minimum width and height for the game's window if it can be resized by the user. If you set lower values to window.width and window.height LÖVE will always favor the minimum dimensions set via window.minwidth and window.minheight.
t.window.minheight (1) number Sets the minimum width and height for the game's window if it can be resized by the user. If you set lower values to window.width and window.height LÖVE will always favor the minimum dimensions set via window.minwidth and window.minheight.
t.window.fullscreen (false) boolean Whether to run the game in fullscreen (true) or windowed (false) mode. The fullscreen can also be toggled via love.window.setFullscreen or love.window.setMode.
t.window.fullscreentype ("desktop") string Specifies the type of fullscreen mode to use (normal or desktop). Generally the desktop is recommended, as it is less restrictive than normal mode on some operating systems.
t.window.vsync (true) boolean Enables or deactivates vertical synchronization. Vsync tries to keep the game at a steady framerate and can prevent issues like screen tearing. It is recommended to keep vsync activated if you don't know about the possible implications of turning it off.
t.window.msaa (0) number The number of samples to use with multi-sampled antialiasing.
t.window.display (1) number The index of the display to show the window in, if multiple monitors are available.
t.window.highdpi (false) boolean See love.window.getPixelScale, love.window.toPixels, and love.window.fromPixels. It is recommended to keep this option disabled if you can't test your game on a Mac or iOS system with a Retina display, because code will need tweaking to make sure things look correct.
t.window.x (nil) number Determines the position of the window on the user's screen. Alternatively love.window.setPosition can be used to change the position on the fly.
t.window.y (nil) number Determines the position of the window on the user's screen. Alternatively love.window.setPosition can be used to change the position on the fly.
t.modules table Module options.
t.modules.audio (true) boolean Enable the audio module.
t.modules.event (true) boolean Enable the event module.
t.modules.graphics (true) boolean Enable the graphics module.
t.modules.image (true) boolean Enable the image module.
t.modules.joystick (true) boolean Enable the joystick module.
t.modules.keyboard (true) boolean Enable the keyboard module.
t.modules.math (true) boolean Enable the math module.
t.modules.mouse (true) boolean Enable the mouse module.
t.modules.physics (true) boolean Enable the physics module.
t.modules.sound (true) boolean Enable the sound module.
t.modules.system (true) boolean Enable the system module.
t.modules.timer (true) boolean Enable the timer module.
t.modules.touch (true) boolean Enable the touch module.
t.modules.video (true) boolean Enable the video module.
t.modules.window (true) boolean Enable the window module.
t.modules.thread (true) boolean Enable the thread module.

ByteData

Data object containing arbitrary bytes in an contiguous memory.

There are currently no LÖVE functions provided for manipulating the contents of a ByteData, but Data:getPointer can be used with LuaJIT's FFI to access and write to the contents directly.

Supertypes

Data

The superclass of all data.

Supertypes

Subtypes

Drawable

Superclass for all things that can be drawn on screen. This is an abstract type that can't be created directly.

Supertypes

Subtypes

Object

The superclass of all LÖVE types.

Subtypes

love.audio

Types

Functions

Playback

Listener

Other

Enums

love.audio.getActiveEffects

Gets a list of the names of the currently enabled effects.

effects = love.audio.getActiveEffects()

effects table The list of the names of the currently enabled effects.

love.audio.getActiveSourceCount

Gets the current number of simultaneously playing sources.

count = love.audio.getActiveSourceCount()

count number The current number of simultaneously playing sources.

love.audio.getDistanceModel

Returns the distance attenuation model.

model = love.audio.getDistanceModel()

model DistanceModel The current distance model. The default is 'inverseclamped'.

love.audio.getDopplerScale

Gets the current global scale factor for velocity-based doppler effects.

scale = love.audio.getDopplerScale()

scale number The current doppler scale factor.

love.audio.getEffect

Gets the settings associated with an effect.

settings = love.audio.getEffect( name )

settings table The settings associated with the effect.
name string The name of the effect.

love.audio.getMaxSceneEffects

Gets the maximum number of active effects supported by the system.

maximum = love.audio.getMaxSceneEffects()

maximum number The maximum number of active effects.

love.audio.getMaxSourceEffects

Gets the maximum number of active Effects in a single Source object, that the system can support.

maximum = love.audio.getMaxSourceEffects()

This function return 0 for system that doesn't support audio effects.

maximum number The maximum number of active Effects per Source.

love.audio.getOrientation

Returns the orientation of the listener.

fx, fy, fz, ux, uy, uz = love.audio.getOrientation()

fx, fy, fz number Forward vector of the listener orientation.
ux, uy, uz number Up vector of the listener orientation.

love.audio.getPosition

Returns the position of the listener. Please note that positional audio only works for mono (i.e. non-stereo) sources.

x, y, z = love.audio.getPosition()

x number The X position of the listener.
y number The Y position of the listener.
z number The Z position of the listener.

love.audio.getRecordingDevices

Gets a list of RecordingDevices on the system.

The first device in the list is the user's default recording device. The list may be empty if there are no microphones connected to the system.

Audio recording is currently not supported on iOS.

devices = love.audio.getRecordingDevices()

Audio recording for Android is supported since 11.3. However, it's not supported when APK from Play Store is used.

devices table The list of connected recording devices.

love.audio.getSourceCount

Gets the current number of simultaneously playing sources.

numSources = love.audio.getSourceCount()

numSources number The current number of simultaneously playing sources.

love.audio.getVelocity

Returns the velocity of the listener.

x, y, z = love.audio.getVelocity()

x number The X velocity of the listener.
y number The Y velocity of the listener.
z number The Z velocity of the listener.

love.audio.getVolume

Returns the master volume.

volume = love.audio.getVolume()

volume number The current master volume

love.audio.isEffectsSupported

Gets whether audio effects are supported in the system.

supported = love.audio.isEffectsSupported()

Older Linux distributions that ship with older OpenAL library may not support audio effects. Furthermore, iOS doesn't

support audio effects at all.

supported boolean True if effects are supported, false otherwise.

love.audio.newQueueableSource

Creates a new Source usable for real-time generated sound playback with Source:queue.

source = love.audio.newQueueableSource( samplerate, bitdepth, channels, buffercount )

The sample rate, bit depth, and channel count of any SoundData used with Source:queue must match the parameters given to this constructor.

source Source The new Source usable with Source:queue.
samplerate number Number of samples per second when playing.
bitdepth number Bits per sample (8 or 16).
channels number 1 for mono or 2 for stereo.
buffercount (0) number The number of buffers that can be queued up at any given time with Source:queue. Cannot be greater than 64. A sensible default (~8) is chosen if no value is specified.

love.audio.pause

Pauses specific or all currently played Sources.

Sources = love.audio.pause()

Pauses all currently active Sources and returns them.

Sources table A table containing a list of Sources that were paused by this call.

love.audio.pause( source, ... )

Pauses the given Sources.

source Source The first Source to pause.
... Source Additional Sources to pause.

love.audio.pause( sources )

Pauses the given Sources.

sources table A table containing a list of Sources to pause.

love.audio.play

Plays the specified Source.

love.audio.play( source )

source Source The Source to play.

love.audio.play( sources )

Starts playing multiple Sources simultaneously.

sources table Table containing a list of Sources to play.

love.audio.play( source1, source2, ... )

Starts playing multiple Sources simultaneously.

source1 Source The first Source to play.
source2 Source The second Source to play.
... Source Additional Sources to play.

love.audio.setDistanceModel

Sets the distance attenuation model.

love.audio.setDistanceModel( model )

model DistanceModel The new distance model.

love.audio.setDopplerScale

Sets a global scale factor for velocity-based doppler effects. The default scale value is 1.

love.audio.setDopplerScale( scale )

scale number The new doppler scale factor. The scale must be greater than 0.

love.audio.setEffect

Defines an effect that can be applied to a Source.

Not all system supports audio effects. Use love.audio.isEffectsSupported to check.

success = love.audio.setEffect( name, settings )

success boolean Whether the effect was successfully created.
name string The name of the effect.
settings table The settings to use for this effect, with the following fields:
settings.type EffectType The type of effect to use.
settings.volume number The volume of the effect.
settings.... number Effect-specific settings. See EffectType for available effects and their corresponding settings.

success = love.audio.setEffect( name, enabled )

success boolean Whether the effect was successfully disabled.
name string The name of the effect.
enabled (true) boolean If false and the given effect name was previously set, disables the effect.

love.audio.setMixWithSystem

Sets whether the system should mix the audio with the system's audio.

success = love.audio.setMixWithSystem( mix )

success boolean True if the change succeeded, false otherwise.
mix boolean True to enable mixing, false to disable it.

love.audio.setOrientation

Sets the orientation of the listener.

love.audio.setOrientation( fx, fy, fz, ux, uy, uz )

fx, fy, fz number Forward vector of the listener orientation.
ux, uy, uz number Up vector of the listener orientation.

love.audio.setPosition

Sets the position of the listener, which determines how sounds play.

love.audio.setPosition( x, y, z )

x number The x position of the listener.
y number The y position of the listener.
z number The z position of the listener.

love.audio.setVelocity

Sets the velocity of the listener.

love.audio.setVelocity( x, y, z )

x number The X velocity of the listener.
y number The Y velocity of the listener.
z number The Z velocity of the listener.

love.audio.setVolume

Sets the master volume.

love.audio.setVolume( volume )

volume number 1.0 is max and 0.0 is off.

love.audio.stop

Stops currently played sources.

love.audio.stop()

This function will stop all currently active sources.

love.audio.stop( source )

This function will only stop the specified source.

source Source The source on which to stop the playback.

love.audio.stop( source1, source2, ... )

Simultaneously stops all given Sources.

source1 Source The first Source to stop.
source2 Source The second Source to stop.
... Source Additional Sources to stop.

love.audio.stop( sources )

Simultaneously stops all given Sources.

sources table A table containing a list of Sources to stop.

DistanceModel

none

Sources do not get attenuated.

inverse

Inverse distance attenuation.

inverseclamped

Inverse distance attenuation. Gain is clamped. In version 0.9.2 and older this is named '''inverse clamped'''.

linear

Linear attenuation.

linearclamped

Linear attenuation. Gain is clamped. In version 0.9.2 and older this is named '''linear clamped'''.

exponent

Exponential attenuation.

exponentclamped

Exponential attenuation. Gain is clamped. In version 0.9.2 and older this is named '''exponent clamped'''.

EffectType

chorus

Plays multiple copies of the sound with slight pitch and time variation. Used to make sounds sound "fuller" or "thicker".

compressor

Decreases the dynamic range of the sound, making the loud and quiet parts closer in volume, producing a more uniform amplitude throughout time.

distortion

Alters the sound by amplifying it until it clips, shearing off parts of the signal, leading to a compressed and distorted sound.

echo

Decaying feedback based effect, on the order of seconds. Also known as delay; causes the sound to repeat at regular intervals at a decreasing volume.

equalizer

Adjust the frequency components of the sound using a 4-band (low-shelf, two band-pass and a high-shelf) equalizer.

flanger

Plays two copies of the sound; while varying the phase, or equivalently delaying one of them, by amounts on the order of milliseconds, resulting in phasing sounds.

reverb

Decaying feedback based effect, on the order of milliseconds. Used to simulate the reflection off of the surroundings.

ringmodulator

An implementation of amplitude modulation; multiplies the source signal with a simple waveform, to produce either volume changes, or inharmonic overtones.

EffectWaveform

sawtooth

A sawtooth wave, also known as a ramp wave. Named for its linear rise, and (near-)instantaneous fall along time.

sine

A sine wave. Follows a trigonometric sine function.

square

A square wave. Switches between high and low states (near-)instantaneously.

triangle

A triangle wave. Follows a linear rise and fall that repeats periodically.

FilterType

lowpass

Low-pass filter. High frequency sounds are attenuated.

highpass

High-pass filter. Low frequency sounds are attenuated.

bandpass

Band-pass filter. Both high and low frequency sounds are attenuated based on the given parameters.

SourceType

static

The whole audio is decoded.

stream

The audio is decoded in chunks when needed.

queue

The audio must be manually queued by the user.

TimeUnit

seconds

Regular seconds.

samples

Audio samples.

RecordingDevice

Represents an audio input device capable of recording sounds.

Functions

Supertypes

RecordingDevice:getBitDepth

Gets the number of bits per sample in the data currently being recorded.

bits = RecordingDevice:getBitDepth()

bits number The number of bits per sample in the data that's currently being recorded.

RecordingDevice:getBitDepth

Gets the number of bits per sample in the data currently being recorded.

bits = RecordingDevice:getBitDepth()

bits number The number of bits per sample in the data that's currently being recorded.

RecordingDevice:getChannelCount

Gets the number of channels currently being recorded (mono or stereo).

channels = RecordingDevice:getChannelCount()

channels number The number of channels being recorded (1 for mono, 2 for stereo).

RecordingDevice:getData

Gets all recorded audio SoundData stored in the device's internal ring buffer.

The internal ring buffer is cleared when this function is called, so calling it again will only get audio recorded after the previous call. If the device's internal ring buffer completely fills up before getData is called, the oldest data that doesn't fit into the buffer will be lost.

data = RecordingDevice:getData()

data SoundData The recorded audio data, or nil if the device isn't recording.

RecordingDevice:getName

Gets the name of the recording device.

name = RecordingDevice:getName()

name string The name of the device.

RecordingDevice:getSampleCount

Gets the number of currently recorded samples.

samples = RecordingDevice:getSampleCount()

samples number The number of samples that have been recorded so far.

RecordingDevice:getSampleRate

Gets the number of samples per second currently being recorded.

rate = RecordingDevice:getSampleRate()

rate number The number of samples being recorded per second (sample rate).

RecordingDevice:isRecording

Gets whether the device is currently recording.

recording = RecordingDevice:isRecording()

recording boolean True if the recording, false otherwise.

RecordingDevice:start

Begins recording audio using this device.

success = RecordingDevice:start( samplecount, samplerate, bitdepth, channels )

A ring buffer is used internally to store recorded data before RecordingDevice:getData or RecordingDevice:stop are called – the former clears the buffer. If the buffer completely fills up before getData or stop are called, the oldest data that doesn't fit into the buffer will be lost.

success boolean True if the device successfully began recording using the specified parameters, false if not.
samplecount number The maximum number of samples to store in an internal ring buffer when recording. RecordingDevice:getData clears the internal buffer when called.
samplerate (8000) number The number of samples per second to store when recording.
bitdepth (16) number The number of bits per sample.
channels (1) number Whether to record in mono or stereo. Most microphones don't support more than 1 channel.

RecordingDevice:stop

Stops recording audio from this device. Any sound data currently in the device's buffer will be returned.

data = RecordingDevice:stop()

data SoundData The sound data currently in the device's buffer, or nil if the device wasn't recording.

Source

A Source represents audio you can play back.

You can do interesting things with Sources, like set the volume, pitch, and its position relative to the listener. Please note that positional audio only works for mono (i.e. non-stereo) sources.

The Source controls (play/pause/stop) act according to the following state table.

Functions

Playback

Spatial

Info

Supertypes

Source:clone

Creates an identical copy of the Source in the stopped state.

Static Sources will use significantly less memory and take much less time to be created if Source:clone is used to create them instead of love.audio.newSource, so this method should be preferred when making multiple Sources which play the same sound.

source = Source:clone()

Cloned Sources inherit all the set-able state of the original Source, but they are initialized stopped.

source Source The new identical copy of this Source.

Source:getActiveEffects

Gets a list of the Source's active effect names.

effects = Source:getActiveEffects()

effects table A list of the source's active effect names.

Source:getAirAbsorption

Gets the amount of air absorption applied to the Source.

By default the value is set to 0 which means that air absorption effects are disabled. A value of 1 will apply high frequency attenuation to the Source at a rate of 0.05 dB per meter.

amount = Source:getAirAbsorption()

Audio air absorption functionality is not supported on iOS.

amount number The amount of air absorption applied to the Source.

Source:getAttenuationDistances

Gets the reference and maximum attenuation distances of the Source. The values, combined with the current DistanceModel, affect how the Source's volume attenuates based on distance from the listener.

ref, max = Source:getAttenuationDistances()

ref number The current reference attenuation distance. If the current DistanceModel is clamped, this is the minimum distance before the Source is no longer attenuated.
max number The current maximum attenuation distance.

Source:getChannelCount

Gets the number of channels in the Source. Only 1-channel (mono) Sources can use directional and positional effects.

channels = Source:getChannelCount()

channels number 1 for mono, 2 for stereo.

Source:getCone

Gets the Source's directional volume cones. Together with Source:setDirection, the cone angles allow for the Source's volume to vary depending on its direction.

innerAngle, outerAngle, outerVolume = Source:getCone()

innerAngle number The inner angle from the Source's direction, in radians. The Source will play at normal volume if the listener is inside the cone defined by this angle.
outerAngle number The outer angle from the Source's direction, in radians. The Source will play at a volume between the normal and outer volumes, if the listener is in between the cones defined by the inner and outer angles.
outerVolume number The Source's volume when the listener is outside both the inner and outer cone angles.

Source:getDirection

Gets the direction of the Source.

x, y, z = Source:getDirection()

x number The X part of the direction vector.
y number The Y part of the direction vector.
z number The Z part of the direction vector.

Source:getDuration

Gets the duration of the Source. For streaming Sources it may not always be sample-accurate, and may return -1 if the duration cannot be determined at all.

duration = Source:getDuration( unit )

duration number The duration of the Source, or -1 if it cannot be determined.
unit ('seconds') TimeUnit The time unit for the return value.

Source:getEffect

Gets the filter settings associated to a specific effect.

This function returns nil if the effect was applied with no filter settings associated to it.

filtersettings = Source:getEffect( name, filtersettings )

filtersettings table The settings for the filter associated to this effect, or nil if the effect is not present in this Source or has no filter associated. The table has the following fields:
filtersettings.volume number The overall volume of the audio.
filtersettings.highgain number Volume of high-frequency audio. Only applies to low-pass and band-pass filters.
filtersettings.lowgain number Volume of low-frequency audio. Only applies to high-pass and band-pass filters.
name string The name of the effect.
filtersettings ({}) table An optional empty table that will be filled with the filter settings.

Source:getFilter

Gets the filter settings currently applied to the Source.

settings = Source:getFilter()

settings table The filter settings to use for this Source, or nil if the Source has no active filter. The table has the following fields:
settings.type FilterType The type of filter to use.
settings.volume number The overall volume of the audio.
settings.highgain number Volume of high-frequency audio. Only applies to low-pass and band-pass filters.
settings.lowgain number Volume of low-frequency audio. Only applies to high-pass and band-pass filters.

Source:getFreeBufferCount

Gets the number of free buffer slots in a queueable Source. If the queueable Source is playing, this value will increase up to the amount the Source was created with. If the queueable Source is stopped, it will process all of its internal buffers first, in which case this function will always return the amount it was created with.

buffers = Source:getFreeBufferCount()

buffers number How many more SoundData objects can be queued up.

Source:getPitch

Gets the current pitch of the Source.

pitch = Source:getPitch()

pitch number The pitch, where 1.0 is normal.

Source:getPosition

Gets the position of the Source.

x, y, z = Source:getPosition()

x number The X position of the Source.
y number The Y position of the Source.
z number The Z position of the Source.

Source:getRolloff

Returns the rolloff factor of the source.

rolloff = Source:getRolloff()

rolloff number The rolloff factor.

Source:getType

Gets the type of the Source.

sourcetype = Source:getType()

sourcetype SourceType The type of the source.

Source:getVelocity

Gets the velocity of the Source.

x, y, z = Source:getVelocity()

x number The X part of the velocity vector.
y number The Y part of the velocity vector.
z number The Z part of the velocity vector.

Source:getVolume

Gets the current volume of the Source.

volume = Source:getVolume()

volume number The volume of the Source, where 1.0 is normal volume.

Source:getVolumeLimits

Returns the volume limits of the source.

min, max = Source:getVolumeLimits()

min number The minimum volume.
max number The maximum volume.

Source:isLooping

Returns whether the Source will loop.

loop = Source:isLooping()

loop boolean True if the Source will loop, false otherwise.

Source:isPlaying

Returns whether the Source is playing.

playing = Source:isPlaying()

playing boolean True if the Source is playing, false otherwise.

Source:isRelative

Gets whether the Source's position, velocity, direction, and cone angles are relative to the listener.

relative = Source:isRelative()

relative boolean True if the position, velocity, direction and cone angles are relative to the listener, false if they're absolute.

Source:pause

Pauses the Source.

Source:pause()

Source:play

Starts playing the Source.

success = Source:play()

success boolean Whether the Source was able to successfully start playing.

Source:queue

Queues SoundData for playback in a queueable Source.

This method requires the Source to be created via love.audio.newQueueableSource.

success = Source:queue( sounddata )

success boolean True if the data was successfully queued for playback, false if there were no available buffers to use for queueing.
sounddata SoundData The data to queue. The SoundData's sample rate, bit depth, and channel count must match the Source's.

Source:seek

Sets the currently playing position of the Source.

Source:seek( offset, unit )

offset number The position to seek to.
unit ('seconds') TimeUnit The unit of the position value.

Source:setAirAbsorption

Sets the amount of air absorption applied to the Source.

By default the value is set to 0 which means that air absorption effects are disabled. A value of 1 will apply high frequency attenuation to the Source at a rate of 0.05 dB per meter.

Air absorption can simulate sound transmission through foggy air, dry air, smoky atmosphere, etc. It can be used to simulate different atmospheric conditions within different locations in an area.

Source:setAirAbsorption( amount )

Audio air absorption functionality is not supported on iOS.

amount number The amount of air absorption applied to the Source. Must be between 0 and 10.

Source:setAttenuationDistances

Sets the reference and maximum attenuation distances of the Source. The parameters, combined with the current DistanceModel, affect how the Source's volume attenuates based on distance.

Distance attenuation is only applicable to Sources based on mono (rather than stereo) audio.

Source:setAttenuationDistances( ref, max )

ref number The new reference attenuation distance. If the current DistanceModel is clamped, this is the minimum attenuation distance.
max number The new maximum attenuation distance.

Source:setCone

Sets the Source's directional volume cones. Together with Source:setDirection, the cone angles allow for the Source's volume to vary depending on its direction.

Source:setCone( innerAngle, outerAngle, outerVolume )

innerAngle number The inner angle from the Source's direction, in radians. The Source will play at normal volume if the listener is inside the cone defined by this angle.
outerAngle number The outer angle from the Source's direction, in radians. The Source will play at a volume between the normal and outer volumes, if the listener is in between the cones defined by the inner and outer angles.
outerVolume (0) number The Source's volume when the listener is outside both the inner and outer cone angles.

Source:setDirection

Sets the direction vector of the Source. A zero vector makes the source non-directional.

Source:setDirection( x, y, z )

x number The X part of the direction vector.
y number The Y part of the direction vector.
z number The Z part of the direction vector.

Source:setEffect

Applies an audio effect to the Source.

The effect must have been previously defined using love.audio.setEffect.

success = Source:setEffect( name, enable )

Applies the given previously defined effect to this Source.

success boolean Whether the effect was successfully applied to this Source.
name string The name of the effect previously set up with love.audio.setEffect.
enable (true) boolean If false and the given effect name was previously enabled on this Source, disables the effect.

success = Source:setEffect( name, filtersettings )

Applies the given previously defined effect to this Source, and applies a filter to the Source which affects the sound fed into the effect.

Audio effect functionality is not supported on iOS.

success boolean Whether the effect and filter were successfully applied to this Source.
name string The name of the effect previously set up with love.audio.setEffect.
filtersettings table The filter settings to apply prior to the effect, with the following fields:
filtersettings.type FilterType The type of filter to use.
filtersettings.volume number The overall volume of the audio. Must be between 0 and 1.
filtersettings.highgain number Volume of high-frequency audio. Only applies to low-pass and band-pass filters. Must be between 0 and 1.
filtersettings.lowgain number Volume of low-frequency audio. Only applies to high-pass and band-pass filters. Must be between 0 and 1.

Source:setFilter

Sets a low-pass, high-pass, or band-pass filter to apply when playing the Source.

success = Source:setFilter( settings )

success boolean Whether the filter was successfully applied to the Source.
settings table The filter settings to use for this Source, with the following fields:
settings.type FilterType The type of filter to use.
settings.volume number The overall volume of the audio. Must be between 0 and 1.
settings.highgain number Volume of high-frequency audio. Only applies to low-pass and band-pass filters. Must be between 0 and 1.
settings.lowgain number Volume of low-frequency audio. Only applies to high-pass and band-pass filters. Must be between 0 and 1.

Source:setFilter()

Disables filtering on this Source.

Source:setLooping

Sets whether the Source should loop.

Source:setLooping( loop )

loop boolean True if the source should loop, false otherwise.

Source:setPitch

Sets the pitch of the Source.

Source:setPitch( pitch )

pitch number Calculated with regard to 1 being the base pitch. Each reduction by 50 percent equals a pitch shift of -12 semitones (one octave reduction). Each doubling equals a pitch shift of 12 semitones (one octave increase). Zero is not a legal value.

Source:setPosition

Sets the position of the Source. Please note that this only works for mono (i.e. non-stereo) sound files!

Source:setPosition( x, y, z )

x number The X position of the Source.
y number The Y position of the Source.
z number The Z position of the Source.

Source:setRelative

Sets whether the Source's position, velocity, direction, and cone angles are relative to the listener, or absolute.

By default, all sources are absolute and therefore relative to the origin of love's coordinate system 0, 0. Only absolute sources are affected by the position of the listener. Please note that positional audio only works for mono (i.e. non-stereo) sources.

Source:setRelative( enable )

enable ('false') boolean True to make the position, velocity, direction and cone angles relative to the listener, false to make them absolute.

Source:setRolloff

Sets the rolloff factor which affects the strength of the used distance attenuation.

Extended information and detailed formulas can be found in the chapter '3.4. Attenuation By Distance' of OpenAL 1.1 specification.

Source:setRolloff( rolloff )

rolloff number The new rolloff factor.

Source:setVelocity

Sets the velocity of the Source.

This does '''not''' change the position of the Source, but lets the application know how it has to calculate the doppler effect.

Source:setVelocity( x, y, z )

x number The X part of the velocity vector.
y number The Y part of the velocity vector.
z number The Z part of the velocity vector.

Source:setVolume

Sets the current volume of the Source.

Source:setVolume( volume )

volume number The volume for a Source, where 1.0 is normal volume. Volume cannot be raised above 1.0.

Source:setVolumeLimits

Sets the volume limits of the source. The limits have to be numbers from 0 to 1.

Source:setVolumeLimits( min, max )

min number The minimum volume.
max number The maximum volume.

Source:stop

Stops a Source.

Source:stop()

Source:tell

Gets the currently playing position of the Source.

position = Source:tell( unit )

position number The currently playing position of the Source.
unit ('seconds') TimeUnit The type of unit for the return value.

love.data

Functions

Enums

love.data.compress

Compresses a string or data using a specific compression algorithm.

compressedData = love.data.compress( container, format, rawstring, level )

compressedData value CompressedData/string which contains the compressed version of rawstring.
container ContainerType What type to return the compressed data as.
format CompressedDataFormat The format to use when compressing the string.
rawstring string The raw (un-compressed) string to compress.
level (-1) number The level of compression to use, between 0 and 9. -1 indicates the default level. The meaning of this argument depends on the compression format being used.

compressedData = love.data.compress( container, format, data, level )

compressedData value CompressedData/string which contains the compressed version of data.
container ContainerType What type to return the compressed data as.
format CompressedDataFormat The format to use when compressing the data.
data Data A Data object containing the raw (un-compressed) data to compress.
level (-1) number The level of compression to use, between 0 and 9. -1 indicates the default level. The meaning of this argument depends on the compression format being used.

love.data.decode

Decode Data or a string from any of the EncodeFormats to Data or string.

decoded = love.data.decode( container, format, sourceString )

decoded value ByteData/string which contains the decoded version of source.
container ContainerType What type to return the decoded data as.
format EncodeFormat The format of the input data.
sourceString string The raw (encoded) data to decode.

decoded = love.data.decode( container, format, sourceData )

decoded value ByteData/string which contains the decoded version of source.
container ContainerType What type to return the decoded data as.
format EncodeFormat The format of the input data.
sourceData Data The raw (encoded) data to decode.

love.data.decompress

Decompresses a CompressedData or previously compressed string or Data object.

decompressedData = love.data.decompress( container, compressedData )

decompressedData value Data/string containing the raw decompressed data.
container ContainerType What type to return the decompressed data as.
compressedData CompressedData The compressed data to decompress.

decompressedData = love.data.decompress( container, format, compressedString )

decompressedData value Data/string containing the raw decompressed data.
container ContainerType What type to return the decompressed data as.
format CompressedDataFormat The format that was used to compress the given string.
compressedString string A string containing data previously compressed with love.data.compress.

decompressedData = love.data.decompress( container, format, data )

decompressedData value Data/string containing the raw decompressed data.
container ContainerType What type to return the decompressed data as.
format CompressedDataFormat The format that was used to compress the given data.
data Data A Data object containing data previously compressed with love.data.compress.

love.data.encode

Encode Data or a string to a Data or string in one of the EncodeFormats.

encoded = love.data.encode( container, format, sourceString, linelength )

encoded value ByteData/string which contains the encoded version of source.
container ContainerType What type to return the encoded data as.
format EncodeFormat The format of the output data.
sourceString string The raw data to encode.
linelength (0) number The maximum line length of the output. Only supported for base64, ignored if 0.

encoded = love.data.encode( container, format, sourceData, linelength )

encoded value ByteData/string which contains the encoded version of source.
container ContainerType What type to return the encoded data as.
format EncodeFormat The format of the output data.
sourceData Data The raw data to encode.
linelength (0) number The maximum line length of the output. Only supported for base64, ignored if 0.

love.data.getPackedSize

Gets the size in bytes that a given format used with love.data.pack will use.

This function behaves the same as Lua 5.3's string.packsize.

size = love.data.getPackedSize( format )

The format string cannot have the variable-length options 's' or 'z'.

size number The size in bytes that the packed data will use.
format string A string determining how the values are packed. Follows the rules of Lua 5.3's string.pack format strings.

love.data.hash

Compute the message digest of a string using a specified hash algorithm.

rawdigest = love.data.hash( hashFunction, string )

rawdigest string Raw message digest string.
hashFunction HashFunction Hash algorithm to use.
string string String to hash.

rawdigest = love.data.hash( hashFunction, data )

To return the hex string representation of the hash, use love.data.encode

hexDigestString = love.data.encode('string', 'hex', love.data.hash(algo, data))

rawdigest string Raw message digest string.
hashFunction HashFunction Hash algorithm to use.
data Data Data to hash.

love.data.newByteData

Creates a new Data object containing arbitrary bytes.

Data:getPointer along with LuaJIT's FFI can be used to manipulate the contents of the ByteData object after it has been created.

bytedata = love.data.newByteData( datastring )

Creates a new ByteData by copying the contents of the specified string.

bytedata ByteData The new Data object.
datastring string The byte string to copy.

bytedata = love.data.newByteData( Data, offset, size )

Creates a new ByteData by copying from an existing Data object.

bytedata ByteData The new Data object.
Data Data The existing Data object to copy.
offset (0) number The offset of the subsection to copy, in bytes.
size (data:getSize()) number The size in bytes of the new Data object.

bytedata = love.data.newByteData( size )

Creates a new empty ByteData with the specific size.

bytedata ByteData The new Data object.
size number The size in bytes of the new Data object.

love.data.newDataView

Creates a new Data referencing a subsection of an existing Data object.

view = love.data.newDataView( data, offset, size )

Data:getString and Data:getPointer will return the original Data object's contents, with the view's offset and size applied.

view Data The new Data view.
data Data The Data object to reference.
offset number The offset of the subsection to reference, in bytes.
size number The size in bytes of the subsection to reference.

love.data.pack

Packs (serializes) simple Lua values.

This function behaves the same as Lua 5.3's string.pack.

data = love.data.pack( container, format, v1, ... )

Packing integers with values greater than 2^52 is not supported, as Lua 5.1 cannot represent those values in its number type.

data value Data/string which contains the serialized data.
container ContainerType What type to return the encoded data as.
format string A string determining how the values are packed. Follows the rules of Lua 5.3's string.pack format strings.
v1 value The first value (number, boolean, or string) to serialize.
... value Additional values to serialize.

love.data.unpack

Unpacks (deserializes) a byte-string or Data into simple Lua values.

This function behaves the same as Lua 5.3's string.unpack.

v1, ..., index = love.data.unpack( format, datastring, pos )

v1 value The first value (number, boolean, or string) that was unpacked.
... value Additional unpacked values.
index number The index of the first unread byte in the data string.
format string A string determining how the values were packed. Follows the rules of Lua 5.3's string.pack format strings.
datastring string A string containing the packed (serialized) data.
pos (1) number Where to start reading in the string. Negative values can be used to read relative from the end of the string.

v1, ..., index = love.data.unpack( format, data, pos )

Unpacking integers with values greater than 2^52 is not supported, as Lua 5.1 cannot represent those values in its number type.

v1 value The first value (number, boolean, or string) that was unpacked.
... value Additional unpacked values.
index number The 1-based index of the first unread byte in the Data.
format string A string determining how the values were packed. Follows the rules of Lua 5.3's string.pack format strings.
data Data A Data object containing the packed (serialized) data.
pos (1) number 1-based index indicating where to start reading in the Data. Negative values can be used to read relative from the end of the Data object.

ContainerType

data

Return type is ByteData.

string

Return type is string.

EncodeFormat

base64

Encode/decode data as base64 binary-to-text encoding.

hex

Encode/decode data as hexadecimal string.

HashFunction

md5

MD5 hash algorithm (16 bytes).

sha1

SHA1 hash algorithm (20 bytes).

sha224

SHA2 hash algorithm with message digest size of 224 bits (28 bytes).

sha256

SHA2 hash algorithm with message digest size of 256 bits (32 bytes).

sha384

SHA2 hash algorithm with message digest size of 384 bits (48 bytes).

sha512

SHA2 hash algorithm with message digest size of 512 bits (64 bytes).

love.event

Functions

Enums

love.event.clear

Clears the event queue.

love.event.clear()

love.event.poll

Returns an iterator for messages in the event queue.

i = love.event.poll()

i function Iterator function usable in a for loop.

love.event.pump

Pump events into the event queue.

This is a low-level function, and is usually not called by the user, but by love.run.

Note that this does need to be called for any OS to think you're still running,

and if you want to handle OS-generated events at all (think callbacks).

love.event.pump()

love.event.push

Adds an event to the event queue.

From 0.10.0 onwards, you may pass an arbitrary amount of arguments with this function, though the default callbacks don't ever use more than six.

love.event.push( n, a, b, c, d, e, f, ... )

n Event The name of the event.
a (nil) Variant First event argument.
b (nil) Variant Second event argument.
c (nil) Variant Third event argument.
d (nil) Variant Fourth event argument.
e (nil) Variant Fifth event argument.
f (nil) Variant Sixth event argument.
... (nil) Variant Further event arguments may follow.

love.event.quit

Adds the quit event to the queue.

The quit event is a signal for the event handler to close LÖVE. It's possible to abort the exit process with the love.quit callback.

love.event.quit( exitstatus )

exitstatus (0) number The program exit status to use when closing the application.

love.event.quit( 'restart' )

Restarts the game without relaunching the executable. This cleanly shuts down the main Lua state instance and creates a brand new one.

'restart' string Tells the default love.run to exit and restart the game without relaunching the executable.

love.event.wait

Like love.event.poll(), but blocks until there is an event in the queue.

n, a, b, c, d, e, f, ... = love.event.wait()

n Event The name of event.
a Variant First event argument.
b Variant Second event argument.
c Variant Third event argument.
d Variant Fourth event argument.
e Variant Fifth event argument.
f Variant Sixth event argument.
... Variant Further event arguments may follow.

Event

focus

Window focus gained or lost

joystickpressed

Joystick pressed

joystickreleased

Joystick released

keypressed

Key pressed

keyreleased

Key released

mousepressed

Mouse pressed

mousereleased

Mouse released

quit

Quit

resize

Window size changed by the user

visible

Window is minimized or un-minimized by the user

mousefocus

Window mouse focus gained or lost

threaderror

A Lua error has occurred in a thread

joystickadded

Joystick connected

joystickremoved

Joystick disconnected

joystickaxis

Joystick axis motion

joystickhat

Joystick hat pressed

gamepadpressed

Joystick's virtual gamepad button pressed

gamepadreleased

Joystick's virtual gamepad button released

gamepadaxis

Joystick's virtual gamepad axis moved

textinput

User entered text

mousemoved

Mouse position changed

lowmemory

Running out of memory on mobile devices system

textedited

Candidate text for an IME changed

wheelmoved

Mouse wheel moved

touchpressed

Touch screen touched

touchreleased

Touch screen stop touching

touchmoved

Touch press moved inside touch screen

directorydropped

Directory is dragged and dropped onto the window

filedropped

File is dragged and dropped onto the window.

jp

Joystick pressed

jr

Joystick released

kp

Key pressed

kr

Key released

mp

Mouse pressed

mr

Mouse released

q

Quit

f

Window focus gained or lost

love.filesystem

Types

Functions

Mounting

Directory paths

File operations

Other

Enums

love.filesystem.append

Append data to an existing file.

success, errormsg = love.filesystem.append( name, data, size )

success boolean True if the operation was successful, or nil if there was an error.
errormsg string The error message on failure.
name string The name (and path) of the file.
data string The string data to append to the file.
size (all) number How many bytes to write.

success, errormsg = love.filesystem.append( name, data, size )

success boolean True if the operation was successful, or nil if there was an error.
errormsg string The error message on failure.
name string The name (and path) of the file.
data Data The Data object to append to the file.
size (all) number How many bytes to write.

love.filesystem.areSymlinksEnabled

Gets whether love.filesystem follows symbolic links.

enable = love.filesystem.areSymlinksEnabled()

enable boolean Whether love.filesystem follows symbolic links.

love.filesystem.createDirectory

Recursively creates a directory.

When called with 'a/b' it creates both 'a' and 'a/b', if they don't exist already.

success = love.filesystem.createDirectory( name )

success boolean True if the directory was created, false if not.
name string The directory to create.

love.filesystem.getAppdataDirectory

Returns the application data directory (could be the same as getUserDirectory)

path = love.filesystem.getAppdataDirectory()

path string The path of the application data directory

love.filesystem.getCRequirePath

Gets the filesystem paths that will be searched for c libraries when require is called.

The paths string returned by this function is a sequence of path templates separated by semicolons. The argument passed to ''require'' will be inserted in place of any question mark ('?') character in each template (after the dot characters in the argument passed to ''require'' are replaced by directory separators.) Additionally, any occurrence of a double question mark ('??') will be replaced by the name passed to require and the default library extension for the platform.

The paths are relative to the game's source and save directories, as well as any paths mounted with love.filesystem.mount.

paths = love.filesystem.getCRequirePath()

The default paths string is '??', which makes require('cool') try to load cool.dll, or cool.so depending on the platform.

paths string The paths that the ''require'' function will check for c libraries in love's filesystem.

love.filesystem.getDirectoryItems

Returns a table with the names of files and subdirectories in the specified path. The table is not sorted in any way; the order is undefined.

If the path passed to the function exists in the game and the save directory, it will list the files and directories from both places.

files = love.filesystem.getDirectoryItems( dir )

files table A sequence with the names of all files and subdirectories as strings.
dir string The directory.

files = love.filesystem.getDirectoryItems( dir, callback )

files table A sequence with the names of all files and subdirectories as strings.
dir string The directory.
callback function A function which is called for each file and folder in the directory. The filename is passed to the function as an argument.

love.filesystem.getIdentity

Gets the write directory name for your game.

Note that this only returns the name of the folder to store your files in, not the full path.

name = love.filesystem.getIdentity()

name string The identity that is used as write directory.

love.filesystem.getInfo

Gets information about the specified file or directory.

info = love.filesystem.getInfo( path, filtertype )

info table A table containing information about the specified path, or nil if nothing exists at the path. The table contains the following fields:
info.type FileType The type of the object at the path (file, directory, symlink, etc.)
info.size number The size in bytes of the file, or nil if it can't be determined.
info.modtime number The file's last modification time in seconds since the unix epoch, or nil if it can't be determined.
path string The file or directory path to check.
filtertype (nil) FileType If supplied, this parameter causes getInfo to only return the info table if the item at the given path matches the specified file type.

info = love.filesystem.getInfo( path, info )

This variant accepts an existing table to fill in, instead of creating a new one.

info table The table given as an argument, or nil if nothing exists at the path. The table will be filled in with the following fields:
info.type FileType The type of the object at the path (file, directory, symlink, etc.)
info.size number The size in bytes of the file, or nil if it can't be determined.
info.modtime number The file's last modification time in seconds since the unix epoch, or nil if it can't be determined.
path string The file or directory path to check.
info table A table which will be filled in with info about the specified path.

info = love.filesystem.getInfo( path, filtertype, info )

This variant only returns info if the item at the given path is the same file type as specified in the filtertype argument, and accepts an existing table to fill in, instead of creating a new one.

info table The table given as an argument, or nil if nothing exists at the path. The table will be filled in with the following fields:
info.type FileType The type of the object at the path (file, directory, symlink, etc.)
info.size number The size in bytes of the file, or nil if it can't be determined.
info.modtime number The file's last modification time in seconds since the unix epoch, or nil if it can't be determined.
path string The file or directory path to check.
filtertype FileType Causes getInfo to only return the info table if the item at the given path matches the specified file type.
info table A table which will be filled in with info about the specified path.

love.filesystem.getRealDirectory

Gets the platform-specific absolute path of the directory containing a filepath.

This can be used to determine whether a file is inside the save directory or the game's source .love.

realdir = love.filesystem.getRealDirectory( filepath )

This function returns the directory containing the given ''file path'', rather than file. For example, if the file screenshot1.png exists in a directory called screenshots in the game's save directory, love.filesystem.getRealDirectory('screenshots/screenshot1.png') will return the same value as love.filesystem.getSaveDirectory.

realdir string The platform-specific full path of the directory containing the filepath.
filepath string The filepath to get the directory of.

love.filesystem.getRequirePath

Gets the filesystem paths that will be searched when require is called.

The paths string returned by this function is a sequence of path templates separated by semicolons. The argument passed to ''require'' will be inserted in place of any question mark ('?') character in each template (after the dot characters in the argument passed to ''require'' are replaced by directory separators.)

The paths are relative to the game's source and save directories, as well as any paths mounted with love.filesystem.mount.

paths = love.filesystem.getRequirePath()

The default paths string is '?.lua;?/init.lua', which makes require('cool') try to load cool.lua and then try cool/init.lua if cool.lua doesn't exist.

paths string The paths that the ''require'' function will check in love's filesystem.

love.filesystem.getSaveDirectory

Gets the full path to the designated save directory.

This can be useful if you want to use the standard io library (or something else) to

read or write in the save directory.

dir = love.filesystem.getSaveDirectory()

dir string The absolute path to the save directory.

love.filesystem.getSource

Returns the full path to the the .love file or directory. If the game is fused to the LÖVE executable, then the executable is returned.

path = love.filesystem.getSource()

path string The full platform-dependent path of the .love file or directory.

love.filesystem.getSourceBaseDirectory

Returns the full path to the directory containing the .love file. If the game is fused to the LÖVE executable, then the directory containing the executable is returned.

If love.filesystem.isFused is true, the path returned by this function can be passed to love.filesystem.mount, which will make the directory containing the main game (e.g. C:\Program Files\coolgame\) readable by love.filesystem.

path = love.filesystem.getSourceBaseDirectory()

path string The full platform-dependent path of the directory containing the .love file.

love.filesystem.getUserDirectory

Returns the path of the user's directory

path = love.filesystem.getUserDirectory()

path string The path of the user's directory

love.filesystem.getWorkingDirectory

Gets the current working directory.

cwd = love.filesystem.getWorkingDirectory()

cwd string The current working directory.

love.filesystem.init

Initializes love.filesystem, will be called internally, so should not be used explicitly.

love.filesystem.init( appname )

appname string The name of the application binary, typically love.

love.filesystem.isFused

Gets whether the game is in fused mode or not.

If a game is in fused mode, its save directory will be directly in the Appdata directory instead of Appdata/LOVE/. The game will also be able to load C Lua dynamic libraries which are located in the save directory.

A game is in fused mode if the source .love has been fused to the executable (see Game Distribution), or if '--fused' has been given as a command-line argument when starting the game.

fused = love.filesystem.isFused()

fused boolean True if the game is in fused mode, false otherwise.

love.filesystem.lines

Iterate over the lines in a file.

iterator = love.filesystem.lines( name )

iterator function A function that iterates over all the lines in the file
name string The name (and path) of the file

love.filesystem.load

Loads a Lua file (but does not run it).

chunk, errormsg = love.filesystem.load( name )

chunk function The loaded chunk.
errormsg string The error message if file could not be opened.
name string The name (and path) of the file.

love.filesystem.mount

Mounts a zip file or folder in the game's save directory for reading.

It is also possible to mount love.filesystem.getSourceBaseDirectory if the game is in fused mode.

success = love.filesystem.mount( archive, mountpoint, appendToPath )

success boolean True if the archive was successfully mounted, false otherwise.
archive string The folder or zip file in the game's save directory to mount.
mountpoint string The new path the archive will be mounted to.
appendToPath (false) boolean Whether the archive will be searched when reading a filepath before or after already-mounted archives. This includes the game's source and save directories.

success = love.filesystem.mount( filedata, mountpoint, appendToPath )

Mounts the contents of the given FileData in memory. The FileData's data must contain a zipped directory structure.

success boolean True if the archive was successfully mounted, false otherwise.
filedata FileData The FileData object in memory to mount.
mountpoint string The new path the archive will be mounted to.
appendToPath (false) boolean Whether the archive will be searched when reading a filepath before or after already-mounted archives. This includes the game's source and save directories.

success = love.filesystem.mount( data, archivename, mountpoint, appendToPath )

Mounts the contents of the given Data object in memory. The data must contain a zipped directory structure.

success boolean True if the archive was successfully mounted, false otherwise.
data Data The Data object in memory to mount.
archivename string The name to associate the mounted data with, for use with love.filesystem.unmount. Must be unique compared to other mounted data.
mountpoint string The new path the archive will be mounted to.
appendToPath (false) boolean Whether the archive will be searched when reading a filepath before or after already-mounted archives. This includes the game's source and save directories.

love.filesystem.newFile

Creates a new File object.

It needs to be opened before it can be accessed.

file = love.filesystem.newFile( filename )

Please note that this function will not return any error message (e.g. if you use an invalid filename) because it just creates the File Object. You can still check if the file is valid by using File:open which returns a boolean and an error message if something goes wrong while opening the file.

file File The new File object.
filename string The filename of the file.

file, errorstr = love.filesystem.newFile( filename, mode )

Creates a File object and opens it for reading, writing, or appending.

file File The new File object, or nil if an error occurred.
errorstr string The error string if an error occurred.
filename string The filename of the file.
mode FileMode The mode to open the file in.

love.filesystem.newFileData

Creates a new FileData object.

data = love.filesystem.newFileData( contents, name )

data FileData Your new FileData.
contents string The contents of the file.
name string The name of the file.

data, err = love.filesystem.newFileData( filepath )

Creates a new FileData from a file on the storage device.

data FileData The new FileData, or nil if an error occurred.
err string The error string, if an error occurred.
filepath string Path to the file.

love.filesystem.read

Read the contents of a file.

contents, size, contents, error = love.filesystem.read( name, size )

contents string The file contents.
size number How many bytes have been read.
contents nil returns nil as content.
error string returns an error message.
name string The name (and path) of the file.
size (all) number How many bytes to read.

contents, size, contents, error = love.filesystem.read( container, name, size )

Reads the contents of a file into either a string or a FileData object.

contents value FileData or string containing the file contents.
size number How many bytes have been read.
contents nil returns nil as content.
error string returns an error message.
container ContainerType What type to return the file's contents as.
name string The name (and path) of the file
size (all) number How many bytes to read

love.filesystem.remove

Removes a file or empty directory.

success = love.filesystem.remove( name )

The directory must be empty before removal or else it will fail. Simply remove all files and folders in the directory beforehand.

If the file exists in the .love but not in the save directory, it returns false as well.

An opened File prevents removal of the underlying file. Simply close the File to remove it.

success boolean True if the file/directory was removed, false otherwise.
name string The file or directory to remove.

love.filesystem.setCRequirePath

Sets the filesystem paths that will be searched for c libraries when require is called.

The paths string returned by this function is a sequence of path templates separated by semicolons. The argument passed to ''require'' will be inserted in place of any question mark ('?') character in each template (after the dot characters in the argument passed to ''require'' are replaced by directory separators.) Additionally, any occurrence of a double question mark ('??') will be replaced by the name passed to require and the default library extension for the platform.

The paths are relative to the game's source and save directories, as well as any paths mounted with love.filesystem.mount.

love.filesystem.setCRequirePath( paths )

The default paths string is '??', which makes require('cool') try to load cool.dll, or cool.so depending on the platform.

paths string The paths that the ''require'' function will check in love's filesystem.

love.filesystem.setIdentity

Sets the write directory for your game.

Note that you can only set the name of the folder to store your files in, not the location.

love.filesystem.setIdentity( name )

name string The new identity that will be used as write directory.

love.filesystem.setIdentity( name )

name string The new identity that will be used as write directory.

love.filesystem.setRequirePath

Sets the filesystem paths that will be searched when require is called.

The paths string given to this function is a sequence of path templates separated by semicolons. The argument passed to ''require'' will be inserted in place of any question mark ('?') character in each template (after the dot characters in the argument passed to ''require'' are replaced by directory separators.)

The paths are relative to the game's source and save directories, as well as any paths mounted with love.filesystem.mount.

love.filesystem.setRequirePath( paths )

The default paths string is '?.lua;?/init.lua', which makes require('cool') try to load cool.lua and then try cool/init.lua if cool.lua doesn't exist.

paths string The paths that the ''require'' function will check in love's filesystem.

love.filesystem.setSource

Sets the source of the game, where the code is present. This function can only be called once, and is normally automatically done by LÖVE.

love.filesystem.setSource( path )

path string Absolute path to the game's source folder.

love.filesystem.setSymlinksEnabled

Sets whether love.filesystem follows symbolic links. It is enabled by default in version 0.10.0 and newer, and disabled by default in 0.9.2.

love.filesystem.setSymlinksEnabled( enable )

enable boolean Whether love.filesystem should follow symbolic links.

love.filesystem.unmount

Unmounts a zip file or folder previously mounted for reading with love.filesystem.mount.

success = love.filesystem.unmount( archive )

success boolean True if the archive was successfully unmounted, false otherwise.
archive string The folder or zip file in the game's save directory which is currently mounted.

love.filesystem.write

Write data to a file in the save directory. If the file existed already, it will be completely replaced by the new contents.

success, message = love.filesystem.write( name, data, size )

success boolean If the operation was successful.
message string Error message if operation was unsuccessful.
name string The name (and path) of the file.
data string The string data to write to the file.
size (all) number How many bytes to write.

success, message = love.filesystem.write( name, data, size )

If you are getting the error message 'Could not set write directory', try setting the save directory. This is done either with love.filesystem.setIdentity or by setting the identity field in love.conf.

'''Writing to multiple lines''': In Windows, some text editors (e.g. Notepad) only treat CRLF ('\r\n') as a new line.

success boolean If the operation was successful.
message string Error message if operation was unsuccessful.
name string The name (and path) of the file.
data Data The Data object to write to the file.
size (all) number How many bytes to write.

BufferMode

none

No buffering. The result of write and append operations appears immediately.

line

Line buffering. Write and append operations are buffered until a newline is output or the buffer size limit is reached.

full

Full buffering. Write and append operations are always buffered until the buffer size limit is reached.

FileDecoder

file

The data is unencoded.

base64

The data is base64-encoded.

FileMode

r

Open a file for read.

w

Open a file for write.

a

Open a file for append.

c

Do not open a file (represents a closed file.)

FileType

file

Regular file.

directory

Directory.

symlink

Symbolic link.

other

Something completely different like a device.

File

Represents a file on the filesystem. A function that takes a file path can also take a File.

Functions

Supertypes

File:close

Closes a File.

success = File:close()

success boolean Whether closing was successful.

File:flush

Flushes any buffered written data in the file to the disk.

success, err = File:flush()

success boolean Whether the file successfully flushed any buffered data to the disk.
err string The error string, if an error occurred and the file could not be flushed.

File:getBuffer

Gets the buffer mode of a file.

mode, size = File:getBuffer()

mode BufferMode The current buffer mode of the file.
size number The maximum size in bytes of the file's buffer.

File:getFilename

Gets the filename that the File object was created with. If the file object originated from the love.filedropped callback, the filename will be the full platform-dependent file path.

filename = File:getFilename()

filename string The filename of the File.

File:getMode

Gets the FileMode the file has been opened with.

mode = File:getMode()

mode FileMode The mode this file has been opened with.

File:getSize

Returns the file size.

size = File:getSize()

size number The file size in bytes.

File:isEOF

Gets whether end-of-file has been reached.

eof = File:isEOF()

eof boolean Whether EOF has been reached.

File:isOpen

Gets whether the file is open.

open = File:isOpen()

open boolean True if the file is currently open, false otherwise.

File:lines

Iterate over all the lines in a file.

iterator = File:lines()

iterator function The iterator (can be used in for loops).

File:open

Open the file for write, read or append.

ok, err = File:open( mode )

If you are getting the error message 'Could not set write directory', try setting the save directory. This is done either with love.filesystem.setIdentity or by setting the identity field in love.conf (only available with love 0.7 or higher).

ok boolean True on success, false otherwise.
err string The error string if an error occurred.
mode FileMode The mode to open the file in.

File:read

Read a number of bytes from a file.

contents, size = File:read( bytes )

contents string The contents of the read bytes.
size number How many bytes have been read.
bytes (all) number The number of bytes to read.

contents, size = File:read( container, bytes )

Reads the contents of a file into either a string or a FileData object.

contents value FileData or string containing the read bytes.
size number How many bytes have been read.
container ContainerType What type to return the file's contents as.
bytes (all) number The number of bytes to read.

File:seek

Seek to a position in a file

success = File:seek( pos )

success boolean Whether the operation was successful
pos number The position to seek to

File:setBuffer

Sets the buffer mode for a file opened for writing or appending. Files with buffering enabled will not write data to the disk until the buffer size limit is reached, depending on the buffer mode.

File:flush will force any buffered data to be written to the disk.

success, errorstr = File:setBuffer( mode, size )

success boolean Whether the buffer mode was successfully set.
errorstr string The error string, if the buffer mode could not be set and an error occurred.
mode BufferMode The buffer mode to use.
size (0) number The maximum size in bytes of the file's buffer.

File:tell

Returns the position in the file.

pos = File:tell()

pos number The current position.

File:write

Write data to a file.

success, err = File:write( data, size )

success boolean Whether the operation was successful.
err string The error string if an error occurred.
data string The string data to write.
size (all) number How many bytes to write.

success, errorstr = File:write( data, size )

'''Writing to multiple lines''': In Windows, some text editors (e.g. Notepad before Windows 10 1809) only treat CRLF ('\r\n') as a new line.

--example

f = love.filesystem.newFile('note.txt')

f:open('w')

for i = 1, 10 do

f:write('This is line '..i..'!\r\n')

end

f:close()

success boolean Whether the operation was successful.
errorstr string The error string if an error occurred.
data Data The Data object to write.
size (all) number How many bytes to write.

FileData

Data representing the contents of a file.

Functions

Supertypes

FileData:getExtension

Gets the extension of the FileData.

ext = FileData:getExtension()

ext string The extension of the file the FileData represents.

FileData:getFilename

Gets the filename of the FileData.

name = FileData:getFilename()

name string The name of the file the FileData represents.

love.graphics

Types

Functions

Drawing

Stencil

Graphics state

Coordinate system

Window

Info

Other

Enums

love.graphics.applyTransform

Applies the given Transform object to the current coordinate transformation.

This effectively multiplies the existing coordinate transformation's matrix with the Transform object's internal matrix to produce the new coordinate transformation.

love.graphics.applyTransform( transform )

transform Transform The Transform object to apply to the current graphics coordinate transform.

love.graphics.arc

Draws a filled or unfilled arc at position (x, y). The arc is drawn from angle1 to angle2 in radians. The segments parameter determines how many segments are used to draw the arc. The more segments, the smoother the edge.

love.graphics.arc( drawmode, x, y, radius, angle1, angle2, segments )

Draws an arc using the 'pie' ArcType.

drawmode DrawMode How to draw the arc.
x number The position of the center along x-axis.
y number The position of the center along y-axis.
radius number Radius of the arc.
angle1 number The angle at which the arc begins.
angle2 number The angle at which the arc terminates.
segments (10) number The number of segments used for drawing the arc.

love.graphics.arc( drawmode, arctype, x, y, radius, angle1, angle2, segments )

drawmode DrawMode How to draw the arc.
arctype ArcType The type of arc to draw.
x number The position of the center along x-axis.
y number The position of the center along y-axis.
radius number Radius of the arc.
angle1 number The angle at which the arc begins.
angle2 number The angle at which the arc terminates.
segments (10) number The number of segments used for drawing the arc.

love.graphics.captureScreenshot

Creates a screenshot once the current frame is done (after love.draw has finished).

Since this function enqueues a screenshot capture rather than executing it immediately, it can be called from an input callback or love.update and it will still capture all of what's drawn to the screen in that frame.

love.graphics.captureScreenshot( filename )

Capture a screenshot and save it to a file at the end of the current frame.

filename string The filename to save the screenshot to. The encoded image type is determined based on the extension of the filename, and must be one of the ImageFormats.

love.graphics.captureScreenshot( callback )

Capture a screenshot and call a callback with the generated ImageData at the end of the current frame.

callback function Function which gets called once the screenshot has been captured. An ImageData is passed into the function as its only argument.

love.graphics.captureScreenshot( channel )

Capture a screenshot and push the generated ImageData to a Channel at the end of the current frame.

channel Channel The Channel to push the generated ImageData to.

love.graphics.circle

Draws a circle.

love.graphics.circle( mode, x, y, radius )

mode DrawMode How to draw the circle.
x number The position of the center along x-axis.
y number The position of the center along y-axis.
radius number The radius of the circle.

love.graphics.circle( mode, x, y, radius, segments )

mode DrawMode How to draw the circle.
x number The position of the center along x-axis.
y number The position of the center along y-axis.
radius number The radius of the circle.
segments number The number of segments used for drawing the circle. Note: The default variable for the segments parameter varies between different versions of LÖVE.

love.graphics.clear

Clears the screen or active Canvas to the specified color.

This function is called automatically before love.draw in the default love.run function. See the example in love.run for a typical use of this function.

Note that the scissor area bounds the cleared region.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

In versions prior to background color instead.

love.graphics.clear()

Clears the screen to the background color in 0.9.2 and earlier, or to transparent black (0, 0, 0, 0) in LÖVE 0.10.0 and newer.

love.graphics.clear( r, g, b, a, clearstencil, cleardepth )

Clears the screen or active Canvas to the specified color.

r number The red channel of the color to clear the screen to.
g number The green channel of the color to clear the screen to.
b number The blue channel of the color to clear the screen to.
a (1) number The alpha channel of the color to clear the screen to.
clearstencil (true) boolean Whether to clear the active stencil buffer, if present. It can also be an integer between 0 and 255 to clear the stencil buffer to a specific value.
cleardepth (true) boolean Whether to clear the active depth buffer, if present. It can also be a number between 0 and 1 to clear the depth buffer to a specific value.

love.graphics.clear( color, ..., clearstencil, cleardepth )

Clears multiple active Canvases to different colors, if multiple Canvases are active at once via love.graphics.setCanvas.

A color must be specified for each active Canvas, when this function variant is used.

color table A table in the form of {r, g, b, a} containing the color to clear the first active Canvas to.
... table Additional tables for each active Canvas.
clearstencil (true) boolean Whether to clear the active stencil buffer, if present. It can also be an integer between 0 and 255 to clear the stencil buffer to a specific value.
cleardepth (true) boolean Whether to clear the active depth buffer, if present. It can also be a number between 0 and 1 to clear the depth buffer to a specific value.

love.graphics.clear( clearcolor, clearstencil, cleardepth )

Clears the stencil or depth buffers without having to clear the color canvas as well.

clearcolor boolean Whether to clear the active color canvas to transparent black (0, 0, 0, 0). Typically this should be set to false with this variant of the function.
clearstencil boolean Whether to clear the active stencil buffer, if present. It can also be an integer between 0 and 255 to clear the stencil buffer to a specific value.
cleardepth boolean Whether to clear the active depth buffer, if present. It can also be a number between 0 and 1 to clear the depth buffer to a specific value.

love.graphics.discard

Discards (trashes) the contents of the screen or active Canvas. This is a performance optimization function with niche use cases.

If the active Canvas has just been changed and the 'replace' BlendMode is about to be used to draw something which covers the entire screen, calling love.graphics.discard rather than calling love.graphics.clear or doing nothing may improve performance on mobile devices.

On some desktop systems this function may do nothing.

love.graphics.discard( discardcolor, discardstencil )

discardcolor (true) boolean Whether to discard the texture(s) of the active Canvas(es) (the contents of the screen if no Canvas is active.)
discardstencil (true) boolean Whether to discard the contents of the stencil buffer of the screen / active Canvas.

love.graphics.discard( discardcolors, discardstencil )

discardcolors table An array containing boolean values indicating whether to discard the texture of each active Canvas, when multiple simultaneous Canvases are active.
discardstencil (true) boolean Whether to discard the contents of the stencil buffer of the screen / active Canvas.

love.graphics.draw

Draws a Drawable object (an Image, Canvas, SpriteBatch, ParticleSystem, Mesh, Text object, or Video) on the screen with optional rotation, scaling and shearing.

Objects are drawn relative to their local coordinate system. The origin is by default located at the top left corner of Image and Canvas. All scaling, shearing, and rotation arguments transform the object relative to that point. Also, the position of the origin can be specified on the screen coordinate system.

It's possible to rotate an object about its center by offsetting the origin to the center. Angles must be given in radians for rotation. One can also use a negative scaling factor to flip about its centerline.

Note that the offsets are applied before rotation, scaling, or shearing; scaling and shearing are applied before rotation.

The right and bottom edges of the object are shifted at an angle defined by the shearing factors.

When using the default shader anything drawn with this function will be tinted according to the currently selected color. Set it to pure white to preserve the object's original colors.

love.graphics.draw( drawable, x, y, r, sx, sy, ox, oy, kx, ky )

drawable Drawable A drawable object.
x (0) number The position to draw the object (x-axis).
y (0) number The position to draw the object (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

love.graphics.draw( texture, quad, x, y, r, sx, sy, ox, oy, kx, ky )

texture Texture A Texture (Image or Canvas) to texture the Quad with.
quad Quad The Quad to draw on screen.
x number The position to draw the object (x-axis).
y number The position to draw the object (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

love.graphics.draw( drawable, transform )

drawable Drawable A drawable object.
transform Transform Transformation object.

love.graphics.draw( texture, quad, transform )

texture Texture A Texture (Image or Canvas) to texture the Quad with.
quad Quad The Quad to draw on screen.
transform Transform Transformation object.

love.graphics.drawInstanced

Draws many instances of a Mesh with a single draw call, using hardware geometry instancing.

Each instance can have unique properties (positions, colors, etc.) but will not by default unless a custom per-instance vertex attributes or the love_InstanceID GLSL 3 vertex shader variable is used, otherwise they will all render at the same position on top of each other.

Instancing is not supported by some older GPUs that are only capable of using OpenGL ES 2 or OpenGL 2. Use love.graphics.getSupported to check.

love.graphics.drawInstanced( mesh, instancecount, x, y, r, sx, sy, ox, oy, kx, ky )

mesh Mesh The mesh to render.
instancecount number The number of instances to render.
x (0) number The position to draw the instances (x-axis).
y (0) number The position to draw the instances (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

love.graphics.drawInstanced( mesh, instancecount, transform )

mesh Mesh The mesh to render.
instancecount number The number of instances to render.
transform Transform A transform object.

love.graphics.drawLayer

Draws a layer of an Array Texture.

love.graphics.drawLayer( texture, layerindex, x, y, r, sx, sy, ox, oy, kx, ky )

Draws a layer of an Array Texture.

texture Texture The Array Texture to draw.
layerindex number The index of the layer to use when drawing.
x (0) number The position to draw the texture (x-axis).
y (0) number The position to draw the texture (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

love.graphics.drawLayer( texture, layerindex, quad, x, y, r, sx, sy, ox, oy, kx, ky )

Draws a layer of an Array Texture using the specified Quad.

The specified layer index overrides any layer index set on the Quad via Quad:setLayer.

texture Texture The Array Texture to draw.
layerindex number The index of the layer to use when drawing.
quad Quad The subsection of the texture's layer to use when drawing.
x (0) number The position to draw the texture (x-axis).
y (0) number The position to draw the texture (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

love.graphics.drawLayer( texture, layerindex, transform )

Draws a layer of an Array Texture using the specified Transform.

texture Texture The Array Texture to draw.
layerindex number The index of the layer to use when drawing.
transform Transform A transform object.

love.graphics.drawLayer( texture, layerindex, quad, transform )

Draws a layer of an Array Texture using the specified Quad and Transform.

In order to use an Array Texture or other non-2D texture types as the main texture in a custom void effect() variant must be used in the pixel shader, and MainTex must be declared as an ArrayImage or sampler2DArray like so: uniform ArrayImage MainTex;.

texture Texture The Array Texture to draw.
layerindex number The index of the layer to use when drawing.
quad Quad The subsection of the texture's layer to use when drawing.
transform Transform A transform object.

love.graphics.ellipse

Draws an ellipse.

love.graphics.ellipse( mode, x, y, radiusx, radiusy )

mode DrawMode How to draw the ellipse.
x number The position of the center along x-axis.
y number The position of the center along y-axis.
radiusx number The radius of the ellipse along the x-axis (half the ellipse's width).
radiusy number The radius of the ellipse along the y-axis (half the ellipse's height).

love.graphics.ellipse( mode, x, y, radiusx, radiusy, segments )

mode DrawMode How to draw the ellipse.
x number The position of the center along x-axis.
y number The position of the center along y-axis.
radiusx number The radius of the ellipse along the x-axis (half the ellipse's width).
radiusy number The radius of the ellipse along the y-axis (half the ellipse's height).
segments number The number of segments used for drawing the ellipse.

love.graphics.flushBatch

Immediately renders any pending automatically batched draws.

LÖVE will call this function internally as needed when most state is changed, so it is not necessary to manually call it.

The current batch will be automatically flushed by color), as well as Shader:send and methods on Textures which change their state. Using a different Image in consecutive love.graphics.draw calls will also flush the current batch.

SpriteBatches, ParticleSystems, Meshes, and Text objects do their own batching and do not affect automatic batching of other draws, aside from flushing the current batch when they're drawn.

love.graphics.flushBatch()

love.graphics.getBackgroundColor

Gets the current background color.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

r, g, b, a = love.graphics.getBackgroundColor()

r number The red component (0-1).
g number The green component (0-1).
b number The blue component (0-1).
a number The alpha component (0-1).

love.graphics.getBlendMode

Gets the blending mode.

mode, alphamode = love.graphics.getBlendMode()

mode BlendMode The current blend mode.
alphamode BlendAlphaMode The current blend alpha mode – it determines how the alpha of drawn objects affects blending.

love.graphics.getCanvas

Gets the current target Canvas.

canvas = love.graphics.getCanvas()

canvas Canvas The Canvas set by setCanvas. Returns nil if drawing to the real screen.

love.graphics.getCanvasFormats

Gets the available Canvas formats, and whether each is supported.

formats = love.graphics.getCanvasFormats()

formats table A table containing CanvasFormats as keys, and a boolean indicating whether the format is supported as values. Not all systems support all formats.

formats = love.graphics.getCanvasFormats( readable )

formats table A table containing CanvasFormats as keys, and a boolean indicating whether the format is supported as values (taking into account the readable parameter). Not all systems support all formats.
readable boolean If true, the returned formats will only be indicated as supported if readable flag set to true for that format, and vice versa if the parameter is false.

love.graphics.getColor

Gets the current color.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

r, g, b, a = love.graphics.getColor()

r number The red component (0-1).
g number The green component (0-1).
b number The blue component (0-1).
a number The alpha component (0-1).

love.graphics.getColorMask

Gets the active color components used when drawing. Normally all 4 components are active unless love.graphics.setColorMask has been used.

The color mask determines whether individual components of the colors of drawn objects will affect the color of the screen. They affect love.graphics.clear and Canvas:clear as well.

r, g, b, a = love.graphics.getColorMask()

r boolean Whether the red color component is active when rendering.
g boolean Whether the green color component is active when rendering.
b boolean Whether the blue color component is active when rendering.
a boolean Whether the alpha color component is active when rendering.

love.graphics.getDPIScale

Gets the DPI scale factor of the window.

The DPI scale factor represents relative pixel density. The pixel density inside the window might be greater (or smaller) than the 'size' of the window. For example on a retina screen in Mac OS X with the highdpi window flag enabled, the window may take up the same physical size as an 800x600 window, but the area inside the window uses 1600x1200 pixels. love.graphics.getDPIScale() would return 2 in that case.

The love.window.fromPixels and love.window.toPixels functions can also be used to convert between units.

The highdpi window flag must be enabled to use the full pixel density of a Retina screen on Mac OS X and iOS. The flag currently does nothing on Windows and Linux, and on Android it is effectively always enabled.

scale = love.graphics.getDPIScale()

The units of love.graphics.getWidth, love.graphics.getHeight, love.mouse.getPosition, mouse events, love.touch.getPosition, and touch events are always in DPI-scaled units rather than pixels. In LÖVE 0.10 and older they were in pixels.

scale number The pixel scale factor associated with the window.

love.graphics.getDefaultFilter

Returns the default scaling filters used with Images, Canvases, and Fonts.

min, mag, anisotropy = love.graphics.getDefaultFilter()

min FilterMode Filter mode used when scaling the image down.
mag FilterMode Filter mode used when scaling the image up.
anisotropy number Maximum amount of Anisotropic Filtering used.

love.graphics.getDepthMode

Gets the current depth test mode and whether writing to the depth buffer is enabled.

This is low-level functionality designed for use with custom vertex shaders and Meshes with custom vertex attributes. No higher level APIs are provided to set the depth of 2D graphics such as shapes, lines, and Images.

comparemode, write = love.graphics.getDepthMode()

comparemode CompareMode Depth comparison mode used for depth testing.
write boolean Whether to write update / write values to the depth buffer when rendering.

love.graphics.getDimensions

Gets the width and height in pixels of the window.

width, height = love.graphics.getDimensions()

width number The width of the window.
height number The height of the window.

love.graphics.getFont

Gets the current Font object.

font = love.graphics.getFont()

font Font The current Font. Automatically creates and sets the default font, if none is set yet.

love.graphics.getFrontFaceWinding

Gets whether triangles with clockwise- or counterclockwise-ordered vertices are considered front-facing.

This is designed for use in combination with Mesh face culling. Other love.graphics shapes, lines, and sprites are not guaranteed to have a specific winding order to their internal vertices.

winding = love.graphics.getFrontFaceWinding()

winding VertexWinding The winding mode being used. The default winding is counterclockwise ('ccw').

love.graphics.getHeight

Gets the height in pixels of the window.

height = love.graphics.getHeight()

height number The height of the window.

love.graphics.getImageFormats

Gets the raw and compressed pixel formats usable for Images, and whether each is supported.

formats = love.graphics.getImageFormats()

formats table A table containing PixelFormats as keys, and a boolean indicating whether the format is supported as values. Not all systems support all formats.

love.graphics.getLineJoin

Gets the line join style.

join = love.graphics.getLineJoin()

join LineJoin The LineJoin style.

love.graphics.getLineStyle

Gets the line style.

style = love.graphics.getLineStyle()

style LineStyle The current line style.

love.graphics.getLineWidth

Gets the current line width.

width = love.graphics.getLineWidth()

This function does not work in 0.8.0, but has been fixed in version 0.9.0. Use the following snippet to circumvent this in 0.8.0;

love.graphics._getLineWidth = love.graphics.getLineWidth

love.graphics._setLineWidth = love.graphics.setLineWidth

function love.graphics.getLineWidth() return love.graphics.varlinewidth or 1 end

function love.graphics.setLineWidth(w) love.graphics.varlinewidth = w; return love.graphics._setLineWidth(w) end

width number The current line width.

love.graphics.getMeshCullMode

Gets whether back-facing triangles in a Mesh are culled.

Mesh face culling is designed for use with low level custom hardware-accelerated 3D rendering via custom vertex attributes on Meshes, custom vertex shaders, and depth testing with a depth buffer.

mode = love.graphics.getMeshCullMode()

mode CullMode The Mesh face culling mode in use (whether to render everything, cull back-facing triangles, or cull front-facing triangles).

love.graphics.getPixelHeight

Gets the height in pixels of the window.

The graphics coordinate system and DPI scale factor, rather than raw pixels. Use getHeight for calculations related to drawing to the screen and using the coordinate system (calculating the center of the screen, for example), and getPixelHeight only when dealing specifically with underlying pixels (pixel-related calculations in a pixel Shader, for example).

pixelheight = love.graphics.getPixelHeight()

pixelheight number The height of the window in pixels.

love.graphics.getPixelWidth

Gets the width in pixels of the window.

The graphics coordinate system and DPI scale factor, rather than raw pixels. Use getWidth for calculations related to drawing to the screen and using the coordinate system (calculating the center of the screen, for example), and getPixelWidth only when dealing specifically with underlying pixels (pixel-related calculations in a pixel Shader, for example).

pixelwidth = love.graphics.getPixelWidth()

pixelwidth number The width of the window in pixels.

love.graphics.getPointSize

Gets the point size.

size = love.graphics.getPointSize()

size number The current point size.

love.graphics.getRendererInfo

Gets information about the system's video card and drivers.

name, version, vendor, device = love.graphics.getRendererInfo()

name string The name of the renderer, e.g. 'OpenGL' or 'OpenGL ES'.
version string The version of the renderer with some extra driver-dependent version info, e.g. '2.1 INTEL-8.10.44'.
vendor string The name of the graphics card vendor, e.g. 'Intel Inc'.
device string The name of the graphics card, e.g. 'Intel HD Graphics 3000 OpenGL Engine'.

love.graphics.getScissor

Gets the current scissor box.

x, y, width, height = love.graphics.getScissor()

x number The x-component of the top-left point of the box.
y number The y-component of the top-left point of the box.
width number The width of the box.
height number The height of the box.

love.graphics.getShader

Gets the current Shader. Returns nil if none is set.

shader = love.graphics.getShader()

shader Shader The currently active Shader, or nil if none is set.

love.graphics.getStackDepth

Gets the current depth of the transform / state stack (the number of pushes without corresponding pops).

depth = love.graphics.getStackDepth()

depth number The current depth of the transform and state love.graphics stack.

love.graphics.getStats

Gets performance-related rendering statistics.

stats = love.graphics.getStats()

stats table A table with the following fields:
stats.drawcalls number The number of draw calls made so far during the current frame.
stats.canvasswitches number The number of times the active Canvas has been switched so far during the current frame.
stats.texturememory number The estimated total size in bytes of video memory used by all loaded Images, Canvases, and Fonts.
stats.images number The number of Image objects currently loaded.
stats.canvases number The number of Canvas objects currently loaded.
stats.fonts number The number of Font objects currently loaded.
stats.shaderswitches number The number of times the active Shader has been changed so far during the current frame.
stats.drawcallsbatched number The number of draw calls that were saved by LÖVE's automatic batching, since the start of the frame.

stats = love.graphics.getStats( stats )

This variant accepts an existing table to fill in, instead of creating a new one.

stats table The table that was passed in above, now containing the following fields:
stats.drawcalls number The number of draw calls made so far during the current frame.
stats.canvasswitches number The number of times the active Canvas has been switched so far during the current frame.
stats.texturememory number The estimated total size in bytes of video memory used by all loaded Images, Canvases, and Fonts.
stats.images number The number of Image objects currently loaded.
stats.canvases number The number of Canvas objects currently loaded.
stats.fonts number The number of Font objects currently loaded.
stats.shaderswitches number The number of times the active Shader has been changed so far during the current frame.
stats.drawcallsbatched number The number of draw calls that were saved by LÖVE's automatic batching, since the start of the frame.
stats table A table which will be filled in with the stat fields below.

love.graphics.getStencilTest

Gets the current stencil test configuration.

When stencil testing is enabled, the geometry of everything that is drawn afterward will be clipped / stencilled out based on a comparison between the arguments of this function and the stencil value of each pixel that the geometry touches. The stencil values of pixels are affected via love.graphics.stencil.

Each Canvas has its own per-pixel stencil values.

comparemode, comparevalue = love.graphics.getStencilTest()

comparemode CompareMode The type of comparison that is made for each pixel. Will be 'always' if stencil testing is disabled.
comparevalue number The value used when comparing with the stencil value of each pixel.

love.graphics.getSupported

Gets the optional graphics features and whether they're supported on the system.

Some older or low-end systems don't always support all graphics features.

features = love.graphics.getSupported()

features table A table containing GraphicsFeature keys, and boolean values indicating whether each feature is supported.

love.graphics.getSystemLimits

Gets the system-dependent maximum values for love.graphics features.

limits = love.graphics.getSystemLimits()

limits table A table containing GraphicsLimit keys, and number values.

love.graphics.getTextureTypes

Gets the available texture types, and whether each is supported.

texturetypes = love.graphics.getTextureTypes()

texturetypes table A table containing TextureTypes as keys, and a boolean indicating whether the type is supported as values. Not all systems support all types.

love.graphics.getWidth

Gets the width in pixels of the window.

width = love.graphics.getWidth()

width number The width of the window.

love.graphics.intersectScissor

Sets the scissor to the rectangle created by the intersection of the specified rectangle with the existing scissor. If no scissor is active yet, it behaves like love.graphics.setScissor.

The scissor limits the drawing area to a specified rectangle. This affects all graphics calls, including love.graphics.clear.

The dimensions of the scissor is unaffected by graphical transformations (translate, scale, ...).

love.graphics.intersectScissor( x, y, width, height )

x number The x-coordinate of the upper left corner of the rectangle to intersect with the existing scissor rectangle.
y number The y-coordinate of the upper left corner of the rectangle to intersect with the existing scissor rectangle.
width number The width of the rectangle to intersect with the existing scissor rectangle.
height number The height of the rectangle to intersect with the existing scissor rectangle.

love.graphics.inverseTransformPoint

Converts the given 2D position from screen-space into global coordinates.

This effectively applies the reverse of the current graphics transformations to the given position. A similar Transform:inverseTransformPoint method exists for Transform objects.

globalX, globalY = love.graphics.inverseTransformPoint( screenX, screenY )

globalX number The x component of the position in global coordinates.
globalY number The y component of the position in global coordinates.
screenX number The x component of the screen-space position.
screenY number The y component of the screen-space position.

love.graphics.isGammaCorrect

Gets whether gamma-correct rendering is supported and enabled. It can be enabled by setting t.gammacorrect = true in love.conf.

Not all devices support gamma-correct rendering, in which case it will be automatically disabled and this function will return false. It is supported on desktop systems which have graphics cards that are capable of using OpenGL 3 / DirectX 10, and iOS devices that can use OpenGL ES 3.

gammacorrect = love.graphics.isGammaCorrect()

When gamma-correct rendering is enabled, many functions and objects perform automatic color conversion between sRGB and linear RGB in order for blending and shader math to be mathematically correct (which they aren't if it's not enabled.)

* The colors passed into converted from sRGB to linear RGB.

* The colors set in text with per-character colors, points with per-point colors, standard custom Meshes which use the 'VertexColor' attribute name will automatically be converted from sRGB to linear RGB when those objects are drawn.

* creating the Image.

* Everything drawn to the screen will be blended in linear RGB and then the result will be converted to sRGB for display.

* Canvases which use the 'normal' or 'srgb' CanvasFormat will have their content blended in linear RGB and the result will be stored in the canvas in sRGB, when drawing to them. When the Canvas itself is drawn, its pixel colors will be converted from sRGB to linear RGB in the same manner as Images. Keeping the canvas pixel data stored as sRGB allows for better precision (less banding) for darker colors compared to 'rgba8'.

Because most conversions are automatically handled, your own code doesn't need to worry about sRGB and linear RGB color conversions when gamma-correct rendering is enabled, except in a couple cases:

* If a Mesh with custom vertex attributes is used and one of the attributes is meant to be used as a color in a Shader, and the attribute isn't named 'VertexColor'.

* If a Shader is used which has uniform / extern variables or other variables that are meant to be used as colors, and Shader:sendColor isn't used.

In both cases, love.math.gammaToLinear can be used to convert color values to linear RGB in Lua code, or the gammaCorrectColor (or unGammaCorrectColor if necessary) shader functions can be used inside shader code. Those shader functions ''only'' do conversions if gamma-correct rendering is actually enabled. The LOVE_GAMMA_CORRECT shader preprocessor define will be set if so.

Read more about gamma-correct rendering here, here, and here.

gammacorrect boolean True if gamma-correct rendering is supported and was enabled in love.conf, false otherwise.

love.graphics.isWireframe

Gets whether wireframe mode is used when drawing.

wireframe = love.graphics.isWireframe()

wireframe boolean True if wireframe lines are used when drawing, false if it's not.

love.graphics.line

Draws lines between points.

love.graphics.line( x1, y1, x2, y2, ... )

x1 number The position of first point on the x-axis.
y1 number The position of first point on the y-axis.
x2 number The position of second point on the x-axis.
y2 number The position of second point on the y-axis.
... number You can continue passing point positions to draw a polyline.

love.graphics.line( points )

points table A table of point positions, as described above.

love.graphics.newArrayImage

Creates a new array Image.

An array image / array texture is a single object which contains multiple 'layers' or 'slices' of 2D sub-images. It can be thought of similarly to a texture atlas or sprite sheet, but it doesn't suffer from the same tile / quad bleeding artifacts that texture atlases do – although every sub-image must have the same dimensions.

A specific layer of an array image can be drawn with love.graphics.drawLayer / SpriteBatch:addLayer, or with the Quad variant of love.graphics.draw and Quad:setLayer, or via a custom Shader.

To use an array image in a Shader, it must be declared as a ArrayImage or sampler2DArray type (instead of Image or sampler2D). The Texel(ArrayImage image, vec3 texturecoord) shader function must be used to get pixel colors from a slice of the array image. The vec3 argument contains the texture coordinate in the first two components, and the 0-based slice index in the third component.

image = love.graphics.newArrayImage( slices, settings )

Creates an array Image given a different image file for each slice of the resulting array image object.

Illustration of how an array image works: [http://codeflow.org/entries/2010/dec/09/minecraft-like-rendering-experiments-in-opengl-4/illustrations/textures.jpg]

A DPI scale of 2 (double the normal pixel density) will result in the image taking up the same space on-screen as an image with half its pixel dimensions that has a DPI scale of 1. This allows for easily swapping out image assets that take the same space on-screen but have different pixel densities, which makes supporting high-dpi / retina resolution require less code logic.

In order to use an Array Texture or other non-2D texture types as the main texture in a custom void effect() variant must be used in the pixel shader, and MainTex must be declared as an ArrayImage or sampler2DArray like so: uniform ArrayImage MainTex;.

image Image An Array Image object.
slices table A table containing filepaths to images (or File, FileData, ImageData, or CompressedImageData objects), in an array. Each sub-image must have the same dimensions. A table of tables can also be given, where each sub-table contains all mipmap levels for the slice index of that sub-table.
settings (nil) table Optional table of settings to configure the array image, containing the following fields:
settings.mipmaps (false) boolean True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a compressed texture format.
settings.linear (false) boolean True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.
settings.dpiscale (1) number The DPI scale to use when drawing the array image and calling getWidth/getHeight.

love.graphics.newCanvas

Creates a new Canvas object for offscreen rendering.

canvas = love.graphics.newCanvas()

canvas Canvas A new Canvas with dimensions equal to the window's size in pixels.

canvas = love.graphics.newCanvas( width, height )

canvas Canvas A new Canvas with specified width and height.
width number The desired width of the Canvas.
height number The desired height of the Canvas.

canvas = love.graphics.newCanvas( width, height, settings )

Creates a 2D or cubemap Canvas using the given settings.

Some Canvas formats have higher system requirements than the default format. Use love.graphics.getCanvasFormats to check for support.

canvas Canvas A new Canvas with specified width and height.
width number The desired width of the Canvas.
height number The desired height of the Canvas.
settings table A table containing the given fields:
settings.type ('2d') TextureType The type of Canvas to create.
settings.format ('normal') PixelFormat The format of the Canvas.
settings.readable boolean Whether the Canvas is readable (drawable and accessible in a Shader). True by default for regular formats, false by default for depth/stencil formats.
settings.msaa (0) number The desired number of multisample antialiasing (MSAA) samples used when drawing to the Canvas.
settings.dpiscale (love.graphics.getDPIScale()) number The DPI scale factor of the Canvas, used when drawing to the Canvas as well as when drawing the Canvas to the screen.
settings.mipmaps ('none') CanvasMipmapMode Whether the Canvas has mipmaps, and whether to automatically regenerate them if so.

canvas = love.graphics.newCanvas( width, height, layers, settings )

Creates a volume or array texture-type Canvas.

canvas Canvas A new Canvas with specified width and height.
width number The desired width of the Canvas.
height number The desired height of the Canvas.
layers number The number of array layers (if the Canvas is an Array Texture), or the volume depth (if the Canvas is a Volume Texture).
settings table A table containing the given fields:
settings.type ('array') TextureType The type of Canvas to create.
settings.format ('normal') PixelFormat The format of the Canvas.
settings.readable boolean Whether the Canvas is readable (drawable and accessible in a Shader). True by default for regular formats, false by default for depth/stencil formats.
settings.msaa (0) number The desired number of multisample antialiasing (MSAA) samples used when drawing to the Canvas.
settings.dpiscale (love.graphics.getDPIScale()) number The DPI scale factor of the Canvas, used when drawing to the Canvas as well as when drawing the Canvas to the screen.
settings.mipmaps ('none') CanvasMipmapMode Whether the Canvas has mipmaps, and whether to automatically regenerate them if so.

canvas = love.graphics.newCanvas( width, height, format )

Some Canvas formats have higher system requirements than the default format. Use love.graphics.getCanvasFormats to check for support.

canvas Canvas A new Canvas with specified width and height.
width (window_width) number The desired width of the Canvas.
height (window_height) number The desired height of the Canvas.
format ('normal') CanvasFormat The desired texture format of the Canvas.

canvas = love.graphics.newCanvas( width, height, format, msaa )

Some Canvas formats have higher system requirements than the default format. Use love.graphics.getCanvasFormats to check for support.

The supported maximum number of MSAA samples varies depending on the system. Use love.graphics.getSystemLimits to check.

If the number of MSAA samples specified is greater than the maximum supported by the system, the Canvas will still be created but only using the maximum supported amount (this includes 0.)

canvas Canvas A new Canvas with specified width and height.
width (window_width) number The desired width of the Canvas.
height (window_height) number The desired height of the Canvas.
format ('normal') CanvasFormat The desired texture format of the Canvas.
msaa (0) number The desired number of multisample antialiasing (MSAA) samples used when drawing to the Canvas.

love.graphics.newCubeImage

Creates a new cubemap Image.

Cubemap images have 6 faces (sides) which represent a cube. They can't be rendered directly, they can only be used in Shader code (and sent to the shader via Shader:send).

To use a cubemap image in a Shader, it must be declared as a CubeImage or samplerCube type (instead of Image or sampler2D). The Texel(CubeImage image, vec3 direction) shader function must be used to get pixel colors from the cubemap. The vec3 argument is a normalized direction from the center of the cube, rather than explicit texture coordinates.

Each face in a cubemap image must have square dimensions.

For variants of this function which accept a single image containing multiple cubemap faces, they must be laid out in one of the following forms in the image:

+y

+z +x -z

-y

-x

or:

+y

-x +z +x -z

-y

or:

+x

-x

+y

-y

+z

-z

or:

+x -x +y -y +z -z

image = love.graphics.newCubeImage( filename, settings )

Creates a cubemap Image given a single image file containing multiple cube faces.

image Image An cubemap Image object.
filename string The filepath to a cubemap image file (or a File, FileData, or ImageData).
settings (nil) table Optional table of settings to configure the cubemap image, containing the following fields:
settings.mipmaps (false) boolean True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a compressed texture format.
settings.linear (false) boolean True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.

image = love.graphics.newCubeImage( faces, settings )

Creates a cubemap Image given a different image file for each cube face.

image Image An cubemap Image object.
faces table A table containing 6 filepaths to images (or File, FileData, ImageData, or CompressedImageData objects), in an array. Each face image must have the same dimensions. A table of tables can also be given, where each sub-table contains all mipmap levels for the cube face index of that sub-table.
settings (nil) table Optional table of settings to configure the cubemap image, containing the following fields:
settings.mipmaps (false) boolean True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a compressed texture format.
settings.linear (false) boolean True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.

love.graphics.newFont

Creates a new Font from a TrueType Font or BMFont file. Created fonts are not cached, in that calling this function with the same arguments will always create a new Font object.

All variants which accept a filename can also accept a Data object instead.

font = love.graphics.newFont( filename )

Create a new BMFont or TrueType font.

If the file is a TrueType font, it will be size 12. Use the variant below to create a TrueType font with a custom size.

font Font A Font object which can be used to draw text on screen.
filename string The filepath to the BMFont or TrueType font file.

font = love.graphics.newFont( filename, size, hinting )

Create a new TrueType font.

font Font A Font object which can be used to draw text on screen.
filename string The filepath to the TrueType font file.
size number The size of the font in pixels.
hinting ('normal') HintingMode True Type hinting mode.

font = love.graphics.newFont( filename, imagefilename )

Create a new BMFont.

font Font A Font object which can be used to draw text on screen.
filename string The filepath to the BMFont file.
imagefilename string The filepath to the BMFont's image file. If this argument is omitted, the path specified inside the BMFont file will be used.

font = love.graphics.newFont( size, hinting )

Create a new instance of the default font (Vera Sans) with a custom size.

font Font A Font object which can be used to draw text on screen.
size (12) number The size of the font in pixels.
hinting ('normal') HintingMode True Type hinting mode.

love.graphics.newImage

Creates a new Image from a filepath, FileData, an ImageData, or a CompressedImageData, and optionally generates or specifies mipmaps for the image.

image = love.graphics.newImage( filename )

image Image An Image object which can be drawn on screen.
filename string The filepath to the image file.

image = love.graphics.newImage( imageData )

image Image An Image object which can be drawn on screen.
imageData ImageData An ImageData object. The Image will use this ImageData to reload itself when love.window.setMode is called.

image = love.graphics.newImage( compressedImageData )

image Image An Image object which can be drawn on screen.
compressedImageData CompressedImageData A CompressedImageData object. The Image will use this CompressedImageData to reload itself when love.window.setMode is called.

image = love.graphics.newImage( filename, flags )

image Image A new Image object which can be drawn on screen.
filename string The filepath to the image file (or a FileData or ImageData or CompressedImageData object).
flags table A table containing the following fields:
flags.linear (false) boolean True if the image's pixels should be interpreted as being linear RGB rather than sRGB-encoded, if gamma-correct rendering is enabled. Has no effect otherwise.
flags.mipmaps (false) boolean or table If true, mipmaps for the image will be automatically generated (or taken from the images's file if possible, if the image originated from a CompressedImageData). If this value is a table, it should contain a list of other filenames of images of the same format that have progressively half-sized dimensions, all the way down to 1x1. Those images will be used as this Image's mipmap levels.

image = love.graphics.newImage( filename, format )

image Image An Image object which can be drawn on screen.
filename string The filepath to the image file (or a FileData or ImageData or CompressedImageData object.)
format TextureFormat The format to interpret the image's data as.

love.graphics.newImageFont

Creates a new specifically formatted image.

In versions prior to 0.9.0, LÖVE expects ISO 8859-1 encoding for the glyphs string.

font = love.graphics.newImageFont( filename, glyphs )

font Font A Font object which can be used to draw text on screen.
filename string The filepath to the image file.
glyphs string A string of the characters in the image in order from left to right.

font = love.graphics.newImageFont( imageData, glyphs )

font Font A Font object which can be used to draw text on screen.
imageData ImageData The ImageData object to create the font from.
glyphs string A string of the characters in the image in order from left to right.

font = love.graphics.newImageFont( filename, glyphs, extraspacing )

Instead of using this function, consider using a BMFont generator such as bmfont, littera, or bmGlyph with love.graphics.newFont. Because slime said it was better.

font Font A Font object which can be used to draw text on screen.
filename string The filepath to the image file.
glyphs string A string of the characters in the image in order from left to right.
extraspacing number Additional spacing (positive or negative) to apply to each glyph in the Font.

love.graphics.newMesh

Creates a new Mesh.

Use Mesh:setTexture if the Mesh should be textured with an Image or Canvas when it's drawn.

In versions prior to 11.0, color and byte component values were within the range of 0 to 255 instead of 0 to 1.

mesh = love.graphics.newMesh( vertices, mode, usage )

Creates a standard Mesh with the specified vertices.

mesh Mesh The new mesh.
vertices table The table filled with vertex information tables for each vertex as follows:
vertices[1] number The position of the vertex on the x-axis.
vertices[2] number The position of the vertex on the y-axis.
vertices[3] (0) number The u texture coordinate of the vertex. Texture coordinates are normally in the range of 1, but can be greater or less (see WrapMode.)
vertices[4] (0) number The v texture coordinate of the vertex. Texture coordinates are normally in the range of 1, but can be greater or less (see WrapMode.)
vertices[5] (1) number The red component of the vertex color.
vertices[6] (1) number The green component of the vertex color.
vertices[7] (1) number The blue component of the vertex color.
vertices[8] (1) number The alpha component of the vertex color.
mode ('fan') MeshDrawMode How the vertices are used when drawing. The default mode 'fan' is sufficient for simple convex polygons.
usage ('dynamic') SpriteBatchUsage The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.

mesh = love.graphics.newMesh( vertexcount, mode, usage )

Creates a standard Mesh with the specified number of vertices.

Mesh:setVertices or Mesh:setVertex and Mesh:setDrawRange can be used to specify vertex information once the Mesh is created.

mesh Mesh The new mesh.
vertexcount number The total number of vertices the Mesh will use. Each vertex is initialized to {0,0, 0,0, 1,1,1,1}.
mode ('fan') MeshDrawMode How the vertices are used when drawing. The default mode 'fan' is sufficient for simple convex polygons.
usage ('dynamic') SpriteBatchUsage The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.

mesh = love.graphics.newMesh( vertexformat, vertices, mode, usage )

Creates a Mesh with custom vertex attributes and the specified vertex data.

The values in each vertex table are in the same order as the vertex attributes in the specified vertex format. If no value is supplied for a specific vertex attribute component, it will be set to a default value of 0 if its data type is 'float', or 1 if its data type is 'byte'.

If the data type of an attribute is 'float', components can be in the range 1 to 4, if the data type is 'byte' it must be 4.

If a custom vertex attribute uses the name 'VertexPosition', 'VertexTexCoord', or 'VertexColor', then the vertex data for that vertex attribute will be used for the standard vertex positions, texture coordinates, or vertex colors respectively, when drawing the Mesh. Otherwise a Vertex Shader is required in order to make use of the vertex attribute when the Mesh is drawn.

A Mesh '''must''' have a 'VertexPosition' attribute in order to be drawn, but it can be attached from a different Mesh via Mesh:attachAttribute.

To use a custom named vertex attribute in a Vertex Shader, it must be declared as an attribute variable of the same name. Variables can be sent from Vertex Shader code to Pixel Shader code by making a varying variable. For example:

''Vertex Shader code''

attribute vec2 CoolVertexAttribute;

varying vec2 CoolVariable;

vec4 position(mat4 transform_projection, vec4 vertex_position)

{

CoolVariable = CoolVertexAttribute;

return transform_projection * vertex_position;

}

''Pixel Shader code''

varying vec2 CoolVariable;

vec4 effect(vec4 color, Image tex, vec2 texcoord, vec2 pixcoord)

{

vec4 texcolor = Texel(tex, texcoord + CoolVariable);

return texcolor * color;

}

mesh Mesh The new mesh.
vertexformat table A table in the form of {attribute, ...}. Each attribute is a table which specifies a custom vertex attribute used for each vertex.
vertexformat.attribute table A table containing the attribute's name, it's data type, and the number of components in the attribute, in the form of {name, datatype, components}.
vertexformat.... table Additional vertex attribute format tables.
vertices table The table filled with vertex information tables for each vertex, in the form of {vertex, ...} where each vertex is a table in the form of {attributecomponent, ...}.
vertices.attributecomponent number The first component of the first vertex attribute in the vertex.
vertices.... number Additional components of all vertex attributes in the vertex.
mode ('fan') MeshDrawMode How the vertices are used when drawing. The default mode 'fan' is sufficient for simple convex polygons.
usage ('dynamic') SpriteBatchUsage The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.

mesh = love.graphics.newMesh( vertexformat, vertexcount, mode, usage )

Creates a Mesh with custom vertex attributes and the specified number of vertices.

Each vertex attribute component is initialized to 0 if its data type is 'float', or 1 if its data type is 'byte'. Vertex Shader is required in order to make use of the vertex attribute when the Mesh is drawn.

A Mesh '''must''' have a 'VertexPosition' attribute in order to be drawn, but it can be attached from a different Mesh via Mesh:attachAttribute.

mesh Mesh The new mesh.
vertexformat table A table in the form of {attribute, ...}. Each attribute is a table which specifies a custom vertex attribute used for each vertex.
vertexformat.attribute table A table containing the attribute's name, it's data type, and the number of components in the attribute, in the form of {name, datatype, components}.
vertexformat.... table Additional vertex attribute format tables.
vertexcount number The total number of vertices the Mesh will use.
mode ('fan') MeshDrawMode How the vertices are used when drawing. The default mode 'fan' is sufficient for simple convex polygons.
usage ('dynamic') SpriteBatchUsage The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.

mesh = love.graphics.newMesh( vertexcount, texture, mode )

Mesh:setVertices or Mesh:setVertex and Mesh:setDrawRange can be used to specify vertex information once the Mesh is created.

mesh Mesh The new mesh.
vertexcount number The total number of vertices the Mesh will use. Each vertex is initialized to {0,0, 0,0, 255,255,255,255}.
texture (nil) Texture The Image or Canvas to use when drawing the Mesh. May be nil to use no texture.
mode ('fan') MeshDrawMode How the vertices are used when drawing. The default mode 'fan' is sufficient for simple convex polygons.

love.graphics.newParticleSystem

Creates a new ParticleSystem.

system = love.graphics.newParticleSystem( image, buffer )

system ParticleSystem A new ParticleSystem.
image Image The image to use.
buffer (1000) number The max number of particles at the same time.

system = love.graphics.newParticleSystem( texture, buffer )

system ParticleSystem A new ParticleSystem.
texture Texture The texture (Image or Canvas) to use.
buffer (1000) number The max number of particles at the same time.

love.graphics.newQuad

Creates a new Quad.

The purpose of a Quad is to use a fraction of an image to draw objects, as opposed to drawing entire image. It is most useful for sprite sheets and atlases: in a sprite atlas, multiple sprites reside in same image, quad is used to draw a specific sprite from that image; in animated sprites with all frames residing in the same image, quad is used to draw specific frame from the animation.

quad = love.graphics.newQuad( x, y, width, height, sw, sh )

quad Quad The new Quad.
x number The top-left position in the Image along the x-axis.
y number The top-left position in the Image along the y-axis.
width number The width of the Quad in the Image. (Must be greater than 0.)
height number The height of the Quad in the Image. (Must be greater than 0.)
sw number The reference width, the width of the Image. (Must be greater than 0.)
sh number The reference height, the height of the Image. (Must be greater than 0.)

love.graphics.newShader

Creates a new Shader object for hardware-accelerated vertex and pixel effects. A Shader contains either vertex shader code, pixel shader code, or both.

Shaders are small programs which are run on the graphics card when drawing. Vertex shaders are run once for each vertex (for example, an image has 4 vertices - one at each corner. A Mesh might have many more.) Pixel shaders are run once for each pixel on the screen which the drawn object touches. Pixel shader code is executed after all the object's vertices have been processed by the vertex shader.

shader = love.graphics.newShader( code )

shader Shader A Shader object for use in drawing operations.
code string The pixel shader or vertex shader code, or a filename pointing to a file with the code.

output_pos = love.graphics.newShader( transform_projection, vertex_position )

Vertex shader code is run for every vertex drawn to the screen (for example, love.graphics.rectangle will produce 4 vertices) and is used to transform the vertex positions from their original coordinates into screen-space, as well as to send information such as per-vertex color and texture coordinate values to the pixel shader.

Pixel shader code is run for every pixel on the screen that a drawn object touches, and is used to produce the color that will be blended onto the screen at that pixel, often by reading from an image. Pixel shaders are sometimes called fragment shaders.

The varying keyword can be used to set a value in the vertex shader and have it interpolated in between vertices and passed down to the pixel shader.

Vertex and Pixel shader code can be combined into one file or string if you wrap the vertex-specific code in #ifdef VERTEX .. #endif and the pixel-specific code in #ifdef PIXEL .. #endif.

== Built-in variables ==

LÖVE provides several built-in variables for both pixel and vertex shaders. The full list can be found here: Shader Variables.

output_pos vec4 The final transformed position of the current vertex.
transform_projection mat4 The transformation matrix affected by love.graphics.translate and friends combined with the orthographic projection matrix.
vertex_position vec4 The raw un-transformed position of the current vertex.

love.graphics.newSpriteBatch

Creates a new SpriteBatch object.

spriteBatch = love.graphics.newSpriteBatch( image, maxsprites )

spriteBatch SpriteBatch The new SpriteBatch.
image Image The Image to use for the sprites.
maxsprites (1000) number The maximum number of sprites that the SpriteBatch can contain at any given time. Since version 11.0, additional sprites added past this number will automatically grow the spritebatch.

spriteBatch = love.graphics.newSpriteBatch( image, maxsprites, usage )

spriteBatch SpriteBatch The new SpriteBatch.
image Image The Image to use for the sprites.
maxsprites (1000) number The maximum number of sprites that the SpriteBatch can contain at any given time. Since version 11.0, additional sprites added past this number will automatically grow the spritebatch.
usage ('dynamic') SpriteBatchUsage The expected usage of the SpriteBatch. The specified usage mode affects the SpriteBatch's memory usage and performance.

spriteBatch = love.graphics.newSpriteBatch( texture, maxsprites, usage )

spriteBatch SpriteBatch The new SpriteBatch.
texture Texture The Image or Canvas to use for the sprites.
maxsprites (1000) number The maximum number of sprites that the SpriteBatch can contain at any given time. Since version 11.0, additional sprites added past this number will automatically grow the spritebatch.
usage ('dynamic') SpriteBatchUsage The expected usage of the SpriteBatch. The specified usage mode affects the SpriteBatch's memory usage and performance.

love.graphics.newText

Creates a new drawable Text object.

text = love.graphics.newText( font, textstring )

text Text The new drawable Text object.
font Font The font to use for the text.
textstring (nil) string The initial string of text that the new Text object will contain. May be nil.

love.graphics.newVolumeImage

Creates a new volume (3D) Image.

Volume images are 3D textures with width, height, and depth. They can't be rendered directly, they can only be used in Shader code (and sent to the shader via Shader:send).

To use a volume image in a Shader, it must be declared as a VolumeImage or sampler3D type (instead of Image or sampler2D). The Texel(VolumeImage image, vec3 texcoords) shader function must be used to get pixel colors from the volume image. The vec3 argument is a normalized texture coordinate with the z component representing the depth to sample at (ranging from 1).

Volume images are typically used as lookup tables in shaders for color grading, for example, because sampling using a texture coordinate that is partway in between two pixels can interpolate across all 3 dimensions in the volume image, resulting in a smooth gradient even when a small-sized volume image is used as the lookup table.

Array images are a much better choice than volume images for storing multiple different sprites in a single array image for directly drawing them.

image = love.graphics.newVolumeImage( layers, settings )

Creates a volume Image given multiple image files with matching dimensions.

Volume images are not supported on some older mobile devices. Use love.graphics.getTextureTypes to check at runtime.

image Image A volume Image object.
layers table A table containing filepaths to images (or File, FileData, ImageData, or CompressedImageData objects), in an array. A table of tables can also be given, where each sub-table represents a single mipmap level and contains all layers for that mipmap.
settings (nil) table Optional table of settings to configure the volume image, containing the following fields:
settings.mipmaps (false) boolean True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a compressed texture format.
settings.linear (false) boolean True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.

love.graphics.origin

Resets the current coordinate transformation.

This function is always used to reverse any previous calls to love.graphics.rotate, love.graphics.scale, love.graphics.shear or love.graphics.translate. It returns the current transformation state to its defaults.

love.graphics.origin()

love.graphics.points

Draws one or more points.

love.graphics.points( x, y, ... )

x number The position of the first point on the x-axis.
y number The position of the first point on the y-axis.
... number The x and y coordinates of additional points.

love.graphics.points( points )

points table A table containing multiple point positions, in the form of {x, y, ...}.
points.x number The position of the first point on the x-axis.
points.y number The position of the first point on the y-axis.
points.... number The x and y coordinates of additional points.

love.graphics.points( points )

Draws one or more individually colored points.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

The pixel grid is actually offset to the center of each pixel. So to get clean pixels drawn use 0.5 + integer increments.

Points are not affected by size is always in pixels.

points table A table containing multiple individually colored points, in the form of {point, ...}.
points.point table A table containing the position and color of the first point, in the form of {x, y, r, g, b, a}. The color components are optional.
points.... table Additional tables containing the position and color of more points, in the form of {x, y, r, g, b, a}. The color components are optional.

love.graphics.polygon

Draw a polygon.

Following the mode argument, this function can accept multiple numeric arguments or a single table of numeric arguments. In either case the arguments are interpreted as alternating x and y coordinates of the polygon's vertices.

love.graphics.polygon( mode, ... )

mode DrawMode How to draw the polygon.
... number The vertices of the polygon.

love.graphics.polygon( mode, vertices )

mode DrawMode How to draw the polygon.
vertices table The vertices of the polygon as a table.

love.graphics.pop

Pops the current coordinate transformation from the transformation stack.

This function is always used to reverse a previous push operation. It returns the current transformation state to what it was before the last preceding push.

love.graphics.pop()

love.graphics.present

Displays the results of drawing operations on the screen.

This function is used when writing your own love.run function. It presents all the results of your drawing operations on the screen. See the example in love.run for a typical use of this function.

love.graphics.present()

* If love.window.setMode has vsync equal to true, this function can't run more frequently than the refresh rate (e.g. 60 Hz), and will halt the program until ready if necessary.

love.graphics.print

Draws text on screen. If no Font is set, one will be created and set (once) if needed.

As of LOVE 0.7.1, when using translation and scaling functions while drawing text, this function assumes the scale occurs first. If you don't script with this in mind, the text won't be in the right position, or possibly even on screen.

love.graphics.print and love.graphics.printf both support UTF-8 encoding. You'll also need a proper Font for special characters.

In versions prior to 11.0, color and byte component values were within the range of 0 to 255 instead of 0 to 1.

love.graphics.print( text, x, y, r, sx, sy, ox, oy, kx, ky )

text string The text to draw.
x (0) number The position to draw the object (x-axis).
y (0) number The position to draw the object (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

love.graphics.print( coloredtext, x, y, angle, sx, sy, ox, oy, kx, ky )

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text.

coloredtext table A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1 string A string of text which has a color specified by the previous color.
coloredtext.color2 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2 string A string of text which has a color specified by the previous color.
coloredtext.... tables and strings Additional colors and strings.
x (0) number The position of the text on the x-axis.
y (0) number The position of the text on the y-axis.
angle (0) number The orientation of the text in radians.
sx (1) number Scale factor on the x-axis.
sy (sx) number Scale factor on the y-axis.
ox (0) number Origin offset on the x-axis.
oy (0) number Origin offset on the y-axis.
kx (0) number Shearing / skew factor on the x-axis.
ky (0) number Shearing / skew factor on the y-axis.

love.graphics.print( text, transform )

text string The text to draw.
transform Transform Transformation object.

love.graphics.print( coloredtext, transform )

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text.

coloredtext table A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1 string A string of text which has a color specified by the previous color.
coloredtext.color2 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2 string A string of text which has a color specified by the previous color.
coloredtext.... tables and strings Additional colors and strings.
transform Transform Transformation object.

love.graphics.print( text, font, transform )

text string The text to draw.
font Font The Font object to use.
transform Transform Transformation object.

love.graphics.print( coloredtext, font, transform )

coloredtext table A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1 string A string of text which has a color specified by the previous color.
coloredtext.color2 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2 string A string of text which has a color specified by the previous color.
coloredtext.... tables and strings Additional colors and strings.
font Font The Font object to use.
transform Transform Transformation object.

love.graphics.printf

Draws formatted text, with word wrap and alignment.

See additional notes in love.graphics.print.

The word wrap limit is applied before any scaling, rotation, and other coordinate transformations. Therefore the amount of text per line stays constant given the same wrap limit, even if the scale arguments change.

In version 0.9.2 and earlier, wrapping was implemented by breaking up words by spaces and putting them back together to make sure things fit nicely within the limit provided. However, due to the way this is done, extra spaces between words would end up missing when printed on the screen, and some lines could overflow past the provided wrap limit. In version 0.10.0 and newer this is no longer the case.

In versions prior to 11.0, color and byte component values were within the range of 0 to 255 instead of 0 to 1.

love.graphics.printf( text, x, y, limit, align, r, sx, sy, ox, oy, kx, ky )

text string A text string.
x number The position on the x-axis.
y number The position on the y-axis.
limit number Wrap the line after this many horizontal pixels.
align ('left') AlignMode The alignment.
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

love.graphics.printf( text, font, x, y, limit, align, r, sx, sy, ox, oy, kx, ky )

text string A text string.
font Font The Font object to use.
x number The position on the x-axis.
y number The position on the y-axis.
limit number Wrap the line after this many horizontal pixels.
align ('left') AlignMode The alignment.
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

love.graphics.printf( text, transform, limit, align )

text string A text string.
transform Transform Transformation object.
limit number Wrap the line after this many horizontal pixels.
align ('left') AlignMode The alignment.

love.graphics.printf( text, font, transform, limit, align )

text string A text string.
font Font The Font object to use.
transform Transform Transformation object.
limit number Wrap the line after this many horizontal pixels.
align ('left') AlignMode The alignment.

love.graphics.printf( coloredtext, x, y, limit, align, angle, sx, sy, ox, oy, kx, ky )

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text.

coloredtext table A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1 string A string of text which has a color specified by the previous color.
coloredtext.color2 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2 string A string of text which has a color specified by the previous color.
coloredtext.... tables and strings Additional colors and strings.
x number The position of the text (x-axis).
y number The position of the text (y-axis).
limit number The maximum width in pixels of the text before it gets automatically wrapped to a new line.
align AlignMode The alignment of the text.
angle (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing / skew factor (x-axis).
ky (0) number Shearing / skew factor (y-axis).

love.graphics.printf( coloredtext, font, x, y, limit, align, angle, sx, sy, ox, oy, kx, ky )

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text.

coloredtext table A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1 string A string of text which has a color specified by the previous color.
coloredtext.color2 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2 string A string of text which has a color specified by the previous color.
coloredtext.... tables and strings Additional colors and strings.
font Font The Font object to use.
x number The position on the x-axis.
y number The position on the y-axis.
limit number Wrap the line after this many horizontal pixels.
align ('left') AlignMode The alignment.
angle (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

love.graphics.printf( coloredtext, transform, limit, align )

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text.

coloredtext table A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1 string A string of text which has a color specified by the previous color.
coloredtext.color2 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2 string A string of text which has a color specified by the previous color.
coloredtext.... tables and strings Additional colors and strings.
transform Transform Transformation object.
limit number Wrap the line after this many horizontal pixels.
align ('left') AlignMode The alignment.

love.graphics.printf( coloredtext, font, transform, limit, align )

coloredtext table A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1 string A string of text which has a color specified by the previous color.
coloredtext.color2 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2 string A string of text which has a color specified by the previous color.
coloredtext.... tables and strings Additional colors and strings.
font Font The Font object to use.
transform Transform Transformation object.
limit number Wrap the line after this many horizontal pixels.
align ('left') AlignMode The alignment.

love.graphics.push

Copies and pushes the current coordinate transformation to the transformation stack.

This function is always used to prepare for a corresponding pop operation later. It stores the current coordinate transformation state into the transformation stack and keeps it active. Later changes to the transformation can be undone by using the pop operation, which returns the coordinate transform to the state it was in before calling push.

love.graphics.push()

Pushes the current transformation to the transformation stack.

love.graphics.push( stack )

Pushes a specific type of state to the stack.

stack StackType The type of stack to push (e.g. just transformation state, or all love.graphics state).

love.graphics.rectangle

Draws a rectangle.

love.graphics.rectangle( mode, x, y, width, height )

mode DrawMode How to draw the rectangle.
x number The position of top-left corner along the x-axis.
y number The position of top-left corner along the y-axis.
width number Width of the rectangle.
height number Height of the rectangle.

love.graphics.rectangle( mode, x, y, width, height, rx, ry, segments )

Draws a rectangle with rounded corners.

mode DrawMode How to draw the rectangle.
x number The position of top-left corner along the x-axis.
y number The position of top-left corner along the y-axis.
width number Width of the rectangle.
height number Height of the rectangle.
rx number The x-axis radius of each round corner. Cannot be greater than half the rectangle's width.
ry (rx) number The y-axis radius of each round corner. Cannot be greater than half the rectangle's height.
segments (nil) number The number of segments used for drawing the round corners. A default amount will be chosen if no number is given.

love.graphics.replaceTransform

Replaces the current coordinate transformation with the given Transform object.

love.graphics.replaceTransform( transform )

transform Transform The Transform object to replace the current graphics coordinate transform with.

love.graphics.reset

Resets the current graphics settings.

Calling reset makes the current drawing color white, the current background color black, disables any active color component masks, disables wireframe mode and resets the current graphics transformation to the origin. It also sets both the point and line drawing modes to smooth and their sizes to 1.0.

love.graphics.reset()

love.graphics.rotate

Rotates the coordinate system in two dimensions.

Calling this function affects all future drawing operations by rotating the coordinate system around the origin by the given amount of radians. This change lasts until love.draw() exits.

love.graphics.rotate( angle )

angle number The amount to rotate the coordinate system in radians.

love.graphics.scale

Scales the coordinate system in two dimensions.

By default the coordinate system in LÖVE corresponds to the display pixels in horizontal and vertical directions one-to-one, and the x-axis increases towards the right while the y-axis increases downwards. Scaling the coordinate system changes this relation.

After scaling by sx and sy, all coordinates are treated as if they were multiplied by sx and sy. Every result of a drawing operation is also correspondingly scaled, so scaling by (2, 2) for example would mean making everything twice as large in both x- and y-directions. Scaling by a negative value flips the coordinate system in the corresponding direction, which also means everything will be drawn flipped or upside down, or both. Scaling by zero is not a useful operation.

Scale and translate are not commutative operations, therefore, calling them in different orders will change the outcome.

Scaling lasts until love.draw() exits.

love.graphics.scale( sx, sy )

sx number The scaling in the direction of the x-axis.
sy (sx) number The scaling in the direction of the y-axis. If omitted, it defaults to same as parameter sx.

love.graphics.setBackgroundColor

Sets the background color.

love.graphics.setBackgroundColor( red, green, blue, alpha )

red number The red component (0-1).
green number The green component (0-1).
blue number The blue component (0-1).
alpha (1) number The alpha component (0-1).

love.graphics.setBackgroundColor()

love.graphics.setBackgroundColor()

love.graphics.setBlendMode

Sets the blending mode.

love.graphics.setBlendMode( mode )

mode BlendMode The blend mode to use.

love.graphics.setBlendMode( mode, alphamode )

The default 'alphamultiply' alpha mode should normally be preferred except when drawing content with pre-multiplied alpha. If content is drawn to a Canvas using the 'alphamultiply' mode, the Canvas texture will have pre-multiplied alpha afterwards, so the 'premultiplied' alpha mode should generally be used when drawing a Canvas to the screen.

mode BlendMode The blend mode to use.
alphamode ('alphamultiply') BlendAlphaMode What to do with the alpha of drawn objects when blending.

love.graphics.setCanvas

Captures drawing operations to a Canvas.

love.graphics.setCanvas( canvas, mipmap )

Sets the render target to a specified stencil or depth testing with an active Canvas, the stencil buffer or depth buffer must be explicitly enabled in setCanvas via the variants below.

Note that no canvas should be active when ''love.graphics.present'' is called. ''love.graphics.present'' is called at the end of love.draw in the default love.run, hence if you activate a canvas using this function, you normally need to deactivate it at some point before ''love.draw'' finishes.

canvas Canvas The new target.
mipmap (1) number The mipmap level to render to, for Canvases with mipmaps.

love.graphics.setCanvas()

Resets the render target to the screen, i.e. re-enables drawing to the screen.

love.graphics.setCanvas( canvas1, canvas2, ... )

Sets the render target to multiple simultaneous 2D Canvases. All drawing operations until the next ''love.graphics.setCanvas'' call will be redirected to the specified canvases and not shown on the screen.

Normally all drawing operations will draw only to the first canvas passed to the function, but that can be changed if a pixel shader is used with the void effect function instead of the regular vec4 effect.

All canvas arguments must have the same widths and heights and the same texture type. Not all computers which support Canvases will support multiple render targets. If love.graphics.isSupported('multicanvas') returns true, at least 4 simultaneously active canvases are supported.

canvas1 Canvas The first render target.
canvas2 Canvas The second render target.
... Canvas More canvases.

love.graphics.setCanvas( canvas, slice, mipmap )

Sets the render target to the specified layer/slice and mipmap level of the given non-2D Canvas. All drawing operations until the next ''love.graphics.setCanvas'' call will be redirected to the Canvas and not shown on the screen.

canvas Canvas The new render target.
slice number For cubemaps this is the cube face index to render to (between 1 and 6). For Array textures this is the array layer. For volume textures this is the depth slice. 2D canvases should use a value of 1.
mipmap (1) number The mipmap level to render to, for Canvases with mipmaps.

love.graphics.setCanvas( setup )

Sets the active render target(s) and active stencil and depth buffers based on the specified setup information. All drawing operations until the next ''love.graphics.setCanvas'' call will be redirected to the specified Canvases and not shown on the screen.

The RenderTargetSetup parameters can either be a Canvas|[1]|The Canvas to use for this active render target.}}

{{param|number|mipmap (1)|The mipmap level to render to, for Canvases with [[Texture:getMipmapCount|mipmaps.}}

{{param|number|layer (1)|Only used for Volume and Array-type Canvases. For Array textures this is the array layer to render to. For volume textures this is the depth slice.}}

{{param|number|face (1)|Only used for Cubemap-type Canvases. The cube face index to render to (between 1 and 6)}}

setup table A table specifying the active Canvas(es), their mipmap levels and active layers if applicable, and whether to use a stencil and/or depth buffer.
setup[1] RenderTargetSetup The Canvas to render to.
setup[2] (nil) RenderTargetSetup An additional Canvas to render to, if multiple simultaneous render targets are wanted.
setup.... RenderTargetSetup Additional Canvases to render to, if multiple simultaneous render targets are wanted.
setup.stencil (false) boolean Whether an internally managed stencil buffer should be used, if the depthstencil field isn't set.
setup.depth (false) boolean Whether an internally managed depth buffer should be used, if the depthstencil field isn't set.
setup.depthstencil (nil) RenderTargetSetup An optional custom depth/stencil formatted Canvas to use for the depth and/or stencil buffer.

love.graphics.setColor

Sets the color used for drawing.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

love.graphics.setColor( red, green, blue, alpha )

red number The amount of red.
green number The amount of green.
blue number The amount of blue.
alpha (1) number The amount of alpha. The alpha value will be applied to all subsequent draw operations, even the drawing of an image.

love.graphics.setColor( rgba )

rgba table A numerical indexed table with the red, green, blue and alpha values as numbers. The alpha is optional and defaults to 1 if it is left out.

love.graphics.setColorMask

Sets the color mask. Enables or disables specific color components when rendering and clearing the screen. For example, if '''red''' is set to '''false''', no further changes will be made to the red component of any pixels.

love.graphics.setColorMask( red, green, blue, alpha )

Enables color masking for the specified color components.

red boolean Render red component.
green boolean Render green component.
blue boolean Render blue component.
alpha boolean Render alpha component.

love.graphics.setColorMask()

Disables color masking.

love.graphics.setDefaultFilter

Sets the default scaling filters used with Images, Canvases, and Fonts.

love.graphics.setDefaultFilter( min, mag, anisotropy )

This function does not apply retroactively to loaded images.

min FilterMode Filter mode used when scaling the image down.
mag FilterMode Filter mode used when scaling the image up.
anisotropy (1) number Maximum amount of Anisotropic Filtering used.

love.graphics.setDepthMode

Configures depth testing and writing to the depth buffer.

This is low-level functionality designed for use with custom vertex shaders and Meshes with custom vertex attributes. No higher level APIs are provided to set the depth of 2D graphics such as shapes, lines, and Images.

love.graphics.setDepthMode( comparemode, write )

comparemode CompareMode Depth comparison mode used for depth testing.
write boolean Whether to write update / write values to the depth buffer when rendering.

love.graphics.setDepthMode()

Disables depth testing and depth writes.

love.graphics.setFont

Set an already-loaded Font as the current font or create and load a new one from the file and size.

It's recommended that Font objects are created with love.graphics.newFont in the loading stage and then passed to this function in the drawing stage.

love.graphics.setFont( font )

font Font The Font object to use.

love.graphics.setFrontFaceWinding

Sets whether triangles with clockwise- or counterclockwise-ordered vertices are considered front-facing.

This is designed for use in combination with Mesh face culling. Other love.graphics shapes, lines, and sprites are not guaranteed to have a specific winding order to their internal vertices.

love.graphics.setFrontFaceWinding( winding )

winding VertexWinding The winding mode to use. The default winding is counterclockwise ('ccw').

love.graphics.setLineJoin

Sets the line join style. See LineJoin for the possible options.

love.graphics.setLineJoin( join )

join LineJoin The LineJoin to use.

love.graphics.setLineStyle

Sets the line style.

love.graphics.setLineStyle( style )

style LineStyle The LineStyle to use. Line styles include smooth and rough.

love.graphics.setLineWidth

Sets the line width.

love.graphics.setLineWidth( width )

width number The width of the line.

love.graphics.setMeshCullMode

Sets whether back-facing triangles in a Mesh are culled.

This is designed for use with low level custom hardware-accelerated 3D rendering via custom vertex attributes on Meshes, custom vertex shaders, and depth testing with a depth buffer.

By default, both front- and back-facing triangles in Meshes are rendered.

love.graphics.setMeshCullMode( mode )

mode CullMode The Mesh face culling mode to use (whether to render everything, cull back-facing triangles, or cull front-facing triangles).

love.graphics.setPointSize

Sets the point size.

love.graphics.setPointSize( size )

size number The new point size.

love.graphics.setScissor

Sets or disables scissor.

The scissor limits the drawing area to a specified rectangle. This affects all graphics calls, including love.graphics.clear.

The dimensions of the scissor is unaffected by graphical transformations (translate, scale, ...).

love.graphics.setScissor( x, y, width, height )

Limits the drawing area to a specified rectangle.

x number x coordinate of upper left corner.
y number y coordinate of upper left corner.
width number width of clipping rectangle.
height number height of clipping rectangle.

love.graphics.setScissor()

Disables scissor.

love.graphics.setShader

Sets or resets a Shader as the current pixel effect or vertex shaders. All drawing operations until the next ''love.graphics.setShader'' will be drawn using the Shader object specified.

love.graphics.setShader( shader )

Sets the current shader to a specified Shader. All drawing operations until the next ''love.graphics.setShader'' will be drawn using the Shader object specified.

shader Shader The new shader.

love.graphics.setShader()

Disables shaders, allowing unfiltered drawing operations.

love.graphics.setStencilTest

Configures or disables stencil testing.

When stencil testing is enabled, the geometry of everything that is drawn afterward will be clipped / stencilled out based on a comparison between the arguments of this function and the stencil value of each pixel that the geometry touches. The stencil values of pixels are affected via love.graphics.stencil.

love.graphics.setStencilTest( comparemode, comparevalue )

comparemode CompareMode The type of comparison to make for each pixel.
comparevalue number The value to use when comparing with the stencil value of each pixel. Must be between 0 and 255.

love.graphics.setStencilTest()

Disables stencil testing.

love.graphics.setWireframe

Sets whether wireframe lines will be used when drawing.

love.graphics.setWireframe( enable )

enable boolean True to enable wireframe mode when drawing, false to disable it.

love.graphics.shear

Shears the coordinate system.

love.graphics.shear( kx, ky )

kx number The shear factor on the x-axis.
ky number The shear factor on the y-axis.

love.graphics.stencil

Draws geometry as a stencil.

The geometry drawn by the supplied function sets invisible stencil values of pixels, instead of setting pixel colors. The stencil buffer (which contains those stencil values) can act like a mask / stencil - love.graphics.setStencilTest can be used afterward to determine how further rendering is affected by the stencil values in each pixel.

Stencil values are integers within the range of 255.

love.graphics.stencil( stencilfunction, action, value, keepvalues )

It is possible to draw to the screen and to the stencil values of pixels at the same time, by using love.graphics.setColorMask inside the stencil function to enable drawing to all color components.

stencilfunction function Function which draws geometry. The stencil values of pixels, rather than the color of each pixel, will be affected by the geometry.
action ('replace') StencilAction How to modify any stencil values of pixels that are touched by what's drawn in the stencil function.
value (1) number The new stencil value to use for pixels if the 'replace' stencil action is used. Has no effect with other stencil actions. Must be between 0 and 255.
keepvalues (false) boolean True to preserve old stencil values of pixels, false to re-set every pixel's stencil value to 0 before executing the stencil function. love.graphics.clear will also re-set all stencil values.

love.graphics.transformPoint

Converts the given 2D position from global coordinates into screen-space.

This effectively applies the current graphics transformations to the given position. A similar Transform:transformPoint method exists for Transform objects.

screenX, screenY = love.graphics.transformPoint( globalX, globalY )

screenX number The x component of the position with graphics transformations applied.
screenY number The y component of the position with graphics transformations applied.
globalX number The x component of the position in global coordinates.
globalY number The y component of the position in global coordinates.

love.graphics.translate

Translates the coordinate system in two dimensions.

When this function is called with two numbers, dx, and dy, all the following drawing operations take effect as if their x and y coordinates were x+dx and y+dy.

Scale and translate are not commutative operations, therefore, calling them in different orders will change the outcome.

This change lasts until love.draw() exits or else a love.graphics.pop reverts to a previous love.graphics.push.

Translating using whole numbers will prevent tearing/blurring of images and fonts draw after translating.

love.graphics.translate( dx, dy )

dx number The translation relative to the x-axis.
dy number The translation relative to the y-axis.

love.graphics.validateShader

Validates shader code. Check if specified shader code does not contain any errors.

status, message = love.graphics.validateShader( gles, code )

status boolean true if specified shader code doesn't contain any errors. false otherwise.
message string Reason why shader code validation failed (or nil if validation succeded).
gles boolean Validate code as GLSL ES shader.
code string The pixel shader or vertex shader code, or a filename pointing to a file with the code.

status, message = love.graphics.validateShader( gles, pixelcode, vertexcode )

status boolean true if specified shader code doesn't contain any errors. false otherwise.
message string Reason why shader code validation failed (or nil if validation succeded).
gles boolean Validate code as GLSL ES shader.
pixelcode string The pixel shader code, or a filename pointing to a file with the code.
vertexcode string The vertex shader code, or a filename pointing to a file with the code.

AlignMode

center

Align text center.

left

Align text left.

right

Align text right.

justify

Align text both left and right.

ArcType

pie

The arc is drawn like a slice of pie, with the arc circle connected to the center at its end-points.

open

The arc circle's two end-points are unconnected when the arc is drawn as a line. Behaves like the "closed" arc type when the arc is drawn in filled mode.

closed

The arc circle's two end-points are connected to each other.

AreaSpreadDistribution

uniform

Uniform distribution.

normal

Normal (gaussian) distribution.

ellipse

Uniform distribution in an ellipse.

borderellipse

Distribution in an ellipse with particles spawning at the edges of the ellipse.

borderrectangle

Distribution in a rectangle with particles spawning at the edges of the rectangle.

none

No distribution - area spread is disabled.

BlendAlphaMode

alphamultiply

The RGB values of what's drawn are multiplied by the alpha values of those colors during blending. This is the default alpha mode.

premultiplied

The RGB values of what's drawn are '''not''' multiplied by the alpha values of those colors during blending. For most blend modes to work correctly with this alpha mode, the colors of a drawn object need to have had their RGB values multiplied by their alpha values at some point previously ("premultiplied alpha").

BlendMode

alpha

Alpha blending (normal). The alpha of what's drawn determines its opacity.

replace

The colors of what's drawn completely replace what was on the screen, with no additional blending. The BlendAlphaMode specified in love.graphics.setBlendMode still affects what happens.

screen

'Screen' blending.

add

The pixel colors of what's drawn are added to the pixel colors already on the screen. The alpha of the screen is not modified.

subtract

The pixel colors of what's drawn are subtracted from the pixel colors already on the screen. The alpha of the screen is not modified.

multiply

The pixel colors of what's drawn are multiplied with the pixel colors already on the screen (darkening them). The alpha of drawn objects is multiplied with the alpha of the screen rather than determining how much the colors on the screen are affected, even when the "alphamultiply" BlendAlphaMode is used.

lighten

The pixel colors of what's drawn are compared to the existing pixel colors, and the larger of the two values for each color component is used. Only works when the "premultiplied" BlendAlphaMode is used in love.graphics.setBlendMode.

darken

The pixel colors of what's drawn are compared to the existing pixel colors, and the smaller of the two values for each color component is used. Only works when the "premultiplied" BlendAlphaMode is used in love.graphics.setBlendMode.

additive

Additive blend mode.

subtractive

Subtractive blend mode.

multiplicative

Multiply blend mode.

premultiplied

Premultiplied alpha blend mode.

CanvasMipmapMode

none

Do not enable mipmap.

auto

Automatically generate mipmap.

manual

Let user manually generate mipmap.

CompareMode

never

Objects will never be drawn.

always

Objects will always be drawn. Effectively disables the depth or stencil test.

CullMode

back

Back-facing triangles in Meshes are culled (not rendered). The vertex order of a triangle determines whether it is back- or front-facing.

front

Front-facing triangles in Meshes are culled.

none

Both back- and front-facing triangles in Meshes are rendered.

DrawMode

fill

Draw filled shape.

line

Draw outlined shape.

FilterMode

linear

Scale image with linear interpolation.

nearest

Scale image with nearest neighbor interpolation.

GraphicsFeature

clampzero

Whether the "clampzero" WrapMode is supported.

lighten

Whether the "lighten" and "darken" BlendModes are supported.

multicanvasformats

Whether multiple formats can be used in the same love.graphics.setCanvas call.

glsl3

Whether GLSL 3 Shaders can be used.

instancing

Whether mesh instancing is supported.

fullnpot

Whether textures with non-power-of-two dimensions can use mipmapping and the 'repeat' WrapMode.

pixelshaderhighp

Whether pixel shaders can use "highp" 32 bit floating point numbers (as opposed to just 16 bit or lower precision).

shaderderivatives

Whether shaders can use the dFdx, dFdy, and fwidth functions for computing derivatives.

canvas

Support for Canvas.

npot

Support for textures with non-power-of-two sizes. See PO2 Syndrome.

subtractive

Support for the subtractive blend mode.

shader

Support for Shaders.

hdrcanvas

Support for HDR Canvases. Use love.graphics.getCanvasFormats instead.

multicanvas

Support for simultaneous rendering to at least 4 canvases at once, with love.graphics.setCanvas. Use love.graphics.getSystemLimits instead.

mipmap

Support for Mipmaps.

dxt

Support for DXT compressed images (see CompressedFormat.) Use love.graphics.getCompressedImageFormats instead.

bc5

Support for BC4 and BC5 compressed images. Use love.graphics.getCompressedImageFormats instead.

srgb

Support for gamma-correct rendering with the srgb window flag in Canvases and Images.

pixeleffect

Support for PixelEffects.

GraphicsLimit

pointsize

The maximum size of points.

texturesize

The maximum width or height of Images and Canvases.

multicanvas

The maximum number of simultaneously active canvases (via love.graphics.setCanvas.)

canvasmsaa

The maximum number of antialiasing samples for a Canvas.

texturelayers

The maximum number of layers in an Array texture.

volumetexturesize

The maximum width, height, or depth of a Volume texture.

cubetexturesize

The maximum width or height of a Cubemap texture.

anisotropy

The maximum amount of anisotropic filtering. Texture:setMipmapFilter internally clamps the given anisotropy value to the system's limit.

canvasfsaa

The maximum number of antialiasing samples for a Canvas.

LineJoin

miter

The ends of the line segments beveled in an angle so that they join seamlessly.

none

No cap applied to the ends of the line segments.

bevel

Flattens the point where line segments join together.

LineStyle

rough

Draw rough lines.

smooth

Draw smooth lines.

MeshDrawMode

fan

The vertices create a "fan" shape with the first vertex acting as the hub point. Can be easily used to draw simple convex polygons.

strip

The vertices create a series of connected triangles using vertices 1, 2, 3, then 3, 2, 4 (note the order), then 3, 4, 5, and so on.

triangles

The vertices create unconnected triangles.

points

The vertices are drawn as unconnected points (see love.graphics.setPointSize.)

ParticleInsertMode

top

Particles are inserted at the top of the ParticleSystem's list of particles.

bottom

Particles are inserted at the bottom of the ParticleSystem's list of particles.

random

Particles are inserted at random positions in the ParticleSystem's list of particles.

SpriteBatchUsage

dynamic

The object's data will change occasionally during its lifetime.

static

The object will not be modified after initial sprites or vertices are added.

stream

The object data will always change between draws.

StackType

transform

The transformation stack (love.graphics.translate, love.graphics.rotate, etc.)

all

All love.graphics state, including transform state.

StencilAction

replace

The stencil value of a pixel will be replaced by the value specified in love.graphics.stencil, if any object touches the pixel.

increment

The stencil value of a pixel will be incremented by 1 for each object that touches the pixel. If the stencil value reaches 255 it will stay at 255.

decrement

The stencil value of a pixel will be decremented by 1 for each object that touches the pixel. If the stencil value reaches 0 it will stay at 0.

incrementwrap

The stencil value of a pixel will be incremented by 1 for each object that touches the pixel. If a stencil value of 255 is incremented it will be set to 0.

decrementwrap

The stencil value of a pixel will be decremented by 1 for each object that touches the pixel. If the stencil value of 0 is decremented it will be set to 255.

invert

The stencil value of a pixel will be bitwise-inverted for each object that touches the pixel. If a stencil value of 0 is inverted it will become 255.

TextureType

2d

Regular 2D texture with width and height.

array

Several same-size 2D textures organized into a single object. Similar to a texture atlas / sprite sheet, but avoids sprite bleeding and other issues.

cube

Cubemap texture with 6 faces. Requires a custom shader (and Shader:send) to use. Sampling from a cube texture in a shader takes a 3D direction vector instead of a texture coordinate.

volume

3D texture with width, height, and depth. Requires a custom shader to use. Volume textures can have texture filtering applied along the 3rd axis.

WrapMode

clamp

Clamp the texture. Appears only once. The area outside the texture's normal range is colored based on the edge pixels of the texture.

repeat

Repeat the texture. Fills the whole available extent.

mirroredrepeat

Repeat the texture, flipping it each time it repeats. May produce better visual results than the repeat mode when the texture doesn't seamlessly tile.

clampzero

Clamp the texture. Fills the area outside the texture's normal range with transparent black (or opaque black for textures with no alpha channel.)

Canvas

A Canvas is used for off-screen rendering. Think of it as an invisible screen that you can draw to, but that will not be visible until you draw it to the actual visible screen. It is also known as "render to texture".

By drawing things that do not change position often (such as background items) to the Canvas, and then drawing the entire Canvas instead of each item, you can reduce the number of draw operations performed each frame.

In versions prior to love.graphics.isSupported("canvas") could be used to check for support at runtime.

Functions

Dimensions

Supertypes

Canvas:generateMipmaps

Generates mipmaps for the Canvas, based on the contents of the highest-resolution mipmap level.

The Canvas must be created with mipmaps set to a MipmapMode other than 'none' for this function to work. It should only be called while the Canvas is not the active render target.

If the mipmap mode is set to 'auto', this function is automatically called inside love.graphics.setCanvas when switching from this Canvas to another Canvas or to the main screen.

Canvas:generateMipmaps()

Canvas:getDimensions

Gets the width and height of the Canvas.

width, height = Canvas:getDimensions()

width number The width of the Canvas, in pixels.
height number The height of the Canvas, in pixels.

Canvas:getFilter

Gets the filter mode of the Canvas.

min, mag = Canvas:getFilter()

min FilterMode Filter mode used when minifying the canvas.
mag FilterMode Filter mode used when magnifying the canvas.

min, mag, anisotropy = Canvas:getFilter()

min FilterMode Filter mode used when minifying the canvas.
mag FilterMode Filter mode used when magnifying the canvas.
anisotropy number Maximum amount of anisotropic filtering used.

Canvas:getHeight

Gets the height of the Canvas.

height = Canvas:getHeight()

height number The height of the Canvas, in pixels.

Canvas:getMSAA

Gets the number of multisample antialiasing (MSAA) samples used when drawing to the Canvas.

This may be different than the number used as an argument to love.graphics.newCanvas if the system running LÖVE doesn't support that number.

samples = Canvas:getMSAA()

samples number The number of multisample antialiasing samples used by the canvas when drawing to it.

Canvas:getMipmapMode

Gets the MipmapMode this Canvas was created with.

mode = Canvas:getMipmapMode()

mode MipmapMode The mipmap mode this Canvas was created with.

Canvas:getWidth

Gets the width of the Canvas.

width = Canvas:getWidth()

width number The width of the Canvas, in pixels.

Canvas:getWrap

Gets the wrapping properties of a Canvas.

This function returns the currently set horizontal and vertical wrapping modes for the Canvas.

horiz, vert = Canvas:getWrap()

horiz WrapMode Horizontal wrapping mode of the Canvas.
vert WrapMode Vertical wrapping mode of the Canvas.

Canvas:newImageData

Generates ImageData from the contents of the Canvas.

data = Canvas:newImageData()

data ImageData The new ImageData made from the Canvas' contents.

data = Canvas:newImageData( slice, mipmap, x, y, width, height )

data ImageData The new ImageData made from the Canvas' contents.
slice number The cubemap face index, array index, or depth layer for cubemap, array, or volume type Canvases, respectively. This argument is ignored for regular 2D canvases.
mipmap (1) number The mipmap index to use, for Canvases with mipmaps.
x number The x-axis of the top-left corner (in pixels) of the area within the Canvas to capture.
y number The y-axis of the top-left corner (in pixels) of the area within the Canvas to capture.
width number The width in pixels of the area within the Canvas to capture.
height number The height in pixels of the area within the Canvas to capture.

Canvas:renderTo

Render to the Canvas using a function.

This is a shortcut to love.graphics.setCanvas:

canvas:renderTo( func )

is the same as

love.graphics.setCanvas( canvas )

func()

love.graphics.setCanvas()

Canvas:renderTo( func )

func function A function performing drawing operations.

Canvas:setFilter

Sets the filter mode of the Canvas.

Canvas:setFilter( min, mag )

min FilterMode Filter mode to use when minifying the canvas.
mag FilterMode Filter mode to use when magnifying the canvas.

Canvas:setFilter( min, mag, anisotropy )

min FilterMode Filter mode to use when minifying the canvas.
mag FilterMode Filter mode to use when magnifying the canvas.
anisotropy (1) number Maximum amount of anisotropic filtering to use.

Canvas:setWrap

Sets the wrapping properties of a Canvas.

This function sets the way the edges of a Canvas are treated if it is scaled or rotated. If the WrapMode is set to 'clamp', the edge will not be interpolated. If set to 'repeat', the edge will be interpolated with the pixels on the opposing side of the framebuffer.

Canvas:setWrap( horiz, vert )

horiz WrapMode Horizontal wrapping mode of the Canvas.
vert WrapMode Vertical wrapping mode of the Canvas.

Font

Defines the shape of characters that can be drawn onto the screen.

Functions

Glyph support

Info

Supertypes

Font:getAscent

Gets the ascent of the Font.

The ascent spans the distance between the baseline and the top of the glyph that reaches farthest from the baseline.

ascent = Font:getAscent()

ascent number The ascent of the Font in pixels.

Font:getBaseline

Gets the baseline of the Font.

Most scripts share the notion of a baseline: an imaginary horizontal line on which characters rest. In some scripts, parts of glyphs lie below the baseline.

baseline = Font:getBaseline()

baseline number The baseline of the Font in pixels.

Font:getDPIScale

Gets the DPI scale factor of the Font.

The DPI scale factor represents relative pixel density. A DPI scale factor of 2 means the font's glyphs have twice the pixel density in each dimension (4 times as many pixels in the same area) compared to a font with a DPI scale factor of 1.

The font size of TrueType fonts is scaled internally by the font's specified DPI scale factor. By default, LÖVE uses the screen's DPI scale factor when creating TrueType fonts.

dpiscale = Font:getDPIScale()

dpiscale number The DPI scale factor of the Font.

Font:getDescent

Gets the descent of the Font.

The descent spans the distance between the baseline and the lowest descending glyph in a typeface.

descent = Font:getDescent()

descent number The descent of the Font in pixels.

Font:getFilter

Gets the filter mode for a font.

min, mag, anisotropy = Font:getFilter()

min FilterMode Filter mode used when minifying the font.
mag FilterMode Filter mode used when magnifying the font.
anisotropy number Maximum amount of anisotropic filtering used.

Font:getHeight

Gets the height of the Font.

The height of the font is the size including any spacing; the height which it will need.

height = Font:getHeight()

height number The height of the Font in pixels.

Font:getLineHeight

Gets the line height.

This will be the value previously set by Font:setLineHeight, or 1.0 by default.

height = Font:getLineHeight()

height number The current line height.

Font:getWidth

Determines the maximum width (accounting for newlines) taken by the given string.

width = Font:getWidth( text )

width number The width of the text.
text string A string.

Font:getWrap

Gets formatting information for text, given a wrap limit.

This function accounts for newlines correctly (i.e. '\n').

width, wrappedtext = Font:getWrap( text, wraplimit )

width number The maximum width of the wrapped text.
wrappedtext table A sequence containing each line of text that was wrapped.
text string The text that will be wrapped.
wraplimit number The maximum width in pixels of each line that ''text'' is allowed before wrapping.

Font:hasGlyphs

Gets whether the Font can render a character or string.

hasglyph = Font:hasGlyphs( text )

hasglyph boolean Whether the font can render all the UTF-8 characters in the string.
text string A UTF-8 encoded unicode string.

hasglyph = Font:hasGlyphs( character1, character2 )

hasglyph boolean Whether the font can render all the glyphs represented by the characters.
character1 string A unicode character.
character2 string Another unicode character.

hasglyph = Font:hasGlyphs( codepoint1, codepoint2 )

hasglyph boolean Whether the font can render all the glyphs represented by the codepoint numbers.
codepoint1 number A unicode codepoint number.
codepoint2 number Another unicode codepoint number.

Font:setFallbacks

Sets the fallback fonts. When the Font doesn't contain a glyph, it will substitute the glyph from the next subsequent fallback Fonts. This is akin to setting a 'font stack' in Cascading Style Sheets (CSS).

Font:setFallbacks( fallbackfont1, ... )

If this is called it should be before love.graphics.print, Font:getWrap, and other Font methods which use glyph positioning information are called.

Every fallback Font must be created from the same file type as the primary Font. For example, a Font created from a .ttf file can only use fallback Fonts that were created from .ttf files.

fallbackfont1 Font The first fallback Font to use.
... Font Additional fallback Fonts.

Font:setFilter

Sets the filter mode for a font.

Font:setFilter( min, mag, anisotropy )

min FilterMode How to scale a font down.
mag FilterMode How to scale a font up.
anisotropy (1) number Maximum amount of anisotropic filtering used.

Font:setLineHeight

Sets the line height.

When rendering the font in lines the actual height will be determined by the line height multiplied by the height of the font. The default is 1.0.

Font:setLineHeight( height )

height number The new line height.

Image

Drawable image type.

Functions

Dimensions

Supertypes

Image:getDimensions

Gets the width and height of the Image.

width, height = Image:getDimensions()

width number The width of the Image, in pixels.
height number The height of the Image, in pixels.

Image:getFilter

Gets the filter mode for an image.

min, mag = Image:getFilter()

min FilterMode Filter mode used when minifying the image.
mag FilterMode Filter mode used when magnifying the image.

min, mag, anisotropy = Image:getFilter()

min FilterMode Filter mode used when minifying the image.
mag FilterMode Filter mode used when magnifying the image.
anisotropy number Maximum amount of anisotropic filtering used.

Image:getFlags

Gets the flags used when the image was created.

flags = Image:getFlags()

flags table A table with ImageFlag keys.

Image:getHeight

Gets the height of the Image.

height = Image:getHeight()

height number The height of the Image, in pixels.

Image:getWidth

Gets the width of the Image.

width = Image:getWidth()

width number The width of the Image, in pixels.

Image:getWrap

Gets the wrapping properties of an Image.

This function returns the currently set horizontal and vertical wrapping modes for the image.

horiz, vert = Image:getWrap()

horiz WrapMode Horizontal wrapping mode of the image.
vert WrapMode Vertical wrapping mode of the image.

Image:replacePixels

Replace the contents of an Image.

Image:replacePixels( data, slice, mipmap, x, y, reloadmipmaps )

data ImageData The new ImageData to replace the contents with.
slice number Which cubemap face, array index, or volume layer to replace, if applicable.
mipmap (1) number The mimap level to replace, if the Image has mipmaps.
x (0) number The x-offset in pixels from the top-left of the image to replace. The given ImageData's width plus this value must not be greater than the pixel width of the Image's specified mipmap level.
y (0) number The y-offset in pixels from the top-left of the image to replace. The given ImageData's height plus this value must not be greater than the pixel height of the Image's specified mipmap level.
reloadmipmaps boolean Whether to generate new mipmaps after replacing the Image's pixels. True by default if the Image was created with automatically generated mipmaps, false by default otherwise.

Image:setFilter

Sets the filter mode for an image.

Image:setFilter( min, mag )

min FilterMode How to scale an image down.
mag FilterMode How to scale an image up.

Image:setFilter( min, mag, anisotropy )

min FilterMode How to scale an image down.
mag FilterMode How to scale an image up.
anisotropy (1) number Maximum amount of anisotropic filtering used.

Image:setWrap

Sets the wrapping properties of an Image.

This function sets the way an Image is repeated when it is drawn with a Quad that is larger than the image's extent. An image may be clamped or set to repeat in both horizontal and vertical directions. Clamped images appear only once, but repeated ones repeat as many times as there is room in the Quad.

N.B. If you use a Quad that is larger than the image extent and do not use repeated tiling, there may be an unwanted visual effect of the image stretching all the way to fill the Quad. If this is the case, setting Image:setWrap('repeat', 'repeat') for all the images to be repeated, and using Quads of appropriate size will result in the best visual appearance.

Image:setWrap( horiz, vert )

horiz WrapMode Horizontal wrapping mode of the image.
vert WrapMode Vertical wrapping mode of the image.

Mesh

A 2D polygon mesh used for drawing arbitrary textured shapes.

Functions

Supertypes

Mesh:attachAttribute

Attaches a vertex attribute from a different Mesh onto this Mesh, for use when drawing. This can be used to share vertex attribute data between several different Meshes.

Mesh:attachAttribute( name, mesh )

name string The name of the vertex attribute to attach.
mesh Mesh The Mesh to get the vertex attribute from.

Mesh:attachAttribute( name, mesh, step, attachname )

If a Mesh wasn't created with a custom vertex format, it will have 3 vertex attributes named VertexPosition, VertexTexCoord, and VertexColor.

Custom named attributes can be accessed in a vertex shader by declaring them as attribute vec4 MyCustomAttributeName; at the top-level of the vertex shader code. The name must match what was specified in the Mesh's vertex format and in the name argument of Mesh:attachAttribute.

name string The name of the vertex attribute to attach.
mesh Mesh The Mesh to get the vertex attribute from.
step ('pervertex') VertexAttributeStep Whether the attribute will be per-vertex or per-instance when the mesh is drawn.
attachname (name) string The name of the attribute to use in shader code. Defaults to the name of the attribute in the given mesh. Can be used to use a different name for this attribute when rendering.

Mesh:attachAttribute

Attaches a vertex attribute from a different Mesh onto this Mesh, for use when drawing. This can be used to share vertex attribute data between several different Meshes.

Mesh:attachAttribute( name, mesh )

name string The name of the vertex attribute to attach.
mesh Mesh The Mesh to get the vertex attribute from.

Mesh:attachAttribute( name, mesh, step, attachname )

If a Mesh wasn't created with a custom vertex format, it will have 3 vertex attributes named VertexPosition, VertexTexCoord, and VertexColor.

Custom named attributes can be accessed in a vertex shader by declaring them as attribute vec4 MyCustomAttributeName; at the top-level of the vertex shader code. The name must match what was specified in the Mesh's vertex format and in the name argument of Mesh:attachAttribute.

name string The name of the vertex attribute to attach.
mesh Mesh The Mesh to get the vertex attribute from.
step ('pervertex') VertexAttributeStep Whether the attribute will be per-vertex or per-instance when the mesh is drawn.
attachname (name) string The name of the attribute to use in shader code. Defaults to the name of the attribute in the given mesh. Can be used to use a different name for this attribute when rendering.

Mesh:detachAttribute

Removes a previously attached vertex attribute from this Mesh.

success = Mesh:detachAttribute( name )

success boolean Whether the attribute was successfully detached.
name string The name of the attached vertex attribute to detach.

Mesh:getDrawMode

Gets the mode used when drawing the Mesh.

mode = Mesh:getDrawMode()

mode MeshDrawMode The mode used when drawing the Mesh.

Mesh:getDrawRange

Gets the range of vertices used when drawing the Mesh.

min, max = Mesh:getDrawRange()

If the Mesh's draw range has not been set previously with Mesh:setDrawRange, this function will return nil.

min number The index of the first vertex used when drawing, or the index of the first value in the vertex map used if one is set for this Mesh.
max number The index of the last vertex used when drawing, or the index of the last value in the vertex map used if one is set for this Mesh.

Mesh:getTexture

Gets the texture (Image or Canvas) used when drawing the Mesh.

texture = Mesh:getTexture()

texture Texture The Image or Canvas to texture the Mesh with when drawing, or nil if none is set.

Mesh:getVertex

Gets the properties of a vertex in the Mesh.

In versions prior to 11.0, color and byte component values were within the range of 0 to 255 instead of 0 to 1.

attributecomponent, ... = Mesh:getVertex( index )

The values are returned in the same order as the vertex attributes in the Mesh's vertex format. A standard Mesh that wasn't created with a custom vertex format will return two position numbers, two texture coordinate numbers, and four color components: x, y, u, v, r, g, b, a.

attributecomponent number The first component of the first vertex attribute in the specified vertex.
... number Additional components of all vertex attributes in the specified vertex.
index number The one-based index of the vertex you want to retrieve the information for.

x, y, u, v, r, g, b, a = Mesh:getVertex( index )

Gets the vertex components of a Mesh that wasn't created with a custom vertex format.

x number The position of the vertex on the x-axis.
y number The position of the vertex on the y-axis.
u number The horizontal component of the texture coordinate.
v number The vertical component of the texture coordinate.
r number The red component of the vertex's color.
g number The green component of the vertex's color.
b number The blue component of the vertex's color.
a number The alpha component of the vertex's color.
index number The index of the vertex you want to retrieve the information for.

Mesh:getVertexAttribute

Gets the properties of a specific attribute within a vertex in the Mesh.

Meshes without a custom vertex format specified in love.graphics.newMesh have position as their first attribute, texture coordinates as their second attribute, and color as their third attribute.

value1, value2, ... = Mesh:getVertexAttribute( vertexindex, attributeindex )

value1 number The value of the first component of the attribute.
value2 number The value of the second component of the attribute.
... number Any additional vertex attribute components.
vertexindex number The index of the the vertex you want to retrieve the attribute for (one-based).
attributeindex number The index of the attribute within the vertex to be retrieved (one-based).

Mesh:getVertexCount

Gets the total number of vertices in the Mesh.

count = Mesh:getVertexCount()

count number The total number of vertices in the mesh.

Mesh:getVertexFormat

Gets the vertex format that the Mesh was created with.

format = Mesh:getVertexFormat()

If a Mesh wasn't created with a custom vertex format, it will have the following vertex format:

defaultformat = {

{'VertexPosition', 'float', 2}, -- The x,y position of each vertex.

{'VertexTexCoord', 'float', 2}, -- The u,v texture coordinates of each vertex.

{'VertexColor', 'byte', 4} -- The r,g,b,a color of each vertex.

}

format table The vertex format of the Mesh, which is a table containing tables for each vertex attribute the Mesh was created with, in the form of {attribute, ...}.
format.attribute table A table containing the attribute's name, it's data type, and the number of components in the attribute, in the form of {name, datatype, components}.
format.... table Additional vertex attributes in the Mesh.

Mesh:getVertexMap

Gets the vertex map for the Mesh. The vertex map describes the order in which the vertices are used when the Mesh is drawn. The vertices, vertex map, and mesh draw mode work together to determine what exactly is displayed on the screen.

If no vertex map has been set previously via Mesh:setVertexMap, then this function will return nil in LÖVE 0.10.0+, or an empty table in 0.9.2 and older.

map = Mesh:getVertexMap()

map table A table containing the list of vertex indices used when drawing.

Mesh:isAttributeEnabled

Gets whether a specific vertex attribute in the Mesh is enabled. Vertex data from disabled attributes is not used when drawing the Mesh.

enabled = Mesh:isAttributeEnabled( name )

If a Mesh wasn't created with a custom vertex format, it will have 3 vertex attributes named VertexPosition, VertexTexCoord, and VertexColor. Otherwise the attribute name must either match one of the vertex attributes specified in the vertex format when creating the Mesh,

or must match a vertex attribute from another Mesh attached to this Mesh via Mesh:attachAttribute.

enabled boolean Whether the vertex attribute is used when drawing this Mesh.
name string The name of the vertex attribute to be checked.

Mesh:setAttributeEnabled

Enables or disables a specific vertex attribute in the Mesh. Vertex data from disabled attributes is not used when drawing the Mesh.

Mesh:setAttributeEnabled( name, enable )

If a Mesh wasn't created with a custom vertex format, it will have 3 vertex attributes named VertexPosition, VertexTexCoord, and VertexColor. Otherwise the attribute name must either match one of the vertex attributes specified in the vertex format when creating the Mesh,

or must match a vertex attribute from another Mesh attached to this Mesh via Mesh:attachAttribute.

name string The name of the vertex attribute to enable or disable.
enable boolean Whether the vertex attribute is used when drawing this Mesh.

Mesh:setDrawMode

Sets the mode used when drawing the Mesh.

Mesh:setDrawMode( mode )

mode MeshDrawMode The mode to use when drawing the Mesh.

Mesh:setDrawRange

Restricts the drawn vertices of the Mesh to a subset of the total.

Mesh:setDrawRange( start, count )

start number The index of the first vertex to use when drawing, or the index of the first value in the vertex map to use if one is set for this Mesh.
count number The number of vertices to use when drawing, or number of values in the vertex map to use if one is set for this Mesh.

Mesh:setDrawRange()

Allows all vertices in the Mesh to be drawn.

Mesh:setTexture

Sets the texture (Image or Canvas) used when drawing the Mesh.

Mesh:setTexture( texture )

texture Texture The Image or Canvas to texture the Mesh with when drawing.

Mesh:setTexture()

Disables any texture from being used when drawing the Mesh. Untextured meshes have a white color by default.

Mesh:setVertex

Sets the properties of a vertex in the Mesh.

In versions prior to 11.0, color and byte component values were within the range of 0 to 255 instead of 0 to 1.

Mesh:setVertex( index, attributecomponent, ... )

The arguments are in the same order as the vertex attributes in the Mesh's vertex format. A standard Mesh that wasn't created with a custom vertex format will use two position numbers, two texture coordinate numbers, and four color components per vertex: x, y, u, v, r, g, b, a.

If no value is supplied for a specific vertex attribute component, it will be set to a default value of 0 if its data type is 'float', or 1 if its data type is 'byte'.

index number The index of the the vertex you want to modify (one-based).
attributecomponent number The first component of the first vertex attribute in the specified vertex.
... number Additional components of all vertex attributes in the specified vertex.

Mesh:setVertex( index, vertex )

The table indices are in the same order as the vertex attributes in the Mesh's vertex format. A standard Mesh that wasn't created with a custom vertex format will use two position numbers, two texture coordinate numbers, and four color components per vertex: x, y, u, v, r, g, b, a.

If no value is supplied for a specific vertex attribute component, it will be set to a default value of 0 if its data type is 'float', or 1 if its data type is 'byte'.

index number The index of the the vertex you want to modify (one-based).
vertex table A table with vertex information, in the form of {attributecomponent, ...}.
vertex.attributecomponent number The first component of the first vertex attribute in the specified vertex.
vertex.... number Additional components of all vertex attributes in the specified vertex.

Mesh:setVertex( index, x, y, u, v, r, g, b, a )

Sets the vertex components of a Mesh that wasn't created with a custom vertex format.

index number The index of the the vertex you want to modify (one-based).
x number The position of the vertex on the x-axis.
y number The position of the vertex on the y-axis.
u number The horizontal component of the texture coordinate.
v number The vertical component of the texture coordinate.
r (1) number The red component of the vertex's color.
g (1) number The green component of the vertex's color.
b (1) number The blue component of the vertex's color.
a (1) number The alpha component of the vertex's color.

Mesh:setVertex( index, vertex )

Sets the vertex components of a Mesh that wasn't created with a custom vertex format.

index number The index of the the vertex you want to modify (one-based).
vertex table A table with vertex information.
vertex[1] number The position of the vertex on the x-axis.
vertex[2] number The position of the vertex on the y-axis.
vertex[3] number The u texture coordinate. Texture coordinates are normally in the range of 1, but can be greater or less (see WrapMode.)
vertex[4] number The v texture coordinate. Texture coordinates are normally in the range of 1, but can be greater or less (see WrapMode.)
vertex[5] (1) number The red color component.
vertex[6] (1) number The green color component.
vertex[7] (1) number The blue color component.
vertex[8] (1) number The alpha color component.

Mesh:setVertexAttribute

Sets the properties of a specific attribute within a vertex in the Mesh.

Meshes without a custom vertex format specified in love.graphics.newMesh have position as their first attribute, texture coordinates as their second attribute, and color as their third attribute.

Mesh:setVertexAttribute( vertexindex, attributeindex, value1, value2, ... )

Attribute components which exist within the attribute but are not specified as arguments default to 0 for attributes with the float data type, and 255 for the byte data type.

vertexindex number The index of the the vertex to be modified (one-based).
attributeindex number The index of the attribute within the vertex to be modified (one-based).
value1 number The new value for the first component of the attribute.
value2 number The new value for the second component of the attribute.
... number Any additional vertex attribute components.

Mesh:setVertexMap

Sets the vertex map for the Mesh. The vertex map describes the order in which the vertices are used when the Mesh is drawn. The vertices, vertex map, and mesh draw mode work together to determine what exactly is displayed on the screen.

The vertex map allows you to re-order or reuse vertices when drawing without changing the actual vertex parameters or duplicating vertices. It is especially useful when combined with different Mesh Draw Modes.

Mesh:setVertexMap( map )

map table A table containing a list of vertex indices to use when drawing. Values must be in the range of Mesh:getVertexCount().

Mesh:setVertexMap( vi1, vi2, vi3 )

vi1 number The index of the first vertex to use when drawing. Must be in the range of Mesh:getVertexCount().
vi2 number The index of the second vertex to use when drawing.
vi3 number The index of the third vertex to use when drawing.

Mesh:setVertexMap( data, datatype )

data Data Array of vertex indices to use when drawing. Values must be in the range of Mesh:getVertexCount()-1
datatype IndexDataType Datatype of the vertex indices array above.

Mesh:setVertices

Replaces a range of vertices in the Mesh with new ones. The total number of vertices in a Mesh cannot be changed after it has been created. This is often more efficient than calling Mesh:setVertex in a loop.

Mesh:setVertices( vertices, startvertex )

The values in each vertex table are in the same order as the vertex attributes in the Mesh's vertex format. A standard Mesh that wasn't created with a custom vertex format will use two position numbers, two texture coordinate numbers, and four color components per vertex: x, y, u, v, r, g, b, a.

If no value is supplied for a specific vertex attribute component, it will be set to a default value of 0 if its data type is 'float', or 255 if its data type is 'byte'.

vertices table The table filled with vertex information tables for each vertex, in the form of {vertex, ...} where each vertex is a table in the form of {attributecomponent, ...}.
vertices.attributecomponent number The first component of the first vertex attribute in the vertex.
vertices.... number Additional components of all vertex attributes in the vertex.
startvertex (1) number The index of the first vertex to replace.

Mesh:setVertices( data, startvertex )

Sets the vertex components of the Mesh by copying directly from the memory of a Data object.

If LuaJIT's FFI is used to populate the Data object via Data:getPointer and ffi.cast, this variant can be drastically more efficient than other methods of setting Mesh vertex data.

data Data A Data object to copy from. The contents of the Data must match the layout of this Mesh's vertex format.
startvertex (1) number The index of the first vertex to replace.

Mesh:setVertices( vertices )

Sets the vertex components of a Mesh that wasn't created with a custom vertex format.

vertices table The table filled with vertex information tables for each vertex as follows:
vertices[1] number The position of the vertex on the x-axis.
vertices[2] number The position of the vertex on the y-axis.
vertices[3] number The horizontal component of the texture coordinate. Texture coordinates are normally in the range of 1, but can be greater or less (see WrapMode).
vertices[4] number The vertical component of the texture coordinate. Texture coordinates are normally in the range of 1, but can be greater or less (see WrapMode).
vertices[5] (1) number The red color component.
vertices[6] (1) number The green color component.
vertices[7] (1) number The blue color component.
vertices[8] (1) number The alpha color component.

ParticleSystem

A ParticleSystem can be used to create particle effects like fire or smoke.

The particle system has to be created using update it in the update callback to see any changes in the particles emitted.

The particle system won't create any particles unless you call setParticleLifetime and setEmissionRate.

Functions

Emitter

Particles

Supertypes

ParticleSystem:clone

Creates an identical copy of the ParticleSystem in the stopped state.

particlesystem = ParticleSystem:clone()

Cloned ParticleSystem inherit all the set-able state of the original ParticleSystem, but they are initialized stopped.

particlesystem ParticleSystem The new identical copy of this ParticleSystem.

ParticleSystem:emit

Emits a burst of particles from the particle emitter.

ParticleSystem:emit( numparticles )

numparticles number The amount of particles to emit. The number of emitted particles will be truncated if the particle system's max buffer size is reached.

ParticleSystem:getBufferSize

Gets the maximum number of particles the ParticleSystem can have at once.

size = ParticleSystem:getBufferSize()

size number The maximum number of particles.

ParticleSystem:getColors

Gets the series of colors applied to the particle sprite.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

r1, g1, b1, a1, r2, g2, b2, a2, r8, g8, b8, a8 = ParticleSystem:getColors()

r1 number First color, red component (0-1).
g1 number First color, green component (0-1).
b1 number First color, blue component (0-1).
a1 number First color, alpha component (0-1).
r2 number Second color, red component (0-1).
g2 number Second color, green component (0-1).
b2 number Second color, blue component (0-1).
a2 number Second color, alpha component (0-1).
r8 number Eighth color, red component (0-1).
g8 number Eighth color, green component (0-1).
b8 number Eighth color, blue component (0-1).
a8 number Eighth color, alpha component (0-1).

ParticleSystem:getCount

Gets the number of particles that are currently in the system.

count = ParticleSystem:getCount()

count number The current number of live particles.

ParticleSystem:getDirection

Gets the direction of the particle emitter (in radians).

direction = ParticleSystem:getDirection()

direction number The direction of the emitter (radians).

ParticleSystem:getEmissionArea

Gets the area-based spawn parameters for the particles.

distribution, dx, dy, angle, directionRelativeToCenter = ParticleSystem:getEmissionArea()

distribution AreaSpreadDistribution The type of distribution for new particles.
dx number The maximum spawn distance from the emitter along the x-axis for uniform distribution, or the standard deviation along the x-axis for normal distribution.
dy number The maximum spawn distance from the emitter along the y-axis for uniform distribution, or the standard deviation along the y-axis for normal distribution.
angle number The angle in radians of the emission area.
directionRelativeToCenter boolean True if newly spawned particles will be oriented relative to the center of the emission area, false otherwise.

ParticleSystem:getEmissionRate

Gets the amount of particles emitted per second.

rate = ParticleSystem:getEmissionRate()

rate number The amount of particles per second.

ParticleSystem:getEmitterLifetime

Gets how long the particle system will emit particles (if -1 then it emits particles forever).

life = ParticleSystem:getEmitterLifetime()

life number The lifetime of the emitter (in seconds).

ParticleSystem:getInsertMode

Gets the mode used when the ParticleSystem adds new particles.

mode = ParticleSystem:getInsertMode()

mode ParticleInsertMode The mode used when the ParticleSystem adds new particles.

ParticleSystem:getLinearAcceleration

Gets the linear acceleration (acceleration along the x and y axes) for particles.

Every particle created will accelerate along the x and y axes between xmin,ymin and xmax,ymax.

xmin, ymin, xmax, ymax = ParticleSystem:getLinearAcceleration()

xmin number The minimum acceleration along the x axis.
ymin number The minimum acceleration along the y axis.
xmax number The maximum acceleration along the x axis.
ymax number The maximum acceleration along the y axis.

ParticleSystem:getLinearDamping

Gets the amount of linear damping (constant deceleration) for particles.

min, max = ParticleSystem:getLinearDamping()

min number The minimum amount of linear damping applied to particles.
max number The maximum amount of linear damping applied to particles.

ParticleSystem:getOffset

Gets the particle image's draw offset.

ox, oy = ParticleSystem:getOffset()

ox number The x coordinate of the particle image's draw offset.
oy number The y coordinate of the particle image's draw offset.

ParticleSystem:getParticleLifetime

Gets the lifetime of the particles.

min, max = ParticleSystem:getParticleLifetime()

min number The minimum life of the particles (in seconds).
max number The maximum life of the particles (in seconds).

ParticleSystem:getPosition

Gets the position of the emitter.

x, y = ParticleSystem:getPosition()

x number Position along x-axis.
y number Position along y-axis.

ParticleSystem:getQuads

Gets the series of Quads used for the particle sprites.

quads = ParticleSystem:getQuads()

quads table A table containing the Quads used.

ParticleSystem:getRadialAcceleration

Gets the radial acceleration (away from the emitter).

min, max = ParticleSystem:getRadialAcceleration()

min number The minimum acceleration.
max number The maximum acceleration.

ParticleSystem:getRotation

Gets the rotation of the image upon particle creation (in radians).

min, max = ParticleSystem:getRotation()

min number The minimum initial angle (radians).
max number The maximum initial angle (radians).

ParticleSystem:getSizeVariation

Gets the amount of size variation (0 meaning no variation and 1 meaning full variation between start and end).

variation = ParticleSystem:getSizeVariation()

variation number The amount of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:getSizes

Gets the series of sizes by which the sprite is scaled. 1.0 is normal size. The particle system will interpolate between each size evenly over the particle's lifetime.

size1, size2, size8 = ParticleSystem:getSizes()

size1 number The first size.
size2 number The second size.
size8 number The eighth size.

ParticleSystem:getSpeed

Gets the speed of the particles.

min, max = ParticleSystem:getSpeed()

min number The minimum linear speed of the particles.
max number The maximum linear speed of the particles.

ParticleSystem:getSpin

Gets the spin of the sprite.

min, max, variation = ParticleSystem:getSpin()

min number The minimum spin (radians per second).
max number The maximum spin (radians per second).
variation number The degree of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:getSpinVariation

Gets the amount of spin variation (0 meaning no variation and 1 meaning full variation between start and end).

variation = ParticleSystem:getSpinVariation()

variation number The amount of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:getSpread

Gets the amount of directional spread of the particle emitter (in radians).

spread = ParticleSystem:getSpread()

spread number The spread of the emitter (radians).

ParticleSystem:getTangentialAcceleration

Gets the tangential acceleration (acceleration perpendicular to the particle's direction).

min, max = ParticleSystem:getTangentialAcceleration()

min number The minimum acceleration.
max number The maximum acceleration.

ParticleSystem:getTexture

Gets the texture (Image or Canvas) used for the particles.

texture = ParticleSystem:getTexture()

texture Texture The Image or Canvas used for the particles.

ParticleSystem:hasRelativeRotation

Gets whether particle angles and rotations are relative to their velocities. If enabled, particles are aligned to the angle of their velocities and rotate relative to that angle.

enable = ParticleSystem:hasRelativeRotation()

enable boolean True if relative particle rotation is enabled, false if it's disabled.

ParticleSystem:isActive

Checks whether the particle system is actively emitting particles.

active = ParticleSystem:isActive()

active boolean True if system is active, false otherwise.

ParticleSystem:isPaused

Checks whether the particle system is paused.

paused = ParticleSystem:isPaused()

paused boolean True if system is paused, false otherwise.

ParticleSystem:isStopped

Checks whether the particle system is stopped.

stopped = ParticleSystem:isStopped()

stopped boolean True if system is stopped, false otherwise.

ParticleSystem:moveTo

Moves the position of the emitter. This results in smoother particle spawning behaviour than if ParticleSystem:setPosition is used every frame.

ParticleSystem:moveTo( x, y )

x number Position along x-axis.
y number Position along y-axis.

ParticleSystem:pause

Pauses the particle emitter.

ParticleSystem:pause()

ParticleSystem:reset

Resets the particle emitter, removing any existing particles and resetting the lifetime counter.

ParticleSystem:reset()

ParticleSystem:setBufferSize

Sets the size of the buffer (the max allowed amount of particles in the system).

ParticleSystem:setBufferSize( size )

size number The buffer size.

ParticleSystem:setColors

Sets a series of colors to apply to the particle sprite. The particle system will interpolate between each color evenly over the particle's lifetime.

Arguments can be passed in groups of four, representing the components of the desired RGBA value, or as tables of RGBA component values, with a default alpha value of 1 if only three values are given. At least one color must be specified. A maximum of eight may be used.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

ParticleSystem:setColors( r1, g1, b1, a1, r2, g2, b2, a2, r8, g8, b8, a8 )

r1 number First color, red component (0-1).
g1 number First color, green component (0-1).
b1 number First color, blue component (0-1).
a1 number First color, alpha component (0-1).
r2 number Second color, red component (0-1).
g2 number Second color, green component (0-1).
b2 number Second color, blue component (0-1).
a2 number Second color, alpha component (0-1).
r8 number Eighth color, red component (0-1).
g8 number Eighth color, green component (0-1).
b8 number Eighth color, blue component (0-1).
a8 number Eighth color, alpha component (0-1).

ParticleSystem:setDirection

Sets the direction the particles will be emitted in.

ParticleSystem:setDirection( direction )

direction number The direction of the particles (in radians).

ParticleSystem:setEmissionArea

Sets area-based spawn parameters for the particles. Newly created particles will spawn in an area around the emitter based on the parameters to this function.

ParticleSystem:setEmissionArea( distribution, dx, dy, angle, directionRelativeToCenter )

distribution AreaSpreadDistribution The type of distribution for new particles.
dx number The maximum spawn distance from the emitter along the x-axis for uniform distribution, or the standard deviation along the x-axis for normal distribution.
dy number The maximum spawn distance from the emitter along the y-axis for uniform distribution, or the standard deviation along the y-axis for normal distribution.
angle (0) number The angle in radians of the emission area.
directionRelativeToCenter (false) boolean True if newly spawned particles will be oriented relative to the center of the emission area, false otherwise.

ParticleSystem:setEmissionRate

Sets the amount of particles emitted per second.

ParticleSystem:setEmissionRate( rate )

rate number The amount of particles per second.

ParticleSystem:setEmitterLifetime

Sets how long the particle system should emit particles (if -1 then it emits particles forever).

ParticleSystem:setEmitterLifetime( life )

life number The lifetime of the emitter (in seconds).

ParticleSystem:setInsertMode

Sets the mode to use when the ParticleSystem adds new particles.

ParticleSystem:setInsertMode( mode )

mode ParticleInsertMode The mode to use when the ParticleSystem adds new particles.

ParticleSystem:setLinearAcceleration

Sets the linear acceleration (acceleration along the x and y axes) for particles.

Every particle created will accelerate along the x and y axes between xmin,ymin and xmax,ymax.

ParticleSystem:setLinearAcceleration( xmin, ymin, xmax, ymax )

xmin number The minimum acceleration along the x axis.
ymin number The minimum acceleration along the y axis.
xmax (xmin) number The maximum acceleration along the x axis.
ymax (ymin) number The maximum acceleration along the y axis.

ParticleSystem:setLinearDamping

Sets the amount of linear damping (constant deceleration) for particles.

ParticleSystem:setLinearDamping( min, max )

min number The minimum amount of linear damping applied to particles.
max (min) number The maximum amount of linear damping applied to particles.

ParticleSystem:setOffset

Set the offset position which the particle sprite is rotated around.

If this function is not used, the particles rotate around their center.

ParticleSystem:setOffset( x, y )

x number The x coordinate of the rotation offset.
y number The y coordinate of the rotation offset.

ParticleSystem:setParticleLifetime

Sets the lifetime of the particles.

ParticleSystem:setParticleLifetime( min, max )

min number The minimum life of the particles (in seconds).
max (min) number The maximum life of the particles (in seconds).

ParticleSystem:setPosition

Sets the position of the emitter.

ParticleSystem:setPosition( x, y )

x number Position along x-axis.
y number Position along y-axis.

ParticleSystem:setQuads

Sets a series of Quads to use for the particle sprites. Particles will choose a Quad from the list based on the particle's current lifetime, allowing for the use of animated sprite sheets with ParticleSystems.

ParticleSystem:setQuads( quad1, quad2 )

quad1 Quad The first Quad to use.
quad2 Quad The second Quad to use.

ParticleSystem:setQuads( quads )

quads table A table containing the Quads to use.

ParticleSystem:setRadialAcceleration

Set the radial acceleration (away from the emitter).

ParticleSystem:setRadialAcceleration( min, max )

min number The minimum acceleration.
max (min) number The maximum acceleration.

ParticleSystem:setRelativeRotation

Sets whether particle angles and rotations are relative to their velocities. If enabled, particles are aligned to the angle of their velocities and rotate relative to that angle.

ParticleSystem:setRelativeRotation( enable )

enable boolean True to enable relative particle rotation, false to disable it.

ParticleSystem:setRotation

Sets the rotation of the image upon particle creation (in radians).

ParticleSystem:setRotation( min, max )

min number The minimum initial angle (radians).
max (min) number The maximum initial angle (radians).

ParticleSystem:setSizeVariation

Sets the amount of size variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:setSizeVariation( variation )

variation number The amount of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:setSizes

Sets a series of sizes by which to scale a particle sprite. 1.0 is normal size. The particle system will interpolate between each size evenly over the particle's lifetime.

At least one size must be specified. A maximum of eight may be used.

ParticleSystem:setSizes( size1, size2, size8 )

size1 number The first size.
size2 number The second size.
size8 number The eighth size.

ParticleSystem:setSpeed

Sets the speed of the particles.

ParticleSystem:setSpeed( min, max )

min number The minimum linear speed of the particles.
max (min) number The maximum linear speed of the particles.

ParticleSystem:setSpin

Sets the spin of the sprite.

ParticleSystem:setSpin( min, max )

min number The minimum spin (radians per second).
max (min) number The maximum spin (radians per second).

ParticleSystem:setSpinVariation

Sets the amount of spin variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:setSpinVariation( variation )

variation number The amount of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:setSpread

Sets the amount of spread for the system.

ParticleSystem:setSpread( spread )

spread number The amount of spread (radians).

ParticleSystem:setTangentialAcceleration

Sets the tangential acceleration (acceleration perpendicular to the particle's direction).

ParticleSystem:setTangentialAcceleration( min, max )

min number The minimum acceleration.
max (min) number The maximum acceleration.

ParticleSystem:setTexture

Sets the texture (Image or Canvas) to be used for the particles.

ParticleSystem:setTexture( texture )

texture Texture An Image or Canvas to use for the particles.

ParticleSystem:start

Starts the particle emitter.

ParticleSystem:start()

ParticleSystem:stop

Stops the particle emitter, resetting the lifetime counter.

ParticleSystem:stop()

ParticleSystem:update

Updates the particle system; moving, creating and killing particles.

ParticleSystem:update( dt )

dt number The time (seconds) since last frame.

Quad

A quadrilateral (a polygon with four sides and four corners) with texture coordinate information.

Quads can be used to select part of a texture to draw. In this way, one large texture atlas can be loaded, and then split up into sub-images.

Functions

Supertypes

Quad:getTextureDimensions

Gets reference texture dimensions initially specified in love.graphics.newQuad.

sw, sh = Quad:getTextureDimensions()

sw number The Texture width used by the Quad.
sh number The Texture height used by the Quad.

Quad:getViewport

Gets the current viewport of this Quad.

x, y, w, h = Quad:getViewport()

x number The top-left corner along the x-axis.
y number The top-left corner along the y-axis.
w number The width of the viewport.
h number The height of the viewport.

Quad:setViewport

Sets the texture coordinates according to a viewport.

Quad:setViewport( x, y, w, h, sw, sh )

x number The top-left corner along the x-axis.
y number The top-left corner along the y-axis.
w number The width of the viewport.
h number The height of the viewport.
sw number The reference width, the width of the Image. (Must be greater than 0.)
sh number The reference height, the height of the Image. (Must be greater than 0.)

Shader

A Shader is used for advanced hardware-accelerated pixel or vertex manipulation. These effects are written in a language based on GLSL (OpenGL Shading Language) with a few things simplified for easier coding.

Potential uses for shaders include HDR/bloom, motion blur, grayscale/invert/sepia/any kind of color effect, reflection/refraction, distortions, bump mapping, and much more! Here is a collection of basic shaders and good starting point to learn: https://github.com/vrld/moonshine

Functions

Supertypes

Shader:getWarnings

Returns any warning and error messages from compiling the shader code. This can be used for debugging your shaders if there's anything the graphics hardware doesn't like.

warnings = Shader:getWarnings()

warnings string Warning and error messages (if any).

Shader:hasUniform

Gets whether a uniform / extern variable exists in the Shader.

If a graphics driver's shader compiler determines that a uniform / extern variable doesn't affect the final output of the shader, it may optimize the variable out. This function will return false in that case.

hasuniform = Shader:hasUniform( name )

hasuniform boolean Whether the uniform exists in the shader and affects its final output.
name string The name of the uniform variable.

Shader:send

Sends one or more values to a special (''uniform'') variable inside the shader. Uniform variables have to be marked using the ''uniform'' or ''extern'' keyword, e.g.

uniform float time; // 'float' is the typical number type used in GLSL shaders.

uniform float varsvec2 light_pos;

uniform vec4 colors[4;

The corresponding send calls would be

shader:send('time', t)

shader:send('vars',a,b)

shader:send('light_pos', {light_x, light_y})

shader:send('colors', {r1, g1, b1, a1}, {r2, g2, b2, a2}, {r3, g3, b3, a3}, {r4, g4, b4, a4})

Uniform / extern variables are read-only in the shader code and remain constant until modified by a Shader:send call. Uniform variables can be accessed in both the Vertex and Pixel components of a shader, as long as the variable is declared in each.

Shader:send( name, number, ... )

Because all numbers in Lua are floating point, in versions prior to 0.10.2 you must use the function Shader:sendInt to send values to uniform int variables in the shader's code.

name string Name of the number to send to the shader.
number number Number to send to store in the uniform variable.
... number Additional numbers to send if the uniform variable is an array.

Shader:send( name, vector, ... )

name string Name of the vector to send to the shader.
vector table Numbers to send to the uniform variable as a vector. The number of elements in the table determines the type of the vector (e.g. two numbers -> vec2). At least two and at most four numbers can be used.
... table Additional vectors to send if the uniform variable is an array. All vectors need to be of the same size (e.g. only vec3's).

Shader:send( name, matrix, ... )

name string Name of the matrix to send to the shader.
matrix table 2x2, 3x3, or 4x4 matrix to send to the uniform variable. Using table form: {{a,b,c,d}, {e,f,g,h}, ... } or (since version 0.10.2) {a,b,c,d, e,f,g,h, ...}. The order in 0.10.2 is column-major; starting in 11.0 it's row-major instead.
... table Additional matrices of the same type as ''matrix'' to store in a uniform array.

Shader:send( name, texture )

name string Name of the Texture to send to the shader.
texture Texture Texture (Image or Canvas) to send to the uniform variable.

Shader:send( name, boolean, ... )

name string Name of the boolean to send to the shader.
boolean boolean Boolean to send to store in the uniform variable.
... boolean Additional booleans to send if the uniform variable is an array.

Shader:send( name, matrixlayout, matrix, ... )

name string Name of the matrix to send to the shader.
matrixlayout MatrixLayout The layout (row- or column-major) of the matrix.
matrix table 2x2, 3x3, or 4x4 matrix to send to the uniform variable. Using table form: {{a,b,c,d}, {e,f,g,h}, ... } or {a,b,c,d, e,f,g,h, ...}.
... table Additional matrices of the same type as ''matrix'' to store in a uniform array.

Shader:send( name, data, offset, size )

Sends uniform values to the Shader sourced from the contents of a Data object. This directly copies the bytes of the data.

name string Name of the uniform to send to the shader.
data Data Data object containing the values to send.
offset (0) number Offset in bytes from the start of the Data object.
size (all) number Size in bytes of the data to send. If nil, as many bytes as the specified uniform uses will be copied.

Shader:send( name, data, matrixlayout, offset, size )

Sends uniform matrices to the Shader sourced from the contents of a Data object. This directly copies the bytes of the data.

name string Name of the uniform matrix to send to the shader.
data Data Data object containing the values to send.
matrixlayout MatrixLayout The layout (row- or column-major) of the matrix in memory.
offset (0) number Offset in bytes from the start of the Data object.
size (all) number Size in bytes of the data to send. If nil, as many bytes as the specified uniform uses will be copied.

Shader:sendColor

Sends one or more colors to a special (''extern'' / ''uniform'') vec3 or vec4 variable inside the shader. The color components must be in the range of 1. The colors are gamma-corrected if global gamma-correction is enabled.

Extern variables must be marked using the ''extern'' keyword, e.g.

extern vec4 Color;

The corresponding sendColor call would be

shader:sendColor('Color', {r, g, b, a})

Extern variables can be accessed in both the Vertex and Pixel stages of a shader, as long as the variable is declared in each.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

Shader:sendColor( name, color, ... )

name string The name of the color extern variable to send to in the shader.
color table A table with red, green, blue, and optional alpha color components in the range of 1 to send to the extern as a vector.
... table Additional colors to send in case the extern is an array. All colors need to be of the same size (e.g. only vec3's).

SpriteBatch

Using a single image, draw any number of identical copies of the image using a single call to love.graphics.draw(). This can be used, for example, to draw repeating copies of a single background image with high performance.

A SpriteBatch can be even more useful when the underlying image is a texture atlas (a single image file containing many independent images); by adding Quads to the batch, different sub-images from within the atlas can be drawn.

Functions

Supertypes

SpriteBatch:add

Adds a sprite to the batch. Sprites are drawn in the order they are added.

id = SpriteBatch:add( x, y, r, sx, sy, ox, oy, kx, ky )

id number An identifier for the added sprite.
x number The position to draw the object (x-axis).
y number The position to draw the object (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shear factor (x-axis).
ky (0) number Shear factor (y-axis).

id = SpriteBatch:add( quad, x, y, r, sx, sy, ox, oy, kx, ky )

Adds a Quad to the batch.

id number An identifier for the added sprite.
quad Quad The Quad to add.
x number The position to draw the object (x-axis).
y number The position to draw the object (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shear factor (x-axis).
ky (0) number Shear factor (y-axis).

SpriteBatch:addLayer

Adds a sprite to a batch created with an Array Texture.

spriteindex = SpriteBatch:addLayer( layerindex, x, y, r, sx, sy, ox, oy, kx, ky )

Adds a layer of the SpriteBatch's Array Texture.

spriteindex number The index of the added sprite, for use with SpriteBatch:set or SpriteBatch:setLayer.
layerindex number The index of the layer to use for this sprite.
x (0) number The position to draw the sprite (x-axis).
y (0) number The position to draw the sprite (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

spriteindex = SpriteBatch:addLayer( layerindex, quad, x, y, r, sx, sy, ox, oy, kx, ky )

Adds a layer of the SpriteBatch's Array Texture using the specified Quad.

The specified layer index overrides any layer index set on the Quad via Quad:setLayer.

spriteindex number The index of the added sprite, for use with SpriteBatch:set or SpriteBatch:setLayer.
layerindex number The index of the layer to use for this sprite.
quad Quad The subsection of the texture's layer to use when drawing the sprite.
x (0) number The position to draw the sprite (x-axis).
y (0) number The position to draw the sprite (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

spriteindex = SpriteBatch:addLayer( layerindex, transform )

Adds a layer of the SpriteBatch's Array Texture using the specified Transform.

spriteindex number The index of the added sprite, for use with SpriteBatch:set or SpriteBatch:setLayer.
layerindex number The index of the layer to use for this sprite.
transform Transform A transform object.

spriteindex = SpriteBatch:addLayer( layerindex, quad, transform )

Adds a layer of the SpriteBatch's Array Texture using the specified Quad and Transform.

In order to use an Array Texture or other non-2D texture types as the main texture in a custom void effect() variant must be used in the pixel shader, and MainTex must be declared as an ArrayImage or sampler2DArray like so: uniform ArrayImage MainTex;.

spriteindex number The index of the added sprite, for use with SpriteBatch:set or SpriteBatch:setLayer.
layerindex number The index of the layer to use for this sprite.
quad Quad The subsection of the texture's layer to use when drawing the sprite.
transform Transform A transform object.

SpriteBatch:attachAttribute

Attaches a per-vertex attribute from a Mesh onto this SpriteBatch, for use when drawing. This can be combined with a Shader to augment a SpriteBatch with per-vertex or additional per-sprite information instead of just having per-sprite colors.

Each sprite in a SpriteBatch has 4 vertices in the following order: top-left, bottom-left, top-right, bottom-right. The index returned by SpriteBatch:add (and used by SpriteBatch:set) can used to determine the first vertex of a specific sprite with the formula 1 + 4 * ( id - 1 ).

SpriteBatch:attachAttribute( name, mesh )

If a created with a custom vertex format, it will have 3 vertex attributes named VertexPosition, VertexTexCoord, and VertexColor. If vertex attributes with those names are attached to the SpriteBatch, it will override the SpriteBatch's sprite positions, texture coordinates, and sprite colors, respectively.

Custom named attributes can be accessed in a vertex shader by declaring them as attribute vec4 MyCustomAttributeName; at the top-level of the vertex shader code. The name must match what was specified in the Mesh's vertex format and in the name argument of SpriteBatch:attachAttribute.

A Mesh must have at least 4 * SpriteBatch:getBufferSize vertices in order to be attachable to a SpriteBatch.

name string The name of the vertex attribute to attach.
mesh Mesh The Mesh to get the vertex attribute from.

SpriteBatch:clear

Removes all sprites from the buffer.

SpriteBatch:clear()

SpriteBatch:flush

Immediately sends all new and modified sprite data in the batch to the graphics card.

Normally it isn't necessary to call this method as love.graphics.draw(spritebatch, ...) will do it automatically if needed, but explicitly using SpriteBatch:flush gives more control over when the work happens.

If this method is used, it generally shouldn't be called more than once (at most) between love.graphics.draw(spritebatch, ...) calls.

SpriteBatch:flush()

SpriteBatch:getBufferSize

Gets the maximum number of sprites the SpriteBatch can hold.

size = SpriteBatch:getBufferSize()

size number The maximum number of sprites the batch can hold.

SpriteBatch:getColor

Gets the color that will be used for the next add and set operations.

If no color has been set with SpriteBatch:setColor or the current SpriteBatch color has been cleared, this method will return nil.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

r, g, b, a = SpriteBatch:getColor()

r number The red component (0-1).
g number The green component (0-1).
b number The blue component (0-1).
a number The alpha component (0-1).

SpriteBatch:getCount

Gets the number of sprites currently in the SpriteBatch.

count = SpriteBatch:getCount()

count number The number of sprites currently in the batch.

SpriteBatch:getTexture

Gets the texture (Image or Canvas) used by the SpriteBatch.

texture = SpriteBatch:getTexture()

texture Texture The Image or Canvas used by the SpriteBatch.

SpriteBatch:set

Changes a sprite in the batch. This requires the sprite index returned by SpriteBatch:add or SpriteBatch:addLayer.

SpriteBatch:set( spriteindex, x, y, r, sx, sy, ox, oy, kx, ky )

spriteindex number The index of the sprite that will be changed.
x number The position to draw the object (x-axis).
y number The position to draw the object (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shear factor (x-axis).
ky (0) number Shear factor (y-axis).

SpriteBatch:set( spriteindex, quad, x, y, r, sx, sy, ox, oy, kx, ky )

Changes a sprite with a Quad in the batch. This requires the index returned by SpriteBatch:add or SpriteBatch:addLayer.

SpriteBatches do not support removing individual sprites. One can do a pseudo removal (instead of clearing and re-adding everything) by:

SpriteBatch:set(id, 0, 0, 0, 0, 0)

This makes all the sprite's vertices equal (because the x and y scales are 0), which prevents the GPU from fully processing the sprite when drawing the SpriteBatch.

spriteindex number The index of the sprite that will be changed.
quad Quad The Quad used on the image of the batch.
x number The position to draw the object (x-axis).
y number The position to draw the object (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shear factor (x-axis).
ky (0) number Shear factor (y-axis).

SpriteBatch:setColor

Sets the color that will be used for the next add and set operations. Calling the function without arguments will disable all per-sprite colors for the SpriteBatch.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

In version 0.9.2 and older, the global color set with love.graphics.setColor will not work on the SpriteBatch if any of the sprites has its own color.

SpriteBatch:setColor( r, g, b, a )

r number The amount of red.
g number The amount of green.
b number The amount of blue.
a (1) number The amount of alpha.

SpriteBatch:setColor()

Disables all per-sprite colors for this SpriteBatch.

SpriteBatch:setDrawRange

Restricts the drawn sprites in the SpriteBatch to a subset of the total.

SpriteBatch:setDrawRange( start, count )

start number The index of the first sprite to draw. Index 1 corresponds to the first sprite added with SpriteBatch:add.
count number The number of sprites to draw.

SpriteBatch:setDrawRange()

Allows all sprites in the SpriteBatch to be drawn.

SpriteBatch:setLayer

Changes a sprite previously added with add or addLayer, in a batch created with an Array Texture.

SpriteBatch:setLayer( spriteindex, layerindex, x, y, r, sx, sy, ox, oy, kx, ky )

Changes the sprite in the SpriteBatch.

spriteindex number The index of the existing sprite to replace.
layerindex number The index of the layer in the Array Texture to use for this sprite.
x (0) number The position to draw the sprite (x-axis).
y (0) number The position to draw the sprite (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

SpriteBatch:setLayer( spriteindex, layerindex, quad, x, y, r, sx, sy, ox, oy, kx, ky )

Adds a layer of the SpriteBatch's Array Texture using the specified Quad.

The specified layer index overrides any layer index set on the Quad via Quad:setLayer.

spriteindex number The index of the existing sprite to replace.
layerindex number The index of the layer to use for this sprite.
quad Quad The subsection of the texture's layer to use when drawing the sprite.
x (0) number The position to draw the sprite (x-axis).
y (0) number The position to draw the sprite (y-axis).
r (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing factor (x-axis).
ky (0) number Shearing factor (y-axis).

SpriteBatch:setLayer( spriteindex, layerindex, transform )

Adds a layer of the SpriteBatch's Array Texture using the specified Transform.

spriteindex number The index of the existing sprite to replace.
layerindex number The index of the layer to use for the sprite.
transform Transform A transform object.

SpriteBatch:setLayer( spriteindex, layerindex, quad, transform )

Adds a layer of the SpriteBatch's Array Texture using the specified Quad and Transform.

The specified layer index overrides any layer index set on the Quad via Quad:setLayer.

spriteindex number The index of the existing sprite to replace.
layerindex number The index of the layer to use for the sprite.
quad Quad The subsection of the texture's layer to use when drawing the sprite.
transform Transform A transform object.

SpriteBatch:setTexture

Sets the texture (Image or Canvas) used for the sprites in the batch, when drawing.

SpriteBatch:setTexture( texture )

texture Texture The new Image or Canvas to use for the sprites in the batch.

Text

Drawable text.

Functions

Dimensions

Supertypes

Text:add

Adds additional colored text to the Text object at the specified position.

index = Text:add( textstring, x, y, angle, sx, sy, ox, oy, kx, ky )

index number An index number that can be used with Text:getWidth or Text:getHeight.
textstring string The text to add to the object.
x (0) number The position of the new text on the x-axis.
y (0) number The position of the new text on the y-axis.
angle (0) number The orientation of the new text in radians.
sx (1) number Scale factor on the x-axis.
sy (sx) number Scale factor on the y-axis.
ox (0) number Origin offset on the x-axis.
oy (0) number Origin offset on the y-axis.
kx (0) number Shearing / skew factor on the x-axis.
ky (0) number Shearing / skew factor on the y-axis.

index = Text:add( coloredtext, x, y, angle, sx, sy, ox, oy, kx, ky )

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text, when drawing the Text object.

index number An index number that can be used with Text:getWidth or Text:getHeight.
coloredtext table A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1 string A string of text which has a color specified by the previous color.
coloredtext.color2 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2 string A string of text which has a color specified by the previous color.
coloredtext.... tables and strings Additional colors and strings.
x (0) number The position of the new text on the x-axis.
y (0) number The position of the new text on the y-axis.
angle (0) number The orientation of the new text in radians.
sx (1) number Scale factor on the x-axis.
sy (sx) number Scale factor on the y-axis.
ox (0) number Origin offset on the x-axis.
oy (0) number Origin offset on the y-axis.
kx (0) number Shearing / skew factor on the x-axis.
ky (0) number Shearing / skew factor on the y-axis.

Text:addf

Adds additional formatted / colored text to the Text object at the specified position.

The word wrap limit is applied before any scaling, rotation, and other coordinate transformations. Therefore the amount of text per line stays constant given the same wrap limit, even if the scale arguments change.

index = Text:addf( textstring, wraplimit, align, x, y, angle, sx, sy, ox, oy, kx, ky )

index number An index number that can be used with Text:getWidth or Text:getHeight.
textstring string The text to add to the object.
wraplimit number The maximum width in pixels of the text before it gets automatically wrapped to a new line.
align AlignMode The alignment of the text.
x number The position of the new text (x-axis).
y number The position of the new text (y-axis).
angle (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing / skew factor (x-axis).
ky (0) number Shearing / skew factor (y-axis).

index = Text:addf( coloredtext, wraplimit, align, x, y, angle, sx, sy, ox, oy, kx, ky )

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text, when drawing the Text object.

index number An index number that can be used with Text:getWidth or Text:getHeight.
coloredtext table A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1 string A string of text which has a color specified by the previous color.
coloredtext.color2 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2 string A string of text which has a color specified by the previous color.
coloredtext.... tables and strings Additional colors and strings.
wraplimit number The maximum width in pixels of the text before it gets automatically wrapped to a new line.
align AlignMode The alignment of the text.
x number The position of the new text (x-axis).
y number The position of the new text (y-axis).
angle (0) number Orientation (radians).
sx (1) number Scale factor (x-axis).
sy (sx) number Scale factor (y-axis).
ox (0) number Origin offset (x-axis).
oy (0) number Origin offset (y-axis).
kx (0) number Shearing / skew factor (x-axis).
ky (0) number Shearing / skew factor (y-axis).

Text:clear

Clears the contents of the Text object.

Text:clear()

Text:getDimensions

Gets the width and height of the text in pixels.

width, height = Text:getDimensions()

width number The width of the text. If multiple sub-strings have been added with Text:add, the width of the last sub-string is returned.
height number The height of the text. If multiple sub-strings have been added with Text:add, the height of the last sub-string is returned.

width, height = Text:getDimensions( index )

Gets the width and height of a specific sub-string that was previously added to the Text object.

width number The width of the sub-string (before scaling and other transformations).
height number The height of the sub-string (before scaling and other transformations).
index number An index number returned by Text:add or Text:addf.

Text:getFont

Gets the Font used with the Text object.

font = Text:getFont()

font Font The font used with this Text object.

Text:getHeight

Gets the height of the text in pixels.

height = Text:getHeight()

height number The height of the text. If multiple sub-strings have been added with Text:add, the height of the last sub-string is returned.

height = Text:getHeight( index )

Gets the height of a specific sub-string that was previously added to the Text object.

height number The height of the sub-string (before scaling and other transformations).
index number An index number returned by Text:add or Text:addf.

Text:getWidth

Gets the width of the text in pixels.

width = Text:getWidth()

width number The width of the text. If multiple sub-strings have been added with Text:add, the width of the last sub-string is returned.

width = Text:getWidth( index )

Gets the width of a specific sub-string that was previously added to the Text object.

width number The width of the sub-string (before scaling and other transformations).
index number An index number returned by Text:add or Text:addf.

Text:set

Replaces the contents of the Text object with a new unformatted string.

Text:set( textstring )

textstring string The new string of text to use.

Text:set( coloredtext )

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text, when drawing the Text object.

coloredtext table A table containing colors and strings to use as the new text, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1 string A string of text which has a color specified by the previous color.
coloredtext.color2 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2 string A string of text which has a color specified by the previous color.
coloredtext.... tables and strings Additional colors and strings.

Text:setFont

Replaces the Font used with the text.

Text:setFont( font )

font Font The new font to use with this Text object.

Text:setf

Replaces the contents of the Text object with a new formatted string.

Text:setf( textstring, wraplimit, align )

textstring string The new string of text to use.
wraplimit number The maximum width in pixels of the text before it gets automatically wrapped to a new line.
align AlignMode The alignment of the text.

Text:setf( coloredtext, wraplimit, align )

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text, when drawing the Text object.

coloredtext table A table containing colors and strings to use as the new text, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1 string A string of text which has a color specified by the previous color.
coloredtext.color2 table A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2 string A string of text which has a color specified by the previous color.
coloredtext.... tables and strings Additional colors and strings.
wraplimit number The maximum width in pixels of the text before it gets automatically wrapped to a new line.
align AlignMode The alignment of the text.

Texture

Superclass for drawable objects which represent a texture. All Textures can be drawn with Quads. This is an abstract type that can't be created directly.

Functions

Supertypes

Subtypes

Texture:getDPIScale

Gets the DPI scale factor of the Texture.

The DPI scale factor represents relative pixel density. A DPI scale factor of 2 means the texture has twice the pixel density in each dimension (4 times as many pixels in the same area) compared to a texture with a DPI scale factor of 1.

For example, a texture with pixel dimensions of 100x100 with a DPI scale factor of 2 will be drawn as if it was 50x50. This is useful with high-dpi / retina displays to easily allow swapping out higher or lower pixel density Images and Canvases without needing any extra manual scaling logic.

dpiscale = Texture:getDPIScale()

dpiscale number The DPI scale factor of the Texture.

Texture:getDepth

Gets the depth of a Volume Texture. Returns 1 for 2D, Cubemap, and Array textures.

depth = Texture:getDepth()

depth number The depth of the volume Texture.

Texture:getFormat

Gets the pixel format of the Texture.

format = Texture:getFormat()

format PixelFormat The pixel format the Texture was created with.

Texture:getLayerCount

Gets the number of layers / slices in an Array Texture. Returns 1 for 2D, Cubemap, and Volume textures.

layers = Texture:getLayerCount()

layers number The number of layers in the Array Texture.

Texture:getMipmapCount

Gets the number of mipmaps contained in the Texture. If the texture was not created with mipmaps, it will return 1.

mipmaps = Texture:getMipmapCount()

mipmaps number The number of mipmaps in the Texture.

Texture:getMipmapFilter

Gets the mipmap filter mode for a Texture. Prior to 11.0 this method only worked on Images.

mode, sharpness = Texture:getMipmapFilter()

mode FilterMode The filter mode used in between mipmap levels. nil if mipmap filtering is not enabled.
sharpness number Value used to determine whether the image should use more or less detailed mipmap levels than normal when drawing.

Texture:getPixelHeight

Gets the height in pixels of the Texture.

DPI scale factor, rather than pixels. Use getHeight for calculations related to drawing the texture (calculating an origin offset, for example), and getPixelHeight only when dealing specifically with pixels, for example when using Canvas:newImageData.

pixelheight = Texture:getPixelHeight()

pixelheight number The height of the Texture, in pixels.

Texture:getPixelWidth

Gets the width in pixels of the Texture.

DPI scale factor, rather than pixels. Use getWidth for calculations related to drawing the texture (calculating an origin offset, for example), and getPixelWidth only when dealing specifically with pixels, for example when using Canvas:newImageData.

pixelwidth = Texture:getPixelWidth()

pixelwidth number The width of the Texture, in pixels.

Texture:getTextureType

Gets the type of the Texture.

texturetype = Texture:getTextureType()

texturetype TextureType The type of the Texture.

Texture:isReadable

Gets whether the Texture can be drawn and sent to a Shader.

Canvases created with stencil and/or depth PixelFormats are not readable by default, unless readable=true is specified in the settings table passed into love.graphics.newCanvas.

Non-readable Canvases can still be rendered to.

readable = Texture:isReadable()

readable boolean Whether the Texture is readable.

Texture:setMipmapFilter

Sets the mipmap filter mode for a Texture. Prior to 11.0 this method only worked on Images.

Mipmapping is useful when drawing a texture at a reduced scale. It can improve performance and reduce aliasing issues.

In created with the mipmaps flag enabled for the mipmap filter to have any effect. In versions prior to 0.10.0 it's best to call this method directly after creating the image with love.graphics.newImage, to avoid bugs in certain graphics drivers.

Due to hardware restrictions and driver bugs, in versions prior to 0.10.0 images that weren't loaded from a CompressedData must have power-of-two dimensions (64x64, 512x256, etc.) to use mipmaps.

Texture:setMipmapFilter( filtermode, sharpness )

On mobile devices (Android and iOS), the sharpness parameter is not supported and will do nothing. You can use a custom compressed and its CompressedData has mipmap data included, it will use that.

filtermode FilterMode The filter mode to use in between mipmap levels. 'nearest' will often give better performance.
sharpness (0) number A positive sharpness value makes the texture use a more detailed mipmap level when drawing, at the expense of performance. A negative value does the reverse.

Texture:setMipmapFilter()

Disables mipmap filtering.

Video

A drawable video.

Functions

Dimensions

Supertypes

Video:getDimensions

Gets the width and height of the Video in pixels.

width, height = Video:getDimensions()

width number The width of the Video.
height number The height of the Video.

Video:getFilter

Gets the scaling filters used when drawing the Video.

min, mag, anisotropy = Video:getFilter()

min FilterMode The filter mode used when scaling the Video down.
mag FilterMode The filter mode used when scaling the Video up.
anisotropy number Maximum amount of anisotropic filtering used.

Video:getHeight

Gets the height of the Video in pixels.

height = Video:getHeight()

height number The height of the Video.

Video:getSource

Gets the audio Source used for playing back the video's audio. May return nil if the video has no audio, or if Video:setSource is called with a nil argument.

source = Video:getSource()

source Source The audio Source used for audio playback, or nil if the video has no audio.

Video:getWidth

Gets the width of the Video in pixels.

width = Video:getWidth()

width number The width of the Video.

Video:isPlaying

Gets whether the Video is currently playing.

playing = Video:isPlaying()

playing boolean Whether the video is playing.

Video:pause

Pauses the Video.

Video:pause()

Video:play

Starts playing the Video. In order for the video to appear onscreen it must be drawn with love.graphics.draw.

Video:play()

Video:rewind

Rewinds the Video to the beginning.

Video:rewind()

Video:seek

Sets the current playback position of the Video.

Video:seek( offset )

offset number The time in seconds since the beginning of the Video.

Video:setFilter

Sets the scaling filters used when drawing the Video.

Video:setFilter( min, mag, anisotropy )

min FilterMode The filter mode used when scaling the Video down.
mag FilterMode The filter mode used when scaling the Video up.
anisotropy (1) number Maximum amount of anisotropic filtering used.

Video:setSource

Sets the audio Source used for playing back the video's audio. The audio Source also controls playback speed and synchronization.

Video:setSource( source )

source (nil) Source The audio Source used for audio playback, or nil to disable audio synchronization.

Video:tell

Gets the current playback position of the Video.

seconds = Video:tell()

seconds number The time in seconds since the beginning of the Video.

love.image

Types

Functions

Enums

love.image.isCompressed

Determines whether a file can be loaded as CompressedImageData.

compressed = love.image.isCompressed( filename )

compressed boolean Whether the file can be loaded as CompressedImageData or not.
filename string The filename of the potentially compressed image file.

compressed = love.image.isCompressed( fileData )

compressed boolean Whether the FileData can be loaded as CompressedImageData or not.
fileData FileData A FileData potentially containing a compressed image.

love.image.newCompressedData

Create a new CompressedImageData object from a compressed image file. LÖVE supports several compressed texture formats, enumerated in the CompressedImageFormat page.

compressedImageData = love.image.newCompressedData( filename )

compressedImageData CompressedImageData The new CompressedImageData object.
filename string The filename of the compressed image file.

compressedImageData = love.image.newCompressedData( fileData )

compressedImageData CompressedImageData The new CompressedImageData object.
fileData FileData A FileData containing a compressed image.

love.image.newImageData

Creates a new ImageData object.

imageData = love.image.newImageData( width, height )

imageData ImageData The new blank ImageData object. Each pixel's color values, (including the alpha values!) will be set to zero.
width number The width of the ImageData.
height number The height of the ImageData.

imageData = love.image.newImageData( width, height, format, data )

imageData ImageData The new ImageData object.
width number The width of the ImageData.
height number The height of the ImageData.
format ('rgba8') PixelFormat The pixel format of the ImageData.
data (nil) string Optional raw byte data to load into the ImageData, in the format specified by ''format''.

imageData = love.image.newImageData( width, height, data )

imageData ImageData The new ImageData object.
width number The width of the ImageData.
height number The height of the ImageData.
data string The data to load into the ImageData (RGBA bytes, left to right and top to bottom).

imageData = love.image.newImageData( filename )

imageData ImageData The new ImageData object.
filename string The filename of the image file.

imageData = love.image.newImageData( filedata )

imageData ImageData The new ImageData object.
filedata FileData The encoded file data to decode into image data.

CompressedImageFormat

DXT1

The DXT1 format. RGB data at 4 bits per pixel (compared to 32 bits for ImageData and regular Images.) Suitable for fully opaque images on desktop systems.

DXT3

The DXT3 format. RGBA data at 8 bits per pixel. Smooth variations in opacity do not mix well with this format.

DXT5

The DXT5 format. RGBA data at 8 bits per pixel. Recommended for images with varying opacity on desktop systems.

BC4

The BC4 format (also known as 3Dc+ or ATI1.) Stores just the red channel, at 4 bits per pixel.

BC4s

The signed variant of the BC4 format. Same as above but pixel values in the texture are in the range of 1 instead of 1 in shaders.

BC5

The BC5 format (also known as 3Dc or ATI2.) Stores red and green channels at 8 bits per pixel.

BC5s

The signed variant of the BC5 format.

BC6h

The BC6H format. Stores half-precision floating-point RGB data in the range of 65504 at 8 bits per pixel. Suitable for HDR images on desktop systems.

BC6hs

The signed variant of the BC6H format. Stores RGB data in the range of +65504.

BC7

The BC7 format (also known as BPTC.) Stores RGB or RGBA data at 8 bits per pixel.

ETC1

The ETC1 format. RGB data at 4 bits per pixel. Suitable for fully opaque images on older Android devices.

ETC2rgb

The RGB variant of the ETC2 format. RGB data at 4 bits per pixel. Suitable for fully opaque images on newer mobile devices.

ETC2rgba

The RGBA variant of the ETC2 format. RGBA data at 8 bits per pixel. Recommended for images with varying opacity on newer mobile devices.

ETC2rgba1

The RGBA variant of the ETC2 format where pixels are either fully transparent or fully opaque. RGBA data at 4 bits per pixel.

EACr

The single-channel variant of the EAC format. Stores just the red channel, at 4 bits per pixel.

EACrs

The signed single-channel variant of the EAC format. Same as above but pixel values in the texture are in the range of 1 instead of 1 in shaders.

EACrg

The two-channel variant of the EAC format. Stores red and green channels at 8 bits per pixel.

EACrgs

The signed two-channel variant of the EAC format.

PVR1rgb2

The 2 bit per pixel RGB variant of the PVRTC1 format. Stores RGB data at 2 bits per pixel. Textures compressed with PVRTC1 formats must be square and power-of-two sized.

PVR1rgb4

The 4 bit per pixel RGB variant of the PVRTC1 format. Stores RGB data at 4 bits per pixel.

PVR1rgba2

The 2 bit per pixel RGBA variant of the PVRTC1 format.

PVR1rgba4

The 4 bit per pixel RGBA variant of the PVRTC1 format.

ASTC4x4

The 4x4 pixels per block variant of the ASTC format. RGBA data at 8 bits per pixel.

ASTC5x4

The 5x4 pixels per block variant of the ASTC format. RGBA data at 6.4 bits per pixel.

ASTC5x5

The 5x5 pixels per block variant of the ASTC format. RGBA data at 5.12 bits per pixel.

ASTC6x5

The 6x5 pixels per block variant of the ASTC format. RGBA data at 4.27 bits per pixel.

ASTC6x6

The 6x6 pixels per block variant of the ASTC format. RGBA data at 3.56 bits per pixel.

ASTC8x5

The 8x5 pixels per block variant of the ASTC format. RGBA data at 3.2 bits per pixel.

ASTC8x6

The 8x6 pixels per block variant of the ASTC format. RGBA data at 2.67 bits per pixel.

ASTC8x8

The 8x8 pixels per block variant of the ASTC format. RGBA data at 2 bits per pixel.

ASTC10x5

The 10x5 pixels per block variant of the ASTC format. RGBA data at 2.56 bits per pixel.

ASTC10x6

The 10x6 pixels per block variant of the ASTC format. RGBA data at 2.13 bits per pixel.

ASTC10x8

The 10x8 pixels per block variant of the ASTC format. RGBA data at 1.6 bits per pixel.

ASTC10x10

The 10x10 pixels per block variant of the ASTC format. RGBA data at 1.28 bits per pixel.

ASTC12x10

The 12x10 pixels per block variant of the ASTC format. RGBA data at 1.07 bits per pixel.

ASTC12x12

The 12x12 pixels per block variant of the ASTC format. RGBA data at 0.89 bits per pixel.

ImageFormat

tga

Targa image format.

png

PNG image format.

jpg

JPG image format.

bmp

BMP image format.

CompressedImageData

Represents compressed image data designed to stay compressed in RAM.

CompressedImageData encompasses standard compressed texture formats such as DXT1, DXT5, and BC5 / 3Dc.

You can't draw CompressedImageData directly to the screen. See Image for that.

Functions

Supertypes

CompressedImageData:getDimensions

Gets the width and height of the CompressedImageData.

width, height = CompressedImageData:getDimensions()

width number The width of the CompressedImageData.
height number The height of the CompressedImageData.

width, height = CompressedImageData:getDimensions( level )

width number The width of a specific mipmap level of the CompressedImageData.
height number The height of a specific mipmap level of the CompressedImageData.
level number A mipmap level. Must be in the range of CompressedImageData:getMipmapCount().

CompressedImageData:getFormat

Gets the format of the CompressedImageData.

format = CompressedImageData:getFormat()

format CompressedImageFormat The format of the CompressedImageData.

CompressedImageData:getHeight

Gets the height of the CompressedImageData.

height = CompressedImageData:getHeight()

height number The height of the CompressedImageData.

height = CompressedImageData:getHeight( level )

height number The height of a specific mipmap level of the CompressedImageData.
level number A mipmap level. Must be in the range of CompressedImageData:getMipmapCount().

CompressedImageData:getMipmapCount

Gets the number of mipmap levels in the CompressedImageData. The base mipmap level (original image) is included in the count.

mipmaps = CompressedImageData:getMipmapCount()

Mipmap filtering cannot be activated for an Image:setMipmapFilter will error. Most tools which can create compressed textures are able to automatically generate mipmaps for them in the same file.

mipmaps number The number of mipmap levels stored in the CompressedImageData.

CompressedImageData:getWidth

Gets the width of the CompressedImageData.

width = CompressedImageData:getWidth()

width number The width of the CompressedImageData.

width = CompressedImageData:getWidth( level )

width number The width of a specific mipmap level of the CompressedImageData.
level number A mipmap level. Must be in the range of CompressedImageData:getMipmapCount().

ImageData

Raw (decoded) image data.

You can't draw ImageData directly to screen. See Image for that.

Functions

Dimensions

Supertypes

ImageData:encode

Encodes the ImageData and optionally writes it to the save directory.

filedata = ImageData:encode( format, filename )

filedata FileData The encoded image as a new FileData object.
format ImageFormat The format to encode the image as.
filename (nil) string The filename to write the file to. If nil, no file will be written but the FileData will still be returned.

ImageData:encode( outFile )

outFile string Name of a file to write encoded data to. The format will be automatically deduced from the file extension.

ImageData:encode( outFile, format )

outFile string Name of a file to write encoded data to.
format ImageFormat The format to encode the image in.

ImageData:getDimensions

Gets the width and height of the ImageData in pixels.

width, height = ImageData:getDimensions()

width number The width of the ImageData in pixels.
height number The height of the ImageData in pixels.

ImageData:getHeight

Gets the height of the ImageData in pixels.

height = ImageData:getHeight()

height number The height of the ImageData in pixels.

ImageData:getPixel

Gets the color of a pixel at a specific position in the image.

Valid x and y values start at 0 and go up to image width and height minus 1. Non-integer values are floored.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

r, g, b, a = ImageData:getPixel( x, y )

r number The red component (0-1).
g number The green component (0-1).
b number The blue component (0-1).
a number The alpha component (0-1).
x number The position of the pixel on the x-axis.
y number The position of the pixel on the y-axis.

ImageData:getWidth

Gets the width of the ImageData in pixels.

width = ImageData:getWidth()

width number The width of the ImageData in pixels.

ImageData:mapPixel

Transform an image by applying a function to every pixel.

This function is a higher-order function. It takes another function as a parameter, and calls it once for each pixel in the ImageData.

The passed function is called with six parameters for each pixel in turn. The parameters are numbers that represent the x and y coordinates of the pixel and its red, green, blue and alpha values. The function should return the new red, green, blue, and alpha values for that pixel.

function pixelFunction(x, y, r, g, b, a)

-- template for defining your own pixel mapping function

-- perform computations giving the new values for r, g, b and a

-- ...

return r, g, b, a

end

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

ImageData:mapPixel( pixelFunction, x, y, width, height )

pixelFunction function Function to apply to every pixel.
x (0) number The x-axis of the top-left corner of the area within the ImageData to apply the function to.
y (0) number The y-axis of the top-left corner of the area within the ImageData to apply the function to.
width (ImageData:getWidth()) number The width of the area within the ImageData to apply the function to.
height (ImageData:getHeight()) number The height of the area within the ImageData to apply the function to.

ImageData:paste

Paste into ImageData from another source ImageData.

ImageData:paste( source, dx, dy, sx, sy, sw, sh )

Note that this function just replaces the contents in the destination rectangle; it does not do any alpha blending.

source ImageData Source ImageData from which to copy.
dx number Destination top-left position on x-axis.
dy number Destination top-left position on y-axis.
sx number Source top-left position on x-axis.
sy number Source top-left position on y-axis.
sw number Source width.
sh number Source height.

ImageData:setPixel

Sets the color of a pixel at a specific position in the image.

Valid x and y values start at 0 and go up to image width and height minus 1.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

ImageData:setPixel( x, y, r, g, b, a )

x number The position of the pixel on the x-axis.
y number The position of the pixel on the y-axis.
r number The red component (0-1).
g number The green component (0-1).
b number The blue component (0-1).
a number The alpha component (0-1).

love.joystick

Types

Functions

Enums

love.joystick.getGamepadMappingString

Gets the full gamepad mapping string of the Joysticks which have the given GUID, or nil if the GUID isn't recognized as a gamepad.

The mapping string contains binding information used to map the Joystick's buttons an axes to the standard gamepad layout, and can be used later with love.joystick.loadGamepadMappings.

mappingstring = love.joystick.getGamepadMappingString( guid )

mappingstring string A string containing the Joystick's gamepad mappings, or nil if the GUID is not recognized as a gamepad.
guid string The GUID value to get the mapping string for.

love.joystick.getJoystickCount

Gets the number of connected joysticks.

joystickcount = love.joystick.getJoystickCount()

joystickcount number The number of connected joysticks.

love.joystick.getJoysticks

Gets a list of connected Joysticks.

joysticks = love.joystick.getJoysticks()

joysticks table The list of currently connected Joysticks.

love.joystick.loadGamepadMappings

Loads a gamepad mappings string or file created with love.joystick.saveGamepadMappings.

It also recognizes any SDL gamecontroller mapping string, such as those created with Steam's Big Picture controller configure interface, or this nice database. If a new mapping is loaded for an already known controller GUID, the later version will overwrite the one currently loaded.

love.joystick.loadGamepadMappings( filename )

Loads a gamepad mappings string from a file.

filename string The filename to load the mappings string from.

love.joystick.loadGamepadMappings( mappings )

Loads a gamepad mappings string directly.

mappings string The mappings string to load.

love.joystick.saveGamepadMappings

Saves the virtual gamepad mappings of all recognized as gamepads and have either been recently used or their gamepad bindings have been modified.

The mappings are stored as a string for use with love.joystick.loadGamepadMappings.

mappings = love.joystick.saveGamepadMappings( filename )

Saves the gamepad mappings of all relevant joysticks to a file.

mappings string The mappings string that was written to the file.
filename string The filename to save the mappings string to.

mappings = love.joystick.saveGamepadMappings()

Returns the mappings string without writing to a file.

mappings string The mappings string.

love.joystick.setGamepadMapping

Binds a virtual gamepad input to a button, axis or hat for all Joysticks of a certain type. For example, if this function is used with a GUID returned by a Dualshock 3 controller in OS X, the binding will affect Joystick:getGamepadAxis and Joystick:isGamepadDown for ''all'' Dualshock 3 controllers used with the game when run in OS X.

LÖVE includes built-in gamepad bindings for many common controllers. This function lets you change the bindings or add new ones for types of Joysticks which aren't recognized as gamepads by default.

The virtual gamepad buttons and axes are designed around the Xbox 360 controller layout.

success = love.joystick.setGamepadMapping( guid, button, inputtype, inputindex, hatdir )

success boolean Whether the virtual gamepad button was successfully bound.
guid string The OS-dependent GUID for the type of Joystick the binding will affect.
button GamepadButton The virtual gamepad button to bind.
inputtype JoystickInputType The type of input to bind the virtual gamepad button to.
inputindex number The index of the axis, button, or hat to bind the virtual gamepad button to.
hatdir (nil) JoystickHat The direction of the hat, if the virtual gamepad button will be bound to a hat. nil otherwise.

success = love.joystick.setGamepadMapping( guid, axis, inputtype, inputindex, hatdir )

The physical locations for the bound gamepad axes and buttons should correspond as closely as possible to the layout of a standard Xbox 360 controller.

success boolean Whether the virtual gamepad axis was successfully bound.
guid string The OS-dependent GUID for the type of Joystick the binding will affect.
axis GamepadAxis The virtual gamepad axis to bind.
inputtype JoystickInputType The type of input to bind the virtual gamepad axis to.
inputindex number The index of the axis, button, or hat to bind the virtual gamepad axis to.
hatdir (nil) JoystickHat The direction of the hat, if the virtual gamepad axis will be bound to a hat. nil otherwise.

GamepadAxis

leftx

The x-axis of the left thumbstick.

lefty

The y-axis of the left thumbstick.

rightx

The x-axis of the right thumbstick.

righty

The y-axis of the right thumbstick.

triggerleft

Left analog trigger.

triggerright

Right analog trigger.

GamepadButton

a

Bottom face button (A).

b

Right face button (B).

x

Left face button (X).

y

Top face button (Y).

back

Back button.

guide

Guide button.

start

Start button.

leftstick

Left stick click button.

rightstick

Right stick click button.

leftshoulder

Left bumper.

rightshoulder

Right bumper.

dpup

D-pad up.

dpdown

D-pad down.

dpleft

D-pad left.

dpright

D-pad right.

JoystickHat

c

Centered

d

Down

l

Left

ld

Left+Down

lu

Left+Up

r

Right

rd

Right+Down

ru

Right+Up

u

Up

JoystickInputType

axis

Analog axis.

button

Button.

hat

8-direction hat value.

Joystick

Represents a physical joystick.

Functions

Input

Count

Info

Vibration

Supertypes

Joystick:getAxes

Gets the direction of each axis.

axisDir1, axisDir2, axisDirN = Joystick:getAxes()

axisDir1 number Direction of axis1.
axisDir2 number Direction of axis2.
axisDirN number Direction of axisN.

Joystick:getAxis

Gets the direction of an axis.

direction = Joystick:getAxis( axis )

direction number Current value of the axis.
axis number The index of the axis to be checked.

Joystick:getAxisCount

Gets the number of axes on the joystick.

axes = Joystick:getAxisCount()

axes number The number of axes available.

Joystick:getButtonCount

Gets the number of buttons on the joystick.

buttons = Joystick:getButtonCount()

buttons number The number of buttons available.

Joystick:getDeviceInfo

Gets the USB vendor ID, product ID, and product version numbers of joystick which consistent across operating systems.

Can be used to show different icons, etc. for different gamepads.

vendorID, productID, productVersion = Joystick:getDeviceInfo()

Some Linux distribution may not ship with SDL 2.0.6 or later, in which case this function will returns 0 for all the three values.

vendorID number The USB vendor ID of the joystick.
productID number The USB product ID of the joystick.
productVersion number The product version of the joystick.

Joystick:getGUID

Gets a stable GUID unique to the type of the physical joystick which does not change over time. For example, all Sony Dualshock 3 controllers in OS X have the same GUID. The value is platform-dependent.

guid = Joystick:getGUID()

guid string The Joystick type's OS-dependent unique identifier.

Joystick:getGamepadAxis

Gets the direction of a virtual gamepad axis. If the Joystick isn't recognized as a gamepad or isn't connected, this function will always return 0.

direction = Joystick:getGamepadAxis( axis )

direction number Current value of the axis.
axis GamepadAxis The virtual axis to be checked.

Joystick:getGamepadMapping

Gets the button, axis or hat that a virtual gamepad input is bound to.

inputtype, inputindex, hatdirection = Joystick:getGamepadMapping( axis )

Returns nil if the Joystick isn't recognized as a gamepad or the virtual gamepad axis is not bound to a Joystick input.

inputtype JoystickInputType The type of input the virtual gamepad axis is bound to.
inputindex number The index of the Joystick's button, axis or hat that the virtual gamepad axis is bound to.
hatdirection JoystickHat The direction of the hat, if the virtual gamepad axis is bound to a hat. nil otherwise.
axis GamepadAxis The virtual gamepad axis to get the binding for.

inputtype, inputindex, hatdirection = Joystick:getGamepadMapping( button )

The physical locations for the virtual gamepad axes and buttons correspond as closely as possible to the layout of a standard Xbox 360 controller.

inputtype JoystickInputType The type of input the virtual gamepad button is bound to.
inputindex number The index of the Joystick's button, axis or hat that the virtual gamepad button is bound to.
hatdirection JoystickHat The direction of the hat, if the virtual gamepad button is bound to a hat. nil otherwise.
button GamepadButton The virtual gamepad button to get the binding for.

Joystick:getGamepadMappingString

Gets the full gamepad mapping string of this Joystick, or nil if it's not recognized as a gamepad.

The mapping string contains binding information used to map the Joystick's buttons an axes to the standard gamepad layout, and can be used later with love.joystick.loadGamepadMappings.

mappingstring = Joystick:getGamepadMappingString()

mappingstring string A string containing the Joystick's gamepad mappings, or nil if the Joystick is not recognized as a gamepad.

Joystick:getHat

Gets the direction of the Joystick's hat.

direction = Joystick:getHat( hat )

direction JoystickHat The direction the hat is pushed.
hat number The index of the hat to be checked.

Joystick:getHatCount

Gets the number of hats on the joystick.

hats = Joystick:getHatCount()

hats number How many hats the joystick has.

Joystick:getID

Gets the joystick's unique identifier. The identifier will remain the same for the life of the game, even when the Joystick is disconnected and reconnected, but it '''will''' change when the game is re-launched.

id, instanceid = Joystick:getID()

id number The Joystick's unique identifier. Remains the same as long as the game is running.
instanceid number Unique instance identifier. Changes every time the Joystick is reconnected. nil if the Joystick is not connected.

Joystick:getName

Gets the name of the joystick.

name = Joystick:getName()

name string The name of the joystick.

Joystick:getVibration

Gets the current vibration motor strengths on a Joystick with rumble support.

left, right = Joystick:getVibration()

left number Current strength of the left vibration motor on the Joystick.
right number Current strength of the right vibration motor on the Joystick.

Joystick:isConnected

Gets whether the Joystick is connected.

connected = Joystick:isConnected()

connected boolean True if the Joystick is currently connected, false otherwise.

Joystick:isDown

Checks if a button on the Joystick is pressed.

LÖVE 0.9.0 had a bug which required the button indices passed to Joystick:isDown to be 0-based instead of 1-based, for example button 1 would be 0 for this function. It was fixed in 0.9.1.

anyDown = Joystick:isDown( buttonN )

anyDown boolean True if any supplied button is down, false if not.
buttonN number The index of a button to check.

Joystick:isGamepad

Gets whether the Joystick is recognized as a gamepad. If this is the case, the Joystick's buttons and axes can be used in a standardized manner across different operating systems and joystick models via Joystick:getGamepadAxis, Joystick:isGamepadDown, love.gamepadpressed, and related functions.

LÖVE automatically recognizes most popular controllers with a similar layout to the Xbox 360 controller as gamepads, but you can add more with love.joystick.setGamepadMapping.

isgamepad = Joystick:isGamepad()

If the Joystick is recognized as a gamepad, the physical locations for the virtual gamepad axes and buttons correspond as closely as possible to the layout of a standard Xbox 360 controller.

isgamepad boolean True if the Joystick is recognized as a gamepad, false otherwise.

Joystick:isGamepadDown

Checks if a virtual gamepad button on the Joystick is pressed. If the Joystick is not recognized as a Gamepad or isn't connected, then this function will always return false.

anyDown = Joystick:isGamepadDown( buttonN )

anyDown boolean True if any supplied button is down, false if not.
buttonN GamepadButton The gamepad button to check.

Joystick:isVibrationSupported

Gets whether the Joystick supports vibration.

supported = Joystick:isVibrationSupported()

The very first call to this function may take more time than expected because SDL's Haptic / Force Feedback subsystem needs to be initialized.

supported boolean True if rumble / force feedback vibration is supported on this Joystick, false if not.

Joystick:setVibration

Sets the vibration motor speeds on a Joystick with rumble support. Most common gamepads have this functionality, although not all drivers give proper support. Use Joystick:isVibrationSupported to check.

success = Joystick:setVibration( left, right )

success boolean True if the vibration was successfully applied, false if not.
left number Strength of the left vibration motor on the Joystick. Must be in the range of 1.
right number Strength of the right vibration motor on the Joystick. Must be in the range of 1.

success = Joystick:setVibration()

Disables vibration.

success boolean True if the vibration was successfully disabled, false if not.

success = Joystick:setVibration( left, right, duration )

If the Joystick only has a single vibration motor, it will still work but it will use the largest value of the left and right parameters.

The Xbox 360 controller on Mac OS X only has support for vibration if a modified version of the Tattiebogle driver is used.

The very first call to this function may take more time than expected because SDL's Haptic / Force Feedback subsystem needs to be initialized.

success boolean True if the vibration was successfully applied, false if not.
left number Strength of the left vibration motor on the Joystick. Must be in the range of 1.
right number Strength of the right vibration motor on the Joystick. Must be in the range of 1.
duration (-1) number The duration of the vibration in seconds. A negative value means infinite duration.

love.keyboard

Functions

Enums

love.keyboard.getKeyFromScancode

Gets the key corresponding to the given hardware scancode.

Unlike key constants, Scancodes are keyboard layout-independent. For example the scancode 'w' will be generated if the key in the same place as the 'w' key on an American keyboard is pressed, no matter what the key is labelled or what the user's operating system settings are.

Scancodes are useful for creating default controls that have the same physical locations on on all systems.

key = love.keyboard.getKeyFromScancode( scancode )

key KeyConstant The key corresponding to the given scancode, or 'unknown' if the scancode doesn't map to a KeyConstant on the current system.
scancode Scancode The scancode to get the key from.

love.keyboard.getScancodeFromKey

Gets the hardware scancode corresponding to the given key.

Unlike key constants, Scancodes are keyboard layout-independent. For example the scancode 'w' will be generated if the key in the same place as the 'w' key on an American keyboard is pressed, no matter what the key is labelled or what the user's operating system settings are.

Scancodes are useful for creating default controls that have the same physical locations on on all systems.

scancode = love.keyboard.getScancodeFromKey( key )

scancode Scancode The scancode corresponding to the given key, or 'unknown' if the given key has no known physical representation on the current system.
key KeyConstant The key to get the scancode from.

love.keyboard.hasKeyRepeat

Gets whether key repeat is enabled.

enabled = love.keyboard.hasKeyRepeat()

enabled boolean Whether key repeat is enabled.

love.keyboard.hasTextInput

Gets whether text input events are enabled.

enabled = love.keyboard.hasTextInput()

enabled boolean Whether text input events are enabled.

love.keyboard.isDown

Checks whether a certain key is down. Not to be confused with love.keypressed or love.keyreleased.

down = love.keyboard.isDown( key )

down boolean True if the key is down, false if not.
key KeyConstant The key to check.

anyDown = love.keyboard.isDown( key, ... )

anyDown boolean True if any supplied key is down, false if not.
key KeyConstant A key to check.
... KeyConstant Additional keys to check.

love.keyboard.isScancodeDown

Checks whether the specified Scancodes are pressed. Not to be confused with love.keypressed or love.keyreleased.

Unlike regular KeyConstants, Scancodes are keyboard layout-independent. The scancode 'w' is used if the key in the same place as the 'w' key on an American keyboard is pressed, no matter what the key is labelled or what the user's operating system settings are.

down = love.keyboard.isScancodeDown( scancode, ... )

down boolean True if any supplied Scancode is down, false if not.
scancode Scancode A Scancode to check.
... Scancode Additional Scancodes to check.

love.keyboard.setKeyRepeat

Enables or disables key repeat for love.keypressed. It is disabled by default.

love.keyboard.setKeyRepeat( enable )

The interval between repeats depends on the user's system settings. This function doesn't affect whether love.textinput is called multiple times while a key is held down.

enable boolean Whether repeat keypress events should be enabled when a key is held down.

love.keyboard.setTextInput

Enables or disables text input events. It is enabled by default on Windows, Mac, and Linux, and disabled by default on iOS and Android.

On touch devices, this shows the system's native on-screen keyboard when it's enabled.

love.keyboard.setTextInput( enable )

enable boolean Whether text input events should be enabled.

love.keyboard.setTextInput( enable, x, y, w, h )

On iOS and Android this variant tells the OS that the specified rectangle is where text will show up in the game, which prevents the system on-screen keyboard from covering the text.

enable boolean Whether text input events should be enabled.
x number Text rectangle x position.
y number Text rectangle y position.
w number Text rectangle width.
h number Text rectangle height.

KeyConstant

a

The A key

b

The B key

c

The C key

d

The D key

e

The E key

f

The F key

g

The G key

h

The H key

i

The I key

j

The J key

k

The K key

l

The L key

m

The M key

n

The N key

o

The O key

p

The P key

q

The Q key

r

The R key

s

The S key

t

The T key

u

The U key

v

The V key

w

The W key

x

The X key

y

The Y key

z

The Z key

0

The zero key

1

The one key

2

The two key

3

The three key

4

The four key

5

The five key

6

The six key

7

The seven key

8

The eight key

9

The nine key

space

Space key

!

Exclamation mark key

"

Double quote key

#

Hash key

$

Dollar key

&

Ampersand key

'

Single quote key

(

Left parenthesis key

)

Right parenthesis key

*

Asterisk key

+

Plus key

,

Comma key

-

Hyphen-minus key

.

Full stop key

/

Slash key

:

Colon key

;

Semicolon key

<

Less-than key

=

Equal key

>

Greater-than key

?

Question mark key

@

At sign key

[

Left square bracket key

\

Backslash key

]

Right square bracket key

^

Caret key

_

Underscore key

`

Grave accent key

kp0

The numpad zero key

kp1

The numpad one key

kp2

The numpad two key

kp3

The numpad three key

kp4

The numpad four key

kp5

The numpad five key

kp6

The numpad six key

kp7

The numpad seven key

kp8

The numpad eight key

kp9

The numpad nine key

kp.

The numpad decimal point key

kp/

The numpad division key

kp*

The numpad multiplication key

kp-

The numpad substraction key

kp+

The numpad addition key

kpenter

The numpad enter key

kp=

The numpad equals key

up

Up cursor key

down

Down cursor key

right

Right cursor key

left

Left cursor key

home

Home key

end

End key

pageup

Page up key

pagedown

Page down key

insert

Insert key

backspace

Backspace key

tab

Tab key

clear

Clear key

return

Return key

delete

Delete key

f1

The 1st function key

f2

The 2nd function key

f3

The 3rd function key

f4

The 4th function key

f5

The 5th function key

f6

The 6th function key

f7

The 7th function key

f8

The 8th function key

f9

The 9th function key

f10

The 10th function key

f11

The 11th function key

f12

The 12th function key

f13

The 13th function key

f14

The 14th function key

f15

The 15th function key

numlock

Num-lock key

capslock

Caps-lock key

scrollock

Scroll-lock key

rshift

Right shift key

lshift

Left shift key

rctrl

Right control key

lctrl

Left control key

ralt

Right alt key

lalt

Left alt key

rmeta

Right meta key

lmeta

Left meta key

lsuper

Left super key

rsuper

Right super key

mode

Mode key

compose

Compose key

pause

Pause key

escape

Escape key

help

Help key

print

Print key

sysreq

System request key

break

Break key

menu

Menu key

power

Power key

euro

Euro (€) key

undo

Undo key

www

WWW key

mail

Mail key

calculator

Calculator key

appsearch

Application search key

apphome

Application home key

appback

Application back key

appforward

Application forward key

apprefresh

Application refresh key

appbookmarks

Application bookmarks key

Scancode

a

The 'A' key on an American layout.

b

The 'B' key on an American layout.

c

The 'C' key on an American layout.

d

The 'D' key on an American layout.

e

The 'E' key on an American layout.

f

The 'F' key on an American layout.

g

The 'G' key on an American layout.

h

The 'H' key on an American layout.

i

The 'I' key on an American layout.

j

The 'J' key on an American layout.

k

The 'K' key on an American layout.

l

The 'L' key on an American layout.

m

The 'M' key on an American layout.

n

The 'N' key on an American layout.

o

The 'O' key on an American layout.

p

The 'P' key on an American layout.

q

The 'Q' key on an American layout.

r

The 'R' key on an American layout.

s

The 'S' key on an American layout.

t

The 'T' key on an American layout.

u

The 'U' key on an American layout.

v

The 'V' key on an American layout.

w

The 'W' key on an American layout.

x

The 'X' key on an American layout.

y

The 'Y' key on an American layout.

z

The 'Z' key on an American layout.

1

The '1' key on an American layout.

2

The '2' key on an American layout.

3

The '3' key on an American layout.

4

The '4' key on an American layout.

5

The '5' key on an American layout.

6

The '6' key on an American layout.

7

The '7' key on an American layout.

8

The '8' key on an American layout.

9

The '9' key on an American layout.

0

The '0' key on an American layout.

return

The 'return' / 'enter' key on an American layout.

escape

The 'escape' key on an American layout.

backspace

The 'backspace' key on an American layout.

tab

The 'tab' key on an American layout.

space

The spacebar on an American layout.

-

The minus key on an American layout.

=

The equals key on an American layout.

[

The left-bracket key on an American layout.

]

The right-bracket key on an American layout.

\

The backslash key on an American layout.

nonus#

The non-U.S. hash scancode.

;

The semicolon key on an American layout.

'

The apostrophe key on an American layout.

`

The back-tick / grave key on an American layout.

,

The comma key on an American layout.

.

The period key on an American layout.

/

The forward-slash key on an American layout.

capslock

The capslock key on an American layout.

f1

The F1 key on an American layout.

f2

The F2 key on an American layout.

f3

The F3 key on an American layout.

f4

The F4 key on an American layout.

f5

The F5 key on an American layout.

f6

The F6 key on an American layout.

f7

The F7 key on an American layout.

f8

The F8 key on an American layout.

f9

The F9 key on an American layout.

f10

The F10 key on an American layout.

f11

The F11 key on an American layout.

f12

The F12 key on an American layout.

f13

The F13 key on an American layout.

f14

The F14 key on an American layout.

f15

The F15 key on an American layout.

f16

The F16 key on an American layout.

f17

The F17 key on an American layout.

f18

The F18 key on an American layout.

f19

The F19 key on an American layout.

f20

The F20 key on an American layout.

f21

The F21 key on an American layout.

f22

The F22 key on an American layout.

f23

The F23 key on an American layout.

f24

The F24 key on an American layout.

lctrl

The left control key on an American layout.

lshift

The left shift key on an American layout.

lalt

The left alt / option key on an American layout.

lgui

The left GUI (command / windows / super) key on an American layout.

rctrl

The right control key on an American layout.

rshift

The right shift key on an American layout.

ralt

The right alt / option key on an American layout.

rgui

The right GUI (command / windows / super) key on an American layout.

printscreen

The printscreen key on an American layout.

scrolllock

The scroll-lock key on an American layout.

pause

The pause key on an American layout.

insert

The insert key on an American layout.

home

The home key on an American layout.

numlock

The numlock / clear key on an American layout.

pageup

The page-up key on an American layout.

delete

The forward-delete key on an American layout.

end

The end key on an American layout.

pagedown

The page-down key on an American layout.

right

The right-arrow key on an American layout.

left

The left-arrow key on an American layout.

down

The down-arrow key on an American layout.

up

The up-arrow key on an American layout.

nonusbackslash

The non-U.S. backslash scancode.

application

The application key on an American layout. Windows contextual menu, compose key.

execute

The 'execute' key on an American layout.

help

The 'help' key on an American layout.

menu

The 'menu' key on an American layout.

select

The 'select' key on an American layout.

stop

The 'stop' key on an American layout.

again

The 'again' key on an American layout.

undo

The 'undo' key on an American layout.

cut

The 'cut' key on an American layout.

copy

The 'copy' key on an American layout.

paste

The 'paste' key on an American layout.

find

The 'find' key on an American layout.

kp/

The keypad forward-slash key on an American layout.

kp*

The keypad '*' key on an American layout.

kp-

The keypad minus key on an American layout.

kp+

The keypad plus key on an American layout.

kp=

The keypad equals key on an American layout.

kpenter

The keypad enter key on an American layout.

kp1

The keypad '1' key on an American layout.

kp2

The keypad '2' key on an American layout.

kp3

The keypad '3' key on an American layout.

kp4

The keypad '4' key on an American layout.

kp5

The keypad '5' key on an American layout.

kp6

The keypad '6' key on an American layout.

kp7

The keypad '7' key on an American layout.

kp8

The keypad '8' key on an American layout.

kp9

The keypad '9' key on an American layout.

kp0

The keypad '0' key on an American layout.

kp.

The keypad period key on an American layout.

international1

The 1st international key on an American layout. Used on Asian keyboards.

international2

The 2nd international key on an American layout.

international3

The 3rd international key on an American layout. Yen.

international4

The 4th international key on an American layout.

international5

The 5th international key on an American layout.

international6

The 6th international key on an American layout.

international7

The 7th international key on an American layout.

international8

The 8th international key on an American layout.

international9

The 9th international key on an American layout.

lang1

Hangul/English toggle scancode.

lang2

Hanja conversion scancode.

lang3

Katakana scancode.

lang4

Hiragana scancode.

lang5

Zenkaku/Hankaku scancode.

mute

The mute key on an American layout.

volumeup

The volume up key on an American layout.

volumedown

The volume down key on an American layout.

audionext

The audio next track key on an American layout.

audioprev

The audio previous track key on an American layout.

audiostop

The audio stop key on an American layout.

audioplay

The audio play key on an American layout.

audiomute

The audio mute key on an American layout.

mediaselect

The media select key on an American layout.

www

The 'WWW' key on an American layout.

mail

The Mail key on an American layout.

calculator

The calculator key on an American layout.

computer

The 'computer' key on an American layout.

acsearch

The AC Search key on an American layout.

achome

The AC Home key on an American layout.

acback

The AC Back key on an American layout.

acforward

The AC Forward key on an American layout.

acstop

Th AC Stop key on an American layout.

acrefresh

The AC Refresh key on an American layout.

acbookmarks

The AC Bookmarks key on an American layout.

power

The system power scancode.

brightnessdown

The brightness-down scancode.

brightnessup

The brightness-up scancode.

displayswitch

The display switch scancode.

kbdillumtoggle

The keyboard illumination toggle scancode.

kbdillumdown

The keyboard illumination down scancode.

kbdillumup

The keyboard illumination up scancode.

eject

The eject scancode.

sleep

The system sleep scancode.

alterase

The alt-erase key on an American layout.

sysreq

The sysreq key on an American layout.

cancel

The 'cancel' key on an American layout.

clear

The 'clear' key on an American layout.

prior

The 'prior' key on an American layout.

return2

The 'return2' key on an American layout.

separator

The 'separator' key on an American layout.

out

The 'out' key on an American layout.

oper

The 'oper' key on an American layout.

clearagain

The 'clearagain' key on an American layout.

crsel

The 'crsel' key on an American layout.

exsel

The 'exsel' key on an American layout.

kp00

The keypad 00 key on an American layout.

kp000

The keypad 000 key on an American layout.

thsousandsseparator

The thousands-separator key on an American layout.

decimalseparator

The decimal separator key on an American layout.

currencyunit

The currency unit key on an American layout.

currencysubunit

The currency sub-unit key on an American layout.

app1

The 'app1' scancode.

app2

The 'app2' scancode.

unknown

An unknown key.

love.math

Types

Functions

Random numbers

Polygons

Compression

Color

Enums

love.math.colorFromBytes

Converts a color from 0..255 to 0..1 range.

r, g, b, a = love.math.colorFromBytes( rb, gb, bb, ab )

Here's implementation for 11.2 and earlier.

function love.math.colorFromBytes(r, g, b, a)

if type(r) == 'table' then

r, g, b, a = rr[2, rr[4

end

r = clamp01(floor(r + 0.5) / 255)

g = clamp01(floor(g + 0.5) / 255)

b = clamp01(floor(b + 0.5) / 255)

a = a ~= nil and clamp01(floor(a + 0.5) / 255) or nil

return r, g, b, a

end

Where clamp01 is defined as follows

local function clamp01(x)

return math.min(math.max(x, 0), 1)

end

r number Red color component in 0..1 range.
g number Green color component in 0..1 range.
b number Blue color component in 0..1 range.
a number Alpha color component in 0..1 range or nil if alpha is not specified.
rb number Red color component in 0..255 range.
gb number Green color component in 0..255 range.
bb number Blue color component in 0..255 range.
ab (nil) number Alpha color component in 0..255 range.

love.math.colorToBytes

Converts a color from 0..1 to 0..255 range.

rb, gb, bb, ab = love.math.colorToBytes( r, g, b, a )

Here's implementation for 11.2 and earlier.

function love.math.colorToBytes(r, g, b, a)

if type(r) == 'table' then

r, g, b, a = rr[2, rr[4

end

r = floor(clamp01(r) * 255 + 0.5)

g = floor(clamp01(g) * 255 + 0.5)

b = floor(clamp01(b) * 255 + 0.5)

a = a ~= nil and floor(clamp01(a) * 255 + 0.5) or nil

return r, g, b, a

end

Where clamp01 is defined as follows

local function clamp01(x)

return math.min(math.max(x, 0), 1)

end

rb number Red color component in 0..255 range.
gb number Green color component in 0..255 range.
bb number Blue color component in 0..255 range.
ab number Alpha color component in 0..255 range or nil if alpha is not specified.
r number Red color component.
g number Green color component.
b number Blue color component.
a (nil) number Alpha color component.

love.math.compress

Compresses a string or data using a specific compression algorithm.

compressedData = love.math.compress( rawstring, format, level )

compressedData CompressedData A new Data object containing the compressed version of the string.
rawstring string The raw (un-compressed) string to compress.
format ('lz4') CompressedDataFormat The format to use when compressing the string.
level (-1) number The level of compression to use, between 0 and 9. -1 indicates the default level. The meaning of this argument depends on the compression format being used.

compressedData = love.math.compress( data, format, level )

compressedData CompressedData A new Data object containing the compressed version of the raw data.
data Data A Data object containing the raw (un-compressed) data to compress.
format ('lz4') CompressedDataFormat The format to use when compressing the data.
level (-1) number The level of compression to use, between 0 and 9. -1 indicates the default level. The meaning of this argument depends on the compression format being used.

love.math.decompress

Decompresses a CompressedData or previously compressed string or Data object.

rawstring = love.math.decompress( compressedData )

rawstring string A string containing the raw decompressed data.
compressedData CompressedData The compressed data to decompress.

rawstring = love.math.decompress( compressedstring, format )

rawstring string A string containing the raw decompressed data.
compressedstring string A string containing data previously compressed with love.math.compress.
format CompressedDataFormat The format that was used to compress the given string.

rawstring = love.math.decompress( data, format )

rawstring string A string containing the raw decompressed data.
data Data A Data object containing data previously compressed with love.math.compress.
format CompressedDataFormat The format that was used to compress the given data.

love.math.gammaToLinear

Converts a color from gamma-space (sRGB) to linear-space (RGB). This is useful when doing gamma-correct rendering and you need to do math in linear RGB in the few cases where LÖVE doesn't handle conversions automatically.

Read more about gamma-correct rendering here, here, and here.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

lr, lg, lb = love.math.gammaToLinear( r, g, b )

An alpha value can be passed into the function as a fourth argument, but it will be returned unchanged because alpha is always linear.

lr number The red channel of the converted color in linear RGB space.
lg number The green channel of the converted color in linear RGB space.
lb number The blue channel of the converted color in linear RGB space.
r number The red channel of the sRGB color to convert.
g number The green channel of the sRGB color to convert.
b number The blue channel of the sRGB color to convert.

lr, lg, lb = love.math.gammaToLinear( color )

lr number The red channel of the converted color in linear RGB space.
lg number The green channel of the converted color in linear RGB space.
lb number The blue channel of the converted color in linear RGB space.
color table An array with the red, green, and blue channels of the sRGB color to convert.

lc = love.math.gammaToLinear( c )

lc number The value of the color channel in linear RGB space.
c number The value of a color channel in sRGB space to convert.

love.math.getRandomSeed

Gets the seed of the random number generator.

The seed is split into two numbers due to Lua's use of doubles for all number values - doubles can't accurately represent integer values above 2^53, but the seed can be an integer value up to 2^64.

low, high = love.math.getRandomSeed()

low number Integer number representing the lower 32 bits of the random number generator's 64 bit seed value.
high number Integer number representing the higher 32 bits of the random number generator's 64 bit seed value.

love.math.getRandomState

Gets the current state of the random number generator. This returns an opaque implementation-dependent string which is only useful for later use with love.math.setRandomState or RandomGenerator:setState.

This is different from love.math.getRandomSeed in that getRandomState gets the random number generator's current state, whereas getRandomSeed gets the previously set seed number.

state = love.math.getRandomState()

The value of the state string does not depend on the current operating system.

state string The current state of the random number generator, represented as a string.

love.math.isConvex

Checks whether a polygon is convex.

PolygonShapes in love.physics, some forms of Meshes, and polygons drawn with love.graphics.polygon must be simple convex polygons.

convex = love.math.isConvex( vertices )

convex boolean Whether the given polygon is convex.
vertices table The vertices of the polygon as a table in the form of {x1, y1, x2, y2, x3, y3, ...}.

convex = love.math.isConvex( x1, y1, x2, y2, x3, y3 )

convex boolean Whether the given polygon is convex.
x1 number The position of the first vertex of the polygon on the x-axis.
y1 number The position of the first vertex of the polygon on the y-axis.
x2 number The position of the second vertex of the polygon on the x-axis.
y2 number The position of the second vertex of the polygon on the y-axis.
x3 number The position of the third vertex of the polygon on the x-axis.
y3 number The position of the third vertex of the polygon on the y-axis.

love.math.linearToGamma

Converts a color from linear-space (RGB) to gamma-space (sRGB). This is useful when storing linear RGB color values in an image, because the linear RGB color space has less precision than sRGB for dark colors, which can result in noticeable color banding when drawing.

In general, colors chosen based on what they look like on-screen are already in gamma-space and should not be double-converted. Colors calculated using math are often in the linear RGB space.

Read more about gamma-correct rendering here, here, and here.

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

cr, cg, cb = love.math.linearToGamma( lr, lg, lb )

An alpha value can be passed into the function as a fourth argument, but it will be returned unchanged because alpha is always linear.

cr number The red channel of the converted color in gamma sRGB space.
cg number The green channel of the converted color in gamma sRGB space.
cb number The blue channel of the converted color in gamma sRGB space.
lr number The red channel of the linear RGB color to convert.
lg number The green channel of the linear RGB color to convert.
lb number The blue channel of the linear RGB color to convert.

cr, cg, cb = love.math.linearToGamma( color )

cr number The red channel of the converted color in gamma sRGB space.
cg number The green channel of the converted color in gamma sRGB space.
cb number The blue channel of the converted color in gamma sRGB space.
color table An array with the red, green, and blue channels of the linear RGB color to convert.

c = love.math.linearToGamma( lc )

c number The value of the color channel in gamma sRGB space.
lc number The value of a color channel in linear RGB space to convert.

love.math.newBezierCurve

Creates a new BezierCurve object.

The number of vertices in the control polygon determines the degree of the curve, e.g. three vertices define a quadratic (degree 2) Bézier curve, four vertices define a cubic (degree 3) Bézier curve, etc.

curve = love.math.newBezierCurve( vertices )

curve BezierCurve A Bézier curve object.
vertices table The vertices of the control polygon as a table in the form of {x1, y1, x2, y2, x3, y3, ...}.

curve = love.math.newBezierCurve( x1, y1, x2, y2, x3, y3 )

curve BezierCurve A Bézier curve object.
x1 number The position of the first vertex of the control polygon on the x-axis.
y1 number The position of the first vertex of the control polygon on the y-axis.
x2 number The position of the second vertex of the control polygon on the x-axis.
y2 number The position of the second vertex of the control polygon on the y-axis.
x3 number The position of the third vertex of the control polygon on the x-axis.
y3 number The position of the third vertex of the control polygon on the y-axis.

love.math.newRandomGenerator

Creates a new RandomGenerator object which is completely independent of other RandomGenerator objects and random functions.

rng = love.math.newRandomGenerator()

rng RandomGenerator The new Random Number Generator object.

rng = love.math.newRandomGenerator( seed )

See RandomGenerator:setSeed.

rng RandomGenerator The new Random Number Generator object.
seed number The initial seed number to use for this object.

rng = love.math.newRandomGenerator( low, high )

See RandomGenerator:setSeed.

rng RandomGenerator The new Random Number Generator object.
low number The lower 32 bits of the seed number to use for this object.
high number The higher 32 bits of the seed number to use for this object.

love.math.newTransform

Creates a new Transform object.

transform = love.math.newTransform()

Creates a Transform with no transformations applied. Call methods on the returned object to apply transformations.

transform Transform The new Transform object.

transform = love.math.newTransform( x, y, angle, sx, sy, ox, oy, kx, ky )

Creates a Transform with the specified transformation applied on creation.

transform Transform The new Transform object.
x number The position of the new Transform on the x-axis.
y number The position of the new Transform on the y-axis.
angle (0) number The orientation of the new Transform in radians.
sx (1) number Scale factor on the x-axis.
sy (sx) number Scale factor on the y-axis.
ox (0) number Origin offset on the x-axis.
oy (0) number Origin offset on the y-axis.
kx (0) number Shearing / skew factor on the x-axis.
ky (0) number Shearing / skew factor on the y-axis.

love.math.noise

Generates a Simplex or Perlin noise value in 1-4 dimensions. The return value will always be the same, given the same arguments.

Simplex noise is closely related to Perlin noise. It is widely used for procedural content generation.

There are many webpages which discuss Perlin and Simplex noise in detail.

value = love.math.noise( x )

Generates Simplex noise from 1 dimension.

value number The noise value in the range of 1.
x number The number used to generate the noise value.

value = love.math.noise( x, y )

Generates Simplex noise from 2 dimensions.

value number The noise value in the range of 1.
x number The first value of the 2-dimensional vector used to generate the noise value.
y number The second value of the 2-dimensional vector used to generate the noise value.

value = love.math.noise( x, y, z )

Generates Perlin noise (Simplex noise in version 0.9.2 and older) from 3 dimensions.

value number The noise value in the range of 1.
x number The first value of the 3-dimensional vector used to generate the noise value.
y number The second value of the 3-dimensional vector used to generate the noise value.
z number The third value of the 3-dimensional vector used to generate the noise value.

value = love.math.noise( x, y, z, w )

Generates Perlin noise (Simplex noise in version 0.9.2 and older) from 4 dimensions.

value number The noise value in the range of 1.
x number The first value of the 4-dimensional vector used to generate the noise value.
y number The second value of the 4-dimensional vector used to generate the noise value.
z number The third value of the 4-dimensional vector used to generate the noise value.
w number The fourth value of the 4-dimensional vector used to generate the noise value.

love.math.random

Generates a pseudo-random number in a platform independent manner. The default love.run seeds this function at startup, so you generally don't need to seed it yourself.

number = love.math.random()

Get uniformly distributed pseudo-random real number within 1.

number number The pseudo-random number.

number = love.math.random( max )

Get a uniformly distributed pseudo-random integer within max.

number number The pseudo-random integer number.
max number The maximum possible value it should return.

number = love.math.random( min, max )

Get uniformly distributed pseudo-random integer within max.

number number The pseudo-random integer number.
min number The minimum possible value it should return.
max number The maximum possible value it should return.

love.math.randomNormal

Get a normally distributed pseudo random number.

number = love.math.randomNormal( stddev, mean )

number number Normally distributed random number with variance (stddev)² and the specified mean.
stddev (1) number Standard deviation of the distribution.
mean (0) number The mean of the distribution.

love.math.setRandomSeed

Sets the seed of the random number generator using the specified integer number. This is called internally at startup, so you generally don't need to call it yourself.

love.math.setRandomSeed( seed )

Due to Lua's use of double-precision floating point numbers, integer values above 2^53 cannot be accurately represented. Use the other variant of the function if you want to use a larger number.

seed number The integer number with which you want to seed the randomization. Must be within the range of 2^53 - 1.

love.math.setRandomSeed( low, high )

Combines two 32-bit integer numbers into a 64-bit integer value and sets the seed of the random number generator using the value.

low number The lower 32 bits of the seed value. Must be within the range of 2^32 - 1.
high number The higher 32 bits of the seed value. Must be within the range of 2^32 - 1.

love.math.setRandomState

Sets the current state of the random number generator. The value used as an argument for this function is an opaque implementation-dependent string and should only originate from a previous call to love.math.getRandomState.

This is different from love.math.setRandomSeed in that setRandomState directly sets the random number generator's current implementation-dependent state, whereas setRandomSeed gives it a new seed value.

love.math.setRandomState( state )

The effect of the state string does not depend on the current operating system.

state string The new state of the random number generator, represented as a string. This should originate from a previous call to love.math.getRandomState.

love.math.triangulate

Decomposes a simple convex or concave polygon into triangles.

triangles = love.math.triangulate( polygon )

triangles table List of triangles the polygon is composed of, in the form of {{x1, y1, x2, y2, x3, y3}, {x1, y1, x2, y2, x3, y3}, ...}.
polygon table Polygon to triangulate. Must not intersect itself.

triangles = love.math.triangulate( x1, y1, x2, y2, x3, y3 )

triangles table List of triangles the polygon is composed of, in the form of {{x1, y1, x2, y2, x3, y3}, {x1, y1, x2, y2, x3, y3}, ...}.
x1 number The position of the first vertex of the polygon on the x-axis.
y1 number The position of the first vertex of the polygon on the y-axis.
x2 number The position of the second vertex of the polygon on the x-axis.
y2 number The position of the second vertex of the polygon on the y-axis.
x3 number The position of the third vertex of the polygon on the x-axis.
y3 number The position of the third vertex of the polygon on the y-axis.

CompressedDataFormat

lz4

The LZ4 compression format. Compresses and decompresses very quickly, but the compression ratio is not the best. LZ4-HC is used when compression level 9 is specified. Some benchmarks are available here.

zlib

The zlib format is DEFLATE-compressed data with a small bit of header data. Compresses relatively slowly and decompresses moderately quickly, and has a decent compression ratio.

gzip

The gzip format is DEFLATE-compressed data with a slightly larger header than zlib. Since it uses DEFLATE it has the same compression characteristics as the zlib format.

deflate

Raw DEFLATE-compressed data (no header).

MatrixLayout

row

The matrix is row-major:

column

The matrix is column-major:

BezierCurve

A Bézier curve object that can evaluate and render Bézier curves of arbitrary degree.

For more information on Bézier curves check this great article on Wikipedia.

Functions

Control points

Transform

Supertypes

BezierCurve:evaluate

Evaluate Bézier curve at parameter t. The parameter must be between 0 and 1 (inclusive).

This function can be used to move objects along paths or tween parameters. However it should not be used to render the curve, see BezierCurve:render for that purpose.

x, y = BezierCurve:evaluate( t )

x number x coordinate of the curve at parameter t.
y number y coordinate of the curve at parameter t.
t number Where to evaluate the curve.

BezierCurve:getControlPoint

Get coordinates of the i-th control point. Indices start with 1.

x, y = BezierCurve:getControlPoint( i )

x number Position of the control point along the x axis.
y number Position of the control point along the y axis.
i number Index of the control point.

BezierCurve:getControlPointCount

Get the number of control points in the Bézier curve.

count = BezierCurve:getControlPointCount()

count number The number of control points.

BezierCurve:getDegree

Get degree of the Bézier curve. The degree is equal to number-of-control-points - 1.

degree = BezierCurve:getDegree()

degree number Degree of the Bézier curve.

BezierCurve:getDerivative

Get the derivative of the Bézier curve.

This function can be used to rotate sprites moving along a curve in the direction of the movement and compute the direction perpendicular to the curve at some parameter t.

derivative = BezierCurve:getDerivative()

derivative BezierCurve The derivative curve.

BezierCurve:getSegment

Gets a BezierCurve that corresponds to the specified segment of this BezierCurve.

curve = BezierCurve:getSegment( startpoint, endpoint )

curve BezierCurve A BezierCurve that corresponds to the specified segment.
startpoint number The starting point along the curve. Must be between 0 and 1.
endpoint number The end of the segment. Must be between 0 and 1.

BezierCurve:insertControlPoint

Insert control point as the new i-th control point. Existing control points from i onwards are pushed back by 1. Indices start with 1. Negative indices wrap around: -1 is the last control point, -2 the one before the last, etc.

BezierCurve:insertControlPoint( x, y, i )

x number Position of the control point along the x axis.
y number Position of the control point along the y axis.
i (-1) number Index of the control point.

BezierCurve:removeControlPoint

Removes the specified control point.

BezierCurve:removeControlPoint( index )

index number The index of the control point to remove.

BezierCurve:render

Get a list of coordinates to be used with love.graphics.line.

This function samples the Bézier curve using recursive subdivision. You can control the recursion depth using the depth parameter.

If you are just interested to know the position on the curve given a parameter, use BezierCurve:evaluate.

coordinates = BezierCurve:render( depth )

coordinates table List of x,y-coordinate pairs of points on the curve.
depth (5) number Number of recursive subdivision steps.

BezierCurve:renderSegment

Get a list of coordinates on a specific part of the curve, to be used with love.graphics.line.

This function samples the Bézier curve using recursive subdivision. You can control the recursion depth using the depth parameter.

If you are just need to know the position on the curve given a parameter, use BezierCurve:evaluate.

coordinates = BezierCurve:renderSegment( startpoint, endpoint, depth )

coordinates table List of x,y-coordinate pairs of points on the specified part of the curve.
startpoint number The starting point along the curve. Must be between 0 and 1.
endpoint number The end of the segment to render. Must be between 0 and 1.
depth (5) number Number of recursive subdivision steps.

BezierCurve:rotate

Rotate the Bézier curve by an angle.

BezierCurve:rotate( angle, ox, oy )

angle number Rotation angle in radians.
ox (0) number X coordinate of the rotation center.
oy (0) number Y coordinate of the rotation center.

BezierCurve:scale

Scale the Bézier curve by a factor.

BezierCurve:scale( s, ox, oy )

s number Scale factor.
ox (0) number X coordinate of the scaling center.
oy (0) number Y coordinate of the scaling center.

BezierCurve:setControlPoint

Set coordinates of the i-th control point. Indices start with 1.

BezierCurve:setControlPoint( i, x, y )

i number Index of the control point.
x number Position of the control point along the x axis.
y number Position of the control point along the y axis.

BezierCurve:translate

Move the Bézier curve by an offset.

BezierCurve:translate( dx, dy )

dx number Offset along the x axis.
dy number Offset along the y axis.

CompressedData

Represents byte data compressed using a specific algorithm.

love.data.decompress can be used to de-compress the data (or love.math.decompress in 0.10.2 or earlier).

Functions

Supertypes

CompressedData:getFormat

Gets the compression format of the CompressedData.

format = CompressedData:getFormat()

format CompressedDataFormat The format of the CompressedData.

RandomGenerator

A random number generation object which has its own random state.

Functions

Supertypes

RandomGenerator:getSeed

Gets the seed of the random number generator object.

The seed is split into two numbers due to Lua's use of doubles for all number values - doubles can't accurately represent integer values above 2^53, but the seed value is an integer number in the range of 2^64 - 1.

low, high = RandomGenerator:getSeed()

low number Integer number representing the lower 32 bits of the RandomGenerator's 64 bit seed value.
high number Integer number representing the higher 32 bits of the RandomGenerator's 64 bit seed value.

RandomGenerator:getState

Gets the current state of the random number generator. This returns an opaque string which is only useful for later use with RandomGenerator:setState in the same major version of LÖVE.

This is different from RandomGenerator:getSeed in that getState gets the RandomGenerator's current state, whereas getSeed gets the previously set seed number.

state = RandomGenerator:getState()

The value of the state string does not depend on the current operating system.

state string The current state of the RandomGenerator object, represented as a string.

RandomGenerator:random

Generates a pseudo-random number in a platform independent manner.

number = RandomGenerator:random()

Get uniformly distributed pseudo-random number within 1.

number number The pseudo-random number.

number = RandomGenerator:random( max )

Get uniformly distributed pseudo-random integer number within max.

number number The pseudo-random integer number.
max number The maximum possible value it should return.

number = RandomGenerator:random( min, max )

Get uniformly distributed pseudo-random integer number within max.

number number The pseudo-random integer number.
min number The minimum possible value it should return.
max number The maximum possible value it should return.

RandomGenerator:randomNormal

Get a normally distributed pseudo random number.

number = RandomGenerator:randomNormal( stddev, mean )

number number Normally distributed random number with variance (stddev)² and the specified mean.
stddev (1) number Standard deviation of the distribution.
mean (0) number The mean of the distribution.

RandomGenerator:setSeed

Sets the seed of the random number generator using the specified integer number.

RandomGenerator:setSeed( seed )

Due to Lua's use of double-precision floating point numbers, values above 2^53 cannot be accurately represented. Use the other variant of this function if your seed will have a larger value.

seed number The integer number with which you want to seed the randomization. Must be within the range of 2^53.

RandomGenerator:setSeed( low, high )

Combines two 32-bit integer numbers into a 64-bit integer value and sets the seed of the random number generator using the value.

low number The lower 32 bits of the seed value. Must be within the range of 2^32 - 1.
high number The higher 32 bits of the seed value. Must be within the range of 2^32 - 1.

RandomGenerator:setState

Sets the current state of the random number generator. The value used as an argument for this function is an opaque string and should only originate from a previous call to RandomGenerator:getState in the same major version of LÖVE.

This is different from RandomGenerator:setSeed in that setState directly sets the RandomGenerator's current implementation-dependent state, whereas setSeed gives it a new seed value.

RandomGenerator:setState( state )

The effect of the state string does not depend on the current operating system.

state string The new state of the RandomGenerator object, represented as a string. This should originate from a previous call to RandomGenerator:getState.

Transform

Object containing a coordinate system transformation.

The love.graphics module has several functions and function variants which accept Transform objects.

Functions

Supertypes

Transform:apply

Applies the given other Transform object to this one.

This effectively multiplies this Transform's internal transformation matrix with the other Transform's (i.e. self * other), and stores the result in this object.

transform = Transform:apply( other )

transform Transform The Transform object the method was called on. Allows easily chaining Transform methods.
other Transform The other Transform object to apply to this Transform.

Transform:clone

Creates a new copy of this Transform.

clone = Transform:clone()

clone Transform The copy of this Transform.

Transform:getMatrix

Gets the internal 4x4 transformation matrix stored by this Transform. The matrix is returned in row-major order.

e1_1, e1_2, ..., e4_4 = Transform:getMatrix()

e1_1 number The first column of the first row of the matrix.
e1_2 number The second column of the first row of the matrix.
... number Additional matrix elements.
e4_4 number The fourth column of the fourth row of the matrix.

Transform:inverse

Creates a new Transform containing the inverse of this Transform.

inverse = Transform:inverse()

inverse Transform A new Transform object representing the inverse of this Transform's matrix.

Transform:inverseTransformPoint

Applies the reverse of the Transform object's transformation to the given 2D position.

This effectively converts the given position from the local coordinate space of the Transform into global coordinates.

One use of this method can be to convert a screen-space mouse position into global world coordinates, if the given Transform has transformations applied that are used for a camera system in-game.

globalX, globalY = Transform:inverseTransformPoint( localX, localY )

globalX number The x component of the position in global coordinates.
globalY number The y component of the position in global coordinates.
localX number The x component of the position with the transform applied.
localY number The y component of the position with the transform applied.

Transform:isAffine

Checks whether the Transform is an affine transformation.

affine = Transform:isAffine()

affine boolean true if the transform object is an affine transformation, false otherwise.

Transform:reset

Resets the Transform to an identity state. All previously applied transformations are erased.

transform = Transform:reset()

transform Transform The Transform object the method was called on. Allows easily chaining Transform methods.

Transform:rotate

Applies a rotation to the Transform's coordinate system. This method does not reset any previously applied transformations.

transform = Transform:rotate( angle )

transform Transform The Transform object the method was called on. Allows easily chaining Transform methods.
angle number The relative angle in radians to rotate this Transform by.

Transform:scale

Scales the Transform's coordinate system. This method does not reset any previously applied transformations.

transform = Transform:scale( sx, sy )

transform Transform The Transform object the method was called on. Allows easily chaining Transform methods.
sx number The relative scale factor along the x-axis.
sy (sx) number The relative scale factor along the y-axis.

Transform:setMatrix

Directly sets the Transform's internal 4x4 transformation matrix.

transform = Transform:setMatrix( e1_1, e1_2, ..., e4_4 )

transform Transform The Transform object the method was called on. Allows easily chaining Transform methods.
e1_1 number The first column of the first row of the matrix.
e1_2 number The second column of the first row of the matrix.
... number Additional matrix elements.
e4_4 number The fourth column of the fourth row of the matrix.

transform = Transform:setMatrix( layout, e1_1, e1_2, ..., e4_4 )

transform Transform The Transform object the method was called on. Allows easily chaining Transform methods.
layout MatrixLayout How to interpret the matrix element arguments (row-major or column-major).
e1_1 number The first column of the first row of the matrix.
e1_2 number The second column of the first row or the first column of the second row of the matrix, depending on the specified layout.
... number Additional matrix elements.
e4_4 number The fourth column of the fourth row of the matrix.

transform = Transform:setMatrix( layout, matrix )

transform Transform The Transform object the method was called on. Allows easily chaining Transform methods.
layout MatrixLayout How to interpret the matrix element arguments (row-major or column-major).
matrix table A flat table containing the 16 matrix elements.

transform = Transform:setMatrix( layout, matrix )

transform Transform The Transform object the method was called on. Allows easily chaining Transform methods.
layout MatrixLayout How to interpret the matrix element arguments (row-major or column-major).
matrix table A table of 4 tables, with each sub-table containing 4 matrix elements.

Transform:setTransformation

Resets the Transform to the specified transformation parameters.

transform = Transform:setTransformation( x, y, angle, sx, sy, ox, oy, kx, ky )

transform Transform The Transform object the method was called on. Allows easily chaining Transform methods.
x number The position of the Transform on the x-axis.
y number The position of the Transform on the y-axis.
angle (0) number The orientation of the Transform in radians.
sx (1) number Scale factor on the x-axis.
sy (sx) number Scale factor on the y-axis.
ox (0) number Origin offset on the x-axis.
oy (0) number Origin offset on the y-axis.
kx (0) number Shearing / skew factor on the x-axis.
ky (0) number Shearing / skew factor on the y-axis.

Transform:shear

Applies a shear factor (skew) to the Transform's coordinate system. This method does not reset any previously applied transformations.

transform = Transform:shear( kx, ky )

transform Transform The Transform object the method was called on. Allows easily chaining Transform methods.
kx number The shear factor along the x-axis.
ky number The shear factor along the y-axis.

Transform:transformPoint

Applies the Transform object's transformation to the given 2D position.

This effectively converts the given position from global coordinates into the local coordinate space of the Transform.

localX, localY = Transform:transformPoint( globalX, globalY )

localX number The x component of the position with the transform applied.
localY number The y component of the position with the transform applied.
globalX number The x component of the position in global coordinates.
globalY number The y component of the position in global coordinates.

Transform:translate

Applies a translation to the Transform's coordinate system. This method does not reset any previously applied transformations.

transform = Transform:translate( dx, dy )

transform Transform The Transform object the method was called on. Allows easily chaining Transform methods.
dx number The relative translation along the x-axis.
dy number The relative translation along the y-axis.

love.mouse

Types

Functions

Input

Cursor

Enums

love.mouse.getCursor

Gets the current Cursor.

cursor = love.mouse.getCursor()

cursor Cursor The current cursor, or nil if no cursor is set.

love.mouse.getPosition

Returns the current position of the mouse.

x, y = love.mouse.getPosition()

x number The position of the mouse along the x-axis.
y number The position of the mouse along the y-axis.

love.mouse.getRelativeMode

Gets whether relative mode is enabled for the mouse.

If relative mode is enabled, the cursor is hidden and doesn't move when the mouse does, but relative mouse motion events are still generated via love.mousemoved. This lets the mouse move in any direction indefinitely without the cursor getting stuck at the edges of the screen.

The reported position of the mouse is not updated while relative mode is enabled, even when relative mouse motion events are generated.

enabled = love.mouse.getRelativeMode()

enabled boolean True if relative mode is enabled, false if it's disabled.

love.mouse.getSystemCursor

Gets a Cursor object representing a system-native hardware cursor.

Hardware cursors are framerate-independent and work the same way as normal operating system cursors. Unlike drawing an image at the mouse's current coordinates, hardware cursors never have visible lag between when the mouse is moved and when the cursor position updates, even at low framerates.

cursor = love.mouse.getSystemCursor( ctype )

The 'image' CursorType is not a valid argument. Use love.mouse.newCursor to create a hardware cursor using a custom image.

cursor Cursor The Cursor object representing the system cursor type.
ctype CursorType The type of system cursor to get.

love.mouse.getX

Returns the current x-position of the mouse.

x = love.mouse.getX()

x number The position of the mouse along the x-axis.

love.mouse.getY

Returns the current y-position of the mouse.

y = love.mouse.getY()

y number The position of the mouse along the y-axis.

love.mouse.hasCursor

Gets whether cursor functionality is supported.

If it isn't supported, calling love.mouse.newCursor and love.mouse.getSystemCursor will cause an error. Mobile devices do not support cursors.

hascursor = love.mouse.hasCursor()

hascursor boolean Whether the system has cursor functionality.

love.mouse.isCursorSupported

Gets whether cursor functionality is supported.

If it isn't supported, calling love.mouse.newCursor and love.mouse.getSystemCursor will cause an error. Mobile devices do not support cursors.

supported = love.mouse.isCursorSupported()

supported boolean Whether the system has cursor functionality.

love.mouse.isDown

Checks whether a certain mouse button is down.

This function does not detect mouse wheel scrolling; you must use the love.wheelmoved (or love.mousepressed in version 0.9.2 and older) callback for that.

down = love.mouse.isDown( button, ... )

down boolean True if any specified button is down.
button number The index of a button to check. 1 is the primary mouse button, 2 is the secondary mouse button and 3 is the middle button. Further buttons are mouse dependant.
... number Additional button numbers to check.

anyDown = love.mouse.isDown( buttonN )

anyDown boolean True if any specified button is down, false otherwise.
buttonN MouseConstant A button to check.

love.mouse.isGrabbed

Checks if the mouse is grabbed.

grabbed = love.mouse.isGrabbed()

grabbed boolean True if the cursor is grabbed, false if it is not.

love.mouse.isVisible

Checks if the cursor is visible.

visible = love.mouse.isVisible()

visible boolean True if the cursor to visible, false if the cursor is hidden.

love.mouse.newCursor

Creates a new h