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

Callback function triggered when window receives or loses focus.

love.focus( f )

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

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

love.keypressed( key, isrepeat )

keyKeyConstantCharacter of the key pressed.
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 key is released.

love.keyreleased( key )

keyKeyConstantCharacter of the key released.

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

Callback function triggered when window receives or loses mouse focus.

love.mousefocus( f )

fbooleanWindow mouse focus.

love.mousepressed

Callback function triggered when a mouse button is pressed.

love.mousepressed( x, y, button )

xnumberMouse x position.
ynumberMouse y position.
buttonMouseConstantMouse button pressed.

love.mousereleased

Callback function triggered when a mouse button is released.

love.mousereleased( x, y, button )

xnumberMouse x position.
ynumberMouse y position.
buttonMouseConstantMouse button released.

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

Callback function triggered when a key is pressed.

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

vbooleanWindow visibility.

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.

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

love.audio.getDistanceModel

Returns the distance attenuation model.

model = love.audio.getDistanceModel()

modelDistanceModelThe current distance model.

love.audio.getOrientation

Returns 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

Returns 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.getSourceCount

Returns 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.getVelocity

Returns 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

Returns 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( filename, type )

sourceSourceA new Source that can play the specified audio.
filenamestringThe filepath to create a Source from.
type ("stream")SourceTypeStreaming or static source.

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

sourceSourceA new Source that can play the specified audio.
fileFileA File pointing to an audio file.
type ("stream")SourceTypeStreaming or static source.

source = love.audio.newSource( fileData )

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

source = love.audio.newSource( soundData )

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

love.audio.pause

Pauses all audio

love.audio.pause()

love.audio.pause( 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.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 all playing audio.

love.audio.stop()

love.audio.stop( source )

sourceSourceThe source on which to stop the playback.

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

Returns 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: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

Returns the rolloff factor of the source.

rolloff = Source:getRolloff()

rolloffnumberThe rolloff factor.

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

Returns the volume limits of the source.

min, max = Source:getVolumeLimits()

minnumberThe minimum volume.
maxnumberThe maximum volume.

Source:isLooping

Returns whether the Source will loop.

loop = Source:isLooping()

loopbooleanTrue if the Source will loop, false otherwise.

Source:isPaused

Returns whether the Source is paused.

paused = Source:isPaused()

pausedbooleanTrue if the Source is paused, false otherwise.

Source:isPlaying

Returns whether the Source is playing.

playing = Source:isPlaying()

playingbooleanTrue if the Source is playing, false otherwise.

Source:isStatic

Returns whether the Source is static.

static = Source:isStatic()

staticbooleanTrue if the Source is static, false otherwise.

Source:isStopped

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

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.

DistanceModel

none

Sources do not get attenuated.

inverse

Inverse distance attenuation.

inverse clamped

Inverse distance attenuation. Gain is clamped.

linear

Linear attenuation.

linear clamped

Linear attenuation. Gain is clamped.

exponent

Exponential attenuation.

exponent clamped

Exponential attenuation. Gain is clamped.

SourceType

static

Decode the entire sound at once.

stream

Stream the sound; decode it gradually.

TimeUnit

seconds

Regular seconds.

samples

Audio samples.

love.event

love.event.clear

Clears the event queue.

love.event.clear()

love.event.poll

Returns an iterator for messages in the event queue.

i = love.event.poll()

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.
amixedFirst event argument.
bmixedSecond event argument.
cmixedThird event argument.
dmixedFourth 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.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.
amixedFirst event argument.
bmixedSecond event argument.
cmixedThird event argument.
dmixedFourth event argument.

Event

focus

Window focus gained or lost

joystickpressed

Joystick pressed

joystickreleased

Joystick released

keypressed

Key pressed

keyreleased

Key released

mousepressed

Mouse pressed

mousereleased

Mouse released

quit

Quit

love.filesystem

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

Creates a directory.

ok = love.filesystem.createDirectory( name )

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

love.filesystem.exists

Check whether a file or directory exists.

e = love.filesystem.exists( filename )

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

love.filesystem.getAppdataDirectory

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

path = love.filesystem.getAppdataDirectory()

pathstringThe path of the application data directory.

love.filesystem.getDirectoryItems

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

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

items = love.filesystem.getDirectoryItems( dir )

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

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

itemstableA sequence with the names of all files and subdirectories as strings.
dirstringThe directory.
callbackfunctionA function which is called for each file and folder in the directory. The filename is passed to the function as an argument.

love.filesystem.getIdentity

Gets the write directory name for your game. Note that this only returns the name of the folder to store your files in, not the full 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.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.getUserDirectory

Returns 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.isDirectory

Check whether something is a directory.

is_dir = love.filesystem.isDirectory( path )

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

is_file = love.filesystem.isFile( path )

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

Load a file (but not run it).

chunk = love.filesystem.load( name )

chunkfunctionThe loaded chunk.
namestringThe name (and path) of the file.

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.

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.

ok = love.filesystem.remove( name )

okbooleanTrue 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, searchorder )

namestringThe new identity that will be used as write directory.
searchorder ("first")SearchOrderWhether love.filesystem will look for files in the write directory before or after looking in the main game source.

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 = love.filesystem.write( name, data, size )

successbooleanIf the operation was successful
namestringThe name (and path) of the file.
datastringThe data that should be written to the file
size (all)numberHow many bytes to write.

File:close

Closes a file.

success = File:close()

successbooleanWhether closing was successful.

File:eof

If the end-of-file has been reached

eof = File:eof()

eofbooleanWhether EOF has been reached.

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:getMode

Gets the FileMode the file has been opened with.

mode = File:getMode()

modeFileModeThe mode this file has been opened with.

File:getSize

Returns the file size.

size = File:getSize()

sizenumberThe file size

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.

ok = File:open( mode )

okbooleanTrue 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.
sizenumberThe maximum size in bytes of the file's buffer.

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

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

love.graphics

love.graphics.arc

Draws an arc.

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

modeDrawModeHow to draw the arc.
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, 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.
segments (max(radius, 10))numberThe number of segments used for drawing the circle.

love.graphics.clear

Clears the screen to background color and restores the default coordinate system.

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

love.graphics.draw

Draws objects on screen. Drawable objects are loaded images, but may be other kinds of Drawable objects, such as a ParticleSystem.

In addition to simple drawing, this function can rotate and scale the object at the same time, as well as offset the image (for example, to center the image at the chosen coordinates).

love.graphics.draw anchors from the top left corner by default.

You can specify a negative value for sx or sy to flip the drawable horizontally or vertically.

The pivotal point is (x, y) on the screen and (ox, oy) in the internal coordinate system of the drawable object, before rotation and scaling. The object is scaled by (sx, sy), then rotated by r around the pivotal point.

The origin offset values are most often used to shift the images up and left by half of its height and width, so that (effectively) the specified x and y coordinates are where the center of the image will end up.

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( image, quad, x, y, r, sx, sy, ox, oy, kx, ky )

