love

audio

event

filesystem

graphics

image

joystick

keyboard

math

mouse

physics

sound

system

thread

timer

touch

video

window

love

Types

Callbacks

Input

Window

Error handling

Functions

love.getVersion

Gets the current running version of LÖVE.

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

majornumberThe major version of LÖVE, i.e. 0 for version 0.9.1.
minornumberThe minor version of LÖVE, i.e. 9 for version 0.9.1.
revisionnumberThe revision version of LÖVE, i.e. 1 for version 0.9.1.
codenamestringThe codename of the current version, i.e. "Baby Inspector" for version 0.9.1.

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 )

ttableThe 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)stringThis 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 ("0.10.2")stringt.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)booleanDetermines 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)booleanSets 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)booleanSets whether files are saved in external storage (true) or internal storage (false) on Android.
t.gammacorrect (false)booleanDetermines whether gamma-correct rendering is enabled, when the system supports it.
t.windowtableIt 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.modulestableModule options.

love.directorydropped

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

love.directorydropped( path )

pathstringThe 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.draw

Callback function used to draw on the screen every frame.

love.draw()

love.errhand

The error handler, used to display error messages.

love.errhand( msg )

msgstringThe error message.

love.filedropped

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

love.filedropped( file )

fileFileThe unopened File object representing the file that was dropped.

love.focus

Callback function triggered when window receives or loses focus.

love.focus( focus )

focusbooleanTrue 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 )

joystickJoystickThe joystick object.
axisGamepadAxisThe virtual gamepad axis.

love.gamepadpressed

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

love.gamepadpressed( joystick, button )

joystickJoystickThe joystick object.
buttonGamepadButtonThe virtual gamepad button.

love.gamepadreleased

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

love.gamepadreleased( joystick, button )

joystickJoystickThe joystick object.
buttonGamepadButtonThe virtual gamepad button.

love.joystickadded

Called when a Joystick is connected.

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

love.joystickadded( joystick )

joystickJoystickThe newly connected Joystick object.

love.joystickaxis

Called when a joystick axis moves.

love.joystickaxis( joystick, axis, value )

joystickJoystickThe joystick object.
axisnumberThe axis number.
valuenumberThe new axis value.

love.joystickhat

Called when a joystick hat direction changes.

love.joystickhat( joystick, hat, direction )

joystickJoystickThe joystick object.
hatnumberThe hat number.
directionJoystickHatThe new hat direction.

love.joystickpressed

Called when a joystick button is pressed.

love.joystickpressed( joystick, button )

joysticknumberThe joystick number.
buttonnumberThe button number.

love.joystickreleased

Called when a joystick button is released.

love.joystickreleased( joystick, button )

joysticknumberThe joystick number.
buttonnumberThe button number.

love.joystickremoved

Called when a Joystick is disconnected.

love.joystickremoved( joystick )

joystickJoystickThe now-disconnected Joystick object.

love.keypressed

Callback function triggered when a key is pressed.

love.keypressed( key, scancode, isrepeat )

keyKeyConstantCharacter of the pressed key.
scancodeScancodeThe scancode representing the pressed key.
isrepeatbooleanWhether 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 )

keyKeyConstantCharacter of the released key.
scancodeScancodeThe scancode representing the released key.

love.load

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

love.load( arg )

argtableCommand line arguments given to the game.

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, and calling collectgarbage()), 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 )

focusbooleanWhether the window has mouse focus or not.

love.mousemoved

Callback function triggered when the mouse is moved.

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

xnumberThe mouse position on the x-axis.
ynumberThe mouse position on the y-axis.
dxnumberThe amount moved along the x-axis since the last time love.mousemoved was called.
dynumberThe amount moved along the y-axis since the last time love.mousemoved was called.
istouchbooleanTrue 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 )

xnumberMouse x position, in pixels.
ynumberMouse y position, in pixels.
buttonnumberThe 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
isTouchbooleanTrue if the mouse button press originated from a touchscreen touch-press.

love.mousereleased

Callback function triggered when a mouse button is released.

love.mousereleased( x, y, button, isTouch )

xnumberMouse x position, in pixels.
ynumberMouse y position, in pixels.
buttonnumberThe 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.
isTouchbooleanTrue if the mouse button press originated from a touchscreen touch-release.

love.quit

Callback function triggered when the game is closed.

r = love.quit()

rbooleanAbort 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.

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.

love.resize( w, h )

wnumberThe new width.
hnumberThe new height.

love.run

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

love.run()

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 )

textstringThe UTF-8 encoded unicode candidate text.
startnumberThe start cursor of the selected candidate text.
lengthnumberThe 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 )

textstringThe UTF-8 encoded unicode text.

love.threaderror

Callback function triggered when a Thread encounters an error.

love.threaderror( thread, errorstr )

threadThreadThe thread which produced the error.
errorstrstringThe error message.

love.touchmoved

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

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

idlight userdataThe identifier for the touch press.
xnumberThe x-axis position of the touch inside the window, in pixels.
ynumberThe y-axis position of the touch inside the window, in pixels.
dxnumberThe x-axis movement of the touch inside the window, in pixels.
dynumberThe y-axis movement of the touch inside the window, in pixels.
pressurenumberThe 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 )

idlight userdataThe identifier for the touch press.
xnumberThe x-axis position of the touch press inside the window, in pixels.
ynumberThe y-axis position of the touch press inside the window, in pixels.
dxnumberThe x-axis movement of the touch press inside the window, in pixels. This should always be zero.
dynumberThe y-axis movement of the touch press inside the window, in pixels. This should always be zero.
pressurenumberThe 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 )

idlight userdataThe identifier for the touch press.
xnumberThe x-axis position of the touch inside the window, in pixels.
ynumberThe y-axis position of the touch inside the window, in pixels.
dxnumberThe x-axis movement of the touch inside the window, in pixels.
dynumberThe y-axis movement of the touch inside the window, in pixels.
pressurenumberThe 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 )

dtnumberTime since the last update in seconds.

love.visible

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

love.visible( visible )

visiblebooleanTrue 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 )

xnumberAmount of horizontal mouse wheel movement. Positive values indicate movement to the right.
ynumberAmount of vertical mouse wheel movement. Positive values indicate upward movement.

Data

The superclass of all data.

Functions

Supertypes

Subtypes

Data:getPointer

Gets a pointer to the Data.

pointer = Data:getPointer()

pointerlight userdataA raw pointer to the Data.

Data:getSize

Gets the size of the Data.

size = Data:getSize()

sizenumberThe size of the Data in bytes.

Data:getString

Gets the full Data as a string.

data = Data:getString()

datastringThe raw data.

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.

Functions

Subtypes

Object:type

Gets the type of the object as a string.

type = Object:type()

typestringThe type as a string.

Object:typeOf

Checks whether an object is of a certain type. If the object has the type with the specified name in its hierarchy, this function will return true.

b = Object:typeOf( name )

bbooleanTrue if the object is of the specified type, false otherwise.
namestringThe name of the type to check for.

love.audio

Types

Functions

Enums

love.audio.getDistanceModel

Gets the distance attenuation model.

model = love.audio.getDistanceModel()

modelDistanceModelThe 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()

scalenumberThe current doppler scale factor.

love.audio.getSourceCount

Gets the number of sources which are currently playing or paused.

numSources = love.audio.getSourceCount()

numSourcesnumberThe number of sources which are currently playing or paused.

love.audio.getOrientation

Gets the orientation of the listener.

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

fxnumberThe X component of the forward vector of the listener orientation.
fynumberThe Y component of the forward vector of the listener orientation.
fznumberThe Z component of the forward vector of the listener orientation.
uxnumberThe X component of the up vector of the listener orientation.
uynumberThe Y component of the up vector of the listener orientation.
uznumberThe Z component of the up vector of the listener orientation.

love.audio.getPosition

Gets the position of the listener.

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

xnumberThe X position of the listener.
ynumberThe Y position of the listener.
znumberThe Z position of the listener.

love.audio.getVelocity

Gets the velocity of the listener.

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

xnumberThe X velocity of the listener.
ynumberThe Y velocity of the listener.
znumberThe Z velocity of the listener.

love.audio.getVolume

Gets the master volume.

volume = love.audio.getVolume()

volumenumberThe current master volume.

love.audio.newSource

Creates a new Source from a file or SoundData. Sources created from SoundData are always static.

source = love.audio.newSource( file, type )

sourceSourceA new Source that can play the specified audio.
filestring / FileThe path/File to create a Source from.
type ("stream")SourceTypeStreaming or static source.

source = love.audio.newSource( soundData )

sourceSourceA new Source that can play the specified audio. The SourceType of the returned audio is "static".
soundDataSoundData / FileDataThe SoundData/FileData to create a Source from.

love.audio.pause

Pauses currently played Sources.

love.audio.pause()

This function will pause all currently active Sources.

love.audio.pause( source )

This function will only pause the specified Source.

sourceSourceThe source on which to pause the playback.

love.audio.play

Plays the specified Source.

love.audio.play( source )

sourceSourceThe Source to play.

love.audio.resume

Resumes all audio

love.audio.resume()

love.audio.resume( source )

sourceSourceThe source on which to resume the playback.

love.audio.rewind

Rewinds all playing audio.

love.audio.rewind()

love.audio.rewind( source )

sourceSourceThe source to rewind.

love.audio.setDistanceModel

Sets the distance attenuation model.

love.audio.setDistanceModel( model )

modelDistanceModelThe 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 )

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

love.audio.setOrientation

Sets the orientation of the listener.

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

fxnumberThe X component of the forward vector of the listener orientation.
fynumberThe Y component of the forward vector of the listener orientation.
fznumberThe Z component of the forward vector of the listener orientation.
uxnumberThe X component of the up vector of the listener orientation.
uynumberThe Y component of the up vector of the listener orientation.
uznumberThe Z component of the 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 )

xnumberThe X position of the listener.
ynumberThe Y position of the listener.
znumberThe Z position of the listener.

love.audio.setVelocity

Sets the velocity of the listener.

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

xnumberThe X velocity of the listener.
ynumberThe Y velocity of the listener.
znumberThe Z velocity of the listener.

love.audio.setVolume

Sets the master volume.

love.audio.setVolume( volume )

volumenumber1.0f is max and 0.0f 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.

sourceSourceThe source on which to stop the playback.

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.

SourceType

static

Decode the entire sound at once.

stream

Stream the sound; decode it gradually.

TimeUnit

seconds

Regular seconds.

samples

Audio samples.

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.

Constructors

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.

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

source = Source:clone()

sourceSourceThe new identical copy of this Source.

Source:getAttenuationDistances

Gets the reference and maximum distance of the source.

ref, max = Source:getAttenuationDistances()

refnumberThe reference distance.
maxnumberThe maximum distance.

Source:getChannels

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

channels = Source:getChannels()

channelsnumber1 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()

innerAnglenumberThe 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.
outerAnglenumberThe 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.
outerVolumenumberThe 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()

xnumberThe X part of the direction vector.
ynumberThe Y part of the direction vector.
znumberThe 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 )

durationnumberThe duration of the Source, or -1 if it cannot be determined.
unit ("seconds")TimeUnitThe time unit for the return value.

Source:getPitch

Gets the current pitch of the Source.

pitch = Source:getPitch()

pitchnumberThe pitch, where 1.0 is normal.

Source:getPosition

Gets the position of the Source.

x, y, z = Source:getPosition()

xnumberThe X position of the Source.
ynumberThe Y position of the Source.
znumberThe Z position of the Source.

Source:getRolloff

Gets the rolloff factor of the source.

rolloff = Source:getRolloff()

rolloffnumberThe rolloff factor.

Source:getType

Gets the type (static or stream) of the Source.

sourcetype = Source:getType()

sourcetypeSourceTypeThe type of the source.

Source:getVelocity

Gets the velocity of the Source.

x, y, z = Source:getVelocity()

xnumberThe X part of the velocity vector.
ynumberThe Y part of the velocity vector.
znumberThe Z part of the velocity vector.

Source:getVolume

Gets the current volume of the Source.

volume = Source:getVolume()

volumenumberThe volume of the Source, where 1.0 is normal volume.

Source:getVolumeLimits

Gets the volume limits of the source.

min, max = Source:getVolumeLimits()

minnumberThe minimum volume.
maxnumberThe maximum volume.

Source:isLooping

Gets whether the Source will loop.

loop = Source:isLooping()

loopbooleanTrue if the Source will loop, false otherwise.

Source:isPaused

Gets whether the Source is paused.

paused = Source:isPaused()

pausedbooleanTrue if the Source is paused, false otherwise.

Source:isPlaying

Gets whether the Source is playing.

playing = Source:isPlaying()

playingbooleanTrue if the Source is playing, false otherwise.

Source:isStopped

Gets whether the Source is stopped.

stopped = Source:isStopped()

stoppedbooleanTrue if the Source is stopped, false otherwise.

Source:pause

Pauses the Source.

Source:pause()

Source:play

Starts playing the Source.

success = Source:play()

successbooleanTrue if the Source started playing successfully, false otherwise.

Source:resume

Resumes a paused Source.

Source:resume()

Source:rewind

Rewinds a Source.

Source:rewind()

Source:seek

Sets the playing position of the Source.

Source:seek( position, unit )

positionnumberThe position to seek to.
unit ("seconds")TimeUnitThe unit of the position value.

Source:setDirection

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

Source:setDirection( x, y, z )

xnumberThe X part of the direction vector.
ynumberThe Y part of the direction vector.
znumberThe Z part of the direction vector.

Source:setAttenuationDistances

Sets the reference and maximum distance of the source.

Source:setAttenuationDistances( ref, max )

refnumberThe new reference distance.
maxnumberThe new maximum 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 )

innerAnglenumberThe 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.
outerAnglenumberThe 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)numberThe Source's volume when the listener is outside both the inner and outer cone angles.

Source:setLooping

Sets whether the Source should loop.

Source:setLooping( loop )

loopbooleanTrue if the source should loop, false otherwise.

Source:setPitch

Sets the pitch of the Source.

Source:setPitch( pitch )

pitchnumberCalculated 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.

Source:setPosition( x, y, z )

xnumberThe X position of the Source.
ynumberThe Y position of the Source.
znumberThe Z position of the Source.

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 )

rolloffnumberThe new rolloff factor.

Source:setVelocity

Sets the velocity of the Source.

This does not change the position of the Source, but is used to calculate the doppler effect.

Source:setVelocity( x, y, z )

xnumberThe X part of the velocity vector.
ynumberThe Y part of the velocity vector.
znumberThe Z part of the velocity vector.

Source:setVolume

Sets the volume of the Source.

Source:setVolume( volume )

volumenumberThe volume of the Source, where 1.0 is normal volume.

Source:setVolumeLimits

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

Source:setVolumeLimits( min, max )

minnumberThe minimum volume.
maxnumberThe maximum volume.

Source:stop

Stops a Source.

Source:stop()

Source:tell

Gets the currently playing position of the Source.

position = Source:tell( unit )

positionnumberThe currently playing position of the Source.
unit ("seconds")TimeUnitThe type of unit for the return value.

love.event

Functions

Enums

love.event.clear

Clears the event queue.

love.event.clear()

love.event.poll

Gets an iterator for messages in the event queue.

i = love.event.poll()

ifunctionIterator 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 can only be called from the main thread, but afterwards, the rest of love.event can be used from any other thread.

love.event.pump()

love.event.push

Adds an event to the event queue.

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

eEventThe name of the event.
a (nil)VariantFirst event argument.
b (nil)VariantSecond event argument.
c (nil)VariantThird event argument.
d (nil)VariantFourth event argument.

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()

love.event.quit( exitstatus )

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

love.event.quit( "restart" )

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

love.event.wait

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

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

eEventThe type of event.
aVariantFirst event argument.
bVariantSecond event argument.
cVariantThird event argument.
dVariantFourth event argument.

Event

focus

Window focus gained or lost

joystickaxis

Joystick axis motion

joystickhat

Joystick hat pressed

joystickpressed

Joystick pressed

joystickreleased

Joystick released

keypressed

Key pressed

keyreleased

Key released

mousefocus

Window mouse focus gained or lost

mousepressed

Mouse pressed

mousereleased

Mouse released

resize

Window size changed by the user

threaderror

A Lua error has occurred in a thread.

quit

Quit

visible

Window is minimized or un-minimized by the user

love.filesystem

Types

Functions

Enums

love.filesystem.append

Append data to an existing file.

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

successbooleanTrue if the operation was successful, or nil if there was an error.
errormsgstringThe error message on failure.
namestringThe name (and path) of the file.
datastringThe data that should be written to the file
size (all)numberHow many bytes to write.

love.filesystem.areSymlinksEnabled

Gets whether love.filesystem follows symbolic links.

enable = love.filesystem.areSymlinksEnabled()

enablebooleanWhether love.filesystem follows symbolic links.

love.filesystem.createDirectory

Creates a directory.

success = love.filesystem.createDirectory( name )

successbooleanTrue if the directory was created, false if not.
namestringThe directory to create.

love.filesystem.exists

Check whether a file or directory exists.

exists = love.filesystem.exists( filename )

existsbooleanTrue if there is a file or directory with the specified name. False otherwise.
filenamestringThe path to a potential file or directory.

love.filesystem.getAppdataDirectory

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

path = love.filesystem.getAppdataDirectory()

pathstringThe path of the application data directory.

love.filesystem.getDirectoryItems

Gets 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.

items = love.filesystem.getDirectoryItems( dir )

itemstableA sequence with the names of all files and subdirectories as strings.
dirstringThe directory.

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 location.

love.filesystem.getIdentity( name )

namestringThe identity that is used as write directory.

love.filesystem.getLastModified

Gets the last modification time of a file.

modtime, errormsg = love.filesystem.getLastModified( filename )

modtimenumberThe last modification time in seconds since the unix epoch or nil on failure.
errormsgstringThe error message on failure.
filenamestringThe path and name to a file.

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 )

realdirstringThe platform-specific full path of the directory containing the filepath.
filepathstringThe 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()

pathsstringThe 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.

path = love.filesystem.getSaveDirectory()

pathstringThe absolute path to the save directory.

love.filesystem.getSize

Gets the size in bytes of a file.

size, errormsg = love.filesystem.getSize( filename )

sizenumberThe size in bytes of the file, or nil on failure.
errormsgstringThe error message on failure.
filenamestringThe path and name to a file.

love.filesystem.getSource

Gets 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()

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

love.filesystem.getSourceBaseDirectory

Gets 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 readable by love.filesystem.

path = love.filesystem.getSourceBaseDirectory()

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

love.filesystem.getUserDirectory

Gets the path of the user's directory.

path = love.filesystem.getUserDirectory()

pathstringThe path of the user's directory.

love.filesystem.getWorkingDirectory

Gets the current working directory.

path = love.filesystem.getWorkingDirectory()

pathstringThe current working directory.

love.filesystem.init

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

love.filesystem.init( appname )

appnamestringThe name of the application binary, typically love.

love.filesystem.isDirectory

Check whether something is a directory.

isDir = love.filesystem.isDirectory( path )

isDirbooleanTrue if there is a directory with the specified name. False otherwise.
pathstringThe path to a potential directory.

love.filesystem.isFile

Check whether something is a file.

isFile = love.filesystem.isFile( path )

isFilebooleanTrue if there is a file with the specified name. False otherwise.
pathstringThe path to a potential file.

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()

fusedbooleanTrue if the game is in fused mode, false otherwise.

love.filesystem.isSymlink

Gets whether a filepath is actually a symbolic link.

If symbolic links are not enabled (via love.filesystem.setSymlinksEnabled), this function will always return false.

symlink = love.filesystem.isSymlink( path )

symlinkbooleanTrue if the path is a symbolic link, false otherwise.
pathstringThe file or directory path to check.

love.filesystem.lines

Iterate over the lines in a file.

iterator = love.filesystem.lines( name )

iteratorfunctionA function that iterates over all the lines in the file.
namestringThe name (and path) of the file.

love.filesystem.load

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

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

chunkfunctionThe loaded chunk.
namestringThe name (and path) of the file.
errormsg (nil)stringThe error message if file could not be opened.

love.filesystem.mount

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

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

successbooleanTrue if the archive was successfully mounted, false otherwise.
archivestringThe folder or zip file in the game's save directory to mount.
mountpointstringThe new path the archive will be mounted to.
appendToPath (false)stringWhether 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, errorstr = love.filesystem.newFile( filename, mode )

fileFileThe new File object, or nil if an error occurred.
errorstrstringThe error string if an error occurred.
filenamestringThe filename of the file to read.
mode ("c")FileModeThe mode to open the file in.

love.filesystem.newFileData

Creates a new FileData object.

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

dataFileDataYour new FileData.
contentsstringThe contents of the file.
namestringThe name of the file.
decoder ("file")FileDecoderThe method to use when decoding the contents.

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

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

dataFileDataThe new FileData, or nil if an error occurred.
errstringThe error string, if an error occurred.
filepathstringPath to the file.

love.filesystem.read

Read the contents of a file.

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

contentsstringThe file contents.
sizenumberHow many bytes have been read.
namestringThe name (and path) of the file.
bytes (all)numberHow many bytes to read.

love.filesystem.remove

Removes a file or directory.

success = love.filesystem.remove( name )

successbooleanTrue if the file/directory was removed, false otherwise.
namestringThe file or directory to remove.

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, appendToPath )

namestringThe new identity that will be used as write directory.
appendToPath (false)booleanWhether the identity directory will be searched when reading a filepath before or after the game's source directory and any currently mounted archives.

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 )

pathsstringThe 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 )

pathstringAbsolute 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 )

enablebooleanWhether 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 )

successbooleanTrue if the archive was successfully unmounted, false otherwise.
archivestringThe folder or zip file in the game's save directory which is currently mounted.

love.filesystem.write

Write data to a file.

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.

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

successbooleanIf the operation was successful.
messagestringError message if operation was unsuccessful.
namestringThe name (and path) of the file.
datastringThe string data to write to the file.
size (all)numberHow many bytes to write.

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

successbooleanIf the operation was successful.
messagestringError message if operation was unsuccessful.
namestringThe name (and path) of the file.
dataDataThe Data object to write to the file.
size (all)numberHow 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.)

File

Represents a file on the filesystem.

Constructors

Functions

Supertypes

File:close

Closes a file.

success = File:close()

successbooleanWhether closing was successful.

File:flush

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

success, err = File:flush()

successbooleanWhether the file successfully flushed any buffered data to the disk.
errstringThe 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()

modeBufferModeThe current buffer mode of the file.
sizenumberThe 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()

filenamestringThe filename of the File.

File:getMode

Gets the FileMode the file has been opened with.

mode = File:getMode()

modeFileModeThe mode this file has been opened with.

File:getSize

Gets the file size.

size = File:getSize()

sizenumberThe file size

File:isEOF

Gets whether end-of-file has been reached.

eof = File:isEOF()

eofbooleanWhether EOF has been reached.

File:isOpen

Gets whether the file is open.

open = File:isOpen()

openbooleanTrue if the file is currently open, false otherwise.

File:lines

Iterate over all the lines in a file

iterator = File:lines()

iteratorfunctionThe iterator (can be used in for loops)

File:open

Open the file for write, read or append.

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.

success = File:open( mode )

successbooleanTrue on success, false otherwise.
modeFileModeThe mode to open the file in.

File:read

Read a number of bytes from a file.

contents, size = File:read( bytes )

contentsstringThe contents of the read bytes.
sizenumberHow many bytes have been read.
bytes (all)numberThe number of bytes to read

File:seek

Seek to a position in a file.

success = File:seek( position )

successbooleanWhether the operation was successful.
positionnumberThe 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.

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

successbooleanWhether the buffer mode was successfully set.
errorstrstringThe error string, if the buffer mode could not be set and an error occurred.
modeBufferModeThe buffer mode to use.
size (0)numberThe maximum size in bytes of the file's buffer.

File:tell

Gets the position in the file.

pos = File:tell()

posnumberThe current position.

File:write

Write data to a file.

success = File:write( data, size )

successbooleanWhether the operation was successful.
datastringThe data to write.
size (all)numberHow many bytes to write.

FileData

Data representing the contents of a file.

Constructors

Functions

Supertypes

FileData:getExtension

Gets the extension of the FileData.

ext = FileData:getExtension()

extstringThe extension of the file the FileData represents.

FileData:getFilename

Gets the filename of the FileData.

name = FileData:getFilename()

namestringThe name of the file the FileData represents.

love.graphics

Types

Functions

Drawing

Stencil

Graphics state

Coordinate system

Window

Info

Other

Enums

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, arctype, x, y, radius, angle1, angle2, segments )

drawmodeDrawModeHow to draw the arc.
arctype ("pie")ArcTypeThe type of arc to draw.
xnumberThe position of the center along x-axis.
ynumberThe position of the center along y-axis.
radiusnumberRadius of the arc.
angle1numberThe angle at which the arc begins.
angle2numberThe angle at which the arc terminates.
segments (10)numberThe number of segments used for drawing the arc.

love.graphics.circle

Draws a circle.

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

modeDrawModeHow to draw the circle.
xnumberThe position of the center along x-axis.
ynumberThe position of the center along y-axis.
radiusnumberThe radius of the circle.

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

modeDrawModeHow to draw the circle.
xnumberThe position of the center along x-axis.
ynumberThe position of the center along y-axis.
radiusnumberThe radius of the circle.
segmentsnumberThe 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 to the background color in LÖVE 0.9.2 and earlier, or to the specified color in 0.10.0 and newer.

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.

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 )

Clears the screen or active Canvas to the specified color.

rnumberThe red channel of the color to clear the screen to.
gnumberThe green channel of the color to clear the screen to.
bnumberThe blue channel of the color to clear the screen to.
a (255)numberThe alpha channel of the color to clear the screen to.

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

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

colortableA table in the form of {r, g, b, a} containing the color to clear the first active Canvas to.
...tableAdditional tables for each active Canvas.

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)booleanWhether to discard the texture(s) of the active Canvas(es) (the contents of the screen if no Canvas is active).
discardstencil (true)booleanWhether to discard the contents of the stencil buffer of the screen / active Canvas.

love.graphics.discard( discardcolors, discardstencil )

discardcolorstableAn array containing boolean values indicating whether to discard the texture of each active Canvas, when multiple simultaneous Canvases are active.
discardstencil (true)booleanWhether 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, 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.

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

