Interacting with the game: Event-based programming

The Lua scripts are all executed at startup. If you were to add a single file named hello_world.lua to the data/modules directory containing the following:

print("Hello, World!")

you would literally see the words, "Hello, World!" appear in Pioneer's output (if running in a terminal) shortly before the main menu appeared. You would also see it in the Lua console, if you were to open it.

All file-scoped imperative statements in all Lua files are executed at that time. The way to get Lua code to interact with the game itself, beyond that time, is to write functions and to connect them to event handlers. Many events are triggered by Pioneer during the course of play, all of which will cause any functions which are connected to them, to run. Most will provide those functions with arguments.

Here is a quick list of some of the more commonly used events:

• onGameStart is triggered when the player clicks on a new game button in the main menu, or when the player loads a game.
• onEnterSystem is triggered whenever any ship arrives in the current star system after a hyperspace journey.
• onLeaveSystem is triggered whenever any ship leaves the current star system by hyperspacing.
• onShipDestroyed is triggered whenever any ship is destroyed.
• onShipDocked is triggered whenever any ship docks at a starport.

There are many more. All are fully documented in the Pioneer Codedoc. Of the five that I have listed, only onGameStart does not provide the function with any arguments. The other four provide a reference to the ship in question, and the latter two each also provide an additional argument (a reference to the attacker, and the starport, respectively).

Writing a function for an event

An event handling function does not have to return anything. It will be passed any arguments specified in the documentation, which it can either deal with, or ignore. It has access to any variables that are declared in the same file scope, including named functions and tables.

The following function sends a message to the player's ship console, welcoming them to Pioneer:

local welcome = function ()
    UI.Message ('Welcome to Pioneer!')
end

The next one expects a ship, and if that ship is the player, it greets them again:

local greetShip = function (ship)
    if ship:IsPlayer() then
        UI.Message ('Hope you had an enjoyable hyperjump.')
    end
end

All that remains is to attach these functions to events. The first, I'm going to attach to the onGameStart event, the second, I'm going to attach to onEnterSystem:

EventQueue.onGameStart:Connect(welcome)
EventQueue.onEnterSystem:Connect(greetShip)

EventQueue is a global table containing all of the events, which themselves have methods to connect and disconnect functions as handlers. Connect() sets the function up as an event handler, and Disconnect() is its (rarely required) counterpart.

It's actually common practice in Pioneer to name the function after the event:

local onGameStart = function ()
    UI.Message ('Welcome to Pioneer!')
end

EventQueue.onGameStart:Connect(onGameStart)