imageImageAn image 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.draw( canvas, quad, x, y, r, sx, sy, ox, oy, kx, ky )

canvasCanvasA 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.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 = love.graphics.getBlendMode()

modeBlendModeThe current blend mode.

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

Returns 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.getFSAA

Gets the number of antialiasing 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 = love.graphics.getFSAA()

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

love.graphics.getFont

Gets the current Font object.

font = love.graphics.getFont()

fontFontThe current Font, or nil if none is set.

love.graphics.getFullscreenModes

Gets a list of supported fullscreen modes.

modes = love.graphics.getFullscreenModes()

modestableA table of width/height pairs. (Note that this may not be in order.)

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

Gets the point size.

size = love.graphics.getPointSize()

sizenumberThe current point size.

love.graphics.getPointStyle

Gets the current point style.

style = love.graphics.getPointStyle()

stylePointStyleThe current point style.

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".
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.getShader

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

shader = love.graphics.getShader()

shaderShaderThe current Shader.

love.graphics.getSystemLimit

Gets the system-dependent maximum value for a love.graphics feature.

limit = love.graphics.getSystemLimit( limittype )

limitnumberThe system-dependent max value for the feature.
limittypeGraphicsLimitThe graphics feature to get the maximum value of.

love.graphics.getWidth

Gets the width of the window.

width = love.graphics.getWidth()

widthnumberThe width of the window.

love.graphics.isSupported

Checks if certain graphics functions can be used.

Older and low-end systems do not always support all graphics extensions.

isSupported = love.graphics.isSupported( supportN )

isSupportedbooleanTrue if everything is supported, false otherwise.
supportNGraphicsFeatureThe graphics feature to check for.

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 FSAA samples varies depending on the system. Use love.graphics.getSystemLimit to check.

If the number of FSAA 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, texture_type, fsaa )

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

love.graphics.newFont

Creates a new Font.

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

fontFontA Font object which can be used to draw text on screen.
filenamestringThe filepath to the font file.
size (12)numberThe size of the font in pixels.

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

fontFontA Font object which can be used to draw text on screen.
fileFileA File pointing to a font.
size (12)numberThe size of the font in pixels.

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

fontFontA Font object which can be used to draw text on screen.
filedataFileDataThe encoded data to decode into a font.
size (12)numberThe size of the font in pixels.

font = love.graphics.newFont( size )

fontFontA Font object which can be used to draw text on screen.
size (12)numberThe size of the font in pixels.

love.graphics.newImage

Creates a new Image.

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

imageImageAn Image object which can be drawn on screen.
filenamestringThe filepath to the image file.
format ("normal")TextureFormatThe format to interpret the image's data as.

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

imageImageAn Image object which can be drawn on screen.
fileFileA File pointing to an image.
format ("normal")TextureFormatThe format to interpret the image's data as.

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

imageImageAn Image object which can be drawn on screen.
fileDataFileDataA FileData pointing to an image.
format ("normal")TextureFormatThe format to interpret the image's data as.

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

imageImageAn Image object which can be drawn on screen.
imageDataImageDataAn ImageData object.
format ("normal")TextureFormatThe format to interpret the image's data as.

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

imageImageAn Image object which can be drawn on screen.
compressedDataCompressedDataA CompressedData object. The Image will use this CompressedData to reload itself when love.window.setMode is called.
format ("normal")TextureFormatThe format to interpret the image's data as.

love.graphics.newImageFont

Creates a new font by loading a specifically formatted image. There can be up to 256 glyphs.

Expects ISO 8859-1 encoding for the glyphs string.

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

fontFontA Font object which can be used to draw text on screen.
filenamestringThe filepath to the image file.
glyphsstringA string of the characters in the image in order from left to right.

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

fontFontA Font object which can be used to draw text on screen.
fileFileA File pointing to an image.
glyphsstringA string of the characters in the image in order from left to right.

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

fontFontA Font object which can be used to draw text on screen.
dataDataThe encoded data to decode into image data.
glyphsstringA string of the characters in the image in order from left to right.

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

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

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

fontFontA Font object which can be used to draw text on screen.
imageImageThe Image object to create the font from.
glyphsstringA string of the characters in the image in order from left to right.

love.graphics.newMesh

Creates a new Mesh.

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

meshMeshThe new Mesh.
verticestableThe table filled with vertex information tables.
vertices.xnumberThe position of the vertex on the x-axis.
vertices.ynumberThe position of the vertex on the y-axis.
vertices.u (0)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.v (0)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.r (255)numberThe red color component.
vertices.g (255)numberThe green color component.
vertices.b (255)numberThe blue color component.
vertices.a (255)numberThe alpha color component.
texture (nil)TextureThe Image or Canvas to use when drawing the Mesh. May be nil to use no texture.
mode ("fan")MeshDrawModeHow the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.

love.graphics.newParticleSystem

Creates a new ParticleSystem.

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

systemParticleSystemA new ParticleSystem.
textureTextureThe Image or Canvas to use.
buffernumberThe max number of particles at the same time.

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

screenshotImageDataThe image data of the screenshot.

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.
codestringThe pixel shader or vertex shader code, or a filename pointing to a file with the code.

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

shaderShaderA Shader object for use in drawing operations.
pixelcodestringThe pixel shader code, or a filename pointing to a file with the code.
vertexcodestringThe vertex shader code, or a filename pointing to a file with the code.

love.graphics.newSpriteBatch

Creates a new SpriteBatch object.

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

spriteBatchSpriteBatchThe new SpriteBatch.
textureTextureThe Image or Canvas to use for the sprites.
size (1000)numberThe max number of sprites.
usage ("dynamic")SpriteBatchUsageThe expected usage of the SpriteBatch.

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

Draws a point.

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

love.graphics.point( x, y )

xnumberThe position on the x-axis.
ynumberThe position on the y-axis.

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.

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 stops at the first '' (null) character. This can bite you if you are appending keystrokes to form your string, as some of those are multi-byte unicode characters which will likely contain null bytes.

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

Draws formatted text, with word wrap and alignment.

See additional notes in love.graphics.print.

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

love.graphics.rectangle

Draws a rectangle.

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

modeDrawModeHow to draw the rectangle.
xnumberThe position of top-left corner along x-axis.
ynumberThe position of top-left corner along y-axis.
widthnumberWidth of the rectangle.
heightnumberHeight of the rectangle.

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 )

modeBlendModeThe blend mode to use.

love.graphics.setCanvas

Sets the render target to one or more Canvases. All drawing operations until the next love.graphics.setCanvas call will be redirected to the specified canvases and not shown on the screen.

All canvas arguments must have the same widths and heights and the same texture type. Normally the same thing will be drawn on each canvas, but that can be changed if a pixel shader is used with the "effects" function instead of the regular effect.

Not all computers support Canvases, and not all computers which support Canvases will support multiple render targets. Use love.graphics.isSupported to check.

nWhen called without arguments, the render target is reset to the screen.