drawableDrawableA drawable object.
x (0)numberThe position to draw the object (x-axis).
y (0)numberThe position to draw the object (y-axis).
r (0)numberOrientation (radians).
sx (1)numberScale factor (x-axis). Can be negative.
sy (sx)numberScale factor (y-axis). Can be negative.
ox (0)numberOrigin offset (x-axis). (A value of 20 would effectively move your drawable object 20 pixels to the left.)
oy (0)numberOrigin offset (y-axis). (A value of 20 would effectively move your drawable object 20 pixels up.)
kx (0)numberShearing factor (x-axis).
ky (0)numberShearing factor (y-axis).

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

textureTextureA Texture (Image or Canvas) to texture the Quad with.
quadQuadThe Quad to draw on screen.
x (0)numberThe position to draw the object (x-axis).
y (0)numberThe position to draw the object (y-axis).
r (0)numberOrientation (radians).
sx (1)numberScale factor (x-axis). Can be negative.
sy (sx)numberScale factor (y-axis). Can be negative.
ox (0)numberOrigin offset (x-axis).
oy (0)numberOrigin offset (y-axis)
kx (0)numberShearing factor (x-axis).
ky (0)numberShearing factor (y-axis).

love.graphics.ellipse

Draws an ellipse.

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

modeDrawModeHow to draw the ellipse.
xnumberThe position of the center along x-axis.
ynumberThe position of the center along y-axis.
radiusxnumberThe radius of the ellipse along the x-axis (half the ellipse's width).
radiusynumberThe radius of the ellipse along the y-axis (half the ellipse's height).
segments (based on size)numberThe number of segments used for drawing the ellipse.

love.graphics.getBackgroundColor

Gets the current background color.

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

rnumberThe red component (0-255).
gnumberThe green component (0-255).
bnumberThe blue component (0-255).
anumberThe alpha component (0-255).

love.graphics.getBlendMode

Gets the blending mode.

mode, alphamode = love.graphics.getBlendMode()

modeBlendModeThe current blend mode.
alphamodeBlendAlphaModeThe 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()

canvasCanvasThe 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()

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

love.graphics.getColor

Gets the current color.

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

rnumberThe red component (0-255).
gnumberThe red component (0-255).
bnumberThe blue component (0-255).
anumberThe alpha component (0-255).

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()

rbooleanWhether the red color component is active when rendering.
gbooleanWhether the green color component is active when rendering.
bbooleanWhether the blue color component is active when rendering.
abooleanWhether the alpha color component is active when rendering.

love.graphics.getCompressedImageFormats

Gets the available compressed image formats, and whether each is supported.

formats = love.graphics.getCompressedImageFormats()

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

love.graphics.getDefaultFilter

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

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

minFilterModeFilter mode used when scaling the image down.
magFilterModeFilter mode used when scaling the image up.
anisotropynumberMaximum amount of Anisotropic Filtering used.

love.graphics.getDimensions

Gets the width and height of the window.

width, height = love.graphics.getDimensions()

widthnumberThe width of the window.
heightnumberThe height of the window.

love.graphics.getFont

Gets the current Font object.

font = love.graphics.getFont()

fontFontThe current Font, or nil if none is set.

love.graphics.getHeight

Gets the height of the window.

height = love.graphics.getHeight()

heightnumberThe height of the window.

love.graphics.getLineJoin

Gets the line join style.

join = love.graphics.getLineJoin()

joinLineJoinThe LineJoin style.

love.graphics.getLineStyle

Gets the line style.

style = love.graphics.getLineStyle()

styleLineStyleThe current line style.

love.graphics.getLineWidth

Gets the current line width.

width = love.graphics.getLineWidth()

widthnumberThe current line width.

love.graphics.getShader

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

shader = love.graphics.getShader()

shaderShaderThe current Shader.

love.graphics.getStats

Gets performance-related rendering statistics.

stats = love.graphics.getStats()

statstableA table with the following fields:
stats.drawcallsnumberThe number of draw calls made so far during the current frame.
stats.canvasswitchesnumberThe number of times the active Canvas has been switched so far during the current frame.
stats.texturememorynumberThe estimated total size in bytes of video memory used by all loaded Images, Canvases, and Fonts.
stats.imagesnumberThe number of Image objects currently loaded.
stats.canvasesnumberThe number of Canvas objects currently loaded.
stats.fontsnumberThe number of Font objects currently loaded.
stats.shaderswitchesnumberThe number of times the active Shader has been changed so far during the current frame.

love.graphics.getStencilTest

Gets whether stencil testing is enabled.

When stencil testing is enabled, the geometry of everything that is drawn will be clipped / stencilled out based on whether it intersects with what has been previously drawn to the stencil buffer.

Each Canvas has its own stencil buffer.

enabled, inverted = love.graphics.getStencilTest()

enabledbooleanWhether stencil testing is enabled.
invertedbooleanWhether the stencil test is inverted or not.

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()

featurestableA 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()

limitstableA table containing GraphicsLimit keys, and number values.

love.graphics.getPointSize

Gets the point size.

size = love.graphics.getPointSize()

sizenumberThe current point size.

love.graphics.getRendererInfo

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

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

namestringThe name of the renderer, e.g. "OpenGL" or "OpenGL ES".
versionstringThe version of the renderer with some extra driver-dependent version info, e.g. "2.1 INTEL-8.10.44".
vendorstringThe name of the graphics card vendor, e.g. "Intel Inc".
devicestringThe 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()

xnumberThe x component of the top-left point of the box.
ynumberThe y component of the top-left point of the box.
widthnumberThe width of the box.
heightnumberThe height of the box.

love.graphics.getWidth

Gets the width of the window.

width = love.graphics.getWidth()

widthnumberThe 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 )

Limits the drawing area to a specified rectangle.

xnumberThe x-coordinate of the upper left corner of the rectangle to intersect with the existing scissor rectangle.
ynumberThe y-coordinate of the upper left corner of the rectangle to intersect with the existing scissor rectangle.
widthnumberThe width of the rectangle to intersect with the existing scissor rectangle.
heightnumberThe height of the rectangle to intersect with the existing scissor rectangle.

love.graphics.intersectScissor()

Disables scissor.

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()

gammacorrectbooleanTrue 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()

wireframebooleanTrue 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, ... )

x1numberThe position of first point on the x-axis.
y1numberThe position of first point on the y-axis.
x2numberThe position of second point on the x-axis.
y2numberThe position of second point on the y-axis.
...numberYou can continue passing point positions to draw a polyline.

love.graphics.line( points )

pointstableA table of point positions.

love.graphics.newCanvas

Creates a new Canvas object for offscreen rendering.

Antialiased Canvases have slightly higher system requirements than normal Canvases. Additionally, the supported maximum number of MSAA samples varies depending on the system. Use love.graphics.getSystemLimit 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 = love.graphics.newCanvas( width, height, format, msaa )

canvasCanvasA new Canvas object.
width (window width)numberThe width of the Canvas.
height (window height)numberThe height of the Canvas.
format ("normal")CanvasFormatThe desired texture mode of the Canvas.
msaa (0)numberThe desired number of antialiasing samples used when drawing to the Canvas.

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.

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

fontFontA Font object which can be used to draw text on screen.
filestring / File / FileDataThe file/File/FileData of the TrueType font file.
size (12)numberThe size of the font in pixels.

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

fontFontA Font object which can be used to draw text on screen.
filestring / File / FileDataThe path/File/FileData of the BMFont file.
imagefilename (path inside BMFont file)string / File / FileDataThe path/File/FileData of the BMFont's image file.

font = love.graphics.newFont( size )

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

fontFontA Font object which can be used to draw text on screen.
sizenumberThe size of the font in pixels.

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.

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

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

meshMeshThe new Mesh.
vertexformat (none)tableA table in the form of {attribute, ...}. Each attribute is a table which specifies a custom vertex attribute used for each vertex.
vertexformat.attributetableA 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....tableAdditional vertex attribute format tables.
verticestableThe 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.attributecomponentnumberThe first component of the first vertex attribute in the vertex.
vertices....numberAdditional components of all vertex attributes in the vertex.
mode ("fan")MeshDrawModeHow the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.
usage ("dynamic")SpriteBatchUsageThe 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.

meshMeshThe new Mesh.
vertexformat (none)tableA table in the form of {attribute, ...}. Each attribute is a table which specifies a custom vertex attribute used for each vertex.
vertexformat.attributetableA 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....tableAdditional vertex attribute format tables.
vertexcountnumberThe total number of vertices the Mesh will use.
mode ("fan")MeshDrawModeHow the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.
usage ("dynamic")SpriteBatchUsageThe expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.

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.

Images using CompressedImageData will use it to reload itself when love.window.setMode is called.

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

imageImageAn Image object which can be drawn on screen.
filepath / File / FileData / ImageData / CompressedImageDataThe file path/File/FileData/ImageData/CompressedImageData of the image.
flagstableA table containing the following fields:
flags.linear (false)booleanTrue 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 tableIf 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.

love.graphics.newImageFont

Creates a new Font by loading a 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( file, glyphs, extraspacing )

fontFontA Font object which can be used to draw text on screen.
filepath / File / FileDataThe file path/File/FileData of the image file.
glyphsstringA string of the characters in the image in order from left to right.
extraspacing (0)numberAdditional spacing (positive or negative) to apply to each glyph in the Font.

love.graphics.newParticleSystem

Creates a new ParticleSystem.

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

systemParticleSystemA new ParticleSystem.
textureTextureThe Image or Canvas to use.
buffer (1000)numberThe max number of particles at the same time.

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.

Vertex shader code must contain at least one function, named position, which is the function that will produce transformed vertex positions of drawn objects in screen-space.

Pixel shader code must contain at least one function, named effect, which is the function that will produce the color which is blended onto the screen for each pixel a drawn object touches.

shader = love.graphics.newShader( code )

shaderShaderA Shader object for use in drawing operations.
codestring / File / FileDataThe pixel shader or vertex shader code, or a file with the code.

shader = love.graphics.newShader( pixelcode, vertexcode )

shaderShaderA Shader object for use in drawing operations.
pixelcodestring / File / FileDataThe pixel shader code, or a file with the code.
vertexcodestring / File / FileDataThe vertex shader code, or a file with the code.

love.graphics.newText

Creates a new Font.

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

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

love.graphics.newQuad

Creates a new Quad.

The purpose of a Quad is to describe the result of the following transformation on any drawable object. The object is first scaled to dimensions sw * sh. The Quad then describes the rectangular area of dimensions width * height whose upper left corner is at position (x, y) inside the scaled object.

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

quadQuadThe new Quad.
xnumberThe top-left position along the x-axis.
ynumberThe top-left position along the y-axis.
widthnumberThe width of the Quad.
heightnumberThe height of the Quad.
swnumberThe reference width, the width of the Image.
shnumberThe reference height, the height of the Image.

love.graphics.newScreenshot

Creates a screenshot and returns the image data.

screenshot = love.graphics.newScreenshot( copyAlpha )

screenshotImageDataThe image data of the screenshot.
copyAlpha (false)booleanWhether to include the screen's alpha channel in the ImageData. If false, the screenshot will be fully opaque.

love.graphics.newSpriteBatch

Creates a new SpriteBatch object.

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

spriteBatchSpriteBatchThe new SpriteBatch.
textureTextureThe Image or Canvas to use for the sprites.
maxsprites (1000)numberThe max number of sprites.
usage ("dynamic")SpriteBatchUsageThe expected usage of the SpriteBatch. The specified usage mode affects the SpriteBatch's memory usage and performance.

love.graphics.newVideo

Creates a new drawable Video. Currently only Ogg Theora video files are supported.

video = love.graphics.newVideo( file, loadaudio )

videoVideoA new Video.
filestring / FileThe file path/File of the Ogg Theora video file.
loadaudio (nil)booleanWhether to try to load the video's audio into an audio Source. If not explicitly set to true or false, it will try without causing an error if the video has no audio.

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, ... )

xnumberThe position of the first point on the x-axis.
ynumberThe position of the first point on the y-axis.
...numberThe x and y coordinates of additional points.

love.graphics.points( points )

pointstableA table containing multiple point positions, in the form of {x, y, ...}.
points.xnumberThe position of the first point on the x-axis.
points.ynumberThe position of the first point on the y-axis.
points....numberThe x and y coordinates of additional points.

love.graphics.points( points )

pointstableA table containing multiple individually colored points, in the form of {point, ...}. Each table contains the position and color of a point in the form of {x, y, r, g, b, a}. The color components are optional.
points.pointtableA 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....tableAdditional 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.

When in fill mode, the polygon must be convex and simple or rendering artifacts may occur.

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

modeDrawModeHow to draw the polygon.
...numberThe vertices of the polygon.

love.graphics.polygon( mode, vertices )

modeDrawModeHow to draw the polygon.
verticestableThe 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. For an example, see the description of love.graphics.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()

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 suppport UTF-8 encoding. You'll also need a proper Font for special characters.

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

textstringThe text to draw.
xnumberThe position to draw the object (x-axis).
ynumberThe position to draw the object (y-axis).
r (0)numberOrientation (radians).
sx (1)numberScale factor (x-axis).
sy (sx)numberScale factor (y-axis).
ox (0)numberOrigin offset (x-axis).
oy (0)numberOrigin offset (y-axis).
kx (0)numberShear factor (x-axis).
ky (0)numberShear factor (y-axis).

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

coloredtexttableA table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1tableA 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.string1stringA string of text which has a color specified by the previous color.
coloredtext.color2tableA 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.string2stringA string of text which has a color specified by the previous color.
coloredtext....tables and stringsAdditional colors and strings.
xnumberThe position of the new text on the x-axis.
ynumberThe position of the new text on the y-axis.
angle (0)numberThe orientation of the object in radians.
sx (1)numberScale factor on the x-axis.
sy (sx)numberScale factor on the y-axis.
ox (0)numberOrigin offset on the x-axis.
oy (0)numberOrigin offset on the y-axis.
kx (0)numberShearing / skew factor on the x-axis.
ky (0)numberShearing / skew factor on the y-axis.

love.graphics.printf

Draws formatted text, with word wrap and alignment.

See additional notes in love.graphics.print.

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.

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

textstringA text string.
xnumberThe position on the x-axis.
ynumberThe position on the y-axis.
limitnumberWrap the line after this many horizontal pixels.
align ("left")AlignModeThe alignment.
r (0)numberOrientation (radians).
sx (1)numberScale factor (x-axis).
sy (sx)numberScale factor (y-axis).
ox (0)numberOrigin offset (x-axis).
oy (0)numberOrigin offset (y-axis).
kx (0)numberShear factor (x-axis).
ky (0)numberShear factor (y-axis).

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

coloredtexttableA table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
coloredtext.color1tableA 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.string1stringA string of text which has a color specified by the previous color.
coloredtext.color2tableA 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.string2stringA string of text which has a color specified by the previous color.
coloredtext....tables and stringsAdditional colors and strings.
xnumberThe position of the new text on the x-axis.
ynumberThe position of the new text on the y-axis.
wraplimitnumberThe maximum width in pixels of the text before it gets automatically wrapped to a new line.
alignAlignModeThe alignment of the text.
angle (0)numberThe orientation of the object in radians.
sx (1)numberScale factor on the x-axis.
sy (sx)numberScale factor on the y-axis.
ox (0)numberOrigin offset on the x-axis.
oy (0)numberOrigin offset on the y-axis.
kx (0)numberShearing / skew factor on the x-axis.
ky (0)numberShearing / skew factor on the y-axis.

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( stack )

stack ("transform")StackTypeThe 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, rx, ry, segments )

Draws a rectangle with rounded corners.

modeDrawModeHow to draw the rectangle.
xnumberThe position of top-left corner along the x-axis.
ynumberThe position of top-left corner along the y-axis.
widthnumberWidth of the rectangle.
heightnumberHeight of the rectangle.
rx (0)numberThe x-axis radius of each round corner. Cannot be greater than half the rectangle's width.
ry (rx)numberThe y-axis radius of each round corner. Cannot be greater than half the rectangle's height.
segments (based on size)numberThe number of segments used for drawing the round corners.

love.graphics.reset

Resets the current graphics settings.

Calling reset makes the current drawing color white, the current background color black, resets any active Canvas or Shader, and removes any scissor settings. It sets the BlendMode to alpha. 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 )

anglenumberThe 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 )

sxnumberThe scaling in the direction of the x-axis.
sy (sx)numberThe 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( r, g, b, a )

rnumberThe red component (0-255).
gnumberThe green component (0-255).
bnumberThe blue component (0-255).
a (255)numberThe alpha component (0-255).

love.graphics.setBackgroundColor( rgba )

rgbatableA numerical indexed table with the red, green and blue values as numbers. Alpha is 255 if it is not in the table

love.graphics.setBlendMode

Sets the blending mode.

love.graphics.setBlendMode( mode, alphamode )

modeBlendModeThe blend mode to use.
alphamode ("alphamultiply")BlendAlphaModeWhat to do with the alpha of drawn objects when blending.

love.graphics.setCanvas

Captures drawing operations to a Canvas.

love.graphics.setCanvas( canvas )

Sets the render target to a specified Canvas. All drawing operations until the next love.graphics.setCanvas call will be redirected to the Canvas and not shown on the screen.

canvasCanvasA render target.

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 Canvases. All drawing operations until the next love.graphics.setCanvas call will be redirected to the specified canvases and not shown on the screen.

canvas1CanvasThe first render target.
canvas2CanvasThe second render target.
...CanvasMore canvases.

love.graphics.setColor

Sets the color used for drawing.

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

rednumberThe amount of red.
greennumberThe amount of green.
bluenumberThe amount of blue.
alphanumberThe amount of alpha. The alpha value will be applied to all subsequent draw operations, even the drawing of an image.

love.graphics.setColor( rgba )

rgbatableA numerical indexed table with the red, green, blue and alpha values as numbers. The alpha is optional and defaults to 255 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.

Enables all color components when called without arguments.

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

Enables color masking for the specified color components.

redbooleanRender red component.
greenbooleanRender green component.
bluebooleanRender blue component.
alphabooleanRender alpha component.

love.graphics.setColorMask()

Disables color masking.

love.graphics.setDefaultFilter

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

This function does not apply retroactively to loaded images.

love.graphics.setDefaultFilter( min, mag, anisotropy )

minFilterModeFilter mode used when scaling the image down.
mag (min)FilterModeFilter mode used when scaling the image up.
anisotropy (1)numberMaximum amount of Anisotropic Filtering used.

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 )

fontFontThe Font object to use.

love.graphics.setLineJoin

Sets the line join style.

love.graphics.setLineJoin( join )

joinLineJoinThe LineJoin to use.

love.graphics.setLineStyle

Sets the line style.

love.graphics.setLineStyle( style )

styleLineStyleThe LineStyle to use.

love.graphics.setLineWidth

Sets the line width.

love.graphics.setLineWidth( width )

widthnumberThe width of the line.

love.graphics.setNewFont

Creates and sets a new font.

font = love.graphics.setNewFont( filename, size )

fontFontThe new font.
filenamestring / File / FileDataThe file path/File/FileData of the font.
size (12)numberThe size of the font.

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.

Disables the shaders when called without arguments.

love.graphics.setShader()

love.graphics.setShader( shader )

shaderShaderThe new shader.

love.graphics.setPointSize

Sets the point size.

love.graphics.setPointSize( size )

sizenumberThe 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.

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

Limits the drawing area to a specified rectangle.

xnumberThe X coordinate of upper left corner.
ynumberThe Y coordinate of upper left corner.
widthnumberThe width of clipping rectangle.
heightnumberThe height of clipping rectangle.

love.graphics.setScissor()

Disables scissor.

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.

Each Canvas has its own per-pixel stencil values.

love.graphics.setStencilTest( comparemode, comparevalue )

comparemodeCompareModeThe type of comparison to make for each pixel.
comparevaluenumberThe 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.

Wireframe mode should only be used for debugging. The lines drawn with it enabled do not behave like regular love.graphics.lines: their widths don't scale with the coordinate transformations or with love.graphics.setLineWidth, and they don't use the smooth LineStyle.

love.graphics.setWireframe( enable )

enablebooleanTrue to enable wireframe mode when drawing, false to disable it.

love.graphics.shear

Shears the coordinate system.

love.graphics.shear( kx, ky )

kxnumberThe shear factor on the x-axis.
kynumberThe 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 values of pixels 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.

Each Canvas has its own per-pixel stencil values. Stencil values are within the range of [0, 255].

love.graphics.stencil( stencilfunction, action, value, keepvalues )

stencilfunctionfunctionFunction which draws geometry. The stencil values of pixels, rather than the color of each pixel, will be affected by the geometry.
action ("replace")StencilActionHow to modify any stencil values of pixels that are touched by what's drawn in the stencil function.
value (1)numberThe 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)booleanTrue 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.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.graphics.clear is called (which is called automatically before love.draw in the default love.run function), or a love.graphics.pop reverts to a previous coordinate system state.

Translating using whole numbers will prevent tearing/blurring of images and fonts draw after translating.

love.graphics.translate( dx, dy )

dxnumberThe translation relative to the x-axis.
dynumberThe translation relative to the y-axis.

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.

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.

CanvasFormat

normal

The default Canvas format - usually an alias for the rgba8 format, or the srgb format if gamma-correct rendering is enabled in LÖVE 0.10.0 and newer.

hdr

A format suitable for high dynamic range content - an alias for the rgba16f format, normally.

rgba8

8 bits per channel (32 bpp) RGBA. Color channel values range from 0-255 (0-1 in shaders).

rgba4

4 bits per channel (16 bpp) RGBA.

rgb5a1

RGB with 5 bits each, and a 1-bit alpha channel (16 bpp).

rgb565

RGB with 5, 6, and 5 bits each, respectively (16 bpp). There is no alpha channel in this format.

rgb10a2

RGB with 10 bits per channel, and a 2-bit alpha channel (32 bpp).

rgba16f

Floating point RGBA with 16 bits per channel (64 bpp). Color values can range from [-65504, +65504].

rgba32f

Floating point RGBA with 32 bits per channel (128 bpp).

rg11b10f

Floating point RGB with 11 bits in the red and green channels, and 10 bits in the blue channel (32 bpp). There is no alpha channel. Color values can range from [0, +65024].

srgb

The same as rgba8, but the Canvas is interpreted as being in the sRGB color space. Everything drawn to the Canvas will be converted from linear RGB to sRGB. When the Canvas is drawn (or used in a shader), it will be decoded from sRGB to linear RGB. This reduces color banding when doing gamma-correct rendering, since sRGB encoding has more precision than linear RGB for darker colors.

r8

Single-channel (red component) format (8 bpp).

rg8

Two channels (red and green components) with 8 bits per channel (16 bpp).

r16f

Floating point single-channel format (16 bpp). Color values can range from [-65504, +65504].

rg16f

Floating point two-channel format with 16 bits per channel (32 bpp). Color values can range from [-65504, +65504].

r32f

Floating point single-channel format (32 bpp).

rg32f

Floating point two-channel format with 32 bits per channel (64 bpp).

CompareMode

equal

The stencil value of the pixel must be equal to the supplied value.

notequal

The stencil value of the pixel must not be equal to the supplied value.

less

The stencil value of the pixel must be less than the supplied value.

lequal

The stencil value of the pixel must be less than or equal to the supplied value.

gequal

The stencil value of the pixel must be greater than or equal to the supplied value.

greater

The stencil value of the pixel must be greater than the supplied value.

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 Canvases with different formats can be used in the same love.graphics.setCanvas call.

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.

LineJoin

miter

The ends of the line segments beveled in an angle so that they join seamlessly.

bevel

No cap applied to the ends of the line segments.

none

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.

WrapMode

clamp

How the image wraps inside a Quad with a larger quad size than image size. This also affects how Meshes with texture coordinates which are outside the range of [0, 1] are drawn, and the color returned by the Texel Shader function when using it to sample from texture coordinates outside of the range of [0, 1].

repeat

Repeat the image. 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 0.10.0, not all graphics cards that LÖVE supported could use Canvases. love.graphics.isSupported("canvas") could be used to check for support at runtime.

Constructors

Functions

Dimensions

Supertypes

Canvas:getDimensions

Gets the width and height of the Canvas.

width, height = Canvas:getDimensions()

widthnumberThe width of the Canvas, in pixels.
heightnumberThe height of the Canvas, in pixels.

Canvas:getFilter

Gets the filter mode of the Canvas.

min, mag, anisotropy = Canvas:getFilter()

minFilterModeFilter mode used when minifying the canvas.
magFilterModeFilter mode used when magnifying the canvas.
anisotropynumberMaximum amount of anisotropic filtering used.

Canvas:getFormat

Gets the texture format of the Canvas.

format = Canvas:getFormat()

formatCanvasFormatThe format of the Canvas.

Canvas:getHeight

Gets the height of the Canvas.

height = Canvas:getHeight()

heightnumberThe 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()

samplesnumberThe number of multisample antialiasing samples used by the canvas when drawing to it.

Canvas:getWidth

Gets the width of the Canvas.

width = Canvas:getWidth()

widthnumberThe 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.

horizontal, vertical = Canvas:getWrap()

horizontalWrapModeHorizontal wrapping mode of the Canvas.
verticalWrapModeVertical wrapping mode of the Canvas.

Canvas:newImageData

Generates ImageData from the contents of the Canvas.

data = Canvas:newImageData()

dataImageDataThe image data stored in the Canvas.

data = Canvas:newImageData( x, y, width, height )

dataImageDataThe new ImageData made from the Canvas' contents.
xnumberThe x-axis of the top-left corner of the area within the Canvas to capture.
ynumberThe y-axis of the top-left corner of the area within the Canvas to capture.
widthnumberThe width of the area within the Canvas to capture.
heightnumberThe height of the area within the Canvas to capture.

Canvas:renderTo

Render to the Canvas using a function.

Canvas:renderTo( func )

funcfunctionA function performing drawing operations.

Canvas:setFilter

Sets the filter of the Canvas.

Canvas:setFilter( min, mag, anisotropy )

minFilterModeHow to scale a canvas down.
mag (min)FilterModeHow to scale a canvas up.
anisotropy (1)numberMaximum amount of anisotropic filtering used.

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( horizontal, vertical )

horizontalWrapModeHorizontal wrapping mode of the Canvas.
vertical (horizontal)WrapModeVertical wrapping mode of the Canvas.

Font

Defines the shape of characters than can be drawn onto the screen.

Constructors

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()

ascentnumberThe 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()

baselinenumberThe baseline of the Font in pixels.

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()

descentnumberThe descent of the Font in pixels.

Font:getFilter

Gets the filter mode for a font.

min, mag, anisotropy = Font:getFilter()

