/**

@page events Subscribing to Events
@section Overview

Robots and Levelgens can register to be notified of certain game events.
When the event occurs, a specific function in the script (termed a "callback"
function) is invoked. This lets a script perform some action in response to
these events.

For a complete list of Events and their callback signatures, see the \ref
EventEnum page

@section Example
Subscribing to an event is the same for robots and levelgens: you call \link
LuaScriptRunner::subscribe `bf:subscribe`\endlink. Here is a simple example using
the MsgReceived Event which is available to both robots and levelgens:

@code

function main()
  bf:subscribe(Event.MsgReceived)
end

-- Whenever an event occurs which a script is subscribed to, Bitfighter will
-- run the function named after that Event.
-- For the `MsgReceived` Event, the name must be `onMsgReceived`
function onMsgReceived(msg, player, isGlobal)
  print(player:getName(), " said: ", msg)
end

@endcode


Another example that displays an announcement when an object or ship enters any kind of zone.

@code
function onShipEnteredZone(ship, zone)
    levelgen:announce("ship entered zone!")
end

function onShipLeftZone(ship, zone)
    levelgen:announce("ship left zone!")
end 

function onObjectEnteredZone(obj, zone)
    levelgen:announce("obj entered zone!")
end 

function onObjectLeftZone(obj, zone)
    levelgen:announce("obj left zone!")
end 

function main()
    bf:subscribe(Event.ShipEnteredZone)
    bf:subscribe(Event.ShipLeftZone)
    bf:subscribe(Event.ObjectEnteredZone)
    bf:subscribe(Event.ObjectLeftZone)
end
@endcode

*/