love.graphics.setCanvas()

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

canvasCanvasA render target.
...CanvasAdditional render targets.

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

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

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

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

Defines an inverted stencil for the drawing operations or releases the active one.

It's the same as love.graphics.setStencil with the mask inverted.

Calling the function without arguments releases the active stencil.

love.graphics.setInvertedStencil()

love.graphics.setInvertedStencil( stencilFunction )

stencilFunctionfunctionFunction that draws the stencil.

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

fontFontThe new font.
size (12)numberThe size of the font.

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

fontFontThe new font.
filenamestringCreates and sets a new font.
size (12)numberThe size of the font.

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

fontFontThe new font.
fileFileA File with the font.
size (12)numberThe size of the font.

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

fontFontThe new font.
dataDataA Data with the font.
size (12)numberThe size of the font.

font = love.graphics.setNewFont( rasterizer )

fontFontThe new font.
rasterizerRasterizerA rasterizer.

love.graphics.setPointSize

Sets the point size.

love.graphics.setPointSize( size )

sizenumberThe new point size.

love.graphics.setPointStyle

Sets the point style.

love.graphics.setPointStyle( style )

stylePointStyleThe new point style.

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

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

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

Defines or releases a stencil for the drawing operations.

The passed function draws to the stencil instead of the screen, creating an image with transparent and opaque pixels. While active, it is used to test where pixels will be drawn or discarded.

Calling the function without arguments releases the active stencil.

When called without arguments, the active stencil is released.

love.graphics.setStencil()

love.graphics.setStencil( stencilFunction )

stencilFunctionfunctionFunction that draws the stencil.

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

Canvas:clear

Clears content of a Canvas.

When called without arguments, the Canvas will be cleared with color rgba = {0,0,0,0}, i.e. it will be fully transparent. If called with color parameters (be it numbers or a color table), the alpha component may be omitted in which case it defaults to 255 (fully opaque).

Canvas:clear( red, green, blue, alpha )

rednumberRed component of the clear color (0-255).
greennumberGreen component of the clear color (0-255).
bluenumberBlue component of the clear color (0-255).
alpha (255)numberAlpha component of the clear color (0-255).

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:getFSAA

Gets the number of antialiasing 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:getFSAA()

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

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:getHeight

Gets the height of the Canvas.

height = Canvas:getHeight()

heightnumberThe height of the Canvas, in pixels.

Canvas:getImageData

Returns the image data stored in the Canvas. Think of it as taking a screenshot of the hidden screen that is the Canvas.

data = Canvas:getImageData()

dataImageDataThe image data stored in the Canvas.

Canvas:getPixel

Gets the pixel at the specified position from a Canvas.

Valid x and y values start at 0 and go up to canvas width and height minus 1.

r, g, b, a = Canvas: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.

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: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: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

Returns how many lines text would be wrapped to. This function accounts for newlines correctly (i.e. '\n')

width, lines = Font:getWrap( text, width )

widthnumberThe actual width the wrapped text.
linesnumberThe number of lines text was wrapped to.
textstringThe text that would be wrapped.
widthnumberThe width to which text should be wrapped.

Font:hasGlyph

Gets whether the font can render a particular character.

hasglyph = Font:hasGlyph( character )

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

hasglyph = Font:hasGlyph( codepoint )

hasglyphbooleanWhether the font can render the glyph represented by the codepoint number.
codepointnumberA unicode codepoint number.

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: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

Returns vertex information from the Mesh.

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

xnumberThe x vertex coordinate.
ynumberThe y vertex coordinate.
unumberThe u vertex coordinate.
vnumberThe v vertex coordinate.
rnumberThe red color component.
gnumberThe green color component.
bnumberThe blue color component.
anumberThe alpha color component.
inumberThe index of the the vertex you want to retrieve the information for.

Mesh:getVertexCount

Returns the total number of vertices in the Mesh.

num = Mesh:getVertexCount()

numnumberThe total number of vertices in this Mesh.

Mesh:getVertexMap

Gets the Mesh's vertex map.

If no vertex map has been set previously (either in love.graphics.newMesh or with Mesh:setVertexMap), then this function will return the default vertex map: {1, 2, 3, ..., Mesh:getVertexCount()}.

vertex_map = Mesh:getVertexMap()

vertex_maptableA table containing a list of vertex indices used when drawing.

Mesh:getVertices

Gets all the vertices in the Mesh.

This method can be slow if the Mesh has a large number of vertices. Keep the original table used to create the Mesh around and update it when necessary instead of using this method frequently, if possible.

vertices = Mesh:getVertices()

verticestableThe table filled with vertex information tables.

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: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:setVertexColors

Sets if the per-vertex colors are used when rendering instead of the constant color (constant color being love.graphics.setColor or SpriteBatch:setColor)

The per-vertex colors are automatically enabled by default when making a new Mesh or when doing Mesh:setVertex, but only if at least one vertex color is not the default (255,255,255,255).

Mesh:setVertexColors( on )

onbooleanTrue to use per-vertex coloring.

Mesh:setVertex

Sets the vertex information for a Mesh.

Mesh:setVertex( i, x, y, u, v, r, g, b, a )

inumberThe index of the the vertex you want to alter the information for.
xnumberThe x vertex coordinate.
ynumberThe y vertex coordinate.
unumberThe u vertex coordinate.
vnumberThe v vertex coordinate.
r (255)numberThe red color component.
g (255)numberThe green color component.
b (255)numberThe blue color component.
a (255)numberThe alpha color component.

Mesh:setVertexColors

Sets if the per-vertex colors are used when rendering instead of the constant color (constant color being love.graphics.setColor or SpriteBatch:setColor)

The per-vertex colors are automatically enabled by default when making a new Mesh or when doing Mesh:setVertex, but only if at least one vertex color is not the default (255,255,255,255).

Mesh:setVertexColors( on )

onbooleanTrue to use per-vertex coloring.

Mesh:setVertexMap

Sets the vertex map for a Mesh. The vertex map describes the order in which the vertices are used when the Mesh is drawn.

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

vertex_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 all vertices in the Mesh with new ones.

Mesh:setVertices( vertex_map )

vertex_maptableThe table filled with vertex information tables for each vertex.
vertex_map.xnumberThe position of the vertex on the x-axis.
vertex_map.ynumberThe position of the vertex on the y-axis.
vertex_map.u (0)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.)
vertex_map.v (0)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.)
vertex_map.r (255)numberThe red color component.
vertex_map.g (255)numberThe green color component.
vertex_map.b (255)numberThe blue color component.
vertex_map.a (255)numberThe alpha color component.

Image:getData

Gets the original ImageData or CompressedData 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()

dataCompressedDataThe original CompressedData 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: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 CompressedData used to create the image.

Image:refresh()

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.

Automatically creates mipmaps for the Image if none exist yet. If the image is compressed and its CompressedData has mipmap data included, it will use that.

Disables mipmap filtering when called without arguments.

