API Extensions

Ammo adds and modifies several methods and properties in the libraries of both Lua and LÖVE.

math

Most of these functions were ported from FlashPunk.

angle(x1, y1, x2, y2)
Returns the angle (in radians) between the two points.

x1: The X coordinate of the first point.
y1: The Y coordinate of the first point.
x2: The X coordinate of the second point.
y2: The Y coordinate of the second point.

clamp(x, min, max)
Returns x, making sure it is within the minimum and maximum values.

x: The value.
min: The minimum value.
max: The maximum value.

distance(x1, y1, x2, y2)
Returns the distance between the two points.

x1: The X coordinate of the first point.
y1: The Y coordinate of the first point.
x2: The X coordinate of the second point.
y2: The Y coordinate of the second point.

dot(x1, y1, x2, y2)
Returns the dot product of the two points.

x1: The X coordinate of the first point.
y1: The Y coordinate of the first point.
x2: The X coordinate of the second point.
y2: The Y coordinate of the second point.

length(x, y)
Returns the length of the point from (0, 0).

x: The X coordinate.
y: The Y coordinate.

lerp(a, b, t)
Performs a liner interpolation between two values.

a: The first value.
b: The second value.
t: The interpolation factor.

round(x)
Rounds the value. A shortcut for math.floor(x + 0.5).

x: The value.

scale(x, min1, max1, min2, max2)
Transfers a value from one scale to another. As an example, math.scale(30, 0, 100, 0, 1) == 0.3 and math.scale(15, 10, 20, 200, 50) == 125.

x: The value.
min1: The minimum range of the value's current scale.
max1: The maximum range of the value's current scale.
min2: The minimum range of the scale you want to transfer the value to.
max2: The minimum range of the scale you want to transfer the value to.

sign(x)
Finds the sign of the value. Returns 1 if x > 0, -1 if x < 0, and 0 when x == 0.

x: The value.

tau
Equal to math.pi * 2. Very useful whenever operating in radians.

love.graphics

Ammo adds two functions, love.graphics.storeColor and love.graphics.resetColor, which help to avoid overwriting the current colour. storeColor stores the current colour, and resetColor sets the colour back to what was stored. So, instead of doing this:

local r, g, b, a = love.graphics.getColor()
love.graphics.setColor(newColor)
-- draw stuff
love.graphics.setColor(r, g, b, a)

You could do this:

love.graphics.storeColor()
love.graphics.setColor(newColor)
-- draw stuff
love.graphics.resetColor()

World:draw automatically calls storeColor and resetColor before and after drawing each entity, respectively. Therefore, if you're drawing inside an entity's draw function, you needn't worry about calling these:

function Player:draw()
  love.graphics.setColor(self.color)
  -- ...
end

height
Stores the value from love.graphics.getHeight. This is set on initialisation, and updated when love.window.setMode, love.window.updateMode, or love.window.updateConstants are called.

resetColor()
Sets the colour back to whatever was stored by storeColor.

storeColor()
Stores the current colour for later use by resetColor.

width
Stores the value from love.graphics.getWidth. This is set on initialisation, and updated when love.window.setMode, love.window.updateMode, or love.window.updateConstants are called.

love.mouse

Due to the presence of a camera, Ammo defines two sets of functions to get the mouse's position: raw and world. The raw functions are the original functions defined by LÖVE, returning screen-space mouse coordinates. The world functions return coordinates relative to a camera; by default this is the current world's camera, but a different camera can be provided. There is also a set of rotated functions which point to the world functions for the sake of backwards compatibility. These will be removed in a future version.

love.mouse.getX, getY, and getPosition are set to their corresponding world functions by default with love.mouse.switchToWorld.

raw

getRawPosition()
Returns the values of love.mouse.getRawX and love.mouse.getRawY.

getRawX()
The original love.mouse.getX, returning the mouse's X position relative to the screen.

getRawY()
The original love.mouse.getY, returning the mouse's Y position relative to the screen.

switchToRaw()
Sets love.mouse.getX, getY, and getPosition to the corresponding raw functions.

world

getWorldPosition(camera)
Returns the values of love.mouse.getWorldX and love.mouse.getWorldY.

getWorldX(camera)
Returns the mouse's X position in world coordinates relative to the camera. Takes into account camera position, zoom, and rotation.

getWorldY(camera)
Returns the mouse's Y position in world coordinates relative to the camera. Takes into account camera position, zoom, and rotation.

switchToWorld()
Sets love.mouse.getX, getY, and getPosition to the corresponding world functions. This is executed by default.

rotated

getRotatedPosition(camera), getRotatedX(camera), getRotatedY(camera), switchToRotated() all point to the corresponding world functions. These will be removed in a later version.

love.window

height
Stores the value from love.graphics.getHeight. This is set on initialisation, and updated when love.window.setMode, love.window.updateMode, or love.window.updateConstants are called.

setMode(width, height, flags)
Overridden to update love.graphics.width and love.graphics.height. Behaves in the same way as the original method.

updateConstants(width, height) Updates the width/height constants in love.graphics and love.window to either their current value or the values specified by the optional width and height parameters.

updateMode(width, height, settings)
Overridden to update love.graphics.width and love.graphics.height. Behaves in the same way as the original method.

width
Stores the value from love.graphics.getWidth. This is set on initialisation, and updated when love.window.setMode, love.window.updateMode, or love.window.updateConstants are called.