minFilterModeFilter mode used when minifying the font.
magFilterModeFilter mode used when magnifying the font.
anisotropynumberMaximum 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()

heightnumberThe 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()

heightnumberThe current line height.

Font:getWidth

Determines the horizontal size a line of text needs. Does not support line-breaks.

width = Font:getWidth( line )

widthnumberThe width of the line.
linestringA line of text.

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 )

widthnumberThe maximum width of the wrapped text.
wrappedtexttableA sequence containing each line of text that was wrapped.
textstringThe text that will be wrapped.
wraplimitnumberThe maximum width in pixels of each line that text is allowed before wrapping.

Font:hasGlyphs

Gets whether the font can render a particular character.

hasglyph = Font:hasGlyphs( character )

hasglyphbooleanWhether the font can render the glyph represented by the character.
characterstringA unicode character.

hasglyph = Font:hasGlyphs( codepoint )

hasglyphbooleanWhether the font can render the glyph represented by the codepoint number.
codepointnumberA 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, ... )

fallbackfont1FontThe first fallback Font to use.
...FontAdditional fallback Fonts.

Font:setFilter

Sets the filter mode for a font.

Font:setFilter( min, mag, anisotropy )

minFilterModeHow to scale a font down.
mag (min)FilterModeHow to scale a font up.
anisotropy (1)numberMaximum 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 )

heightnumberThe new line height.

Mesh

A 2D polygon mesh used for drawing arbitrary textured shapes.

Constructors

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 )

namestringThe name of the vertex attribute to attach.
meshMeshThe Mesh to get the vertex attribute from.

Mesh:getDrawMode

Gets the mode used when drawing the Mesh.

mode = Mesh:getDrawMode()

modeMeshDrawModeThe mode used when drawing the Mesh.

Mesh:getDrawRange

Gets the range of vertices used when drawing the Mesh.

If the Mesh's draw range has not been set previously with Mesh:setDrawRange, this function will return nil.

min, max = Mesh:getDrawRange()

minnumberThe 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.
maxnumberThe 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()

textureTextureThe 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.

attributecomponent, ... = Mesh:getVertex( index )

attributecomponentnumberThe first component of the first vertex attribute in the specified vertex.
...numberAdditional components of all vertex attributes in the specified vertex.
indexnumberThe index of the the vertex you want to retrieve the information for.

x, y, u, v, r, g, b, a = Mesh:getVertex( index )

xnumberThe position of the vertex on the x-axis.
ynumberThe position of the vertex on the y-axis.
unumberThe horizontal component of the texture coordinate.
vnumberThe vertical component of the texture coordinate.
rnumberThe red component of the vertex's color.
gnumberThe green component of the vertex's color.
bnumberThe blue component of the vertex's color.
anumberThe alpha component of the vertex's color.
indexnumberThe index of the 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 )

value1numberThe value of the first component of the attribute.
value2numberThe value of the second component of the attribute.
...numberAny additional vertex attribute components.
vertexindexnumberThe index of the the vertex to be modified.
attributeindexnumberThe index of the attribute within the vertex to be modified.

Mesh:getVertexCount

Gets the total number of vertices in the Mesh.

num = Mesh:getVertexCount()

numnumberThe total number of vertices in this Mesh.

Mesh:getVertexFormat

Gets the vertex format that the Mesh was created with.

format = Mesh:getVertexFormat()

formattableThe 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.attributetableA 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....tableAdditional 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()

maptableA table containing a 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 )

enabledbooleanWhether the vertex attribute is used when drawing this Mesh.
namestringThe name of the vertex attribute to enable or disable.

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 )

namestringThe name of the vertex attribute to enable or disable.
enablebooleanWhether the vertex attribute is used when drawing this Mesh.

Mesh:setDrawMode

Sets the mode used when drawing the Mesh.

Mesh:setDrawMode( mode )

modeMeshDrawModeThe mode to use when drawing the Mesh.

Mesh:setDrawRange

Restricts the drawn vertices of the Mesh to a subset of the total.

If a vertex map is used with the Mesh, this method will set a subset of the values in the vertex map array to use, instead of a subset of the total vertices in the Mesh.

For example, if Mesh:setVertexMap(1, 2, 3, 1, 3, 4) and Mesh:setDrawRange(4, 6) are called, vertices 1, 3, and 4 will be drawn.

Mesh:setDrawRange( min, max )

minnumberThe 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.
maxnumberThe index of the last vertex to use when drawing, or the index of the last value 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.

When called without an argument disables the texture. Untextured meshes have a white color by default.

Mesh:setTexture()

Mesh:setTexture( texture )

textureTextureThe Image or Canvas to texture the Mesh with when drawing.

Mesh:setVertex

Sets the properties of a vertex in the Mesh.

Mesh:setVertex( index, attributecomponent, ... )

indexnumberThe index of the the vertex you want to modify.
attributecomponentnumberThe first component of the first vertex attribute in the specified vertex.
...numberAdditional components of all vertex attributes in the specified vertex.

Mesh:setVertex( index, vertex )

indexnumberThe index of the the vertex you want to modify.
vertextableA table with vertex information, in the form of {attributecomponent, ...}.
vertex.attributecomponentnumberThe first component of the first vertex attribute in the specified vertex.
vertex....numberAdditional 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.

indexnumberThe index of the the vertex you want to modify.
xnumberThe position of the vertex on the x-axis.
ynumberThe position of the vertex on the y-axis.
unumberThe horizontal component of the texture coordinate.
vnumberThe vertical component of the texture coordinate.
r (255)numberThe red component of the vertex's color.
g (255)numberThe green component of the vertex's color.
b (255)numberThe blue component of the vertex's color.
a (255)numberThe 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.

indexnumberThe index of the the vertex you want to modify.
vertextableA table with vertex information.
vertex.[1]numberThe position of the vertex on the x-axis.
vertex.[2]numberThe position of the vertex on the y-axis.
vertex.[3]numberThe horizontal component of the texture coordinate.
vertex.[4]numberThe vertical component of the texture coordinate.
vertex.[5] (255)numberThe red component of the vertex's color.
vertex.[6] (255)numberThe green component of the vertex's color.
vertex.[7] (255)numberThe blue component of the vertex's color.
vertex.[8] (255)numberThe alpha component of the vertex's color.

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, ... )

vertexindexnumberThe index of the the vertex to be modified.
attributeindexnumberThe index of the attribute within the vertex to be modified.
value1numberThe value of the first component of the attribute.
value2numberThe value of the second component of the attribute.
...numberAny 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 )

maptableA table containing a list of vertex indices to use when drawing. Values must be in the range of [1, Mesh:getVertexCount()].

Mesh:setVertexMap( vi1, vi2, vi3 )

vi1numberThe index of the first vertex to use when drawing. Must be in the range of [1, Mesh:getVertexCount()].
vi2numberThe index of the second vertex to use when drawing.
vi3numberThe index of the third vertex to use when drawing.

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.

Mesh:setVertices( vertices )

verticestableThe 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.attributecomponentnumberThe first component of the first vertex attribute in the vertex.
vertices....numberAdditional components of all vertex attributes in the vertex.
vertices.startvertex (1)numberThe 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.

verticestableThe table filled with vertex information tables for each vertex as follows:
vertices.[1]numberThe position of the vertex on the x-axis.
vertices.[2]numberThe position of the vertex on the y-axis.
vertices.[3]numberThe horizontal component of the texture coordinate. Texture coordinates are normally in the range of [0, 1], but can be greater or less (see WrapMode).
vertices.[4]numberThe vertical component of the texture coordinate. Texture coordinates are normally in the range of [0, 1], but can be greater or less (see WrapMode).
vertices.[5] (255)numberThe red color component.
vertices.[6] (255)numberThe green color component.
vertices.[7] (255)numberThe blue color component.
vertices.[8] (255)numberThe alpha color component.

Image

Drawable image type.

Constructors

Functions

Supertypes

Image:getData

Gets the original ImageData or CompressedImageData used to create the Image.

All Images keep a reference to the Data that was used to create the Image. The Data is used to refresh the Image when love.window.setMode or Image:refresh is called.

data = Image:getData()

dataImageDataThe original ImageData used to create the Image, if the image is not compressed.

data = Image:getData()

dataCompressedImageDataThe original CompressedImageData used to create the Image, if the image is compressed.

Image:getDimensions

Gets the width and height of the Image.

width, height = Image:getDimensions()

widthnumberThe width of the Image, in pixels.
heightnumberThe height of the Image, in pixels.

Image:getFilter

Gets the filter mode for an image.

min, mag = Image:getFilter()

minFilterModeFilter mode used when minifying the image.
magFilterModeFilter mode used when magnifying the image.

Image:getFlags

Gets the flags used when the image was created.

flags = Image:getFlags()

flagstableA table with ImageFlag keys.

Image:getHeight

Gets the height of the Image.

height = Image:getHeight()

heightnumberThe height of the Image, in pixels.

Image:getMipmapFilter

Gets the mipmap filter mode for an Image.

mode, sharpness = Image:getMipmapFilter()

modeFilterModeThe filter mode used in between mipmap levels. nil if mipmap filtering is not enabled.
sharpnessnumberValue used to determine whether the image should use more or less detailed mipmap levels than normal when drawing.

Image:getWidth

Gets the width of the Image.

width = Image:getWidth()

widthnumberThe 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.

horizontal, vertical = Image:getWrap()

horizontalWrapModeHorizontal wrapping mode of the image.
verticalWrapModeVertical wrapping mode of the image.

Image:refresh

Reloads the Image's contents from the ImageData or CompressedImageData used to create the image.

Image:refresh()

Image:refresh( x, y, width, height )

xnumberThe x-axis of the top-left corner of the area within the Image to reload.
ynumberThe y-axis of the top-left corner of the area within the Image to reload.
widthnumberThe width of the area within the Image to reload.
heightnumberThe height of the area within the Image to reload.

Image:setFilter

Sets the filter mode for an image.

Image:setFilter( min, mag )

minFilterModeHow to scale an image down.
mag (min)FilterModeHow to scale an image up.

Image:setMipmapFilter

Sets the mipmap filter mode for an Image.

Mipmapping is useful when drawing an image at a reduced scale. It can improve performance and reduce aliasing issues.

In 0.10.0 and newer, the Image must be created with the mipmaps flag enabled for the mipmap filter to have any effect.

Image:setMipmapFilter( filtermode, sharpness )

filtermodeFilterModeThe filter mode to use in between mipmap levels. "nearest" will often give better performance.
sharpness (0)numberA positive sharpness value makes the image use a more detailed mipmap level when drawing, at the expense of performance. A negative value does the reverse.

Image:setMipmapFilter()

Disables mipmap filtering.

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.

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:getWrap("repeat", "repeat") for all the images to be repeated, and using Quad of appropriate size will result in the best visual appearance.

Image:setWrap( horizontal, vertical )

horizontalWrapModeHorizontal wrapping mode of the image.
vertical (horizontal)WrapModeVertical wrapping mode of the image.

ParticleSystem

Used to create cool effects, like fire. The particle systems are created and drawn on the screen using functions in love.graphics. They also need to be updated in the update(dt) callback for you to see any changes in the particles emitted.

Constructors

Functions

Supertypes

ParticleSystem:clone

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

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

particlesystem = ParticleSystem:clone()

particlesystemParticleSystemThe new identical copy of this ParticleSystem.

ParticleSystem:emit

Emits a burst of particles from the particle emitter.

ParticleSystem:emit( numparticles )

numparticlesnumberThe amount of particles to emit. The number of emitted particles will be truncated if the particle system's max buffer size is reached.

ParticleSystem:getCount

Gets the amount of particles that are currently in the system.

count = ParticleSystem:getCount()

countnumberThe current number of live particles.

ParticleSystem:getAreaSpread

Gets the area-based spawn parameters for the particles.

distribution, dx, dy = ParticleSystem:getAreaSpread()

distributionAreaSpreadDistributionThe type of distribution for new particles.
dxnumberThe maximum spawn distance from the emitter along the x-axis for uniform distribution, or the standard deviation along the x-axis for normal distribution.
dynumberThe maximum spawn distance from the emitter along the y-axis for uniform distribution, or the standard deviation along the y-axis for normal distribution.

ParticleSystem:getBufferSize

Gets the size of the buffer (the max allowed amount of particles in the system).

buffer = ParticleSystem:getBufferSize()

buffernumberThe buffer size.

ParticleSystem:getColors

Gets a series of colors to apply to the particle sprite. The particle system will interpolate between each color evenly over the particle's lifetime. Color modulation needs to be activated for this function to have any effect.

Arguments are passed in groups of four, representing the components of the desired RGBA value. At least one color must be specified. A maximum of eight may be used.

r1, g1, b1, a1, r2, g2, b2, a2, ... = ParticleSystem:getColors()

r1numberFirst color, red component (0-255).
g1numberFirst color, green component (0-255).
b1numberFirst color, blue component (0-255).
a1numberFirst color, alpha component (0-255).
r2numberSecond color, red component (0-255).
g2numberSecond color, green component (0-255).
b2numberSecond color, blue component (0-255).
a2numberSecond color, alpha component (0-255).
...numberEtc.

ParticleSystem:getDirection

Gets the direction the particles will be emitted in.

direction = ParticleSystem:getDirection()

directionnumberThe direction of the particles (in radians).

ParticleSystem:getEmissionRate

Gets the amount of particles emitted per second.

rate = ParticleSystem:getEmissionRate()

ratenumberThe amount of particles per second.

ParticleSystem:getInsertMode

Gets the mode to use when the ParticleSystem adds new particles.

mode = ParticleSystem:getInsertMode()

modeParticleInsertModeThe mode to use 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()

xminnumberThe minimum acceleration along the x axis.
yminnumberThe minimum acceleration along the y axis.
xmaxnumberThe maximum acceleration along the x axis.
ymaxnumberThe maximum acceleration along the y axis.

ParticleSystem:getLinearDamping

Gets the amount of linear damping (constant deceleration) for particles.

min, max = ParticleSystem:getLinearDamping()

minnumberThe minimum amount of linear damping applied to particles.
maxnumberThe maximum amount of linear damping applied to particles.

ParticleSystem:getEmitterLifetime

Gets how long the particle system should emit particles (if -1 then it emits particles forever).

life = ParticleSystem:getEmitterLifetime()

lifenumberThe lifetime of the emitter (in seconds).

ParticleSystem:getOffset

Get the offget position which the particle sprite is rotated around. If this function is not used, the particles rotate around their center.

x, y = ParticleSystem:getOffset()

xnumberThe x coordinate of the rotation offget.
ynumberThe y coordinate of the rotation offget.

ParticleSystem:getParticleLifetime

Gets the life of the particles.

min, max = ParticleSystem:getParticleLifetime()

minnumberThe minimum life of the particles (seconds).
max (min)numberThe maximum life of the particles (seconds).

ParticleSystem:getQuads

Gets the series of Quads used for the particle sprites.

quads = ParticleSystem:getQuads()

quadstableA table containing the Quads used.

ParticleSystem:getPosition

Gets the position of the emitter.

x, y = ParticleSystem:getPosition()

xnumberPosition along x-axis.
ynumberPosition along y-axis.

ParticleSystem:getRadialAcceleration

Get the radial acceleration (away from the emitter).

min, max = ParticleSystem:getRadialAcceleration()

minnumberThe minimum acceleration.
max (min)numberThe maximum acceleration.

ParticleSystem:getRotation

Gets the rotation of the image upon particle creation (in radians).

min, max = ParticleSystem:getRotation()

minnumberThe minimum initial angle (radians).
max (min)numberThe maximum initial angle (radians).

ParticleSystem:getSizes

Gets 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.

size1, size2, ... = ParticleSystem:getSizes()

size1numberThe first size.
size2numberThe second size.
...numberEtc.

ParticleSystem:getSizeVariation

Gets the degree of variation (0 meaning no variation and 1 meaning full variation between start and end).

variation = ParticleSystem:getSizeVariation()

variationnumberThe degree of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:getSpeed

Gets the speed of the particles.

min, max = ParticleSystem:getSpeed()

minnumberThe minimum linear speed of the particles.
max (min)numberThe maximum linear speed of the particles.

ParticleSystem:getSpin

Gets the spin of the sprite.

min, max = ParticleSystem:getSpin()

minnumberThe minimum spin (radians per second).
max (min)numberThe maximum spin (radians per second).

ParticleSystem:getSpinVariation

Gets the degree of variation (0 meaning no variation and 1 meaning full variation between start and end).

variation = ParticleSystem:getSpinVariation()

variationnumberThe degree of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:getSpread

Gets the amount of spread for the system.

spread = ParticleSystem:getSpread()

spreadnumberThe amount of spread (radians).

ParticleSystem:getTexture

Gets the Image or Canvas which is to be emitted.

texture = ParticleSystem:getTexture()

textureTextureAn Image or Canvas to use for the particle.

ParticleSystem:getTangentialAcceleration

Gets the tangential acceleration (acceleration perpendicular to the particle's direction).

min, max = ParticleSystem:getTangentialAcceleration()

minnumberThe minimum acceleration.
max (min)numberThe maximum acceleration.

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.

enabled = ParticleSystem:hasRelativeRotation()

enabledbooleanTrue 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()

activebooleanTrue if system is active, false otherwise.

ParticleSystem:isPaused

Checks whether the particle system is paused.

paused = ParticleSystem:isPaused()

pausedbooleanTrue if system is paused, false otherwise.

ParticleSystem:isStopped

Checks whether the particle system is stopped.

stopped = ParticleSystem:isStopped()

stoppedbooleanTrue 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 )

xnumberPosition along x-axis.
ynumberPosition 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:setAreaSpread

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:setAreaSpread( distribution, dx, dy )

distributionAreaSpreadDistributionThe type of distribution for new particles.
dxnumberThe maximum spawn distance from the emitter along the x-axis for uniform distribution, or the standard deviation along the x-axis for normal distribution.
dynumberThe maximum spawn distance from the emitter along the y-axis for uniform distribution, or the standard deviation along the y-axis for normal distribution.

ParticleSystem:setBufferSize

Sets the size of the buffer (the max allowed amount of particles in the system).

ParticleSystem:setBufferSize( buffer )

buffernumberThe 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. Color modulation needs to be activated for this function to have any effect.

Arguments are passed in groups of four, representing the components of the desired RGBA value. At least one color must be specified. A maximum of eight may be used.

ParticleSystem:setColors( r1, g1, b1, a1, r2, g2, b2, a2, ... )

r1numberFirst color, red component (0-255).
g1numberFirst color, green component (0-255).
b1numberFirst color, blue component (0-255).
a1numberFirst color, alpha component (0-255).
r2numberSecond color, red component (0-255).
g2numberSecond color, green component (0-255).
b2numberSecond color, blue component (0-255).
a2numberSecond color, alpha component (0-255).
...numberEtc.

ParticleSystem:setDirection

Sets the direction the particles will be emitted in.

ParticleSystem:setDirection( direction )

directionnumberThe direction of the particles (in radians).

ParticleSystem:setEmissionRate

Sets the amount of particles emitted per second.

ParticleSystem:setEmissionRate( rate )

ratenumberThe 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 )

lifenumberThe lifetime of the emitter (in seconds).

ParticleSystem:setInsertMode

Sets the mode to use when the ParticleSystem adds new particles.

ParticleSystem:setInsertMode( mode )

modeParticleInsertModeThe 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 )

xminnumberThe minimum acceleration along the x axis.
ymin (0)numberThe minimum acceleration along the y axis.
xmax (xmin)numberThe maximum acceleration along the x axis.
ymax (ymin)numberThe maximum acceleration along the y axis.

ParticleSystem:setLinearDamping

Sets the amount of linear damping (constant deceleration) for particles.

ParticleSystem:setLinearDamping( min, max )

minnumberThe minimum amount of linear damping applied to particles.
maxnumberThe 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 )

xnumberThe x coordinate of the rotation offset.
ynumberThe y coordinate of the rotation offset.

ParticleSystem:setParticleLifetime

Sets the life of the particles.

ParticleSystem:setParticleLifetime( min, max )

minnumberThe minimum life of the particles (seconds).
max (min)numberThe maximum life of the particles (seconds).

ParticleSystem:setPosition

Sets the position of the emitter.

ParticleSystem:setPosition( x, y )

xnumberPosition along x-axis.
ynumberPosition 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 )

quad1QuadThe first Quad to use.
quad2QuadThe second Quad to use.

ParticleSystem:setQuads( quads )

quadstableA table containing the Quads to use.

ParticleSystem:setRadialAcceleration

Set the radial acceleration (away from the emitter).

ParticleSystem:setRadialAcceleration( min, max )

minnumberThe minimum acceleration.
max (min)numberThe 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 )

enablebooleanTrue 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 )

minnumberThe minimum initial angle (radians).
max (min)numberThe maximum initial angle (radians).

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, ... )

size1numberThe first size.
size2numberThe second size.
...numberEtc.

ParticleSystem:setSizeVariation

Sets the degree of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:setSizeVariation( variation )

variationnumberThe degree of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:setSpeed

Sets the speed of the particles.

ParticleSystem:setSpeed( min, max )

minnumberThe minimum linear speed of the particles.
max (min)numberThe maximum linear speed of the particles.

ParticleSystem:setSpin

Sets the spin of the sprite.

ParticleSystem:setSpin( min, max )

minnumberThe minimum spin (radians per second).
max (min)numberThe maximum spin (radians per second).

ParticleSystem:setSpinVariation

Sets the degree of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:setSpinVariation( variation )

variationnumberThe degree 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 )

spreadnumberThe amount of spread (radians).

ParticleSystem:setTexture

Sets the Image or Canvas which is to be emitted.

ParticleSystem:setTexture( texture )

textureTextureAn Image or Canvas to use for the particle.

ParticleSystem:setTangentialAcceleration

Sets the tangential acceleration (acceleration perpendicular to the particle's direction).

ParticleSystem:setTangentialAcceleration( min, max )

minnumberThe minimum acceleration.
max (min)numberThe maximum acceleration.

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 )

dtnumberThe 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.

Constructors

Functions

Supertypes

Quad:getTextureDimensions

Gets reference texture dimensions initially specified in love.graphics.newQuad.

sw, sh = Quad:getTextureDimensions()

swnumberThe Texture width used by the Quad.
shnumberThe Texture height used by the Quad.

Quad:getViewport

Gets the current viewport of this Quad.

x, y, w, h = Quad:getViewport()

xnumberThe top-left corner along the x-axis.
ynumberThe top-right corner along the y-axis.
wnumberThe width of the viewport.
hnumberThe height of the viewport.

Quad:setViewport

Sets the texture coordinates according to a viewport.

Quad:setViewport( x, y, w, h )

xnumberThe top-left corner along the x-axis.
ynumberThe top-right corner along the y-axis.
wnumberThe width of the viewport.
hnumberThe height of the viewport.

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/shine

Constructors

Functions

Supertypes

Shader:getExternVariable

Gets information about an 'extern' ('uniform') variable in the shader.

type, components, arrayelements = Shader:getExternVariable( name )

typeShaderVariableTypeThe base type of the variable.
componentsnumberThe number of components in the variable (e.g. 2 for a vec2 or mat2.)
arrayelementsnumberThe number of elements in the array if the variable is an array, or 1 if not.
namestringThe name of the extern variable.

Shader:getWarnings

Gets 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()

warningsstringWarning messages (if any).

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.

Shader:send( name, number, ... )

namestringName of the number to send to the shader.
numbernumberNumber to send to store in the uniform variable.
...numberAdditional numbers to send if the uniform variable is an array.

Shader:send( name, vector, ... )

namestringName of the vector to send to the shader.
vectortableNumbers 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.
...tableAdditional 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, ... )

namestringName of the matrix to send to the shader.
matrixtable2x2, 3x3, or 4x4 matrix to send to the uniform variable. Using table form: {{a,b,c,d}, {e,f,g,h}, ... }.
...tableAdditional matrices of the same type as matrix to store in a uniform array.

Shader:send( name, texture )

namestringName of the Texture to send to the shader.
textureTextureTexture (Image or Canvas) to send to the uniform variable.

Shader:send( name, boolean, ... )

namestringName of the boolean to send to the shader.
booleanbooleanBoolean to send to store in the uniform variable.
...booleanAdditional booleans to send if the uniform variable is an array.

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 [0, 255], unlike Shader:send. The colors are gamma-corrected if global gamma-correction is enabled.

Shader:sendColor( name, color, ... )

namestringThe name of the color extern variable to send to in the shader.
colortableA table with red, green, blue, and optional alpha color components in the range of [0, 255] to send to the extern as a vector.
...tableAdditional 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.

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 Quad to the batch, different sub-images from within the atlas can be drawn.

Constructors

Functions

Supertypes

SpriteBatch:add

Add a sprite to the batch.

id = SpriteBatch:add( x, y, r, sx, sy, ox, oy, kx, ky )

idnumberAn identifier for the added sprite.
xnumberThe position to draw the object (x-axis).
ynumberThe position to draw the object (y-axis).
r (0)numberOrientation (radians).
sx (1)numberScale factor (x-axis).
sy (sx)numberScale factor (y-axis).
ox (0)numberOrigin offset (x-axis).
oy (0)numberOrigin offset (y-axis).
kx (0)numberShear factor (x-axis).
ky (0)numberShear factor (y-axis).

id = SpriteBatch:add( quad, x, y, r, sx, sy, ox, oy, kx, ky )

idnumberAn identifier for the added sprite.
quadQuadThe Quad to add.
xnumberThe position to draw the object (x-axis).
ynumberThe position to draw the object (y-axis).
r (0)numberOrientation (radians).
sx (1)numberScale factor (x-axis).
sy (sx)numberScale factor (y-axis).
ox (0)numberOrigin offset (x-axis).
oy (0)numberOrigin offset (y-axis).
kx (0)numberShear factor (x-axis).
ky (0)numberShear factor (y-axis).

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 be multiplied by 4 to determine the first vertex in a specific sprite.

SpriteBatch:attachAttribute( name, mesh )

namestringThe name of the vertex attribute to attach.
meshMeshThe 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.

SpriteBatch:flush()

SpriteBatch:getBufferSize

Gets the maximum number of sprites the SpriteBatch can hold.

size = SpriteBatch:getBufferSize()

sizenumberThe 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.

r, g, b, a = SpriteBatch:getColor()

rnumberThe red component (0-255).
gnumberThe green component (0-255).
bnumberThe blue component (0-255).
anumberThe alpha component (0-255).

SpriteBatch:getCount

Gets the amount of sprites currently in the SpriteBatch.

