Subscribing to Events

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 Event page

Example

Subscribing to an event is the same for robots and levelgens: you call bf:subscribe. Here is a simple example using the MsgReceived Event which is available to both robots and levelgens:

function main()
  bf:subscribe(Event.MsgReceived)   -- The subscribe method is also available on
                                    -- the LevelGenerator and Robot objects
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

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

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