LÖVE 11.4 Reference

The newly connected Joystick object.

love.joystickaxis

Called when a joystick axis moves.

love.joystickaxis( joystick, axis, value )

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

love.joystickhat

Called when a joystick hat direction changes.

love.joystickhat( joystick, hat, direction )

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

love.joystickpressed

Called when a joystick button is pressed.

love.joystickpressed( joystick, button )

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

love.joystickreleased

Called when a joystick button is released.

love.joystickreleased( joystick, button )

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

love.joystickremoved

Called when a Joystick is disconnected.

love.joystickremoved( joystick )

joystick

The now-disconnected Joystick object.

love.keypressed

Callback function triggered when a key is pressed.

love.keypressed( key, scancode, isrepeat )

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

love.keypressed( key, isrepeat )

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

Callback function triggered when a key is pressed.

love.keypressed( key, scancode, isrepeat )

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

love.keypressed( key, isrepeat )

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

love.keyreleased

Callback function triggered when a keyboard key is released.

love.keyreleased( key, scancode )

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

love.load

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

love.load( arg, unfilteredArg )

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

love.lowmemory

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

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

love.lowmemory()

love.mousefocus

Callback function triggered when window receives or loses mouse focus.

love.mousefocus( focus )

focus

boolean

Whether the window has mouse focus or not.

love.mousemoved

Callback function triggered when the mouse is moved.

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

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

love.mousepressed

Callback function triggered when a mouse button is pressed.

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

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

love.mousereleased

Callback function triggered when a mouse button is released.

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

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

love.quit

Callback function triggered when the game is closed.

r = love.quit()

boolean

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

love.resize

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

love.resize( w, h )

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

love.run

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

mainLoop = love.run()

mainLoop

function

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

love.textedited

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

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

love.textedited( text, start, length )

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

love.textinput

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

love.textinput( text )

text

string

The UTF-8 encoded unicode text.

love.threaderror

Callback function triggered when a Thread encounters an error.

love.threaderror( thread, errorstr )

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

love.touchmoved

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

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

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

love.touchpressed

Callback function triggered when the touch screen is touched.

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

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

love.touchreleased

Callback function triggered when the touch screen stops being touched.

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

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

love.update

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

love.update( dt )

number

Time since the last update in seconds.

love.visible

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

love.visible( visible )

visible

boolean

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

love.wheelmoved

Callback function triggered when the mouse wheel is moved.

love.wheelmoved( x, y )

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

The superclass of all data.

Functions

Supertypes

Creates a new copy of the Data object.

clone = Data:clone()

clone

Data

The new copy.

Data:getFFIPointer

Gets an FFI pointer to the Data.

This function should be preferred instead of Data:getPointer because the latter uses light userdata which can't store more all possible memory addresses on some new ARM64 architectures, when LuaJIT is used.

pointer = Data:getFFIPointer()

pointer

cdata

A raw void* pointer to the Data, or nil if FFI is unavailable.

Data:getPointer

Gets a pointer to the Data. Can be used with libraries such as LuaJIT's FFI.

pointer = Data:getPointer()

pointer

light userdata

A raw pointer to the Data.

Data:getSize

Gets the Data's size in bytes.

size = Data:getSize()

size

number

The size of the Data in bytes.

Data:getString

Gets the full Data as a string.

data = Data:getString()

data

string

The raw data.

The superclass of all LÖVE types.

Functions

Destroys the object's Lua reference. The object will be completely deleted if it's not referenced by any other LÖVE object or thread.

This method can be used to immediately clean up resources without waiting for Lua's garbage collector.

success = Object:release()

success

boolean

True if the object was released by this call, false if it had been previously released.

Object:type

Gets the type of the object as a string.

type = Object:type()

type

string

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

boolean

True if the object is of the specified type, false otherwise.

name

string

The name of the type to check for.

love.audio

Types

RecordingDevice

love.audio.getActiveEffects

Functions

love.audio.getActiveEffects

love.audio.getActiveSourceCount

love.audio.get/setDistanceModel

love.audio.get/setDopplerScale

love.audio.get/setEffect

love.audio.getMaxSceneEffects

love.audio.getMaxSourceEffects

love.audio.get/setOrientation

love.audio.get/setPosition

love.audio.getRecordingDevices

love.audio.getSourceCount

love.audio.get/setVelocity

love.audio.get/setVolume

love.audio.isEffectsSupported

love.audio.newQueueableSource

love.audio.pause

love.audio.play

love.audio.setMixWithSystem

love.audio.stop

Enums

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

effects = love.audio.getActiveEffects()

effects

table

The list of the names of the currently enabled effects.

love.audio.getActiveSourceCount

Gets the current number of simultaneously playing sources.

count = love.audio.getActiveSourceCount()

count

number

The current number of simultaneously playing sources.

love.audio.getDistanceModel

Returns the distance attenuation model.

model = love.audio.getDistanceModel()

model

DistanceModel

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

love.audio.getDopplerScale

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

scale = love.audio.getDopplerScale()

scale

number

The current doppler scale factor.

love.audio.getEffect

Gets the settings associated with an effect.

settings = love.audio.getEffect( name )

settings

table

The settings associated with the effect.

name

string

The name of the effect.

love.audio.getMaxSceneEffects

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

maximum = love.audio.getMaxSceneEffects()

maximum

number

The maximum number of active effects.

love.audio.getMaxSourceEffects

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

maximum = love.audio.getMaxSourceEffects()

maximum

number

The maximum number of active Effects per Source.

love.audio.getOrientation

Returns the orientation of the listener.

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

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

love.audio.getPosition

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

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

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

love.audio.getRecordingDevices

Gets a list of RecordingDevices on the system.

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

Audio recording is currently not supported on iOS.

devices = love.audio.getRecordingDevices()

devices

table

The list of connected recording devices.

love.audio.getSourceCount

Gets the current number of simultaneously playing sources.

numSources = love.audio.getSourceCount()

numSources

number

The current number of simultaneously playing sources.

love.audio.getVelocity

Returns the velocity of the listener.

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

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

love.audio.getVolume

Returns the master volume.

volume = love.audio.getVolume()

volume

number

The current master volume

love.audio.isEffectsSupported

Gets whether audio effects are supported in the system.

supported = love.audio.isEffectsSupported()

supported

boolean

True if effects are supported, false otherwise.

love.audio.newQueueableSource

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

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

source

The new Source usable with Source:queue.

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

love.audio.newSource

Creates a new Source from a filepath, File, Decoder or SoundData.

Sources created from SoundData are always static.

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

source

A new Source that can play the specified audio.

filename	string	The filepath to the audio file.
type	SourceType	Streaming or static source.

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

source

A new Source that can play the specified audio.

file	File	A File pointing to an audio file.
type	SourceType	Streaming or static source.

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

source

A new Source that can play the specified audio.

decoder	Decoder	The Decoder to create a Source from.
type	SourceType	Streaming or static source.

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

source

A new Source that can play the specified audio.

data	FileData	The FileData to create a Source from.
type	SourceType	Streaming or static source.

source = love.audio.newSource( data )

source

A new Source that can play the specified audio. The SourceType of the returned audio is 'static'.

data

The SoundData to create a Source from.

love.audio.pause

Pauses specific or all currently played Sources.

Sources = love.audio.pause()

Sources

table

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

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

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

love.audio.pause( sources )

sources

table

A table containing a list of Sources to pause.

love.audio.play

Plays the specified Source.

love.audio.play( source )

source

love.audio.setDistanceModel

The Source to play.

love.audio.play( sources )

sources

table

Table containing a list of Sources to play.

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

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

Sets the distance attenuation model.

love.audio.setDistanceModel( model )

model

DistanceModel

The new distance model.

love.audio.setDopplerScale

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

love.audio.setDopplerScale( scale )

scale

number

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

love.audio.setEffect

Defines an effect that can be applied to a Source.

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

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

success

boolean

Whether the effect was successfully created.

name	string	The name of the effect.
settings	table	The settings to use for this effect, with the following fields:

settings.type	EffectType	The type of effect to use.
settings.volume	number	The volume of the effect.
settings....	number	Effect-specific settings. See EffectType for available effects and their corresponding settings.

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

success

boolean

Whether the effect was successfully disabled.

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

love.audio.setMixWithSystem

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

success = love.audio.setMixWithSystem( mix )

success

boolean

True if the change succeeded, false otherwise.

mix

boolean

True to enable mixing, false to disable it.

love.audio.setOrientation

Sets the orientation of the listener.

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

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

love.audio.setPosition

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

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

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

love.audio.setVelocity

Sets the velocity of the listener.

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

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

love.audio.setVolume

Sets the master volume.

love.audio.setVolume( volume )

volume

number

1.0 is max and 0.0 is off.

love.audio.stop

Stops currently played sources.

love.audio.stop()

love.audio.stop( source )

source

The source on which to stop the playback.

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

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

love.audio.stop( sources )

sources

table

A table containing a list of Sources to stop.

RecordingDevice

Represents an audio input device capable of recording sounds.

Functions

RecordingDevice:getBitDepth

RecordingDevice:getChannelCount

RecordingDevice:getData

RecordingDevice:getName

RecordingDevice:getSampleCount

RecordingDevice:getSampleRate

RecordingDevice:isRecording

RecordingDevice:start

RecordingDevice:stop

Supertypes

RecordingDevice:getBitDepth

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

bits = RecordingDevice:getBitDepth()

bits

number

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

RecordingDevice:getChannelCount

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

channels = RecordingDevice:getChannelCount()

channels

number

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

RecordingDevice:getData

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

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

data = RecordingDevice:getData()

data

RecordingDevice:getSampleCount

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

RecordingDevice:getName

Gets the name of the recording device.

name = RecordingDevice:getName()

name

string

The name of the device.

Gets the number of currently recorded samples.

samples = RecordingDevice:getSampleCount()

samples

number

The number of samples that have been recorded so far.

RecordingDevice:getSampleRate

Gets the number of samples per second currently being recorded.

rate = RecordingDevice:getSampleRate()

rate

number

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

RecordingDevice:isRecording

Gets whether the device is currently recording.

recording = RecordingDevice:isRecording()

recording

boolean

True if the recording, false otherwise.

RecordingDevice:start

Begins recording audio using this device.

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

success

boolean

True if the device successfully began recording using the specified parameters, false if not.

samplecount	number	The maximum number of samples to store in an internal ring buffer when recording. RecordingDevice:getData clears the internal buffer when called.
samplerate (8000)	number	The number of samples per second to store when recording.
bitdepth (16)	number	The number of bits per sample.
channels (1)	number	Whether to record in mono or stereo. Most microphones don't support more than 1 channel.

RecordingDevice:stop

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

data = RecordingDevice:stop()

data

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

A Source represents audio you can play back.

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

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

Constructors

love.audio.newQueueableSource

love.audio.newSource

Functions

Source:clone

Source:getActiveEffects

Source:get/setAirAbsorption

Source:get/setAttenuationDistances

Source:getChannelCount

Source:get/setCone

Source:get/setDirection

Source:getDuration

Source:get/setEffect

Source:get/setFilter

Source:getFreeBufferCount

Source:get/setPitch

Source:get/setPosition

Source:get/setRolloff

Source:getType

Source:get/setVelocity

Source:get/setVolume

Source:get/setVolumeLimits

Source:is/setLooping

Source:isPlaying

Source:is/setRelative

Source:pause

Source:play

Source:queue

Source:stop

Source:tell/seek

Supertypes

Source:clone

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

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

source = Source:clone()

source

Source:getAttenuationDistances

The new identical copy of this Source.

Source:getActiveEffects

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

effects = Source:getActiveEffects()

effects

table

A list of the source's active effect names.

Source:getAirAbsorption

Gets the amount of air absorption applied to the Source.

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

amount = Source:getAirAbsorption()

amount

number

The amount of air absorption applied to the Source.

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

ref, max = Source:getAttenuationDistances()

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

Source:getChannelCount

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

channels = Source:getChannelCount()

channels

number

1 for mono, 2 for stereo.

Source:getCone

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

innerAngle, outerAngle, outerVolume = Source:getCone()

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

Source:getDirection

Gets the direction of the Source.

x, y, z = Source:getDirection()

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

Source:getDuration

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

duration = Source:getDuration( unit )

duration

number

The duration of the Source, or -1 if it cannot be determined.

unit ('seconds')

TimeUnit

The time unit for the return value.

Source:getEffect

Gets the filter settings associated to a specific effect.

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

filtersettings = Source:getEffect( name, filtersettings )

filtersettings

table

The settings for the filter associated to this effect, or nil if the effect is not present in this Source or has no filter associated. The table has the following fields:

filtersettings.volume	number	The overall volume of the audio.
filtersettings.highgain	number	Volume of high-frequency audio. Only applies to low-pass and band-pass filters.
filtersettings.lowgain	number	Volume of low-frequency audio. Only applies to high-pass and band-pass filters.

name	string	The name of the effect.
filtersettings ({})	table	An optional empty table that will be filled with the filter settings.

Source:getFilter

Gets the filter settings currently applied to the Source.

settings = Source:getFilter()

settings

table

The filter settings to use for this Source, or nil if the Source has no active filter. The table has the following fields:

settings.type	FilterType	The type of filter to use.
settings.volume	number	The overall volume of the audio.
settings.highgain	number	Volume of high-frequency audio. Only applies to low-pass and band-pass filters.
settings.lowgain	number	Volume of low-frequency audio. Only applies to high-pass and band-pass filters.

Source:getFreeBufferCount

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

buffers = Source:getFreeBufferCount()

buffers

number

How many more SoundData objects can be queued up.

Source:getPitch

Gets the current pitch of the Source.

pitch = Source:getPitch()

pitch

number

The pitch, where 1.0 is normal.

Source:getPosition

Gets the position of the Source.

x, y, z = Source:getPosition()

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

Source:getRolloff

Returns the rolloff factor of the source.

rolloff = Source:getRolloff()

rolloff

number

The rolloff factor.

Source:getType

Gets the type of the Source.

sourcetype = Source:getType()

sourcetype

SourceType

The type of the source.

Source:getVelocity

Gets the velocity of the Source.

x, y, z = Source:getVelocity()

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

Source:getVolume

Gets the current volume of the Source.

volume = Source:getVolume()

volume

number

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

Source:getVolumeLimits

Returns the volume limits of the source.

min, max = Source:getVolumeLimits()

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

Source:isLooping

Returns whether the Source will loop.

loop = Source:isLooping()

loop

boolean

True if the Source will loop, false otherwise.

Source:isPlaying

Returns whether the Source is playing.

playing = Source:isPlaying()

playing

boolean

True if the Source is playing, false otherwise.

Source:isRelative

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

relative = Source:isRelative()

relative

boolean

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

Source:pause

Pauses the Source.

Source:pause()

Source:play

Starts playing the Source.

success = Source:play()

success

boolean

Whether the Source was able to successfully start playing.

Source:queue

Queues SoundData for playback in a queueable Source.

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

success = Source:queue( sounddata )

success

boolean

True if the data was successfully queued for playback, false if there were no available buffers to use for queueing.

sounddata

Source:setAttenuationDistances

The data to queue. The SoundData's sample rate, bit depth, and channel count must match the Source's.

Source:seek

Sets the currently playing position of the Source.

Source:seek( offset, unit )

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

Source:setAirAbsorption

Sets the amount of air absorption applied to the Source.

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

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

Source:setAirAbsorption( amount )

amount

number

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

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

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

Source:setAttenuationDistances( ref, max )

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

Source:setCone

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

Source:setCone( innerAngle, outerAngle, outerVolume )

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

Source:setDirection

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

Source:setDirection( x, y, z )

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

Source:setEffect

Applies an audio effect to the Source.

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

success = Source:setEffect( name, enable )

success

boolean

Whether the effect was successfully applied to this Source.

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

success = Source:setEffect( name, filtersettings )

success

boolean

Whether the effect and filter were successfully applied to this Source.

name	string	The name of the effect previously set up with love.audio.setEffect.
filtersettings	table	The filter settings to apply prior to the effect, with the following fields:

filtersettings.type	FilterType	The type of filter to use.
filtersettings.volume	number	The overall volume of the audio. Must be between 0 and 1.
filtersettings.highgain	number	Volume of high-frequency audio. Only applies to low-pass and band-pass filters. Must be between 0 and 1.
filtersettings.lowgain	number	Volume of low-frequency audio. Only applies to high-pass and band-pass filters. Must be between 0 and 1.

Source:setFilter

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

success = Source:setFilter( settings )

success

boolean

Whether the filter was successfully applied to the Source.

settings

table

The filter settings to use for this Source, with the following fields:

settings.type	FilterType	The type of filter to use.
settings.volume	number	The overall volume of the audio. Must be between 0 and 1.
settings.highgain	number	Volume of high-frequency audio. Only applies to low-pass and band-pass filters. Must be between 0 and 1.
settings.lowgain	number	Volume of low-frequency audio. Only applies to high-pass and band-pass filters. Must be between 0 and 1.

Source:setFilter()

Source:setLooping

Sets whether the Source should loop.

Source:setLooping( loop )

loop

boolean

True if the source should loop, false otherwise.

Source:setPitch

Sets the pitch of the Source.

Source:setPitch( pitch )

pitch

number

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

Source:setPosition

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

Source:setPosition( x, y, z )

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

Source:setRelative

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

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

Source:setRelative( enable )

enable (false)

boolean

True to make the position, velocity, direction and cone angles relative to the listener, false to make them absolute.

Source:setRolloff

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

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

Source:setRolloff( rolloff )

rolloff

number

The new rolloff factor.

Source:setVelocity

Sets the velocity of the Source.

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

Source:setVelocity( x, y, z )

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

Source:setVolume

Sets the current volume of the Source.

Source:setVolume( volume )

volume

number

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

Source:setVolumeLimits

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

Source:setVolumeLimits( min, max )

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

Source:stop

Stops a Source.

Source:stop()

Source:tell

Gets the currently playing position of the Source.

position = Source:tell( unit )

position

number

The currently playing position of the Source.

unit ('seconds')

TimeUnit

The type of unit for the return value.

DistanceModel

none

Sources do not get attenuated.

inverse

Inverse distance attenuation.

inverseclamped

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

linear

Linear attenuation.

linearclamped

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

exponent

Exponential attenuation.

exponentclamped

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

EffectType

chorus

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

compressor

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

distortion

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

echo

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

equalizer

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

flanger

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

reverb

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

ringmodulator

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

EffectWaveform

sawtooth

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

sine

A sine wave. Follows a trigonometric sine function.

square

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

triangle

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

FilterType

lowpass

Low-pass filter. High frequency sounds are attenuated.

highpass

High-pass filter. Low frequency sounds are attenuated.

bandpass

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

SourceType

static

The whole audio is decoded.

stream

The audio is decoded in chunks when needed.

queue

The audio must be manually queued by the user.

TimeUnit

seconds

Regular seconds.

samples

Audio samples.

love.data

Types

Functions

love.data.compress

love.data.decode

love.data.decompress

love.data.encode

love.data.getPackedSize

love.data.hash

love.data.newDataView

love.data.pack

love.data.unpack

Enums

Compresses a string or data using a specific compression algorithm.

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

compressedData

CompressedData or string

CompressedData/string which contains the compressed version of rawstring.

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

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

compressedData

CompressedData or string

CompressedData/string which contains the compressed version of data.

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

love.data.decode

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

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

decoded

ByteData or string

ByteData/string which contains the decoded version of source.

container	ContainerType	What type to return the decoded data as.
format	EncodeFormat	The format of the input data.
sourceString	string	The raw (encoded) data to decode.

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

decoded

ByteData or string

ByteData/string which contains the decoded version of source.

container	ContainerType	What type to return the decoded data as.
format	EncodeFormat	The format of the input data.
sourceData	Data	The raw (encoded) data to decode.

love.data.decompress

Decompresses a CompressedData or previously compressed string or Data object.

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

decompressedData

Data or string

Data/string containing the raw decompressed data.

container	ContainerType	What type to return the decompressed data as.
compressedData	CompressedData	The compressed data to decompress.

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

decompressedData

Data or string

Data/string containing the raw decompressed data.

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

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

decompressedData

Data or string

Data/string containing the raw decompressed data.

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

love.data.encode

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

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

encoded

ByteData or string

ByteData/string which contains the encoded version of source.

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

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

encoded

ByteData or string

ByteData/string which contains the encoded version of source.

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

love.data.getPackedSize

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

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

size = love.data.getPackedSize( format )

size

number

The size in bytes that the packed data will use.

format

string

A string determining how the values are packed. Follows the rules of Lua 5.3's string.pack format strings.

love.data.hash

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

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

rawdigest

string

Raw message digest string.

hashFunction	HashFunction	Hash algorithm to use.
string	string	String to hash.

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

rawdigest

string

Raw message digest string.

hashFunction	HashFunction	Hash algorithm to use.
data	Data	Data to hash.

love.data.newByteData

Creates a new Data object containing arbitrary bytes.

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

bytedata = love.data.newByteData( datastring )

bytedata

The new Data object.

datastring

string

The byte string to copy.

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

bytedata

The new Data object.

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

bytedata = love.data.newByteData( size )

bytedata

The new Data object.

size

number

The size in bytes of the new Data object.

love.data.newDataView

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

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

view

Data

The new Data view.

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

love.data.pack

Packs (serializes) simple Lua values.

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

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

data

Data or string

Data/string which contains the serialized data.

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

love.data.unpack

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

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

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

v1	number or boolean or string	The first value (number, boolean, or string) that was unpacked.
...	number or boolean or string	Additional unpacked values.
index	number	The index of the first unread byte in the data string.

format	string	A string determining how the values were packed. Follows the rules of Lua 5.3's string.pack format strings.
datastring	string	A string containing the packed (serialized) data.
pos (1)	number	Where to start reading in the string. Negative values can be used to read relative from the end of the string.

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

v1	number or boolean or string	The first value (number, boolean, or string) that was unpacked.
...	number or boolean or string	Additional unpacked values.
index	number	The 1-based index of the first unread byte in the Data.

format	string	A string determining how the values were packed. Follows the rules of Lua 5.3's string.pack format strings.
data	Data	A Data object containing the packed (serialized) data.
pos (1)	number	1-based index indicating where to start reading in the Data. Negative values can be used to read relative from the end of the Data object.

Data object containing arbitrary bytes in an contiguous memory.

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

Constructors

love.data.newByteData

Functions

Supertypes

Represents byte data compressed using a specific algorithm.

love.data.decompress can be used to de-compress the data (or love.math.decompress in 0.10.2 or earlier).

Constructors

love.data.compress

Functions

CompressedData:getFormat

Supertypes

love.filesystem.areSymlinksEnabled

CompressedData:getFormat

Gets the compression format of the CompressedData.

format = CompressedData:getFormat()

format

CompressedDataFormat

The format of the CompressedData.

CompressedDataFormat

lz4

The LZ4 compression format. Compresses and decompresses very quickly, but the compression ratio is not the best. LZ4-HC is used when compression level 9 is specified. Some benchmarks are available here.

zlib

The zlib format is DEFLATE-compressed data with a small bit of header data. Compresses relatively slowly and decompresses moderately quickly, and has a decent compression ratio.

gzip

The gzip format is DEFLATE-compressed data with a slightly larger header than zlib. Since it uses DEFLATE it has the same compression characteristics as the zlib format.

deflate

Raw DEFLATE-compressed data (no header).

ContainerType

data

Return type is ByteData.

string

Return type is string.

EncodeFormat

base64

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

hex

Encode/decode data as hexadecimal string.

HashFunction

md5

MD5 hash algorithm (16 bytes).

sha1

SHA1 hash algorithm (20 bytes).

sha224

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

sha256

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

sha384

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

sha512

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

love.event

Functions

love.event.clear

love.event.poll

love.event.pump

love.event.push

love.event.quit

love.event.wait

Enums

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

function

Iterator function usable in a for loop.

love.event.pump

Pump events into the event queue.

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

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

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

love.event.pump()

love.event.push

Adds an event to the event queue.

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

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

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

love.event.quit

Adds the quit event to the queue.

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

love.event.quit( exitstatus )

exitstatus (0)

number

The program exit status to use when closing the application.

love.event.quit( 'restart' )

'restart'

string

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

love.event.wait

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

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

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

Event

focus

Window focus gained or lost

joystickpressed

Joystick pressed

joystickreleased

Joystick released

keypressed

Key pressed

keyreleased

Key released

mousepressed

Mouse pressed

mousereleased

Mouse released

quit

Quit

resize

Window size changed by the user

visible

Window is minimized or un-minimized by the user

mousefocus

Window mouse focus gained or lost

threaderror

A Lua error has occurred in a thread

joystickadded

Joystick connected

joystickremoved

Joystick disconnected

joystickaxis

Joystick axis motion

joystickhat

Joystick hat pressed

gamepadpressed

Joystick's virtual gamepad button pressed

gamepadreleased

Joystick's virtual gamepad button released

gamepadaxis

Joystick's virtual gamepad axis moved

textinput

User entered text

mousemoved

Mouse position changed

lowmemory

Running out of memory on mobile devices system

textedited

Candidate text for an IME changed

wheelmoved

Mouse wheel moved

touchpressed

Touch screen touched

touchreleased

Touch screen stop touching

touchmoved

Touch press moved inside touch screen

directorydropped

Directory is dragged and dropped onto the window

filedropped

File is dragged and dropped onto the window.

Joystick pressed

Joystick released

Key pressed

Key released

Mouse pressed

Mouse released

Quit

Window focus gained or lost

Types

Functions

love.filesystem.get/setCRequirePath

love.filesystem.getInfo

love.filesystem.get/setRequirePath

love.filesystem.getSource

love.filesystem.are/setSymlinksEnabled

love.filesystem.isFused

love.filesystem.createDirectory

love.filesystem.getDirectoryItems

love.filesystem.get/setIdentity

love.filesystem.load

love.filesystem.mount

love.filesystem.unmount

Directory paths

love.filesystem.getAppdataDirectory

love.filesystem.getRealDirectory

love.filesystem.getSaveDirectory

love.filesystem.getSourceBaseDirectory

love.filesystem.getUserDirectory

love.filesystem.getWorkingDirectory

File properties

File operations

love.filesystem.read

love.filesystem.lines

love.filesystem.write

love.filesystem.append

love.filesystem.remove

Enums

love.filesystem.append

Append data to an existing file.

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

success	boolean	True if the operation was successful, or nil if there was an error.
errormsg	string	The error message on failure.

name	string	The name (and path) of the file.
data	string	The string data to append to the file.
size (all)	number	How many bytes to write.

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

success	boolean	True if the operation was successful, or nil if there was an error.
errormsg	string	The error message on failure.

name	string	The name (and path) of the file.
data	Data	The Data object to append to the file.
size (all)	number	How many bytes to write.

Gets whether love.filesystem follows symbolic links.

enable = love.filesystem.areSymlinksEnabled()

enable

boolean

Whether love.filesystem follows symbolic links.

love.filesystem.createDirectory

Recursively creates a directory.

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

success = love.filesystem.createDirectory( name )

success

boolean

True if the directory was created, false if not.

name

string

The directory to create.

love.filesystem.getAppdataDirectory

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

path = love.filesystem.getAppdataDirectory()

path

string

The path of the application data directory

love.filesystem.getCRequirePath

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

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

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

paths = love.filesystem.getCRequirePath()

paths

string

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

love.filesystem.getDirectoryItems

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

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

files = love.filesystem.getDirectoryItems( dir )

files

table

A sequence with the names of all files and subdirectories as strings.

dir

string

The directory.

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

files

table

A sequence with the names of all files and subdirectories as strings.

dir	string	The directory.
callback	function	A function which is called for each file and folder in the directory. The filename is passed to the function as an argument.

love.filesystem.getIdentity

Gets the write directory name for your game.

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

name = love.filesystem.getIdentity()

name

string

The identity that is used as write directory.

love.filesystem.getInfo

Gets information about the specified file or directory.

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

info

table

A table containing information about the specified path, or nil if nothing exists at the path. The table contains the following fields:

info.type	FileType	The type of the object at the path (file, directory, symlink, etc.)
info.size	number	The size in bytes of the file, or nil if it can't be determined.
info.modtime	number	The file's last modification time in seconds since the unix epoch, or nil if it can't be determined.

path	string	The file or directory path to check.
filtertype (nil)	FileType	If supplied, this parameter causes getInfo to only return the info table if the item at the given path matches the specified file type.

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

info

table

The table given as an argument, or nil if nothing exists at the path. The table will be filled in with the following fields:

info.type	FileType	The type of the object at the path (file, directory, symlink, etc.)
info.size	number	The size in bytes of the file, or nil if it can't be determined.
info.modtime	number	The file's last modification time in seconds since the unix epoch, or nil if it can't be determined.

path	string	The file or directory path to check.
info	table	A table which will be filled in with info about the specified path.

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

info

table

The table given as an argument, or nil if nothing exists at the path. The table will be filled in with the following fields:

info.type	FileType	The type of the object at the path (file, directory, symlink, etc.)
info.size	number	The size in bytes of the file, or nil if it can't be determined.
info.modtime	number	The file's last modification time in seconds since the unix epoch, or nil if it can't be determined.

path	string	The file or directory path to check.
filtertype	FileType	Causes getInfo to only return the info table if the item at the given path matches the specified file type.
info	table	A table which will be filled in with info about the specified path.

love.filesystem.getRealDirectory

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

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

realdir = love.filesystem.getRealDirectory( filepath )

realdir

string

The platform-specific full path of the directory containing the filepath.

filepath

string

The filepath to get the directory of.

love.filesystem.getRequirePath

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

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

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

paths = love.filesystem.getRequirePath()

paths

string

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

love.filesystem.getSaveDirectory

Gets the full path to the designated save directory.

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

read or write in the save directory.

dir = love.filesystem.getSaveDirectory()

dir

string

The absolute path to the save directory.

love.filesystem.getSource

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

path = love.filesystem.getSource()

path

string

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

love.filesystem.getSourceBaseDirectory

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

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

path = love.filesystem.getSourceBaseDirectory()

path

string

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

love.filesystem.getUserDirectory

Returns the path of the user's directory

path = love.filesystem.getUserDirectory()

path

string

The path of the user's directory

love.filesystem.getWorkingDirectory

Gets the current working directory.

cwd = love.filesystem.getWorkingDirectory()

cwd

string

The current working directory.

love.filesystem.isFused

Gets whether the game is in fused mode or not.

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

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

fused = love.filesystem.isFused()

fused

boolean

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

love.filesystem.lines

Iterate over the lines in a file.

iterator = love.filesystem.lines( name )

iterator

function

A function that iterates over all the lines in the file

name

string

The name (and path) of the file

love.filesystem.load

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

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

chunk	function	The loaded chunk.
errormsg	string	The error message if file could not be opened.

name

string

The name (and path) of the file.

love.filesystem.mount

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

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

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

success

boolean

True if the archive was successfully mounted, false otherwise.

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

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

success

boolean

True if the archive was successfully mounted, false otherwise.

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

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

success

boolean

True if the archive was successfully mounted, false otherwise.

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

love.filesystem.newFile

Creates a new File object.

It needs to be opened before it can be accessed.

file = love.filesystem.newFile( filename )

file

File

The new File object.

filename

string

The filename of the file.

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

file	File	The new File object, or nil if an error occurred.
errorstr	string	The error string if an error occurred.

filename	string	The filename of the file.
mode	FileMode	The mode to open the file in.

love.filesystem.newFileData

Creates a new FileData object from a file on disk, or from a string in memory.

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

data

The new FileData.

contents	string	The contents of the file in memory represented as a string.
name	string	The name of the file. The extension may be parsed and used by LÖVE when passing the FileData object into love.audio.newSource.

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

data

love.filesystem.setCRequirePath

The new FileData.

originaldata	Data	The Data object to copy into the new FileData object.
name	string	The name of the file. The extension may be parsed and used by LÖVE when passing the FileData object into love.audio.newSource.

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

data	FileData	The new FileData, or nil if an error occurred.
err	string	The error string, if an error occurred.

filepath

string

Path to the file.

love.filesystem.read

Read the contents of a file.

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

contents	string	The file contents.
size	number	How many bytes have been read.
contents	nil	returns nil as content.
error	string	returns an error message.

name	string	The name (and path) of the file.
size (all)	number	How many bytes to read.

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

contents	FileData or string	FileData or string containing the file contents.
size	number	How many bytes have been read.
contents	nil	returns nil as content.
error	string	returns an error message.

container	ContainerType	What type to return the file's contents as.
name	string	The name (and path) of the file
size (all)	number	How many bytes to read

love.filesystem.remove

Removes a file or empty directory.

success = love.filesystem.remove( name )

success

boolean

True if the file/directory was removed, false otherwise.

name

string

The file or directory to remove.

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

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

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

love.filesystem.setCRequirePath( paths )

paths

string

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

love.filesystem.setIdentity

Sets the write directory for your game.

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

love.filesystem.setIdentity( name )

name

string

The new identity that will be used as write directory.

love.filesystem.setIdentity( name )

name

string

The new identity that will be used as write directory.

love.filesystem.setRequirePath

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

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

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

love.filesystem.setRequirePath( paths )

paths

string

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

love.filesystem.setSymlinksEnabled

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

love.filesystem.setSymlinksEnabled( enable )

enable

boolean

Whether love.filesystem should follow symbolic links.

love.filesystem.unmount

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

success = love.filesystem.unmount( archive )

success

boolean

True if the archive was successfully unmounted, false otherwise.

directory

Directory.

symlink

Symbolic link.

other

Something completely different like a device.

love.font

Types

love.font.newBMFontRasterizer

love.font.newBMFontRasterizer

love.font.newImageRasterizer

love.font.newTrueTypeRasterizer

Enums

HintingMode

Creates a new BMFont Rasterizer.

rasterizer = love.font.newBMFontRasterizer( imageData, glyphs, dpiscale )

rasterizer

The rasterizer.

imageData	ImageData	The image data containing the drawable pictures of font glyphs.
glyphs	string	The sequence of glyphs in the ImageData.
dpiscale (1)	number	DPI scale.

rasterizer = love.font.newBMFontRasterizer( fileName, glyphs, dpiscale )

rasterizer

love.font.newImageRasterizer

The rasterizer.

fileName	string	The path to file containing the drawable pictures of font glyphs.
glyphs	string	The sequence of glyphs in the ImageData.
dpiscale (1)	number	DPI scale.

love.font.newGlyphData

Creates a new GlyphData.

love.font.newGlyphData( rasterizer, glyph )

rasterizer	Rasterizer	The Rasterizer containing the font.
glyph	number	The character code of the glyph.

Creates a new Image Rasterizer.

rasterizer = love.font.newImageRasterizer( imageData, glyphs, extraSpacing, dpiscale )

rasterizer

The rasterizer.

imageData	ImageData	Font image data.
glyphs	string	String containing font glyphs.
extraSpacing (0)	number	Font extra spacing.
dpiscale (1)	number	Font DPI scale.

love.font.newRasterizer

Creates a new Rasterizer.

rasterizer = love.font.newRasterizer( filename )

rasterizer

The rasterizer.

filename

string

The font file.

rasterizer = love.font.newRasterizer( data )

rasterizer

The rasterizer.

data

The FileData of the font file.

rasterizer = love.font.newRasterizer( size, hinting, dpiscale )

rasterizer

The rasterizer.

size (12)	number	The font size.
hinting ('normal')	HintingMode	True Type hinting mode.
dpiscale (love.window.getDPIScale())	number	The font DPI scale.

rasterizer = love.font.newRasterizer( fileName, size, hinting, dpiscale )

rasterizer

The rasterizer.

fileName	string	Path to font file.
size (12)	number	The font size.
hinting ('normal')	HintingMode	True Type hinting mode.
dpiscale (love.window.getDPIScale())	number	The font DPI scale.

rasterizer = love.font.newRasterizer( fileData, size, hinting, dpiscale )

rasterizer

The rasterizer.

fileData	FileData	File data containing font.
size (12)	number	The font size.
hinting ('normal')	HintingMode	True Type hinting mode.
dpiscale (love.window.getDPIScale())	number	The font DPI scale.

rasterizer = love.font.newRasterizer( imageData, glyphs, dpiscale )

rasterizer

The rasterizer.

imageData	ImageData	The image data containing the drawable pictures of font glyphs.
glyphs	string	The sequence of glyphs in the ImageData.
dpiscale (1)	number	DPI scale.

rasterizer = love.font.newRasterizer( fileName, glyphs, dpiscale )

rasterizer

love.font.newTrueTypeRasterizer

The rasterizer.

fileName	string	The path to file containing the drawable pictures of font glyphs.
glyphs	string	The sequence of glyphs in the ImageData.
dpiscale (1)	number	DPI scale.

Creates a new TrueType Rasterizer.

rasterizer = love.font.newTrueTypeRasterizer( size, hinting, dpiscale )

rasterizer

The rasterizer.

size (12)	number	The font size.
hinting ('normal')	HintingMode	True Type hinting mode.
dpiscale (love.window.getDPIScale())	number	The font DPI scale.

rasterizer = love.font.newTrueTypeRasterizer( fileName, size, hinting, dpiscale )

rasterizer

The rasterizer.

fileName	string	Path to font file.
size (12)	number	The font size.
hinting ('normal')	HintingMode	True Type hinting mode.
dpiscale (love.window.getDPIScale())	number	The font DPI scale.

rasterizer = love.font.newTrueTypeRasterizer( fileData, size, hinting, dpiscale )

rasterizer

The rasterizer.

fileData	FileData	File data containing font.
size (12)	number	The font size.
hinting ('normal')	HintingMode	True Type hinting mode.
dpiscale (love.window.getDPIScale())	number	The font DPI scale.

A GlyphData represents a drawable symbol of a font Rasterizer.

Functions

GlyphData:getAdvance

GlyphData:getBearing

GlyphData:getBoundingBox

GlyphData:getDimensions

GlyphData:getFormat

GlyphData:getGlyph

GlyphData:getGlyphString

GlyphData:getHeight

GlyphData:getWidth

Supertypes

GlyphData:getAdvance

Gets glyph advance.

advance = GlyphData:getAdvance()

advance

number

Glyph advance.

GlyphData:getBearing

Gets glyph bearing.

bx, by = GlyphData:getBearing()

