View source for Interacting with the game: Event-based programming

__TOC__

==Events==

The Lua scripts are all executed at startup. If you were to add a single file named <code>hello_world.lua</code> 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:

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

There are many more. All are fully documented in the [https://codedoc.pioneerspacesim.net/ Pioneer Codedoc]. Of the five that I have listed, only <code>onGameStart</code> 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.

Here is an adaptation of the 'Hello World' message above to be event driven. It's now triggered on game start and will still turn up on the command line, but now much later in the start sequence, pretty much when the game starts and you find yourself docked at a starport.
 local Event = require 'Event'
 
 local welcome = function ()
     print("Hello, World!")
 end
 
 Event.Register("onGameStart", welcome)

We move on. The same function again but now instead the message is presented on the player's ship console and is now welcoming them to Pioneer. We need to add the ''' 'Comms' ''' module to the script and the function name has changed to ''' 'onGameStart' ''', same as the event, which is common practice in Pioneer.
 local Comms = require 'Comms'
 local Event = require 'Event'
 
 local onGameStart = function ()
     Comms.Message ('Welcome to Pioneer!')
 end
 
 Event.Register("onGameStart", onGameStart)
The latest code may not work as intended. The reason is that ''' 'onGameStart' ''' is not when the game starts but when it is being launched after pressing the button on the main menu to start on Mars, or whatever location you prefer. Instead we go for the next best event, ''' 'onShipDocked' '''. This will make the message trigger every time we dock at a space station, on the ground or in orbit. ''' 'onShipDocked' ''' will not trigger on launching a saved game but it will trigger when we start a new game, docked at a starport. And now the script works just fine...
 local Comms = require 'Comms'
 local Event = require 'Event'
 
 local onShipDocked = function ()
     Comms.Message ('Welcome to Pioneer!')
 end
 
 Event.Register("onShipDocked", onShipDocked)
If you look at the comms log after docking/starting a new game, you will see that the greeting has been posted more than once. This is because the same function is triggered for all ships in the vicinity, not only the players. The Pioneer universe is populated by ships and characters and they follow pretty much the same rules as the player. To make the code work we need to test if the ship is the player first. Modify the ''' 'onShipDocked' ''' function in the previous example like this:
 local onShipDocked = function (ship)
     if ship:IsPlayer() then
         Comms.Message ('Welcome to Pioneer!')
     end
 end

An alternative solution to the last code snippet would be to test for if the ship is '''not''' the player:

 local onShipDocked = function (ship)
     if not ship:IsPlayer() then return end
     Comms.Message ('Welcome to Pioneer!')
 end

==Event arguments==

As mentioned before '''[https://codedoc.pioneerspacesim.net/#LuaClass:Event:onShipDocked onShipDocked]''' passes two arguments to the function. A reference to the ship and a reference to the spacestation.
 local onShipDocked = function (ship, station)
Through these arguments we also get access to some of the ''' 'ship' ''' and ''' 'station' ''' methods without having to include any modules.
''' 'ship:IsPlayer()' ''' is for free. Unlimited power is now at your fingertips! ''' 'Comms.Message' ''' takes a second argument for the sender of the message. ''' 'station.label' ''' gives us the name of the space station.

 Comms.Message ("Congratulations! Your ship has been upgraded for free!", station.label)
 ship:SetShipType('xylophis')