count = SpriteBatch:getCount()

countnumberThe amount of sprites currently in the batch.

SpriteBatch:getTexture

Gets the Image or Canvas used by the SpriteBatch.

texture = SpriteBatch:getTexture()

textureTextureThe Image or Canvas for the sprites.

SpriteBatch:set

Changes a sprite in the batch. This requires the identifier returned by add and addq.

SpriteBatch:set( id, x, y, r, sx, sy, ox, oy, kx, ky )

idnumberThe identifier of the sprite that will be changed.
xnumberThe position to draw the object (x-axis).
ynumberThe position to draw the object (y-axis).
r (0)numberOrientation (radians).
sx (1)numberScale factor (x-axis).
sy (sx)numberScale factor (y-axis).
ox (0)numberOrigin offset (x-axis).
oy (0)numberOrigin offset (y-axis).
kx (0)numberShear factor (x-axis).
ky (0)numberShear factor (y-axis).

SpriteBatch:set( id, quad, x, y, r, sx, sy, ox, oy, kx, ky )

idnumberThe identifier of the sprite that will be changed.
quadQuadThe quad used on the image of the batch.
xnumberThe position to draw the object (x-axis).
ynumberThe position to draw the object (y-axis).
r (0)numberOrientation (radians).
sx (1)numberScale factor (x-axis).
sy (sx)numberScale factor (y-axis).
ox (0)numberOrigin offset (x-axis).
oy (0)numberOrigin offset (y-axis).
kx (0)numberShear factor (x-axis).
ky (0)numberShear factor (y-axis).

SpriteBatch:setBufferSize

Sets the maximum number of sprites the SpriteBatch can hold. Existing sprites in the batch (up to the new maximum) will not be cleared when this function is called.

SpriteBatch:setBufferSize( size )

sizenumberThe new maximum number of sprites the batch can hold.

SpriteBatch:setColor

Sets the color that will be used for the next add and set operations. Calling the function without arguments will clear the color.

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 )

rnumberThe amount of red.
gnumberThe amount of green.
bnumberThe amount of blue.
a (255)numberThe amount of alpha.

SpriteBatch:setColor()

Disables all per-sprite colors for this SpriteBatch.

SpriteBatch:setTexture

Replaces the Image or Canvas used for the sprites.

SpriteBatch:setTexture( texture )

textureTextureThe new Image or Canvas to use for the sprites.

Text

Drawable text.

Constructors

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 )

indexnumberAn index number that can be used with Text:getWidth or Text:getHeight.
textstringstringThe text to add to the object.
x (0)numberThe position of the new text on the x-axis.
y (0)numberThe position of the new text on the y-axis.
angle (0)numberThe orientation of the new text in radians.
sx (1)numberScale factor on the x-axis.
sy (sx)numberScale factor on the y-axis.
ox (0)numberOrigin offset on the x-axis.
oy (0)numberOrigin offset on the y-axis.
kx (0)numberShearing / skew factor on the x-axis.
ky (0)numberShearing / skew factor on the y-axis.

index = Text:add( coloredtext, x, y, angle, sx, sy, ox, oy, kx, ky )

indexnumberAn index number that can be used with Text:getWidth or Text:getHeight.
coloredtexttableA table containing colors and strings to use as the new text, in the form of { color1, string1, color2, string2, ... }.
coloredtext.color1tableA 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.string1stringA string of text which has a color specified by the previous color.
coloredtext.color2tableA 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.string2stringA string of text which has a color specified by the previous color.
coloredtext....tables and stringsAdditional colors and strings.
x (0)numberThe position of the new text on the x-axis.
y (0)numberThe position of the new text on the y-axis.
angle (0)numberThe orientation of the new text in radians.
sx (1)numberScale factor on the x-axis.
sy (sx)numberScale factor on the y-axis.
ox (0)numberOrigin offset on the x-axis.
oy (0)numberOrigin offset on the y-axis.
kx (0)numberShearing / skew factor on the x-axis.
ky (0)numberShearing / skew factor on the y-axis.

Text:addf

Adds additional formatted / colored text to the Text object at the specified position.

index = Text:addf( textstring, wraplimit, align, x, y, angle, sx, sy, ox, oy, kx, ky )

indexnumberAn index number that can be used with Text:getWidth or Text:getHeight.
textstringstringThe text to add to the object.
wraplimitnumberThe maximum width in pixels of the text before it gets automatically wrapped to a new line.
alignAlignModeThe alignment of the text.
xnumberThe position of the new text on the x-axis.
ynumberThe position of the new text on the y-axis.
angle (0)numberThe orientation of the object in radians.
sx (1)numberScale factor on the x-axis.
sy (sx)numberScale factor on the y-axis.
ox (0)numberOrigin offset on the x-axis.
oy (0)numberOrigin offset on the y-axis.
kx (0)numberShearing / skew factor on the x-axis.
ky (0)numberShearing / skew factor on the y-axis.

index = Text:addf( coloredtext, wraplimit, align, x, y, angle, sx, sy, ox, oy, kx, ky )

indexnumberAn index number that can be used with Text:getWidth or Text:getHeight.
coloredtexttableA table containing colors and strings to use as the new text, in the form of { color1, string1, color2, string2, ... }.
coloredtext.color1tableA 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.string1stringA string of text which has a color specified by the previous color.
coloredtext.color2tableA 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.string2stringA string of text which has a color specified by the previous color.
coloredtext....tables and stringsAdditional colors and strings.
wraplimitnumberThe maximum width in pixels of the text before it gets automatically wrapped to a new line.
alignAlignModeThe alignment of the text.
xnumberThe position of the new text on the x-axis.
ynumberThe position of the new text on the y-axis.
angle (0)numberThe orientation of the object in radians.
sx (1)numberScale factor on the x-axis.
sy (sx)numberScale factor on the y-axis.
ox (0)numberOrigin offset on the x-axis.
oy (0)numberOrigin offset on the y-axis.
kx (0)numberShearing / skew factor on the x-axis.
ky (0)numberShearing / skew factor on the 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()

widthnumberThe width of the text. If multiple sub-strings have been added with Text:add, the width of the last sub-string is returned.
heightnumberThe 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.

widthnumberThe width of the sub-string (before scaling and other transformations).
heightnumberThe height of the sub-string (before scaling and other transformations).
indexnumberAn index number returned by Text:add or Text:addf.

Text:getFont

Gets the Font used with the Text object.

font = Text:getFont()

fontFontThe font used with this Text object.

Text:getHeight

Gets the height of the text in pixels.

height = Text:getHeight()

heightnumberThe 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.

heightnumberThe height of the sub-string (before scaling and other transformations).
indexnumberAn index number returned by Text:add or Text:addf.

Text:getWidth

Gets the width of the text in pixels.

width = Text:getWidth()

widthnumberThe 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.

widthnumberThe width of the sub-string (before scaling and other transformations).
indexnumberAn 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 )

textstringstringThe new string of text to use.

Text:set( coloredtext )

coloredtexttableA table containing colors and strings to use as the new text, in the form of { color1, string1, color2, string2, ... }.
coloredtext.color1tableA 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.string1stringA string of text which has a color specified by the previous color.
coloredtext.color2tableA 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.string2stringA string of text which has a color specified by the previous color.
coloredtext....tables and stringsAdditional colors and strings.

Text:set()

Clears the contents of the Text object.

Text:setf

Replaces the contents of the Text object with a new formatted string.

Text:setf( textstring, wraplimit, align )

textstringstringThe new string of text to use.
wraplimitnumberThe maximum width in pixels of the text before it gets automatically wrapped to a new line.
align ("left")AlignModeThe alignment of the text.

Text:setf( coloredtext, wraplimit, align )

coloredtexttableA table containing colors and strings to use as the new text, in the form of { color1, string1, color2, string2, ... }.
coloredtext.color1tableA 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.string1stringA string of text which has a color specified by the previous color.
coloredtext.color2tableA 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.string2stringA string of text which has a color specified by the previous color.
coloredtext....tables and stringsAdditional colors and strings.
wraplimitnumberThe maximum width in pixels of the text before it gets automatically wrapped to a new line.
align ("left")AlignModeThe alignment of the text.

Text:setf()

Clears the contents of the Text object.

Text:setFont

Replaces the Font used with the text.

Text:setFont( font )

fontFontThe new font to use with this Text object.

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.

Supertypes

Subtypes

Video

A drawable video.

Constructors

Functions

Dimensions

Supertypes

Video:getDimensions

Gets the width and height of the Video in pixels.

width, height = Video:getDimensions()

widthnumberThe width of the Video.
heightnumberThe height of the video.

Video:getFilter

Gets the scaling filters used when drawing the Video.

min, mag, anisotropy = Video:getFilter()

minFilterModeThe filter mode used when scaling the Video down.
magFilterModeThe filter mode used when scaling the Video up.
anisotropy (1)numberMaximum amount of anisotropic filtering used.

Video:getHeight

Gets the height of the Video in pixels.

height = Video:getHeight()

heightnumberThe 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()

sourceSourceThe 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()

widthnumberThe width of the Video.

Video:isPlaying

Gets whether the Video is currently playing.

playing = Video:isPlaying()

playingbooleanWhether 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 )

offsetnumberThe 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 )

minFilterModeThe filter mode used when scaling the Video down.
magFilterModeThe filter mode used when scaling the Video up.
anisotropy (1)numberMaximum 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)SourceThe audio Source used for audio playback, or nil to disable audio synchronization.

Video:tell

Gets the current playback position of the Video.

Video:tell( seconds )

secondsnumberThe 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 )

compressedbooleanWhether the file can be loaded as CompressedImageData or not.
filenamestringThe filename of the potentially compressed image file.

compressed = love.image.isCompressed( fileData )

compressedbooleanWhether the FileData can be loaded as CompressedImageData or not.
fileDataFileDataA 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( file )

compressedImageDataCompressedImageDataThe new CompressedImageData object.
filestring / File / FileDataThe file path/File/FileData of the compressed image file.

love.image.newImageData

Create a new ImageData object.

imageData = love.image.newImageData( width, height, data )

imageDataImageDataThe new blank ImageData object. Each pixel's color values, (including the alpha values!) will be set to zero.
widthnumberThe width of the ImageData.
heightnumberThe height of the ImageData.
data (none)stringThe data to load into the ImageData (RGBA bytes, left to right and top to bottom).

imageData = love.image.newImageData( file )

imageDataImageDataThe new ImageData object.
filestring / File / FileDataThe file path/File/FileData of the image file.

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. 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 the pixel values in the texture are in the range of [-1, 1] instead of [0, 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 [0, 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, +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, 1] instead of [0, 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.

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.

Constructors

Functions

Supertypes

CompressedImageData:getDimensions

Gets the width and height of the CompressedImageData.

width, height = CompressedImageData:getDimensions()

widthnumberThe width of the CompressedImageData.
heightnumberThe height of the CompressedImageData.

width, height = CompressedImageData:getDimensions( level )

widthnumberThe width of the CompressedImageData.
heightnumberThe height of the CompressedImageData.
levelnumberA mipmap level. Must be in the range of [1, CompressedImageData:getMipmapCount()].

CompressedImageData:getFormat

Gets the format of the CompressedImageData.

format = CompressedImageData:getFormat()

formatCompressedImageFormatThe format of the CompressedImageData.

CompressedImageData:getHeight

Gets the height of the CompressedImageData.

height = CompressedImageData:getHeight()

heightnumberThe height of the CompressedImageData.

height = CompressedImageData:getHeight( level )

heightnumberThe height of the CompressedImageData.
levelnumberA mipmap level. Must be in the range of [1, 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()

mipmapsnumberThe number of mipmap levels stored in the CompressedImageData.

CompressedImageData:getWidth

Gets the width of the CompressedImageData.

width = CompressedImageData:getWidth()

widthnumberThe width of the CompressedImageData.

width = CompressedImageData:getWidth( level )

widthnumberThe width of the CompressedImageData.
levelnumberA mipmap level. Must be in the range of [1, CompressedImageData:getMipmapCount()].

ImageData

Raw (decoded) image data.

You can't draw ImageData directly to screen. See Image for that.

Constructors

Functions

Dimensions

Supertypes

ImageData:encode

Encodes the ImageData and optionally writes it to the save directory.

filedata = ImageData:encode( format, filename )

filedataFileDataThe encoded image as a new FileData object.
formatImageFormatThe format to encode the image as.
filename (nil)stringThe filename to write the file to. If nil, no file will be written but the FileData will still be returned.

ImageData:getDimensions

Gets the width and height of the ImageData in pixels.

width, height = ImageData:getDimensions()

widthnumberThe width of the ImageData in pixels.
heightnumberThe height of the ImageData in pixels.

ImageData:getHeight

Gets the height of the ImageData in pixels.

height = ImageData:getHeight()

heightnumberThe 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.

r, g, b, a = ImageData:getPixel( x, y )

rnumberThe red component (0-255).
gnumberThe green component (0-255).
bnumberThe blue component (0-255).
anumberThe alpha component (0-255).
xnumberThe position of the pixel on the x-axis.
ynumberThe position of the pixel on the y-axis.

ImageData:getWidth

Gets the width of the ImageData in pixels.

width = ImageData:getWidth()

widthnumberThe 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 function parameter 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 parameter can return up to four number values, which become the new r, g, b and a values of the pixel. If the function returns fewer values, the remaining components are set to 0.

ImageData:mapPixel( pixelFunction )

pixelFunctionfunctionFunction parameter to apply to every pixel.

ImageData:paste

Paste into ImageData from another source ImageData.

ImageData:paste( source, dx, dy, sx, sy, sw, sh )

sourceImageDataSource ImageData from which to copy.
dxnumberDestination top-left position on x-axis.
dynumberDestination top-left position on y-axis.
sxnumberSource top-left position on x-axis.
synumberSource top-left position on y-axis.
swnumberSource width.
shnumberSource 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.

ImageData:setPixel( x, y, r, g, b, a )

xnumberThe position of the pixel on the x-axis.
ynumberThe position of the pixel on the y-axis.
rnumberThe red component (0-255).
gnumberThe green component (0-255).
bnumberThe blue component (0-255).
anumberThe alpha component (0-255).

love.joystick

Types

Functions

Enums

love.joystick.getJoystickCount

Gets the number of connected joysticks.

joystickcount = love.joystick.getJoystickCount()

joystickcountnumberThe number of connected joysticks.

love.joystick.getJoysticks

Gets a list of connected Joysticks.

joysticks = love.joystick.getJoysticks()

joystickstableThe list of currently connected Joysticks.

love.joystick.loadGamepadMappings

Loads a gamepad mappings string or file created with love.joystick.saveGamepadMappings.

love.joystick.loadGamepadMappings( filename )

filenamestringThe filename to load the mappings string from.

love.joystick.loadGamepadMappings( mappings )

mappingsstringThe mappings string to load.

love.joystick.saveGamepadMappings

Saves the virtual gamepad mappings of all Joysticks that are recognized as gamepads and have either been recently used or their gamepad bindings have been modified.

mappings = love.joystick.saveGamepadMappings( filename )

mappingsstringThe mappings string that was written to the file.
filename (no file)stringThe filename to save the mappings string to.

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, hatdirection )

successbooleanWhether the virtual gamepad button was successfully bound.
guidstringThe OS-dependent GUID for the type of Joystick the binding will affect.
buttonGamepadButtonThe virtual gamepad button to bind.
inputtypeJoystickInputTypeThe type of input to bind the virtual gamepad button to.
inputindexnumberThe index of the axis, button, or hat to bind the virtual gamepad button to.
hatdirectionJoystickHatThe 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, hatdirection )

successbooleanWhether the virtual gamepad button was successfully bound.
guidstringThe OS-dependent GUID for the type of Joystick the binding will affect.
axisGamepadAxisThe virtual gamepad axis to bind.
inputtypeJoystickInputTypeThe type of input to bind the virtual gamepad axis to.
inputindexnumberThe index of the axis, button, or hat to bind the virtual gamepad axis to.
hatdirectionJoystickHatThe 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.

Constructors

Functions

Input

Count

Info

Vibration

Supertypes

Joystick:getAxes

Gets the direction of each axis.

axisDir1, axisDir2, axisDirN = Joystick:getAxes()

axisDir1numberDirection of axis1.
axisDir2numberDirection of axis2.
axisDirNnumberDirection of axisN.

Joystick:getAxis

Gets the direction of an axis.

direction = Joystick:getAxis( axis )

directionnumberCurrent value of the axis.
axisnumberThe index of the axis to be checked.

Joystick:getAxisCount

Gets the number of axes on the joystick.

axes = Joystick:getAxisCount()

axesnumberThe number of axes available.

Joystick:getButtonCount

Gets the number of buttons on the joystick.

buttons = Joystick:getButtonCount()

buttonsnumberThe number of buttons available.

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()

guidstringThe 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 )

directionnumberCurrent value of the axis.
axisGamepadAxisThe 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 )

inputtypeJoystickInputTypeThe type of input the virtual gamepad axis is bound to.
inputindexnumberThe index of the Joystick's button, axis or hat that the virtual gamepad axis is bound to.
hatdirectionJoystickHatThe direction of the hat, if the virtual gamepad axis is bound to a hat. nil otherwise.
axisGamepadAxisThe virtual gamepad axis to get the binding for.

inputtype, inputindex, hatdirection = Joystick:getGamepadMapping( button )

inputtypeJoystickInputTypeThe type of input the virtual gamepad button is bound to.
inputindexnumberThe index of the Joystick's button, axis or hat that the virtual gamepad button is bound to.
hatdirectionJoystickHatThe direction of the hat, if the virtual gamepad button is bound to a hat. nil otherwise.
buttonGamepadAxisThe virtual gamepad button to get the binding for.

Joystick:getHat

Gets the direction of the Joystick's hat.

direction = Joystick:getHat( hat )

directionJoystickHatThe direction the hat is pushed.
hatnumberThe index of the hat to be checked.

Joystick:getHatCount

Gets the number of hats on the joystick.

hats = Joystick:getHatCount()

hatsnumberHow 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()

idnumberThe Joystick's unique identifier. Remains the same as long as the game is running.
instanceidnumberUnique 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()

namestringThe name of the joystick.

Joystick:getVibration

Gets the current vibration motor strengths on a Joystick with rumble support.

left, right = Joystick:getVibration()

leftnumberCurrent strength of the left vibration motor on the Joystick.
rightnumberCurrent strength of the right vibration motor on the Joystick.

Joystick:isConnected

Gets whether the Joystick is connected.

connected = Joystick:isConnected()

connectedbooleanTrue 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( ... )

anyDownbooleanTrue if any supplied button is down, false if not.
...numberThe 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 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()

isgamepadbooleanTrue 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( ... )

anyDownbooleanTrue if any supplied button is down, false if not.
...GamepadButtonThe gamepad button to check.

Joystick:isVibrationSupported

Gets whether the Joystick supports vibration.

supported = Joystick:isVibrationSupported()

supportedbooleanTrue 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.

success = Joystick:setVibration( left, right, duration )

successbooleanTrue if the vibration was successfully applied, false if not.
leftnumberStrength of the left vibration motor on the Joystick. Must be in the range of [0, 1].
rightnumberStrength of the right vibration motor on the Joystick. Must be in the range of [0, 1].
duration (-1)numberThe 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 )

keyKeyConstantThe key corresponding to the given scancode, or "unknown" if the scancode doesn't map to a KeyConstant on the current system.
scancodeScancodeThe 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 )

scancodeScancodeThe scancode corresponding to the given key, or "unknown" if the given key has no known physical representation on the current system.
keyKeyConstantThe key to get the scancode from.

love.keyboard.hasKeyRepeat

Gets whether key repeat is enabled.

enabled = love.keyboard.hasKeyRepeat()

enabledbooleanWhether key repeat is enabled.

love.keyboard.hasTextInput

Gets whether text input events are enabled.

enabled = love.keyboard.hasTextInput()

enabledbooleanWhether 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.

anyDown = love.keyboard.isDown( key, ... )

anyDownbooleanTrue if any supplied key is down, false if not.
keyKeyConstantA key to check.
...KeyConstantAdditional 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, ... )

downbooleanTrue if any supplied Scancode is down, false if not.
scancodeScancodeA Scancode to check.
...ScancodeAdditional Scancodes to check.

love.keyboard.setKeyRepeat

Enables or disables key repeat. It is disabled by default.

The interval between repeats depends on the user's system settings.

love.keyboard.setKeyRepeat( enable )

enablebooleanWhether 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.

love.keyboard.setTextInput( enable )

enablebooleanWhether text input events should be enabled.

love.keyboard.setTextInput( enable, x, y, w, h )

enablebooleanWhether text input events should be enabled.
xnumberOn-screen keyboard x position.
ynumberOn-screen keyboard y position.
wnumberOn-screen keyboard width.
hnumberOn-screen keyboard 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

In version 0.9.2 and earlier this is represented by the actual space character

!

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

Also known as the "Back tick" 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

Also known as the Enter 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

Caps-on is a key press. Caps-off is a key release.

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.compress

Compresses a string or data using a specific compression algorithm.

compressedData = love.math.compress( rawstring, format, level )

compressedDataCompressedDataA new Data object containing the compressed version of the string.
rawstringstringThe raw (un-compressed) string to compress.
format ("lz4")CompressedDataFormatThe format to use when compressing the string.
level (-1)numberThe 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 )

compressedDataCompressedDataA new Data object containing the compressed version of the raw data.
dataDataA Data object containing the raw (un-compressed) data to compress.
format ("lz4")CompressedDataFormatThe format to use when compressing the data.
level (-1)numberThe 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 )

rawstringstringA string containing the raw decompressed data.
compressedDataCompressedDataThe compressed data to decompress.

rawstring = love.math.decompress( compressedString, format )

rawstringstringA string containing the raw decompressed data.
compressedStringstringA string containing data previously compressed with love.math.compress.
formatCompressedDataFormatThe format that was used to compress the given string.

rawstring = love.math.decompress( data, format )

rawstringstringA string containing the raw decompressed data.
dataDataA Data object containing data previously compressed with love.math.compress.
formatCompressedDataFormatThe 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.

lr, lg, lb = love.math.gammaToLinear( r, g, b )

lrnumberThe red channel of the converted color in linear RGB space.
lgnumberThe green channel of the converted color in linear RGB space.
lbnumberThe blue channel of the converted color in linear RGB space.
rnumberThe red channel of the sRGB color to convert.
gnumberThe green channel of the sRGB color to convert.
bnumberThe blue channel of the sRGB color to convert.

lr, lg, lb = love.math.gammaToLinear( color )

lrnumberThe red channel of the converted color in linear RGB space.
lgnumberThe green channel of the converted color in linear RGB space.
lbnumberThe blue channel of the converted color in linear RGB space.
colortableAn array with the red, green, and blue channels of the sRGB color to convert.

lc = love.math.gammaToLinear( c )

lcnumberThe value of the color channel in linear RGB space.
cnumberThe value of a color channel in sRGB space to convert.

love.math.getRandomSeed

Gets the seed of the random number generator.

The state 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.

low, high = love.math.getRandomSeed()

lownumberInteger number representing the lower 32 bits of the random number generator's 64 bit state value.
highnumberInteger number representing the higher 32 bits of the random number generator's 64 bit state 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 RandomGenerator:setState.

This is different from RandomGenerator:getSeed in that getState gets the RandomGenerator's current state, whereas getSeed gets the previously set seed number.

The value of the state string does not depend on the current operating system.

state = love.math.getRandomState()

statestringThe current state of the RandomGenerator object, represented as a string.

love.math.isConvex

Checks whether a polygon is convex.

PolygonShapes in love.physics, some forms of Mesh, and polygons drawn with love.graphics.polygon must be simple convex polygons.

convex = love.math.isConvex( vertices )

convexbooleanWhether the given polygon is convex.
verticestableThe 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, ... )

convexbooleanWhether the given polygon is convex.
x1numberThe position of the first vertex of the polygon on the x-axis.
y1numberThe position of the first vertex of the polygon on the y-axis.
x2numberThe position of the second vertex of the polygon on the x-axis.
y2numberThe position of the second vertex of the polygon on the y-axis.
x3numberThe position of the third vertex of the polygon on the x-axis.
y3numberThe position of the third vertex of the polygon on the y-axis.
...numberAdditional vertices.

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.

cr, cg, cb = love.math.linearToGamma( lr, lg, lb )

crnumberThe red channel of the converted color in gamma sRGB space.
cgnumberThe green channel of the converted color in gamma sRGB space.
cbnumberThe blue channel of the converted color in gamma sRGB space.
lrnumberThe red channel of the linear RGB color to convert.
lgnumberThe green channel of the linear RGB color to convert.
lbnumberThe blue channel of the linear RGB color to convert.

cr, cg, cb = love.math.linearToGamma( color )

crnumberThe red channel of the converted color in gamma sRGB space.
cgnumberThe green channel of the converted color in gamma sRGB space.
cbnumberThe blue channel of the converted color in gamma sRGB space.
colortableAn array with the red, green, and blue channels of the linear RGB color to convert.

c = love.math.linearToGamma( lc )

cnumberThe value of the color channel in gamma sRGB space.
lcnumberThe 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 )

curveBezierCurveA Bézier curve object.
verticestableThe 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, ... )

curveBezierCurveA Bézier curve object.
x1numberThe position of the first vertex of the control polygon on the x-axis.
y1numberThe position of the first vertex of the control polygon on the y-axis.
x2numberThe position of the second vertex of the control polygon on the x-axis.
y2numberThe position of the second vertex of the control polygon on the y-axis.
x3numberThe position of the third vertex of the control polygon on the x-axis.
y3numberThe position of the third vertex of the control polygon on the y-axis.
...numberAdditional vertices.

love.math.newRandomGenerator

Creates a new RandomGenerator object which is completely independent of other RandomGenerator objects and random functions.

rng = love.math.newRandomGenerator()

rngRandomGeneratorThe new Random Number Generator object.

rng = love.math.newRandomGenerator( seed )

rngRandomGeneratorThe new Random Number Generator object.
seednumberThe initial seed number to use for this object.

rng = love.math.newRandomGenerator( low, high )

rngRandomGeneratorThe new Random Number Generator object.
lownumberThe lower 32 bits of the state number to use for this instance of the object.
highnumberThe higher 32 bits of the state number to use for this instance of the object.

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.

valuenumberThe noise value in the range of [0, 1].
xnumberThe number used to generate the noise value.

value = love.math.noise( x, y )

Generates Simplex noise from 2 dimensions.