bx	number	Glyph bearing X.
by	number	Glyph bearing Y.

GlyphData:getBoundingBox

Gets glyph bounding box.

x, y, width, height = GlyphData:getBoundingBox()

x	number	Glyph position x.
y	number	Glyph position y.
width	number	Glyph width.
height	number	Glyph height.

GlyphData:getDimensions

Gets glyph dimensions.

width, height = GlyphData:getDimensions()

width	number	Glyph width.
height	number	Glyph height.

GlyphData:getFormat

Gets glyph pixel format.

format = GlyphData:getFormat()

format

Glyph pixel format.

GlyphData:getGlyph

Gets glyph number.

glyph = GlyphData:getGlyph()

glyph

number

Glyph number.

GlyphData:getGlyphString

Gets glyph string.

glyph = GlyphData:getGlyphString()

glyph

string

Glyph string.

GlyphData:getHeight

Gets glyph height.

height = GlyphData:getHeight()

height

number

Glyph height.

GlyphData:getWidth

Gets glyph width.

width = GlyphData:getWidth()

width

number

Glyph width.

A Rasterizer handles font rendering, containing the font data (image or TrueType font) and drawable glyphs.

Constructors

love.font.newTrueTypeRasterizer

love.font.newRasterizer

love.font.newImageRasterizer

love.font.newBMFontRasterizer

Functions

Rasterizer:getAdvance

Rasterizer:getAscent

Rasterizer:getDescent

Rasterizer:getGlyphCount

Rasterizer:getGlyphData

Rasterizer:getHeight

Rasterizer:getLineHeight

Rasterizer:hasGlyphs

Supertypes

Rasterizer:getAdvance

Gets font advance.

advance = Rasterizer:getAdvance()

advance

number

Font advance.

Rasterizer:getAscent

Gets ascent height.

height = Rasterizer:getAscent()

height

number

Ascent height.

Rasterizer:getDescent

Gets descent height.

height = Rasterizer:getDescent()

height

number

Descent height.

Rasterizer:getGlyphCount

Gets number of glyphs in font.

count = Rasterizer:getGlyphCount()

count

number

Glyphs count.

Rasterizer:getGlyphData

Gets glyph data of a specified glyph.

glyphData = Rasterizer:getGlyphData( glyph )

glyphData

Glyph data

glyph

string

Glyph

glyphData = Rasterizer:getGlyphData( glyphNumber )

glyphData

love.graphics.applyTransform

Glyph data

glyphNumber

number

Glyph number

Rasterizer:getHeight

Gets font height.

height = Rasterizer:getHeight()

height

number

Font height

Rasterizer:getLineHeight

Gets line height of a font.

height = Rasterizer:getLineHeight()

height

number

Line height of a font.

Rasterizer:hasGlyphs

Checks if font contains specified glyphs.

hasGlyphs = Rasterizer:hasGlyphs( glyph1, glyph2, ... )

hasGlyphs

boolean

Whatever font contains specified glyphs.

glyph1	string or number	Glyph
glyph2	string or number	Glyph
...	string or number	Additional glyphs

HintingMode

normal

Default hinting. Should be preferred for typical antialiased fonts.

light

Results in fuzzier text but can sometimes preserve the original glyph shapes of the text better than normal hinting.

mono

Results in aliased / unsmoothed text with either full opacity or completely transparent pixels. Should be used when antialiasing is not desired for the font.

none

Disables hinting for the font. Results in fuzzier text.

Types

Functions

love.graphics.applyTransform

love.graphics.captureScreenshot

love.graphics.clear

love.graphics.discard

love.graphics.drawInstanced

love.graphics.drawLayer

love.graphics.flushBatch

love.graphics.getDPIScale

love.graphics.get/setDepthMode

love.graphics.get/setFrontFaceWinding

love.graphics.getImageFormats

love.graphics.get/setMeshCullMode

love.graphics.getPixelDimensions

love.graphics.getPixelHeight

love.graphics.getPixelWidth

love.graphics.getStackDepth

love.graphics.getTextureTypes

love.graphics.inverseTransformPoint

love.graphics.isActive

love.graphics.newArrayImage

love.graphics.newCubeImage

love.graphics.newVolumeImage

love.graphics.present

love.graphics.replaceTransform

love.graphics.transformPoint

love.graphics.validateShader

Drawing

love.graphics.draw

love.graphics.print

love.graphics.printf

love.graphics.line

love.graphics.polygon

love.graphics.rectangle

love.graphics.circle

love.graphics.ellipse

love.graphics.arc

love.graphics.points

Stencil

love.graphics.stencil

love.graphics.get/setStencilTest

Graphics state

love.graphics.push

love.graphics.pop

love.graphics.reset

love.graphics.get/setFont

love.graphics.setNewFont

love.graphics.get/setBackgroundColor

love.graphics.get/setBlendMode

love.graphics.get/setCanvas

love.graphics.get/setColor

love.graphics.get/setColorMask

love.graphics.get/setDefaultFilter

love.graphics.get/setLineJoin

love.graphics.get/setLineStyle

love.graphics.get/setLineWidth

love.graphics.get/setShader

love.graphics.get/setPointSize

love.graphics.get/setScissor

love.graphics.intersectScissor

love.graphics.is/setWireframe

Coordinate system

love.graphics.origin

love.graphics.rotate

love.graphics.scale

love.graphics.shear

love.graphics.translate

Window

love.graphics.getDimensions

love.graphics.getHeight

love.graphics.getWidth

Info

love.graphics.getCanvasFormats

love.graphics.getStats

love.graphics.getSystemLimits

love.graphics.getRendererInfo

love.graphics.getSupported

love.graphics.isGammaCorrect

Enums

AlignMode

ArcType

AreaSpreadDistribution

Applies the given Transform object to the current coordinate transformation.

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

love.graphics.applyTransform( transform )

transform

love.graphics.captureScreenshot

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

love.graphics.arc

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

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

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

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

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

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

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

love.graphics.captureScreenshot( filename )

filename

string

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

love.graphics.captureScreenshot( callback )

callback

function

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

love.graphics.captureScreenshot( channel )

channel

love.graphics.drawInstanced

The Channel to push the generated ImageData to.

love.graphics.circle

Draws a circle.

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

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

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

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

love.graphics.clear

Clears the screen or active Canvas to the specified color.

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

Note that the scissor area bounds the cleared region.

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

In versions prior to background color instead.

love.graphics.clear()

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

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

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

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

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

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

love.graphics.discard

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

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

On some desktop systems this function may do nothing.

love.graphics.discard( discardcolor, discardstencil )

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

love.graphics.discard( discardcolors, discardstencil )

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

love.graphics.draw

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

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

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

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

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

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

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

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

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

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

love.graphics.draw( drawable, transform )

drawable	Drawable	A drawable object.
transform	Transform	Transformation object.

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

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

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

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

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

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

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

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

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

love.graphics.drawLayer

Draws a layer of an Array Texture.

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

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

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

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

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

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

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

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

love.graphics.ellipse

Draws an ellipse.

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

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

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

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

love.graphics.flushBatch

Immediately renders any pending automatically batched draws.

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

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

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

love.graphics.flushBatch()

love.graphics.getBackgroundColor

Gets the current background color.

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

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

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

love.graphics.getBlendMode

Gets the blending mode.

mode, alphamode = love.graphics.getBlendMode()

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

love.graphics.getCanvas

Gets the current target Canvas.

canvas = love.graphics.getCanvas()

canvas

love.graphics.getCanvasFormats

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

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

formats = love.graphics.getCanvasFormats()

formats

table

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

formats = love.graphics.getCanvasFormats( readable )

formats

table

A table containing CanvasFormats as keys, and a boolean indicating whether the format is supported as values (taking into account the readable parameter). Not all systems support all formats.

readable

boolean

If true, the returned formats will only be indicated as supported if readable flag set to true for that format, and vice versa if the parameter is false.

love.graphics.getColor

Gets the current color.

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

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

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

love.graphics.getColorMask

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

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

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

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

love.graphics.getDPIScale

Gets the DPI scale factor of the window.

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

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

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

scale = love.graphics.getDPIScale()

scale

number

The pixel scale factor associated with the window.

love.graphics.getDefaultFilter

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

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

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

love.graphics.getDepthMode

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

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

comparemode, write = love.graphics.getDepthMode()

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

love.graphics.getDimensions

Gets the width and height in pixels of the window.

width, height = love.graphics.getDimensions()

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

love.graphics.getFont

Gets the current Font object.

font = love.graphics.getFont()

font

love.graphics.getFrontFaceWinding

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

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

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

winding = love.graphics.getFrontFaceWinding()

winding

VertexWinding

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

love.graphics.getHeight

Gets the height in pixels of the window.

height = love.graphics.getHeight()

height

number

The height of the window.

love.graphics.getImageFormats

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

formats = love.graphics.getImageFormats()

formats

table

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

love.graphics.getLineJoin

Gets the line join style.

join = love.graphics.getLineJoin()

join

LineJoin

The LineJoin style.

love.graphics.getLineStyle

Gets the line style.

style = love.graphics.getLineStyle()

style

LineStyle

The current line style.

love.graphics.getLineWidth

Gets the current line width.

width = love.graphics.getLineWidth()

width

number

The current line width.

love.graphics.getMeshCullMode

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

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

mode = love.graphics.getMeshCullMode()

mode

CullMode

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

love.graphics.getPixelDimensions

Gets the width and height in pixels of the window.

love.graphics.getDimensions gets the dimensions of the window in units scaled by the screen's DPI scale factor, rather than pixels. Use getDimensions for calculations related to drawing to the screen and using the graphics coordinate system (calculating the center of the screen, for example), and getPixelDimensions only when dealing specifically with underlying pixels (pixel-related calculations in a pixel Shader, for example).

pixelwidth, pixelheight = love.graphics.getPixelDimensions()

pixelwidth	number	The width of the window in pixels.
pixelheight	number	The height of the window in pixels.

love.graphics.getPixelHeight

Gets the height in pixels of the window.

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

pixelheight = love.graphics.getPixelHeight()

pixelheight

number

The height of the window in pixels.

love.graphics.getPixelWidth

Gets the width in pixels of the window.

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

pixelwidth = love.graphics.getPixelWidth()

pixelwidth

number

The width of the window in pixels.

love.graphics.getPointSize

Gets the point size.

size = love.graphics.getPointSize()

size

number

The current point size.

love.graphics.getRendererInfo

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

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

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

love.graphics.getScissor

Gets the current scissor box.

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

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

love.graphics.getShader

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

shader = love.graphics.getShader()

shader

love.graphics.getStackDepth

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

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

depth = love.graphics.getStackDepth()

depth

number

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

love.graphics.getStats

Gets performance-related rendering statistics.

stats = love.graphics.getStats()

stats

table

A table with the following fields:

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

stats = love.graphics.getStats( stats )

stats

table

The table that was passed in above, now containing the following fields:

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

stats

table

A table which will be filled in with the stat fields below.

love.graphics.getStencilTest

Gets the current stencil test configuration.

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

Each Canvas has its own per-pixel stencil values.

comparemode, comparevalue = love.graphics.getStencilTest()

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

love.graphics.getSupported

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

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

features = love.graphics.getSupported()

features

table

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

love.graphics.getSystemLimits

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

limits = love.graphics.getSystemLimits()

limits

table

A table containing GraphicsLimit keys, and number values.

love.graphics.getTextureTypes

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

texturetypes = love.graphics.getTextureTypes()

texturetypes

table

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

love.graphics.getWidth

Gets the width in pixels of the window.

width = love.graphics.getWidth()

width

number

The width of the window.

love.graphics.intersectScissor

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

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

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

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

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

love.graphics.inverseTransformPoint

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

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

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

globalX	number	The x component of the position in global coordinates.
globalY	number	The y component of the position in global coordinates.

screenX	number	The x component of the screen-space position.
screenY	number	The y component of the screen-space position.

love.graphics.isActive

Gets whether the graphics module is able to be used. If it is not active, love.graphics function and method calls will not work correctly and may cause the program to crash. The graphics module is inactive if a window is not open, or if the app is in the background on iOS. Typically the app's execution will be automatically paused by the system, in the latter case.

active = love.graphics.isActive()

active

boolean

Whether the graphics module is active and able to be used.

love.graphics.isGammaCorrect

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

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

gammacorrect = love.graphics.isGammaCorrect()

gammacorrect

boolean

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

love.graphics.isWireframe

Gets whether wireframe mode is used when drawing.

wireframe = love.graphics.isWireframe()

wireframe

boolean

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

love.graphics.line

Draws lines between points.

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

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

love.graphics.line( points )

points

table

A table of point positions, as described above.

love.graphics.newArrayImage

Creates a new array Image.

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

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

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

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

image

An Array Image object.

slices	table	A table containing filepaths to images (or File, FileData, ImageData, or CompressedImageData objects), in an array. Each sub-image must have the same dimensions. A table of tables can also be given, where each sub-table contains all mipmap levels for the slice index of that sub-table.
settings (nil)	table	Optional table of settings to configure the array image, containing the following fields:

settings.mipmaps (false)	boolean	True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a compressed texture format.
settings.linear (false)	boolean	True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.
settings.dpiscale (1)	number	The DPI scale to use when drawing the array image and calling getWidth/getHeight.

love.graphics.newCanvas

Creates a new Canvas object for offscreen rendering.

canvas = love.graphics.newCanvas()

canvas

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

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

canvas

A new Canvas with specified width and height.

width	number	The desired width of the Canvas.
height	number	The desired height of the Canvas.

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

canvas

A new Canvas with specified width and height.

width	number	The desired width of the Canvas.
height	number	The desired height of the Canvas.
settings	table	A table containing the given fields:

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

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

canvas

love.graphics.newCubeImage

A new Canvas with specified width and height.

width	number	The desired width of the Canvas.
height	number	The desired height of the Canvas.
layers	number	The number of array layers (if the Canvas is an Array Texture), or the volume depth (if the Canvas is a Volume Texture).
settings	table	A table containing the given fields:

settings.type ('array')	TextureType	The type of Canvas to create.
settings.format ('normal')	PixelFormat	The format of the Canvas.
settings.readable	boolean	Whether the Canvas is readable (drawable and accessible in a Shader). True by default for regular formats, false by default for depth/stencil formats.
settings.msaa (0)	number	The desired number of multisample antialiasing (MSAA) samples used when drawing to the Canvas.
settings.dpiscale (love.graphics.getDPIScale())	number	The DPI scale factor of the Canvas, used when drawing to the Canvas as well as when drawing the Canvas to the screen.
settings.mipmaps ('none')	MipmapMode	Whether the Canvas has mipmaps, and whether to automatically regenerate them if so.

Creates a new cubemap Image.

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

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

Each face in a cubemap image must have square dimensions.

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

+y

+z +x -z

-y

-x

or:

+y

-x +z +x -z

-y

or:

+x

-x

+y

-y

+z

-z

or:

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

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

image

An cubemap Image object.

filename	string	The filepath to a cubemap image file (or a File, FileData, or ImageData).
settings (nil)	table	Optional table of settings to configure the cubemap image, containing the following fields:

settings.mipmaps (false)	boolean	True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a compressed texture format.
settings.linear (false)	boolean	True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.

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

image

An cubemap Image object.

faces	table	A table containing 6 filepaths to images (or File, FileData, ImageData, or CompressedImageData objects), in an array. Each face image must have the same dimensions. A table of tables can also be given, where each sub-table contains all mipmap levels for the cube face index of that sub-table.
settings (nil)	table	Optional table of settings to configure the cubemap image, containing the following fields:

settings.mipmaps (false)	boolean	True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a compressed texture format.
settings.linear (false)	boolean	True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.

love.graphics.newFont

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

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

font = love.graphics.newFont( filename )

font

A Font object which can be used to draw text on screen.

filename

string

The filepath to the BMFont or TrueType font file.

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

font

A Font object which can be used to draw text on screen.

filename	string	The filepath to the TrueType font file.
size	number	The size of the font in pixels.
hinting ('normal')	HintingMode	True Type hinting mode.
dpiscale (love.graphics.getDPIScale())	number	The DPI scale factor of the font.

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

font

A Font object which can be used to draw text on screen.

filename	string	The filepath to the BMFont file.
imagefilename	string	The filepath to the BMFont's image file. If this argument is omitted, the path specified inside the BMFont file will be used.

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

font

A Font object which can be used to draw text on screen.

size (12)	number	The size of the font in pixels.
hinting ('normal')	HintingMode	True Type hinting mode.
dpiscale (love.graphics.getDPIScale())	number	The DPI scale factor of the font.

love.graphics.newImage

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

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

image

A new Image object which can be drawn on screen.

filename	string	The filepath to the image file.
settings	table	A table containing the following fields:

