Lua Reference
-------------
This is a reference for my game engine, and all the functions you can call from
lua.

The Basics
----------
- All the core logic is in GameState.lua. GameState.lua contains functions
  that map to the main methods in my game engine. If any of those functions are
  removed you can expect errors.
- The engine will load any .lua files in the scripts subdir.
	- Note: On Linux the scripts subdir will reside at:
	  "<install dir>/share/EXCOSC Base". You'll probably want to install
	  the game to your home dir rather than the default /usr/local if you're
	  planning on editing the lua files.
- F5 will reload all scripts in-game.
- Escape will always quit the game.
- You can run the game in a window with "-w <width> -h <height> -win" on the
  commandline.
- Any images in the images subdir will be loaded when the game starts up. They
  will not be reloaded when the scripts are reloaded with F5.
- Ditto for sounds (only .ogg files are supported) in the sounds subdir.
- The engine will rescale automatically to any window size/resolution. Its
  ideal resolution is 1280x720 and if you give it a window with a 16:9 aspect
  ratio, the drawing coordinates will always have a range of 1280x720. If you
  provide it with a different aspect ratio, the range will be adjusted
  accordingly. e.g. running fullscreen on a 1680x1050 (16:10) monitor, the
  drawing area will be 1280x800, scaled up to fit the whole screen.
- You can get the size of the drawing area via the
  Application:getDrawingAreaSize() and Drawer:getDrawingAreaSize() methods.

GameState.lua
-------------
function initialise(app):
- This is called once when the game is started.
- app is the Application object, which has various methods for playing sounds
  and sending OSC messages (see below).

function update(app):
- This is called for every frame, and is where you should update any game logic.

function draw(d):
- This is where any drawing happens.
- d is a Drawer object, and is the interface by which you can draw things.

function keyDown/keyUp(app, action, keyPressed, keyModifier):
- These are called when a key is pressed/released.
- action is the action the key is associated with in the engine's key mappings.
  I don't have a lua interface to add new actions, so you can probably ignore
  this.
- keyPressed is the key that was pressed/released. It's a string (see
  ListOfKeys.txt for the full list of values the engine supports).
- keyModifier is an integer representing any modifier keys that were active when
  the keyDown/Up event was sent (0:none, 1:Ctrl, 2:Shift, 3:Alt, 4:Meta).

function mouseDown/mouseUp(app, button, pos)/mouseMove(app, pos):
- Called when a basic mouse event occurs.
- button is an integer representing which button was clicked/released (1:left,
  2:middle, 3:right).
- pos is a TwoFloats value representing the mouse's position.

function mouseWheel(app, dir):
- Called when the mouse wheel is moved.
- dir is a bool representing the direction the wheel was moved.

function joyMove(app, action, value, joystick, axis):
- Called when a joystick axis changes.
- For action, see keyDown/Up.
- value is the value of the axis (float): -1 -> +1.
- joystick is an integer representing which joystick sent the event.
- axis is an integer representing the axis the event is for (0:up,
  1:right, 2:down, 3:left, 4:trigger1, 5:trigger2, 6:up2, 7:right2,
  8:down2, 9:left2).

Misc Functions
--------------
writeDebugOutput(val):
- This will write a single line of text to the screen for debugging purposes.

hslToRgb(col):
- This will take a ThreeFloats HSL (hue, saturation, luminance) colour value and
  return the equivalent RGB value for it.

rgbToHsl(col):
- Does the opposite.

fakeLog(val):
- Fast log approximation (usage: y = fakeLog(x)).

fakeExp(val):
- Fast exp approximation (usage: y = fakeExp(x)).

Random:
- Pseudo-random number generator from my game engine.
- Float usage: y = Random.getGlobal():getRandomFloat() (returns 0 -> 1).
- Int usage: y = Random.getGlobal():getRandomInt(maxVal) (return 0 -> maxVal).

Basic Types
-----------
There's two basic types I use throughout the engine, TwoFloats and ThreeFloats.
Typically TwoFloats is used to represent positions and sizes, and ThreeFloats
represents colours. They both have the standard operators defined, and can be
multiplied/divided etc. by floats as well as other TwoFloats/ThreeFloats.

TwoFloats also has some useful extra methods:
- getDistance(TwoFloats) (returns the distance to another TwoFloats)
- getDistanceSquared(TwoFloats) (faster than getDistance)
- getMagnitude() (returns the magnitude of the vector)
- getAngle(TwoFloats) (returns the angle between this and another TwoFloats)
- getAngle() (returns the angle between this TwoFloats and the origin)
- perpendicular() (returns a TwoFloats perpendicular to this one)
- normal() (returns a normalised version of this TwoFloats)
- dotProduct(TwoFloats) (returns the dot product of the two TwoFloats)
- crossProduct(TwoFloats) (returns the cross product of the two TwoFloats)
- mirror(TwoFloats) (returns a version of this TwoFloats mirrored around the
					 other)
- isWithin(TwoFloats, TwoFloats) (returns true if the TwoFloats is within the
								  bounding box represented by topLeft, size)

Application
-----------
"sound" in these functions is a string: the filename of the sound in the sounds
subdir minus its extension.

function playMusic(sound):
- Plays a soundfile on a loop. There can only be one active music file. Calling
  playMusic a second time will replace the original sound.

function stopMusic():
- Stops the music soundfile playing.

function triggerSound(sound, level, pan):
- Triggers a sound to play as a one-shot.
- level sets the sound's level (1.0 == its original volume).
- pan sets the sound's panning (0.0 -> 1.0; left -> right).