Image:setMipmapFilter()

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: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: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: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: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: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 (ymax)numberThe maximum acceleration along the y axis.

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

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

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:getWarnings

Returns any warning and error messages from compiling the shader code. This can be used for debugging your shaders if there's anything the graphics hardware doesn't like.

warnings = Shader:getWarnings()

warningsstringWarning messages (if any).

Shader:send

Sends one or more values to a special (extern) variable inside the shader.

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

namestringName of the number to send to the pixel effect.
numbernumberNumber to send to the pixel effect.
...numberAdditional numbers to send in case the extern is an array.

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

namestringName of the vector to send to the shader.
vectortableNumbers to send to the extern 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 in case the extern 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 extern. Using table form: {{a,b,c,d}, {e,f,g,h}, ... }
...tableAdditional matrices of the same type as matrix to store in the extern array.

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

namestringName of the Image to send to the shader.
imageImageImage to send to the extern.
...ImageAdditional images in case the extern is an array.

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

namestringName of the Canvas to send to the shader.
canvasCanvasCanvas to send to the extern. The shader extern type is Image.
...CanvasAdditional canvases to send to the extern array.

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

namestringName of the boolean to send to the shader.
booleanbooleanBoolean to send to store in the extern.
...booleanAdditional booleans to send in case the extern is an array.

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:bind

Binds the SpriteBatch to the memory.

Binding a SpriteBatch before updating its content can improve the performance as it doesn't push each update to the graphics card separately. Don't forget to unbind the SpriteBatch or the updates won't show up.

SpriteBatch:bind()

SpriteBatch:clear

Removes all sprites from the buffer.

SpriteBatch:clear()

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.

SpriteBatch:getColor()

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

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

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

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

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:setTexture

Replaces the Image or Canvas used for the sprites.

SpriteBatch:setTexture( texture )

textureTextureThe new Image or Canvas to use for the sprites.

SpriteBatch:unbind

Unbinds the SpriteBatch.

SpriteBatch:unbind()

AlignMode

center

Align text center.

left

Align text left.

right

Align text right.

AreaSpreadDistribution

uniform

Uniform distribution.

normal

Normal (gaussian) distribution.

none

No distribution - area spread is disabled.

BlendMode

additive

Additive blend mode.

alpha

Alpha blend mode ("normal").

replace

Replace blend mode.

screen

Screen blend mode.

subtractive

Subtractive blend mode.

multiplicative

Multiply blend mode.

premultiplied

Premultiplied blend mode.

DrawMode

fill

Draw filled shape.

line

Draw outlined shape.

FilterMode

linear

Scale image with linear interpolation.

nearest

Scale image with nearest neighbor interpolation.

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 v1, v2, v3, then v3, v2, v4 (note the order), then v3, v4, v5 and so on.

triangles

The vertices create unconnected triangles.

points

The vertices are drawn as unconnected points (see love.graphics.setPointSize.)

GraphicsFeature

canvas

Support for Canvas.

npot

Support for textures with non-power-of-two textures.

subtractive

Support for the subtractive blend mode.

shader

Support for Shader.

hdrcanvas

Support for HDR Canvas.

multicanvas

Support for simultaneous rendering to at least 4 canvases at once, with love.graphics.setCanvas.

mipmap

Support for Mipmaps.

dxt

Support for DXT compressed images (see CompressedFormat.)

bc5

Support for BC4 and BC5 compressed images.

srgb

Support for gamma-correct rendering with the srgb window flag in love.window.setMode, and the "srgb" TextureFormat for Canvases and Images.

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

canvasfsaa

The maximum number of antialiasing samples for a Canvas.

LineJoin

miter

Miter style.

bevel

Bevel style.

none

None style.

LineStyle

rough

Draw rough lines.

smooth

Draw smooth lines.

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.

PointStyle

rough

Draw rough points.

smooth

Draw smooth points.

SpriteBatchUsage

dynamic

The SpriteBatch data will change repeatedly during its lifetime.

static

The SpriteBatch will not be modified after initial sprites are added.

stream

The SpriteBatch data will always change between draws.

TextureFormat

normal

The default texture format: 8 bits per channel (32 bpp) RGBA.

hdr

Only usable in Canvases. The HDR texture format: floating point 16 bits per channel (64 bpp) RGBA.

srgb

The same as normal, but the texture is interpreted as being in the sRGB color space. It will be decoded from sRGB to linear RGB when drawn or sampled from in a shader. For Canvases, this will also convert everything drawn to the Canvas from linear RGB to sRGB.

WrapMode

clamp

Clamp the image. Appears only once.

repeat

Repeat the image. Fills the whole available extent.

love.image

love.image.isCompressed

Determines whether a file can be loaded as CompressedData.

compressed = love.image.isCompressed( filename )

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

compressed = love.image.isCompressed( fileData )

compressedbooleanWhether the FileData can be loaded as CompressedData or not.
fileDataFileDataA FileData potentially containing a compressed image.

love.image.newCompressedData

Create a new CompressedData object from a compressed image file. LÖVE currently supports DDS files compressed with the DXT1, DXT5, and BC5 / 3Dc formats.

compressedData = love.image.newCompressedData( filename )

compressedDataCompressedDataThe new CompressedData object.
filenamestringThe filename of the compressed image file.

compressedData = love.image.newCompressedData( fileData )

compressedDataCompressedDataThe new CompressedData object.
fileDataFileDataA FileData containing a compressed image.

love.image.newImageData

Create a new ImageData object.

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

imageDataImageDataThe new ImageData object.
widthnumberThe width of the ImageData.
heightnumberThe height of the ImageData.

imageData = love.image.newImageData( filename )

imageDataImageDataThe new ImageData object.
filenamestringThe filename of the image file.

imageData = love.image.newImageData( file )

imageDataImageDataThe new ImageData object.
fileFileA File pointing to an image.

imageData = love.image.newImageData( data )

imageDataImageDataThe new ImageData object.
dataDataThe encoded data to decode into image data.

CompressedData:getDimensions

Gets the width and height of the CompressedData.

width, height = CompressedData:getDimensions( level )

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

width, height = CompressedData:getDimensions()

widthnumberThe width of the CompressedData.
heightnumberThe height of the CompressedData.

CompressedData:getHeight

Gets the height of the CompressedData.

height = CompressedData:getHeight()

heightnumberThe height of the CompressedData.

height = CompressedData:getHeight( level )

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

CompressedData:getMipmapCount

Gets the number of mipmap levels in the CompressedData. The base mipmap level (original image) is included in the count.

Mipmap filtering cannot be activated for an Image created from a CompressedData which does not have enough mipmap levels to go down to 1x1. For example, a 256x256 image created from a CompressedData should have 8 mipmap levels or Image:setMipmapFilter will error. Most tools which can create compressed textures are able to automatically generate mipmaps for them in the same file.

CompressedData:getMipmapCount( mipmaps )

mipmapsnumberThe number of mipmap levels stored in the CompressedData.