settings.dpiscale (1)	number	The DPI scale to use when drawing the image and calling getWidth/getHeight.
settings.linear (false)	boolean	True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.
settings.mipmaps (false)	boolean	If true, mipmaps for the image will be automatically generated (or taken from the images's file if possible, if the image originated from a CompressedImageData).

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

image

A new Image object which can be drawn on screen.

fileData	FileData	The FileData containing image file.
settings	table	A table containing the following fields:

settings.dpiscale (1)	number	The DPI scale to use when drawing the image and calling getWidth/getHeight.
settings.linear (false)	boolean	True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.
settings.mipmaps (false)	boolean	If true, mipmaps for the image will be automatically generated (or taken from the images's file if possible, if the image originated from a CompressedImageData).

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

image

A new Image object which can be drawn on screen.

imageData	ImageData	The ImageData containing image.
settings	table	A table containing the following fields:

settings.dpiscale (1)	number	The DPI scale to use when drawing the image and calling getWidth/getHeight.
settings.linear (false)	boolean	True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.
settings.mipmaps (false)	boolean	If true, mipmaps for the image will be automatically generated (or taken from the images's file if possible, if the image originated from a CompressedImageData).

image = love.graphics.newImage( compressedImageData, settings )

image

love.graphics.newImageFont

A new Image object which can be drawn on screen.

compressedImageData	CompressedImageData	A CompressedImageData object. The Image will use this CompressedImageData to reload itself when love.window.setMode is called.
settings	table	A table containing the following fields:

settings.dpiscale (1)	number	The DPI scale to use when drawing the image and calling getWidth/getHeight.
settings.linear (false)	boolean	True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.
settings.mipmaps (false)	boolean	If true, mipmaps for the image will be automatically generated (or taken from the images's file if possible, if the image originated from a CompressedImageData).

Creates a new specifically formatted image.

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

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

font

A Font object which can be used to draw text on screen.

filename	string	The filepath to the image file.
glyphs	string	A string of the characters in the image in order from left to right.

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

font

A Font object which can be used to draw text on screen.

imageData	ImageData	The ImageData object to create the font from.
glyphs	string	A string of the characters in the image in order from left to right.

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

font

A Font object which can be used to draw text on screen.

filename	string	The filepath to the image file.
glyphs	string	A string of the characters in the image in order from left to right.
extraspacing	number	Additional spacing (positive or negative) to apply to each glyph in the Font.

love.graphics.newMesh

Creates a new Mesh.

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

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

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

mesh

The new mesh.

vertices

table

The table filled with vertex information tables for each vertex as follows:

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

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

mesh

The new mesh.

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

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

mesh

The new mesh.

vertexformat

table

A table in the form of {attribute, ...}. Each attribute is a table which specifies a custom vertex attribute used for each vertex.

vertexformat.attribute	table	A table containing the attribute's name, it's data type, and the number of components in the attribute, in the form of {name, datatype, components}.
vertexformat....	table	Additional vertex attribute format tables.
vertices	table	The table filled with vertex information tables for each vertex, in the form of {vertex, ...} where each vertex is a table in the form of {attributecomponent, ...}.

vertices.attributecomponent	number	The first component of the first vertex attribute in the vertex.
vertices....	number	Additional components of all vertex attributes in the vertex.
mode ('fan')	MeshDrawMode	How the vertices are used when drawing. The default mode 'fan' is sufficient for simple convex polygons.
usage ('dynamic')	SpriteBatchUsage	The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.

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

mesh

The new mesh.

vertexformat

table

A table in the form of {attribute, ...}. Each attribute is a table which specifies a custom vertex attribute used for each vertex.

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

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

mesh

love.graphics.newParticleSystem

The new mesh.

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

Creates a new ParticleSystem.

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

system

A new ParticleSystem.

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

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

system

A new ParticleSystem.

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

love.graphics.newQuad

Creates a new Quad.

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

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

quad

Quad

The new Quad.

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

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

quad

Quad

The new Quad.

x	number	The top-left position in the Image along the x-axis.
y	number	The top-left position in the Image along the y-axis.
width	number	The width of the Quad in the Image. (Must be greater than 0.)
height	number	The height of the Quad in the Image. (Must be greater than 0.)
texture	Texture	The texture whose width and height will be used as the reference width and height.

love.graphics.newShader

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

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

shader = love.graphics.newShader( code )

shader

A Shader object for use in drawing operations.

code

string

The pixel shader or vertex shader code, or a filename pointing to a file with the code.

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

shader

love.graphics.newSpriteBatch

A Shader object for use in drawing operations.

pixelcode	string	The pixel shader code, or a filename pointing to a file with the code.
vertexcode	string	The vertex shader code, or a filename pointing to a file with the code.

Creates a new SpriteBatch object.

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

spriteBatch

The new SpriteBatch.

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

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

spriteBatch

The new SpriteBatch.

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

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

spriteBatch

The new SpriteBatch.

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

love.graphics.newText

Creates a new drawable Text object.

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

text

Text

The new drawable Text object.

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

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

text

Text

The new drawable Text object.

font	Font	The font to use for the text.
coloredtext	table	A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.

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

love.graphics.newVideo

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

video = love.graphics.newVideo( filename )

video

A new Video.

filename

string

The file path to the Ogg Theora video file.

video = love.graphics.newVideo( videostream )

video

A new Video.

videostream

A video stream object.

video = love.graphics.newVideo( filename, settings )

video

A new Video.

filename	string	The file path to the Ogg Theora video file (or VideoStream).
settings	table	A table containing the following fields:

settings.audio (false)	boolean	Whether to try to load the video's audio into an audio Source. If not explicitly set to true or false, it will try without causing an error if the video has no audio.
settings.dpiscale (love.graphics.getDPIScale())	number	The DPI scale factor of the video.

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

video

A new Video.

filename	string	The file path to the Ogg Theora video file.
loadaudio (nil)	boolean	Whether to try to load the video's audio into an audio Source. If not explicitly set to true or false, it will try without causing an error if the video has no audio.

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

video

love.graphics.newVolumeImage

A new Video.

videostream	VideoStream	A video stream object.
loadaudio (nil)	boolean	Whether to try to load the video's audio into an audio Source. If not explicitly set to true or false, it will try without causing an error if the video has no audio.

Creates a new volume (3D) Image.

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

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

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

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

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

image

love.graphics.replaceTransform

A volume Image object.

layers	table	A table containing filepaths to images (or File, FileData, ImageData, or CompressedImageData objects), in an array. A table of tables can also be given, where each sub-table represents a single mipmap level and contains all layers for that mipmap.
settings (nil)	table	Optional table of settings to configure the volume image, containing the following fields:

settings.mipmaps (false)	boolean	True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a compressed texture format.
settings.linear (false)	boolean	True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.

love.graphics.origin

Resets the current coordinate transformation.

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

love.graphics.origin()

love.graphics.points

Draws one or more points.

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

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

love.graphics.points( points )

points

table

A table containing multiple point positions, in the form of {x, y, ...}.

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

love.graphics.points( points )

points

table

A table containing multiple individually colored points, in the form of {point, ...}.

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

love.graphics.polygon

Draw a polygon.

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

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

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

love.graphics.polygon( mode, vertices )

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

love.graphics.pop

Pops the current coordinate transformation from the transformation stack.

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

love.graphics.pop()

love.graphics.present

Displays the results of drawing operations on the screen.

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

love.graphics.present()

love.graphics.print

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

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

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

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

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

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

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

coloredtext

table

A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.

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

love.graphics.print( text, transform )

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

love.graphics.print( coloredtext, transform )

coloredtext

table

A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.

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

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

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

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

coloredtext

table

A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.

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

love.graphics.printf

Draws formatted text, with word wrap and alignment.

See additional notes in love.graphics.print.

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

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

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

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

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

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

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

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

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

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

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

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

coloredtext

table

A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.

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

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

coloredtext

table

A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.

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

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

coloredtext

table

A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.

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

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

coloredtext

table

A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.

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

love.graphics.push

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

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

love.graphics.push()

love.graphics.push( stack )

stack

StackType

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

love.graphics.rectangle

Draws a rectangle.

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

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

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

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

Replaces the current coordinate transformation with the given Transform object.

love.graphics.replaceTransform( transform )

transform

love.graphics.setBackgroundColor

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

love.graphics.reset

Resets the current graphics settings.

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

love.graphics.reset()

love.graphics.rotate

Rotates the coordinate system in two dimensions.

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

love.graphics.rotate( angle )

angle

number

The amount to rotate the coordinate system in radians.

love.graphics.scale

Scales the coordinate system in two dimensions.

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

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

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

Scaling lasts until love.draw() exits.

love.graphics.scale( sx, sy )

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

Sets the background color.

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

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

love.graphics.setBackgroundColor( rgba )

rgba

table

A numerical indexed table with the red, green, blue and alpha values as numbers. The alpha is optional and defaults to 1 if it is left out.

love.graphics.setBlendMode

Sets the blending mode.

love.graphics.setBlendMode( mode )

mode

BlendMode

The blend mode to use.

love.graphics.setBlendMode( mode, alphamode )

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

love.graphics.setCanvas

Captures drawing operations to a Canvas.

love.graphics.setCanvas( canvas, mipmap )

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

love.graphics.setCanvas()

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

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

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

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

love.graphics.setCanvas( setup )

setup

table

A table specifying the active Canvas(es), their mipmap levels and active layers if applicable, and whether to use a stencil and/or depth buffer.

setup.1	RenderTargetSetup	The Canvas to render to.
setup.2 (nil)	RenderTargetSetup	An additional Canvas to render to, if multiple simultaneous render targets are wanted.
setup....	RenderTargetSetup	Additional Canvases to render to, if multiple simultaneous render targets are wanted.
setup.stencil (false)	boolean	Whether an internally managed stencil buffer should be used, if the depthstencil field isn't set.
setup.depth (false)	boolean	Whether an internally managed depth buffer should be used, if the depthstencil field isn't set.
setup.depthstencil (nil)	RenderTargetSetup	An optional custom depth/stencil formatted Canvas to use for the depth and/or stencil buffer.

love.graphics.setColor

Sets the color used for drawing.

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

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

red	number	The amount of red.
green	number	The amount of green.
blue	number	The amount of blue.
alpha (1)	number	The amount of alpha. The alpha value will be applied to all subsequent draw operations, even the drawing of an image.

love.graphics.setColor( rgba )

rgba

table

A numerical indexed table with the red, green, blue and alpha values as numbers. The alpha is optional and defaults to 1 if it is left out.

love.graphics.setColorMask

Sets the color mask. Enables or disables specific color components when rendering and clearing the screen. For example, if '''red''' is set to '''false''', no further changes will be made to the red component of any pixels.

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

red	boolean	Render red component.
green	boolean	Render green component.
blue	boolean	Render blue component.
alpha	boolean	Render alpha component.

love.graphics.setColorMask()

love.graphics.setDefaultFilter

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

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

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

love.graphics.setDepthMode

Configures depth testing and writing to the depth buffer.

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

love.graphics.setDepthMode( comparemode, write )

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

love.graphics.setDepthMode()

love.graphics.setFont

Set an already-loaded Font as the current font or create and load a new one from the file and size.

It's recommended that Font objects are created with love.graphics.newFont in the loading stage and then passed to this function in the drawing stage.

love.graphics.setFont( font )

font

love.graphics.setFrontFaceWinding

The Font object to use.

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

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

love.graphics.setFrontFaceWinding( winding )

winding

VertexWinding

The winding mode to use. The default winding is counterclockwise ('ccw').

love.graphics.setLineJoin

Sets the line join style. See LineJoin for the possible options.

love.graphics.setLineJoin( join )

join

LineJoin

The LineJoin to use.

love.graphics.setLineStyle

Sets the line style.

love.graphics.setLineStyle( style )

style

LineStyle

The LineStyle to use. Line styles include smooth and rough.

love.graphics.setLineWidth

Sets the line width.

love.graphics.setLineWidth( width )

width

number

The width of the line.

love.graphics.setMeshCullMode

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

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

By default, both front- and back-facing triangles in Meshes are rendered.

love.graphics.setMeshCullMode( mode )

mode

CullMode

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

love.graphics.setNewFont

Creates and sets a new Font.

font = love.graphics.setNewFont( size )

font

The new font.

size (12)

number

The size of the font.

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

font

The new font.

filename	string	The path and name of the file with the font.
size (12)	number	The size of the font.

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

font

The new font.

file	File	A File with the font.
size (12)	number	The size of the font.

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

font

The new font.

data	Data	A Data with the font.
size (12)	number	The size of the font.

font = love.graphics.setNewFont( rasterizer )

font

The new font.

rasterizer

love.graphics.setPointSize

A rasterizer.

Sets the point size.

love.graphics.setPointSize( size )

size

number

The new point size.

love.graphics.setScissor

Sets or disables scissor.

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

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

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

x	number	x coordinate of upper left corner.
y	number	y coordinate of upper left corner.
width	number	width of clipping rectangle.
height	number	height of clipping rectangle.

love.graphics.setScissor()

love.graphics.setShader

Sets or resets a Shader as the current pixel effect or vertex shaders. All drawing operations until the next ''love.graphics.setShader'' will be drawn using the Shader object specified.

love.graphics.setShader( shader )

shader

love.graphics.setStencilTest

The new shader.

love.graphics.setShader()

Configures or disables stencil testing.

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

love.graphics.setStencilTest( comparemode, comparevalue )

comparemode	CompareMode	The type of comparison to make for each pixel.
comparevalue	number	The value to use when comparing with the stencil value of each pixel. Must be between 0 and 255.

love.graphics.setStencilTest()

love.graphics.setWireframe

Sets whether wireframe lines will be used when drawing.

love.graphics.setWireframe( enable )

enable

boolean

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

love.graphics.shear

Shears the coordinate system.

love.graphics.shear( kx, ky )

kx	number	The shear factor on the x-axis.
ky	number	The shear factor on the y-axis.

love.graphics.stencil

Draws geometry as a stencil.

The geometry drawn by the supplied function sets invisible stencil values of pixels, instead of setting pixel colors. The stencil buffer (which contains those stencil values) can act like a mask / stencil - love.graphics.setStencilTest can be used afterward to determine how further rendering is affected by the stencil values in each pixel.

Stencil values are integers within the range of 255.

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

stencilfunction	function	Function which draws geometry. The stencil values of pixels, rather than the color of each pixel, will be affected by the geometry.
action ('replace')	StencilAction	How to modify any stencil values of pixels that are touched by what's drawn in the stencil function.
value (1)	number	The new stencil value to use for pixels if the 'replace' stencil action is used. Has no effect with other stencil actions. Must be between 0 and 255.
keepvalues (false)	boolean	True to preserve old stencil values of pixels, false to re-set every pixel's stencil value to 0 before executing the stencil function. love.graphics.clear will also re-set all stencil values.

love.graphics.transformPoint

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

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

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

screenX	number	The x component of the position with graphics transformations applied.
screenY	number	The y component of the position with graphics transformations applied.

globalX	number	The x component of the position in global coordinates.
globalY	number	The y component of the position in global coordinates.

love.graphics.translate

Translates the coordinate system in two dimensions.

When this function is called with two numbers, dx, and dy, all the following drawing operations take effect as if their x and y coordinates were x+dx and y+dy.

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

This change lasts until love.draw() exits or else a love.graphics.pop reverts to a previous love.graphics.push.

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

love.graphics.translate( dx, dy )

dx	number	The translation relative to the x-axis.
dy	number	The translation relative to the y-axis.

love.graphics.validateShader

Validates shader code. Check if specified shader code does not contain any errors.

status, message = love.graphics.validateShader( gles, code )

status	boolean	true if specified shader code doesn't contain any errors. false otherwise.
message	string	Reason why shader code validation failed (or nil if validation succeded).

gles	boolean	Validate code as GLSL ES shader.
code	string	The pixel shader or vertex shader code, or a filename pointing to a file with the code.

status, message = love.graphics.validateShader( gles, pixelcode, vertexcode )

status	boolean	true if specified shader code doesn't contain any errors. false otherwise.
message	string	Reason why shader code validation failed (or nil if validation succeded).

gles	boolean	Validate code as GLSL ES shader.
pixelcode	string	The pixel shader code, or a filename pointing to a file with the code.
vertexcode	string	The vertex shader code, or a filename pointing to a file with the code.

A Canvas is used for off-screen rendering. Think of it as an invisible screen that you can draw to, but that will not be visible until you draw it to the actual visible screen. It is also known as "render to texture".

By drawing things that do not change position often (such as background items) to the Canvas, and then drawing the entire Canvas instead of each item, you can reduce the number of draw operations performed each frame.

In versions prior to love.graphics.isSupported("canvas") could be used to check for support at runtime.

Constructors

love.graphics.newCanvas

love.graphics.getCanvas

Functions

Canvas:generateMipmaps

Canvas:getMSAA

Canvas:getMipmapMode

Canvas:newImageData

Canvas:renderTo

Supertypes

Canvas:generateMipmaps

Generates mipmaps for the Canvas, based on the contents of the highest-resolution mipmap level.

The Canvas must be created with mipmaps set to a MipmapMode other than 'none' for this function to work. It should only be called while the Canvas is not the active render target.

If the mipmap mode is set to 'auto', this function is automatically called inside love.graphics.setCanvas when switching from this Canvas to another Canvas or to the main screen.

Canvas:generateMipmaps()

Canvas:getMSAA

Gets the number of multisample antialiasing (MSAA) samples used when drawing to the Canvas.

This may be different than the number used as an argument to love.graphics.newCanvas if the system running LÖVE doesn't support that number.

samples = Canvas:getMSAA()

samples

number

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

Canvas:getMipmapMode

Gets the MipmapMode this Canvas was created with.

mode = Canvas:getMipmapMode()

mode

MipmapMode

The mipmap mode this Canvas was created with.

Canvas:newImageData

Generates ImageData from the contents of the Canvas.

data = Canvas:newImageData()

data

The new ImageData made from the Canvas' contents.

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

data

The new ImageData made from the Canvas' contents.

slice	number	The cubemap face index, array index, or depth layer for cubemap, array, or volume type Canvases, respectively. This argument is ignored for regular 2D canvases.
mipmap (1)	number	The mipmap index to use, for Canvases with mipmaps.
x	number	The x-axis of the top-left corner (in pixels) of the area within the Canvas to capture.
y	number	The y-axis of the top-left corner (in pixels) of the area within the Canvas to capture.
width	number	The width in pixels of the area within the Canvas to capture.
height	number	The height in pixels of the area within the Canvas to capture.

Canvas:renderTo

Render to the Canvas using a function.

This is a shortcut to love.graphics.setCanvas:

canvas:renderTo( func )

is the same as

love.graphics.setCanvas( canvas )

func()

love.graphics.setCanvas()

Canvas:renderTo( func )

func

function

A function performing drawing operations.

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

Functions

Supertypes

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

Constructors

love.graphics.getFont

love.graphics.newFont

love.graphics.setNewFont

love.graphics.newImageFont

Functions

Font:getAscent

Font:getBaseline

Font:getDPIScale

Font:getDescent

Font:get/setFilter

Font:getHeight

Font:getKerning

Font:get/setLineHeight

Font:getWidth

Font:getWrap

Font:hasGlyphs

Font:setFallbacks

Supertypes

Font:getAscent

Gets the ascent of the Font.

The ascent spans the distance between the baseline and the top of the glyph that reaches farthest from the baseline.

ascent = Font:getAscent()

ascent

number

The ascent of the Font in pixels.

Font:getBaseline

Gets the baseline of the Font.

Most scripts share the notion of a baseline: an imaginary horizontal line on which characters rest. In some scripts, parts of glyphs lie below the baseline.

baseline = Font:getBaseline()

baseline

number

The baseline of the Font in pixels.

Font:getDPIScale

Gets the DPI scale factor of the Font.

The DPI scale factor represents relative pixel density. A DPI scale factor of 2 means the font's glyphs have twice the pixel density in each dimension (4 times as many pixels in the same area) compared to a font with a DPI scale factor of 1.

The font size of TrueType fonts is scaled internally by the font's specified DPI scale factor. By default, LÖVE uses the screen's DPI scale factor when creating TrueType fonts.

dpiscale = Font:getDPIScale()

dpiscale

number

The DPI scale factor of the Font.

Font:getDescent

Gets the descent of the Font.

The descent spans the distance between the baseline and the lowest descending glyph in a typeface.

descent = Font:getDescent()

descent

number

The descent of the Font in pixels.

Font:getFilter

Gets the filter mode for a font.

min, mag, anisotropy = Font:getFilter()

min	FilterMode	Filter mode used when minifying the font.
mag	FilterMode	Filter mode used when magnifying the font.
anisotropy	number	Maximum amount of anisotropic filtering used.

Font:getHeight

Gets the height of the Font.

The height of the font is the size including any spacing; the height which it will need.

height = Font:getHeight()

height

number

The height of the Font in pixels.

Font:getKerning

Gets the kerning between two characters in the Font.

Kerning is normally handled automatically in love.graphics.print, Text objects, Font:getWidth, Font:getWrap, etc. This function is useful when stitching text together manually.

kerning = Font:getKerning( leftchar, rightchar )

kerning

number

The kerning amount to add to the spacing between the two characters. May be negative.

leftchar	string	The left character.
rightchar	string	The right character.

kerning = Font:getKerning( leftglyph, rightglyph )

kerning

number

The kerning amount to add to the spacing between the two characters. May be negative.

leftglyph	number	The unicode number for the left glyph.
rightglyph	number	The unicode number for the right glyph.

Font:getLineHeight

Gets the line height.

This will be the value previously set by Font:setLineHeight, or 1.0 by default.

height = Font:getLineHeight()

height

number

The current line height.

Font:getWidth

Determines the maximum width (accounting for newlines) taken by the given string.

width = Font:getWidth( text )

width

number

The width of the text.

text

string

A string.

Font:getWrap

Gets formatting information for text, given a wrap limit.

This function accounts for newlines correctly (i.e. '\n').

width, wrappedtext = Font:getWrap( text, wraplimit )

width	number	The maximum width of the wrapped text.
wrappedtext	table	A sequence containing each line of text that was wrapped.

text	string	The text that will be wrapped.
wraplimit	number	The maximum width in pixels of each line that ''text'' is allowed before wrapping.

Font:hasGlyphs

Gets whether the Font can render a character or string.

hasglyph = Font:hasGlyphs( text )

hasglyph

boolean

Whether the font can render all the UTF-8 characters in the string.

text

string

A UTF-8 encoded unicode string.

hasglyph = Font:hasGlyphs( character1, character2 )

hasglyph

boolean

Whether the font can render all the glyphs represented by the characters.

character1	string	A unicode character.
character2	string	Another unicode character.

hasglyph = Font:hasGlyphs( codepoint1, codepoint2 )

hasglyph

boolean

Whether the font can render all the glyphs represented by the codepoint numbers.

codepoint1	number	A unicode codepoint number.
codepoint2	number	Another unicode codepoint number.

Font:setFallbacks

Sets the fallback fonts. When the Font doesn't contain a glyph, it will substitute the glyph from the next subsequent fallback Fonts. This is akin to setting a 'font stack' in Cascading Style Sheets (CSS).

Font:setFallbacks( fallbackfont1, ... )

fallbackfont1	Font	The first fallback Font to use.
...	Font	Additional fallback Fonts.

Font:setFilter

Sets the filter mode for a font.

Font:setFilter( min, mag, anisotropy )

min	FilterMode	How to scale a font down.
mag	FilterMode	How to scale a font up.
anisotropy (1)	number	Maximum amount of anisotropic filtering used.

Font:setLineHeight

Sets the line height.

When rendering the font in lines the actual height will be determined by the line height multiplied by the height of the font. The default is 1.0.

Font:setLineHeight( height )

height

number

The new line height.

Drawable image type.

Constructors

love.graphics.newImage

love.graphics.newVolumeImage

love.graphics.newCubeImage

love.graphics.newArrayImage

Functions

Image:getFlags

Image:isCompressed

Image:replacePixels

Supertypes

Gets the flags used when the image was created.

flags = Image:getFlags()

flags

table

A table with ImageFlag keys.

Image:isCompressed

Gets whether the Image was created from CompressedData.

Compressed images take up less space in VRAM, and drawing a compressed image will generally be more efficient than drawing one created from raw pixel data.

compressed = Image:isCompressed()

compressed

boolean

Whether the Image is stored as a compressed texture on the GPU.

Image:replacePixels

Replace the contents of an Image.

Image:replacePixels( data, slice, mipmap, x, y, reloadmipmaps )

data	ImageData	The new ImageData to replace the contents with.
slice	number	Which cubemap face, array index, or volume layer to replace, if applicable.
mipmap (1)	number	The mimap level to replace, if the Image has mipmaps.
x (0)	number	The x-offset in pixels from the top-left of the image to replace. The given ImageData's width plus this value must not be greater than the pixel width of the Image's specified mipmap level.
y (0)	number	The y-offset in pixels from the top-left of the image to replace. The given ImageData's height plus this value must not be greater than the pixel height of the Image's specified mipmap level.
reloadmipmaps	boolean	Whether to generate new mipmaps after replacing the Image's pixels. True by default if the Image was created with automatically generated mipmaps, false by default otherwise.

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

Constructors

love.graphics.newMesh

Functions

Mesh:attachAttribute

Mesh:detachAttribute

Mesh:get/setDrawMode

Mesh:get/setDrawRange

Mesh:get/setTexture

Mesh:get/setVertex

Mesh:get/setVertexAttribute

Mesh:getVertexCount

Mesh:getVertexFormat

Mesh:get/setVertexMap

Mesh:is/setAttributeEnabled

Mesh:setVertices

Supertypes

Mesh:attachAttribute

Attaches a vertex attribute from a different Mesh onto this Mesh, for use when drawing. This can be used to share vertex attribute data between several different Meshes.

Mesh:attachAttribute( name, mesh )

name	string	The name of the vertex attribute to attach.
mesh	Mesh	The Mesh to get the vertex attribute from.

Mesh:attachAttribute( name, mesh, step, attachname )

name	string	The name of the vertex attribute to attach.
mesh	Mesh	The Mesh to get the vertex attribute from.
step ('pervertex')	VertexAttributeStep	Whether the attribute will be per-vertex or per-instance when the mesh is drawn.
attachname (name)	string	The name of the attribute to use in shader code. Defaults to the name of the attribute in the given mesh. Can be used to use a different name for this attribute when rendering.

Mesh:attachAttribute

Attaches a vertex attribute from a different Mesh onto this Mesh, for use when drawing. This can be used to share vertex attribute data between several different Meshes.

Mesh:attachAttribute( name, mesh )

name	string	The name of the vertex attribute to attach.
mesh	Mesh	The Mesh to get the vertex attribute from.

Mesh:attachAttribute( name, mesh, step, attachname )

name	string	The name of the vertex attribute to attach.
mesh	Mesh	The Mesh to get the vertex attribute from.
step ('pervertex')	VertexAttributeStep	Whether the attribute will be per-vertex or per-instance when the mesh is drawn.
attachname (name)	string	The name of the attribute to use in shader code. Defaults to the name of the attribute in the given mesh. Can be used to use a different name for this attribute when rendering.

Mesh:detachAttribute

Removes a previously attached vertex attribute from this Mesh.

success = Mesh:detachAttribute( name )

success

boolean

Whether the attribute was successfully detached.

name

string

The name of the attached vertex attribute to detach.

Mesh:getDrawMode

Gets the mode used when drawing the Mesh.

mode = Mesh:getDrawMode()

mode

MeshDrawMode

The mode used when drawing the Mesh.

Mesh:getDrawRange

Gets the range of vertices used when drawing the Mesh.

min, max = Mesh:getDrawRange()

min	number	The index of the first vertex used when drawing, or the index of the first value in the vertex map used if one is set for this Mesh.
max	number	The index of the last vertex used when drawing, or the index of the last value in the vertex map used if one is set for this Mesh.

Mesh:getTexture

Gets the texture (Image or Canvas) used when drawing the Mesh.

texture = Mesh:getTexture()

texture

The Image or Canvas to texture the Mesh with when drawing, or nil if none is set.

Mesh:getVertex

Gets the properties of a vertex in the Mesh.

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

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

attributecomponent	number	The first component of the first vertex attribute in the specified vertex.
...	number	Additional components of all vertex attributes in the specified vertex.

index

number

The one-based index of the vertex you want to retrieve the information for.

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

x	number	The position of the vertex on the x-axis.
y	number	The position of the vertex on the y-axis.
u	number	The horizontal component of the texture coordinate.
v	number	The vertical component of the texture coordinate.
r	number	The red component of the vertex's color.
g	number	The green component of the vertex's color.
b	number	The blue component of the vertex's color.
a	number	The alpha component of the vertex's color.

index

number

The index of the vertex you want to retrieve the information for.

Mesh:getVertexAttribute

Gets the properties of a specific attribute within a vertex in the Mesh.

Meshes without a custom vertex format specified in love.graphics.newMesh have position as their first attribute, texture coordinates as their second attribute, and color as their third attribute.

value1, value2, ... = Mesh:getVertexAttribute( vertexindex, attributeindex )

value1	number	The value of the first component of the attribute.
value2	number	The value of the second component of the attribute.
...	number	Any additional vertex attribute components.

vertexindex	number	The index of the the vertex you want to retrieve the attribute for (one-based).
attributeindex	number	The index of the attribute within the vertex to be retrieved (one-based).

Mesh:getVertexCount

Gets the total number of vertices in the Mesh.

count = Mesh:getVertexCount()

count

number

The total number of vertices in the mesh.

Mesh:getVertexFormat

Gets the vertex format that the Mesh was created with.

format = Mesh:getVertexFormat()

format

table

The vertex format of the Mesh, which is a table containing tables for each vertex attribute the Mesh was created with, in the form of {attribute, ...}.

format.attribute	table	A table containing the attribute's name, it's data type, and the number of components in the attribute, in the form of {name, datatype, components}.
format....	table	Additional vertex attributes in the Mesh.

Mesh:getVertexMap

Gets the vertex map for the Mesh. The vertex map describes the order in which the vertices are used when the Mesh is drawn. The vertices, vertex map, and mesh draw mode work together to determine what exactly is displayed on the screen.

If no vertex map has been set previously via Mesh:setVertexMap, then this function will return nil in LÖVE 0.10.0+, or an empty table in 0.9.2 and older.

map = Mesh:getVertexMap()

map

table

A table containing the list of vertex indices used when drawing.

Mesh:isAttributeEnabled

Gets whether a specific vertex attribute in the Mesh is enabled. Vertex data from disabled attributes is not used when drawing the Mesh.

enabled = Mesh:isAttributeEnabled( name )

enabled

boolean

Whether the vertex attribute is used when drawing this Mesh.

name

string

The name of the vertex attribute to be checked.

Mesh:setAttributeEnabled

Enables or disables a specific vertex attribute in the Mesh. Vertex data from disabled attributes is not used when drawing the Mesh.

Mesh:setAttributeEnabled( name, enable )

name	string	The name of the vertex attribute to enable or disable.
enable	boolean	Whether the vertex attribute is used when drawing this Mesh.

Mesh:setDrawMode

Sets the mode used when drawing the Mesh.

Mesh:setDrawMode( mode )

mode

MeshDrawMode

The mode to use when drawing the Mesh.

Mesh:setDrawRange

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

Mesh:setDrawRange( start, count )

start	number	The index of the first vertex to use when drawing, or the index of the first value in the vertex map to use if one is set for this Mesh.
count	number	The number of vertices to use when drawing, or number of values in the vertex map to use if one is set for this Mesh.

Mesh:setDrawRange()

Mesh:setTexture

Sets the texture (Image or Canvas) used when drawing the Mesh.

Mesh:setTexture( texture )

texture

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

Mesh:setTexture()

Mesh:setVertex

Sets the properties of a vertex in the Mesh.

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

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

index	number	The index of the the vertex you want to modify (one-based).
attributecomponent	number	The first component of the first vertex attribute in the specified vertex.
...	number	Additional components of all vertex attributes in the specified vertex.

Mesh:setVertex( index, vertex )

index	number	The index of the the vertex you want to modify (one-based).
vertex	table	A table with vertex information, in the form of {attributecomponent, ...}.

vertex.attributecomponent	number	The first component of the first vertex attribute in the specified vertex.
vertex....	number	Additional components of all vertex attributes in the specified vertex.

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

index	number	The index of the the vertex you want to modify (one-based).
x	number	The position of the vertex on the x-axis.
y	number	The position of the vertex on the y-axis.
u	number	The horizontal component of the texture coordinate.
v	number	The vertical component of the texture coordinate.
r (1)	number	The red component of the vertex's color.
g (1)	number	The green component of the vertex's color.
b (1)	number	The blue component of the vertex's color.
a (1)	number	The alpha component of the vertex's color.

Mesh:setVertex( index, vertex )

index	number	The index of the the vertex you want to modify (one-based).
vertex	table	A table with vertex information.

vertex.1	number	The position of the vertex on the x-axis.
vertex.2	number	The position of the vertex on the y-axis.
vertex.3	number	The u texture coordinate. Texture coordinates are normally in the range of 1, but can be greater or less (see WrapMode.)
vertex.4	number	The v texture coordinate. Texture coordinates are normally in the range of 1, but can be greater or less (see WrapMode.)
vertex.5 (1)	number	The red color component.
vertex.6 (1)	number	The green color component.
vertex.7 (1)	number	The blue color component.
vertex.8 (1)	number	The alpha color component.

Mesh:setVertexAttribute

Sets the properties of a specific attribute within a vertex in the Mesh.

Meshes without a custom vertex format specified in love.graphics.newMesh have position as their first attribute, texture coordinates as their second attribute, and color as their third attribute.

Mesh:setVertexAttribute( vertexindex, attributeindex, value1, value2, ... )

vertexindex	number	The index of the the vertex to be modified (one-based).
attributeindex	number	The index of the attribute within the vertex to be modified (one-based).
value1	number	The new value for the first component of the attribute.
value2	number	The new value for the second component of the attribute.
...	number	Any additional vertex attribute components.

Mesh:setVertexMap

Sets the vertex map for the Mesh. The vertex map describes the order in which the vertices are used when the Mesh is drawn. The vertices, vertex map, and mesh draw mode work together to determine what exactly is displayed on the screen.

The vertex map allows you to re-order or reuse vertices when drawing without changing the actual vertex parameters or duplicating vertices. It is especially useful when combined with different Mesh Draw Modes.

Mesh:setVertexMap( map )

map

table

A table containing a list of vertex indices to use when drawing. Values must be in the range of Mesh:getVertexCount().

Mesh:setVertexMap( vi1, vi2, vi3 )

vi1	number	The index of the first vertex to use when drawing. Must be in the range of Mesh:getVertexCount().
vi2	number	The index of the second vertex to use when drawing.
vi3	number	The index of the third vertex to use when drawing.

Mesh:setVertexMap( data, datatype )

data	Data	Array of vertex indices to use when drawing. Values must be in the range of Mesh:getVertexCount()-1
datatype	IndexDataType	Datatype of the vertex indices array above.

Mesh:setVertices

Replaces a range of vertices in the Mesh with new ones. The total number of vertices in a Mesh cannot be changed after it has been created. This is often more efficient than calling Mesh:setVertex in a loop.

Mesh:setVertices( vertices, startvertex, count )

vertices

table

The table filled with vertex information tables for each vertex, in the form of {vertex, ...} where each vertex is a table in the form of {attributecomponent, ...}.

vertices.attributecomponent	number	The first component of the first vertex attribute in the vertex.
vertices....	number	Additional components of all vertex attributes in the vertex.
startvertex (1)	number	The index of the first vertex to replace.
count (all)	number	Amount of vertices to replace.

Mesh:setVertices( data, startvertex )

data	Data	A Data object to copy from. The contents of the Data must match the layout of this Mesh's vertex format.
startvertex (1)	number	The index of the first vertex to replace.

Mesh:setVertices( vertices )

vertices

table

The table filled with vertex information tables for each vertex as follows:

vertices.1	number	The position of the vertex on the x-axis.
vertices.2	number	The position of the vertex on the y-axis.
vertices.3	number	The horizontal component of the texture coordinate. Texture coordinates are normally in the range of 1, but can be greater or less (see WrapMode).
vertices.4	number	The vertical component of the texture coordinate. Texture coordinates are normally in the range of 1, but can be greater or less (see WrapMode).
vertices.5 (1)	number	The red color component.
vertices.6 (1)	number	The green color component.
vertices.7 (1)	number	The blue color component.
vertices.8 (1)	number	The alpha color component.

A ParticleSystem can be used to create particle effects like fire or smoke.

The particle system has to be created using update it in the update callback to see any changes in the particles emitted.

The particle system won't create any particles unless you call setParticleLifetime and setEmissionRate.

Constructors

love.graphics.newParticleSystem

Functions

ParticleSystem:clone

ParticleSystem:emit

ParticleSystem:get/setBufferSize

ParticleSystem:get/setColors

ParticleSystem:getCount

ParticleSystem:get/setDirection

ParticleSystem:get/setEmissionArea

ParticleSystem:get/setEmissionRate

ParticleSystem:get/setEmitterLifetime

ParticleSystem:get/setInsertMode

ParticleSystem:get/setLinearAcceleration

ParticleSystem:get/setLinearDamping

ParticleSystem:get/setOffset

ParticleSystem:get/setParticleLifetime

ParticleSystem:get/setPosition

ParticleSystem:get/setQuads

ParticleSystem:get/setRadialAcceleration

ParticleSystem:get/setRotation

ParticleSystem:get/setSizeVariation

ParticleSystem:get/setSizes

ParticleSystem:get/setSpeed

ParticleSystem:get/setSpin

ParticleSystem:get/setSpinVariation

ParticleSystem:get/setSpread

ParticleSystem:get/setTangentialAcceleration

ParticleSystem:get/setTexture

ParticleSystem:has/setRelativeRotation

ParticleSystem:isActive

ParticleSystem:isPaused

ParticleSystem:isStopped

ParticleSystem:moveTo

ParticleSystem:pause

ParticleSystem:reset

ParticleSystem:start

ParticleSystem:stop

ParticleSystem:update

Supertypes

ParticleSystem:clone

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

particlesystem = ParticleSystem:clone()

particlesystem

ParticleSystem:getBufferSize

The new identical copy of this ParticleSystem.

ParticleSystem:emit

Emits a burst of particles from the particle emitter.

ParticleSystem:emit( numparticles )

numparticles

number

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

Gets the maximum number of particles the ParticleSystem can have at once.

size = ParticleSystem:getBufferSize()

size

number

The maximum number of particles.

ParticleSystem:getColors

Gets the series of colors applied to the particle sprite.

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

r1, g1, b1, a1, r2, g2, b2, a2, r8, g8, b8, a8 = ParticleSystem:getColors()

r1	number	First color, red component (0-1).
g1	number	First color, green component (0-1).
b1	number	First color, blue component (0-1).
a1	number	First color, alpha component (0-1).
r2	number	Second color, red component (0-1).
g2	number	Second color, green component (0-1).
b2	number	Second color, blue component (0-1).
a2	number	Second color, alpha component (0-1).
r8	number	Eighth color, red component (0-1).
g8	number	Eighth color, green component (0-1).
b8	number	Eighth color, blue component (0-1).
a8	number	Eighth color, alpha component (0-1).

ParticleSystem:getCount

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

count = ParticleSystem:getCount()

count

number

The current number of live particles.

ParticleSystem:getDirection

Gets the direction of the particle emitter (in radians).

direction = ParticleSystem:getDirection()

direction

number

The direction of the emitter (radians).

ParticleSystem:getEmissionArea

Gets the area-based spawn parameters for the particles.

distribution, dx, dy, angle, directionRelativeToCenter = ParticleSystem:getEmissionArea()

distribution	AreaSpreadDistribution	The type of distribution for new particles.
dx	number	The maximum spawn distance from the emitter along the x-axis for uniform distribution, or the standard deviation along the x-axis for normal distribution.
dy	number	The maximum spawn distance from the emitter along the y-axis for uniform distribution, or the standard deviation along the y-axis for normal distribution.
angle	number	The angle in radians of the emission area.
directionRelativeToCenter	boolean	True if newly spawned particles will be oriented relative to the center of the emission area, false otherwise.

ParticleSystem:getEmissionRate

Gets the amount of particles emitted per second.

rate = ParticleSystem:getEmissionRate()

rate

number

The amount of particles per second.

ParticleSystem:getEmitterLifetime

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

life = ParticleSystem:getEmitterLifetime()

life

number

The lifetime of the emitter (in seconds).

ParticleSystem:getInsertMode

Gets the mode used when the ParticleSystem adds new particles.

mode = ParticleSystem:getInsertMode()

mode

ParticleInsertMode

The mode used when the ParticleSystem adds new particles.

ParticleSystem:getLinearAcceleration

Gets the linear acceleration (acceleration along the x and y axes) for particles.

Every particle created will accelerate along the x and y axes between xmin,ymin and xmax,ymax.

xmin, ymin, xmax, ymax = ParticleSystem:getLinearAcceleration()

xmin	number	The minimum acceleration along the x axis.
ymin	number	The minimum acceleration along the y axis.
xmax	number	The maximum acceleration along the x axis.
ymax	number	The maximum acceleration along the y axis.

ParticleSystem:getLinearDamping

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

min, max = ParticleSystem:getLinearDamping()

min	number	The minimum amount of linear damping applied to particles.
max	number	The maximum amount of linear damping applied to particles.

ParticleSystem:getOffset

Gets the particle image's draw offset.

ox, oy = ParticleSystem:getOffset()

ox	number	The x coordinate of the particle image's draw offset.
oy	number	The y coordinate of the particle image's draw offset.

ParticleSystem:getParticleLifetime

Gets the lifetime of the particles.

min, max = ParticleSystem:getParticleLifetime()

min	number	The minimum life of the particles (in seconds).
max	number	The maximum life of the particles (in seconds).

ParticleSystem:getPosition

Gets the position of the emitter.

x, y = ParticleSystem:getPosition()

x	number	Position along x-axis.
y	number	Position along y-axis.

ParticleSystem:getQuads

Gets the series of Quads used for the particle sprites.

quads = ParticleSystem:getQuads()

quads

table

A table containing the Quads used.

ParticleSystem:getRadialAcceleration

Gets the radial acceleration (away from the emitter).

min, max = ParticleSystem:getRadialAcceleration()

min	number	The minimum acceleration.
max	number	The maximum acceleration.

ParticleSystem:getRotation

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

min, max = ParticleSystem:getRotation()

min	number	The minimum initial angle (radians).
max	number	The maximum initial angle (radians).

ParticleSystem:getSizeVariation

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

variation = ParticleSystem:getSizeVariation()

variation

number

The amount of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:getSizes

Gets the series of sizes by which the sprite is scaled. 1.0 is normal size. The particle system will interpolate between each size evenly over the particle's lifetime.

size1, size2, size8 = ParticleSystem:getSizes()

size1	number	The first size.
size2	number	The second size.
size8	number	The eighth size.

ParticleSystem:getSpeed

Gets the speed of the particles.

min, max = ParticleSystem:getSpeed()

min	number	The minimum linear speed of the particles.
max	number	The maximum linear speed of the particles.

ParticleSystem:getSpin

Gets the spin of the sprite.

min, max, variation = ParticleSystem:getSpin()

min	number	The minimum spin (radians per second).
max	number	The maximum spin (radians per second).
variation	number	The degree of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:getSpinVariation

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

variation = ParticleSystem:getSpinVariation()

variation

number

The amount of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:getSpread

Gets the amount of directional spread of the particle emitter (in radians).

spread = ParticleSystem:getSpread()

spread

number

The spread of the emitter (radians).

ParticleSystem:getTangentialAcceleration

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

min, max = ParticleSystem:getTangentialAcceleration()

min	number	The minimum acceleration.
max	number	The maximum acceleration.

ParticleSystem:getTexture

Gets the texture (Image or Canvas) used for the particles.

texture = ParticleSystem:getTexture()

texture

ParticleSystem:hasRelativeRotation

The Image or Canvas used for the particles.

Gets whether particle angles and rotations are relative to their velocities. If enabled, particles are aligned to the angle of their velocities and rotate relative to that angle.

enable = ParticleSystem:hasRelativeRotation()

enable

boolean

True if relative particle rotation is enabled, false if it's disabled.

ParticleSystem:isActive

Checks whether the particle system is actively emitting particles.

active = ParticleSystem:isActive()

active

boolean

True if system is active, false otherwise.

ParticleSystem:isPaused

Checks whether the particle system is paused.

paused = ParticleSystem:isPaused()

paused

boolean

True if system is paused, false otherwise.

ParticleSystem:isStopped

Checks whether the particle system is stopped.

stopped = ParticleSystem:isStopped()

stopped

boolean

True if system is stopped, false otherwise.

ParticleSystem:moveTo

Moves the position of the emitter. This results in smoother particle spawning behaviour than if ParticleSystem:setPosition is used every frame.

ParticleSystem:moveTo( x, y )

x	number	Position along x-axis.
y	number	Position along y-axis.

ParticleSystem:pause

Pauses the particle emitter.

ParticleSystem:pause()

ParticleSystem:reset

Resets the particle emitter, removing any existing particles and resetting the lifetime counter.

ParticleSystem:reset()

ParticleSystem:setBufferSize

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

ParticleSystem:setBufferSize( size )

size

number

The buffer size.

ParticleSystem:setColors

Sets a series of colors to apply to the particle sprite. The particle system will interpolate between each color evenly over the particle's lifetime.

Arguments can be passed in groups of four, representing the components of the desired RGBA value, or as tables of RGBA component values, with a default alpha value of 1 if only three values are given. At least one color must be specified. A maximum of eight may be used.

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

ParticleSystem:setColors( r1, g1, b1, a1, r2, g2, b2, a2, r8, g8, b8, a8 )

r1	number	First color, red component (0-1).
g1	number	First color, green component (0-1).
b1	number	First color, blue component (0-1).
a1 (1)	number	First color, alpha component (0-1).
r2 (nil)	number	Second color, red component (0-1).
g2 (nil)	number	Second color, green component (0-1).
b2 (nil)	number	Second color, blue component (0-1).
a2 (1)	number	Second color, alpha component (0-1).
r8 (nil)	number	Eighth color, red component (0-1).
g8 (nil)	number	Eighth color, green component (0-1).
b8 (nil)	number	Eighth color, blue component (0-1).
a8 (1)	number	Eighth color, alpha component (0-1).

ParticleSystem:setColors( rgba1, rgba2, rgba8 )

rgba1	table	First color, a numerical indexed table with the red, green, blue and alpha values as numbers (0-1). The alpha is optional and defaults to 1 if it is left out.
rgba2 (nil)	table	Second color, a numerical indexed table with the red, green, blue and alpha values as numbers (0-1). The alpha is optional and defaults to 1 if it is left out.
rgba8 (nil)	table	Eighth color, a numerical indexed table with the red, green, blue and alpha values as numbers (0-1). The alpha is optional and defaults to 1 if it is left out.

ParticleSystem:setDirection

Sets the direction the particles will be emitted in.

ParticleSystem:setDirection( direction )

direction

number

The direction of the particles (in radians).

ParticleSystem:setEmissionArea

Sets area-based spawn parameters for the particles. Newly created particles will spawn in an area around the emitter based on the parameters to this function.

ParticleSystem:setEmissionArea( distribution, dx, dy, angle, directionRelativeToCenter )

distribution	AreaSpreadDistribution	The type of distribution for new particles.
dx	number	The maximum spawn distance from the emitter along the x-axis for uniform distribution, or the standard deviation along the x-axis for normal distribution.
dy	number	The maximum spawn distance from the emitter along the y-axis for uniform distribution, or the standard deviation along the y-axis for normal distribution.
angle (0)	number	The angle in radians of the emission area.
directionRelativeToCenter (false)	boolean	True if newly spawned particles will be oriented relative to the center of the emission area, false otherwise.

ParticleSystem:setEmissionRate

Sets the amount of particles emitted per second.

ParticleSystem:setEmissionRate( rate )

rate

number

The amount of particles per second.

ParticleSystem:setEmitterLifetime

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

ParticleSystem:setEmitterLifetime( life )

life

number

The lifetime of the emitter (in seconds).

ParticleSystem:setInsertMode

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

ParticleSystem:setInsertMode( mode )

mode

ParticleInsertMode

The mode to use when the ParticleSystem adds new particles.

ParticleSystem:setLinearAcceleration

Sets the linear acceleration (acceleration along the x and y axes) for particles.

Every particle created will accelerate along the x and y axes between xmin,ymin and xmax,ymax.

ParticleSystem:setLinearAcceleration( xmin, ymin, xmax, ymax )

xmin	number	The minimum acceleration along the x axis.
ymin	number	The minimum acceleration along the y axis.
xmax (xmin)	number	The maximum acceleration along the x axis.
ymax (ymin)	number	The maximum acceleration along the y axis.

ParticleSystem:setLinearDamping

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

ParticleSystem:setLinearDamping( min, max )

min	number	The minimum amount of linear damping applied to particles.
max (min)	number	The maximum amount of linear damping applied to particles.

ParticleSystem:setOffset

Set the offset position which the particle sprite is rotated around.

If this function is not used, the particles rotate around their center.

ParticleSystem:setOffset( x, y )

x	number	The x coordinate of the rotation offset.
y	number	The y coordinate of the rotation offset.

ParticleSystem:setParticleLifetime

Sets the lifetime of the particles.

ParticleSystem:setParticleLifetime( min, max )

min	number	The minimum life of the particles (in seconds).
max (min)	number	The maximum life of the particles (in seconds).

ParticleSystem:setPosition

Sets the position of the emitter.

ParticleSystem:setPosition( x, y )

x	number	Position along x-axis.
y	number	Position along y-axis.

ParticleSystem:setQuads

Sets a series of Quads to use for the particle sprites. Particles will choose a Quad from the list based on the particle's current lifetime, allowing for the use of animated sprite sheets with ParticleSystems.

ParticleSystem:setQuads( quad1, quad2 )

quad1	Quad	The first Quad to use.
quad2	Quad	The second Quad to use.

ParticleSystem:setQuads( quads )

quads

table

A table containing the Quads to use.

ParticleSystem:setRadialAcceleration

Set the radial acceleration (away from the emitter).

ParticleSystem:setRadialAcceleration( min, max )

min	number	The minimum acceleration.
max (min)	number	The maximum acceleration.

ParticleSystem:setRelativeRotation

Sets whether particle angles and rotations are relative to their velocities. If enabled, particles are aligned to the angle of their velocities and rotate relative to that angle.

ParticleSystem:setRelativeRotation( enable )

enable

boolean

True to enable relative particle rotation, false to disable it.

ParticleSystem:setRotation

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

ParticleSystem:setRotation( min, max )

min	number	The minimum initial angle (radians).
max (min)	number	The maximum initial angle (radians).

ParticleSystem:setSizeVariation

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

ParticleSystem:setSizeVariation( variation )

variation

number

The amount of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:setSizes

Sets a series of sizes by which to scale a particle sprite. 1.0 is normal size. The particle system will interpolate between each size evenly over the particle's lifetime.

At least one size must be specified. A maximum of eight may be used.

ParticleSystem:setSizes( size1, size2, size8 )

size1	number	The first size.
size2 (nil)	number	The second size.
size8 (nil)	number	The eighth size.

ParticleSystem:setSpeed

Sets the speed of the particles.

ParticleSystem:setSpeed( min, max )

min	number	The minimum linear speed of the particles.
max (min)	number	The maximum linear speed of the particles.

ParticleSystem:setSpin

Sets the spin of the sprite.

ParticleSystem:setSpin( min, max )

min	number	The minimum spin (radians per second).
max (min)	number	The maximum spin (radians per second).

ParticleSystem:setSpinVariation

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

ParticleSystem:setSpinVariation( variation )

variation

number

The amount of variation (0 meaning no variation and 1 meaning full variation between start and end).

ParticleSystem:setSpread

Sets the amount of spread for the system.

ParticleSystem:setSpread( spread )

spread

number

The amount of spread (radians).

ParticleSystem:setTangentialAcceleration

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

ParticleSystem:setTangentialAcceleration( min, max )

min	number	The minimum acceleration.
max (min)	number	The maximum acceleration.

ParticleSystem:setTexture

Sets the texture (Image or Canvas) to be used for the particles.

ParticleSystem:setTexture( texture )

texture

An Image or Canvas to use for the particles.

ParticleSystem:start

Starts the particle emitter.

ParticleSystem:start()

ParticleSystem:stop

Stops the particle emitter, resetting the lifetime counter.

ParticleSystem:stop()

ParticleSystem:update

Updates the particle system; moving, creating and killing particles.

ParticleSystem:update( dt )

number

The time (seconds) since last frame.

Quad

A quadrilateral (a polygon with four sides and four corners) with texture coordinate information.

Quads can be used to select part of a texture to draw. In this way, one large texture atlas can be loaded, and then split up into sub-images.

Constructors

love.graphics.newQuad

Functions

Quad:getTextureDimensions

Quad:get/setViewport

Supertypes

Quad:getTextureDimensions

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

sw, sh = Quad:getTextureDimensions()

sw	number	The Texture width used by the Quad.
sh	number	The Texture height used by the Quad.

Quad:getViewport

Gets the current viewport of this Quad.

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

x	number	The top-left corner along the x-axis.
y	number	The top-left corner along the y-axis.
w	number	The width of the viewport.
h	number	The height of the viewport.

Quad:setViewport

Sets the texture coordinates according to a viewport.

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

x	number	The top-left corner along the x-axis.
y	number	The top-left corner along the y-axis.
w	number	The width of the viewport.
h	number	The height of the viewport.
sw	number	The reference width, the width of the Image. (Must be greater than 0.)
sh	number	The reference height, the height of the Image. (Must be greater than 0.)

A Shader is used for advanced hardware-accelerated pixel or vertex manipulation. These effects are written in a language based on GLSL (OpenGL Shading Language) with a few things simplified for easier coding.

Potential uses for shaders include HDR/bloom, motion blur, grayscale/invert/sepia/any kind of color effect, reflection/refraction, distortions, bump mapping, and much more! Here is a collection of basic shaders and good starting point to learn: https://github.com/vrld/moonshine

Constructors

love.graphics.getShader

love.graphics.newShader

Functions

Shader:getWarnings

Shader:hasUniform

Shader:send

Shader:sendColor

Supertypes

Shader:getWarnings

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

warnings = Shader:getWarnings()

warnings

string

Warning and error messages (if any).

Shader:hasUniform

Gets whether a uniform / extern variable exists in the Shader.

If a graphics driver's shader compiler determines that a uniform / extern variable doesn't affect the final output of the shader, it may optimize the variable out. This function will return false in that case.

hasuniform = Shader:hasUniform( name )

hasuniform

boolean

Whether the uniform exists in the shader and affects its final output.

name

string

The name of the uniform variable.

Shader:send

Sends one or more values to a special (''uniform'') variable inside the shader. Uniform variables have to be marked using the ''uniform'' or ''extern'' keyword, e.g.

uniform float time; // 'float' is the typical number type used in GLSL shaders.

uniform float varsvec2 light_pos;

uniform vec4 colors[4;

The corresponding send calls would be

shader:send('time', t)

shader:send('vars',a,b)

shader:send('light_pos', {light_x, light_y})

shader:send('colors', {r1, g1, b1, a1}, {r2, g2, b2, a2}, {r3, g3, b3, a3}, {r4, g4, b4, a4})

Uniform / extern variables are read-only in the shader code and remain constant until modified by a Shader:send call. Uniform variables can be accessed in both the Vertex and Pixel components of a shader, as long as the variable is declared in each.

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

name	string	Name of the number to send to the shader.
number	number	Number to send to store in the uniform variable.
...	number	Additional numbers to send if the uniform variable is an array.

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

name	string	Name of the vector to send to the shader.
vector	table	Numbers to send to the uniform variable as a vector. The number of elements in the table determines the type of the vector (e.g. two numbers -> vec2). At least two and at most four numbers can be used.
...	table	Additional vectors to send if the uniform variable is an array. All vectors need to be of the same size (e.g. only vec3's).

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

name	string	Name of the matrix to send to the shader.
matrix	table	2x2, 3x3, or 4x4 matrix to send to the uniform variable. Using table form: {{a,b,c,d}, {e,f,g,h}, ... } or (since version 0.10.2) {a,b,c,d, e,f,g,h, ...}. The order in 0.10.2 is column-major; starting in 11.0 it's row-major instead.
...	table	Additional matrices of the same type as ''matrix'' to store in a uniform array.

Shader:send( name, texture )

name	string	Name of the Texture to send to the shader.
texture	Texture	Texture (Image or Canvas) to send to the uniform variable.

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

name	string	Name of the boolean to send to the shader.
boolean	boolean	Boolean to send to store in the uniform variable.
...	boolean	Additional booleans to send if the uniform variable is an array.

Shader:send( name, matrixlayout, matrix, ... )

name	string	Name of the matrix to send to the shader.
matrixlayout	MatrixLayout	The layout (row- or column-major) of the matrix.
matrix	table	2x2, 3x3, or 4x4 matrix to send to the uniform variable. Using table form: {{a,b,c,d}, {e,f,g,h}, ... } or {a,b,c,d, e,f,g,h, ...}.
...	table	Additional matrices of the same type as ''matrix'' to store in a uniform array.

Shader:send( name, data, offset, size )

name	string	Name of the uniform to send to the shader.
data	Data	Data object containing the values to send.
offset (0)	number	Offset in bytes from the start of the Data object.
size (all)	number	Size in bytes of the data to send. If nil, as many bytes as the specified uniform uses will be copied.

Shader:send( name, data, matrixlayout, offset, size )

name	string	Name of the uniform matrix to send to the shader.
data	Data	Data object containing the values to send.
matrixlayout	MatrixLayout	The layout (row- or column-major) of the matrix in memory.
offset (0)	number	Offset in bytes from the start of the Data object.
size (all)	number	Size in bytes of the data to send. If nil, as many bytes as the specified uniform uses will be copied.

Shader:send( name, matrixlayout, data, offset, size )

name	string	Name of the uniform matrix to send to the shader.
matrixlayout	MatrixLayout	The layout (row- or column-major) of the matrix in memory.
data	Data	Data object containing the values to send.
offset (0)	number	Offset in bytes from the start of the Data object.
size (all)	number	Size in bytes of the data to send. If nil, as many bytes as the specified uniform uses will be copied.

Shader:sendColor

Sends one or more colors to a special (''extern'' / ''uniform'') vec3 or vec4 variable inside the shader. The color components must be in the range of 1. The colors are gamma-corrected if global gamma-correction is enabled.

Extern variables must be marked using the ''extern'' keyword, e.g.

extern vec4 Color;

The corresponding sendColor call would be

shader:sendColor('Color', {r, g, b, a})

Extern variables can be accessed in both the Vertex and Pixel stages of a shader, as long as the variable is declared in each.

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

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

name	string	The name of the color extern variable to send to in the shader.
color	table	A table with red, green, blue, and optional alpha color components in the range of 1 to send to the extern as a vector.
...	table	Additional colors to send in case the extern is an array. All colors need to be of the same size (e.g. only vec3's).

Using a single image, draw any number of identical copies of the image using a single call to love.graphics.draw(). This can be used, for example, to draw repeating copies of a single background image with high performance.

A SpriteBatch can be even more useful when the underlying image is a texture atlas (a single image file containing many independent images); by adding Quads to the batch, different sub-images from within the atlas can be drawn.

Constructors

love.graphics.newSpriteBatch

Functions

SpriteBatch:add

SpriteBatch:addLayer

SpriteBatch:attachAttribute

SpriteBatch:clear

SpriteBatch:flush

SpriteBatch:getBufferSize

SpriteBatch:get/setColor

SpriteBatch:getCount

SpriteBatch:get/setTexture

SpriteBatch:set

SpriteBatch:setDrawRange

SpriteBatch:setLayer

Supertypes

SpriteBatch:attachAttribute

SpriteBatch:add

Adds a sprite to the batch. Sprites are drawn in the order they are added.

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

number

An identifier for the added sprite.

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

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

number

An identifier for the added sprite.

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

SpriteBatch:addLayer

Adds a sprite to a batch created with an Array Texture.

spriteindex = SpriteBatch:addLayer( layerindex, x, y, r, sx, sy, ox, oy, kx, ky )

spriteindex

number

The index of the added sprite, for use with SpriteBatch:set or SpriteBatch:setLayer.

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

spriteindex = SpriteBatch:addLayer( layerindex, quad, x, y, r, sx, sy, ox, oy, kx, ky )

spriteindex

number

The index of the added sprite, for use with SpriteBatch:set or SpriteBatch:setLayer.

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

spriteindex = SpriteBatch:addLayer( layerindex, transform )

spriteindex

number

The index of the added sprite, for use with SpriteBatch:set or SpriteBatch:setLayer.

layerindex	number	The index of the layer to use for this sprite.
transform	Transform	A transform object.

spriteindex = SpriteBatch:addLayer( layerindex, quad, transform )

spriteindex

number

The index of the added sprite, for use with SpriteBatch:set or SpriteBatch:setLayer.

layerindex	number	The index of the layer to use for this sprite.
quad	Quad	The subsection of the texture's layer to use when drawing the sprite.
transform	Transform	A transform object.

Attaches a per-vertex attribute from a Mesh onto this SpriteBatch, for use when drawing. This can be combined with a Shader to augment a SpriteBatch with per-vertex or additional per-sprite information instead of just having per-sprite colors.

Each sprite in a SpriteBatch has 4 vertices in the following order: top-left, bottom-left, top-right, bottom-right. The index returned by SpriteBatch:add (and used by SpriteBatch:set) can used to determine the first vertex of a specific sprite with the formula 1 + 4 * ( id - 1 ).

SpriteBatch:attachAttribute( name, mesh )

name	string	The name of the vertex attribute to attach.
mesh	Mesh	The Mesh to get the vertex attribute from.

SpriteBatch:clear

Removes all sprites from the buffer.

SpriteBatch:clear()

SpriteBatch:flush

Immediately sends all new and modified sprite data in the batch to the graphics card.

Normally it isn't necessary to call this method as love.graphics.draw(spritebatch, ...) will do it automatically if needed, but explicitly using SpriteBatch:flush gives more control over when the work happens.

If this method is used, it generally shouldn't be called more than once (at most) between love.graphics.draw(spritebatch, ...) calls.

SpriteBatch:flush()

SpriteBatch:getBufferSize

Gets the maximum number of sprites the SpriteBatch can hold.

size = SpriteBatch:getBufferSize()

size

number

The maximum number of sprites the batch can hold.

SpriteBatch:getColor

Gets the color that will be used for the next add and set operations.

If no color has been set with SpriteBatch:setColor or the current SpriteBatch color has been cleared, this method will return nil.

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

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

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

SpriteBatch:getCount

Gets the number of sprites currently in the SpriteBatch.

count = SpriteBatch:getCount()

count

number

The number of sprites currently in the batch.

SpriteBatch:getTexture

Gets the texture (Image or Canvas) used by the SpriteBatch.

texture = SpriteBatch:getTexture()

texture

The Image or Canvas used by the SpriteBatch.

SpriteBatch:set

Changes a sprite in the batch. This requires the sprite index returned by SpriteBatch:add or SpriteBatch:addLayer.

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

spriteindex	number	The index of the sprite that will be changed.
x	number	The position to draw the object (x-axis).
y	number	The position to draw the object (y-axis).
r (0)	number	Orientation (radians).
sx (1)	number	Scale factor (x-axis).
sy (sx)	number	Scale factor (y-axis).
ox (0)	number	Origin offset (x-axis).
oy (0)	number	Origin offset (y-axis).
kx (0)	number	Shear factor (x-axis).
ky (0)	number	Shear factor (y-axis).

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

spriteindex	number	The index of the sprite that will be changed.
quad	Quad	The Quad used on the image of the batch.
x	number	The position to draw the object (x-axis).
y	number	The position to draw the object (y-axis).
r (0)	number	Orientation (radians).
sx (1)	number	Scale factor (x-axis).
sy (sx)	number	Scale factor (y-axis).
ox (0)	number	Origin offset (x-axis).
oy (0)	number	Origin offset (y-axis).
kx (0)	number	Shear factor (x-axis).
ky (0)	number	Shear factor (y-axis).

SpriteBatch:setColor

Sets the color that will be used for the next add and set operations. Calling the function without arguments will disable all per-sprite colors for the SpriteBatch.

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

In version 0.9.2 and older, the global color set with love.graphics.setColor will not work on the SpriteBatch if any of the sprites has its own color.

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

r	number	The amount of red.
g	number	The amount of green.
b	number	The amount of blue.
a (1)	number	The amount of alpha.

SpriteBatch:setColor()

SpriteBatch:setDrawRange

Restricts the drawn sprites in the SpriteBatch to a subset of the total.

SpriteBatch:setDrawRange( start, count )

start	number	The index of the first sprite to draw. Index 1 corresponds to the first sprite added with SpriteBatch:add.
count	number	The number of sprites to draw.

SpriteBatch:setDrawRange()

SpriteBatch:setLayer

Changes a sprite previously added with add or addLayer, in a batch created with an Array Texture.

SpriteBatch:setLayer( spriteindex, layerindex, x, y, r, sx, sy, ox, oy, kx, ky )

spriteindex	number	The index of the existing sprite to replace.
layerindex	number	The index of the layer in the Array Texture to use for this sprite.
x (0)	number	The position to draw the sprite (x-axis).
y (0)	number	The position to draw the sprite (y-axis).
r (0)	number	Orientation (radians).
sx (1)	number	Scale factor (x-axis).
sy (sx)	number	Scale factor (y-axis).
ox (0)	number	Origin offset (x-axis).
oy (0)	number	Origin offset (y-axis).
kx (0)	number	Shearing factor (x-axis).
ky (0)	number	Shearing factor (y-axis).

SpriteBatch:setLayer( spriteindex, layerindex, quad, x, y, r, sx, sy, ox, oy, kx, ky )

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

SpriteBatch:setLayer( spriteindex, layerindex, transform )

spriteindex	number	The index of the existing sprite to replace.
layerindex	number	The index of the layer to use for the sprite.
transform	Transform	A transform object.

SpriteBatch:setLayer( spriteindex, layerindex, quad, transform )

spriteindex	number	The index of the existing sprite to replace.
layerindex	number	The index of the layer to use for the sprite.
quad	Quad	The subsection of the texture's layer to use when drawing the sprite.
transform	Transform	A transform object.

SpriteBatch:setTexture

Sets the texture (Image or Canvas) used for the sprites in the batch, when drawing.

SpriteBatch:setTexture( texture )

texture

The new Image or Canvas to use for the sprites in the batch.

Text

Drawable text.

Constructors

love.graphics.newText

Functions

Text:add

Text:addf

Text:clear

Text:getDimensions

Text:get/setFont

Text:getHeight

Text:getWidth

Text:set

Text:setf

Supertypes

Text:add

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

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

index

number

An index number that can be used with Text:getWidth or Text:getHeight.

textstring	string	The text to add to the object.
x (0)	number	The position of the new text on the x-axis.
y (0)	number	The position of the new text on the y-axis.
angle (0)	number	The orientation of the new text in radians.
sx (1)	number	Scale factor on the x-axis.
sy (sx)	number	Scale factor on the y-axis.
ox (0)	number	Origin offset on the x-axis.
oy (0)	number	Origin offset on the y-axis.
kx (0)	number	Shearing / skew factor on the x-axis.
ky (0)	number	Shearing / skew factor on the y-axis.

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

index

number

An index number that can be used with Text:getWidth or Text:getHeight.

coloredtext

table

A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.

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

Text:addf

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

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

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

index

number

An index number that can be used with Text:getWidth or Text:getHeight.

textstring	string	The text to add to the object.
wraplimit	number	The maximum width in pixels of the text before it gets automatically wrapped to a new line.
align	AlignMode	The alignment of the text.
x	number	The position of the new text (x-axis).
y	number	The position of the new text (y-axis).
angle (0)	number	Orientation (radians).
sx (1)	number	Scale factor (x-axis).
sy (sx)	number	Scale factor (y-axis).
ox (0)	number	Origin offset (x-axis).
oy (0)	number	Origin offset (y-axis).
kx (0)	number	Shearing / skew factor (x-axis).
ky (0)	number	Shearing / skew factor (y-axis).

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

index

number

An index number that can be used with Text:getWidth or Text:getHeight.

coloredtext

table

A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.

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

Text:clear

Clears the contents of the Text object.

Text:clear()

Text:getDimensions

Gets the width and height of the text in pixels.

width, height = Text:getDimensions()

width	number	The width of the text. If multiple sub-strings have been added with Text:add, the width of the last sub-string is returned.
height	number	The height of the text. If multiple sub-strings have been added with Text:add, the height of the last sub-string is returned.

width, height = Text:getDimensions( index )

width	number	The width of the sub-string (before scaling and other transformations).
height	number	The height of the sub-string (before scaling and other transformations).

index

number

An index number returned by Text:add or Text:addf.

Text:getFont

Gets the Font used with the Text object.

font = Text:getFont()

font

The font used with this Text object.

Text:getHeight

Gets the height of the text in pixels.

height = Text:getHeight()

height

number

The height of the text. If multiple sub-strings have been added with Text:add, the height of the last sub-string is returned.

height = Text:getHeight( index )

height

number

The height of the sub-string (before scaling and other transformations).

index

number

An index number returned by Text:add or Text:addf.

Text:getWidth

Gets the width of the text in pixels.

width = Text:getWidth()

width

number

The width of the text. If multiple sub-strings have been added with Text:add, the width of the last sub-string is returned.

width = Text:getWidth( index )

width

number

The width of the sub-string (before scaling and other transformations).

index

number

An index number returned by Text:add or Text:addf.

Text:set

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

Text:set( textstring )

textstring

string

The new string of text to use.

Text:set( coloredtext )

coloredtext

table

A table containing colors and strings to use as the new text, in the form of {color1, string1, color2, string2, ...}.

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

Text:setFont

Replaces the Font used with the text.

Text:setFont( font )

font

The new font to use with this Text object.

Text:setf

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

Text:setf( textstring, wraplimit, align )

textstring	string	The new string of text to use.
wraplimit	number	The maximum width in pixels of the text before it gets automatically wrapped to a new line.
align	AlignMode	The alignment of the text.

Text:setf( coloredtext, wraplimit, align )

coloredtext

table

A table containing colors and strings to use as the new text, in the form of {color1, string1, color2, string2, ...}.

coloredtext.color1	table	A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string1	string	A string of text which has a color specified by the previous color.
coloredtext.color2	table	A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
coloredtext.string2	string	A string of text which has a color specified by the previous color.
coloredtext....	tables and strings	Additional colors and strings.
wraplimit	number	The maximum width in pixels of the text before it gets automatically wrapped to a new line.
align	AlignMode	The alignment of the text.

Superclass for drawable objects which represent a texture. All Textures can be drawn with Quads. This is an abstract type that can't be created directly.

Functions

Texture:getDPIScale

Texture:getDepth

Texture:get/setDepthSampleMode

Texture:getDimensions

Texture:get/setFilter

Texture:getFormat

Texture:getHeight

Texture:getLayerCount

Texture:getMipmapCount

Texture:get/setMipmapFilter

Texture:getPixelDimensions

Texture:getPixelHeight

Texture:getPixelWidth

Texture:getTextureType

Texture:getWidth

Texture:get/setWrap

Texture:isReadable

Supertypes

Texture:getDepthSampleMode

Texture:getDPIScale

Gets the DPI scale factor of the Texture.

The DPI scale factor represents relative pixel density. A DPI scale factor of 2 means the texture has twice the pixel density in each dimension (4 times as many pixels in the same area) compared to a texture with a DPI scale factor of 1.

For example, a texture with pixel dimensions of 100x100 with a DPI scale factor of 2 will be drawn as if it was 50x50. This is useful with high-dpi / retina displays to easily allow swapping out higher or lower pixel density Images and Canvases without needing any extra manual scaling logic.

dpiscale = Texture:getDPIScale()

dpiscale

number

The DPI scale factor of the Texture.

Texture:getDepth

Gets the depth of a Volume Texture. Returns 1 for 2D, Cubemap, and Array textures.

depth = Texture:getDepth()

depth

number

The depth of the volume Texture.

Gets the comparison mode used when sampling from a depth texture in a shader.

Depth texture comparison modes are advanced low-level functionality typically used with shadow mapping in 3D.

compare = Texture:getDepthSampleMode()

compare (nil)

CompareMode

The comparison mode used when sampling from this texture in a shader, or nil if setDepthSampleMode has not been called on this Texture.

Texture:getDimensions

Gets the width and height of the Texture.

width, height = Texture:getDimensions()

width	number	The width of the Texture.
height	number	The height of the Texture.

Texture:getFilter

Gets the filter mode of the Texture.

min, mag, anisotropy = Texture:getFilter()

min	FilterMode	Filter mode to use when minifying the texture (rendering it at a smaller size on-screen than its size in pixels).
mag	FilterMode	Filter mode to use when magnifying the texture (rendering it at a smaller size on-screen than its size in pixels).
anisotropy	number	Maximum amount of anisotropic filtering used.

Texture:getFormat

Gets the pixel format of the Texture.

format = Texture:getFormat()

format

Texture:getPixelDimensions

The pixel format the Texture was created with.

Texture:getHeight

Gets the height of the Texture.

height = Texture:getHeight()

height

number

The height of the Texture.

Texture:getLayerCount

Gets the number of layers / slices in an Array Texture. Returns 1 for 2D, Cubemap, and Volume textures.

layers = Texture:getLayerCount()

layers

number

The number of layers in the Array Texture.

Texture:getMipmapCount

Gets the number of mipmaps contained in the Texture. If the texture was not created with mipmaps, it will return 1.

mipmaps = Texture:getMipmapCount()

mipmaps

number

The number of mipmaps in the Texture.

Texture:getMipmapFilter

Gets the mipmap filter mode for a Texture. Prior to 11.0 this method only worked on Images.

mode, sharpness = Texture:getMipmapFilter()

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

Gets the width and height in pixels of the Texture.

Texture:getDimensions gets the dimensions of the texture in units scaled by the texture's DPI scale factor, rather than pixels. Use getDimensions for calculations related to drawing the texture (calculating an origin offset, for example), and getPixelDimensions only when dealing specifically with pixels, for example when using Canvas:newImageData.

pixelwidth, pixelheight = Texture:getPixelDimensions()

pixelwidth	number	The width of the Texture, in pixels.
pixelheight	number	The height of the Texture, in pixels.

Texture:getPixelHeight

Gets the height in pixels of the Texture.

DPI scale factor, rather than pixels. Use getHeight for calculations related to drawing the texture (calculating an origin offset, for example), and getPixelHeight only when dealing specifically with pixels, for example when using Canvas:newImageData.

pixelheight = Texture:getPixelHeight()

pixelheight

number

The height of the Texture, in pixels.

Texture:getPixelWidth

Gets the width in pixels of the Texture.

DPI scale factor, rather than pixels. Use getWidth for calculations related to drawing the texture (calculating an origin offset, for example), and getPixelWidth only when dealing specifically with pixels, for example when using Canvas:newImageData.

pixelwidth = Texture:getPixelWidth()

pixelwidth

number

The width of the Texture, in pixels.

Texture:getTextureType

Gets the type of the Texture.

texturetype = Texture:getTextureType()

texturetype

TextureType

The type of the Texture.

Texture:getWidth

Gets the width of the Texture.

width = Texture:getWidth()

width

number

The width of the Texture.

Texture:getWrap

Gets the wrapping properties of a Texture.

This function returns the currently set horizontal and vertical wrapping modes for the texture.

horiz, vert, depth = Texture:getWrap()

horiz	WrapMode	Horizontal wrapping mode of the texture.
vert	WrapMode	Vertical wrapping mode of the texture.
depth	WrapMode	Wrapping mode for the z-axis of a Volume texture.

Texture:isReadable

Gets whether the Texture can be drawn and sent to a Shader.

Canvases created with stencil and/or depth PixelFormats are not readable by default, unless readable=true is specified in the settings table passed into love.graphics.newCanvas.

Non-readable Canvases can still be rendered to.

readable = Texture:isReadable()

readable

boolean

Whether the Texture is readable.

Texture:setDepthSampleMode

Sets the comparison mode used when sampling from a depth texture in a shader. Depth texture comparison modes are advanced low-level functionality typically used with shadow mapping in 3D.

When using a depth texture with a comparison mode set in a shader, it must be declared as a sampler2DShadow and used in a GLSL 3 Shader. The result of accessing the texture in the shader will return a float between 0 and 1, proportional to the number of samples (up to 4 samples will be used if bilinear filtering is enabled) that passed the test set by the comparison operation.

Depth texture comparison can only be used with readable depth-formatted Canvases.

Texture:setDepthSampleMode( compare )

compare

CompareMode

The comparison mode used when sampling from this texture in a shader.

Texture:setFilter

Sets the filter mode of the Texture.

Texture:setFilter( min, mag, anisotropy )

min	FilterMode	Filter mode to use when minifying the texture (rendering it at a smaller size on-screen than its size in pixels).
mag (min)	FilterMode	Filter mode to use when magnifying the texture (rendering it at a larger size on-screen than its size in pixels).
anisotropy (1)	number	Maximum amount of anisotropic filtering to use.

Texture:setMipmapFilter

Sets the mipmap filter mode for a Texture. Prior to 11.0 this method only worked on Images.

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

In created with the mipmaps flag enabled for the mipmap filter to have any effect. In versions prior to 0.10.0 it's best to call this method directly after creating the image with love.graphics.newImage, to avoid bugs in certain graphics drivers.

Due to hardware restrictions and driver bugs, in versions prior to 0.10.0 images that weren't loaded from a CompressedData must have power-of-two dimensions (64x64, 512x256, etc.) to use mipmaps.

Texture:setMipmapFilter( filtermode, sharpness )

filtermode	FilterMode	The filter mode to use in between mipmap levels. 'nearest' will often give better performance.
sharpness (0)	number	A positive sharpness value makes the texture use a more detailed mipmap level when drawing, at the expense of performance. A negative value does the reverse.

Texture:setMipmapFilter()

Texture:setWrap

Sets the wrapping properties of a Texture.

This function sets the way a Texture is repeated when it is drawn with a Quad that is larger than the texture's extent, or when a custom Shader is used which uses texture coordinates outside of [0, 1]. A texture may be clamped or set to repeat in both horizontal and vertical directions.

Clamped textures appear only once (with the edges of the texture stretching to fill the extent of the Quad), whereas repeated ones repeat as many times as there is room in the Quad.

Texture:setWrap( horiz, vert, depth )

horiz	WrapMode	Horizontal wrapping mode of the texture.
vert (horiz)	WrapMode	Vertical wrapping mode of the texture.
depth (horiz)	WrapMode	Wrapping mode for the z-axis of a Volume texture.

A drawable video.

Constructors

love.graphics.newVideo

Functions

Video:getDimensions

Video:get/setFilter

Video:getHeight

Video:get/setSource

Video:getStream

Video:getWidth

Video:isPlaying

Video:pause

Video:play

Video:rewind

Video:tell/seek

Supertypes

Video:getDimensions

Gets the width and height of the Video in pixels.

width, height = Video:getDimensions()

width	number	The width of the Video.
height	number	The height of the Video.

Video:getFilter

Gets the scaling filters used when drawing the Video.

min, mag, anisotropy = Video:getFilter()

min	FilterMode	The filter mode used when scaling the Video down.
mag	FilterMode	The filter mode used when scaling the Video up.
anisotropy	number	Maximum amount of anisotropic filtering used.

Video:getHeight

Gets the height of the Video in pixels.

height = Video:getHeight()

height

number

The height of the Video.

Video:getSource

Gets the audio Source used for playing back the video's audio. May return nil if the video has no audio, or if Video:setSource is called with a nil argument.

source = Video:getSource()

source

The audio Source used for audio playback, or nil if the video has no audio.

Video:getStream

Gets the VideoStream object used for decoding and controlling the video.

stream = Video:getStream()

stream

The VideoStream used for decoding and controlling the video.

Video:getWidth

Gets the width of the Video in pixels.

width = Video:getWidth()

width

number

The width of the Video.

Video:isPlaying

Gets whether the Video is currently playing.

playing = Video:isPlaying()

playing

boolean

Whether the video is playing.

Video:pause

Pauses the Video.

Video:pause()

Video:play

Starts playing the Video. In order for the video to appear onscreen it must be drawn with love.graphics.draw.

Video:play()

Video:rewind

Rewinds the Video to the beginning.

Video:rewind()

Video:seek

Sets the current playback position of the Video.

Video:seek( offset )

offset

number

The time in seconds since the beginning of the Video.

Video:setFilter

Sets the scaling filters used when drawing the Video.

Video:setFilter( min, mag, anisotropy )

min	FilterMode	The filter mode used when scaling the Video down.
mag	FilterMode	The filter mode used when scaling the Video up.
anisotropy (1)	number	Maximum amount of anisotropic filtering used.

Video:setSource

Sets the audio Source used for playing back the video's audio. The audio Source also controls playback speed and synchronization.

Video:setSource( source )

source (nil)

The audio Source used for audio playback, or nil to disable audio synchronization.

Video:tell

Gets the current playback position of the Video.

seconds = Video:tell()

seconds

number

The time in seconds since the beginning of the Video.

AlignMode

center

Align text center.

left

Align text left.

right

Align text right.

justify

Align text both left and right.

ArcType

pie

The arc is drawn like a slice of pie, with the arc circle connected to the center at its end-points.

open

The arc circle's two end-points are unconnected when the arc is drawn as a line. Behaves like the "closed" arc type when the arc is drawn in filled mode.

closed

The arc circle's two end-points are connected to each other.

AreaSpreadDistribution

uniform

Uniform distribution.

normal

Normal (gaussian) distribution.

ellipse

Uniform distribution in an ellipse.

borderellipse

Distribution in an ellipse with particles spawning at the edges of the ellipse.

borderrectangle

Distribution in a rectangle with particles spawning at the edges of the rectangle.

none

No distribution - area spread is disabled.

BlendAlphaMode

alphamultiply

The RGB values of what's drawn are multiplied by the alpha values of those colors during blending. This is the default alpha mode.

premultiplied

The RGB values of what's drawn are '''not''' multiplied by the alpha values of those colors during blending. For most blend modes to work correctly with this alpha mode, the colors of a drawn object need to have had their RGB values multiplied by their alpha values at some point previously ("premultiplied alpha").

BlendMode

alpha

Alpha blending (normal). The alpha of what's drawn determines its opacity.

replace

The colors of what's drawn completely replace what was on the screen, with no additional blending. The BlendAlphaMode specified in love.graphics.setBlendMode still affects what happens.

screen

'Screen' blending.

add

The pixel colors of what's drawn are added to the pixel colors already on the screen. The alpha of the screen is not modified.

subtract

The pixel colors of what's drawn are subtracted from the pixel colors already on the screen. The alpha of the screen is not modified.

multiply

The pixel colors of what's drawn are multiplied with the pixel colors already on the screen (darkening them). The alpha of drawn objects is multiplied with the alpha of the screen rather than determining how much the colors on the screen are affected, even when the "alphamultiply" BlendAlphaMode is used.

lighten

The pixel colors of what's drawn are compared to the existing pixel colors, and the larger of the two values for each color component is used. Only works when the "premultiplied" BlendAlphaMode is used in love.graphics.setBlendMode.

darken

The pixel colors of what's drawn are compared to the existing pixel colors, and the smaller of the two values for each color component is used. Only works when the "premultiplied" BlendAlphaMode is used in love.graphics.setBlendMode.

additive

Additive blend mode.

subtractive

Subtractive blend mode.

multiplicative

Multiply blend mode.

premultiplied

Premultiplied alpha blend mode.

CompareMode

equal

* stencil tests: the stencil value of the pixel must be equal to the supplied value. * depth tests: the depth value of the drawn object at that pixel must be equal to the existing depth value of that pixel.

notequal

* stencil tests: the stencil value of the pixel must not be equal to the supplied value. * depth tests: the depth value of the drawn object at that pixel must not be equal to the existing depth value of that pixel.

less

* stencil tests: the stencil value of the pixel must be less than the supplied value. * depth tests: the depth value of the drawn object at that pixel must be less than the existing depth value of that pixel.

lequal

* stencil tests: the stencil value of the pixel must be less than or equal to the supplied value. * depth tests: the depth value of the drawn object at that pixel must be less than or equal to the existing depth value of that pixel.

gequal

* stencil tests: the stencil value of the pixel must be greater than or equal to the supplied value. * depth tests: the depth value of the drawn object at that pixel must be greater than or equal to the existing depth value of that pixel.

greater

* stencil tests: the stencil value of the pixel must be greater than the supplied value. * depth tests: the depth value of the drawn object at that pixel must be greater than the existing depth value of that pixel.

never

Objects will never be drawn.

always

Objects will always be drawn. Effectively disables the depth or stencil test.

CullMode

back

Back-facing triangles in Meshes are culled (not rendered). The vertex order of a triangle determines whether it is back- or front-facing.

front

Front-facing triangles in Meshes are culled.

none

Both back- and front-facing triangles in Meshes are rendered.

DrawMode

fill

Draw filled shape.

line

Draw outlined shape.

FilterMode

linear

Scale image with linear interpolation.

nearest

Scale image with nearest neighbor interpolation.

GraphicsFeature

clampzero

Whether the "clampzero" WrapMode is supported.

lighten

Whether the "lighten" and "darken" BlendModes are supported.

multicanvasformats

Whether multiple formats can be used in the same love.graphics.setCanvas call.

glsl3

Whether GLSL 3 Shaders can be used.

instancing

Whether mesh instancing is supported.

fullnpot

Whether textures with non-power-of-two dimensions can use mipmapping and the 'repeat' WrapMode.

pixelshaderhighp

Whether pixel shaders can use "highp" 32 bit floating point numbers (as opposed to just 16 bit or lower precision).

shaderderivatives

Whether shaders can use the dFdx, dFdy, and fwidth functions for computing derivatives.

GraphicsLimit

pointsize

The maximum size of points.

texturesize

The maximum width or height of Images and Canvases.

multicanvas

The maximum number of simultaneously active canvases (via love.graphics.setCanvas.)

canvasmsaa

The maximum number of antialiasing samples for a Canvas.

texturelayers

The maximum number of layers in an Array texture.

volumetexturesize

The maximum width, height, or depth of a Volume texture.

cubetexturesize

The maximum width or height of a Cubemap texture.

anisotropy

The maximum amount of anisotropic filtering. Texture:setMipmapFilter internally clamps the given anisotropy value to the system's limit.

IndexDataType

uint16

The vertex map is array of unsigned word (16-bit).

uint32

The vertex map is array of unsigned dword (32-bit).

LineJoin

miter

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

none

No cap applied to the ends of the line segments.

bevel

Flattens the point where line segments join together.

LineStyle

rough

Draw rough lines.

smooth

Draw smooth lines.

MeshDrawMode

fan

The vertices create a "fan" shape with the first vertex acting as the hub point. Can be easily used to draw simple convex polygons.

strip

The vertices create a series of connected triangles using vertices 1, 2, 3, then 3, 2, 4 (note the order), then 3, 4, 5, and so on.

triangles

The vertices create unconnected triangles.

points

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

MipmapMode

none

The Canvas has no mipmaps.

auto

The Canvas has mipmaps. love.graphics.setCanvas can be used to render to a specific mipmap level, or Canvas:generateMipmaps can (re-)compute all mipmap levels based on the base level.

manual

The Canvas has mipmaps, and all mipmap levels will automatically be recomputed when switching away from the Canvas with love.graphics.setCanvas.

ParticleInsertMode

top

Particles are inserted at the top of the ParticleSystem's list of particles.

bottom

Particles are inserted at the bottom of the ParticleSystem's list of particles.

random

Particles are inserted at random positions in the ParticleSystem's list of particles.

SpriteBatchUsage

dynamic

The object's data will change occasionally during its lifetime.

static

The object will not be modified after initial sprites or vertices are added.

stream

The object data will always change between draws.

StackType

transform

The transformation stack (love.graphics.translate, love.graphics.rotate, etc.)

all

All love.graphics state, including transform state.

StencilAction

replace

The stencil value of a pixel will be replaced by the value specified in love.graphics.stencil, if any object touches the pixel.

increment

The stencil value of a pixel will be incremented by 1 for each object that touches the pixel. If the stencil value reaches 255 it will stay at 255.

decrement

The stencil value of a pixel will be decremented by 1 for each object that touches the pixel. If the stencil value reaches 0 it will stay at 0.

incrementwrap

The stencil value of a pixel will be incremented by 1 for each object that touches the pixel. If a stencil value of 255 is incremented it will be set to 0.

decrementwrap

The stencil value of a pixel will be decremented by 1 for each object that touches the pixel. If the stencil value of 0 is decremented it will be set to 255.

invert

The stencil value of a pixel will be bitwise-inverted for each object that touches the pixel. If a stencil value of 0 is inverted it will become 255.

TextureType

Regular 2D texture with width and height.

array

Several same-size 2D textures organized into a single object. Similar to a texture atlas / sprite sheet, but avoids sprite bleeding and other issues.

cube

Cubemap texture with 6 faces. Requires a custom shader (and Shader:send) to use. Sampling from a cube texture in a shader takes a 3D direction vector instead of a texture coordinate.

volume

3D texture with width, height, and depth. Requires a custom shader to use. Volume textures can have texture filtering applied along the 3rd axis.

VertexAttributeStep

pervertex

The vertex attribute will have a unique value for each vertex in the Mesh.

perinstance

The vertex attribute will have a unique value for each instance of the Mesh.

VertexWinding

Clockwise.

ccw

Counter-clockwise.

WrapMode

clamp

Clamp the texture. Appears only once. The area outside the texture's normal range is colored based on the edge pixels of the texture.

repeat

Repeat the texture. Fills the whole available extent.

mirroredrepeat

Repeat the texture, flipping it each time it repeats. May produce better visual results than the repeat mode when the texture doesn't seamlessly tile.

clampzero

Clamp the texture. Fills the area outside the texture's normal range with transparent black (or opaque black for textures with no alpha channel.)

love.image

Types

Functions

love.image.isCompressed

Enums

CompressedImageFormat

ImageFormat

love.image.isCompressed

Determines whether a file can be loaded as CompressedImageData.

compressed = love.image.isCompressed( filename )

compressed

boolean

Whether the file can be loaded as CompressedImageData or not.

filename

string

The filename of the potentially compressed image file.

compressed = love.image.isCompressed( fileData )

compressed

boolean

Whether the FileData can be loaded as CompressedImageData or not.

fileData

love.image.newCompressedData

A FileData potentially containing a compressed image.

Create a new CompressedImageData object from a compressed image file. LÖVE supports several compressed texture formats, enumerated in the CompressedImageFormat page.

compressedImageData = love.image.newCompressedData( filename )

compressedImageData

The new CompressedImageData object.

filename

string

The filename of the compressed image file.

compressedImageData = love.image.newCompressedData( fileData )

compressedImageData

The new CompressedImageData object.

fileData

A FileData containing a compressed image.

love.image.newImageData

Creates a new ImageData object.

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

imageData

The new blank ImageData object. Each pixel's color values, (including the alpha values!) will be set to zero.

width	number	The width of the ImageData.
height	number	The height of the ImageData.

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

imageData

The new ImageData object.

width	number	The width of the ImageData.
height	number	The height of the ImageData.
format ('rgba8')	PixelFormat	The pixel format of the ImageData.
data (nil)	string	Optional raw byte data to load into the ImageData, in the format specified by ''format''.

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

imageData

The new ImageData object.

width	number	The width of the ImageData.
height	number	The height of the ImageData.
data	string	The data to load into the ImageData (RGBA bytes, left to right and top to bottom).

imageData = love.image.newImageData( filename )

imageData

The new ImageData object.

filename

string

The filename of the image file.

imageData = love.image.newImageData( filedata )

imageData

The new ImageData object.

filedata

The encoded file data to decode into image data.

Represents compressed image data designed to stay compressed in RAM.

CompressedImageData encompasses standard compressed texture formats such as DXT1, DXT5, and BC5 / 3Dc.

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

Constructors

love.image.newCompressedData

Functions

CompressedImageData:getDimensions

CompressedImageData:getFormat

CompressedImageData:getHeight

CompressedImageData:getMipmapCount

CompressedImageData:getWidth

Supertypes

CompressedImageData:getDimensions

Gets the width and height of the CompressedImageData.

width, height = CompressedImageData:getDimensions()

width	number	The width of the CompressedImageData.
height	number	The height of the CompressedImageData.

width, height = CompressedImageData:getDimensions( level )

width	number	The width of a specific mipmap level of the CompressedImageData.
height	number	The height of a specific mipmap level of the CompressedImageData.

level

number

A mipmap level. Must be in the range of CompressedImageData:getMipmapCount().

CompressedImageData:getFormat

Gets the format of the CompressedImageData.

format = CompressedImageData:getFormat()

format

CompressedImageFormat

The format of the CompressedImageData.

CompressedImageData:getHeight

Gets the height of the CompressedImageData.

height = CompressedImageData:getHeight()

height

number

The height of the CompressedImageData.

height = CompressedImageData:getHeight( level )

height

number

The height of a specific mipmap level of the CompressedImageData.

level

number

A mipmap level. Must be in the range of CompressedImageData:getMipmapCount().

CompressedImageData:getMipmapCount

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

mipmaps = CompressedImageData:getMipmapCount()

mipmaps

number

The number of mipmap levels stored in the CompressedImageData.

CompressedImageData:getWidth

Gets the width of the CompressedImageData.

width = CompressedImageData:getWidth()

width

number

The width of the CompressedImageData.

width = CompressedImageData:getWidth( level )

width

number

The width of a specific mipmap level of the CompressedImageData.

level

number

A mipmap level. Must be in the range of CompressedImageData:getMipmapCount().

Raw (decoded) image data.

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

Constructors

love.image.newImageData

Functions

ImageData:encode

ImageData:getDimensions

ImageData:getHeight

ImageData:get/setPixel

ImageData:getWidth

ImageData:mapPixel

ImageData:paste

ImageData:getFormat

Supertypes

ImageData:encode

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

filedata = ImageData:encode( format, filename )

filedata

The encoded image as a new FileData object.

format	ImageFormat	The format to encode the image as.
filename (nil)	string	The filename to write the file to. If nil, no file will be written but the FileData will still be returned.

ImageData:encode( outFile )

outFile

string

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

ImageData:encode( outFile, format )

outFile	string	Name of a file to write encoded data to.
format	ImageFormat	The format to encode the image in.

ImageData:getDimensions

Gets the width and height of the ImageData in pixels.

width, height = ImageData:getDimensions()

width	number	The width of the ImageData in pixels.
height	number	The height of the ImageData in pixels.

ImageData:getHeight

Gets the height of the ImageData in pixels.

height = ImageData:getHeight()

height

number

The height of the ImageData in pixels.

ImageData:getPixel

Gets the color of a pixel at a specific position in the image.

Valid x and y values start at 0 and go up to image width and height minus 1. Non-integer values are floored.

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

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

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

x	number	The position of the pixel on the x-axis.
y	number	The position of the pixel on the y-axis.

ImageData:getWidth

Gets the width of the ImageData in pixels.

width = ImageData:getWidth()

width

number

The width of the ImageData in pixels.

ImageData:mapPixel

Transform an image by applying a function to every pixel.

This function is a higher-order function. It takes another function as a parameter, and calls it once for each pixel in the ImageData.

The passed function is called with six parameters for each pixel in turn. The parameters are numbers that represent the x and y coordinates of the pixel and its red, green, blue and alpha values. The function should return the new red, green, blue, and alpha values for that pixel.

function pixelFunction(x, y, r, g, b, a)

-- template for defining your own pixel mapping function

-- perform computations giving the new values for r, g, b and a

-- ...

return r, g, b, a

end

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

ImageData:mapPixel( pixelFunction, x, y, width, height )

pixelFunction	function	Function to apply to every pixel.
x (0)	number	The x-axis of the top-left corner of the area within the ImageData to apply the function to.
y (0)	number	The y-axis of the top-left corner of the area within the ImageData to apply the function to.
width (ImageData:getWidth())	number	The width of the area within the ImageData to apply the function to.
height (ImageData:getHeight())	number	The height of the area within the ImageData to apply the function to.

ImageData:paste

Paste into ImageData from another source ImageData.

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

source	ImageData	Source ImageData from which to copy.
dx	number	Destination top-left position on x-axis.
dy	number	Destination top-left position on y-axis.
sx	number	Source top-left position on x-axis.
sy	number	Source top-left position on y-axis.
sw	number	Source width.
sh	number	Source height.

ImageData:setPixel

Sets the color of a pixel at a specific position in the image.

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

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

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

x	number	The position of the pixel on the x-axis.
y	number	The position of the pixel on the y-axis.
r	number	The red component (0-1).
g	number	The green component (0-1).
b	number	The blue component (0-1).
a	number	The alpha component (0-1).

ImageData:getFormat

Gets the pixel format of the ImageData.

format = ImageData:getFormat()

format

The pixel format the ImageData was created with.

CompressedImageFormat

DXT1

The DXT1 format. RGB data at 4 bits per pixel (compared to 32 bits for ImageData and regular Images.) Suitable for fully opaque images on desktop systems.

DXT3

The DXT3 format. RGBA data at 8 bits per pixel. Smooth variations in opacity do not mix well with this format.

DXT5

The DXT5 format. RGBA data at 8 bits per pixel. Recommended for images with varying opacity on desktop systems.

BC4

The BC4 format (also known as 3Dc+ or ATI1.) Stores just the red channel, at 4 bits per pixel.

BC4s

The signed variant of the BC4 format. Same as above but pixel values in the texture are in the range of 1 instead of 1 in shaders.

BC5

The BC5 format (also known as 3Dc or ATI2.) Stores red and green channels at 8 bits per pixel.

BC5s

The signed variant of the BC5 format.

BC6h

The BC6H format. Stores half-precision floating-point RGB data in the range of 65504 at 8 bits per pixel. Suitable for HDR images on desktop systems.

BC6hs

The signed variant of the BC6H format. Stores RGB data in the range of +65504.

BC7

The BC7 format (also known as BPTC.) Stores RGB or RGBA data at 8 bits per pixel.

ETC1

The ETC1 format. RGB data at 4 bits per pixel. Suitable for fully opaque images on older Android devices.

ETC2rgb

The RGB variant of the ETC2 format. RGB data at 4 bits per pixel. Suitable for fully opaque images on newer mobile devices.

ETC2rgba

The RGBA variant of the ETC2 format. RGBA data at 8 bits per pixel. Recommended for images with varying opacity on newer mobile devices.

ETC2rgba1

The RGBA variant of the ETC2 format where pixels are either fully transparent or fully opaque. RGBA data at 4 bits per pixel.

EACr

The single-channel variant of the EAC format. Stores just the red channel, at 4 bits per pixel.

EACrs

The signed single-channel variant of the EAC format. Same as above but pixel values in the texture are in the range of 1 instead of 1 in shaders.

EACrg

The two-channel variant of the EAC format. Stores red and green channels at 8 bits per pixel.

EACrgs

The signed two-channel variant of the EAC format.

PVR1rgb2

The 2 bit per pixel RGB variant of the PVRTC1 format. Stores RGB data at 2 bits per pixel. Textures compressed with PVRTC1 formats must be square and power-of-two sized.

PVR1rgb4

The 4 bit per pixel RGB variant of the PVRTC1 format. Stores RGB data at 4 bits per pixel.

PVR1rgba2

The 2 bit per pixel RGBA variant of the PVRTC1 format.

PVR1rgba4

The 4 bit per pixel RGBA variant of the PVRTC1 format.

ASTC4x4

The 4x4 pixels per block variant of the ASTC format. RGBA data at 8 bits per pixel.

ASTC5x4

The 5x4 pixels per block variant of the ASTC format. RGBA data at 6.4 bits per pixel.

ASTC5x5

The 5x5 pixels per block variant of the ASTC format. RGBA data at 5.12 bits per pixel.

ASTC6x5

The 6x5 pixels per block variant of the ASTC format. RGBA data at 4.27 bits per pixel.

ASTC6x6

The 6x6 pixels per block variant of the ASTC format. RGBA data at 3.56 bits per pixel.

ASTC8x5

The 8x5 pixels per block variant of the ASTC format. RGBA data at 3.2 bits per pixel.

ASTC8x6

The 8x6 pixels per block variant of the ASTC format. RGBA data at 2.67 bits per pixel.

ASTC8x8

The 8x8 pixels per block variant of the ASTC format. RGBA data at 2 bits per pixel.

ASTC10x5

The 10x5 pixels per block variant of the ASTC format. RGBA data at 2.56 bits per pixel.

ASTC10x6

The 10x6 pixels per block variant of the ASTC format. RGBA data at 2.13 bits per pixel.

ASTC10x8

The 10x8 pixels per block variant of the ASTC format. RGBA data at 1.6 bits per pixel.

ASTC10x10

The 10x10 pixels per block variant of the ASTC format. RGBA data at 1.28 bits per pixel.

ASTC12x10

The 12x10 pixels per block variant of the ASTC format. RGBA data at 1.07 bits per pixel.

ASTC12x12

The 12x12 pixels per block variant of the ASTC format. RGBA data at 0.89 bits per pixel.

ImageFormat

tga

Targa image format.

png

PNG image format.

jpg

JPG image format.

bmp

BMP image format.

unknown

Indicates unknown pixel format, used internally.

normal

Alias for rgba8, or srgba8 if gamma-correct rendering is enabled.

hdr

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

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

rg8

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

rgba8

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

srgba8

gamma-correct version of rgba8.

r16

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

rg16

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

rgba16

16 bits per channel (64 bpp) RGBA. Color channel values range from 0-65535 (0-1 in shaders).

r16f

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

rg16f

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

rgba16f

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

r32f

Floating point single-channel format (32 bpp).

rg32f

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

rgba32f

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

la8

Same as rg8, but accessed as (L, L, L, A)

rgba4

4 bits per channel (16 bpp) RGBA.

rgb5a1

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

rgb565

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

rgb10a2

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

rg11b10f

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

stencil8

No depth buffer and 8-bit stencil buffer.

depth16

16-bit depth buffer and no stencil buffer.

depth24

24-bit depth buffer and no stencil buffer.

depth32f

32-bit float depth buffer and no stencil buffer.

depth24stencil8

24-bit depth buffer and 8-bit stencil buffer.

depth32fstencil8

32-bit float depth buffer and 8-bit stencil buffer.

DXT1

The DXT1 format. RGB data at 4 bits per pixel (compared to 32 bits for ImageData and regular Images.) Suitable for fully opaque images on desktop systems.

DXT3

The DXT3 format. RGBA data at 8 bits per pixel. Smooth variations in opacity do not mix well with this format.

DXT5

The DXT5 format. RGBA data at 8 bits per pixel. Recommended for images with varying opacity on desktop systems.

BC4

The BC4 format (also known as 3Dc+ or ATI1.) Stores just the red channel, at 4 bits per pixel.

BC4s

The signed variant of the BC4 format. Same as above but pixel values in the texture are in the range of 1 instead of 1 in shaders.

BC5

The BC5 format (also known as 3Dc or ATI2.) Stores red and green channels at 8 bits per pixel.

BC5s

The signed variant of the BC5 format.

BC6h

The BC6H format. Stores half-precision floating-point RGB data in the range of 65504 at 8 bits per pixel. Suitable for HDR images on desktop systems.

BC6hs

The signed variant of the BC6H format. Stores RGB data in the range of +65504.

BC7

The BC7 format (also known as BPTC.) Stores RGB or RGBA data at 8 bits per pixel.

ETC1

The ETC1 format. RGB data at 4 bits per pixel. Suitable for fully opaque images on older Android devices.

ETC2rgb

The RGB variant of the ETC2 format. RGB data at 4 bits per pixel. Suitable for fully opaque images on newer mobile devices.

ETC2rgba

The RGBA variant of the ETC2 format. RGBA data at 8 bits per pixel. Recommended for images with varying opacity on newer mobile devices.

ETC2rgba1

The RGBA variant of the ETC2 format where pixels are either fully transparent or fully opaque. RGBA data at 4 bits per pixel.

EACr

The single-channel variant of the EAC format. Stores just the red channel, at 4 bits per pixel.

EACrs

The signed single-channel variant of the EAC format. Same as above but pixel values in the texture are in the range of 1 instead of 1 in shaders.

EACrg

The two-channel variant of the EAC format. Stores red and green channels at 8 bits per pixel.

EACrgs

The signed two-channel variant of the EAC format.

PVR1rgb2

The 2 bit per pixel RGB variant of the PVRTC1 format. Stores RGB data at 2 bits per pixel. Textures compressed with PVRTC1 formats must be square and power-of-two sized.

PVR1rgb4

The 4 bit per pixel RGB variant of the PVRTC1 format. Stores RGB data at 4 bits per pixel.

PVR1rgba2

The 2 bit per pixel RGBA variant of the PVRTC1 format.

PVR1rgba4

The 4 bit per pixel RGBA variant of the PVRTC1 format.

ASTC4x4

The 4x4 pixels per block variant of the ASTC format. RGBA data at 8 bits per pixel.

ASTC5x4

The 5x4 pixels per block variant of the ASTC format. RGBA data at 6.4 bits per pixel.

ASTC5x5

The 5x5 pixels per block variant of the ASTC format. RGBA data at 5.12 bits per pixel.

ASTC6x5

The 6x5 pixels per block variant of the ASTC format. RGBA data at 4.27 bits per pixel.

ASTC6x6

The 6x6 pixels per block variant of the ASTC format. RGBA data at 3.56 bits per pixel.

ASTC8x5

The 8x5 pixels per block variant of the ASTC format. RGBA data at 3.2 bits per pixel.

ASTC8x6

The 8x6 pixels per block variant of the ASTC format. RGBA data at 2.67 bits per pixel.

ASTC8x8

The 8x8 pixels per block variant of the ASTC format. RGBA data at 2 bits per pixel.

ASTC10x5

The 10x5 pixels per block variant of the ASTC format. RGBA data at 2.56 bits per pixel.

ASTC10x6

The 10x6 pixels per block variant of the ASTC format. RGBA data at 2.13 bits per pixel.

ASTC10x8

The 10x8 pixels per block variant of the ASTC format. RGBA data at 1.6 bits per pixel.

ASTC10x10

The 10x10 pixels per block variant of the ASTC format. RGBA data at 1.28 bits per pixel.

ASTC12x10

The 12x10 pixels per block variant of the ASTC format. RGBA data at 1.07 bits per pixel.

ASTC12x12

The 12x12 pixels per block variant of the ASTC format. RGBA data at 0.89 bits per pixel.

love.joystick

Types

love.joystick.getGamepadMappingString

Functions

love.joystick.getGamepadMappingString

love.joystick.getJoystickCount

love.joystick.getJoysticks

love.joystick.load/saveGamepadMappings

love.joystick.setGamepadMapping

Enums

Gets the full gamepad mapping string of the Joysticks which have the given GUID, or nil if the GUID isn't recognized as a gamepad.

The mapping string contains binding information used to map the Joystick's buttons an axes to the standard gamepad layout, and can be used later with love.joystick.loadGamepadMappings.

mappingstring = love.joystick.getGamepadMappingString( guid )

mappingstring

string

A string containing the Joystick's gamepad mappings, or nil if the GUID is not recognized as a gamepad.

guid

string

The GUID value to get the mapping string for.

love.joystick.getJoystickCount

Gets the number of connected joysticks.

joystickcount = love.joystick.getJoystickCount()

joystickcount

number

The number of connected joysticks.

love.joystick.getJoysticks

Gets a list of connected Joysticks.

joysticks = love.joystick.getJoysticks()

joysticks

table

The list of currently connected Joysticks.

love.joystick.loadGamepadMappings

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

It also recognizes any SDL gamecontroller mapping string, such as those created with Steam's Big Picture controller configure interface, or this nice database. If a new mapping is loaded for an already known controller GUID, the later version will overwrite the one currently loaded.

love.joystick.loadGamepadMappings( filename )

filename

string

The filename to load the mappings string from.

love.joystick.loadGamepadMappings( mappings )

mappings

string

The mappings string to load.

love.joystick.saveGamepadMappings

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

The mappings are stored as a string for use with love.joystick.loadGamepadMappings.

mappings = love.joystick.saveGamepadMappings( filename )

mappings

string

The mappings string that was written to the file.

filename

string

The filename to save the mappings string to.

mappings = love.joystick.saveGamepadMappings()

mappings

string

The mappings string.

love.joystick.setGamepadMapping

Binds a virtual gamepad input to a button, axis or hat for all Joysticks of a certain type. For example, if this function is used with a GUID returned by a Dualshock 3 controller in OS X, the binding will affect Joystick:getGamepadAxis and Joystick:isGamepadDown for ''all'' Dualshock 3 controllers used with the game when run in OS X.

LÖVE includes built-in gamepad bindings for many common controllers. This function lets you change the bindings or add new ones for types of Joysticks which aren't recognized as gamepads by default.

The virtual gamepad buttons and axes are designed around the Xbox 360 controller layout.

success = love.joystick.setGamepadMapping( guid, button, inputtype, inputindex, hatdir )

success

boolean

Whether the virtual gamepad button was successfully bound.

guid	string	The OS-dependent GUID for the type of Joystick the binding will affect.
button	GamepadButton	The virtual gamepad button to bind.
inputtype	JoystickInputType	The type of input to bind the virtual gamepad button to.
inputindex	number	The index of the axis, button, or hat to bind the virtual gamepad button to.
hatdir (nil)	JoystickHat	The direction of the hat, if the virtual gamepad button will be bound to a hat. nil otherwise.

success = love.joystick.setGamepadMapping( guid, axis, inputtype, inputindex, hatdir )

success

boolean

Whether the virtual gamepad axis was successfully bound.

guid	string	The OS-dependent GUID for the type of Joystick the binding will affect.
axis	GamepadAxis	The virtual gamepad axis to bind.
inputtype	JoystickInputType	The type of input to bind the virtual gamepad axis to.
inputindex	number	The index of the axis, button, or hat to bind the virtual gamepad axis to.
hatdir (nil)	JoystickHat	The direction of the hat, if the virtual gamepad axis will be bound to a hat. nil otherwise.

Represents a physical joystick.

Functions

Joystick:getAxes

Joystick:getAxis

Joystick:getAxisCount

Joystick:getButtonCount

Joystick:getDeviceInfo

Joystick:getGUID

Joystick:getGamepadAxis

Joystick:getGamepadMapping

Joystick:getGamepadMappingString

Joystick:getHat

Joystick:getHatCount

Joystick:getID

Joystick:getName

Joystick:get/setVibration

Joystick:isConnected

Joystick:isDown

Joystick:isGamepad

Joystick:isGamepadDown

Joystick:isVibrationSupported

Supertypes

Joystick:getGamepadMapping

Joystick:getAxes

Gets the direction of each axis.

axisDir1, axisDir2, axisDirN = Joystick:getAxes()

axisDir1	number	Direction of axis1.
axisDir2	number	Direction of axis2.
axisDirN	number	Direction of axisN.

Joystick:getAxis

Gets the direction of an axis.

direction = Joystick:getAxis( axis )

direction

number

Current value of the axis.

axis

number

The index of the axis to be checked.

Joystick:getAxisCount

Gets the number of axes on the joystick.

axes = Joystick:getAxisCount()

axes

number

The number of axes available.

Joystick:getButtonCount

Gets the number of buttons on the joystick.

buttons = Joystick:getButtonCount()

buttons

number

The number of buttons available.

Joystick:getDeviceInfo

Gets the USB vendor ID, product ID, and product version numbers of joystick which consistent across operating systems.

Can be used to show different icons, etc. for different gamepads.

vendorID, productID, productVersion = Joystick:getDeviceInfo()

vendorID	number	The USB vendor ID of the joystick.
productID	number	The USB product ID of the joystick.
productVersion	number	The product version of the joystick.

Joystick:getGUID

Gets a stable GUID unique to the type of the physical joystick which does not change over time. For example, all Sony Dualshock 3 controllers in OS X have the same GUID. The value is platform-dependent.

guid = Joystick:getGUID()

guid

string

The Joystick type's OS-dependent unique identifier.

Joystick:getGamepadAxis

Gets the direction of a virtual gamepad axis. If the Joystick isn't recognized as a gamepad or isn't connected, this function will always return 0.

direction = Joystick:getGamepadAxis( axis )

direction

number

Current value of the axis.

axis

GamepadAxis

The virtual axis to be checked.

Gets the button, axis or hat that a virtual gamepad input is bound to.

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

inputtype	JoystickInputType	The type of input the virtual gamepad axis is bound to.
inputindex	number	The index of the Joystick's button, axis or hat that the virtual gamepad axis is bound to.
hatdirection	JoystickHat	The direction of the hat, if the virtual gamepad axis is bound to a hat. nil otherwise.

axis

GamepadAxis

The virtual gamepad axis to get the binding for.

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

inputtype	JoystickInputType	The type of input the virtual gamepad button is bound to.
inputindex	number	The index of the Joystick's button, axis or hat that the virtual gamepad button is bound to.
hatdirection	JoystickHat	The direction of the hat, if the virtual gamepad button is bound to a hat. nil otherwise.

button

GamepadButton

The virtual gamepad button to get the binding for.

Joystick:getGamepadMappingString

Gets the full gamepad mapping string of this Joystick, or nil if it's not recognized as a gamepad.

The mapping string contains binding information used to map the Joystick's buttons an axes to the standard gamepad layout, and can be used later with love.joystick.loadGamepadMappings.

mappingstring = Joystick:getGamepadMappingString()

mappingstring

string

A string containing the Joystick's gamepad mappings, or nil if the Joystick is not recognized as a gamepad.

Joystick:getHat

Gets the direction of the Joystick's hat.

direction = Joystick:getHat( hat )

direction

JoystickHat

The direction the hat is pushed.

hat

number

The index of the hat to be checked.

Joystick:getHatCount

Gets the number of hats on the joystick.

hats = Joystick:getHatCount()

hats

number

How many hats the joystick has.

Joystick:getID

Gets the joystick's unique identifier. The identifier will remain the same for the life of the game, even when the Joystick is disconnected and reconnected, but it '''will''' change when the game is re-launched.

id, instanceid = Joystick:getID()

id	number	The Joystick's unique identifier. Remains the same as long as the game is running.
instanceid	number	Unique instance identifier. Changes every time the Joystick is reconnected. nil if the Joystick is not connected.

Joystick:getName

Gets the name of the joystick.

name = Joystick:getName()

name

string

The name of the joystick.

Joystick:getVibration

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

left, right = Joystick:getVibration()

left	number	Current strength of the left vibration motor on the Joystick.
right	number	Current strength of the right vibration motor on the Joystick.

Joystick:isConnected

Gets whether the Joystick is connected.

connected = Joystick:isConnected()

connected

boolean

True if the Joystick is currently connected, false otherwise.

Joystick:isDown

Checks if a button on the Joystick is pressed.

LÖVE 0.9.0 had a bug which required the button indices passed to Joystick:isDown to be 0-based instead of 1-based, for example button 1 would be 0 for this function. It was fixed in 0.9.1.

anyDown = Joystick:isDown( buttonN )

anyDown

boolean

True if any supplied button is down, false if not.

buttonN

number

The index of a button to check.

Joystick:isGamepad

Gets whether the Joystick is recognized as a gamepad. If this is the case, the Joystick's buttons and axes can be used in a standardized manner across different operating systems and joystick models via Joystick:getGamepadAxis, Joystick:isGamepadDown, love.gamepadpressed, and related functions.

LÖVE automatically recognizes most popular controllers with a similar layout to the Xbox 360 controller as gamepads, but you can add more with love.joystick.setGamepadMapping.

isgamepad = Joystick:isGamepad()

isgamepad

boolean

True if the Joystick is recognized as a gamepad, false otherwise.

Joystick:isGamepadDown

Checks if a virtual gamepad button on the Joystick is pressed. If the Joystick is not recognized as a Gamepad or isn't connected, then this function will always return false.

anyDown = Joystick:isGamepadDown( buttonN )

anyDown

boolean

True if any supplied button is down, false if not.

buttonN

GamepadButton

The gamepad button to check.

Joystick:isVibrationSupported

Gets whether the Joystick supports vibration.

supported = Joystick:isVibrationSupported()

supported

boolean

True if rumble / force feedback vibration is supported on this Joystick, false if not.

Joystick:setVibration

Sets the vibration motor speeds on a Joystick with rumble support. Most common gamepads have this functionality, although not all drivers give proper support. Use Joystick:isVibrationSupported to check.

success = Joystick:setVibration( left, right )

success

boolean

True if the vibration was successfully applied, false if not.

left	number	Strength of the left vibration motor on the Joystick. Must be in the range of 1.
right	number	Strength of the right vibration motor on the Joystick. Must be in the range of 1.

success = Joystick:setVibration()

success

boolean

True if the vibration was successfully disabled, false if not.

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

success

boolean

True if the vibration was successfully applied, false if not.

left	number	Strength of the left vibration motor on the Joystick. Must be in the range of 1.
right	number	Strength of the right vibration motor on the Joystick. Must be in the range of 1.
duration (-1)	number	The duration of the vibration in seconds. A negative value means infinite duration.

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

Bottom face button (A).

Right face button (B).

Left face button (X).

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

Centered

Down

Left

Left+Down

Left+Up

Right

Right+Down

Right+Up

JoystickInputType

axis

Analog axis.

button

Button.

hat

8-direction hat value.

love.keyboard

Functions

love.keyboard.getKeyFromScancode

love.keyboard.getScancodeFromKey

love.keyboard.has/setKeyRepeat

love.keyboard.hasScreenKeyboard

love.keyboard.has/setTextInput

love.keyboard.isDown

love.keyboard.isScancodeDown

Enums

love.keyboard.getKeyFromScancode

Gets the key corresponding to the given hardware scancode.

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

Scancodes are useful for creating default controls that have the same physical locations on on all systems.

key = love.keyboard.getKeyFromScancode( scancode )

key

The key corresponding to the given scancode, or 'unknown' if the scancode doesn't map to a KeyConstant on the current system.

scancode

love.keyboard.getScancodeFromKey

The scancode to get the key from.

Gets the hardware scancode corresponding to the given key.

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

Scancodes are useful for creating default controls that have the same physical locations on on all systems.

scancode = love.keyboard.getScancodeFromKey( key )

scancode

The scancode corresponding to the given key, or 'unknown' if the given key has no known physical representation on the current system.

key

love.keyboard.hasKeyRepeat

The key to get the scancode from.

Gets whether key repeat is enabled.

enabled = love.keyboard.hasKeyRepeat()

enabled

boolean

Whether key repeat is enabled.

love.keyboard.hasScreenKeyboard

Gets whether screen keyboard is supported.

supported = love.keyboard.hasScreenKeyboard()

supported

boolean

Whether screen keyboard is supported.

love.keyboard.hasTextInput

Gets whether text input events are enabled.

enabled = love.keyboard.hasTextInput()

enabled

boolean

Whether text input events are enabled.

love.keyboard.isDown

Checks whether a certain key is down. Not to be confused with love.keypressed or love.keyreleased.

down = love.keyboard.isDown( key )

down

boolean

True if the key is down, false if not.

key

love.keyboard.isScancodeDown

The key to check.

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

anyDown

boolean

True if any supplied key is down, false if not.

key	KeyConstant	A key to check.
...	KeyConstant	Additional keys to check.

Checks whether the specified Scancodes are pressed. Not to be confused with love.keypressed or love.keyreleased.

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

down = love.keyboard.isScancodeDown( scancode, ... )

down

boolean

True if any supplied Scancode is down, false if not.

scancode	Scancode	A Scancode to check.
...	Scancode	Additional Scancodes to check.

love.keyboard.setKeyRepeat

Enables or disables key repeat for love.keypressed. It is disabled by default.

love.keyboard.setKeyRepeat( enable )

enable

boolean

Whether repeat keypress events should be enabled when a key is held down.

love.keyboard.setTextInput

Enables or disables text input events. It is enabled by default on Windows, Mac, and Linux, and disabled by default on iOS and Android.

On touch devices, this shows the system's native on-screen keyboard when it's enabled.

love.keyboard.setTextInput( enable )

enable

boolean

Whether text input events should be enabled.

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

enable	boolean	Whether text input events should be enabled.
x	number	Text rectangle x position.
y	number	Text rectangle y position.
w	number	Text rectangle width.
h	number	Text rectangle height.

The A key

The B key

The C key

The D key

The E key

The F key

The G key

The H key

The I key

The J key

The K key

The L key

The M key

The N key

The O key

The P key

The Q key

The R key

The S key

The T key

The U key

The V key

The W key

The X key

The Y key

The Z key

The zero key

The one key

The two key

The three key

The four key

The five key

The six key

The seven key

The eight key

The nine key

space

Space key

Exclamation mark key

Double quote key

Hash key

Dollar key

Ampersand key

Single quote key

(

Left parenthesis key

)

Right parenthesis key

Asterisk key

Plus key

Comma key

Hyphen-minus key

Full stop key

Slash key

Colon key

;

Semicolon key

Less-than key

Equal key

Greater-than key

Question mark key

At sign key

[

Left square bracket key

Backslash key

]

Right square bracket key

Caret key

Underscore key

Grave accent key

kp0

The numpad zero key

kp1

The numpad one key

kp2

The numpad two key

kp3

The numpad three key

kp4

The numpad four key

kp5

The numpad five key

kp6

The numpad six key

kp7

The numpad seven key

kp8

The numpad eight key

kp9

The numpad nine key

kp.

The numpad decimal point key

kp/

The numpad division key

kp*

The numpad multiplication key

kp-

The numpad substraction key

kp+

The numpad addition key

kpenter

The numpad enter key

kp=

The numpad equals key

Up 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

The 1st function key

The 2nd function key

The 3rd function key

The 4th function key

The 5th function key

The 6th function key

The 7th function key

The 8th function key

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 key

sysreq

System request key

break

Break key

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

The 'A' key on an American layout.

The 'B' key on an American layout.

The 'C' key on an American layout.

The 'D' key on an American layout.

The 'E' key on an American layout.

The 'F' key on an American layout.

The 'G' key on an American layout.

The 'H' key on an American layout.

The 'I' key on an American layout.

The 'J' key on an American layout.

The 'K' key on an American layout.

The 'L' key on an American layout.

The 'M' key on an American layout.

The 'N' key on an American layout.

The 'O' key on an American layout.

The 'P' key on an American layout.

The 'Q' key on an American layout.

The 'R' key on an American layout.

The 'S' key on an American layout.

The 'T' key on an American layout.

The 'U' key on an American layout.

The 'V' key on an American layout.

The 'W' key on an American layout.

The 'X' key on an American layout.

The 'Y' key on an American layout.

The 'Z' key on an American layout.

The '1' key on an American layout.

The '2' key on an American layout.

The '3' key on an American layout.

The '4' key on an American layout.

The '5' key on an American layout.

The '6' key on an American layout.

The '7' key on an American layout.

The '8' key on an American layout.

The '9' key on an American layout.

The '0' key on an American layout.

return

The 'return' / 'enter' key on an American layout.

escape

The 'escape' key on an American layout.

backspace

The 'backspace' key on an American layout.

tab

The 'tab' key on an American layout.

space

The spacebar on an American layout.

The minus key on an American layout.

The equals key on an American layout.

[

The left-bracket key on an American layout.

]

The right-bracket key on an American layout.

The backslash key on an American layout.

nonus#

The non-U.S. hash scancode.

;

The semicolon key on an American layout.

The apostrophe key on an American layout.

The back-tick / grave key on an American layout.

The comma key on an American layout.

The period key on an American layout.

The forward-slash key on an American layout.

capslock

The capslock key on an American layout.

The F1 key on an American layout.

The F2 key on an American layout.

The F3 key on an American layout.

The F4 key on an American layout.

The F5 key on an American layout.

The F6 key on an American layout.

The F7 key on an American layout.

The F8 key on an American layout.

The F9 key on an American layout.

f10

The F10 key on an American layout.

f11

The F11 key on an American layout.

f12

The F12 key on an American layout.

f13

The F13 key on an American layout.

f14

The F14 key on an American layout.

f15

The F15 key on an American layout.

f16

The F16 key on an American layout.

f17

The F17 key on an American layout.

f18

The F18 key on an American layout.

f19

The F19 key on an American layout.

f20

The F20 key on an American layout.

f21

The F21 key on an American layout.

f22

The F22 key on an American layout.

f23

The F23 key on an American layout.

f24

The F24 key on an American layout.

lctrl

The left control key on an American layout.

lshift

The left shift key on an American layout.

lalt

The left alt / option key on an American layout.

lgui

The left GUI (command / windows / super) key on an American layout.

rctrl

The right control key on an American layout.

rshift

The right shift key on an American layout.

ralt

The right alt / option key on an American layout.

rgui

The right GUI (command / windows / super) key on an American layout.

printscreen

The printscreen key on an American layout.

scrolllock

The scroll-lock key on an American layout.

pause

The pause key on an American layout.

insert

The insert key on an American layout.

home

The home key on an American layout.

numlock

The numlock / clear key on an American layout.

pageup

The page-up key on an American layout.

delete

The forward-delete key on an American layout.

end

The end key on an American layout.

pagedown

The page-down key on an American layout.

right

The right-arrow key on an American layout.

left

The left-arrow key on an American layout.

down

The down-arrow key on an American layout.

The up-arrow key on an American layout.

nonusbackslash

The non-U.S. backslash scancode.

application

The application key on an American layout. Windows contextual menu, compose key.

execute

The 'execute' key on an American layout.

help

The 'help' key on an American layout.

The 'menu' key on an American layout.

select

The 'select' key on an American layout.

stop

The 'stop' key on an American layout.

again

The 'again' key on an American layout.

undo

The 'undo' key on an American layout.

cut

The 'cut' key on an American layout.

copy

The 'copy' key on an American layout.

paste

The 'paste' key on an American layout.

find

The 'find' key on an American layout.

kp/

The keypad forward-slash key on an American layout.

kp*

The keypad '*' key on an American layout.

kp-

The keypad minus key on an American layout.

kp+

The keypad plus key on an American layout.

kp=

The keypad equals key on an American layout.

kpenter

The keypad enter key on an American layout.

kp1

The keypad '1' key on an American layout.

kp2

The keypad '2' key on an American layout.

kp3

The keypad '3' key on an American layout.

kp4

The keypad '4' key on an American layout.

kp5

The keypad '5' key on an American layout.

kp6

The keypad '6' key on an American layout.

kp7

The keypad '7' key on an American layout.

kp8

The keypad '8' key on an American layout.

kp9

The keypad '9' key on an American layout.

kp0

The keypad '0' key on an American layout.

kp.

The keypad period key on an American layout.

international1

The 1st international key on an American layout. Used on Asian keyboards.

international2

The 2nd international key on an American layout.

international3

The 3rd international key on an American layout. Yen.

international4

The 4th international key on an American layout.

international5

The 5th international key on an American layout.

international6

The 6th international key on an American layout.

international7

The 7th international key on an American layout.

international8

The 8th international key on an American layout.

international9

The 9th international key on an American layout.

lang1

Hangul/English toggle scancode.

lang2

Hanja conversion scancode.

lang3

Katakana scancode.

lang4

Hiragana scancode.

lang5

Zenkaku/Hankaku scancode.

mute

The mute key on an American layout.

volumeup

The volume up key on an American layout.

volumedown

The volume down key on an American layout.

audionext

The audio next track key on an American layout.

audioprev

The audio previous track key on an American layout.

audiostop

The audio stop key on an American layout.

audioplay

The audio play key on an American layout.

audiomute

The audio mute key on an American layout.

mediaselect

The media select key on an American layout.

www

The 'WWW' key on an American layout.

mail

The Mail key on an American layout.

calculator

The calculator key on an American layout.

computer

The 'computer' key on an American layout.

acsearch

The AC Search key on an American layout.

achome

The AC Home key on an American layout.

acback

The AC Back key on an American layout.

acforward

The AC Forward key on an American layout.

acstop

Th AC Stop key on an American layout.

acrefresh

The AC Refresh key on an American layout.

acbookmarks

The AC Bookmarks key on an American layout.

power

The system power scancode.

brightnessdown

The brightness-down scancode.

brightnessup

The brightness-up scancode.

displayswitch

The display switch scancode.

kbdillumtoggle

The keyboard illumination toggle scancode.

kbdillumdown

The keyboard illumination down scancode.

kbdillumup

The keyboard illumination up scancode.

eject

The eject scancode.

sleep

The system sleep scancode.

alterase

The alt-erase key on an American layout.

sysreq

The sysreq key on an American layout.

cancel

The 'cancel' key on an American layout.

clear

The 'clear' key on an American layout.

prior

The 'prior' key on an American layout.

return2

The 'return2' key on an American layout.

separator

The 'separator' key on an American layout.

out

The 'out' key on an American layout.

oper

The 'oper' key on an American layout.

clearagain

The 'clearagain' key on an American layout.

crsel

The 'crsel' key on an American layout.

exsel

The 'exsel' key on an American layout.

kp00

The keypad 00 key on an American layout.

kp000

The keypad 000 key on an American layout.

thsousandsseparator

The thousands-separator key on an American layout.

decimalseparator

The decimal separator key on an American layout.

currencyunit

The currency unit key on an American layout.

currencysubunit

The currency sub-unit key on an American layout.

app1

The 'app1' scancode.

app2

The 'app2' scancode.

unknown

An unknown key.

Types

Functions

love.math.colorFromBytes

love.math.colorToBytes

love.math.noise

Random numbers

love.math.random

love.math.randomNormal

love.math.get/setRandomSeed

love.math.get/setRandomState

Polygons

love.math.isConvex

love.math.triangulate

Compression

love.math.compress

love.math.decompress

Color

love.math.linearToGamma

love.math.gammaToLinear

Enums

MatrixLayout

love.math.colorFromBytes

Converts a color from 0..255 to 0..1 range.

r, g, b, a = love.math.colorFromBytes( rb, gb, bb, ab )

r	number	Red color component in 0..1 range.
g	number	Green color component in 0..1 range.
b	number	Blue color component in 0..1 range.
a	number	Alpha color component in 0..1 range or nil if alpha is not specified.

rb	number	Red color component in 0..255 range.
gb	number	Green color component in 0..255 range.
bb	number	Blue color component in 0..255 range.
ab (nil)	number	Alpha color component in 0..255 range.

love.math.colorToBytes

Converts a color from 0..1 to 0..255 range.

rb, gb, bb, ab = love.math.colorToBytes( r, g, b, a )

rb	number	Red color component in 0..255 range.
gb	number	Green color component in 0..255 range.
bb	number	Blue color component in 0..255 range.
ab	number	Alpha color component in 0..255 range or nil if alpha is not specified.

r	number	Red color component.
g	number	Green color component.
b	number	Blue color component.
a (nil)	number	Alpha color component.

love.math.compress

Compresses a string or data using a specific compression algorithm.

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

compressedData

A new Data object containing the compressed version of the string.

rawstring	string	The raw (un-compressed) string to compress.
format ('lz4')	CompressedDataFormat	The format to use when compressing the string.
level (-1)	number	The level of compression to use, between 0 and 9. -1 indicates the default level. The meaning of this argument depends on the compression format being used.

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

compressedData

A new Data object containing the compressed version of the raw data.

data	Data	A Data object containing the raw (un-compressed) data to compress.
format ('lz4')	CompressedDataFormat	The format to use when compressing the data.
level (-1)	number	The level of compression to use, between 0 and 9. -1 indicates the default level. The meaning of this argument depends on the compression format being used.

love.math.decompress

Decompresses a CompressedData or previously compressed string or Data object.

rawstring = love.math.decompress( compressedData )

rawstring

string

A string containing the raw decompressed data.

compressedData

The compressed data to decompress.

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

rawstring

string

A string containing the raw decompressed data.

compressedstring	string	A string containing data previously compressed with love.math.compress.
format	CompressedDataFormat	The format that was used to compress the given string.

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

rawstring

string

A string containing the raw decompressed data.

data	Data	A Data object containing data previously compressed with love.math.compress.
format	CompressedDataFormat	The format that was used to compress the given data.

love.math.gammaToLinear

Converts a color from gamma-space (sRGB) to linear-space (RGB). This is useful when doing gamma-correct rendering and you need to do math in linear RGB in the few cases where LÖVE doesn't handle conversions automatically.

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

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

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

lr	number	The red channel of the converted color in linear RGB space.
lg	number	The green channel of the converted color in linear RGB space.
lb	number	The blue channel of the converted color in linear RGB space.

r	number	The red channel of the sRGB color to convert.
g	number	The green channel of the sRGB color to convert.
b	number	The blue channel of the sRGB color to convert.

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

lr	number	The red channel of the converted color in linear RGB space.
lg	number	The green channel of the converted color in linear RGB space.
lb	number	The blue channel of the converted color in linear RGB space.

color

table

An array with the red, green, and blue channels of the sRGB color to convert.

lc = love.math.gammaToLinear( c )

number

The value of the color channel in linear RGB space.

number

The value of a color channel in sRGB space to convert.

love.math.getRandomSeed

Gets the seed of the random number generator.

The seed is split into two numbers due to Lua's use of doubles for all number values - doubles can't accurately represent integer values above 2^53, but the seed can be an integer value up to 2^64.

low, high = love.math.getRandomSeed()

low	number	Integer number representing the lower 32 bits of the random number generator's 64 bit seed value.
high	number	Integer number representing the higher 32 bits of the random number generator's 64 bit seed value.

love.math.getRandomState

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

This is different from love.math.getRandomSeed in that getRandomState gets the random number generator's current state, whereas getRandomSeed gets the previously set seed number.

state = love.math.getRandomState()

state

string

The current state of the random number generator, represented as a string.

love.math.isConvex

Checks whether a polygon is convex.

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

convex = love.math.isConvex( vertices )

convex

boolean

Whether the given polygon is convex.

vertices

table

The vertices of the polygon as a table in the form of {x1, y1, x2, y2, x3, y3, ...}.

convex = love.math.isConvex( x1, y1, x2, y2, x3, y3 )

convex

boolean

Whether the given polygon is convex.

x1	number	The position of the first vertex of the polygon on the x-axis.
y1	number	The position of the first vertex of the polygon on the y-axis.
x2	number	The position of the second vertex of the polygon on the x-axis.
y2	number	The position of the second vertex of the polygon on the y-axis.
x3	number	The position of the third vertex of the polygon on the x-axis.
y3	number	The position of the third vertex of the polygon on the y-axis.

love.math.linearToGamma

Converts a color from linear-space (RGB) to gamma-space (sRGB). This is useful when storing linear RGB color values in an image, because the linear RGB color space has less precision than sRGB for dark colors, which can result in noticeable color banding when drawing.

In general, colors chosen based on what they look like on-screen are already in gamma-space and should not be double-converted. Colors calculated using math are often in the linear RGB space.

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

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

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

cr	number	The red channel of the converted color in gamma sRGB space.
cg	number	The green channel of the converted color in gamma sRGB space.
cb	number	The blue channel of the converted color in gamma sRGB space.

lr	number	The red channel of the linear RGB color to convert.
lg	number	The green channel of the linear RGB color to convert.
lb	number	The blue channel of the linear RGB color to convert.

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

cr	number	The red channel of the converted color in gamma sRGB space.
cg	number	The green channel of the converted color in gamma sRGB space.
cb	number	The blue channel of the converted color in gamma sRGB space.

color

table

An array with the red, green, and blue channels of the linear RGB color to convert.

c = love.math.linearToGamma( lc )

number

The value of the color channel in gamma sRGB space.

number

The value of a color channel in linear RGB space to convert.

love.math.newBezierCurve

Creates a new BezierCurve object.

The number of vertices in the control polygon determines the degree of the curve, e.g. three vertices define a quadratic (degree 2) Bézier curve, four vertices define a cubic (degree 3) Bézier curve, etc.

curve = love.math.newBezierCurve( vertices )

curve

A Bézier curve object.

vertices

table

The vertices of the control polygon as a table in the form of {x1, y1, x2, y2, x3, y3, ...}.

curve = love.math.newBezierCurve( x1, y1, x2, y2, x3, y3 )

curve

love.math.newRandomGenerator

A Bézier curve object.

x1	number	The position of the first vertex of the control polygon on the x-axis.
y1	number	The position of the first vertex of the control polygon on the y-axis.
x2	number	The position of the second vertex of the control polygon on the x-axis.
y2	number	The position of the second vertex of the control polygon on the y-axis.
x3	number	The position of the third vertex of the control polygon on the x-axis.
y3	number	The position of the third vertex of the control polygon on the y-axis.

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

rng = love.math.newRandomGenerator()

rng

The new Random Number Generator object.

rng = love.math.newRandomGenerator( seed )

rng

The new Random Number Generator object.

seed

number

The initial seed number to use for this object.

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

rng

The new Random Number Generator object.

low	number	The lower 32 bits of the seed number to use for this object.
high	number	The higher 32 bits of the seed number to use for this object.

love.math.newTransform

Creates a new Transform object.

transform = love.math.newTransform()

transform

The new Transform object.

transform = love.math.newTransform( x, y, angle, sx, sy, ox, oy, kx, ky )

transform

The new Transform object.

x	number	The position of the new Transform on the x-axis.
y	number	The position of the new Transform on the y-axis.
angle (0)	number	The orientation of the new Transform in radians.
sx (1)	number	Scale factor on the x-axis.
sy (sx)	number	Scale factor on the y-axis.
ox (0)	number	Origin offset on the x-axis.
oy (0)	number	Origin offset on the y-axis.
kx (0)	number	Shearing / skew factor on the x-axis.
ky (0)	number	Shearing / skew factor on the y-axis.

love.math.noise

Generates a Simplex or Perlin noise value in 1-4 dimensions. The return value will always be the same, given the same arguments.

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

There are many webpages which discuss Perlin and Simplex noise in detail.

value = love.math.noise( x )

value

number

The noise value in the range of 1.

number

The number used to generate the noise value.

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

value

number

The noise value in the range of 1.

x	number	The first value of the 2-dimensional vector used to generate the noise value.
y	number	The second value of the 2-dimensional vector used to generate the noise value.

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

value

number

The noise value in the range of 1.

x	number	The first value of the 3-dimensional vector used to generate the noise value.
y	number	The second value of the 3-dimensional vector used to generate the noise value.
z	number	The third value of the 3-dimensional vector used to generate the noise value.

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

value

number

The noise value in the range of 1.

x	number	The first value of the 4-dimensional vector used to generate the noise value.
y	number	The second value of the 4-dimensional vector used to generate the noise value.
z	number	The third value of the 4-dimensional vector used to generate the noise value.
w	number	The fourth value of the 4-dimensional vector used to generate the noise value.

love.math.random

Generates a pseudo-random number in a platform independent manner. The default love.run seeds this function at startup, so you generally don't need to seed it yourself.

number = love.math.random()

number

The pseudo-random number.

number = love.math.random( max )

number

The pseudo-random integer number.

max

number

The maximum possible value it should return.

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

number

The pseudo-random integer number.

min	number	The minimum possible value it should return.
max	number	The maximum possible value it should return.

love.math.randomNormal

Get a normally distributed pseudo random number.

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

number

Normally distributed random number with variance (stddev)² and the specified mean.

stddev (1)	number	Standard deviation of the distribution.
mean (0)	number	The mean of the distribution.

love.math.setRandomSeed

Sets the seed of the random number generator using the specified integer number. This is called internally at startup, so you generally don't need to call it yourself.

love.math.setRandomSeed( seed )

seed

number

The integer number with which you want to seed the randomization. Must be within the range of 2^53 - 1.

love.math.setRandomSeed( low, high )

low	number	The lower 32 bits of the seed value. Must be within the range of 2^32 - 1.
high	number	The higher 32 bits of the seed value. Must be within the range of 2^32 - 1.

love.math.setRandomState

Sets the current state of the random number generator. The value used as an argument for this function is an opaque implementation-dependent string and should only originate from a previous call to love.math.getRandomState.

This is different from love.math.setRandomSeed in that setRandomState directly sets the random number generator's current implementation-dependent state, whereas setRandomSeed gives it a new seed value.

love.math.setRandomState( state )

state

string

The new state of the random number generator, represented as a string. This should originate from a previous call to love.math.getRandomState.

love.math.triangulate

Decomposes a simple convex or concave polygon into triangles.

triangles = love.math.triangulate( polygon )

triangles

table

List of triangles the polygon is composed of, in the form of {{x1, y1, x2, y2, x3, y3}, {x1, y1, x2, y2, x3, y3}, ...}.

polygon

table

Polygon to triangulate. Must not intersect itself.

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

triangles

table

List of triangles the polygon is composed of, in the form of {{x1, y1, x2, y2, x3, y3}, {x1, y1, x2, y2, x3, y3}, ...}.

x1	number	The position of the first vertex of the polygon on the x-axis.
y1	number	The position of the first vertex of the polygon on the y-axis.
x2	number	The position of the second vertex of the polygon on the x-axis.
y2	number	The position of the second vertex of the polygon on the y-axis.
x3	number	The position of the third vertex of the polygon on the x-axis.
y3	number	The position of the third vertex of the polygon on the y-axis.

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

For more information on Bézier curves check this great article on Wikipedia.

Constructors

love.math.newBezierCurve

Functions

BezierCurve:evaluate

BezierCurve:get/setControlPoint

BezierCurve:getControlPointCount

BezierCurve:getDegree

BezierCurve:getDerivative

BezierCurve:getSegment

BezierCurve:insertControlPoint

BezierCurve:removeControlPoint

BezierCurve:render

BezierCurve:renderSegment

BezierCurve:rotate

BezierCurve:scale

BezierCurve:translate

Supertypes

BezierCurve:getControlPoint

BezierCurve:evaluate

Evaluate Bézier curve at parameter t. The parameter must be between 0 and 1 (inclusive).

This function can be used to move objects along paths or tween parameters. However it should not be used to render the curve, see BezierCurve:render for that purpose.

x, y = BezierCurve:evaluate( t )

x	number	x coordinate of the curve at parameter t.
y	number	y coordinate of the curve at parameter t.

number

Where to evaluate the curve.

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

x, y = BezierCurve:getControlPoint( i )

x	number	Position of the control point along the x axis.
y	number	Position of the control point along the y axis.

number

Index of the control point.

BezierCurve:getControlPointCount

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

count = BezierCurve:getControlPointCount()

count

number

The number of control points.

BezierCurve:getDegree

Get degree of the Bézier curve. The degree is equal to number-of-control-points - 1.

degree = BezierCurve:getDegree()

degree

number

Degree of the Bézier curve.

BezierCurve:getDerivative

Get the derivative of the Bézier curve.

This function can be used to rotate sprites moving along a curve in the direction of the movement and compute the direction perpendicular to the curve at some parameter t.

derivative = BezierCurve:getDerivative()

derivative

The derivative curve.

BezierCurve:getSegment

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

curve = BezierCurve:getSegment( startpoint, endpoint )

curve

BezierCurve:insertControlPoint

A BezierCurve that corresponds to the specified segment.

startpoint	number	The starting point along the curve. Must be between 0 and 1.
endpoint	number	The end of the segment. Must be between 0 and 1.

Insert control point as the new i-th control point. Existing control points from i onwards are pushed back by 1. Indices start with 1. Negative indices wrap around: -1 is the last control point, -2 the one before the last, etc.

BezierCurve:insertControlPoint( x, y, i )

x	number	Position of the control point along the x axis.
y	number	Position of the control point along the y axis.
i (-1)	number	Index of the control point.

BezierCurve:removeControlPoint

Removes the specified control point.

BezierCurve:removeControlPoint( index )

index

number

The index of the control point to remove.

BezierCurve:render

Get a list of coordinates to be used with love.graphics.line.

This function samples the Bézier curve using recursive subdivision. You can control the recursion depth using the depth parameter.

If you are just interested to know the position on the curve given a parameter, use BezierCurve:evaluate.

coordinates = BezierCurve:render( depth )

coordinates

table

List of x,y-coordinate pairs of points on the curve.

depth (5)

number

Number of recursive subdivision steps.

BezierCurve:renderSegment

Get a list of coordinates on a specific part of the curve, to be used with love.graphics.line.

This function samples the Bézier curve using recursive subdivision. You can control the recursion depth using the depth parameter.

If you are just need to know the position on the curve given a parameter, use BezierCurve:evaluate.

coordinates = BezierCurve:renderSegment( startpoint, endpoint, depth )

coordinates

table

List of x,y-coordinate pairs of points on the specified part of the curve.

startpoint	number	The starting point along the curve. Must be between 0 and 1.
endpoint	number	The end of the segment to render. Must be between 0 and 1.
depth (5)	number	Number of recursive subdivision steps.

BezierCurve:rotate

Rotate the Bézier curve by an angle.

BezierCurve:rotate( angle, ox, oy )

angle	number	Rotation angle in radians.
ox (0)	number	X coordinate of the rotation center.
oy (0)	number	Y coordinate of the rotation center.

BezierCurve:scale

Scale the Bézier curve by a factor.

BezierCurve:scale( s, ox, oy )

s	number	Scale factor.
ox (0)	number	X coordinate of the scaling center.
oy (0)	number	Y coordinate of the scaling center.

BezierCurve:setControlPoint

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

BezierCurve:setControlPoint( i, x, y )

i	number	Index of the control point.
x	number	Position of the control point along the x axis.
y	number	Position of the control point along the y axis.

BezierCurve:translate

Move the Bézier curve by an offset.

BezierCurve:translate( dx, dy )

dx	number	Offset along the x axis.
dy	number	Offset along the y axis.

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

Constructors

love.math.newRandomGenerator

Functions

RandomGenerator:get/setSeed

RandomGenerator:get/setState

RandomGenerator:random

RandomGenerator:randomNormal

Supertypes

RandomGenerator:randomNormal

RandomGenerator:getSeed

Gets the seed of the random number generator object.

The seed is split into two numbers due to Lua's use of doubles for all number values - doubles can't accurately represent integer values above 2^53, but the seed value is an integer number in the range of 2^64 - 1.

low, high = RandomGenerator:getSeed()

low	number	Integer number representing the lower 32 bits of the RandomGenerator's 64 bit seed value.
high	number	Integer number representing the higher 32 bits of the RandomGenerator's 64 bit seed value.

RandomGenerator:getState

Gets the current state of the random number generator. This returns an opaque string which is only useful for later use with RandomGenerator:setState in the same major version of LÖVE.

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

state = RandomGenerator:getState()

state

string

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

RandomGenerator:random

Generates a pseudo-random number in a platform independent manner.

number = RandomGenerator:random()

number

The pseudo-random number.

number = RandomGenerator:random( max )

number

The pseudo-random integer number.

max

number

The maximum possible value it should return.

number = RandomGenerator:random( min, max )

number

The pseudo-random integer number.

min	number	The minimum possible value it should return.
max	number	The maximum possible value it should return.

Get a normally distributed pseudo random number.

number = RandomGenerator:randomNormal( stddev, mean )

number

Normally distributed random number with variance (stddev)² and the specified mean.

stddev (1)	number	Standard deviation of the distribution.
mean (0)	number	The mean of the distribution.

RandomGenerator:setSeed

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

RandomGenerator:setSeed( seed )

seed

number

The integer number with which you want to seed the randomization. Must be within the range of 2^53.

RandomGenerator:setSeed( low, high )

low	number	The lower 32 bits of the seed value. Must be within the range of 2^32 - 1.
high	number	The higher 32 bits of the seed value. Must be within the range of 2^32 - 1.

RandomGenerator:setState

Sets the current state of the random number generator. The value used as an argument for this function is an opaque string and should only originate from a previous call to RandomGenerator:getState in the same major version of LÖVE.

This is different from RandomGenerator:setSeed in that setState directly sets the RandomGenerator's current implementation-dependent state, whereas setSeed gives it a new seed value.

RandomGenerator:setState( state )

state

string

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

Object containing a coordinate system transformation.

The love.graphics module has several functions and function variants which accept Transform objects.

Constructors

love.math.newTransform

Functions

Transform:apply

Transform:clone

Transform:get/setMatrix

Transform:inverse

Transform:inverseTransformPoint

Transform:isAffine2DTransform

Transform:reset

Transform:rotate

Transform:scale

Transform:setTransformation

Transform:shear

Transform:transformPoint

Transform:translate

Supertypes

Transform:apply

Applies the given other Transform object to this one.

This effectively multiplies this Transform's internal transformation matrix with the other Transform's (i.e. self * other), and stores the result in this object.

transform = Transform:apply( other )

transform

The Transform object the method was called on. Allows easily chaining Transform methods.

other

The other Transform object to apply to this Transform.

Transform:clone

Creates a new copy of this Transform.

clone = Transform:clone()

clone

The copy of this Transform.

Transform:getMatrix

Gets the internal 4x4 transformation matrix stored by this Transform. The matrix is returned in row-major order.

e1_1, e1_2, e1_3, e1_4, e2_1, e2_2, e2_3, e2_4, e3_1, e3_2, e3_3, e3_4, e4_1, e4_2, e4_3, e4_4 = Transform:getMatrix()

e1_1	number	The first column of the first row of the matrix.
e1_2	number	The second column of the first row of the matrix.
e1_3	number	The third column of the first row of the matrix.
e1_4	number	The fourth column of the first row of the matrix.
e2_1	number	The first column of the second row of the matrix.
e2_2	number	The second column of the second row of the matrix.
e2_3	number	The third column of the second row of the matrix.
e2_4	number	The fourth column of the second row of the matrix.
e3_1	number	The first column of the third row of the matrix.
e3_2	number	The second column of the third row of the matrix.
e3_3	number	The third column of the third row of the matrix.
e3_4	number	The fourth column of the third row of the matrix.
e4_1	number	The first column of the fourth row of the matrix.
e4_2	number	The second column of the fourth row of the matrix.
e4_3	number	The third column of the fourth row of the matrix.
e4_4	number	The fourth column of the fourth row of the matrix.

Transform:inverse

Creates a new Transform containing the inverse of this Transform.

inverse = Transform:inverse()

inverse

Transform:inverseTransformPoint

A new Transform object representing the inverse of this Transform's matrix.

Applies the reverse of the Transform object's transformation to the given 2D position.

This effectively converts the given position from the local coordinate space of the Transform into global coordinates.

One use of this method can be to convert a screen-space mouse position into global world coordinates, if the given Transform has transformations applied that are used for a camera system in-game.

globalX, globalY = Transform:inverseTransformPoint( localX, localY )

globalX	number	The x component of the position in global coordinates.
globalY	number	The y component of the position in global coordinates.

localX	number	The x component of the position with the transform applied.
localY	number	The y component of the position with the transform applied.

Transform:isAffine2DTransform

Checks whether the Transform is an affine transformation.

affine = Transform:isAffine2DTransform()

affine

boolean

true if the transform object is an affine transformation, false otherwise.

Transform:reset

Resets the Transform to an identity state. All previously applied transformations are erased.

transform = Transform:reset()

transform

The Transform object the method was called on. Allows easily chaining Transform methods.

Transform:rotate

Applies a rotation to the Transform's coordinate system. This method does not reset any previously applied transformations.

transform = Transform:rotate( angle )

transform

The Transform object the method was called on. Allows easily chaining Transform methods.

angle

number

The relative angle in radians to rotate this Transform by.

Transform:scale

Scales the Transform's coordinate system. This method does not reset any previously applied transformations.

transform = Transform:scale( sx, sy )

transform

The Transform object the method was called on. Allows easily chaining Transform methods.

sx	number	The relative scale factor along the x-axis.
sy (sx)	number	The relative scale factor along the y-axis.

Transform:setMatrix

Directly sets the Transform's internal 4x4 transformation matrix.

transform = Transform:setMatrix( e1_1, e1_2, e1_3, e1_4, e2_1, e2_2, e2_3, e2_4, e3_1, e3_2, e3_3, e3_4, e4_1, e4_2, e4_3, e4_4 )

transform

The Transform object the method was called on. Allows easily chaining Transform methods.

e1_1	number	The first column of the first row of the matrix.
e1_2	number	The second column of the first row of the matrix.
e1_3	number	The third column of the first row of the matrix.
e1_4	number	The fourth column of the first row of the matrix.
e2_1	number	The first column of the second row of the matrix.
e2_2	number	The second column of the second row of the matrix.
e2_3	number	The third column of the second row of the matrix.
e2_4	number	The fourth column of the second row of the matrix.
e3_1	number	The first column of the third row of the matrix.
e3_2	number	The second column of the third row of the matrix.
e3_3	number	The third column of the third row of the matrix.
e3_4	number	The fourth column of the third row of the matrix.
e4_1	number	The first column of the fourth row of the matrix.
e4_2	number	The second column of the fourth row of the matrix.
e4_3	number	The third column of the fourth row of the matrix.
e4_4	number	The fourth column of the fourth row of the matrix.

transform = Transform:setMatrix( layout, e1_1, e1_2, e1_3, e1_4, e2_1, e2_2, e2_3, e2_4, e3_1, e3_2, e3_3, e3_4, e4_1, e4_2, e4_3, e4_4 )

transform

The Transform object the method was called on. Allows easily chaining Transform methods.

layout	MatrixLayout	How to interpret the matrix element arguments (row-major or column-major).
e1_1	number	The first column of the first row of the matrix.
e1_2	number	The second column of the first row or the first column of the second row of the matrix, depending on the specified layout.
e1_3	number	The third column/row of the first row/column of the matrix.
e1_4	number	The fourth column/row of the first row/column of the matrix.
e2_1	number	The first column/row of the second row/column of the matrix.
e2_2	number	The second column/row of the second row/column of the matrix.
e2_3	number	The third column/row of the second row/column of the matrix.
e2_4	number	The fourth column/row of the second row/column of the matrix.
e3_1	number	The first column/row of the third row/column of the matrix.
e3_2	number	The second column/row of the third row/column of the matrix.
e3_3	number	The third column/row of the third row/column of the matrix.
e3_4	number	The fourth column/row of the third row/column of the matrix.
e4_1	number	The first column/row of the fourth row/column of the matrix.
e4_2	number	The second column/row of the fourth row/column of the matrix.
e4_3	number	The third column/row of the fourth row/column of the matrix.
e4_4	number	The fourth column of the fourth row of the matrix.

transform = Transform:setMatrix( layout, matrix )

transform

The Transform object the method was called on. Allows easily chaining Transform methods.

layout	MatrixLayout	How to interpret the matrix element arguments (row-major or column-major).
matrix	table	A flat table containing the 16 matrix elements.

transform = Transform:setMatrix( layout, matrix )

transform

Transform:setTransformation

The Transform object the method was called on. Allows easily chaining Transform methods.

layout	MatrixLayout	How to interpret the matrix element arguments (row-major or column-major).
matrix	table	A table of 4 tables, with each sub-table containing 4 matrix elements.

Resets the Transform to the specified transformation parameters.

transform = Transform:setTransformation( x, y, angle, sx, sy, ox, oy, kx, ky )

transform

The Transform object the method was called on. Allows easily chaining Transform methods.

x	number	The position of the Transform on the x-axis.
y	number	The position of the Transform on the y-axis.
angle (0)	number	The orientation of the Transform in radians.
sx (1)	number	Scale factor on the x-axis.
sy (sx)	number	Scale factor on the y-axis.
ox (0)	number	Origin offset on the x-axis.
oy (0)	number	Origin offset on the y-axis.
kx (0)	number	Shearing / skew factor on the x-axis.
ky (0)	number	Shearing / skew factor on the y-axis.

Transform:shear

Applies a shear factor (skew) to the Transform's coordinate system. This method does not reset any previously applied transformations.

transform = Transform:shear( kx, ky )

transform

The Transform object the method was called on. Allows easily chaining Transform methods.

kx	number	The shear factor along the x-axis.
ky	number	The shear factor along the y-axis.

Transform:transformPoint

Applies the Transform object's transformation to the given 2D position.

This effectively converts the given position from global coordinates into the local coordinate space of the Transform.

localX, localY = Transform:transformPoint( globalX, globalY )

localX	number	The x component of the position with the transform applied.
localY	number	The y component of the position with the transform applied.

globalX	number	The x component of the position in global coordinates.
globalY	number	The y component of the position in global coordinates.

Transform:translate

Applies a translation to the Transform's coordinate system. This method does not reset any previously applied transformations.

transform = Transform:translate( dx, dy )

transform

The Transform object the method was called on. Allows easily chaining Transform methods.

dx	number	The relative translation along the x-axis.
dy	number	The relative translation along the y-axis.

MatrixLayout

row

The matrix is row-major:

column

The matrix is column-major:

love.mouse

Types

Functions

love.mouse.get/setRelativeMode

love.mouse.isCursorSupported

love.mouse.is/setGrabbed

love.mouse.is/setVisible

Input

love.mouse.isDown

love.mouse.get/setPosition

love.mouse.get/setX

love.mouse.get/setY

Cursor

love.mouse.get/setCursor

love.mouse.getSystemCursor

Enums

love.mouse.getCursor

Gets the current Cursor.

cursor = love.mouse.getCursor()

cursor

love.mouse.getRelativeMode

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

love.mouse.getPosition

Returns the current position of the mouse.

x, y = love.mouse.getPosition()

x	number	The position of the mouse along the x-axis.
y	number	The position of the mouse along the y-axis.

Gets whether relative mode is enabled for the mouse.

If relative mode is enabled, the cursor is hidden and doesn't move when the mouse does, but relative mouse motion events are still generated via love.mousemoved. This lets the mouse move in any direction indefinitely without the cursor getting stuck at the edges of the screen.

The reported position of the mouse is not updated while relative mode is enabled, even when relative mouse motion events are generated.

enabled = love.mouse.getRelativeMode()

enabled

boolean

True if relative mode is enabled, false if it's disabled.

love.mouse.getSystemCursor

Gets a Cursor object representing a system-native hardware cursor.

Hardware cursors are framerate-independent and work the same way as normal operating system cursors. Unlike drawing an image at the mouse's current coordinates, hardware cursors never have visible lag between when the mouse is moved and when the cursor position updates, even at low framerates.

cursor = love.mouse.getSystemCursor( ctype )

cursor

The Cursor object representing the system cursor type.

ctype

love.mouse.isCursorSupported

The type of system cursor to get.

love.mouse.getX

Returns the current x-position of the mouse.

x = love.mouse.getX()

number

The position of the mouse along the x-axis.

love.mouse.getY

Returns the current y-position of the mouse.

y = love.mouse.getY()

number

The position of the mouse along the y-axis.

Gets whether cursor functionality is supported.

If it isn't supported, calling love.mouse.newCursor and love.mouse.getSystemCursor will cause an error. Mobile devices do not support cursors.

supported = love.mouse.isCursorSupported()

supported

boolean

Whether the system has cursor functionality.

love.mouse.isDown

Checks whether a certain mouse button is down.

This function does not detect mouse wheel scrolling; you must use the love.wheelmoved (or love.mousepressed in version 0.9.2 and older) callback for that.

down = love.mouse.isDown( button, ... )

down

boolean

True if any specified button is down.

button	number	The index of a button to check. 1 is the primary mouse button, 2 is the secondary mouse button and 3 is the middle button. Further buttons are mouse dependant.
...	number	Additional button numbers to check.

love.mouse.isGrabbed

Checks if the mouse is grabbed.

grabbed = love.mouse.isGrabbed()

grabbed

boolean

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

love.mouse.isVisible

Checks if the cursor is visible.

visible = love.mouse.isVisible()

visible

boolean

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

love.mouse.newCursor

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

Hardware cursors are framerate-independent and work the same way as normal operating system cursors. Unlike drawing an image at the mouse's current coordinates, hardware cursors never have visible lag between when the mouse is moved and when the cursor position updates, even at low framerates.

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

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

cursor

The new Cursor object.

imageData	ImageData	The ImageData to use for the new Cursor.
hotx (0)	number	The x-coordinate in the ImageData of the cursor's hot spot.
hoty (0)	number	The y-coordinate in the ImageData of the cursor's hot spot.

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

cursor

The new Cursor object.

filename	string	Path to the image to use for the new Cursor.
hotx (0)	number	The x-coordinate in the image of the cursor's hot spot.
hoty (0)	number	The y-coordinate in the image of the cursor's hot spot.

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

cursor

The new Cursor object.

fileData	FileData	Data representing the image to use for the new Cursor.
hotx (0)	number	The x-coordinate in the image of the cursor's hot spot.
hoty (0)	number	The y-coordinate in the image of the cursor's hot spot.

love.mouse.setCursor

Sets the current mouse cursor.

love.mouse.setCursor( cursor )

cursor

love.mouse.setRelativeMode

The Cursor object to use as the current mouse cursor.

love.mouse.setCursor()

love.mouse.setGrabbed

Grabs the mouse and confines it to the window.

love.mouse.setGrabbed( grab )

grab

boolean

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

love.mouse.setPosition

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

love.mouse.setPosition( x, y )

x	number	The new position of the mouse along the x-axis.
y	number	The new position of the mouse along the y-axis.

Sets whether relative mode is enabled for the mouse.

When relative mode is enabled, the cursor is hidden and doesn't move when the mouse does, but relative mouse motion events are still generated via love.mousemoved. This lets the mouse move in any direction indefinitely without the cursor getting stuck at the edges of the screen.

The reported position of the mouse may not be updated while relative mode is enabled, even when relative mouse motion events are generated.

love.mouse.setRelativeMode( enable )

enable

boolean

True to enable relative mode, false to disable it.

love.mouse.setVisible

Sets the current visibility of the cursor.

love.mouse.setVisible( visible )

visible

boolean

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

love.mouse.setX

Sets the current X position of the mouse.

Non-integer values are floored.

love.mouse.setX( x )

number

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

love.mouse.setY

Sets the current Y position of the mouse.

Non-integer values are floored.

love.mouse.setY( y )

number

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

Represents a hardware cursor.

Constructors

love.mouse.getCursor

love.mouse.newCursor

love.mouse.getSystemCursor

Functions

Cursor:getType

Supertypes

Cursor:getType

Gets the type of the Cursor.

ctype = Cursor:getType()

ctype

The type of the Cursor.

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.

Slashed circle or crossbones.

hand

Hand symbol.

Types

Functions

love.physics.getDistance

love.physics.get/setMeter

Enums

JointType

ShapeType

love.physics.getDistance

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

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

distance	number	The distance of the two points.
x1	number	The x-coordinate of the first point.
y1	number	The y-coordinate of the first point.
x2	number	The x-coordinate of the second point.
y2	number	The y-coordinate of the second point.

fixture1	Fixture	The first fixture.
fixture2	Fixture	The second fixture.

love.physics.getMeter

Returns the meter scale factor.

All coordinates in the physics module are divided by this number, creating 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.

scale = love.physics.getMeter()

scale

number

The scale factor as an integer.

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 )

body

love.physics.newChainShape

A new body.

world	World	The world to create the body in.
x (0)	number	The x position of the body.
y (0)	number	The y position of the body.
type ('static')	BodyType	The type of the body.

Creates a new ChainShape.

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

shape

ChainShape

The new shape.

loop	boolean	If the chain should loop back to the first point.
x1	number	The x position of the first point.
y1	number	The y position of the first point.
x2	number	The x position of the second point.
y2	number	The y position of the second point.
...	number	Additional point positions.

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

shape

ChainShape

The new shape.

loop	boolean	If the chain should loop back to the first point.
points	table	A list of points to construct the ChainShape, in the form of {x1, y1, x2, y2, ...}.

love.physics.newCircleShape

Creates a new CircleShape.

shape = love.physics.newCircleShape( radius )

shape

CircleShape

The new shape.

radius

number

The radius of the circle.

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

shape

CircleShape

The new shape.

x	number	The x position of the circle.
y	number	The y position of the circle.
radius	number	The radius of the circle.

love.physics.newDistanceJoint

Creates a DistanceJoint 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 )

joint

DistanceJoint

The new distance joint.

body1	Body	The first body to attach to the joint.
body2	Body	The second body to attach to the joint.
x1	number	The x position of the first anchor point (world space).
y1	number	The y position of the first anchor point (world space).
x2	number	The x position of the second anchor point (world space).
y2	number	The y position of the second anchor point (world space).
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

love.physics.newEdgeShape

Creates a new EdgeShape.

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

shape

EdgeShape

The new shape.

x1	number	The x position of the first point.
y1	number	The y position of the first point.
x2	number	The x position of the second point.
y2	number	The y position of the second point.

love.physics.newFixture

Creates and attaches a Fixture to a body.

Note that the Shape object is copied rather than kept as a reference when the Fixture is created. To get the Shape object that the Fixture owns, use Fixture:getShape.

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

fixture

Fixture

The new fixture.

body	Body	The body which gets the fixture attached.
shape	Shape	The shape to be copied to the fixture.
density (1)	number	The 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 )

joint

FrictionJoint

The new FrictionJoint.

body1	Body	The first body to attach to the joint.
body2	Body	The second body to attach to the joint.
x	number	The x position of the anchor point.
y	number	The y position of the anchor point.
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

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

joint

FrictionJoint

The new FrictionJoint.

body1	Body	The first body to attach to the joint.
body2	Body	The second body to attach to the joint.
x1	number	The x position of the first anchor point.
y1	number	The y position of the first anchor point.
x2	number	The x position of the second anchor point.
y2	number	The y position of the second anchor point.
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

love.physics.newGearJoint

Create a GearJoint 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 )

joint

GearJoint

The new gear joint.

joint1	Joint	The first joint to connect with a gear joint.
joint2	Joint	The second joint to connect with a gear joint.
ratio (1)	number	The gear ratio.
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

love.physics.newMotorJoint

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

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

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

joint

MotorJoint

The new MotorJoint.

body1	Body	The first body to attach to the joint.
body2	Body	The second body to attach to the joint.
correctionFactor (0.3)	number	The joint's initial position correction factor, in the range of 1.

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

joint

MotorJoint

The new MotorJoint.

body1	Body	The first body to attach to the joint.
body2	Body	The second body to attach to the joint.
correctionFactor (0.3)	number	The joint's initial position correction factor, in the range of 1.
collideConnected (false)	boolean	Specifies 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 )

joint

MouseJoint

The new mouse joint.

body	Body	The body to attach to the mouse.
x	number	The x position of the connecting point.
y	number	The y position of the connecting point.

love.physics.newPolygonShape

Creates a new PolygonShape.

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

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

shape

A new PolygonShape.

x1	number	The x position of the first point.
y1	number	The y position of the first point.
x2	number	The x position of the second point.
y2	number	The y position of the second point.
x3	number	The x position of the third point.
y3	number	The y position of the third point.
...	number	You can continue passing more point positions to create the PolygonShape.

shape = love.physics.newPolygonShape( vertices )

shape

love.physics.newPrismaticJoint

A new PolygonShape.

vertices

table

A list of vertices to construct the polygon, in the form of {x1, y1, x2, y2, x3, y3, ...}.

Creates a PrismaticJoint 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 )

joint

The new prismatic joint.

body1	Body	The first body to connect with a prismatic joint.
body2	Body	The second body to connect with a prismatic joint.
x	number	The x coordinate of the anchor point.
y	number	The y coordinate of the anchor point.
ax	number	The x coordinate of the axis vector.
ay	number	The y coordinate of the axis vector.
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

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

joint

The new prismatic joint.

body1	Body	The first body to connect with a prismatic joint.
body2	Body	The second body to connect with a prismatic joint.
x1	number	The x coordinate of the first anchor point.
y1	number	The y coordinate of the first anchor point.
x2	number	The x coordinate of the second anchor point.
y2	number	The y coordinate of the second anchor point.
ax	number	The x coordinate of the axis unit vector.
ay	number	The y coordinate of the axis unit vector.
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

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

joint

love.physics.newPulleyJoint

The new prismatic joint.

body1	Body	The first body to connect with a prismatic joint.
body2	Body	The second body to connect with a prismatic joint.
x1	number	The x coordinate of the first anchor point.
y1	number	The y coordinate of the first anchor point.
x2	number	The x coordinate of the second anchor point.
y2	number	The y coordinate of the second anchor point.
ax	number	The x coordinate of the axis unit vector.
ay	number	The y coordinate of the axis unit vector.
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.
referenceAngle (0)	number	The reference angle between body1 and body2, in radians.

Creates a PulleyJoint 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 )

joint

PulleyJoint

The new pulley joint.

body1	Body	The first body to connect with a pulley joint.
body2	Body	The second body to connect with a pulley joint.
gx1	number	The x coordinate of the first body's ground anchor.
gy1	number	The y coordinate of the first body's ground anchor.
gx2	number	The x coordinate of the second body's ground anchor.
gy2	number	The y coordinate of the second body's ground anchor.
x1	number	The x coordinate of the pulley joint anchor in the first body.
y1	number	The y coordinate of the pulley joint anchor in the first body.
x2	number	The x coordinate of the pulley joint anchor in the second body.
y2	number	The y coordinate of the pulley joint anchor in the second body.
ratio (1)	number	The joint ratio.
collideConnected (true)	boolean	Specifies whether the two bodies should collide with each other.

love.physics.newRectangleShape

Shorthand for creating rectangular PolygonShapes.

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

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

shape

A new PolygonShape.

width	number	The width of the rectangle.
height	number	The height of the rectangle.

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

shape

love.physics.newRevoluteJoint

A new PolygonShape.

x	number	The offset along the x-axis.
y	number	The offset along the y-axis.
width	number	The width of the rectangle.
height	number	The height of the rectangle.
angle (0)	number	The initial angle of the rectangle.

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 )

joint

RevoluteJoint

The new revolute joint.

body1	Body	The first body.
body2	Body	The second body.
x	number	The x position of the connecting point.
y	number	The y position of the connecting point.
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

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

joint

RevoluteJoint

The new revolute joint.

body1	Body	The first body.
body2	Body	The second body.
x1	number	The x position of the first connecting point.
y1	number	The y position of the first connecting point.
x2	number	The x position of the second connecting point.
y2	number	The y position of the second connecting point.
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.
referenceAngle (0)	number	The reference angle between body1 and body2, in radians.

love.physics.newRopeJoint

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

joint

RopeJoint

The new RopeJoint.

body1	Body	The first body to attach to the joint.
body2	Body	The second body to attach to the joint.
x1	number	The x position of the first anchor point.
y1	number	The y position of the first anchor point.
x2	number	The x position of the second anchor point.
y2	number	The y position of the second anchor point.
maxLength	number	The maximum distance for the bodies.
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

love.physics.newWeldJoint

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

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

joint

The new WeldJoint.

body1	Body	The first body to attach to the joint.
body2	Body	The second body to attach to the joint.
x	number	The x position of the anchor point (world space).
y	number	The y position of the anchor point (world space).
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

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

joint

The new WeldJoint.

body1	Body	The first body to attach to the joint.
body2	Body	The second body to attach to the joint.
x1	number	The x position of the first anchor point (world space).
y1	number	The y position of the first anchor point (world space).
x2	number	The x position of the second anchor point (world space).
y2	number	The y position of the second anchor point (world space).
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

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

joint

love.physics.newWheelJoint

The new WeldJoint.

body1	Body	The first body to attach to the joint.
body2	Body	The second body to attach to the joint.
x1	number	The x position of the first anchor point (world space).
y1	number	The y position of the first anchor point (world space).
x2	number	The x position of the second anchor point (world space).
y2	number	The y position of the second anchor point (world space).
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.
referenceAngle (0)	number	The reference angle between body1 and body2, in radians.

Creates a wheel joint.

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

joint

WheelJoint

The new WheelJoint.

body1	Body	The first body.
body2	Body	The second body.
x	number	The x position of the anchor point.
y	number	The y position of the anchor point.
ax	number	The x position of the axis unit vector.
ay	number	The y position of the axis unit vector.
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

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

joint

WheelJoint

The new WheelJoint.

body1	Body	The first body.
body2	Body	The second body.
x1	number	The x position of the first anchor point.
y1	number	The y position of the first anchor point.
x2	number	The x position of the second anchor point.
y2	number	The y position of the second anchor point.
ax	number	The x position of the axis unit vector.
ay	number	The y position of the axis unit vector.
collideConnected (false)	boolean	Specifies whether the two bodies should collide with each other.

love.physics.newWorld

Creates a new World.

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

world

World

A brave new World.

xg (0)	number	The x component of gravity.
yg (0)	number	The y component of gravity.
sleep (true)	boolean	Whether the bodies in this world are allowed to sleep.

love.physics.setMeter

Sets the pixels to meter scale factor.

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

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

love.physics.setMeter( scale )

scale

number

The scale factor as an integer.

Bodies are objects with velocity and position.

Constructors

love.physics.newBody

Functions

Body:applyAngularImpulse

Body:applyForce

Body:applyLinearImpulse

Body:applyTorque

Body:destroy

Body:get/setAngle

Body:get/setAngularDamping

Body:get/setAngularVelocity

Body:getContacts

Body:getFixtures

Body:get/setGravityScale

Body:get/setInertia

Body:getJoints

Body:get/setLinearDamping

Body:get/setLinearVelocity

Body:getLinearVelocityFromLocalPoint

Body:getLinearVelocityFromWorldPoint

Body:getLocalCenter

Body:getLocalPoint

Body:getLocalPoints

Body:getLocalVector

Body:get/setMass

Body:get/setMassData

Body:get/setPosition

Body:get/setTransform

Body:get/setType

Body:get/setUserData

Body:getWorld

Body:getWorldCenter

Body:getWorldPoint

Body:getWorldPoints

Body:getWorldVector

Body:get/setX

Body:get/setY

Body:is/setActive

Body:is/setAwake

Body:is/setBullet

Body:isDestroyed

Body:is/setFixedRotation

Body:is/setSleepingAllowed

Body:isTouching

Body:resetMassData

Supertypes

Body:getLinearVelocityFromLocalPoint

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 )

impulse

number

The impulse in kilogram-square meter per second.

Body:applyForce

Apply force to a Body.

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

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

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

Body:applyForce( fx, fy )

fx	number	The x component of force to apply to the center of mass.
fy	number	The y component of force to apply to the center of mass.

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

fx	number	The x component of force to apply.
fy	number	The y component of force to apply.
x	number	The x position to apply the force.
y	number	The 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 )

ix	number	The x component of the impulse applied to the center of mass.
iy	number	The y component of the impulse applied to the center of mass.

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

ix	number	The x component of the impulse.
iy	number	The y component of the impulse.
x	number	The x position to apply the impulse.
y	number	The 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 )

torque

number

The torque to apply.

Body:destroy

Explicitly destroys the Body and all fixtures and joints attached to it.

An error will occur if you attempt to use the object after calling this function. In 0.7.2, when you don't have time to wait for garbage collection, this function may be used to free the object immediately.

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

angle

number

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

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

damping

number

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

number

The angular velocity in radians/second.

Body:getContacts

Gets a list of all Contacts attached to the Body.

contacts = Body:getContacts()

contacts

table

A list with all contacts associated with the Body.

Body:getFixtures

Returns a table with all fixtures.

fixtures = Body:getFixtures()

fixtures

table

A sequence with all fixtures.

Body:getGravityScale

Returns the gravity scale factor.

scale = Body:getGravityScale()

scale

number

The gravity scale factor.

Body:getInertia

Gets the rotational inertia of the body.

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

inertia = Body:getInertia()

inertia

number

The rotational inertial of the body.

Body:getJoints

Returns a table containing the Joints attached to this Body.

joints = Body:getJoints()

joints

table

A sequence with the Joints attached to the Body.

Body:getLinearDamping

Gets the linear damping of the Body.

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

Damping is not the same as friction - they can be modelled together.

damping = Body:getLinearDamping()

damping

number

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

See page 136 of 'Essential Mathematics for Games and Interactive Applications' for definitions of local and world coordinates.

x, y = Body:getLinearVelocity()

x	number	The x-component of the velocity vector
y	number	The y-component of the velocity vector

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 )

vx	number	The x component of velocity at point (x,y).
vy	number	The y component of velocity at point (x,y).

x	number	The x position to measure velocity.
y	number	The 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 )

vx	number	The x component of velocity at point (x,y).
vy	number	The y component of velocity at point (x,y).

x	number	The x position to measure velocity.
y	number	The 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()

x	number	The x coordinate of the center of mass.
y	number	The y coordinate of the center of mass.

Body:getLocalPoint

Transform a point from world coordinates to local coordinates.

localX, localY = Body:getLocalPoint( worldX, worldY )

localX	number	The x position in local coordinates.
localY	number	The y position in local coordinates.

worldX	number	The x position in world coordinates.
worldY	number	The y position in world coordinates.

Body:getLocalPoints

Transforms multiple points from world coordinates to local coordinates.

x1, y1, x2, y2, ... = Body:getLocalPoints( x1, y1, x2, y2, ... )

x1	number	(Result) The transformed x position of the first point.
y1	number	(Result) The transformed y position of the first point.
x2	number	(Result) The transformed x position of the second point.
y2	number	(Result) The transformed y position of the second point.
...	number	(Result) Additional transformed x and y position of the points.

x1	number	(Argument) The x position of the first point.
y1	number	(Argument) The y position of the first point.
x2	number	(Argument) The x position of the second point.
y2	number	(Argument) The y position of the second point.
...	number	(Argument) You can continue passing x and y position of the points.

Body:getLocalVector

Transform a vector from world coordinates to local coordinates.

localX, localY = Body:getLocalVector( worldX, worldY )

localX	number	The vector x component in local coordinates.
localY	number	The vector y component in local coordinates.

worldX	number	The vector x component in world coordinates.
worldY	number	The vector y component in world coordinates.

Body:getMass

Get the mass of the body.

Static bodies always have a mass of 0.

mass = Body:getMass()

mass

number

The mass of the body (in kilograms).

Body:getMassData

Returns the mass, its center, and the rotational inertia.

x, y, mass, inertia = Body:getMassData()

x	number	The x position of the center of mass.
y	number	The y position of the center of mass.
mass	number	The mass of the body.
inertia	number	The 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()

x	number	The x position.
y	number	The y position.

Body:getTransform

Get the position and angle of the body.

Note that the position may not be the center of mass of the body. An angle 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.

x, y, angle = Body:getTransform()

x	number	The x component of the position.
y	number	The y component of the position.
angle	number	The angle in radians.

Body:getType

Returns the type of the body.

type = Body:getType()

type

The body type.

Body:getUserData

Returns the Lua value associated with this Body.

value = Body:getUserData()

value

any

The Lua value associated with the Body.

Body:getWorld

Gets the World the body lives in.

world = Body:getWorld()

world

World

The world the body lives in.

Body:getWorldCenter

Get the center of mass position in world coordinates.

Use Body:getLocalCenter to get the center of mass in local coordinates.

x, y = Body:getWorldCenter()

x	number	The x coordinate of the center of mass.
y	number	The y coordinate of the center of mass.

Body:getWorldPoint

Transform a point from local coordinates to world coordinates.

worldX, worldY = Body:getWorldPoint( localX, localY )

worldX	number	The x position in world coordinates.
worldY	number	The y position in world coordinates.

localX	number	The x position in local coordinates.
localY	number	The 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 )

x1	number	The transformed x position of the first point.
y1	number	The transformed y position of the first point.
x2	number	The transformed x position of the second point.
y2	number	The transformed y position of the second point.

x1	number	The x position of the first point.
y1	number	The y position of the first point.
x2	number	The x position of the second point.
y2	number	The y position of the second point.

Body:getWorldVector

Transform a vector from local coordinates to world coordinates.

worldX, worldY = Body:getWorldVector( localX, localY )

worldX	number	The vector x component in world coordinates.
worldY	number	The vector y component in world coordinates.

localX	number	The vector x component in local coordinates.
localY	number	The vector y component in local coordinates.

Body:getX

Get the x position of the body in world coordinates.

x = Body:getX()

number

The x position in world coordinates.

Body:getY

Get the y position of the body in world coordinates.

y = Body:getY()

number

The y position in world coordinates.

Body:isActive

Returns whether the body is actively used in the simulation.

status = Body:isActive()

status

boolean

True if the body is active or false if not.

Body:isAwake

Returns the sleep status of the body.

status = Body:isAwake()

status

boolean

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

status

boolean

The bullet status of the body.

Body:isDestroyed

Gets whether the Body is destroyed. Destroyed bodies cannot be used.

destroyed = Body:isDestroyed()

destroyed

boolean

Whether the Body is destroyed.

Body:isFixedRotation

Returns whether the body rotation is locked.

fixed = Body:isFixedRotation()

fixed

boolean

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

Body:isSleepingAllowed

Returns the sleeping behaviour of the body.

allowed = Body:isSleepingAllowed()

allowed

boolean

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

Body:isTouching

Gets whether the Body is touching the given other Body.

touching = Body:isTouching( otherbody )

touching

boolean

True if this body is touching the other body, false otherwise.

otherbody

The other body to check.

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 )

active

boolean

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

angle

number

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

damping

number

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

number

The new angular velocity, in radians per second

Body:setAwake

Wakes the body up or puts it to sleep.

Body:setAwake( awake )

awake

boolean

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

status

boolean

The 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. Calling this function causes the mass to be reset.

Body:setFixedRotation( isFixed )

isFixed

boolean

Whether the body should have fixed rotation.

Body:setGravityScale

Sets a new gravity scale factor for the body.

Body:setGravityScale( scale )

scale

number

The new gravity scale factor.

Body:setInertia

Set the inertia of a body.

Body:setInertia( inertia )

inertia

number

The new moment of inertia, in kilograms * pixel 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'(if gravity is enabled).

Body:setLinearDamping( ld )

number

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

x	number	The x-component of the velocity vector.
y	number	The y-component of the velocity vector.

Body:setMass

Sets a new body mass.

Body:setMass( mass )

mass

number

The mass, in kilograms.

Body:setMassData

Overrides the calculated mass data.

Body:setMassData( x, y, mass, inertia )

x	number	The x position of the center of mass.
y	number	The y position of the center of mass.
mass	number	The mass of the body.
inertia	number	The rotational inertia.

Body:setPosition

Set the position of the body.

Note that this may not be the center of mass of the body.

This function cannot wake up the body.

Body:setPosition( x, y )

x	number	The x position.
y	number	The y position.

Body:setSleepingAllowed

Sets the sleeping behaviour of the body. Should sleeping be allowed, a body at rest will automatically sleep. A sleeping body is not simulated unless it collided with an awake body. Be wary that one can end up with a situation like a floating sleeping body if the floor was removed.

Body:setSleepingAllowed( allowed )

allowed

boolean

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

Body:setTransform

Set the position and angle of the body.

Note that the position may not be the center of mass of the body. An angle 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.

This function cannot wake up the body.

Body:setTransform( x, y, angle )

x	number	The x component of the position.
y	number	The y component of the position.
angle	number	The angle in radians.

Body:setType

Sets a new body type.

Body:setType( type )

type

The new type.

Body:setUserData

Associates a Lua value with the Body.

To delete the reference, explicitly pass nil.

Body:setUserData( value )

value

any

The Lua value to associate with the Body.

Body:setX

Set the x position of the body.

This function cannot wake up the body.

Body:setX( x )

number

The x position.

Body:setY

Set the y position of the body.

This function cannot wake up the body.

Body:setY( y )

number

The y position.

ChainShape

A ChainShape consists of multiple line segments. It can be used to create the boundaries of your terrain. The shape does not have volume and can only collide with PolygonShape and CircleShape.

Unlike the PolygonShape, the ChainShape does not have a vertices limit or has to form a convex shape, but self intersections are not supported.

Constructors

love.physics.newChainShape

Functions

ChainShape:getChildEdge

ChainShape:get/setNextVertex

ChainShape:getPoint

ChainShape:getPoints

ChainShape:get/setPreviousVertex

ChainShape:getVertexCount

Supertypes

ChainShape:getPreviousVertex

ChainShape:getChildEdge

Returns a child of the shape as an EdgeShape.

shape = ChainShape:getChildEdge( index )

shape

EdgeShape

The child as an EdgeShape.

index

number

The index of the child.

ChainShape:getNextVertex

Gets the vertex that establishes a connection to the next shape.

Setting next and previous ChainShape vertices can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

x, y = ChainShape:getNextVertex()

x	number	The x-component of the vertex, or nil if ChainShape:setNextVertex hasn't been called.
y	number	The y-component of the vertex, or nil if ChainShape:setNextVertex hasn't been called.

ChainShape:getPoint

Returns a point of the shape.

x, y = ChainShape:getPoint( index )

x	number	The x-coordinate of the point.
y	number	The y-coordinate of the point.

index

number

The index of the point to return.

ChainShape:getPoints

Returns all points of the shape.

x1, y1, x2, y2 = ChainShape:getPoints()

x1	number	The x-coordinate of the first point.
y1	number	The y-coordinate of the first point.
x2	number	The x-coordinate of the second point.
y2	number	The y-coordinate of the second point.

Gets the vertex that establishes a connection to the previous shape.

Setting next and previous ChainShape vertices can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

x, y = ChainShape:getPreviousVertex()

x	number	The x-component of the vertex, or nil if ChainShape:setPreviousVertex hasn't been called.
y	number	The y-component of the vertex, or nil if ChainShape:setPreviousVertex hasn't been called.

ChainShape:getVertexCount

Returns the number of vertices the shape has.

count = ChainShape:getVertexCount()

count

number

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

x	number	The x-component of the vertex.
y	number	The 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 )

x	number	The x-component of the vertex.
y	number	The y-component of the vertex.

CircleShape

Circle extends Shape and adds a radius and a local position.

Constructors

love.physics.newCircleShape

Functions

CircleShape:get/setPoint

CircleShape:get/setRadius

Supertypes

CircleShape:getPoint

Gets the center point of the circle shape.

x, y = CircleShape:getPoint()

x	number	The x-component of the center point of the circle.
y	number	The y-component of the center point of the circle.

CircleShape:getRadius

Gets the radius of the circle shape.

radius = CircleShape:getRadius()

radius

number

The radius of the circle

CircleShape:setPoint

Sets the location of the center of the circle shape.

CircleShape:setPoint( x, y )

x	number	The x-component of the new center point of the circle.
y	number	The y-component of the new center point of the circle.

CircleShape:setRadius

Sets the radius of the circle.

CircleShape:setRadius( radius )

radius

number

The radius of the circle

Contact

Contacts are objects created to manage collisions in worlds.

Functions

Contact:getChildren

Contact:getFixtures

Contact:get/setFriction

Contact:getNormal

Contact:getPositions

Contact:get/setRestitution

Contact:is/setEnabled

Contact:isTouching

Contact:resetFriction

Contact:resetRestitution

Supertypes

Contact:getChildren

Gets the child indices of the shapes of the two colliding fixtures. For ChainShapes, an index of 1 is the first edge in the chain. Used together with Fixture:rayCast or ChainShape:getChildEdge.

indexA, indexB = Contact:getChildren()

indexA	number	The child index of the first fixture's shape.
indexB	number	The child index of the second fixture's shape.

Contact:getFixtures

Gets the two Fixtures that hold the shapes that are in contact.

fixtureA, fixtureB = Contact:getFixtures()

fixtureA	Fixture	The first Fixture.
fixtureB	Fixture	The second Fixture.

Contact:getFriction

Get the friction between two shapes that are in contact.

friction = Contact:getFriction()

friction

number

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

nx	number	The x component of the normal vector.
ny	number	The 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()

x1	number	The x coordinate of the first contact point.
y1	number	The y coordinate of the first contact point.
x2	number	The x coordinate of the second contact point.
y2	number	The y coordinate of the second contact point.

Contact:getRestitution

Get the restitution between two shapes that are in contact.

restitution = Contact:getRestitution()

restitution

number

The 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 preSolve callback.

enabled = Contact:isEnabled()

enabled

boolean

True if enabled, false otherwise.

Contact:isTouching

Returns whether the two colliding fixtures are touching each other.

touching = Contact:isTouching()

touching

boolean

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

enabled

boolean

True to enable or false to disable.

Contact:setFriction

Sets the contact friction.

Contact:setFriction( friction )

friction

number

The contact friction.

Contact:setRestitution

Sets the contact restitution.

Contact:setRestitution( restitution )

restitution

number

The contact restitution.

DistanceJoint

Keeps two bodies at the same distance.

Constructors

love.physics.newDistanceJoint

Functions

DistanceJoint:get/setDampingRatio

DistanceJoint:get/setFrequency

DistanceJoint:get/setLength

Supertypes

DistanceJoint:getDampingRatio

Gets the damping ratio.

ratio = DistanceJoint:getDampingRatio()

ratio

number

The damping ratio.

DistanceJoint:getFrequency

Gets the response speed.

Hz = DistanceJoint:getFrequency()

number

The response speed.

DistanceJoint:getLength

Gets the equilibrium distance between the two Bodies.

l = DistanceJoint:getLength()

number

The length between the two Bodies.

DistanceJoint:setDampingRatio

Sets the damping ratio.

DistanceJoint:setDampingRatio( ratio )

ratio

number

The damping ratio.

DistanceJoint:setFrequency

Sets the response speed.

DistanceJoint:setFrequency( Hz )

number

The response speed.

DistanceJoint:setLength

Sets the equilibrium distance between the two Bodies.

DistanceJoint:setLength( l )

number

The length between the two Bodies.

EdgeShape

A EdgeShape is a line segment. They can be used to create the boundaries of your terrain. The shape does not have volume and can only collide with PolygonShape and CircleShape.

Constructors

love.physics.newEdgeShape

Functions

EdgeShape:get/setNextVertex

EdgeShape:getPoints

EdgeShape:get/setPreviousVertex

Supertypes

EdgeShape:getPreviousVertex

EdgeShape:getNextVertex

Gets the vertex that establishes a connection to the next shape.

Setting next and previous EdgeShape vertices can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

x, y = EdgeShape:getNextVertex()

x	number	The x-component of the vertex, or nil if EdgeShape:setNextVertex hasn't been called.
y	number	The y-component of the vertex, or nil if EdgeShape:setNextVertex hasn't been called.

EdgeShape:getPoints

Returns the local coordinates of the edge points.

x1, y1, x2, y2 = EdgeShape:getPoints()

x1	number	The x-component of the first vertex.
y1	number	The y-component of the first vertex.
x2	number	The x-component of the second vertex.
y2	number	The y-component of the second vertex.

Gets the vertex that establishes a connection to the previous shape.

Setting next and previous EdgeShape vertices can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

x, y = EdgeShape:getPreviousVertex()

x	number	The x-component of the vertex, or nil if EdgeShape:setPreviousVertex hasn't been called.
y	number	The y-component of the vertex, or nil if EdgeShape:setPreviousVertex hasn't been called.

EdgeShape:setNextVertex

Sets a vertex that establishes a connection to the next shape.

This can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

EdgeShape:setNextVertex( x, y )

x	number	The x-component of the vertex.
y	number	The y-component of the vertex.

EdgeShape:setPreviousVertex

Sets a vertex that establishes a connection to the previous shape.

This can help prevent unwanted collisions when a flat shape slides along the edge and moves over to the new shape.

EdgeShape:setPreviousVertex( x, y )

x	number	The x-component of the vertex.
y	number	The y-component of the vertex.

Fixture

Fixtures attach shapes to bodies.

Constructors

love.physics.newFixture

Functions

Fixture:destroy

Fixture:getBody

Fixture:getBoundingBox

Fixture:get/setCategory

Fixture:get/setDensity

Fixture:get/setFilterData

Fixture:get/setFriction

Fixture:get/setGroupIndex

Fixture:get/setMask

Fixture:getMassData

Fixture:get/setRestitution

Fixture:getShape

Fixture:get/setUserData

Fixture:isDestroyed

Fixture:is/setSensor

Fixture:rayCast

Fixture:testPoint

Supertypes

Fixture:destroy

Destroys the fixture.

Fixture:destroy()

Fixture:getBody

Returns the body to which the fixture is attached.

body = Fixture:getBody()

body

The parent body.

Fixture:getBoundingBox

Returns the points of the fixture bounding box. In case the fixture has multiple children a 1-based index can be specified. For example, a fixture will have multiple children with a chain shape.

topLeftX, topLeftY, bottomRightX, bottomRightY = Fixture:getBoundingBox( index )

topLeftX	number	The x position of the top-left point.
topLeftY	number	The y position of the top-left point.
bottomRightX	number	The x position of the bottom-right point.
bottomRightY	number	The y position of the bottom-right point.

index (1)

number

A bounding box of the fixture.

Fixture:getCategory

Returns the categories the fixture belongs to.

... = Fixture:getCategory()

...

number

The categories.

Fixture:getDensity

Returns the density of the fixture.

density = Fixture:getDensity()

density

number

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

categories	number	The categories as an integer from 0 to 65535.
mask	number	The mask as an integer from 0 to 65535.
group	number	The group as an integer from -32768 to 32767.

Fixture:getFriction

Returns the friction of the fixture.

friction = Fixture:getFriction()

friction

number

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

group

number

The group of the fixture.

Fixture:getMask

Returns which categories this fixture should '''NOT''' collide with.

mask1, mask2 = Fixture:getMask()

mask1	number	The first category selected by the mask.
mask2	number	The second category selected by the mask.

Fixture:getMassData

Returns the mass, its center and the rotational inertia.

x, y, mass, inertia = Fixture:getMassData()

x	number	The x position of the center of mass.
y	number	The y position of the center of mass.
mass	number	The mass of the fixture.
inertia	number	The rotational inertia.

Fixture:getRestitution

Returns the restitution of the fixture.

restitution = Fixture:getRestitution()

restitution

number

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

shape = Fixture:getShape()

shape

The fixture's shape.

Fixture:getUserData

Returns the Lua value associated with this fixture.

value = Fixture:getUserData()

value

any

The Lua value associated with the fixture.

Fixture:isDestroyed

Gets whether the Fixture is destroyed. Destroyed fixtures cannot be used.

destroyed = Fixture:isDestroyed()

destroyed

boolean

Whether the Fixture is destroyed.

Fixture:isSensor

Returns whether the fixture is a sensor.

sensor = Fixture:isSensor()

sensor

boolean

If 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 fifth 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 = Fixture:rayCast( x1, y1, x2, y2, maxFraction, childIndex )

xn	number	The x component of the normal vector of the edge where the ray hit the shape.
yn	number	The y component of the normal vector of the edge where the ray hit the shape.
fraction	number	The position on the input line where the intersection happened as a factor of the line length.

x1	number	The x position of the input line starting point.
y1	number	The y position of the input line starting point.
x2	number	The x position of the input line end point.
y2	number	The y position of the input line end point.
maxFraction	number	Ray length parameter.
childIndex (1)	number	The 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.

All fixture's default category is 1.

Fixture:setCategory( ... )

...

number

The categories.

Fixture:setDensity

Sets the density of the fixture. Call Body:resetMassData if this needs to take effect immediately.

Fixture:setDensity( density )

density

number

The fixture density in kilograms per square meter.

Fixture:setFilterData

Sets the filter data of the fixture.

Groups, categories, and mask can be used to define the collision behaviour of the fixture.

If two fixtures are in the same group they either always collide if the group is positive, or never collide if it's negative. If the group is zero or they do not match, then the contact filter checks if the fixtures select a category of the other fixture with their masks. The fixtures do not collide if that's not the case. If they do have each other's categories selected, the return value of the custom contact filter will be used. They always collide if none was set.

There can be up to 16 categories. Categories and masks are encoded as the bits of a 16-bit integer.

When created, prior to calling this function, all fixtures have category set to 1, mask set to 65535 (all categories) and group set to 0.

This function allows setting all filter data for a fixture at once. To set only the categories, the mask or the group, you can use Fixture:setCategory, Fixture:setMask or Fixture:setGroupIndex respectively.

Fixture:setFilterData( categories, mask, group )

categories	number	The categories as an integer from 0 to 65535.
mask	number	The mask as an integer from 0 to 65535.
group	number	The group as an integer from -32768 to 32767.

Fixture:setFriction

Sets the friction of the fixture.

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.

Fixture:setFriction( friction )

friction

number

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

group

number

The 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 '''NOT''' 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 )

mask1	number	The first category.
mask2	number	The second category.

Fixture:setRestitution

Sets the restitution of the fixture.

Fixture:setRestitution( restitution )

restitution

number

The fixture restitution.

Fixture:setSensor

Sets whether the fixture should act as a sensor.

Sensors do not cause collision responses, but the begin-contact and end-contact World callbacks will still be called for this fixture.

Fixture:setSensor( sensor )

sensor

boolean

The sensor status.

Fixture:setUserData

Associates a Lua value with the fixture.

To delete the reference, explicitly pass nil.

Fixture:setUserData( value )

value

any

The Lua value to associate with the fixture.

Fixture:testPoint

Checks if a point is inside the shape of the fixture.

isInside = Fixture:testPoint( x, y )

isInside

boolean

True if the point is inside or false if it is outside.

x	number	The x position of the point.
y	number	The y position of the point.

FrictionJoint

A FrictionJoint applies friction to a body.

Constructors

love.physics.newFrictionJoint

Functions

FrictionJoint:get/setMaxForce

FrictionJoint:get/setMaxTorque

Supertypes

FrictionJoint:getMaxForce

Gets the maximum friction force in Newtons.

force = FrictionJoint:getMaxForce()

force

number

Maximum force in Newtons.

FrictionJoint:getMaxTorque

Gets the maximum friction torque in Newton-meters.

torque = FrictionJoint:getMaxTorque()

torque

number

Maximum torque in Newton-meters.

FrictionJoint:setMaxForce

Sets the maximum friction force in Newtons.

FrictionJoint:setMaxForce( maxForce )

maxForce

number

Max force in Newtons.

FrictionJoint:setMaxTorque

Sets the maximum friction torque in Newton-meters.

FrictionJoint:setMaxTorque( torque )

torque

number

Maximum torque in Newton-meters.

GearJoint

Keeps bodies together in such a way that they act like gears.

Constructors

love.physics.newGearJoint

Functions

GearJoint:getJoints

GearJoint:get/setRatio

Supertypes

GearJoint:getJoints

Get the Joints connected by this GearJoint.

joint1, joint2 = GearJoint:getJoints()

joint1	Joint	The first connected Joint.
joint2	Joint	The second connected Joint.

GearJoint:getRatio

Get the ratio of a gear joint.

ratio = GearJoint:getRatio()

ratio

number

The ratio of the joint.

GearJoint:setRatio

Set the ratio of a gear joint.

GearJoint:setRatio( ratio )

ratio

number

The new ratio of the joint.

Attach multiple bodies together to interact in unique ways.

Functions

Joint:destroy

Joint:getAnchors

Joint:getBodies

Joint:getCollideConnected

Joint:getReactionForce

Joint:getReactionTorque

Joint:getType

Joint:get/setUserData

Joint:isDestroyed

Supertypes

Joint:getCollideConnected

Joint:destroy

Explicitly destroys the Joint. An error will occur if you attempt to use the object after calling this function.

In 0.7.2, when you don't have time to wait for garbage collection, this function

may be used to free the object immediately.

Joint:destroy()

Joint:getAnchors

Get the anchor points of the joint.

x1, y1, x2, y2 = Joint:getAnchors()

x1	number	The x-component of the anchor on Body 1.
y1	number	The y-component of the anchor on Body 1.
x2	number	The x-component of the anchor on Body 2.
y2	number	The y-component of the anchor on Body 2.

Joint:getBodies

Gets the bodies that the Joint is attached to.

bodyA, bodyB = Joint:getBodies()

bodyA	Body	The first Body.
bodyB	Body	The second Body.

Gets whether the connected Bodies collide.

c = Joint:getCollideConnected()

boolean

True if they collide, false otherwise.

Joint:getReactionForce

Returns the reaction force in newtons on the second body

x, y = Joint:getReactionForce( x )

x	number	The x-component of the force.
y	number	The y-component of the force.

number

How long the force applies. Usually the inverse time step or 1/dt.

Joint:getReactionTorque

Returns the reaction torque on the second body.

torque = Joint:getReactionTorque( invdt )

torque

number

The reaction torque on the second body.

invdt

number

How long the force applies. Usually the inverse time step or 1/dt.

Joint:getType

Gets a string representing the type.

type = Joint:getType()

type

JointType

A string with the name of the Joint type.

Joint:getUserData

Returns the Lua value associated with this Joint.

value = Joint:getUserData()

value

any

The Lua value associated with the Joint.

Joint:isDestroyed

Gets whether the Joint is destroyed. Destroyed joints cannot be used.

destroyed = Joint:isDestroyed()

destroyed

boolean

Whether the Joint is destroyed.

Joint:setUserData

Associates a Lua value with the Joint.

To delete the reference, explicitly pass nil.

Joint:setUserData( value )

value

any

The Lua value to associate with the Joint.

MotorJoint

Controls the relative motion between two Bodies. Position and rotation offsets can be specified, as well as the maximum motor force and torque that will be applied to reach the target offsets.

Constructors

love.physics.newMotorJoint

Functions

MotorJoint:get/setAngularOffset

MotorJoint:get/setLinearOffset

Supertypes

MotorJoint:getAngularOffset

Gets the target angular offset between the two Bodies the Joint is attached to.

angleoffset = MotorJoint:getAngularOffset()

angleoffset

number

The target angular offset in radians: the second body's angle minus the first body's angle.

MotorJoint:getLinearOffset

Gets the target linear offset between the two Bodies the Joint is attached to.

x, y = MotorJoint:getLinearOffset()

x	number	The x component of the target linear offset, relative to the first Body.
y	number	The y component of the target linear offset, relative to the first Body.

MotorJoint:setAngularOffset

Sets the target angluar offset between the two Bodies the Joint is attached to.

MotorJoint:setAngularOffset( angleoffset )

angleoffset

number

The target angular offset in radians: the second body's angle minus the first body's angle.

MotorJoint:setLinearOffset

Sets the target linear offset between the two Bodies the Joint is attached to.

MotorJoint:setLinearOffset( x, y )

x	number	The x component of the target linear offset, relative to the first Body.
y	number	The y component of the target linear offset, relative to the first Body.

MouseJoint

For controlling objects with the mouse.

Constructors

love.physics.newMouseJoint

Functions

MouseJoint:get/setDampingRatio

MouseJoint:get/setFrequency

MouseJoint:get/setMaxForce

MouseJoint:get/setTarget

Supertypes

MouseJoint:getDampingRatio

Returns the damping ratio.

ratio = MouseJoint:getDampingRatio()

ratio

number

The new damping ratio.

MouseJoint:getFrequency

Returns the frequency.

freq = MouseJoint:getFrequency()

freq

number

The frequency in hertz.

MouseJoint:getMaxForce

Gets the highest allowed force.

f = MouseJoint:getMaxForce()

number

The max allowed force.

MouseJoint:getTarget

Gets the target point.

x, y = MouseJoint:getTarget()

x	number	The x-component of the target.
y	number	The x-component of the target.

MouseJoint:setDampingRatio

Sets a new damping ratio.

MouseJoint:setDampingRatio( ratio )

ratio

number

The new damping ratio.

MouseJoint:setFrequency

Sets a new frequency.

MouseJoint:setFrequency( freq )

freq

number

The new frequency in hertz.

MouseJoint:setMaxForce

Sets the highest allowed force.

MouseJoint:setMaxForce( f )

number

The max allowed force.

MouseJoint:setTarget

Sets the target point.

MouseJoint:setTarget( x, y )

x	number	The x-component of the target.
y	number	The y-component of the target.

A PolygonShape is a convex polygon with up to 8 vertices.

Constructors

love.physics.newPolygonShape

love.physics.newRectangleShape

Functions

PolygonShape:getPoints

Supertypes

PolygonShape:getPoints

Get the local coordinates of the polygon's vertices.

This function has a variable number of return values. It can be used in a nested fashion with love.graphics.polygon.

x1, y1, x2, y2 = PolygonShape:getPoints()

x1	number	The x-component of the first vertex.
y1	number	The y-component of the first vertex.
x2	number	The x-component of the second vertex.
y2	number	The y-component of the second vertex.

Restricts relative motion between Bodies to one shared axis.

Constructors

love.physics.newPrismaticJoint

Functions

PrismaticJoint:are/setLimitsEnabled

PrismaticJoint:getAxis

PrismaticJoint:getJointSpeed

PrismaticJoint:getJointTranslation

PrismaticJoint:get/setLimits

PrismaticJoint:get/setLowerLimit

PrismaticJoint:get/setMaxMotorForce

PrismaticJoint:getMotorForce

PrismaticJoint:get/setMotorSpeed

PrismaticJoint:getReferenceAngle

PrismaticJoint:get/setUpperLimit

PrismaticJoint:is/setMotorEnabled

Supertypes

PrismaticJoint:areLimitsEnabled

Checks whether the limits are enabled.

enabled = PrismaticJoint:areLimitsEnabled()

enabled

boolean

True if enabled, false otherwise.

PrismaticJoint:getAxis

Gets the world-space axis vector of the Prismatic Joint.

x, y = PrismaticJoint:getAxis()

x	number	The x-axis coordinate of the world-space axis vector.
y	number	The y-axis coordinate of the world-space axis vector.

PrismaticJoint:getJointSpeed

Get the current joint angle speed.

s = PrismaticJoint:getJointSpeed()

number

Joint angle speed in meters/second.

PrismaticJoint:getJointTranslation

Get the current joint translation.

t = PrismaticJoint:getJointTranslation()

number

Joint translation, usually in meters..

PrismaticJoint:getLimits

Gets the joint limits.

lower, upper = PrismaticJoint:getLimits()

lower	number	The lower limit, usually in meters.
upper	number	The upper limit, usually in meters.

PrismaticJoint:getLowerLimit

Gets the lower limit.

lower = PrismaticJoint:getLowerLimit()

lower

number

The lower limit, usually in meters.

PrismaticJoint:getMaxMotorForce

Gets the maximum motor force.

f = PrismaticJoint:getMaxMotorForce()

number

The maximum motor force, usually in N.

PrismaticJoint:getMotorForce

Returns the current motor force.

force = PrismaticJoint:getMotorForce( invdt )

force

number

The force on the motor in newtons.

invdt

number

How long the force applies. Usually the inverse time step or 1/dt.

PrismaticJoint:getMotorSpeed

Gets the motor speed.

s = PrismaticJoint:getMotorSpeed()

number

The motor speed, usually in meters per second.

PrismaticJoint:getReferenceAngle

Gets the reference angle.

angle = PrismaticJoint:getReferenceAngle()

angle

number

The reference angle in radians.

PrismaticJoint:getUpperLimit

Gets the upper limit.

upper = PrismaticJoint:getUpperLimit()

upper

number

The upper limit, usually in meters.

PrismaticJoint:isMotorEnabled

Checks whether the motor is enabled.

enabled = PrismaticJoint:isMotorEnabled()

enabled

boolean

True if enabled, false if disabled.

PrismaticJoint:setLimits

Sets the limits.

PrismaticJoint:setLimits( lower, upper )

lower	number	The lower limit, usually in meters.
upper	number	The upper limit, usually in meters.

PrismaticJoint:setLimitsEnabled

Enables/disables the joint limit.

enable = PrismaticJoint:setLimitsEnabled()

enable

boolean

True if enabled, false if disabled.

PrismaticJoint:setLowerLimit

Sets the lower limit.

PrismaticJoint:setLowerLimit( lower )

lower

number

The lower limit, usually in meters.

PrismaticJoint:setMaxMotorForce

Set the maximum motor force.

PrismaticJoint:setMaxMotorForce( f )

number

The maximum motor force, usually in N.

PrismaticJoint:setMotorEnabled

Enables/disables the joint motor.

PrismaticJoint:setMotorEnabled( enable )

enable

boolean

True to enable, false to disable.

PrismaticJoint:setMotorSpeed

Sets the motor speed.

PrismaticJoint:setMotorSpeed( s )

number

The motor speed, usually in meters per second.

PrismaticJoint:setUpperLimit

Sets the upper limit.

PrismaticJoint:setUpperLimit( upper )

upper

number

The upper limit, usually in meters.

PulleyJoint

Allows you to simulate bodies connected through pulleys.

Constructors

love.physics.newPulleyJoint

Functions

PulleyJoint:get/setConstant

PulleyJoint:getGroundAnchors

PulleyJoint:getLengthA

PulleyJoint:getLengthB

PulleyJoint:get/setMaxLengths

PulleyJoint:get/setRatio

Supertypes

PulleyJoint:getGroundAnchors

PulleyJoint:getConstant

Get the total length of the rope.

length = PulleyJoint:getConstant()

length

number

The length of the rope in the joint.

Get the ground anchor positions in world coordinates.

a1x, a1y, a2x, a2y = PulleyJoint:getGroundAnchors()

a1x	number	The x coordinate of the first anchor.
a1y	number	The y coordinate of the first anchor.
a2x	number	The x coordinate of the second anchor.
a2y	number	The y coordinate of the second anchor.

PulleyJoint:getLengthA

Get the current length of the rope segment attached to the first body.

length = PulleyJoint:getLengthA()

length

number

The length of the rope segment.

PulleyJoint:getLengthB

Get the current length of the rope segment attached to the second body.

length = PulleyJoint:getLengthB()

length

number

The length of the rope segment.

PulleyJoint:getMaxLengths

Get the maximum lengths of the rope segments.

len1, len2 = PulleyJoint:getMaxLengths()

len1	number	The maximum length of the first rope segment.
len2	number	The maximum length of the second rope segment.

PulleyJoint:getRatio

Get the pulley ratio.

ratio = PulleyJoint:getRatio()

ratio

number

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

length

number

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

max1	number	The new maximum length of the first segment.
max2	number	The new maximum length of the second segment.

PulleyJoint:setRatio

Set the pulley ratio.

PulleyJoint:setRatio( ratio )

ratio

number

The new pulley ratio of the joint.

RevoluteJoint

Allow two Bodies to revolve around a shared point.

Constructors

love.physics.newRevoluteJoint

Functions

RevoluteJoint:are/setLimitsEnabled

RevoluteJoint:getJointAngle

RevoluteJoint:getJointSpeed

RevoluteJoint:get/setLimits

RevoluteJoint:get/setLowerLimit

RevoluteJoint:get/setMaxMotorTorque

RevoluteJoint:get/setMotorSpeed

RevoluteJoint:getMotorTorque

RevoluteJoint:getReferenceAngle

RevoluteJoint:get/setUpperLimit

RevoluteJoint:has/setLimitsEnabled

RevoluteJoint:is/setMotorEnabled

Supertypes

RevoluteJoint:areLimitsEnabled

Checks whether limits are enabled.

enabled = RevoluteJoint:areLimitsEnabled()

enabled

boolean

True if enabled, false otherwise.

RevoluteJoint:getJointAngle

Get the current joint angle.

angle = RevoluteJoint:getJointAngle()

angle

number

The joint angle in radians.

RevoluteJoint:getJointSpeed

Get the current joint angle speed.

s = RevoluteJoint:getJointSpeed()

number

Joint angle speed in radians/second.

RevoluteJoint:getLimits

Gets the joint limits.

lower, upper = RevoluteJoint:getLimits()

lower	number	The lower limit, in radians.
upper	number	The upper limit, in radians.

RevoluteJoint:getLowerLimit

Gets the lower limit.

lower = RevoluteJoint:getLowerLimit()

lower

number

The lower limit, in radians.

RevoluteJoint:getMaxMotorTorque

Gets the maximum motor force.

f = RevoluteJoint:getMaxMotorTorque()

number

The maximum motor force, in Nm.

RevoluteJoint:getMotorSpeed

Gets the motor speed.

s = RevoluteJoint:getMotorSpeed()

number

The motor speed, radians per second.

RevoluteJoint:getMotorTorque

Get the current motor force.

f = RevoluteJoint:getMotorTorque()

number

The current motor force, in Nm.

RevoluteJoint:getReferenceAngle

Gets the reference angle.

angle = RevoluteJoint:getReferenceAngle()

angle

number

The reference angle in radians.

RevoluteJoint:getUpperLimit

Gets the upper limit.

upper = RevoluteJoint:getUpperLimit()

upper

number

The upper limit, in radians.

RevoluteJoint:hasLimitsEnabled

Checks whether limits are enabled.

enabled = RevoluteJoint:hasLimitsEnabled()

enabled

boolean

True if enabled, false otherwise.

RevoluteJoint:isMotorEnabled

Checks whether the motor is enabled.

enabled = RevoluteJoint:isMotorEnabled()

enabled

boolean

True if enabled, false if disabled.

RevoluteJoint:setLimits

Sets the limits.

RevoluteJoint:setLimits( lower, upper )

lower	number	The lower limit, in radians.
upper	number	The upper limit, in radians.

RevoluteJoint:setLimitsEnabled

Enables/disables the joint limit.

RevoluteJoint:setLimitsEnabled( enable )

enable

boolean

True to enable, false to disable.

RevoluteJoint:setLowerLimit

Sets the lower limit.

RevoluteJoint:setLowerLimit( lower )

lower

number

The lower limit, in radians.

RevoluteJoint:setMaxMotorTorque

Set the maximum motor force.

RevoluteJoint:setMaxMotorTorque( f )

number

The maximum motor force, in Nm.

RevoluteJoint:setMotorEnabled

Enables/disables the joint motor.

RevoluteJoint:setMotorEnabled( enable )

enable

boolean

True to enable, false to disable.

RevoluteJoint:setMotorSpeed

Sets the motor speed.

RevoluteJoint:setMotorSpeed( s )

number

The motor speed, radians per second.

RevoluteJoint:setUpperLimit

Sets the upper limit.

RevoluteJoint:setUpperLimit( upper )

upper

number

The upper limit, in radians.

RopeJoint

The RopeJoint enforces a maximum distance between two points on two bodies. It has no other effect.

Constructors

love.physics.newRopeJoint

Functions

RopeJoint:get/setMaxLength

Supertypes

RopeJoint:getMaxLength

Gets the maximum length of a RopeJoint.

maxLength = RopeJoint:getMaxLength()

maxLength

number

The maximum length of the RopeJoint.

RopeJoint:setMaxLength

Sets the maximum length of a RopeJoint.

RopeJoint:setMaxLength( maxLength )

maxLength

number

The new maximum length of the RopeJoint.

Shapes are solid 2d geometrical objects which handle the mass and collision of a Body in love.physics.

Shapes are attached to a Body via a Fixture. The Shape object is copied when this happens.

The Shape's position is relative to the position of the Body it has been attached to.

Functions

Shape:computeAABB

Shape:computeMass

Shape:getChildCount

Shape:getRadius

Shape:getType

Shape:rayCast

Shape:testPoint

Supertypes

Shape:computeAABB

Returns the points of the bounding box for the transformed shape.

topLeftX, topLeftY, bottomRightX, bottomRightY = Shape:computeAABB( tx, ty, tr, childIndex )

topLeftX	number	The x position of the top-left point.
topLeftY	number	The y position of the top-left point.
bottomRightX	number	The x position of the bottom-right point.
bottomRightY	number	The y position of the bottom-right point.

tx	number	The translation of the shape on the x-axis.
ty	number	The translation of the shape on the y-axis.
tr	number	The shape rotation.
childIndex (1)	number	The 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 )

x	number	The x postition of the center of mass.
y	number	The y postition of the center of mass.
mass	number	The mass of the shape.
inertia	number	The rotational inertia.

density

number

The shape density.

Shape:getChildCount

Returns the number of children the shape has.

count = Shape:getChildCount()

count

number

The number of children.

Shape:getRadius

Gets the radius of the shape.

radius = Shape:getRadius()

radius

number

The radius of the shape.

Shape:getType

Gets a string representing the Shape.

This function can be useful for conditional debug drawing.

type = Shape:getType()

type

ShapeType

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

xn	number	The x component of the normal vector of the edge where the ray hit the shape.
yn	number	The y component of the normal vector of the edge where the ray hit the shape.
fraction	number	The position on the input line where the intersection happened as a factor of the line length.

x1	number	The x position of the input line starting point.
y1	number	The y position of the input line starting point.
x2	number	The x position of the input line end point.
y2	number	The y position of the input line end point.
maxFraction	number	Ray length parameter.
tx	number	The translation of the shape on the x-axis.
ty	number	The translation of the shape on the y-axis.
tr	number	The shape rotation.
childIndex (1)	number	The index of the child the ray gets cast against.

Shape:testPoint

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( tx, ty, tr, x, y )

hit

boolean

True if inside, false if outside

tx	number	Translates the shape along the x-axis.
ty	number	Translates the shape along the y-axis.
tr	number	Rotates the shape.
x	number	The x-component of the point.
y	number	The y-component of the point.

A WeldJoint essentially glues two bodies together.

Constructors

love.physics.newWeldJoint

Functions

WeldJoint:get/setDampingRatio

WeldJoint:get/setFrequency

WeldJoint:getReferenceAngle

Supertypes

WeldJoint:getDampingRatio

Returns the damping ratio of the joint.

ratio = WeldJoint:getDampingRatio()

ratio

number

The damping ratio.

WeldJoint:getFrequency

Returns the frequency.

freq = WeldJoint:getFrequency()

freq

number

The frequency in hertz.

WeldJoint:getReferenceAngle

Gets the reference angle.

angle = WeldJoint:getReferenceAngle()

angle

number

The reference angle in radians.

WeldJoint:setDampingRatio

Sets a new damping ratio.

WeldJoint:setDampingRatio( ratio )

ratio

number

The new damping ratio.

WeldJoint:setFrequency

Sets a new frequency.

WeldJoint:setFrequency( freq )

freq

number

The new frequency in hertz.

WheelJoint

Restricts a point on the second body to a line on the first body.

Constructors

love.physics.newWheelJoint

Functions

WheelJoint:getAxis

WheelJoint:getJointSpeed

WheelJoint:getJointTranslation

WheelJoint:get/setMaxMotorTorque

WheelJoint:get/setMotorSpeed

WheelJoint:getMotorTorque

WheelJoint:get/setSpringDampingRatio

WheelJoint:get/setSpringFrequency

WheelJoint:is/setMotorEnabled

Supertypes

WheelJoint:getJointTranslation

WheelJoint:getAxis

Gets the world-space axis vector of the Wheel Joint.

x, y = WheelJoint:getAxis()

x	number	The x-axis coordinate of the world-space axis vector.
y	number	The y-axis coordinate of the world-space axis vector.

WheelJoint:getJointSpeed

Returns the current joint translation speed.

speed = WheelJoint:getJointSpeed()

speed

number

The translation speed of the joint in meters per second.

Returns the current joint translation.

position = WheelJoint:getJointTranslation()

position

number

The translation of the joint in meters.

WheelJoint:getMaxMotorTorque

Returns the maximum motor torque.

maxTorque = WheelJoint:getMaxMotorTorque()

maxTorque

number

The maximum torque of the joint motor in newton meters.

WheelJoint:getMotorSpeed

Returns the speed of the motor.

speed = WheelJoint:getMotorSpeed()

speed

number

The speed of the joint motor in radians per second.

WheelJoint:getMotorTorque

Returns the current torque on the motor.

torque = WheelJoint:getMotorTorque( invdt )

torque

number

The torque on the motor in newton meters.

invdt

number

How long the force applies. Usually the inverse time step or 1/dt.

WheelJoint:getSpringDampingRatio

Returns the damping ratio.

ratio = WheelJoint:getSpringDampingRatio()

ratio

number

The damping ratio.

WheelJoint:getSpringFrequency

Returns the spring frequency.

freq = WheelJoint:getSpringFrequency()

freq

number

The frequency in hertz.

WheelJoint:isMotorEnabled

Checks if the joint motor is running.

on = WheelJoint:isMotorEnabled()

boolean

The status of the joint motor.

WheelJoint:setMaxMotorTorque

Sets a new maximum motor torque.

WheelJoint:setMaxMotorTorque( maxTorque )

maxTorque

number

The new maximum torque for the joint motor in newton meters.

WheelJoint:setMotorEnabled

Starts and stops the joint motor.

WheelJoint:setMotorEnabled( enable )

enable

boolean

True turns the motor on and false turns it off.

WheelJoint:setMotorSpeed

Sets a new speed for the motor.

WheelJoint:setMotorSpeed( speed )

speed

number

The new speed for the joint motor in radians per second.

WheelJoint:setSpringDampingRatio

Sets a new damping ratio.

WheelJoint:setSpringDampingRatio( ratio )

ratio

number

The new damping ratio.

WheelJoint:setSpringFrequency

Sets a new spring frequency.

WheelJoint:setSpringFrequency( freq )

freq

number

The new frequency in hertz.

World

A world is an object that contains all bodies and joints.

Constructors

love.physics.newWorld

Functions

World:destroy

World:getBodies

World:getBodyCount

World:get/setCallbacks

World:getContactCount

World:get/setContactFilter

World:getContacts

World:get/setGravity

World:getJointCount

World:getJoints

World:isDestroyed

World:isLocked

World:is/setSleepingAllowed

World:queryBoundingBox

World:rayCast

World:translateOrigin

World:update

Supertypes

World:destroy

Destroys the world, taking all bodies, joints, fixtures and their shapes with it.

An error will occur if you attempt to use any of the destroyed objects after calling this function.

World:destroy()

World:getBodies

Returns a table with all bodies.

bodies = World:getBodies()

bodies

table

A sequence with all bodies.

World:getBodyCount

Returns the number of bodies in the world.

n = World:getBodyCount()

number

The number of bodies in the world.

World:getCallbacks

Returns functions for the callbacks during the world update.

beginContact, endContact, preSolve, postSolve = World:getCallbacks()

beginContact	function	Gets called when two fixtures begin to overlap.
endContact	function	Gets called when two fixtures cease to overlap.
preSolve	function	Gets called before a collision gets resolved.
postSolve	function	Gets called after the collision has been resolved.

World:getContactCount

Returns the number of contacts in the world.

n = World:getContactCount()

number

The number of contacts in the world.

World:getContactFilter

Returns the function for collision filtering.

contactFilter = World:getContactFilter()

contactFilter

function

The function that handles the contact filtering.

World:getContacts

Returns a table with all Contacts.

contacts = World:getContacts()

contacts

table

A sequence with all Contacts.

World:getGravity

Get the gravity of the world.

x, y = World:getGravity()

x	number	The x component of gravity.
y	number	The y component of gravity.

World:getJointCount

Returns the number of joints in the world.

n = World:getJointCount()

number

The number of joints in the world.

World:getJoints

Returns a table with all joints.

joints = World:getJoints()

joints

table

A sequence with all joints.

World:isDestroyed

Gets whether the World is destroyed. Destroyed worlds cannot be used.

destroyed = World:isDestroyed()

destroyed

boolean

Whether the World is destroyed.

World:isLocked

Returns if the world is updating its state.

This will return true inside the callbacks from World:setCallbacks.

locked = World:isLocked()

locked

boolean

Will be true if the world is in the process of updating its state.

World:isSleepingAllowed

Gets the sleep behaviour of the world.

allow = World:isSleepingAllowed()

allow

boolean

True if bodies in the world are allowed to sleep, or false if not.

World:queryBoundingBox

Calls a function for each fixture inside the specified area by searching for any overlapping bounding box (Fixture:getBoundingBox).

World:queryBoundingBox( topLeftX, topLeftY, bottomRightX, bottomRightY, callback )

topLeftX	number	The x position of the top-left point.
topLeftY	number	The y position of the top-left point.
bottomRightX	number	The x position of the bottom-right point.
bottomRightY	number	The y position of the bottom-right point.
callback	function	This function gets passed one argument, the fixture, and should return a boolean. The search will continue if it is true or stop if it is false.

World:rayCast

Casts a ray and calls a function for each fixtures it intersects.

World:rayCast( x1, y1, x2, y2, callback )

x1	number	The x position of the starting point of the ray.
y1	number	The x position of the starting point of the ray.
x2	number	The x position of the end point of the ray.
y2	number	The x value of the surface normal vector of the shape edge.
callback	function	A function called for each fixture intersected by the ray. The function gets six arguments and should return a number as a control value. The intersection points fed into the function will be in an arbitrary order. If you wish to find the closest point of intersection, you'll need to do that yourself within the function. The easiest way to do that is by using the fraction value.

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

If you are interested to know when exactly each callback is called, consult a Box2d manual

World:setCallbacks( beginContact, endContact, preSolve, postSolve )

beginContact	function	Gets called when two fixtures begin to overlap.
endContact	function	Gets called when two fixtures cease to overlap. This will also be called outside of a world update, when colliding objects are destroyed.
preSolve (nil)	function	Gets called before a collision gets resolved.
postSolve (nil)	function	Gets called after the collision has been resolved.

World:setContactFilter

Sets a function for collision filtering.

If the group and category filtering doesn't generate a collision decision, this function gets called with the two fixtures as arguments. The function should return a boolean value where true means the fixtures will collide and false means they will pass through each other.

World:setContactFilter( filter )

filter

function

The function handling the contact filtering.

World:setGravity

Set the gravity of the world.

World:setGravity( x, y )

x	number	The x component of gravity.
y	number	The y component of gravity.

World:setSleepingAllowed

Sets the sleep behaviour of the world.

World:setSleepingAllowed( allow )

allow

boolean

True if bodies in the world are allowed to sleep, or false if not.

World:translateOrigin

Translates the World's origin. Useful in large worlds where floating point precision issues become noticeable at far distances from the origin.

World:translateOrigin( x, y )

x	number	The x component of the new origin with respect to the old origin.
y	number	The y component of the new origin with respect to the old origin.

World:update

Update the state of the world.

World:update( dt, velocityiterations, positioniterations )

dt	number	The time (in seconds) to advance the physics simulation.
velocityiterations (8)	number	The maximum number of steps used to determine the new velocities when resolving a collision.
positioniterations (3)	number	The maximum number of steps used to determine the new positions when resolving a collision.

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.

friction

A FrictionJoint.

gear

A GearJoint.

mouse

A MouseJoint.

prismatic

A PrismaticJoint.

pulley

A PulleyJoint.

revolute

A RevoluteJoint.

rope

A RopeJoint.

weld

A WeldJoint.

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

Types

Enums

love.sound.newDecoder

Attempts to find a decoder for the encoded sound data in the specified file.

decoder = love.sound.newDecoder( file, buffer )

decoder

A new Decoder object.

file	File	The file with encoded sound data.
buffer (2048)	number	The size of each decoded chunk, in bytes.

decoder = love.sound.newDecoder( filename, buffer )

decoder

A new Decoder object.

filename	string	The filename of the file with encoded sound data.
buffer (2048)	number	The size of each decoded chunk, in bytes.

love.sound.newSoundData

Creates new SoundData from a filepath, File, or Decoder. 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 )

soundData

A new SoundData object.

filename

string

The file name of the file to load.

soundData = love.sound.newSoundData( file )

soundData

A new SoundData object.

file

File

A File pointing to an audio file.

soundData = love.sound.newSoundData( decoder )

soundData

A new SoundData object.

decoder

Decode data from this Decoder until EOF.

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

soundData

A new SoundData object.

samples	number	Total number of samples.
rate (44100)	number	Number of samples per second
bits (16)	number	Bits per sample (8 or 16).
channels (2)	number	Either 1 for mono or 2 for stereo.

An object which can gradually decode a sound file.

Constructors

love.sound.newDecoder

Functions

Decoder:clone

Decoder:decode

Decoder:getBitDepth

Decoder:getChannelCount

Decoder:getDuration

Decoder:getSampleRate

Decoder:seek

Supertypes

Decoder:clone

Creates a new copy of current decoder.

The new decoder will start decoding from the beginning of the audio stream.

decoder = Decoder:clone()

decoder

New copy of the decoder.

Decoder:decode

Decodes the audio and returns a SoundData object containing the decoded audio data.

soundData = Decoder:decode()

soundData

Decoded audio data.

Decoder:getBitDepth

Returns the number of bits per sample.

bitDepth = Decoder:getBitDepth()

bitDepth

number

Either 8, or 16.

Decoder:getChannelCount

Returns the number of channels in the stream.

channels = Decoder:getChannelCount()

channels

number

1 for mono, 2 for stereo.

Decoder:getDuration

Gets the duration of the sound file. It may not always be sample-accurate, and it may return -1 if the duration cannot be determined at all.

duration = Decoder:getDuration()

duration

number

The duration of the sound file in seconds, or -1 if it cannot be determined.

Decoder:getSampleRate

Returns the sample rate of the Decoder.

rate = Decoder:getSampleRate()

rate

number

Number of samples per second.

Decoder:seek

Sets the currently playing position of the Decoder.

Decoder:seek( offset )

offset

number

The position to seek to, in seconds.

Contains raw audio samples.

You can not play SoundData back directly. You must wrap a Source object around it.

Constructors

love.sound.newSoundData

Functions

SoundData:getBitDepth

SoundData:getChannelCount

SoundData:getDuration

SoundData:get/setSample

SoundData:getSampleCount

SoundData:getSampleRate

Supertypes

SoundData:getChannelCount

SoundData:getBitDepth

Returns the number of bits per sample.

bitdepth = SoundData:getBitDepth()

bitdepth

number

Either 8, or 16.

Returns the number of channels in the SoundData.

channels = SoundData:getChannelCount()

channels

number

1 for mono, 2 for stereo.

SoundData:getDuration

Gets the duration of the sound data.

duration = SoundData:getDuration()

duration

number

The duration of the sound data in seconds.

SoundData:getSample

Gets the value of the sample-point at the specified position. For stereo SoundData objects, the data from the left and right channels are interleaved in that order.

sample = SoundData:getSample( i )

sample

number

The normalized samplepoint (range -1.0 to 1.0).

number

An integer value specifying the position of the sample (starting at 0).

sample = SoundData:getSample( i, channel )

sample

number

The normalized samplepoint (range -1.0 to 1.0).

i	number	An integer value specifying the position of the sample (starting at 0).
channel	number	The index of the channel to get within the given sample.

SoundData:getSampleCount

Returns the number of samples per channel of the SoundData.

count = SoundData:getSampleCount()

count

number

Total number of samples.

SoundData:getSampleRate

Returns the sample rate of the SoundData.

rate = SoundData:getSampleRate()

rate

number

Number of samples per second.

SoundData:setSample

Sets the value of the sample-point at the specified position. For stereo SoundData objects, the data from the left and right channels are interleaved in that order.

SoundData:setSample( i, sample )

i	number	An integer value specifying the position of the sample (starting at 0).
sample	number	The normalized samplepoint (range -1.0 to 1.0).

SoundData:setSample( i, channel, sample )

i	number	An integer value specifying the position of the sample (starting at 0).
channel	number	The index of the channel to set within the given sample.
sample	number	The normalized samplepoint (range -1.0 to 1.0).

love.system

Functions

love.system.get/setClipboardText

love.system.getOS

love.system.getPowerInfo

love.system.getProcessorCount

love.system.hasBackgroundMusic

love.system.openURL

love.system.vibrate

Enums

PowerState

love.system.getClipboardText

Gets text from the clipboard.

text = love.system.getClipboardText()

text

string

The text currently held in the system's clipboard.

love.system.getOS

Gets the current operating system. In general, LÖVE abstracts away the need to know the current operating system, but there are a few cases where it can be useful (especially in combination with os.execute.)

osString = love.system.getOS()

osString

string

The current operating system. 'OS X', 'Windows', 'Linux', 'Android' or 'iOS'.

love.system.getPowerInfo

Gets information about the system's power supply.

state, percent, seconds = love.system.getPowerInfo()

state	PowerState	The basic state of the power supply.
percent	number	Percentage of battery life left, between 0 and 100. nil if the value can't be determined or there's no battery.
seconds	number	Seconds of battery life left. nil if the value can't be determined or there's no battery.

love.system.getProcessorCount

Gets the amount of logical processor in the system.

processorCount = love.system.getProcessorCount()

processorCount

number

Amount of logical processors.

love.system.hasBackgroundMusic

Gets whether another application on the system is playing music in the background.

Currently this is implemented on iOS and Android, and will always return false on other operating systems. The t.audio.mixwithsystem flag in love.conf can be used to configure whether background audio / music from other apps should play while LÖVE is open.

backgroundmusic = love.system.hasBackgroundMusic()

backgroundmusic

boolean

True if the user is playing music in the background via another app, false otherwise.

love.system.openURL

Opens a URL with the user's web or file browser.

success = love.system.openURL( url )

success

boolean

Whether the URL was opened successfully.

url

string

The URL to open. Must be formatted as a proper URL.

love.system.setClipboardText

Puts text in the clipboard.

love.system.setClipboardText( text )

text

string

The new text to hold in the system's clipboard.

love.system.vibrate

Causes the device to vibrate, if possible. Currently this will only work on Android and iOS devices that have a built-in vibration motor.

love.system.vibrate( seconds )

seconds (0.5)

number

The duration to vibrate for. If called on an iOS device, it will always vibrate for 0.5 seconds due to limitations in the iOS system APIs.

PowerState

unknown

Cannot determine power status.

battery

Not plugged in, running on a battery.

nobattery

Plugged in, no battery available.

charging

Plugged in, charging battery.

charged

Plugged in, battery is fully charged.

love.thread

Types

Functions

love.thread.getChannel

Enums

love.thread.getChannel

Creates or retrieves a named thread channel.

channel = love.thread.getChannel( name )

channel

The Channel object associated with the name.

name

string

The 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 on a named channel.

channel = love.thread.newChannel()

channel

The new Channel object.

love.thread.newThread

Creates a new Thread from a filename, string or FileData object containing Lua code.

thread = love.thread.newThread( filename )

thread

A new Thread that has yet to be started.

filename

string

The name of the Lua file to use as the source.

thread = love.thread.newThread( fileData )

thread

A new Thread that has yet to be started.

fileData

The FileData containing the Lua code to use as the source.

thread = love.thread.newThread( codestring )

thread

A new Thread that has yet to be started.

codestring

string

A string containing the Lua code to use as the source. It needs to either be at least 1024 characters long, or contain at least one newline.

An object which can be used to send and receive data between different threads.

Constructors

love.thread.newChannel

love.thread.getChannel

Functions

Channel:clear

Channel:demand

Channel:getCount

Channel:hasRead

Channel:peek

Channel:performAtomic

Channel:pop

Channel:push

Channel:supply

Supertypes

Channel:clear

Clears all the messages in the Channel queue.

Channel:clear()

Channel:demand

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

It waits until a message is in the queue then returns the message value.

value = Channel:demand()

value

Variant

The contents of the message.

value = Channel:demand( timeout )

value

Variant

The contents of the message or nil if the timeout expired.

timeout

number

The maximum amount of time to wait.

Channel:getCount

Retrieves the number of messages in the thread Channel queue.

count = Channel:getCount()

count

number

The number of messages in the queue.

Channel:hasRead

Gets whether a pushed value has been popped or otherwise removed from the Channel.

hasread = Channel:hasRead( id )

hasread

boolean

Whether the value represented by the id has been removed from the Channel via Channel:pop, Channel:demand, or Channel:clear.

number

An id value previously returned by Channel:push.

Channel:peek

Retrieves the value of a Channel message, but leaves it in the queue.

It returns nil if there's no message in the queue.

value = Channel:peek()

value

Variant

The contents of the message.

Channel:performAtomic

Executes the specified function atomically with respect to this Channel.

Calling multiple methods in a row on the same Channel is often useful. However if multiple Threads are calling this Channel's methods at the same time, the different calls on each Thread might end up interleaved (e.g. one or more of the second thread's calls may happen in between the first thread's calls.)

This method avoids that issue by making sure the Thread calling the method has exclusive access to the Channel until the specified function has returned.

ret1, ... = Channel:performAtomic( func, arg1, ... )

ret1	any	The first return value of the given function (if any.)
...	any	Any other return values.

func	function	The function to call, the form of function(channel, arg1, arg2, ...) end. The Channel is passed as the first argument to the function when it is called.
arg1	any	Additional arguments that the given function will receive when it is called.
...	any	Additional arguments that the given function will receive when it is called.

Channel:pop

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

It returns nil if there are no messages in the queue.

value = Channel:pop()

value

Variant

The contents of the message.

Channel:push

Send a message to the thread Channel.

See Variant for the list of supported types.

id = Channel:push( value )

number

Identifier which can be supplied to Channel:hasRead

value

Variant

The contents of the message.

Channel:supply

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

See Variant for the list of supported types.

success = Channel:supply( value )

success

boolean

Whether the message was successfully supplied (always true).

value

Variant

The contents of the message.

success = Channel:supply( value, timeout )

success

boolean

Whether the message was successfully supplied before the timeout expired.

value	Variant	The contents of the message.
timeout	number	The maximum amount of time to wait.

A Thread is a chunk of code that can run in parallel with other threads. Data can be sent between different threads with Channel objects.

Constructors

love.thread.newThread

Functions

Thread:getError

Thread:isRunning

Thread:start

Thread:wait

Supertypes

love.timer.getAverageDelta

Thread:getError

Retrieves the error string from the thread if it produced an error.

err = Thread:getError()

err

string

The error message, or nil if the Thread has not caused an error.

Thread:isRunning

Returns whether the thread is currently running.

Threads which are not running can be (re)started with Thread:start.

value = Thread:isRunning()

value

boolean

True if the thread is running, false otherwise.

Thread:start

Starts the thread.

Beginning with version 0.9.0, threads can be restarted after they have completed their execution.

Thread:start()

Thread:start( arg1, arg2, ... )

arg1	Variant	A string, number, boolean, LÖVE object, or simple table.
arg2	Variant	A string, number, boolean, LÖVE object, or simple table.
...	Variant	You can continue passing values to the thread.

Thread:wait

Wait for a thread to finish.

This call will block until the thread finishes.

Thread:wait()

love.timer

Functions

love.timer.getAverageDelta

love.timer.getDelta

love.timer.getFPS

love.timer.getTime

love.timer.sleep

love.timer.step

Enums

Returns the average delta time (seconds per frame) over the last second.

delta = love.timer.getAverageDelta()

delta

number

The average delta time over the last second.

love.timer.getDelta

Returns the time between the last two frames.

dt = love.timer.getDelta()

number

The time passed (in seconds).

love.timer.getFPS

Returns the current frames per second.

fps = love.timer.getFPS()

fps

number

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

time

number

The time in seconds. Given as a decimal, accurate to the microsecond.

love.timer.sleep

Pauses the current thread for the specified amount of time.

love.timer.sleep( s )

number

Seconds to sleep for.

love.timer.step

Measures the time between two frames.

Calling this changes the return value of love.timer.getDelta.

dt = love.timer.step()

number

The time passed (in seconds).

love.touch

Functions

love.touch.getPosition

love.touch.getPressure

love.touch.getTouches

Enums

love.touch.getPosition

Gets the current position of the specified touch-press, in pixels.

x, y = love.touch.getPosition( id )

x	number	The position along the x-axis of the touch-press inside the window, in pixels.
y	number	The position along the y-axis of the touch-press inside the window, in pixels.

light userdata

The identifier of the touch-press. Use love.touch.getTouches, love.touchpressed, or love.touchmoved to obtain touch id values.

love.touch.getPressure

Gets the current pressure of the specified touch-press.

pressure = love.touch.getPressure( id )

pressure

number

The pressure of the touch-press. Most touch screens aren't pressure sensitive, in which case the pressure will be 1.

light userdata

The identifier of the touch-press. Use love.touch.getTouches, love.touchpressed, or love.touchmoved to obtain touch id values.

love.touch.getTouches

Gets a list of all active touch-presses.

touches = love.touch.getTouches()

touches

table

A list of active touch-press id values, which can be used with love.touch.getPosition.

love.video

Types

love.video.newVideoStream

Enums

Creates a new VideoStream. Currently only Ogg Theora video files are supported. VideoStreams can't draw videos, see love.graphics.newVideo for that.

videostream = love.video.newVideoStream( filename )

videostream

A new VideoStream.

filename

string

The file path to the Ogg Theora video file.

videostream = love.video.newVideoStream( file )

videostream

A new VideoStream.

file

File

The File object containing the Ogg Theora video.

An object which decodes, streams, and controls Videos.

Constructors

love.video.newVideoStream

Functions

VideoStream:getFilename

VideoStream:isPlaying

VideoStream:pause

VideoStream:play

VideoStream:rewind

VideoStream:tell/seek

Supertypes

love.window.getDesktopDimensions

VideoStream:getFilename

Gets the filename of the VideoStream.

filename = VideoStream:getFilename()

filename

string

The filename of the VideoStream

VideoStream:isPlaying

Gets whether the VideoStream is playing.

playing = VideoStream:isPlaying()

playing

boolean

Whether the VideoStream is playing.

VideoStream:pause

Pauses the VideoStream.

VideoStream:pause()

VideoStream:play

Plays the VideoStream.

VideoStream:play()

VideoStream:rewind

Rewinds the VideoStream. Synonym to VideoStream:seek(0).

VideoStream:rewind()

VideoStream:seek

Sets the current playback position of the VideoStream.

VideoStream:seek( offset )

offset

number

The time in seconds since the beginning of the VideoStream.

VideoStream:tell

Gets the current playback position of the VideoStream.

seconds = VideoStream:tell()

seconds

number

The number of seconds sionce the beginning of the VideoStream.

love.window

Functions

love.window.close

love.window.getDPIScale

love.window.getDesktopDimensions

love.window.getDisplayCount

love.window.getDisplayName

love.window.getDisplayOrientation

love.window.get/setFullscreen

love.window.getFullscreenModes

love.window.get/setIcon

love.window.get/setMode

love.window.get/setPosition

love.window.getSafeArea

love.window.get/setTitle

love.window.get/setVSync

love.window.hasFocus

love.window.hasMouseFocus

love.window.is/setDisplaySleepEnabled

love.window.isMaximized

love.window.isMinimized

love.window.isOpen

love.window.isVisible

love.window.maximize

love.window.minimize

love.window.requestAttention

love.window.restore

love.window.showMessageBox

love.window.to/fromPixels

love.window.updateMode

Enums

Closes the window. It can be reopened with love.window.setMode.

love.window.close()

love.window.fromPixels

Converts a number from pixels to density-independent units.

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

This function converts coordinates from pixels to the size users are expecting them to display at onscreen. love.window.toPixels does the opposite. The highdpi window flag must be enabled to use the full pixel density of a Retina screen on Mac OS X and iOS. The flag currently does nothing on Windows and Linux, and on Android it is effectively always enabled.

Most LÖVE functions return values and expect arguments in terms of pixels rather than density-independent units.

value = love.window.fromPixels( pixelvalue )

value

number

The converted number, in density-independent units.

pixelvalue

number

A number in pixels to convert to density-independent units.

x, y = love.window.fromPixels( px, py )

x	number	The converted x-axis value of the coordinate, in density-independent units.
y	number	The converted y-axis value of the coordinate, in density-independent units.

px	number	The x-axis value of a coordinate in pixels.
py	number	The y-axis value of a coordinate in pixels.

love.window.getDPIScale

Gets the DPI scale factor associated with the window.

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

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

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

scale = love.window.getDPIScale()

scale

number

The pixel scale factor associated with the window.

Gets the width and height of the desktop.

width, height = love.window.getDesktopDimensions( displayindex )

width	number	The width of the desktop.
height	number	The height of the desktop.

displayindex (1)

number

The index of the display, if multiple monitors are available.

love.window.getDisplayCount

Gets the number of connected monitors.

count = love.window.getDisplayCount()

count

number

The number of currently connected displays.

love.window.getDisplayName

Gets the name of a display.

name = love.window.getDisplayName( displayindex )

name

string

The name of the specified display.

displayindex (1)

number

The index of the display to get the name of.

love.window.getDisplayOrientation

Gets current device display orientation.

orientation = love.window.getDisplayOrientation( displayindex )

orientation

DisplayOrientation

Current device display orientation.

displayindex (nil)

number

Display index to get its display orientation, or nil for default display index.

love.window.getFullscreen

Gets whether the window is fullscreen.

fullscreen, fstype = love.window.getFullscreen()

fullscreen	boolean	True if the window is fullscreen, false otherwise.
fstype	FullscreenType	The type of fullscreen mode used.

love.window.getFullscreenModes

Gets a list of supported fullscreen modes.

modes = love.window.getFullscreenModes( displayindex )

modes

table

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

displayindex (1)

number

The index of the display, if multiple monitors are available.

love.window.getIcon

Gets the window icon.

imagedata = love.window.getIcon()

imagedata

love.window.hasMouseFocus

The window icon imagedata, or nil if no icon has been set with love.window.setIcon.

love.window.getMode

Gets the display mode and properties of the window.

width, height, flags = love.window.getMode()

width	number	Window width.
height	number	Window height.
flags	table	Table with the window properties:

flags.fullscreen	boolean	Fullscreen (true), or windowed (false).
flags.fullscreentype	FullscreenType	The type of fullscreen mode used.
flags.vsync	boolean	True if the graphics framerate is synchronized with the monitor's refresh rate, false otherwise.
flags.msaa	number	The number of antialiasing samples used (0 if MSAA is disabled).
flags.resizable	boolean	True if the window is resizable in windowed mode, false otherwise.
flags.borderless	boolean	True if the window is borderless in windowed mode, false otherwise.
flags.centered	boolean	True if the window is centered in windowed mode, false otherwise.
flags.display	number	The index of the display the window is currently in, if multiple monitors are available.
flags.minwidth	number	The minimum width of the window, if it's resizable.
flags.minheight	number	The minimum height of the window, if it's resizable.
flags.highdpi	boolean	True if high-dpi mode is allowed on Retina displays in OS X. Does nothing on non-Retina displays.
flags.refreshrate	number	The refresh rate of the screen's current display mode, in Hz. May be 0 if the value can't be determined.
flags.x	number	The x-coordinate of the window's position in its current display.
flags.y	number	The y-coordinate of the window's position in its current display.
flags.srgb	boolean	Removed in 0.10.0 (use love.graphics.isGammaCorrect instead). True if sRGB gamma correction is applied when drawing to the screen.

love.window.getPosition

Gets the position of the window on the screen.

The window position is in the coordinate space of the display it is currently in.

x, y, displayindex = love.window.getPosition()

x	number	The x-coordinate of the window's position.
y	number	The y-coordinate of the window's position.
displayindex	number	The index of the display that the window is in.

love.window.getSafeArea

Gets area inside the window which is known to be unobstructed by a system title bar, the iPhone X notch, etc. Useful for making sure UI elements can be seen by the user.

x, y, w, h = love.window.getSafeArea()

x	number	Starting position of safe area (x-axis).
y	number	Starting position of safe area (y-axis).
w	number	Width of safe area.
h	number	Height of safe area.

love.window.getTitle

Gets the window title.

title = love.window.getTitle()

title

string

The current window title.

love.window.getVSync

Gets current vertical synchronization (vsync).

vsync = love.window.getVSync()

vsync

number

Current vsync status. 1 if enabled, 0 if disabled, and -1 for adaptive vsync.

love.window.hasFocus

Checks if the game window has keyboard focus.

focus = love.window.hasFocus()

focus

boolean

True if the window has the focus or false if not.

Checks if the game window has mouse focus.

focus = love.window.hasMouseFocus()

focus

boolean

True if the window has mouse focus or false if not.

love.window.isDisplaySleepEnabled

Gets whether the display is allowed to sleep while the program is running.

Display sleep is disabled by default. Some types of input (e.g. joystick button presses) might not prevent the display from sleeping, if display sleep is allowed.

enabled = love.window.isDisplaySleepEnabled()

enabled

boolean

True if system display sleep is enabled / allowed, false otherwise.

love.window.isMaximized

Gets whether the Window is currently maximized.

The window can be maximized if it is not fullscreen and is resizable, and either the user has pressed the window's Maximize button or love.window.maximize has been called.

maximized = love.window.isMaximized()

maximized

boolean

True if the window is currently maximized in windowed mode, false otherwise.

love.window.isMinimized

Gets whether the Window is currently minimized.

minimized = love.window.isMinimized()

minimized

boolean

True if the window is currently minimized, false otherwise.

love.window.isOpen

Checks if the window is open.

open = love.window.isOpen()

open

boolean

True if the window is open, false otherwise.

love.window.isVisible

Checks if the game window is visible.

The window is considered visible if it's not minimized and the program isn't hidden.

visible = love.window.isVisible()

visible

boolean

True if the window is visible or false if not.

love.window.maximize

Makes the window as large as possible.

This function has no effect if the window isn't resizable, since it essentially programmatically presses the window's 'maximize' button.

love.window.maximize()

love.window.minimize

Minimizes the window to the system's task bar / dock.

love.window.minimize()

love.window.requestAttention

Causes the window to request the attention of the user if it is not in the foreground.

In Windows the taskbar icon will flash, and in OS X the dock icon will bounce.

love.window.requestAttention( continuous )

continuous (false)

boolean

Whether to continuously request attention until the window becomes active, or to do it only once.

love.window.restore

Restores the size and position of the window if it was minimized or maximized.

love.window.restore()

love.window.setDisplaySleepEnabled

Sets whether the display is allowed to sleep while the program is running.

Display sleep is disabled by default. Some types of input (e.g. joystick button presses) might not prevent the display from sleeping, if display sleep is allowed.

love.window.setDisplaySleepEnabled( enable )

enable

boolean

True to enable system display sleep, false to disable it.

love.window.setFullscreen

Enters or exits fullscreen. The display to use when entering fullscreen is chosen based on which display the window is currently in, if multiple monitors are connected.

success = love.window.setFullscreen( fullscreen )

success

boolean

True if an attempt to enter fullscreen was successful, false otherwise.

fullscreen

boolean

Whether to enter or exit fullscreen mode.

success = love.window.setFullscreen( fullscreen, fstype )

success

boolean

True if an attempt to enter fullscreen was successful, false otherwise.

fullscreen	boolean	Whether to enter or exit fullscreen mode.
fstype	FullscreenType	The 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 )

success

boolean

Whether the icon has been set successfully.

imagedata