function triggerLoop(sound, level, pan, fade):
- Triggers a sound to play on a loop.
- Returns an index representing the sound (can be used to stop the sound
  playing).
- fade is a bool. If true, the sound will fade in when triggered, and fade
  out when stopped.

function stopLoop(soundIndex):
- Stops the indexed sound from playing.

function toggleGranulator(val):
- Togggles the granulator audio effect on/off.

function setGranulatorParams(density, duration, pitch, feedback, mix, level):
- Sets the parameters of the granulator audio effect.
- density is the density of the grains (0->1).
- duration is the length of the individual grains (0->2 seconds).
- pitch sets the pitch of the grains (where 1 is the original pitch, 2 is an
  octave above, 0.5 an octave below etc.).
- feedback is how much of the granulated sound is fed back into the granulator's
  delay line.
- mix is how much of the input is fed to the output (i.e. 1 = all granulator,
  0 = all input).
- level is the amplitude of the granulator's output (1 = no gain or attenuation).

function toggleDelay(val):
- Togggles the delay audio effect on/off.

function setDelayParams(time, feedback, mix):
- Sets the parameter of the delay audio effect.
- time is the delay time (0->2 seconds).
- feedback is how much of the delayed signal is fed back into the delay line.
- mix is how much of the input is fed to the output (i.e. 1 = all delay,
  0 = all input).

function toggleDistortion(val):
- Togggles the distortion audio effect on/off.

function setDistortionGain(val):
- Sets the gain of the distortion. Higher values are better i.e. 32.0 gives a
  nice heavy distortion.

function getDrawingAreaSize():
- Returns the dimensions of the drawing area as a TwoFloats (see The Basics,
  above).

Drawer
------
"image" in these functions is a string: the filename of the image in the images
subdir minus its extension. The engine understands jpg and png images.
Non-power-of-two images are converted to power-of-two dimensions when loaded.

function drawImage(image, position, size, colour, alpha):
- Draws an image on screen.
- position and size are TwoFloats values. A size of 1.0,1.0 represents the
  image's original dimensions.
- colour is a ThreeFloats representing the RGB colour to tint the image
  (1.0, 1.0, 1.0 means no tint).
- alpha is a float representing how much to blend the image.
- These variables are the same for the following functions.

function drawRotImage(image, position, angle, pivot, size, colour, alpha):
- Draws a rotated image on screen.
- angle is a float representing the angle to rotate the image (in radians).
- pivot is a TwoFloats representing the pivot point (within the image) around
  which to rotate it.

function drawSubImage(image, position, subPos, subSize, size, colour, alpha):
- Draws a cropped section of the image on screen.
- subPos and subSize are TwoFloats representing the position and dimensions of
  the cropped section. They are both 0 -> 1.

function drawTiledImage(image, position, size, tilePos, tileNum, colour, alpha):
- Draws a single image tiled multiple times within the desired rect.
- tilePos is a TwoFloats representing the position within the image drawing
  should start at.
- tileNum is a TwoFloats representing how many times the image should be tiled
  along both axes.

function drawText(text, font, position, boxWidth, justification, size, colour, alpha):
- Draws some text on screen.
- font is a string representing the font. Due to the way the engine works,
  this is currently limited to "DebugFont", "SmallFont", "MedFont", or
  "BigFont".
- boxWidth is a float representing the width of the box within which to draw the
  text. Going beyond the box's bounds will trigger a line break.
- justification is an int (0:left justification, 1:centre justification).

function drawTextCached(text, font, layout, position, boxWidth, justification, size, colour, alpha):
- This is a more efficient version of drawText, making use of a TextLayout
  object to cache the text's layout.
- For text that changes frequently it won't provide much benefit, but for
  text that is relatively static, this function is ridiculously fast.
- It is used as such:

layout = TextLayout()

function draw(d)
	d:drawTextCached("This is some text that won't change.",
					 "BigFont",
					 layout,
					 TwoFloats(128.0),
					 1024.0,
					 1,
					 1.0,
					 ThreeFloats(1.0),
					 1.0)
end

- Note that if you want to update cached text, you will need to call
  TextLayout:clear() before you see any changes.

function drawLine(image, start, end, colour, alpha):
- Draws a straight line between its start and end points.
- image is the line texture.

function drawConnectedLine(image, points, pointsScale, pointsColour, pointsAlpha):
- Draws a line made up of multiple points.
- image is the line texture.
- points is a table made up of TwoFloats representing the points of the line.
- pointsScale is a table of floats representing the size of the line at each
  point.
- pointsColour is a table of ThreeFloats representing the colour of the line at
  each point.
- pointsAlpha is a table of floats representing the alpha value of each point on
  the line.
- NOTE: The 4 tables must all have the same number of elements, or bad things
  will likely happen.

function fillRect(position, size, colour, alpha):
- Fills a rectangle with a solid colour.

function fillGradient(position, size, colourTop, colourBottom, alphaTop, alphaBottom):
- Fills a rectangle with a horizontal gradient.

function translate(offset):
- Translates all subsequent drawing commands by the specified offset.

function scale(size):
- Scales all subsequent drawing commands by the specified amounts.

function rotate(angle, pivot):
- Rotates all subsequent drawing commands around the pivot point by the
  specified angle.

function setViewport(position, size):
- Specifies a viewport to restrict drawing to.

function resetViewport():
- Resets the viewport to its original dimensions.

function getDrawingAreaSize():
- Returns the dimensions of the drawing area as a TwoFloats (see The Basics,
  above).
 