CompressedData:getWidth

Gets the width of the CompressedData.

width = CompressedData:getWidth()

widthnumberThe width of the CompressedData.

width = CompressedData:getWidth( level )

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

ImageData:encode

Encodes the ImageData and writes it to the save directory.

ImageData:encode( filename )

filenamestringName of a file to write encoded data to. The format will be automatically deduced from the file extension.

ImageData:encode( filename, format )

filenamestringName of a file to write encoded data to.
formatImageFormatThe format to encode the image in.

ImageData:getDimensions

Gets the width and height of the ImageData.

width, height = ImageData:getDimensions()

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

ImageData:getHeight

Gets the height of the ImageData.

height = ImageData:getHeight()

heightnumberThe height of the ImageData.

ImageData:getPixel

Gets the pixel at the specified position.

Valid x and y values start at 0 and go up to image width and height minus 1.

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.

width = ImageData:getWidth()

widthnumberThe width of the ImageData.

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.

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

ImageFormat

bmp

BMP image format.

tga

Targa image format.

png

PNG image format.

jpg

JPG image format.

love.joystick

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

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 a 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: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.

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.

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.

love.keyboard

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.

down = love.keyboard.isDown( key )

downbooleanTrue if the key is down, false if not.
keyKeyConstantThe key to check.

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

anyDownbooleanTrue if any supplied key is down, false if not.
...KeyConstantA key 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.

love.keyboard.setTextInput( enable )

enablebooleanWhether text input events should be enabled.

KeyConstant

a

The A key

b

The B key

c

The C key

d

The D key

e

The E key

f

The F key

g

The G key

h

The H key

i

The I key

j

The J key

k

The K key

l

The L key

m

The M key

n

The N key

o

The O key

p

The P key

q

The Q key

r

The R key

s

The S key

t

The T key

u

The U key

v

The V key

w

The W key

x

The X key

y

The Y key

z

The Z key

0

The zero key

1

The one key

2

The two key

3

The three key

4

The four key

5

The five key

6

The six key

7

The seven key

8

The eight key

9

The nine key

(space)

Space key

!

Exclamation mark key

"

Double quote key

#

Hash key

$

Dollar key

&

Ampersand key

'

Single quote key

(

Left parenthesis key

)

Right parenthesis key

*

Asterisk key

+

Plus key

,

Comma key

-

Hyphen-minus key

.

Full stop key

/

Slash key

:

Colon key

;

Semicolon key

<

Less-than key

=

Equal key

>

Greater-than key

?

Question mark key

@

At sign key

?

Question mark key

[

Left square bracket key

\

Backslash key

]

Right square bracket key

^

Caret key

_

Underscore key