valuenumberThe noise value in the range of [0, 1].
xnumberThe first value of the 2-dimensional vector used to generate the noise value.
ynumberThe 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.

valuenumberThe noise value in the range of [0, 1].
xnumberThe first value of the 3-dimensional vector used to generate the noise value.
ynumberThe second value of the 3-dimensional vector used to generate the noise value.
znumberThe 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.

valuenumberThe noise value in the range of [0, 1].
xnumberThe first value of the 4-dimensional vector used to generate the noise value.
ynumberThe second value of the 4-dimensional vector used to generate the noise value.
znumberThe third value of the 4-dimensional vector used to generate the noise value.
wnumberThe 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.

number = love.math.random()

Get uniformly distributed pseudo-random real number within [0, 1].

numbernumberThe pseudo-random number.

number = love.math.random( max )

Get a uniformly distributed pseudo-random integer within [1, max].

numbernumberThe pseudo-random integer number.
maxnumberThe maximum possible value it should return.

number = love.math.random( min, max )

Get uniformly distributed pseudo-random integer within [min, max].

numbernumberThe pseudo-random integer number.
minnumberThe minimum possible value it should return.
maxnumberThe maximum possible value it should return.

love.math.randomNormal

Get a normally distributed pseudo random number.

number = love.math.randomNormal( stddev, mean )

numbernumberNormally distributed random number with variance (stddev)² and the specified mean.
stddev (1)numberStandard deviation of the distribution.
mean (0)numberThe mean of the distribution.

love.math.setRandomSeed

Sets the seed of the random number generator using the specified integer number.

love.math.setRandomSeed( seed )

seednumberThe integer number with which you want to seed the randomization. Must be within the range of [1, 2^53].

love.math.setRandomSeed( low, high )

lownumberThe lower 32 bits of the state value. Must be within the range of [0, 2^32 - 1].
highnumberThe higher 32 bits of the state value. Must be within the range of [0, 2^32 - 1].

love.math.setRandomState

Gets the current state of the random number generator. This returns an opaque implementation-dependent string which is only useful for later use with RandomGenerator:setState.

This is different from RandomGenerator:getSeed in that getState gets the RandomGenerator's current state, whereas getSeed gets the previously set seed number.

The value of the state string does not depend on the current operating system.

love.math.setRandomState( state )

statestringThe current state of the RandomGenerator object, represented as a string.

love.math.triangulate

Triangulate a simple polygon.

triangles = love.math.triangulate( polygon )

trianglestableList of triangles the polygon is composed of, in the form of {{x1, y1, x2, y2, x3, y3}, {x1, y1, x2, y2, x3, y3}, ...}.
polygontablePolygon to triangulate. Must not intersect itself.

triangles = love.math.triangulate( x1, y1, x2, y2, x3, y3, ... )

trianglestableList of triangles the polygon is composed of, in the form of {{x1, y1, x2, y2, x3, y3}, {x1, y1, x2, y2, x3, y3}, ...}.
x1numberThe position of the first vertex of the polygon on the x-axis.
y1numberThe position of the first vertex of the polygon on the y-axis.
x2numberThe position of the second vertex of the polygon on the x-axis.
y2numberThe position of the second vertex of the polygon on the y-axis.
x3numberThe position of the third vertex of the polygon on the x-axis.
y3numberThe position of the third vertex of the polygon on the y-axis.
...numberAdditional vertices.

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.

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.

BezierCurve

A Bézier curve object that can evaluate and render Bézier curves of arbitrary degree.

Constructors

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 )

xnumberx coordinate of the curve at parameter t.
ynumbery coordinate of the curve at parameter t.
tnumberWhere to evaluate the curve.

BezierCurve:getControlPoint

Get coordinates of the i-th control point. Indices start with 1.

x, y = BezierCurve:getControlPoint( i )

xnumberPosition of the control point along the x axis.
ynumberPosition of the control point along the y axis.
inumberIndex of the control point.

BezierCurve:getControlPointCount

Get the number of control points in the Bézier curve.

count = BezierCurve:getControlPointCount()

countnumberThe 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()

degreenumberDegree 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()

derivativeBezierCurveThe derivative curve.

BezierCurve:getSegment

Gets a BezierCurve that corresponds to the specified segment of this BezierCurve.

curve = BezierCurve:getSegment( startpoint, endpoint )

curveBezierCurveA BezierCurve that corresponds to the specified segment.
startpointnumberThe starting point along the curve. Must be between 0 and 1.
endpointnumberThe 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 )

xnumberPosition of the control point along the x axis.
ynumberPosition of the control point along the y axis.
i (-1)numberIndex of the control point.

BezierCurve:removeControlPoint

Removes the specified control point.

BezierCurve:removeControlPoint( index )

indexnumberThe 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 )

coordinatestableList of x,y-coordinate pairs of points on the curve.
depth (5)numberNumber 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 )

coordinatestableList of x,y-coordinate pairs of points on the curve.
startpointnumberThe starting point along the curve. Must be between 0 and 1.
endpointnumberThe end of the segment to render. Must be between 0 and 1.
depth (5)numberNumber of recursive subdivision steps.

BezierCurve:rotate

Rotate the Bézier curve by an angle.

BezierCurve:rotate( angle, ox, oy )

anglenumberRotation angle in radians.
ox (0)numberX coordinate of the rotation center.
oy (0)numberY coordinate of the rotation center.

BezierCurve:scale

Scale the Bézier curve by a factor.

BezierCurve:scale( s, ox, oy )

snumberScale factor.
ox (0)numberX coordinate of the scaling center.
oy (0)numberY coordinate of the scaling center.

BezierCurve:setControlPoint

Set coordinates of the i-th control point. Indices start with 1.

BezierCurve:setControlPoint( i, ox, oy )

inumberIndex of the control point.
oxnumberPosition of the control point along the x axis.
oynumberPosition of the control point along the y axis.

BezierCurve:translate

Move the Bézier curve by an offset.

BezierCurve:translate( dx, dy )

dxnumberOffset along the x axis.
dynumberOffset along the y axis.

CompressedData

Represents byte data compressed using a specific algorithm.

love.math.decompress can be used to de-compress the data.

Constructors

Functions

Supertypes

CompressedData:getFormat

Gets the compression format of the CompressedData.

format = CompressedData:getFormat()

formatCompressedDataFormatThe format of the CompressedData.

RandomGenerator

A random number generation object which has its own random state.

Constructors

Functions

Supertypes

RandomGenerator:getSeed

Gets the state of the random number generator.

The state 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.

low, high = RandomGenerator:getSeed()

lownumberInteger number representing the lower 32 bits of the random number generator's 64 bit state value.
highnumberInteger number representing the higher 32 bits of the random number generator's 64 bit state value.

RandomGenerator:getState

Gets the current state of the random number generator. This returns an opaque implementation-dependent string which is only useful for later use with RandomGenerator:setState.

This is different from RandomGenerator:getSeed in that getState gets the RandomGenerator's current state, whereas getSeed gets the previously set seed number.

The value of the state string does not depend on the current operating system.

state = RandomGenerator:getState()

statestringThe 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 [0, 1].

numbernumberThe pseudo random number.

number = RandomGenerator:random( max )

Get uniformly distributed pseudo-random integer number within [1, max].

numbernumberThe pseudo-random integer number.
maxnumberThe maximum possible value it should return.

number = RandomGenerator:random( min, max )

Get uniformly distributed pseudo-random integer number within [min, max].

numbernumberThe pseudo-random integer number.
minnumberThe minimum possible value it should return.
maxnumberThe maximum possible value it should return.

RandomGenerator:randomNormal

Get a normally distributed pseudo random number.

number = RandomGenerator:randomNormal( stddev, mean )

numbernumberNormally distributed random number with variance (stddev)² and the specified mean.
stddev (1)numberStandard deviation of the distribution.
mean (0)numberThe mean of the distribution.

RandomGenerator:setSeed

Sets the seed of the random number generator using the specified integer number.

RandomGenerator:setSeed( seed )

seednumberThe integer number with which you want to seed the randomization. Must be within the range of [1, 2^53].

RandomGenerator:setSeed( low, high )

lownumberThe lower 32 bits of the state value. Must be within the range of [0, 2^32 - 1].
high (0)numberThe higher 32 bits of the state value. Must be within the range of [0, 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 implementation-dependent string and should only originate from a previous call to RandomGenerator:getState.

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.

The effect of the state string does not depend on the current operating system.

RandomGenerator:setState( state )

statestringThe new state of the RandomGenerator object, represented as a string. This should originate from a previous call to RandomGenerator:getState.

love.mouse

Types

Functions

Input

Cursor

Enums

love.mouse.getCursor

Gets the current Cursor.

cursor = love.mouse.getCursor()

cursorCursorThe current cursor, or nil if no cursor is set.

love.mouse.getPosition

Gets the current position of the mouse.

x, y = love.mouse.getPosition()

xnumberThe position of the mouse along the x-axis.
ynumberThe 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()

enabledbooleanTrue 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 )

cursorCursorThe Cursor object representing the system cursor type.
ctypeCursorTypeThe type of system cursor to get.

love.mouse.getX

Gets the current x position of the mouse.

x = love.mouse.getX()

xnumberThe position of the mouse along the x-axis.

love.mouse.getY

Gets the current y position of the mouse.

y = love.mouse.getY()

ynumberThe 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()

hascursorbooleanWhether the system has cursor functionality.

love.mouse.isDown

Checks whether a certain mouse button is down. This function does not detect mousewheel 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, ... )

downbooleanTrue if the specified button is down.
buttonnumberThe index of a button to check. 1 is the primary mouse button, 2 is the secondary mouse button, etc.
...numberAdditional button numbers to check.

love.mouse.isGrabbed

Checks if the mouse is grabbed.

grabbed = love.mouse.isGrabbed()

grabbedbooleanTrue if the cursor is grabbed, false if it is not.

love.mouse.isVisible

Checks if the cursor is visible.

visible = love.mouse.isVisible()

visiblebooleanTrue if the cursor to visible, false if the cursor is hidden.

love.mouse.newCursor

Creates a new hardware Cursor object from an image file or ImageData.

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.

The hot spot is the point the operating system uses to determine what was clicked and at what position the mouse cursor is. For example, the normal arrow pointer normally has its hot spot at the top left of the image, but a crosshair cursor might have it in the middle.

cursor = love.mouse.newCursor( imageData, hotx, hoty )

cursorCursorThe new Cursor object.
imageDataImageDataThe ImageData to use for the the new Cursor.
hotx (0)numberThe x-coordinate in the ImageData of the cursor's hot spot.
hoty (0)numberThe y-coordinate in the ImageData of the cursor's hot spot.

cursor = love.mouse.newCursor( filepath, hotx, hoty )

cursorCursorThe new Cursor object.
filepathstringPath to the image to use for the new Cursor.
hotx (0)numberThe x-coordinate in the ImageData of the cursor's hot spot.
hoty (0)numberThe y-coordinate in the ImageData of the cursor's hot spot.

cursor = love.mouse.newCursor( fileData, hotx, hoty )

cursorCursorThe new Cursor object.
fileDataFileDataData representing the image to use for the new Cursor.
hotx (0)numberThe x-coordinate in the ImageData of the cursor's hot spot.
hoty (0)numberThe y-coordinate in the ImageData of the cursor's hot spot.

love.mouse.setCursor

Sets the current mouse cursor.

Resets the current mouse cursor to the default when called without arguments.

love.mouse.setCursor()

love.mouse.setCursor( cursor )

cursorCursorThe Cursor object to use as the current mouse cursor.

love.mouse.setGrabbed

Grabs the mouse and confines it to the window.

love.mouse.setGrabbed( grab )

grabbooleanTrue to confine the mouse, false to let it leave the window.

love.mouse.setPosition

Sets the current position of the mouse. Non-integer values are floored.

love.mouse.setPosition( x, y )

xnumberThe new position of the mouse along the x-axis.
ynumberThe new position of the mouse along the y-axis.

love.mouse.setRelativeMode

Sets whether relative mode is enabled for the mouse.

When 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.

love.mouse.setRelativeMode( enable )

enablebooleanTrue to enable relative mode, false to disable it.

love.mouse.setVisible

Sets the visibility of the cursor.

love.mouse.setVisible( visible )

visiblebooleanTrue to set the cursor to visible, false to hide the cursor.

love.mouse.setX

Sets the current X position of the mouse. Non-integer values are floored.

love.mouse.setX( x )

xnumberThe new position of the mouse along the x-axis.

love.mouse.setY

Sets the current Y position of the mouse. Non-integer values are floored.

love.mouse.setY( y )

ynumberThe new position of the mouse along the y-axis.

CursorType

image

The cursor is using a custom image.

arrow

An arrow pointer.

ibeam

An I-beam, normally used when mousing over editable or selectable text.

wait

Wait graphic.

waitarrow

Small wait cursor with an arrow pointer.

crosshair

Crosshair symbol.

sizenwse

Double arrow pointing to the top-left and bottom-right.

sizenesw

Double arrow pointing to the top-right and bottom-left.

sizewe

Double arrow pointing left and right.

sizens

Double arrow pointing up and down.

sizeall

Four-pointed arrow pointing up, down, left, and right.

no

Slashed circle or crossbones.

hand

Hand symbol.

Cursor

Represents a hardware cursor.

Constructors

Functions

Supertypes

Cursor:getType

Gets the type of the Cursor.

cursortype = Cursor:getType()

cursortypeCursorTypeThe type of the Cursor.

love.physics

Types

Functions

Enums

love.physics.getDistance

Gets the two closest points between two fixtures and their distance.

distance, x1, y1, x2, y2 = love.physics.getDistance( fixture1, fixture2 )

distancenumberThe distance of the two points.
x1numberThe x-coordinate of the first point.
y1numberThe y-coordinate of the first point.
x2numberThe x-coordinate of the second point.
y2numberThe y-coordinate of the second point.
fixture1FixtureThe first fixture.
fixture2FixtureThe second fixture.

love.physics.getMeter

Get the scale of the world.

The world scale is the number of pixels per meter. Try to keep your shape sizes less than 10 times this scale.

This is important because the physics in Box2D is tuned to work well for objects of size 0.1m up to 10m. All physics coordinates are divided by this number for the physics calculations.

scale = love.physics.getMeter()

scalenumberThe size of 1 meter in pixels.

love.physics.newBody

Creates a new body.

There are three types of bodies. Static bodies do not move, have a infinite mass, and can be used for level boundaries. Dynamic bodies are the main actors in the simulation, they collide with everything. Kinematic bodies do not react to forces and only collide with dynamic bodies.

The mass of the body gets calculated when a Fixture is attached or removed, but can be changed at any time with Body:setMass or Body:resetMassData.

body = love.physics.newBody( world, x, y, type )

bodyBodyA new body.
worldWorldThe world to create the body in.
x (0)numberThe x position of the body.
y (0)numberThe y position of the body.
type ("static")BodyTypeThe type of the body.

love.physics.newChainShape

Creates a new ChainShape.

shape = love.physics.newChainShape( loop, x1, y1, x2, y2, ... )

shapeChainShapeThe new shape.
loopbooleanIf the chain should loop back to the first point.
x1numberThe x position of the first point.
y1numberThe y position of the first point.
x2numberThe x position of the second point.
y2numberThe y position of the second point.
...numberAdditional point positions.

shape = love.physics.newChainShape( loop, points )

shapeChainShapeThe new shape.
loopbooleanIf the chain should loop back to the first point.
pointstableA list of points to construct the ChainShape, in the form of {x1, y1, x2, y2, ...}.

love.physics.newCircleShape

Creates a new CircleShape.

shape = love.physics.newCircleShape( radius )

shapeCircleShapeThe new shape.
radiusnumberThe radius of the circle.

shape = love.physics.newCircleShape( x, y, radius )

shapeCircleShapeThe new shape.
xnumberThe x offset of the circle.
ynumberThe y offset of the circle.
radiusnumberThe radius of the circle.

love.physics.newDistanceJoint

Create a distance joint between two bodies.

This joint constrains the distance between two points on two bodies to be constant. These two points are specified in world coordinates and the two bodies are assumed to be in place when this joint is created. The first anchor point is connected to the first body and the second to the second body, and the points define the length of the distance joint.

joint = love.physics.newDistanceJoint( body1, body2, x1, y1, x2, y2, collideConnected )

jointDistanceJointThe new distance joint.
body1BodyThe first body to attach to the joint.
body2BodyThe second body to attach to the joint.
x1numberThe x position of the first anchor point (world space).
y1numberThe y position of the first anchor point (world space).
x2numberThe x position of the second anchor point (world space).
y2numberThe y position of the second anchor point (world space).
collideConnected (false)booleanSpecifies whether the two bodies should collide with each other.

love.physics.newEdgeShape

Creates a edge shape.

shape = love.physics.newEdgeShape( x1, y1, x2, y2 )

shapeEdgeShapeThe new shape.
x1numberThe x position of the first point.
y1numberThe y position of the first point.
x2numberThe x position of the second point.
y2numberThe y position of the second point.

love.physics.newFixture

Creates and attaches a Fixture to a body.

fixture = love.physics.newFixture( body, shape, density )

fixtureFixtureThe new fixture.
bodyBodyThe body which gets the fixture attached.
shapeShapeThe shape of the fixture.
density (1)numberThe density of the fixture.

love.physics.newFrictionJoint

Create a friction joint between two bodies. A FrictionJoint applies friction to a body.

joint = love.physics.newFrictionJoint( body1, body2, x, y, collideConnected )

jointFrictionJointThe new FrictionJoint.
body1BodyThe first body to attach to the joint.
body2BodyThe second body to attach to the joint.
xnumberThe x position of the anchor point.
ynumberThe y position of the anchor point.
collideConnected (false)booleanSpecifies whether the two bodies should collide with eachother.

love.physics.newGearJoint

Create a gear joint connecting two joints.

The gear joint connects two joints that must be either prismatic or revolute joints. Using this joint requires that the joints it uses connect their respective bodies to the ground and have the ground as the first body. When destroying the bodies and joints you must make sure you destroy the gear joint before the other joints.

The gear joint has a ratio the determines how the angular or distance values of the connected joints relate to each other. The formula coordinate1 + ratio * coordinate2 always has a constant value that is set when the gear joint is created.

joint = love.physics.newGearJoint( joint1, joint2, ratio, collideConnected )

jointGearJointThe new gear joint.
joint1JointThe first joint to connect with a gear joint.
joint2JointThe second joint to connect with a gear joint.
ratio (1)numberThe gear ratio.
collideConnected (false)booleanSpecifies whether the two bodies should collide with each other.

love.physics.newMotorJoint

Creates a joint between two bodies which controls the relative motion between them.

Position and rotation offsets can be specified once the MotorJoint has been created, as well as the maximum motor force and torque that will be be applied to reach the target offsets.

joint = love.physics.newMotorJoint( body1, body2, correctionFactor, collideConnected )

jointMotorJointThe new MotorJoint.
body1BodyThe first body to attach to the joint.
body2BodyThe second body to attach to the joint.
correctionFactor (0.3)numberThe joint's initial position correction factor, in the range of [0, 1].
collideConnected (false)booleanSpecifies whether the two bodies should collide with each other.

love.physics.newMouseJoint

Create a joint between a body and the mouse.

This joint actually connects the body to a fixed point in the world. To make it follow the mouse, the fixed point must be updated every timestep (example below).

The advantage of using a MouseJoint instead of just changing a body position directly is that collisions and reactions to other joints are handled by the physics engine.

joint = love.physics.newMouseJoint( body, x, y )

jointMouseJointThe new mouse joint.
bodyBodyThe body to attach to the mouse.
xnumberThe x position of the connecting point.
ynumberThe y position of the connecting point.

love.physics.newPolygonShape

Creates a new PolygonShape.

This shape can have 8 vertices at most, and must form a convex shape.

shape = love.physics.newPolygonShape( x1, y1, x2, y2, ... )

shapePolygonShapeA new PolygonShape.
x1numberThe position of first point on the x-axis.
y1numberThe position of first point on the y-axis.
x2numberThe position of second point on the x-axis.
y2numberThe position of second point on the y-axis.
...numberYou can continue passing more point positions to create the PolygonShape.

shape = love.physics.newPolygonShape( vertices )

shapePolygonShapeA new PolygonShape.
verticestableA list of vertices to construct the polygon, in the form of {x1, y1, x2, y2, x3, y3, ...}.

love.physics.newPrismaticJoint

Create a prismatic joints between two bodies.

A prismatic joint constrains two bodies to move relatively to each other on a specified axis. It does not allow for relative rotation. Its definition and operation are similar to a revolute joint, but with translation and force substituted for angle and torque.

joint = love.physics.newPrismaticJoint( body1, body2, x1, y1, x2, y2, ax, ay, collideConnected, referenceAngle )

jointPrismaticJointThe new prismatic joint.
body1BodyThe first body to connect with a prismatic joint.
body2BodyThe second body to connect with a prismatic joint.
x1numberThe x coordinate of the first anchor point.
y1numberThe y coordinate of the first anchor point.
x2numberThe x coordinate of the second anchor point.
y2numberThe y coordinate of the second anchor point.
axnumberThe x coordinate of the axis unit vector.
aynumberThe y coordinate of the axis unit vector.
collideConnected (false)booleanSpecifies whether the two bodies should collide with each other.
referenceAngle (0)numberThe reference angle between body1 and body2, in radians.

love.physics.newPulleyJoint

Create a pulley joint to join two bodies to each other and the ground.

The pulley joint simulates a pulley with an optional block and tackle. If the ratio parameter has a value different from one, then the simulated rope extends faster on one side than the other. In a pulley joint the total length of the simulated rope is the constant length1 + ratio * length2, which is set when the pulley joint is created.

Pulley joints can behave unpredictably if one side is fully extended. It is recommended that the method setMaxLengths be used to constrain the maximum lengths each side can attain.

joint = love.physics.newPulleyJoint( body1, body2, gx1, gy1, gx2, gy2, x1, y1, x2, y2, ratio, collideConnected )

jointPulleyJointThe new pulley joint.
body1BodyThe first body to connect with a pulley joint.
body2BodyThe second body to connect with a pulley joint.
gx1numberThe x coordinate of the first body's ground anchor.
gy1numberThe y coordinate of the first body's ground anchor.
gx2numberThe x coordinate of the second body's ground anchor.
gy2numberThe y coordinate of the second body's ground anchor.
x1numberThe x coordinate of the pulley joint anchor in the first body.
y1numberThe y coordinate of the pulley joint anchor in the first body.
x2numberThe x coordinate of the pulley joint anchor in the second body.
y2numberThe y coordinate of the pulley joint anchor in the second body.
ratio (1)numberThe joint ratio.
collideConnected (true)booleanSpecifies whether the two bodies should collide with each other.

love.physics.newRectangleShape

Shorthand for creating rectangular PolygonShapes.

By default, the local origin is located at the center of the rectangle as opposed to the top left for graphics.

shape = love.physics.newRectangleShape( width, height )

shapePolygonShapeA new PolygonShape.
widthnumberThe width of the rectangle.
heightnumberThe height of the rectangle.

shape = love.physics.newRectangleShape( x, y, width, height, angle )

shapePolygonShapeA new PolygonShape.
xnumberThe offset along the x-axis.
ynumberThe offset along the y-axis.
widthnumberThe width of the rectangle.
heightnumberThe height of the rectangle.
angle (0)numberThe initial angle of the rectangle.

love.physics.newRevoluteJoint

Creates a pivot joint between two bodies.

This joint connects two bodies to a point around which they can pivot.

joint = love.physics.newRevoluteJoint( body1, body2, x, y, collideConnected )

jointRevoluteJointThe new revolute joint.
body1BodyThe first body.
body2BodyThe second body.
xnumberThe x position of the connecting point.
ynumberThe y position of the connecting point.
collideConnected (false)booleanSpecifies whether the two bodies should collide with each other.

joint = love.physics.newRevoluteJoint( body1, body2, x1, y1, x2, y2, collideConnected, referenceAngle )

jointRevoluteJointThe new revolute joint.
body1BodyThe first body.
body2BodyThe second body.
x1numberThe x position of the first connecting point.
y1numberThe y position of the first connecting point.
x2numberThe x position of the second connecting point.
y2numberThe y position of the second connecting point.
collideConnected (false)booleanSpecifies whether the two bodies should collide with each other.
referenceAngle (0)numberSpecifies whether the two bodies should collide with each other.

love.physics.newRopeJoint

Create a joint between two bodies. Its only function is enforcing a max distance between these bodies.

joint = love.physics.newRopeJoint( body1, body2, x1, y1, x2, y2, maxLength, collideConnected )

jointRopeJointThe new RopeJoint.
body1BodyThe first body to attach to the joint.
body2BodyThe second body to attach to the joint.
x1numberThe x position of the first anchor point.
y1numberThe y position of the first anchor point.
x2numberThe x position of the second anchor point.
y2numberThe y position of the second anchor point.
maxLengthnumberThe maximum distance for the bodies.
collideConnected (false)booleanSpecifies whether the two bodies should collide with each other.

love.physics.newWeldJoint

Creates a constraint joint between two bodies. A WeldJoint essentially glues two bodies together. The constraint is a bit soft, however, due to Box2D's iterative solver.

joint = love.physics.newWeldJoint( body1, body2, x1, y1, x2, y2, collideConnected, referenceAngle )

jointWeldJointThe new WeldJoint.
body1BodyThe first body to attach to the joint.
body2BodyThe second body to attach to the joint.
x1numberThe x position of the first anchor point (world space).
y1numberThe y position of the first anchor point (world space).
x2numberThe x position of the second anchor point (world space).
y2numberThe y position of the second anchor point (world space).
collideConnected (false)booleanSpecifies whether the two bodies should collide with each other.
referenceAngle (0)numberThe reference angle between body1 and body2, in radians.

love.physics.newWheelJoint

Creates a wheel joint.

joint = love.physics.newWheelJoint( body1, body2, x, y, ax, ay, collideConnected )

jointWheelJointThe new WheelJoint.
body1BodyThe first body.
body2BodyThe second body.
xnumberThe x position of the anchor point.
ynumberThe y position of the anchor point.
axnumberThe x position of the axis unit vector.
aynumberThe y position of the axis unit vector.
collideConnected (false)booleanSpecifies whether the two bodies should collide with each other.

love.physics.newWorld

Creates a new World.

world = love.physics.newWorld( xg, yg, sleep )

worldWorldA brave new World.
xg (0)numberThe x component of gravity.
yg (0)numberThe y component of gravity.
sleep (true)booleanWhether the bodies in this world are allowed to sleep.

