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:
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:
onGameStartis triggered when the player clicks on a new game button in the main menu, or when the player loads a game.
onEnterSystemis triggered whenever any ship arrives in the current star system after a hyperspace journey.
onLeaveSystemis triggered whenever any ship leaves the current star system by hyperspacing.
onShipDestroyedis triggered whenever any ship is destroyed.
onShipDockedis 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
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)