`

Grave accent key

kp0

The numpad zero key

kp1

The numpad one key

kp2

The numpad two key

kp3

The numpad three key

kp4

The numpad four key

kp5

The numpad five key

kp6

The numpad six key

kp7

The numpad seven key

kp8

The numpad eight key

kp9

The numpad nine key

kp.

The numpad decimal point key

kp/

The numpad division key

kp*

The numpad multiplication key

kp-

The numpad substraction key

kp+

The numpad addition key

kpenter

The numpad enter key

kp=

The numpad equals key

up

Up cursor key

down

Down cursor key

right

Right cursor key

left

Left cursor key

home

Home key

end

End key

pageup

Page up key

pagedown

Page down key

insert

Insert key

backspace

Backspace key

tab

Tab key

clear

Clear key

return

Return key

delete

Delete key

f1

The 1st function key

f2

The 2nd function key

f3

The 3rd function key

f4

The 4th function key

f5

The 5th function key

f6

The 6th function key

f7

The 7th function key

f8

The 8th function key

f9

The 9th function key

f10

The 10th function key

f11

The 11th function key

f12

The 12th function key

f13

The 13th function key

f14

The 14th function key

f15

The 15th function key

numlock

Num-lock key

capslock

Caps-lock key

scrollock

Scroll-lock key

rshift

Right shift key

lshift

Left shift key

rctrl

Right control key

lctrl

Left control key

ralt

Right alt key

lalt

Left alt key

rmeta

Right meta key

lmeta

Left meta key

lsuper

Left super key

rsuper

Right super key

mode

Mode key

compose

Compose key

pause

Pause key

escape

Escape key

help

Help key

print

Print key

sysreq

System request key

break

Break key

menu

Menu key

power

Power key

euro

Euro (€) key

undo

Undo key

www

WWW key

mail

Mail key

calculator

Calculator key

appsearch

Application search key

apphome

Application home key

appback

Application back key

appforward

Application forward key

apprefresh

Application refresh key

appbookmarks

Application bookmarks key

love.math

love.math.gammaToLinear

Converts a color from gamma-space (sRGB) to linear-space (RGB). This is useful when doing gamma-correct rendering using colors created based on what they look like on-screen.

Gamma-space sRGB has more precision in the lower end than linear RGB. Using this function to convert from sRGB to RGB can result in non-integer color values, which get truncated to integers and lose precision when used with other functions such as love.graphics.setColor.

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

rngRandomGeneratorA Random Number Generator object.

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

rngRandomGeneratorA Random Number Generator object.
lownumberThe lower 32 bits of the state number to use for this instance of the object.
high (0)numberThe higher 32 bits of the state number to use for this instance of the object.

rng = love.math.newRandomGenerator( seed )

rngRandomGeneratorA Random Number Generator object.
seedstringA state of a RandomGenerator object returned by RandomGenerator:getState.

love.math.noise

Generates a Simplex noise value in 1-4 dimensions.

Simplex noise is closely related to Perlin noise. It is widely used for procedural content generation.

value = love.math.noise( x )

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

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

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 )

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 )

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

number = love.math.random()

numbernumberThe pseudo random number.

number = love.math.random( max )

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

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

numbernumberThe pseudo random 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].
high (0)numberThe 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.

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

number = RandomGenerator:random()

numbernumberThe pseudo random number.

number = RandomGenerator:random( max )

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

number = RandomGenerator:random( min, max )

numbernumberThe pseudo random 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.

BezierCurve:evalulate

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:evalulate( 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:insertControlPoint

Insert control point after the i-th control point. 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: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:evalulate.

coordinates = BezierCurve:render( depth )

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

love.mouse

love.mouse.getCursor

Gets the current Cursor.

cursor = love.mouse.getCursor()

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

love.mouse.getPosition

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

Returns the current x position of the mouse.

x = love.mouse.getX()

xnumberThe position of the mouse along the x-axis.

love.mouse.getY

Returns the current y position of the mouse.

y = love.mouse.getY()

ynumberThe position of the mouse along the y-axis.

love.mouse.isDown

Checks whether a certain mouse button is down. This function does not detect mousewheel scrolling; you must use the love.mousepressed callback for that.

down = love.mouse.isDown( button )

downbooleanTrue if the specified button is down.
buttonMouseConstantThe button to check.

anyDown = love.mouse.isDown( ... )

anyDownbooleanTrue if any specified button is down, false otherwise.
...MouseConstantA button 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 frameratesn

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 position of the mouse.

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

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.

love.mouse.setY( y )

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

Cursor:getType

Gets the type of the Cursor.

cursortype = Cursor:getType()

cursortypeCursorTypeThe type of the Cursor.

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.

MouseConstant

l

Left mouse button.

m

Middle mouse button.

r

Right mouse button.

wd

Mouse wheel down.

wu

Mouse wheel up.

x1

Mouse X1 (also known as button 4).

x2

Mouse X2 (also known as button 5).

love.physics

love.physics.getDistance

Returns 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 chain shape.

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.

love.physics.newCircleShape

Create a new CircleShape at (x,y) in local coordinates.

Anchors from the center of the shape by default.

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

shapeCircleShapeA new CircleShape.
bodyBodyThe body to attach the shape to.
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.
y1numberThe y position of the first anchor point.
x2numberThe x position of the second anchor point.
y2numberThe y position of the second anchor point.
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 )

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

jointJointThe 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( body, ... )

shapePolygonShapeA new PolygonShape.
bodyBodyThe body to attach the shape to.
...numberVertices of the polygon.

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, x, y, ax, ay, collideConnected )

jointPrismaticJointThe new prismatic joint.
body1BodyThe first body to connect with a prismatic joint.
body2BodyThe second body to connect with a prismatic joint.
xnumberThe x coordinate of the anchor point.
ynumberThe y coordinate of the anchor point.
axnumberThe x coordinate of the axis vector.
aynumberThe y coordinate of the axis vector.
collideConnected (false)booleanSpecifies whether the two bodies should collide with each other.

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 )

jointJointThe 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 rectangluar PolygonShapes.

The rectangle will be created at (x,y) in local coordinates.

Anchors from the center of the shape by default.

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

shapePolygonShapeA new PolygonShape.
bodyBodyThe Body to attach the Shape to.
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 )

jointJointThe new revolute joint.
body1BodyThe first body to connect with a Revolute Joint.
body2BodyThe second body to connect with a Revolute Joint.
xnumberThe x position of the connecting point.
ynumberThe y position of the connecting point.
collideConnectednumberSpecifies 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

Create a friction joint between two bodies. A WeldJoint essentially glues two bodies together.

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

jointWeldJointThe new WeldJoint.
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 each other.

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.

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.

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:applyImpulse.

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:getFixtureList

Returns a table with all fixtures.

fixtures = Body:getFixtureList()

fixturestableA sequence with all fixtures.

Body:getGravityScale

Returns 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. It is set with the 4th argument to Body:setMass, or automatically with Body:setMassFromShapes.

inertia = Body:getInertia()

inertianumberThe rotational inertial of 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.

local_x, local_y = Body:getLocalPoint( world_x, world_y )

local_xnumberThe x position in local coordinates.
local_ynumberThe y position in local coordinates.
world_xnumberThe x position in world coordinates.
world_ynumberThe y position in world coordinates.

Body:getLocalVector

Transform a vector from world coordinates to local coordinates.

local_x, local_y = Body:getLocalVector( world_x, world_y )

local_xnumberThe vector x component in local coordinates.
local_ynumberThe vector y component in local coordinates.
world_xnumberThe vector x component in world coordinates.
world_ynumberThe 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

Returns 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

Returns the type of the body.

type = Body:getType()

typeBodyTypeThe body type.

Body:getUserData

Returns the Lua value associated with this Body.

Use this function in one thread only.

value = Body:getUserData()

valuevalueThe Lua value associated with the Body.

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.

world_x, world_y = Body:getWorldPoint( local_x, local_y )

world_xnumberThe x position in world coordinates.
world_ynumberThe y position in world coordinates.
local_xnumberThe x position in local coordinates.
local_ynumberThe 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.

world_x, world_y = Body:getWorldVector( local_x, local_y )

world_xnumberThe vector x component in world coordinates.
world_ynumberThe vector y component in world coordinates.
local_xnumberThe vector x component in local coordinates.
local_ynumberThe 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

Returns whether the body is actively used in the simulation.

status = Body:isActive()

statusbooleanTrue if the body is active or false if not.

Body:isAwake

Returns 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:isDynamic

Get the dynamic status of the body.

A static body has no mass and a constant position. It will not react to collisions. Often used for walls.

A dynamic body has mass and can move. It will react to collisions when the world is updated.

status = Body:isDynamic()

statusbooleanThe dynamic status of the body.

Body:isFixedRotation

Returns whether the body rotation is locked.

fixed = Body:isFixedRotation()

fixedbooleanTrue if the body's rotation is locked or false if not.

Body:isFrozen

Get the frozen status of the body.

A body becomes frozen when it goes outside the world boundary. A frozen body is no longer changed by World:update.

status = Body:isFrozen()

statusbooleanThe frozen status of the body.

Body:isSleepingAllowed

Returns the sleeping behaviour of the body.

status = Body:isSleepingAllowed()

statusbooleanTrue if the body is allowed to sleep or false if not.

Body:isStatic

Get the static status of the body.

A static body has no mass and a constant position. It will not react to collisions. Often used for walls.

A dynamic body has mass and can move. It will react to collisions when the world is updated.

status = Body:isStatic()

statusbooleanThe static status of the body.

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.

This value can also be set by the fourth argument of Body:setMass.

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:setMassFromShapes

Sets mass properties from attatched shapes.

If you feel that finding the correct mass properties is tricky, then this function may be able to help you. After creating the needed shapes on the Body, a call to this function will set the mass properties based on those shapes. Remember to call this function after adding the shapes.

Setting the mass properties this way always results in a realistic (or at least good-looking) simulation, so using it is highly recommended.

Body:setMassFromShapes()

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.

Use this function in one thread only.

Body:setUserData( value )

valuevalueThe 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:getChildEdge

Returns a child of the shape as an EdgeShape.

EdgeShape = ChainShape:getChildEdge( index )

EdgeShapenumberThe child as an EdgeShape.
indexnumberThe index of the child.

ChainShape:getPoint

Returns 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

Returns 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:getVertexCount

Returns 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: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: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

Returns 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

Returns whether the contact is enabled. The collision will be ignored if a contact gets disabled in the post solve callback.

enabled = Contact:isEnabled()

enabledbooleanTrue if enabled, false otherwise.

Contact:isTouching

Returns 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:getPoints

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

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:destroy

Destroys the fixture

Fixture:destroy()

Fixture:getBody

Returns the body to which the fixture is attached.

body = Fixture:getBody()

bodyBodyThe parent body.

Fixture:getBoundingBox

Returns the points of the fixture bounding box. In case the fixture has multiple childern a 1-based index can be specified.

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)numberThe fixture child to get the bounding box of.

Fixture:getCategory

Returns the categories the fixture belongs to.

category1, category2, ... = Fixture:getCategory()

category1numberThe first category.
category2numberThe second category.
...numberAdditional categories.

Fixture:getDensity

Returns the density of the fixture.

density = Fixture:getDensity()

densitynumberThe fixture density in kilograms per square meter.

Fixture:getFilterData

Returns 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

Returns the friction of the fixture.

friction = Fixture:getFriction()

frictionnumberThe fixture friction.

Fixture:getGroupIndex

Returns 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

Returns 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

Returns 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

Returns the restitution of the fixture.

restitution = Fixture:getRestitution()

restitutionnumberThe fixture restitution.

Fixture:getShape

Returns 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

Returns the Lua value associated with this fixture.

Use this function in one thread only.

value = Fixture:getUserData()

valuemixedThe Lua value associated with the fixture.

Fixture:isSensor

Returns 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. Is the group 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 others 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 )

valuemixedThe 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: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: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: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: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

Returns 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 an string representing the type.

type = Joint:getType()

typeJointTypeA string with the name of the Joint type.

Joint:setCollideConnected

Sets whether the connected Bodies should collide with eachother.

Joint:setCollideConnected( collide )

collidebooleanTrue for the Bodies to collide, false otherwise.

MouseJoint:getDampingRatio

Returns the damping ratio.

ratio = MouseJoint:getDampingRatio()

rationumberThe new damping ratio.

MouseJoint:getFrequency

Returns 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: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:setLimitsEnabled

Enables or disables the limits of the joint.

PrismaticJoint:setLimitsEnabled( enable )

enablebooleanTrue to enable, false to disable.

PrismaticJoint:setMotorEnabled

Starts or stops the joint motor.

PrismaticJoint:setMotorEnabled( enable )

enablebooleanTrue to enable, false to disable.

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: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: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: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: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:getMaxLength

Gets the maximum length of a RopeJoint.

maxLength = RopeJoint:getMaxLength()

maxLengthnumberThe maximum length of the RopeJoint.

Shape:computeAABB

Returns 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:destroy

Explicitly destroys the Shape. 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. Note that Box2D doesn't allow destroying or creating shapes during collision callbacks.

Shape:destroy()

Shape:getBody

Get the Body the shape is attached to.

body = Shape:getBody()

bodyBodyThe body the shape is attached to.

Shape:getBoundingBox

Gets the bounding box of the shape. This function can be used in a nested fashion with love.graphics.polygon.

A bounding box is the smallest rectangle that encapsulates the entire polygon.

Vertexes are returned starting from the bottom-left in a clockwise fashion (bottom-left, top-left, top-right, bottom-right).

x1, y1, x2, y2, x3, y3, x4, y4 = Shape:getBoundingBox()

x1numberThe x component of the first vertex, bottom-left.
y1numberThe y component of the first vertex, bottom-left.
x2numberThe x component of the second vertex, top-left.
y2numberThe y component of the second vertex, top-left.
x3numberThe x component of the third vertex, top-right.
y3numberThe y component of the third vertex, top-right.
x4numberThe x component of the fourth vertex, bottom-right.
y4numberThe y component of the fourth vertex, bottom-right.

Shape:getChildCount

Returns the number of children the shape has.

count = Shape:getChildCount()

countnumberThe number of children.

Shape:getData

Get the data set with setData.

v = Shape:getData()

vanyThe data previously set, or nil if none.

Shape:getDensity

Gets the density of the Shape.

density = Shape:getDensity()

densitynumberThe density of the Shape.

Shape:getFilterData

Gets the filter data of the Shape.

categoryBits, maskBits, groupIndex = Shape:getFilterData()

categoryBitsnumberA 16-bit integer representing category membership.
maskBitsnumberA 16-bit integer representing masked categories.
groupIndexnumberAn integer representing the group index.

Shape:getFriction

Gets the friction of this shape.

friction = Shape:getFriction()

frictionnumberThe friction 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:setData

Set data to be passed to the collision callback.

When a shape collides, the value set here will be passed to the collision callback as one of the parameters. Typically, you would want to store a table reference here, but any value can be used.

Shape:setData( v )

vanyAny Lua value.

Shape:setDensity

Sets the density of a Shape. Do this before calling Body:setMassFromShapes.

Shape:setDensity( density )

densitynumberThe new density of the Shape.

Shape:setFilterData

Sets the filter data for a Shape.

Collision filtering is a system for preventing collision between shapes. For example, say you make a character that rides a bicycle. You want the bicycle to collide with the terrain and the character to collide with the terrain, but you don't want the character to collide with the bicycle (because they must overlap). Box2D supports such collision filtering using categories and groups.

Shape:setFilterData( categoryBits, maskBits, groupIndex )

categoryBitsnumberA 16-bit integer representing category membership.
maskBitsnumberA 16-bit integer representing masked categories.
groupIndexnumberAn integer representing the group index.

Shape:setFriction

Sets the friction of the shape. Friction determines how shapes react when they "slide" along other shapes. Low friction indicates a slippery surface, like ice, while high friction indicates a rough surface, like concrete. Range: 0.0 - 1.0.

Shape:setFriction( friction )

frictionnumberThe friction of the shape.

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.

Shape:testSegment

Checks whether a line segment intersects a shape. This function will either return the "time" of impact and the surface normal at the point of collision, or nil if the line does not intersect the shape. The "time" is a value between 0.0 and 1.0 and can be used to calculate where the collision occured.

t, xn, yn = Shape:testSegment( x1, y1, x2, y2 )

tnumberThe time of impact, or nil if no impact.
xnnumberThe x component of the surface normal.
ynnumberThe y component of the surface normal.
x1numberThe x component of the first endpoint.
y1numberThe y component of the first endpoint.
x2numberThe x component of the second endpoint.
y2numberThe y component of the second endpoint.

WeldJoint:getDampingRatio

Returns the damping ratio of the joint.

ratio = WeldJoint:getDampingRatio()

rationumberThe damping ratio.

WeldJoint:getFrequency

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

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:isSleepingAllowed

Returns the sleep behaviour of the world.

allowSleep = World:isSleepingAllowed()

allowSleepbooleanTrue if the bodies are allowed to sleep or false if not.

World:getBodyCount

Get the number of bodies in the world.

n = World:getBodyCount()

nnumberThe number of bodies in the world.

World:getBodyList

Returns a table with all bodies.

bodies = World:getBodyList()

bodiestableA sequence with all bodies.

World:getCallbacks

Returns 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

Returns the number of contacts in the world.

n = World:getContactCount()

nnumberThe number of contacts in the world.

World:getContactFilter

Returns the function for collision filtering.

contactFilter = World:getContactFilter()

contactFilterfunctionThe function that handles the contact filtering.

World:getContactList

Returns 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

Returns a table with all joints.

joints = World:getJointList()

jointstableA sequence with all joints.

World:isLocked

Returns 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: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 with the fixtures that intersect it. You cannot make any assumptions about the order of the callbacks.

Each time the function gets called, 6 arguments get passed to it. The first is the fixture intersecting the ray. The second and third are the coordinates of the intersection point. The fourth and fifth is the surface normal vector of the shape edge. The sixth argument is the position of the intersection on the ray as a number from 0 to 1 (or even higher if the ray length was changed with the return value).

The ray can be controlled with the return value. A positive value sets a new ray length where 1 is the default value. A value of 0 terminates the ray. If the callback function returns -1, the intersection gets ignored as if it didn't happen.

There is a bug in 0.8.0 where the normal vector passed to the callback function gets scaled by love.physics.getMeter.

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: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: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:setGravity

Set the gravity of the world.

World:setGravity( x, y )

xnumberThe x component of gravity.
ynumberThe y component of gravity.

World:update

Update the state of the world.

World:update( dt )

dtnumberThe time (in seconds) to advance the physics simulation.

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.

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.

love.sound

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

soundDataSoundDataA new SoundData object.
filenamestringThe filename of the file to load.

soundData = love.sound.newSoundData( file )

soundDataSoundDataA new SoundData object.
fileFileA File pointing to an audio file.

soundData = love.sound.newSoundData( data )

soundDataSoundDataA new SoundData object.
dataDataThe encoded data to decode into audio.

soundData = love.sound.newSoundData( samples, rate, bits, channels )

soundDataSoundDataA new SoundData object.
samplesnumberTotal number of samples.
rate (44100)numberNumber of samples per second
bits (16)numberBits per sample (8 or 16).
channels (2)numberEither 1 for mono or 2 for stereo.

SoundData:getBitDepth

Returns the number of bits per sample.

bits = SoundData:getBitDepth()

bitsnumberEither 8 or 16.

SoundData:getChannels

Returns the number of channels in the stream.

channels = SoundData:getChannels()

channelsnumber1 for mono, 2 for stereo.

SoundData:getDuration

Returns the number of channels in the stream.

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).
inumberThe position of the sample (0 means first sample).

SoundData:getSampleCount

Returns the sample count of the SoundData.

count = SoundData:getSampleCount()

countnumberTotal number of samples.

SoundData:getSampleRate

Returns 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

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

os_string = love.system.getOS()

os_stringstringThe current operating system. "OS X", "Windows", or "Linux".

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.

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

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 or Data object.

thread = love.thread.newThread( name, filename )

threadThreadA new Thread that has yet to be started.
namestringThe name of the thread.
filenamestringThe name of the File to use as source.

thread = love.thread.newThread( name, file )

threadThreadA new Thread that has yet to be started.
namestringThe name of the thread.
fileFileThe file to use as source.

thread = love.thread.newThread( name, data )

threadThreadA new Thread that has yet to be started.
namestringThe name of the thread.
dataDataThe data to use as source.

Thread:getError

Retrieves the error string from the thread if it produced a 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:wait

Wait for a thread to finish. This call will block until the thread finishes.

Thread:wait()

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.

The value of the message can be a boolean, string, number, LÖVE userdata, or a simple flat table. It waits until a message is in the queue then returns the message value.

value = Channel:demand()

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

The value of the message can be a boolean, string, number or a LÖVE userdata. It returns nil if there's no message in the queue.

value = Channel:peek()

valuevalueThe contents of the message.

Channel:pop

Retrieves the value of a Channel message and removes it from the message queue.

The value of the message can be a boolean, string, number, LÖVE userdata, or a simple flat table. It returns nil if there are no messages in the queue.

value = Channel:pop()

valuevalueThe contents of the message.

Channel:push

Send a message to the thread Channel.

The value of the message can be a boolean, string, number, LÖVE userdata, or a simple flat table. Foreign userdata (Lua's files, LuaSocket, ENet, ...), functions, and tables inside tables are not supported.

value = Channel:push()

valuevalueThe contents of the message.

Channel:supply

Send a message to the thread Channel and wait for a thread to accept it.

The value of the message can be a boolean, string, number, LÖVE userdata, or a simple flat table. Foreign userdata (Lua's files, LuaSocket, ENet, ...), functions, and tables inside tables are not supported.

value = Channel:supply()

valuevalueThe contents of the message.

love.timer

love.timer.getAverageDelta

Returns 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

Returns the time between the last two frames.

dt = love.timer.getDelta()

dtnumberThe time passed (in seconds).

love.timer.getFPS

Returns the current frames per second.

fps = love.timer.getFPS()

fpsnumberThe current FPS.

love.timer.getTime

Returns 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.window

love.window.getDimensions

Gets the width and height of the window.

width, height = love.window.getDimensions()

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

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

Gets the height of the window.

height = love.window.getHeight()

heightnumberThe height of the window.

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

Returns the current display mode.

width, height, fullscreen, vsync, fsaa = love.window.getMode()

widthnumberDisplay width.
heightnumberDisplay height.
fullscreenbooleanFullscreen (true) or windowed (false).
vsyncbooleanTrue if vertical sync is enabled or false if disabled.
fsaanumberThe number of FSAA samples.

love.window.getPixelScale

Gets the scale factor associated with the window. In Mac OS X with the window in a retina screen and the highdpi window flag enabled this will be 2.0, otherwise it will be 1.0.

The scale factor is used to display graphics at a size the user is expecting, rather than the size of the pixels. On retina displays with the highdpi window flag enabled, the pixels in the window are 2x smaller than the scale of the normal content on the screen, so love.window.getPixelScale will return 2.

The units of love.graphics.getWidth, love.graphics.getHeight, love.mouse.getPosition, and mouse events are always in terms of pixels.

scale = love.window.getPixelScale()

scalenumberThe pixel scale factor associated with the window.

love.window.getWidth

Gets the width of the window.

width = love.window.getWidth()

widthnumberThe width of the window.

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

Checks if the window has been created.

created = love.window.isCreated()

createdbooleanTrue if the window has been created, 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.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

Changes the display mode.

If width or height is 0, the width or height of the desktop will be used.

success = love.window.setMode( width, height, flags )

successbooleanTrue if successful, false otherwise.
width (Screen width.)numberDisplay width.
height (Screen height.)numberDisplay height.
flagstableThe flags table.
flags.fullscreen (false)booleanFullscreen (true), or windowed (false).
flags.fullscreentype ("normal")FullscreenTypeThe type of fullscreen to use.
flags.vsync (true)booleanTrue if LÖVE should wait for vsync, false otherwise.
flags.fsaa (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.srgb (false)booleanTrue if sRGB gamma correction should be applied when drawing to the screen.

love.window.setTitle

Sets the window title.

love.window.setTitle( title )

titlestringThe new window title.

FullscreenType

normal

Standard fullscreen mode. Changes the display mode (actual resolution) of the monitor.

desktop

Sometimes known as borderless fullscreen windowed mode. A borderless screen-sized window is created which sits on top of all desktop GUI elements (such as the Windows taskbar and the Mac OS X dock.) The window is automatically resized to match the dimensions of the desktop, and its size cannot be changed.