love.physics.setMeter

Sets the pixels to meter scale factor.

All coordinates in the physics module are divided by this number and converted to meters, and it creates a convenient way to draw the objects directly to the screen without the need for graphics transformations.

It is recommended to create shapes no larger than 10 times the scale. This is important because Box2D is tuned to work well with shape sizes from 0.1 to 10 meters. The default meter scale is 30.

love.physics.setMeter does not apply retroactively to created objects. Created objects retain their meter coordinates but the scale factor will affect their pixel coordinates.

love.physics.setMeter( scale )

scalenumberThe scale factor as an integer.

BodyType

static

Static bodies do not move.

dynamic

Dynamic bodies collide with all bodies.

kinematic

Kinematic bodies only collide with dynamic bodies.

JointType

distance

A DistanceJoint.

gear

A GearJoint.

mouse

A MouseJoint.

prismatic

A PrismaticJoint.

pulley

A PulleyJoint.

revolute

A RevoluteJoint.

friction

A FrictionJoint.

weld

A WeldJoint.

rope

A RopeJoint.

ShapeType

circle

The Shape is a CircleShape.

polygon

The Shape is a PolygonShape.

edge

The Shape is a EdgeShape.

chain

The Shape is a ChainShape.

Body

Bodies are objects with velocity and position.

Constructors

Functions

Supertypes

Body:applyAngularImpulse

Applies an angular impulse to a body. This makes a single, instantaneous addition to the body momentum.

A body with with a larger mass will react less. The reaction does not depend on the timestep, and is equivalent to applying a force continuously for 1 second. Impulses are best used to give a single push to a body. For a continuous push to a body it is better to use Body:applyForce.

Body:applyAngularImpulse( impulse )

impulsenumberThe impulse in kilogram-square meter per second.

Body:applyForce

Apply force to a Body.

A force pushes a body in a direction. A body with with a larger mass will react less. The reaction also depends on how long a force is applied: since the force acts continuously over the entire timestep, a short timestep will only push the body for a short time. Thus forces are best used for many timesteps to give a continuous push to a body (like gravity). For a single push that is independent of timestep, it is better to use Body:applyLinearImpulse.

If the position to apply the force is not given, it will act on the center of mass of the body. The part of the force not directed towards the center of mass will cause the body to spin (and depends on the rotational inertia).

Note that the force components and position must be given in world coordinates.

Body:applyForce( fx, fy )

fxnumberThe x component of force to apply to the center of mass.
fynumberThe y component of force to apply to the center of mass.

Body:applyForce( fx, fy, x, y )

fxnumberThe x component of force to apply.
fynumberThe y component of force to apply.
xnumberThe x position to apply the force.
ynumberThe y position to apply the force.

Body:applyLinearImpulse

Applies an impulse to a body. This makes a single, instantaneous addition to the body momentum.

An impulse pushes a body in a direction. A body with with a larger mass will react less. The reaction does not depend on the timestep, and is equivalent to applying a force continuously for 1 second. Impulses are best used to give a single push to a body. For a continuous push to a body it is better to use Body:applyForce.

If the position to apply the impulse is not given, it will act on the center of mass of the body. The part of the impulse not directed towards the center of mass will cause the body to spin (and depends on the rotational inertia).

Note that the impulse components and position must be given in world coordinates.

Body:applyLinearImpulse( ix, iy )

ixnumberThe x component of the impulse applied to the center of mass.
iynumberThe y component of the impulse applied to the center of mass.

Body:applyLinearImpulse( ix, iy, x, y )

ixnumberThe x component of the impulse.
iynumberThe y component of the impulse.
xnumberThe x position to apply the impulse.
ynumberThe y position to apply the impulse.

Body:applyTorque

Apply torque to a body.

Torque is like a force that will change the angular velocity (spin) of a body. The effect will depend on the rotational inertia a body has.

Body:applyTorque( torque )

torquenumberThe torque to apply.

Body:destroy

Explicitly destroys the Body. When you don't have time to wait for garbage collection, this function may be used to free the object immediately, but note that an error will occur if you attempt to use the object after calling this function.

Body:destroy()

Body:getAngle

Get the angle of the body.

The angle is measured in radians. If you need to transform it to degrees, use math.deg.

A value of 0 radians will mean "looking to the right". Although radians increase counter-clockwise, the y-axis points down so it becomes clockwise from our point of view.

angle = Body:getAngle()

anglenumberThe angle in radians.

Body:getAngularDamping

Gets the Angular damping of the Body

The angular damping is the rate of decrease of the angular velocity over time: A spinning body with no damping and no external forces will continue spinning indefinitely. A spinning body with damping will gradually stop spinning.

Damping is not the same as friction - they can be modelled together. However, only damping is provided by Box2D (and LÖVE).

Damping parameters should be between 0 and infinity, with 0 meaning no damping, and infinity meaning full damping. Normally you will use a damping value between 0 and 0.1.

damping = Body:getAngularDamping()

dampingnumberThe value of the angular damping.

Body:getAngularVelocity

Get the angular velocity of the Body.

The angular velocity is the rate of change of angle over time.

It is changed in World:update by applying torques, off centre forces/impulses, and angular damping. It can be set directly with Body:setAngularVelocity.

If you need the rate of change of position over time, use Body:getLinearVelocity.

w = Body:getAngularVelocity()

wnumberThe angular velocity in radians/second.

Body:getContactList

Gets a list of all Contacts attached to the Body.

contacts = Body:getContactList()

contactstableA list with all contacts associated with the Body.

Body:getFixtureList

Gets a table with all fixtures.

fixtures = Body:getFixtureList()

fixturestableA sequence with all fixtures.

Body:getGravityScale

Gets the gravity scale factor.

scale = Body:getGravityScale()

scalenumberThe gravity scale factor.

Body:getInertia

Gets the rotational inertia of the body.

The rotational inertia is how hard is it to make the body spin.

inertia = Body:getInertia()

inertianumberThe rotational inertial of the body.

Body:getJointList

Gets a table containing the Joints attached to this Body.

joints = Body:getJointList()

jointstableA sequence with the Joints attached to the Body.

Body:getLinearDamping

Gets the linear damping of the Body.

The linear damping is the rate of decrease of the linear velocity over time. A moving body with no damping and no external forces will continue moving indefinitely, as is the case in space. A moving body with damping will gradually stop moving.

Damping is not the same as friction - they can be modelled together. However, only damping is provided by Box2D (and LÖVE).

damping = Body:getLinearDamping()

dampingnumberThe value of the linear damping.

Body:getLinearVelocity

Gets the linear velocity of the Body from its center of mass.

The linear velocity is the rate of change of position over time.

If you need the rate of change of angle over time, use Body:getAngularVelocity. If you need to get the linear velocity of a point different from the center of mass:

Body:getLinearVelocityFromLocalPoint allows you to specify the point in local coordinates.

Body:getLinearVelocityFromWorldPoint allows you to specify the point in world coordinates.

x, y = Body:getLinearVelocity()

xnumberThe x component of the velocity vector.
ynumberThe y component of the velocity vector.

Body:getLinearVelocityFromLocalPoint

Get the linear velocity of a point on the body.

The linear velocity for a point on the body is the velocity of the body center of mass plus the velocity at that point from the body spinning.

The point on the body must given in local coordinates. Use Body:getLinearVelocityFromWorldPoint to specify this with world coordinates.

vx, vy = Body:getLinearVelocityFromLocalPoint( x, y )

vxnumberThe x component of velocity at point (x,y).
vynumberThe y component of velocity at point (x,y).
xnumberThe x position to measure velocity.
ynumberThe y position to measure velocity.

Body:getLinearVelocityFromWorldPoint

Get the linear velocity of a point on the body.

The linear velocity for a point on the body is the velocity of the body center of mass plus the velocity at that point from the body spinning.

The point on the body must given in world coordinates. Use Body:getLinearVelocityFromLocalPoint to specify this with local coordinates.

vx, vy = Body:getLinearVelocityFromWorldPoint( x, y )

vxnumberThe x component of velocity at point (x,y).
vynumberThe y component of velocity at point (x,y).
xnumberThe x position to measure velocity.
ynumberThe y position to measure velocity.

Body:getLocalCenter

Get the center of mass position in local coordinates.

Use Body:getWorldCenter to get the center of mass in world coordinates.

x, y = Body:getLocalCenter()

xnumberThe x coordinate of the center of mass.
ynumberThe y coordinate of the center of mass.

Body:getLocalPoint

Transform a point from world coordinates to local coordinates.

localX, localY = Body:getLocalPoint( worldX, worldY )

localXnumberThe x position in local coordinates.
localYnumberThe y position in local coordinates.
worldXnumberThe x position in world coordinates.
worldYnumberThe y position in world coordinates.

Body:getLocalVector

Transform a vector from world coordinates to local coordinates.

localX, localY = Body:getLocalVector( worldX, worldY )

localXnumberThe vector x component in local coordinates.
localYnumberThe vector y component in local coordinates.
worldXnumberThe vector x component in world coordinates.
worldYnumberThe vector y component in world coordinates.

Body:getMass

Get the mass of the body.

mass = Body:getMass()

massnumberThe mass of the body (in kilograms).

Body:getMassData

Gets the mass, its center, and the rotational inertia.

x, y, mass, inertia = Body:getMassData()

xnumberThe x position of the center of mass.
ynumberThe y position of the center of mass.
massnumberThe mass of the body.
inertianumberThe rotational inertia.

Body:getPosition

Get the position of the body.

Note that this may not be the center of mass of the body.

x, y = Body:getPosition()

xnumberThe x position.
ynumberThe y position.

Body:getType

Gets the type of the body.

type = Body:getType()

typeBodyTypeThe body type.

Body:getUserData

Gets the Lua value associated with this Body.

value = Body:getUserData()

valueanyThe Lua value associated with the Body.

Body:getWorld

Gets the World the body lives in.

world = Body:getWorld()

worldWorldThe world the body lives in.

Body:getWorldCenter

Get the center of mass position in world coordinates.

Use Body:getLocalCenter to get the center of mass in local coordinates.

x, y = Body:getWorldCenter()

xnumberThe x coordinate of the center of mass.
ynumberThe y coordinate of the center of mass.

Body:getWorldPoint

Transform a point from local coordinates to world coordinates.

worldX, worldY = Body:getWorldPoint( localX, localY )

worldXnumberThe x position in world coordinates.
worldYnumberThe y position in world coordinates.
localXnumberThe x position in local coordinates.
localYnumberThe y position in local coordinates.

Body:getWorldPoints

Transforms multiple points from local coordinates to world coordinates.

x1, y1, x2, y2, ... = Body:getWorldPoints( x1, y1, x2, y2, ... )

x1numberThe transformed x position of the first point.
y1numberThe transformed y position of the first point.
x2numberThe transformed x position of the second point.
y2numberThe transformed y position of the second point.
...numberThe transformed x and y positions of additional points.
x1numberThe x position of the first point.
y1numberThe y position of the first point.
x2numberThe x position of the second point.
y2numberThe y position of the second point.
...numberMore x and y points.

Body:getWorldVector

Transform a vector from local coordinates to world coordinates.

worldX, worldY = Body:getWorldVector( localX, localY )

worldXnumberThe vector x component in world coordinates.
worldYnumberThe vector y component in world coordinates.
localXnumberThe vector x component in local coordinates.
localYnumberThe vector y component in local coordinates.

Body:getX

Get the x position of the body in world coordinates.

x = Body:getX()

xnumberThe x position in world coordinates.

Body:getY

Get the y position of the body in world coordinates.

y = Body:getY()

ynumberThe y position in world coordinates.

Body:isActive

Gets whether the body is actively used in the simulation.

status = Body:isActive()

statusbooleanTrue if the body is active or false if not.

Body:isAwake

Gets the sleep status of the body.

status = Body:isAwake()

statusbooleanTrue if the body is awake or false if not.

Body:isBullet

Get the bullet status of a body.

There are two methods to check for body collisions:

at their location when the world is updated (default)

using continuous collision detection (CCD)

The default method is efficient, but a body moving very quickly may sometimes jump over another body without producing a collision. A body that is set as a bullet will use CCD. This is less efficient, but is guaranteed not to jump when moving quickly.

Note that static bodies (with zero mass) always use CCD, so your walls will not let a fast moving body pass through even if it is not a bullet.

status = Body:isBullet()

statusbooleanThe bullet status of the body.

Body:isDestroyed

Gets whether the Body is destroyed. Destroyed bodies cannot be used.

destroyed = Body:isDestroyed()

destroyedbooleanWhether the Body is destroyed.

Body:isFixedRotation

Gets whether the body rotation is locked.

fixed = Body:isFixedRotation()

fixedbooleanTrue if the body's rotation is locked or false if not.

Body:isSleepingAllowed

Gets the sleeping behaviour of the body.

status = Body:isSleepingAllowed()

statusbooleanTrue if the body is allowed to sleep or false if not.

Body:resetMassData

Resets the mass of the body by recalculating it from the mass properties of the fixtures.

Body:resetMassData()

Body:setActive

Sets whether the body is active in the world.

An inactive body does not take part in the simulation. It will not move or cause any collisions.

Body:setActive( active )

activebooleanIf the body is active or not.

Body:setAngle

Set the angle of the body.

The angle is measured in radians. If you need to transform it from degrees, use math.rad.

A value of 0 radians will mean "looking to the right". Although radians increase counter-clockwise, the y-axis points down so it becomes clockwise from our point of view.

It is possible to cause a collision with another body by changing its angle.

Body:setAngle( angle )

anglenumberThe angle in radians.

Body:setAngularDamping

Sets the angular damping of a Body.

See Body:getAngularDamping for a definition of angular damping.

Angular damping can take any value from 0 to infinity. It is recommended to stay between 0 and 0.1, though. Other values will look unrealistic.

Body:setAngularDamping( damping )

dampingnumberThe new angular damping.

Body:setAngularVelocity

Sets the angular velocity of a Body.

The angular velocity is the rate of change of angle over time.

This function will not accumulate anything; any impulses previously applied since the last call to World:update will be lost.

Body:setAngularVelocity( w )

wnumberThe new angular velocity, in radians per second

Body:setAwake

Wakes the body up or puts it to sleep.

Body:setAwake( awake )

awakebooleanThe body sleep status.

Body:setBullet

Set the bullet status of a body.

There are two methods to check for body collisions:

at their location when the world is updated (default)

using continuous collision detection (CCD)

The default method is efficient, but a body moving very quickly may sometimes jump over another body without producing a collision. A body that is set as a bullet will use CCD. This is less efficient, but is guaranteed not to jump when moving quickly.

Note that static bodies (with zero mass) always use CCD, so your walls will not let a fast moving body pass through even if it is not a bullet.

Body:setBullet( status )

statusbooleanThe bullet status of the body.

Body:setFixedRotation

Set whether a body has fixed rotation.

Bodies with fixed rotation don't vary the speed at which they rotate.

Body:setFixedRotation( fixed )

fixedbooleanWhether the body should have fixed rotation.

Body:setGravityScale

Sets a new gravity scale factor for the body.

Body:setGravityScale( scale )

scalenumberThe new gravity scale factor.

Body:setInertia

Set the inertia of a body.

Body:setInertia( inertia )

inertianumberThe new moment of inertia, in kilograms per meter squared.

Body:setLinearDamping

Sets the linear damping of a Body

See Body:getLinearDamping for a definition of linear damping.

Linear damping can take any value from 0 to infinity. It is recommended to stay between 0 and 0.1, though. Other values will make the objects look "floaty".

Body:setLinearDamping( ld )

ldnumberThe new linear damping.

Body:setLinearVelocity

Sets a new linear velocity for the Body.

This function will not accumulate anything; any impulses previously applied since the last call to World:update will be lost.

Body:setLinearVelocity( x, y )

xnumberThe x component of the velocity vector.
ynumberThe y component of the velocity vector.

Body:setMass

Sets the mass in kilograms.

Body:setMass( mass )

massnumberThe mass, in kilograms.

Body:setMassData

Overrides the calculated mass data.

Body:setMassData( x, y, mass, inertia )

xnumberThe x component of the center of mass in local coordinates.
ynumberThe y component of the center of mass in local coordinates.
massnumberThe mass, in kilograms.
inertianumberThe rotational inertia, in kilograms per squared meter.

Body:setPosition

Set the position of the body.

Note that this may not be the center of mass of the body.

Body:setPosition( x, y )

xnumberThe x position.
ynumberThe y position.

Body:setSleepingAllowed

Sets the sleeping behaviour of the body.

Body:setSleepingAllowed( allowed )

allowedbooleanTrue if the body is allowed to sleep or false if not.

Body:setType

Sets a new body type.

Body:setType( type )

typeBodyTypeThe new type.

Body:setUserData

Associates a Lua value with the Body.

To delete the reference, explicitly pass nil.

Body:setUserData( value )

valueanyThe Lua value to associate with the Body.

Body:setX

Set the x position of the body.

Body:setX( x )

xnumberThe x position.

Body:setY

Set the y position of the body.

Body:setY( y )

ynumberThe y position.

ChainShape

A ChainShape consists of multiple line segments. It can be used to create the boundaries of your terrain. The shape does not have volume and can only collide with PolygonShape and CircleShape.

Unlike the PolygonShape, the ChainShape does not have a vertices limit or has to form a convex shape, but self intersections are not supported.

Constructors

Functions

Supertypes

ChainShape:getChildEdge

Gets a child of the shape as an EdgeShape.

EdgeShape = ChainShape:getChildEdge( index )

EdgeShapenumberThe child as an EdgeShape.
indexnumberThe index of the child.

ChainShape:getNextVertex

Gets the vertex that establishes a connection to the next shape.

Setting next and previous ChainShape vertices can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

ChainShape:getNextVertex( x, y )

x (nil)numberThe x-component of the vertex, or nil if ChainShape:setNextVertex hasn't been called.
y (nil)numberThe y-component of the vertex, or nil if ChainShape:setNextVertex hasn't been called.

ChainShape:getPoint

Gets a point of the shape.

x, y = ChainShape:getPoint( index )

xnumberThe x-coordinate of the point.
ynumberThe y-coordinate of the point.
indexnumberThe index of the point to return.

ChainShape:getPoints

Gets all points of the shape.

x1, y1, x2, y2, ... = ChainShape:getPoints()

x1numberThe x-coordinate of the first point.
y1numberThe y-coordinate of the first point.
x2numberThe x-coordinate of the second point.
y2numberThe y-coordinate of the second point.
...numberAdditional x and y values.

ChainShape:getPreviousVertex

Gets the vertex that establishes a connection to the previous shape.

Setting next and previous ChainShape vertices can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

x, y = ChainShape:getPreviousVertex()

x (nil)numberThe x-component of the vertex, or nil if ChainShape:setNextVertex hasn't been called.
y (nil)numberThe y-component of the vertex, or nil if ChainShape:setNextVertex hasn't been called.

ChainShape:getVertexCount

Gets the number of vertices the shape has.

count = ChainShape:getVertexCount()

countnumberThe number of vertices.

ChainShape:setNextVertex

Sets a vertex that establishes a connection to the next shape.

This can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

ChainShape:setNextVertex( x, y )

xnumberThe x component of the vertex.
ynumberThe y component of the vertex.

ChainShape:setPreviousVertex

Sets a vertex that establishes a connection to the previous shape.

This can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

ChainShape:setPreviousVertex( x, y )

xnumberThe x component of the vertex.
ynumberThe y component of the vertex.

CircleShape

Circle extends Shape and adds a radius and a local position.

Constructors

Functions

Supertypes

CircleShape:getPoint

Gets the center point of the circle shape.

x, y = CircleShape:getPoint()

xnumberThe x-component of the center point of the circle.
ynumberThe y-component of the center point of the circle.

CircleShape:getRadius

Gets the radius of the circle shape.

radius = CircleShape:getRadius()

radiusnumberThe radius of the circle.

CircleShape:setPoint

Sets the location of the center of the circle shape.

CircleShape:setPoint( x, y )

xnumberThe x-component of the new center point of the circle.
ynumberThe y-component of the new center point of the circle.

CircleShape:setRadius

Sets the radius of the circle.

CircleShape:setRadius( radius )

radiusnumberThe radius of the circle.

Contact

Contacts are objects created to manage collisions in worlds.

Functions

Supertypes

Contact:getFixtures

Gets the two Fixtures that hold the shapes that are in contact.

fixtureA, fixtureB = Contact:getFixtures()

fixtureAFixtureThe first Fixture.
fixtureBFixtureThe second Fixture.

Contact:getFriction

Get the friction between two shapes that are in contact.

friction = Contact:getFriction()

frictionnumberThe friction of the contact.

Contact:getNormal

Get the normal vector between two shapes that are in contact.

This function returns the coordinates of a unit vector that points from the first shape to the second.

nx, ny = Contact:getNormal()

nxnumberThe x component of the normal vector.
nynumberThe y component of the normal vector.

Contact:getPositions

Gets the contact points of the two colliding fixtures. There can be one or two points.

x1, y1, x2, y2 = Contact:getPositions()

x1numberThe x coordinate of the first contact point.
y1numberThe y coordinate of the first contact point.
x2numberThe x coordinate of the second contact point.
y2numberThe y coordinate of the second contact point.

Contact:getRestitution

Get the restitution between two shapes that are in contact.

restitution = Contact:getRestitution()

restitutionnumberThe restitution between the two shapes.

Contact:isEnabled

Gets whether the contact is enabled. The collision will be ignored if a contact gets disabled in the preSolve callback.

enabled = Contact:isEnabled()

enabledbooleanTrue if enabled, false otherwise.

Contact:isTouching

Gets whether the two colliding fixtures are touching each other.

touching = Contact:isTouching()

touchingbooleanTrue if they touch or false if not.

Contact:resetFriction

Resets the contact friction to the mixture value of both fixtures.

Contact:resetFriction()

Contact:resetRestitution

Resets the contact restitution to the mixture value of both fixtures.

Contact:resetRestitution()

Contact:setEnabled

Enables or disables the contact.

Contact:setEnabled( enabled )

enabledbooleanTrue to enable or false to disable.

Contact:setFriction

Sets the contact friction.

Contact:setFriction( friction )

frictionnumberThe contact friction.

Contact:setRestitution

Sets the contact restitution.

Contact:setRestitution( restitution )

restitutionnumberThe contact restitution.

EdgeShape

A EdgeShape is a line segment. They can be used to create the boundaries of your terrain. The shape does not have volume and can only collide with PolygonShape and CircleShape.

Constructors

Functions

Supertypes

EdgeShape:getPoints

Gets the local coordinates of the edge points.

x1, y1, x2, y2 = EdgeShape:getPoints()

x1numberThe x component of the first vertex.
y1numberThe y component of the first vertex.
x2numberThe x component of the second vertex.
y2numberThe y component of the second vertex.

EdgeShape:getNextVertex

Gets the vertex that establishes a connection to the next shape.

Setting next and previous EdgeShape vertices can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

x, y = EdgeShape:getNextVertex()

xnumberThe x-component of the vertex, or nil if EdgeShape:setNextVertex hasn't been called.
ynumberThe y-component of the vertex, or nil if EdgeShape:setNextVertex hasn't been called.

EdgeShape:getPreviousVertex

Gets the vertex that establishes a connection to the previous shape.

Setting next and previous EdgeShape vertices can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

x, y = EdgeShape:getPreviousVertex()

xnumberThe x-component of the vertex, or nil if EdgeShape:setPreviousVertex hasn't been called.
ynumberThe y-component of the vertex, or nil if EdgeShape:setPreviousVertex hasn't been called.

EdgeShape:setNextVertex

Sets a vertex that establishes a connection to the next shape.

This can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

EdgeShape:setNextVertex( x, y )

xnumberThe x-component of the vertex.
ynumberThe y-component of the vertex.

EdgeShape:setPreviousVertex

Sets a vertex that establishes a connection to the previous shape.

This can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

EdgeShape:setPreviousVertex( x, y )

xnumberThe x-component of the vertex.
ynumberThe y-component of the vertex.

DistanceJoint

Keeps two bodies at the same distance.

Constructors

Functions

Supertypes

DistanceJoint:getDampingRatio

Gets the damping ratio.

ratio = DistanceJoint:getDampingRatio()

rationumberThe damping ratio.

DistanceJoint:getFrequency

Gets the response speed.

Hz = DistanceJoint:getFrequency()

HznumberThe response speed.

DistanceJoint:getLength

Gets the equilibrium distance between the two Bodies.

l = DistanceJoint:getLength()

lnumberThe length between the two Bodies.

DistanceJoint:setDampingRatio

Sets the damping ratio.

DistanceJoint:setDampingRatio( ratio )

rationumberThe damping ratio.

DistanceJoint:setFrequency

Sets the response speed.

DistanceJoint:setFrequency( Hz )

HznumberThe response speed.

DistanceJoint:setLength

Sets the equilibrium distance between the two Bodies.

DistanceJoint:setLength( l )

lnumberThe length between the two Bodies.

Fixture

Fixtures attach shapes to bodies.

Constructors

Functions

Supertypes

Fixture:destroy

Destroys the fixture

Fixture:destroy()

Fixture:getBody

Gets the body to which the fixture is attached.

body = Fixture:getBody()

bodyBodyThe parent body.

Fixture:getBoundingBox

Gets the points of the fixture bounding box. In case the fixture has multiple children a 1-based index can be specified. For example, a fixture will have multiple children with a chain shape.

topLeftX, topLeftY, bottomRightX, bottomRightY = Fixture:getBoundingBox( index )

topLeftXnumberThe x position of the top-left point.
topLeftYnumberThe y position of the top-left point.
bottomRightXnumberThe x position of the bottom-right point.
bottomRightYnumberThe y position of the bottom-right point.
index (1)numberA bounding box of the fixture.

Fixture:getCategory

Gets the categories the fixture belongs to.

category1, category2, ... = Fixture:getCategory()

category1numberThe first category.
category2numberThe second category.
...numberAdditional categories.

Fixture:getDensity

Gets the density of the fixture.

density = Fixture:getDensity()

densitynumberThe fixture density in kilograms per square meter.

Fixture:getFilterData

Gets the filter data of the fixture. Categories and masks are encoded as the bits of a 16-bit integer.

categories, mask, group = Fixture:getFilterData()

categoriesnumberThe categories as an integer from 0 to 65535.
masknumberThe mask as an integer from 0 to 65535.
groupnumberThe group as an integer from -32768 to 32767.

Fixture:getFriction

Gets the friction of the fixture.

friction = Fixture:getFriction()

frictionnumberThe fixture friction.

Fixture:getGroupIndex

Gets the group the fixture belongs to. Fixtures with the same group will always collide if the group is positive or never collide if it's negative. The group zero means no group.

The groups range from -32768 to 32767.

group = Fixture:getGroupIndex()

groupnumberThe group of the fixture.

Fixture:getMask

Gets the category mask of the fixture.

mask1, mask2, ... = Fixture:getMask()

mask1numberThe first category selected by the mask.
mask2numberThe second category selected by the mask.
...numberAdditional categories selected by the mask.

Fixture:getMassData

Gets the mass, its center and the rotational inertia.

x, y, mass, inertia = Fixture:getMassData()

xnumberThe x position of the center of mass.
ynumberThe y position of the center of mass.
massnumberThe mass of the fixture.
inertianumberThe rotational inertia.

Fixture:getRestitution

Gets the restitution of the fixture.

restitution = Fixture:getRestitution()

restitutionnumberThe fixture restitution.

Fixture:getShape

Gets the shape of the fixture. This shape is a reference to the actual data used in the simulation. It's possible to change its values between timesteps.

Do not call any functions on this shape after the parent fixture has been destroyed. This shape will point to an invalid memory address and likely cause crashes if you interact further with it.

shape = Fixture:getShape()

shapeShapeThe fixture's shape.

Fixture:getUserData

Gets the Lua value associated with this fixture.

Use this function in one thread only.

value = Fixture:getUserData()

valueanyThe Lua value associated with the fixture.

Fixture:isDestroyed

Gets whether the Fixture is destroyed. Destroyed fixtures cannot be used.

destroyed = Fixture:isDestroyed()

destroyedbooleanWhether the Fixture is destroyed.

Fixture:isSensor

Gets whether the fixture is a sensor.

sensor = Fixture:isSensor()

sensorbooleanIf the fixture is a sensor.

Fixture:rayCast

Casts a ray against the shape of the fixture and returns the surface normal vector and the line position where the ray hit. If the ray missed the shape, nil will be returned.

The ray starts on the first point of the input line and goes towards the second point of the line. The fourth argument is the maximum distance the ray is going to travel as a scale factor of the input line length.

The childIndex parameter is used to specify which child of a parent shape, such as a ChainShape, will be ray casted. For ChainShapes, the index of 1 is the first edge on the chain. Ray casting a parent shape will only test the child specified so if you want to test every shape of the parent, you must loop through all of its children.

The world position of the impact can be calculated by multiplying the line vector with the third return value and adding it to the line starting point.

hitx, hity = x1 + (x2 - x1) * fraction, y1 + (y2 - y1) * fraction

x, y, fraction = Fixture:rayCast( x1, y1, x2, y1, maxFraction, childIndex )

xnumberThe x position where the ray intersects with the shape.
ynumberThe y position where the ray intersects with the shape.
fractionnumberThe position on the input vector where the intersection happened as a number from 0 to 1.
x1numberThe x position of the ray starting point.
y1numberThe y position of the ray starting point.
x2numberThe x position of the ray end point.
y1numberThe y position of the ray end point.
maxFractionnumberThe maximum distance the ray is going to travel as a number from 0 to 1.
childIndex (1)numberThe index of the child the ray gets cast against.

Fixture:setCategory

Sets the categories the fixture belongs to. There can be up to 16 categories represented as a number from 1 to 16.

Fixture:setCategory( category1, category2, ... )

category1numberThe first category.
category2numberThe second category.
...numberAdditional categories.

Fixture:setDensity

Sets the density of the fixture. Call Body:resetMassData if this needs to take effect immediately.

Fixture:setDensity( density )

densitynumberThe fixture density in kilograms per square meter.

Fixture:setFilterData

Sets the filter data of the fixture.

Groups, categories, and mask can be used to define the collision behaviour of the fixture.

If two fixtures are in the same group they either always collide if the group is positive, or never collide if it's negative. If the group is zero or they do not match, then the contact filter checks if the fixtures select a category of the other fixture with their masks. The fixtures do not collide if that's not the case. If they do have each other's categories selected, the return value of the custom contact filter will be used. They always collide if none was set.

There can be up to 16 categories. Categories and masks are encoded as the bits of a 16-bit integer.

Fixture:setFilterData( categories, mask, group )

categoriesnumberThe categories as an integer from 0 to 65535.
masknumberThe mask as an integer from 0 to 65535.
groupnumberThe group as an integer from -32768 to 32767.

Fixture:setFriction

Sets the friction of the fixture.

Fixture:setFriction( friction )

frictionnumberThe fixture friction.

Fixture:setGroupIndex

Sets the group the fixture belongs to. Fixtures with the same group will always collide if the group is positive or never collide if it's negative. The group zero means no group.

The groups range from -32768 to 32767.

Fixture:setGroupIndex( group )

groupnumberThe group as an integer from -32768 to 32767.

Fixture:setMask

Sets the category mask of the fixture. There can be up to 16 categories represented as a number from 1 to 16.

This fixture will collide with the fixtures that are in the selected categories if the other fixture also has a category of this fixture selected.

Fixture:setMask( mask1, mask2, ... )

mask1numberThe first category.
mask2numberThe second category.
...numberAdditional categories.

Fixture:setRestitution

Sets the restitution of the fixture.

Fixture:setRestitution( restitution )

restitutionnumberThe fixture restitution.

Fixture:setSensor

Sets whether the fixture should act as a sensor.

Sensor do not produce collisions responses, but the begin and end callbacks will still be called for this fixture.

Fixture:setSensor( sensor )

sensorbooleanThe sensor status.

Fixture:setUserData

Associates a Lua value with the fixture.

Use this function in one thread only.

Fixture:setUserData( value )

valueanyThe Lua value associated with the fixture.

Fixture:testPoint

Checks if a point is inside the shape of the fixture.

isInside = Fixture:testPoint( x, y )

isInsidebooleanTrue if the point is inside or false if it is outside.
xnumberThe x position of the point.
ynumberThe y position of the point.

FrictionJoint

A FrictionJoint applies friction to a body.

Constructors

Functions

Supertypes

FrictionJoint:getMaxForce

Gets the maximum friction force in Newtons.

force = FrictionJoint:getMaxForce()

forcenumberMaximum force in Newtons.

FrictionJoint:getMaxTorque

Gets the maximum friction torque in Newton-meters.

torque = FrictionJoint:getMaxTorque()

torquenumberMaximum torque in Newton-meters.

FrictionJoint:setMaxForce

Sets the maximum friction force in Newtons.

FrictionJoint:setMaxForce( maxForce )

maxForcenumberMax force in Newtons.

FrictionJoint:setMaxTorque

Sets the maximum friction torque in Newton-meters.

FrictionJoint:setMaxTorque( torque )

torquenumberMaximum torque in Newton-meters.

GearJoint

Keeps bodies together in such a way that they act like gears.

Constructors

Functions

Supertypes

GearJoint:getJoints

Get the Joints connected by this GearJoint.

joint1, joint2 = GearJoint:getJoints()

joint1JointThe first connected Joint.
joint2JointThe second connected Joint.

GearJoint:getRatio

Get the ratio of a gear joint.

ratio = GearJoint:getRatio()

rationumberThe ratio of the joint.

GearJoint:setRatio

Set the ratio of a gear joint.

GearJoint:setRatio( ratio )

rationumberThe new ratio of the joint.

Joint

Attach multiple bodies together to interact in unique ways.

Functions

Supertypes

Subtypes

Joint:destroy

Explicitly destroys the Joint. When you don't have time to wait for garbage collection, this function may be used to free the object immediately, but note that an error will occur if you attempt to use the object after calling this function.

Joint:destroy()

Joint:getAnchors

Get the anchor points of the joint.

x1, y1, x2, y2 = Joint:getAnchors()

x1numberThe x component of the anchor on Body 1.
y1numberThe y component of the anchor on Body 1.
x2numberThe x component of the anchor on Body 2.
y2numberThe y component of the anchor on Body 2.

Joint:getBodies

Gets the bodies that the Joint is attached to.

bodyA, bodyB = Joint:getBodies()

bodyABodyThe first Body.
bodyBBodyThe second Body.

Joint:getCollideConnected

Gets whether the connected Bodies collide.

c = Joint:getCollideConnected()

cbooleanTrue if they collide, false otherwise.

Joint:getReactionForce

Gets the reaction force on Body 2 at the joint anchor.

x, y = Joint:getReactionForce()

xnumberThe x component of the force.
ynumberThe y component of the force.

Joint:getReactionTorque

Gets the reaction torque on the second body.

torque = Joint:getReactionTorque( invdt )

torquenumberThe reaction torque on the second body.
invdtnumberHow long the force applies. Usually the inverse time step or 1/dt.

Joint:getType

Gets a string representing the type.

type = Joint:getType()

typeJointTypeA string with the name of the Joint type.

Joint:getUserData

Gets the Lua value associated with this Joint.

value = Joint:getUserData()

valueanyThe Lua value associated with the Joint.

Joint:isDestroyed

Gets whether the Joint is destroyed. Destroyed joints cannot be used.

destroyed = Joint:isDestroyed()

destroyedbooleanWhether the Joint is destroyed.

Joint:setUserData

Associates a Lua value with the Joint.

To delete the reference, explicitly pass nil.

Joint:setUserData( value )

valueanyThe Lua value to associate with the Joint.

MotorJoint

Controls the relative motion between two Bodies. Position and rotation offsets can be specified, as well as the maximum motor force and torque that will be applied to reach the target offsets.

Constructors

Functions

Supertypes

MotorJoint:getAngularOffset

Gets the target angular offset between the two Bodies the Joint is attached to.

angularoffset = MotorJoint:getAngularOffset()

angularoffsetnumberThe target angular offset in radians: the second body's angle minus the first body's angle.

MotorJoint:getLinearOffset

Gets the target linear offset between the two Bodies the Joint is attached to.

x, y = MotorJoint:getLinearOffset()

xnumberThe x component of the target linear offset, relative to the first Body.
ynumberThe y component of the target linear offset, relative to the first Body.

MotorJoint:setAngularOffset

Sets the target angluar offset between the two Bodies the Joint is attached to.

MotorJoint:setAngularOffset( angularoffset )

angularoffsetnumberThe target angular offset in radians: the second body's angle minus the first body's angle.

MotorJoint:setLinearOffset

Sets the target linear offset between the two Bodies the Joint is attached to.

MotorJoint:setLinearOffset( x, y )

xnumberThe x component of the target linear offset, relative to the first Body.
ynumberThe y component of the target linear offset, relative to the first Body.

MouseJoint

For controlling objects with the mouse.

Constructors

Functions

Supertypes

MouseJoint:getDampingRatio

Gets the damping ratio.

ratio = MouseJoint:getDampingRatio()

rationumberThe new damping ratio.

MouseJoint:getFrequency

Gets the frequency.

freq = MouseJoint:getFrequency()

freqnumberThe frequency in hertz.

MouseJoint:getMaxForce

Gets the highest allowed force.

f = MouseJoint:getMaxForce()

fnumberThe max allowed force.

MouseJoint:getTarget

Gets the target point.

x, y = MouseJoint:getTarget()

xnumberThe x component of the target.
ynumberThe x component of the target.

MouseJoint:setDampingRatio

Sets a new damping ratio.

MouseJoint:setDampingRatio( ratio )

rationumberThe new damping ratio.

MouseJoint:setFrequency

Sets a new frequency.

MouseJoint:setFrequency( freq )

freqnumberThe new frequency in hertz.

MouseJoint:setMaxForce

Sets the highest allowed force.

MouseJoint:setMaxForce( f )

fnumberThe max allowed force.

MouseJoint:setTarget

Sets the target point.

MouseJoint:setTarget( x, y )

xnumberThe x component of the target.
ynumberThe y component of the target.

PolygonShape

Polygon is a convex polygon with up to 8 sides.

Constructors

Functions

Supertypes

PolygonShape:getPoints

Get the local coordinates of the polygon's vertices.

This function has a variable number of return values. It can be used in a nested fashion with love.graphics.polygon.

This function may have up to 16 return values, since it returns two values for each vertex in the polygon. In other words, it can return the coordinates of up to 8 points.

x1, y1, x2, y2, ... = PolygonShape:getPoints()

x1numberThe x component of the first vertex.
y1numberThe y component of the first vertex.
x2numberThe x component of the second vertex.
y2numberThe y component of the second vertex.
...numberAdditional x and y values.

PrismaticJoint

Restricts relative motion between Bodies to one shared axis.

Constructors

Functions

Supertypes

PrismaticJoint:getAxis

Gets the world-space axis vector of the Prismatic Joint.

x, y = PrismaticJoint:getAxis()

xnumberThe x-axis coordinate of the world-space axis vector.
ynumberThe y-axis coordinate of the world-space axis vector.

PrismaticJoint:getJointSpeed

Get the current joint angle speed.

s = PrismaticJoint:getJointSpeed()

snumberJoint angle speed in meters/second.

PrismaticJoint:getJointTranslation

Get the current joint translation.

t = PrismaticJoint:getJointTranslation()

tnumberJoint translation, usually in meters.

PrismaticJoint:getLimits

Gets the joint limits.

lower, upper = PrismaticJoint:getLimits()

lowernumberThe lower limit, usually in meters.
uppernumberThe upper limit, usually in meters.

PrismaticJoint:getLowerLimit

Gets the lower limit.

lower = PrismaticJoint:getLowerLimit()

lowernumberThe lower limit, usually in meters.

PrismaticJoint:getMaxMotorForce

Gets the maximum motor force.

f = PrismaticJoint:getMaxMotorForce()

fnumberThe maximum motor force, usually in N.

PrismaticJoint:getMotorForce

Get the current motor force.

f = PrismaticJoint:getMotorForce()

fnumberThe current motor force, usually in N.

PrismaticJoint:getMotorSpeed

Gets the motor speed.

s = PrismaticJoint:getMotorSpeed()

snumberThe motor speed, usually in meters per second.

PrismaticJoint:getUpperLimit

Gets the upper limit.

upper = PrismaticJoint:getUpperLimit()

uppernumberThe upper limit, usually in meters.

PrismaticJoint:hasLimitsEnabled

Checks whether the limits are enabled.

enabled = PrismaticJoint:hasLimitsEnabled()

enabledbooleanTrue if enabled, false otherwise.

PrismaticJoint:isMotorEnabled

Checks whether the motor is enabled.

enabled = PrismaticJoint:isMotorEnabled()

enabledbooleanTrue if enabled, false if disabled.

PrismaticJoint:setLimits

Sets the limits.

PrismaticJoint:setLimits( lower, upper )

lowernumberThe lower limit, usually in meters.
uppernumberThe upper limit, usually in meters.

PrismaticJoint:setLimitsEnabled

Enables or disables the limits of the joint.

PrismaticJoint:setLimitsEnabled( enable )

enablebooleanTrue to enable, false to disable.

PrismaticJoint:setLowerLimit

Sets the lower limit.

PrismaticJoint:setLowerLimit( lower )

lowernumberThe lower limit, usually in meters.

PrismaticJoint:setMaxMotorForce

Set the maximum motor force.

PrismaticJoint:setMaxMotorForce( f )

fnumberThe maximum motor force, usually in N.

PrismaticJoint:setMotorEnabled

Starts or stops the joint motor.

PrismaticJoint:setMotorEnabled( enable )

enablebooleanTrue to enable, false to disable.

PrismaticJoint:setMotorSpeed

Sets the motor speed.

PrismaticJoint:setMotorSpeed( s )

snumberThe motor speed, usually in meters per second.

PrismaticJoint:setUpperLimit

Sets the upper limit.

PrismaticJoint:setUpperLimit( upper )

uppernumberThe upper limit, usually in meters.

PulleyJoint

Allows you to simulate bodies connected through pulleys.

Constructors

Functions

Supertypes

PulleyJoint:getConstant

Get the total length of the rope.

length = PulleyJoint:getConstant()

lengthnumberThe length of the rope in the joint.

PulleyJoint:getGroundAnchors

Get the ground anchor positions in world coordinates.

a1x, a1y, a2x, a2y = PulleyJoint:getGroundAnchors()

a1xnumberThe x coordinate of the first anchor.
a1ynumberThe y coordinate of the first anchor.
a2xnumberThe x coordinate of the second anchor.
a2ynumberThe y coordinate of the second anchor.

PulleyJoint:getLengthA

Get the current length of the rope segment attached to the first body.

length = PulleyJoint:getLengthA()

lengthnumberThe length of the rope segment.

PulleyJoint:getLengthB

Get the current length of the rope segment attached to the second body.

length = PulleyJoint:getLengthB()

lengthnumberThe length of the rope segment.

PulleyJoint:getMaxLengths

Get the maximum lengths of the rope segments.

len1, len2 = PulleyJoint:getMaxLengths()

len1numberThe maximum length of the first rope segment.
len2numberThe maximum length of the second rope segment.

PulleyJoint:getRatio

Get the pulley ratio.

ratio = PulleyJoint:getRatio()

rationumberThe pulley ratio of the joint.

PulleyJoint:setConstant

Set the total length of the rope.

Setting a new length for the rope updates the maximum length values of the joint.

PulleyJoint:setConstant( length )

lengthnumberThe new length of the rope in the joint.

PulleyJoint:setMaxLengths

Set the maximum lengths of the rope segments.

The physics module also imposes maximum values for the rope segments. If the parameters exceed these values, the maximum values are set instead of the requested values.

PulleyJoint:setMaxLengths( max1, max2 )

max1numberThe new maximum length of the first segment.
max2numberThe new maximum length of the second segment.

PulleyJoint:setRatio

Set the pulley ratio.

PulleyJoint:setRatio( ratio )

rationumberThe new pulley ratio of the joint.

RevoluteJoint

Allow two Bodies to revolve around a shared point.

Constructors

Functions

Supertypes

RevoluteJoint:setLimitsEnabled

Enables or disables the joint limits.

RevoluteJoint:setLimitsEnabled( enable )

enablebooleanTrue to enable, false to disable.

RevoluteJoint:setMotorEnabled

Starts or stops the joint motor.

RevoluteJoint:setMotorEnabled( enable )

enablebooleanTrue to enable, false to disable.

RevoluteJoint:getJointAngle

Get the current joint angle.

angle = RevoluteJoint:getJointAngle()

anglenumberThe joint angle in radians.

RevoluteJoint:getJointSpeed

Get the current joint angle speed.

s = RevoluteJoint:getJointSpeed()

snumberJoint angle speed in radians/second.

RevoluteJoint:getLimits

Gets the joint limits.

lower, upper = RevoluteJoint:getLimits()

lowernumberThe lower limit, in radians.
uppernumberThe upper limit, in radians.

RevoluteJoint:getLowerLimit

Gets the lower limit.

lower = RevoluteJoint:getLowerLimit()

lowernumberThe lower limit, in radians.

RevoluteJoint:getMaxMotorTorque

Gets the maximum motor force.

f = RevoluteJoint:getMaxMotorTorque()

fnumberThe maximum motor force, in Nm.

RevoluteJoint:getMotorSpeed

Gets the motor speed.

s = RevoluteJoint:getMotorSpeed()

snumberThe motor speed, radians per second.

RevoluteJoint:getMotorTorque

Get the current motor force.

f = RevoluteJoint:getMotorTorque()

fnumberThe current motor force, in Nm.

RevoluteJoint:getUpperLimit

Gets the upper limit.

upper = RevoluteJoint:getUpperLimit()

uppernumberThe upper limit, in radians.

RevoluteJoint:hasLimitsEnabled

Checks whether limits are enabled.

enabled = RevoluteJoint:hasLimitsEnabled()

enabledbooleanTrue if enabled, false otherwise.

RevoluteJoint:isMotorEnabled

Checks whether the motor is enabled.

enabled = RevoluteJoint:isMotorEnabled()

enabledbooleanTrue if enabled, false if disabled.

RevoluteJoint:setLimits

Sets the limits.

RevoluteJoint:setLimits( lower, upper )

lowernumberThe lower limit, in radians.
uppernumberThe upper limit, in radians.

RevoluteJoint:setLowerLimit

Sets the lower limit.

RevoluteJoint:setLowerLimit( lower )

lowernumberThe lower limit, in radians.

RevoluteJoint:setMaxMotorTorque

Set the maximum motor force.

RevoluteJoint:setMaxMotorTorque( f )

fnumberThe maximum motor force, in Nm.

RevoluteJoint:setMotorSpeed

Sets the motor speed.

RevoluteJoint:setMotorSpeed( s )

snumberThe motor speed, radians per second.

RevoluteJoint:setUpperLimit

Sets the upper limit.

RevoluteJoint:setUpperLimit( upper )

uppernumberThe upper limit, in radians.

RopeJoint

The RopeJoint enforces a maximum distance between two points on two bodies. It has no other effect.

Constructors

Functions

Supertypes

RopeJoint:getMaxLength

Gets the maximum length of a RopeJoint.

maxLength = RopeJoint:getMaxLength()

maxLengthnumberThe maximum length of the RopeJoint.

Shape

Shapes are solid 2d geometrical objects used in love.physics.

Shapes are attached to a Body via a Fixture. The Shape object is copied when this happens. Shape position is relative to Body position.

Constructors

Functions

Supertypes

Subtypes

Shape:computeAABB

Gets the points of the bounding box for the transformed shape.

topLeftX, topLeftY, bottomRightX, bottomRightY = Shape:computeAABB( tx, ty, tr, childIndex )

topLeftXnumberThe x position of the top-left point.
topLeftYnumberThe y position of the top-left point.
bottomRightXnumberThe x position of the bottom-right point.
bottomRightYnumberThe y position of the bottom-right point.
txnumberThe translation of the shape on the x-axis.
tynumberThe translation of the shape on the y-axis.
trnumberThe shape rotation.
childIndex (1)numberThe index of the child to compute the bounding box of.

Shape:computeMass

Computes the mass properties for the shape with the specified density.

x, y, mass, inertia = Shape:computeMass( density )

xnumberThe x postition of the center of mass.
ynumberThe y postition of the center of mass.
massnumberThe mass of the shape.
inertianumberThe rotational inertia.
densitynumberThe shape density.

Shape:getChildCount

Gets the number of children the shape has.

count = Shape:getChildCount()

countnumberThe number of children.

Shape:getRadius

Gets the radius of the shape.

radius = Shape:getRadius()

radiusnumberThe radius of the shape.

Shape:getType

Gets a string representing the Shape. This function can be useful for conditional debug drawing.

type = Shape:getType()

typeShapeTypeThe type of the Shape.

Shape:rayCast

Casts a ray against the shape and returns the surface normal vector and the line position where the ray hit. If the ray missed the shape, nil will be returned. The Shape can be transformed to get it into the desired position.

The ray starts on the first point of the input line and goes towards the second point of the line. The fourth argument is the maximum distance the ray is going to travel as a scale factor of the input line length.

The childIndex parameter is used to specify which child of a parent shape, such as a ChainShape, will be ray casted. For ChainShapes, the index of 1 is the first edge on the chain. Ray casting a parent shape will only test the child specified so if you want to test every shape of the parent, you must loop through all of its children.

The world position of the impact can be calculated by multiplying the line vector with the third return value and adding it to the line starting point.

hitx, hity = x1 + (x2 - x1) * fraction, y1 + (y2 - y1) * fraction

xn, yn, fraction = Shape:rayCast( x1, y1, x2, y2, maxFraction, tx, ty, tr, childIndex )

xnnumberThe x component of the normal vector of the edge where the ray hit the shape.
ynnumberThe y component of the normal vector of the edge where the ray hit the shape.
fractionnumberThe position on the input line where the intersection happened as a factor of the line length.
x1numberThe x position of the input line starting point.
y1numberThe y position of the input line starting point.
x2numberThe x position of the input line end point.
y2numberThe y position of the input line end point.
maxFractionnumberRay length parameter.
txnumberThe translation of the shape on the x-axis.
tynumberThe translation of the shape on the y-axis.
trnumberThe shape rotation.
childIndex (1)numberThe index of the child the ray gets cast against.

Shape:testPoint

Checks whether a point lies inside the shape. This is particularly useful for mouse interaction with the shapes. By looping through all shapes and testing the mouse position with this function, we can find which shapes the mouse touches.

hit = Shape:testPoint( x, y )

hitbooleanTrue if inside, false if outside
xnumberThe x component of the point.
ynumberThe y component of the point.

WeldJoint

A WeldJoint essentially glues two bodies together.

Constructors

Functions

Supertypes

WeldJoint:getDampingRatio

Gets the damping ratio of the joint.

ratio = WeldJoint:getDampingRatio()

rationumberThe damping ratio.

WeldJoint:getFrequency

Gets the frequency.

freq = WeldJoint:getFrequency()

freqnumberThe frequency in hertz.

WeldJoint:setDampingRatio

The new damping ratio.

WeldJoint:setDampingRatio( ratio )

rationumberThe new damping ratio.

WeldJoint:setFrequency

Sets a new frequency.

WeldJoint:setFrequency( freq )

freqnumberThe new frequency in hertz.

WheelJoint

Restricts a point on the second body to a line on the first body.

Constructors

Functions

Supertypes

WheelJoint:getAxis

Gets the world-space axis vector of the Wheel Joint.

x, y = WheelJoint:getAxis()

xnumberThe x-axis coordinate of the world-space axis vector.
ynumberThe y-axis coordinate of the world-space axis vector.

WheelJoint:getJointSpeed

Gets the current joint translation speed.

speed = WheelJoint:getJointSpeed()

speednumberThe translation speed of the joint in meters per second.

WheelJoint:getJointTranslation

Gets the current joint translation.

position = WheelJoint:getJointTranslation()

positionnumberThe translation of the joint in meters.

WheelJoint:getMaxMotorTorque

Gets the maximum motor torque.

maxTorque = WheelJoint:getMaxMotorTorque()

maxTorquenumberThe maximum torque of the joint motor in newton meters.

WheelJoint:getMotorSpeed

Gets the speed of the motor.

speed = WheelJoint:getMotorSpeed()

speednumberThe speed of the joint motor in radians per second.

WheelJoint:getMotorTorque

Gets the current torque on the motor.

torque = WheelJoint:getMotorTorque( invdt )

torquenumberThe torque on the motor in newton meters.
invdtnumberHow long the force applies. Usually the inverse time step or 1/dt.

WheelJoint:getSpringDampingRatio

Gets the damping ratio.

ratio = WheelJoint:getSpringDampingRatio()

rationumberThe damping ratio.

WheelJoint:getSpringFrequency

Gets the spring frequency.

freq = WheelJoint:getSpringFrequency()

freqnumberThe frequency in hertz.

WheelJoint:setMaxMotorTorque

Sets a new maximum motor torque.

WheelJoint:setMaxMotorTorque( maxTorque )

maxTorquenumberThe new maximum torque for the joint motor in newton meters.

WheelJoint:setMotorEnabled

Starts and stops the joint motor.

WheelJoint:setMotorEnabled( enable )

enablebooleanTrue turns the motor on and false turns it off.

WheelJoint:setMotorSpeed

Sets a new speed for the motor.

WheelJoint:setMotorSpeed( speed )

speednumberThe new speed for the joint motor in radians per second.

WheelJoint:setSpringDampingRatio

Sets a new damping ratio.

WheelJoint:setSpringDampingRatio( ratio )

rationumberThe new damping ratio.

WheelJoint:setSpringFrequency

Sets a new spring frequency.

WheelJoint:setSpringFrequency( freq )

freqnumberThe new frequency in hertz.

World

A world is an object that contains all bodies and joints.

Constructors

Functions

Supertypes

World:destroy

Destroys the world, taking all bodies, joints, fixtures and their shapes with it.

An error will occur if you attempt to use any of the destroyed objects after calling this function.

World:destroy()

World:getBodyCount

Get the number of bodies in the world.

n = World:getBodyCount()

nnumberThe number of bodies in the world.

World:getBodyList

Gets a table with all bodies.

bodies = World:getBodyList()

bodiestableA sequence with all bodies.

World:getCallbacks

Gets functions for the callbacks during the world update.

beginContact, endContact, preSolve, postSolve = World:getCallbacks()

beginContactfunctionGets called when two fixtures begin to overlap.
endContactfunctionGets called when two fixtures cease to overlap.
preSolvefunctionGets called before a collision gets resolved.
postSolvefunctionGets called after the collision has been resolved.

World:getContactCount

Gets the number of contacts in the world.

n = World:getContactCount()

nnumberThe number of contacts in the world.

World:getContactFilter

Gets the function for collision filtering.

contactFilter = World:getContactFilter()

contactFilterfunctionThe function that handles the contact filtering.

World:getContactList

Gets a table with all contacts.

contacts = World:getContactList()

contactstableA sequence with all contacts.

World:getGravity

Get the gravity of the world.

x, y = World:getGravity()

xnumberThe x component of gravity.
ynumberThe y component of gravity.

World:getJointCount

Get the number of joints in the world.

n = World:getJointCount()

nnumberThe number of joints in the world.

World:getJointList

Gets a table with all joints.

joints = World:getJointList()

jointstableA sequence with all joints.

World:isDestroyed

Gets whether the World is destroyed. Destroyed worlds cannot be used.

destroyed = World:isDestroyed()

destroyedbooleanWhether the World is destroyed.

World:isLocked

Gets if the world is updating its state.

This will return true inside the callbacks from World:setCallbacks.

locked = World:isLocked()

lockedbooleanWill be true if the world is in the process of updating its state.

World:isSleepingAllowed

Gets the sleep behaviour of the world.

allowSleep = World:isSleepingAllowed()

allowSleepbooleanTrue if the bodies are allowed to sleep or false if not.

World:queryBoundingBox

Calls a function for each fixture inside the specified area.

World:queryBoundingBox( topLeftX, topLeftY, bottomRightX, bottomRightY, callback )

topLeftXnumberThe x position of the top-left point.
topLeftYnumberThe y position of the top-left point.
bottomRightXnumberThe x position of the bottom-right point.
bottomRightYnumberThe y position of the bottom-right point.
callbackfunctionThis function gets passed one argument, the fixture, and should return a boolean. The search will continue if it is true or stop if it is false.

World:rayCast

Casts a ray and calls a function for each fixtures it intersects.

World:rayCast( x1, y1, x2, y2, callback )

x1numberThe x position of the starting point of the ray.
y1numberThe y position of the starting point of the ray.
x2numberThe x position of the end point of the ray.
y2numberThe y position of the end point of the ray.
callbackfunctionThis function gets six arguments and should return a number.

World:setCallbacks

Sets functions for the collision callbacks during the world update.

Four Lua functions can be given as arguments. The value nil removes a function.

When called, each function will be passed three arguments. The first two arguments are the colliding fixtures and the third argument is the Contact between them. The PostSolve callback additionally gets the normal and tangent impulse for each contact point.

World:setCallbacks( beginContact, endContact, preSolve, postSolve )

beginContactfunctionGets called when two fixtures begin to overlap.
endContactfunctionGets called when two fixtures cease to overlap.
preSolvefunctionGets called before a collision gets resolved.
postSolvefunctionGets called after the collision has been resolved.

World:setContactFilter

Sets a function for collision filtering.

If the group and category filtering doesn't generate a collision decision, this function gets called with the two fixtures as arguments. The function should return a boolean value where true means the fixtures will collide and false means they will pass through each other.

World:setContactFilter( filter )

filterfunctionThe function handling the contact filtering.

World:setGravity

Set the gravity of the world.

World:setGravity( x, y )

xnumberThe x component of gravity.
ynumberThe y component of gravity.

World:setSleepingAllowed

Set the sleep behaviour of the world.

A sleeping body is much more efficient to simulate than when awake.

If sleeping is allowed, any body that has come to rest will sleep.

World:setSleepingAllowed( allowSleep )

allowSleepbooleanTrue if the bodies are allowed to sleep or false if not.

World:translateOrigin

Translates the World's origin. Useful in large worlds where floating point precision issues become noticeable at far distances from the origin.

World:translateOrigin( x, y )

xnumberThe x component of the new origin with respect to the old origin.
ynumberThe y component of the new origin with respect to the old origin.

World:update

Update the state of the world.

World:update( dt )

dtnumberThe time (in seconds) to advance the physics simulation.

love.sound

Types

love.sound.newSoundData

Creates new SoundData from a file. It's also possible to create SoundData with a custom sample rate, channel and bit depth.

The sound data will be decoded to the memory in a raw format. It is recommended to create only short sounds like effects, as a 3 minute song uses 30 MB of memory this way.

soundData = love.sound.newSoundData( file )

soundDataSoundDataA new SoundData object.
filestring / File / FileDataThe file path/File/FileData of the file to load.

soundData = love.sound.newSoundData( samples, samplingRate, bitRate, channelCount )

soundDataSoundDataA new SoundData object.
samplesnumberTotal number of samples.
samplingRate (44100)numberNumber of samples per second
bitRate (16)numberBits per sample (8 or 16).
channelCount (2)numberEither 1 for mono or 2 for stereo.

SoundData

Contains raw audio samples. You can not play SoundData back directly. You must wrap a Source object around it.

Constructors

Functions

Supertypes

SoundData:getBitDepth

Gets the number of bits per sample.

bits = SoundData:getBitDepth()

bitsnumberEither 8 or 16.

SoundData:getChannels

Gets the number of channels in the stream.

channels = SoundData:getChannels()

channelsnumber1 for mono, 2 for stereo.

SoundData:getDuration

Gets the duration of the sound data.

duration = SoundData:getDuration()

durationnumberThe duration of the sound data in seconds.

SoundData:getSample

Gets the sample at the specified position.

sample = SoundData:getSample( i )

samplenumberThe normalized sample (range -1.0 to 1.0).
inumberAn integer value specifying the position of the sample (0 points to the first sample).

SoundData:getSampleCount

Gets the number of samples per channel of the SoundData.

count = SoundData:getSampleCount()

countnumberTotal number of samples.

SoundData:getSampleRate

Gets the sample rate of the SoundData.

rate = SoundData:getSampleRate()

ratenumberNumber of samples per second.

SoundData:setSample

Sets the sample at the specified position.

SoundData:setSample( i, sample )

inumberThe position of the sample (0 means first sample).
samplenumberA normalized sample (range -1.0 to 1.0).

love.system

Functions

Info

Enums

love.system.getClipboardText

Gets text from the clipboard.

text = love.system.getClipboardText()

textstringThe text currently held in the system's clipboard.

love.system.getOS

Gets the current operating system. In general, LÖVE abstracts away the need to know the current operating system, but there are a few cases where it can be useful (especially in combination with os.execute.)

osString = love.system.getOS()

osStringstringThe current operating system. "OS X", "Windows", "Linux", "Android" or "iOS".

love.system.getPowerInfo

Gets information about the system's power supply.

state, percent, seconds = love.system.getPowerInfo()

statePowerStateThe basic state of the power supply.
percentnumberPercentage of battery life left, between 0 and 100. nil if the value can't be determined or there's no battery.
secondsnumberSeconds of battery life left. nil if the value can't be determined or there's no battery.

love.system.getProcessorCount

Gets the number of CPU cores in the system.

The number includes the threads reported if technologies such as Intel's Hyper-threading are enabled. For example, on a 4-core CPU with Hyper-threading, this function will return 8.

cores = love.system.getProcessorCount()

coresnumberGets the number of CPU cores in the system.

love.system.openURL

Opens a URL with the user's web or file browser.

success = love.system.openURL( url )

successbooleanWhether the URL was opened successfully.
urlstringThe URL to open. Must be formatted as a proper URL. To open a file or folder, "file://" must be prepended to the path.

love.system.setClipboardText

Puts text in the clipboard.

love.system.setClipboardText( text )

textstringThe new text to hold in the system's clipboard.

love.system.vibrate

Causes the device to vibrate, if possible. Currently this will only work on Android and iOS devices that have a built-in vibration motor.

love.system.vibrate( seconds )

seconds (0.5)numberThe duration to vibrate for. If called on an iOS device, it will always vibrate for 0.5 seconds due to limitations in the iOS system APIs.

PowerState

unknown

Cannot determine power status.

battery

Not plugged in, running on a battery.

nobattery

Plugged in, no battery available.

charging

Plugged in, charging battery.

charged

Plugged in, battery is fully charged.

love.thread

Types

love.thread.getChannel

Creates or retrieves a named thread channel.

channel = love.thread.getChannel( name )

channelChannelA named channel object which can be further manipulated.
namestringThe name of the channel you want to create or retrieve.

love.thread.newChannel

Create a new unnamed thread channel.

One use for them is to pass new unnamed channels to other threads via Channel:push

channel = love.thread.newChannel()

channelChannelA unnamed channel object which can be further manipulated.

love.thread.newThread

Creates a new Thread from a file.

thread = love.thread.newThread( file )

threadThreadA new Thread that has yet to be started.
filestring / File / FileDataThe file path/File/FileData of the Lua File to use as source.

thread = love.thread.newThread( codestring )

threadThreadA new Thread that has yet to be started.
codestringstringA string containing the Lua code to use as the source. It needs to either be at least 1024 characters long, or contain at least one newline.

Thread

A Thread is a chunk of code that can run in parallel with other threads. Data can be sent between different threads with Channel objects.

Constructors

Functions

Supertypes

Thread:getError

Retrieves the error string from the thread if it produced an error.

message = Thread:getError()

messagestringThe error message.

Thread:start

Starts the thread.

Threads can be restarted after they have completed their execution.

Thread:start()

Thread:start( arg1, arg2, ... )

arg1VariantA string, number, boolean, LÖVE object, or simple table.
arg2VariantA string, number, boolean, LÖVE object, or simple table.
...VariantYou can continue passing values to the thread.

Thread:wait

Wait for a thread to finish. This call will block until the thread finishes.

Thread:wait()

Thread:isRunning

Gets whether the thread is currently running.

Threads which are not running can be (re)started with Thread:start.

running = Thread:isRunning()

runningbooleanTrue if the thread is running, false otherwise.

Channel

A channel is a way to send and receive data to and from different threads.

Constructors

Functions

Supertypes

Channel:clear

Clears all the messages in the Channel queue.

Channel:clear()

Channel:demand

Retrieves the value of a Channel message and removes it from the message queue.

It waits until a message is in the queue then returns the message value.

value = Channel:demand()

valueVariantThe contents of the message.

Channel:getCount

Retrieves the number of messages in the thread Channel queue.

count = Channel:getCount()

countnumberThe number of messages in the queue.

Channel:peek

Retrieves the value of a Channel message, but leaves it in the queue.

It returns nil if there's no message in the queue.

value = Channel:peek()

valueVariantThe contents of the message.

Channel:performAtomic

Executes the specified function atomically with respect to this Channel.

Calling multiple methods in a row on the same Channel is often useful. However if multiple Threads are calling this Channel's methods at the same time, the different calls on each Thread might end up interleaved (e.g. one or more of the second thread's calls may happen in between the first thread's calls.)

This method avoids that issue by making sure the Thread calling the method has exclusive access to the Channel until the specified function has returned.

ret1, ... = Channel:performAtomic( func, arg1, ... )

ret1anyThe first return value of the given function (if any.)
...anyAny other return values.
funcfunctionThe function to call, the form of function(channel, arg1, arg2, ...) end. The Channel is passed as the first argument to the function when it is called.
arg1anyAdditional arguments that the given function will receive when it is called.
...anyAdditional arguments that the given function will receive when it is called.

Channel:pop

Retrieves the value of a Channel message and removes it from the message queue.

It returns nil if there are no messages in the queue.

value = Channel:pop()

valueVariantThe contents of the message.

Channel:push

Send a message to the thread Channel.

See Variant for the list of supported types.

Channel:push( value )

valueVariantThe contents of the message.

Channel:supply

Send a message to the thread Channel and wait for a thread to accept it.

See Variant for the list of supported types.

Channel:supply( value )

valueVariantThe contents of the message.

love.timer

Functions

love.timer.getAverageDelta

Gets the average delta time (seconds per frame) over the last second.

delta = love.timer.getAverageDelta()

deltanumberThe average delta time over the last second.

love.timer.getDelta

Gets the time between the last two frames.

dt = love.timer.getDelta()

dtnumberThe time passed (in seconds).

love.timer.getFPS

Gets the current frames per second.

fps = love.timer.getFPS()

fpsnumberThe current FPS.

love.timer.getTime

Gets the value of a timer with an unspecified starting time. This function should only be used to calculate differences between points in time, as the starting time of the timer is unknown.

time = love.timer.getTime()

timenumberThe time in seconds.

love.timer.sleep

Sleeps the program for the specified amount of time.

love.timer.sleep( s )

snumberSeconds to sleep for.

love.timer.step

Measures the time between two frames. Calling this changes the return value of love.timer.getDelta.

love.timer.step()

love.touch

Functions

love.touch.getPosition

Gets the current position of the specified touch-press, in pixels.

x, y = love.touch.getPosition( id )

xnumberThe position along the x-axis of the touch-press inside the window, in pixels.
ynumberThe position along the y-axis of the touch-press inside the window, in pixels.
idlight userdataThe identifier of the touch-press. Use love.touch.getTouches, love.touchpressed, or love.touchmoved to obtain touch id values.

love.touch.getPressure

Gets the current pressure of the specified touch-press.

pressure = love.touch.getPressure( id )

pressurenumberThe pressure of the touch-press. Most touch screens aren't pressure sensitive, in which case the pressure will be 1.
idlight userdataThe identifier of the touch-press. Use love.touch.getTouches, love.touchpressed, or love.touchmoved to obtain touch id values.

love.touch.getTouches

Gets a list of all active touch-presses.

touches = love.touch.getTouches()

touchestableA list of active touch-press id values, which can be used with love.touch.getPosition.

love.video

love.window

Functions

Enums

love.window.close

Closes the window. It can be reopened with love.window.setMode.

love.window.close()

love.window.fromPixels

Converts a number from pixels to density-independent units.

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.window.fromPixels(1600) would return 800 in that case.

This function converts coordinates from pixels to the size users are expecting them to display at onscreen. love.window.toPixels does the opposite. 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.

Most LÖVE functions return values and expect arguments in terms of pixels rather than density-independent units.

value = love.window.fromPixels( pixelvalue )

valuenumberThe converted number, in density-independent units.
pixelvaluenumberA number in pixels to convert to density-independent units.

x, y = love.window.fromPixels( px, py )

xnumberThe converted x-axis value of the coordinate, in density-independent units.
ynumberThe converted y-axis value of the coordinate, in density-independent units.
pxnumberThe x-axis value of a coordinate in pixels.
pynumberThe y-axis value of a coordinate in pixels.

love.window.getDisplayName

Gets the name of a display.

name = love.window.getDisplayName( displayindex )

namestringThe name of the specified display.
displayindexnumberThe index of the display to get the name of.

love.window.getFullscreen

Gets whether the window is fullscreen.

fullscreen, fstype = love.window.getFullscreen()

fullscreenbooleanTrue if the window is fullscreen, false otherwise.
fstypeFullscreenTypeThe type of fullscreen mode used.

love.window.getFullscreenModes

Gets a list of supported fullscreen modes.

modes = love.window.getFullscreenModes( display )

modestableA table of width/height pairs. (Note that this may not be in order.)
display (1)numberThe index of the display, if multiple monitors are available.

love.window.getIcon

Gets the window icon.

imagedata = love.window.getIcon()

imagedataImageDataThe window icon imagedata, or nil of no icon has been set with love.window.setIcon.

love.window.getMode

Gets the current display mode.

width, height, flags = love.window.getMode()

widthnumberWindow width.
heightnumberWindow height.
flagstableTable containing the window properties.
flags.fullscreenbooleanFullscreen (true), or windowed (false).
flags.fullscreentypeFullscreenTypeThe type of fullscreen mode used.
flags.vsyncbooleanTrue if the graphics framerate is synchronized with the monitor's refresh rate, false otherwise.
flags.msaanumberThe number of antialiasing samples used (0 if MSAA is disabled).
flags.resizablebooleanTrue if the window is resizable in windowed mode, false otherwise.
flags.borderlessbooleanTrue if the window is borderless in windowed mode, false otherwise.
flags.centeredbooleanTrue if the window is centered in windowed mode, false otherwise.
flags.displaynumberThe index of the display the window is currently in, if multiple monitors are available.
flags.minwidthnumberThe minimum width of the window, if it's resizable.
flags.minheightnumberThe minimum height of the window, if it's resizable.
flags.highdpibooleanTrue if high-dpi mode should be used on Retina displays in OS X and iOS. Does nothing on non-Retina displays. Added in 0.9.1.
flags.refreshratenumberThe refresh rate of the screen's current display mode, in Hz. May be 0 if the value can't be determined.
flags.xnumberThe x-coordinate of the window's position in its current display.
flags.ynumberThe y-coordinate of the window's position in its current display.

love.window.getPixelScale

Gets the DPI scale factor associated with the window.

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.window.getPixelScale() would return 2.0 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.window.getPixelScale()

scalenumberThe pixel scale factor associated with the window.

love.window.getPosition

Gets the position of the window on the screen.

The window position is in the coordinate space of the display it is currently in.

x, y, display = love.window.getPosition()

xnumberThe x-coordinate of the window's position.
ynumberThe y-coordinate of the window's position.
displaynumberThe index of the display that the window is in.

love.window.getTitle

Gets the window title.

title = love.window.getTitle()

titlestringThe current window title.

love.window.hasFocus

Checks if the game window has keyboard focus.

focus = love.window.hasFocus()

focusbooleanTrue if the window has the focus or false if not.

love.window.hasMouseFocus

Checks if the game window has mouse focus.

focus = love.window.hasMouseFocus()

focusbooleanTrue if the window has mouse focus or false if not.

love.window.isDisplaySleepEnabled

Gets whether the display is allowed to sleep while the program is running.

Display sleep is disabled by default. Some types of input (e.g. joystick button presses) might not prevent the display from sleeping, if display sleep is allowed.

enabled = love.window.isDisplaySleepEnabled()

enabledbooleanTrue if system display sleep is enabled / allowed, false otherwise.

love.window.isMaximized

Gets whether the Window is currently maximized.

The window can be maximized if it is not fullscreen and is resizable, and either the user has pressed the window's Maximize button or love.window.maximize has been called.

maximized = love.window.isMaximized()

maximizedbooleanTrue if the window is currently maximized in windowed mode, false otherwise.

love.window.isOpen

Checks if the window is open.

open = love.window.isOpen()

openbooleanTrue if the window is open, false otherwise.

love.window.isVisible

Checks if the game window is visible.

The window is considered visible if it's not minimized and the program isn't hidden.

visible = love.window.isVisible()

visiblebooleanTrue if the window is visible or false if not.

love.window.maximize

Makes the window as large as possible.

This function has no effect if the window isn't resizable, since it essentially programmatically presses the window's "maximize" button.

love.window.maximize()

love.window.minimize

Minimizes the window to the system's task bar / dock.

love.window.minimize()

love.window.requestAttention

Causes the window to request the attention of the user if it is not in the foreground.

In Windows the taskbar icon will flash, and in OS X the dock icon will bounce.

love.window.requestAttention( continuous )

continuous (false)booleanWhether to continuously request attention until the window becomes active, or to do it only once.

love.window.setDisplaySleepEnabled

Sets whether the display is allowed to sleep while the program is running.

Display sleep is disabled by default. Some types of input (e.g. joystick button presses) might not prevent the display from sleeping, if display sleep is allowed.

love.window.setDisplaySleepEnabled( enable )

enablebooleanTrue to enable system display sleep, false to disable it.

love.window.setFullscreen

Enters or exits fullscreen. The display to use when entering fullscreen is chosen based on which display the window is currently in, if multiple monitors are connected.

If fullscreen mode is entered and the window size doesn't match one of the monitor's display modes (in normal fullscreen mode) or the window size doesn't match the desktop size (in 'desktop' fullscreen mode), the window will be resized appropriately. The window will revert back to its original size again when fullscreen mode is exited using this function.

success = love.window.setFullscreen( fullscreen )

successbooleanTrue if successful, false otherwise.
fullscreenbooleanWhether to enter or exit fullscreen mode.

success = love.window.setFullscreen( fullscreen, fstype )

successbooleanTrue if successful, false otherwise.
fullscreenbooleanWhether to enter or exit fullscreen mode.
fstypeFullscreenTypeThe type of fullscreen mode to use.

love.window.setIcon

Sets the window icon until the game is quit. Not all operating systems support very large icon images.

success = love.window.setIcon( imagedata )

successbooleanWhether the icon has been set successfully.
imagedataImageDataThe window icon image.

love.window.setMode

Sets the display mode and properties of the window.

If width or height is 0, setMode will use the width and height of the desktop.

Changing the display mode may have side effects: for example, canvases will be cleared and values sent to shaders with Shader:send will be erased. Make sure to save the contents of canvases beforehand or re-draw to them afterward if you need to.

success = love.window.setMode( width, height, flags )

successbooleanTrue if successful, false otherwise.
widthnumberDisplay width.
heightnumberDisplay height.
flagstableThe flags table with the options:
flags.fullscreen (false)booleanFullscreen (true), or windowed (false).
flags.fullscreentype ("desktop")FullscreenTypeThe type of fullscreen to use. This defaults to "normal" in 0.9.2 and older.
flags.vsync (true)booleanTrue if LÖVE should wait for vsync, false otherwise.
flags.msaa (0)numberThe number of antialiasing samples.
flags.resizable (false)booleanTrue if the window should be resizable in windowed mode, false otherwise.
flags.borderless (false)booleanTrue if the window should be borderless in windowed mode, false otherwise.
flags.centered (true)booleanTrue if the window should be centered in windowed mode, false otherwise.
flags.display (1)numberThe index of the display to show the window in, if multiple monitors are available.
flags.minwidth (1)numberThe minimum width of the window, if it's resizable. Cannot be less than 1.
flags.minheight (1)numberThe minimum height of the window, if it's resizable. Cannot be less than 1.
flags.highdpi (false)booleanTrue if high-dpi mode should be used on Retina displays in OS X. Does nothing on non-Retina displays.
flags.x (nil)numberThe x-coordinate of the window's position in the specified display.
flags.y (nil)numberThe y-coordinate of the window's position in the specified display.

love.window.setPosition

Sets the position of the window on the screen.

The window position is in the coordinate space of the specified display.

love.window.setPosition( x, y, display )

xnumberThe x-coordinate of the window's position.
ynumberThe y-coordinate of the window's position.
displaynumberThe index of the display that the new window position is relative to.

love.window.setTitle

Sets the window title.

love.window.setTitle( title )

titlestringThe new window title.

love.window.showMessageBox

Displays a message box dialog above the love window. The message box contains a title, optional text, and buttons.

success = love.window.showMessageBox( title, message, type, attachtowindow )

successbooleanWhether the message box was successfully displayed.
titlestringThe title of the message box.
messagestringThe text inside the message box.
type ("info")MessageBoxTypeThe type of the message box.
attachtowindow (true)booleanWhether the message box should be attached to the love window or free-floating.

pressedbutton = love.window.showMessageBox( title, message, buttonlist, type, attachtowindow )

pressedbuttonnumberThe index of the button pressed by the user. May be 0 if the message box dialog was closed without pressing a button.
titlestringThe title of the message box.
messagestringThe text inside the message box.
buttonlisttableA table containing a list of button names to show. The table can also contain the fields enterbutton and escapebutton, which should be the index of the default button to use when the user presses 'enter' or 'escape', respectively.
type ("info")MessageBoxTypeThe type of the message box.
attachtowindow (true)booleanWhether the message box should be attached to the love window or free-floating.

love.window.toPixels

Converts a number from density-independent units to pixels.

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.window.toPixels(800) would return 1600 in that case.

This is used to convert coordinates from the size users are expecting them to display at onscreen to pixels. love.window.fromPixels does the opposite. 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.

Most LÖVE functions return values and expect arguments in terms of pixels rather than density-independent units.

pixelvalue = love.window.toPixels( value )

pixelvaluenumberThe converted number, in pixels.
valuenumberA number in density-independent units to convert to pixels.

px, py = love.window.toPixels( x, y )

pxnumberThe converted x-axis value of the coordinate, in pixels.
pynumberThe converted y-axis value of the coordinate, in pixels.
xnumberThe x-axis value of a coordinate in density-independent units to convert to pixels.
ynumberThe y-axis value of a coordinate in density-independent units to convert to pixels.

FullscreenType

desktop

Sometimes known as borderless fullscreen windowed mode. A borderless screen-sized window is created which sits on top of all desktop UI elements. The window is automatically resized to match the dimensions of the desktop, and its size cannot be changed.

exclusive

Standard exclusive-fullscreen mode. Changes the display mode (actual resolution) of the monitor.

MessageBoxType

info

Informational dialog.

warning

Warning dialog.

error

Error dialog.