PioneerWiki - User contributions [en]

Interacting with the game: Event-based programming

2026-06-08T12:03:10Z

Zonkmachine: /* More events */

__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 appears. 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/#LuaClass:Event 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. Let's see if there is an event that better suits our purpose. ''' '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 or when we start a new game, docked at a starport. Now the script works just fine and will launch the message the next time you land or dock with a space station.
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/landing, you may see the greeting posted more than once. This is because the same function is triggered for all ships in the vicinity, not only the player's. The Pioneer universe is populated by ships and characters and they follow pretty much the same rules as the player. To fix this 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

==Setting a timer==
Yet another way to avoid the problem with ''' 'onGameStart' ''' missing your function initially is to place a [https://codedoc.pioneerspacesim.net/#CClass:Timer Timer] to delay the event for a short while. Just a second or so to allow the game to load completely. CallAt takes two arguments, the time of action and a function to be carried out. Example form the Timer documentation:
Timer:CallAt(Game.time+30, function ()
Comms.Message("Special offer expired, sorry.")
end)

A complete example of the welcome message reworked with a timer. ''' 'Game.time' ''' gives us the game time right now so if we call the timer with ''' 'Game.time + 1' ''' we give it a second to think things through.

local Comms = require 'Comms'
local Game = require 'Game'
local Event = require 'Event'
local Timer = require 'Timer'

local onGameStart = function ()
if not Game.player then return end

Timer:CallAt(Game.time + 1, function ()
Comms.Message ('Welcome to Pioneer!')
end)
end

Event.Register("onGameStart", onGameStart)

==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')

==More events==

An event can be registered only once per file. If you need more than one function called by the same event you must wrap them in a function.

Example from '''[https://github.com/pioneerspacesim/pioneer/blob/6111dad3f0b14d64df844511bf3c92b9e583ec76/data/modules/MusicPlayer.lua#L131-L138 /data/modules/MusicPlayer.lua]''':
Event.Register("onGameStart", function ()
MusicPlayer.rebuildSongList()
if Game.player:GetDockedWith() and music["docked"] then
MusicPlayer.playRandomSongFromCategory("docked")
else)
playAmbient()
end
end)

If you register an event more than once in the same file only the last instance will be registered and you will see a log warning on the command line and in output.txt.

Example: '''test_module_1.lua'''
Event.Register("onGameStart", function ()
print("Only the first instance of onGameStart() will be registered")
end)

Event.Register("onGameStart", function ()
print("Only the last instance of onGameStart() will be registered")
end)

Output. Warning and message:
...
Info: Loading [00%]: Sound::Init took 11.47ms
Info: Loading [08%]: Lua::InitModules() started
Warning: Module modules.test_module_1 overwriting event callback function: 0x57d5ed8b5d50
Info: Loading [08%]: Lua::InitModules() took 84.46ms
Info: Loading [17%]: GalaxyGenerator::Init() started
Info: Creating new galaxy generator 'legacy' version
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4609ms
Info: Only the last instance of onGameStart() will be registered
Warning: lodos_shield.model: no materials defined!
Info: CreateCollisionMesh for : (lodos_shield)
...

Use instead:
local message1 = function ()
print("This is message1 calling!")
end

local message2 = function ()
print("This is message2 calling!")
end

Event.Register("onGameStart", function()
message1()
message2()
end)

output:
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4510ms
Info: This is message1 calling!
Info: This is message2 calling!
Warning: skipjack_shield.model: no materials defined!
Info: CreateCollisionMesh for : (skipjack_shield)
...

Events can be registered anytime and anywhere in a file but typically they are grouped at the end of a file/module.

If you need to redirect an event to another function you need to first deregister the event.
local Game = require 'Game'
local Event = require 'Event'

local message1 = function ()
print("This is message1 calling!")
end

local message2 = function ()
print("This is message2 calling!")
end

Event.Register("onGameStart", message1)

print("Now deregistering 'onGameStart message1' and registering 'onGameStart message2'")
print("No warning message will be given below")
Event.Deregister("onGameStart", message1)
Event.Register("onGameStart", message2)
print("See!?")

output:
...
Info: Loading [00%]: Sound::Init took 10.81ms
Info: Loading [08%]: Lua::InitModules() started
Info: Now deregistering 'onGameStart message1' and registering 'onGameStart message2'
Info: No warning message will be given below
Info: See!?
Info: Loading [08%]: Lua::InitModules() took 99.92ms
Info: Loading [17%]: GalaxyGenerator::Init() started
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4787ms
Info: This is message2 calling!
Warning: storeria_shield.model: no materials defined!
Info: CreateCollisionMesh for : (storeria_shield)
...

Interacting with the game: Event-based programming

2026-06-08T12:01:50Z

Zonkmachine: /* More events */ fixup

__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 appears. 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/#LuaClass:Event 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. Let's see if there is an event that better suits our purpose. ''' '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 or when we start a new game, docked at a starport. Now the script works just fine and will launch the message the next time you land or dock with a space station.
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/landing, you may see the greeting posted more than once. This is because the same function is triggered for all ships in the vicinity, not only the player's. The Pioneer universe is populated by ships and characters and they follow pretty much the same rules as the player. To fix this 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

==Setting a timer==
Yet another way to avoid the problem with ''' 'onGameStart' ''' missing your function initially is to place a [https://codedoc.pioneerspacesim.net/#CClass:Timer Timer] to delay the event for a short while. Just a second or so to allow the game to load completely. CallAt takes two arguments, the time of action and a function to be carried out. Example form the Timer documentation:
Timer:CallAt(Game.time+30, function ()
Comms.Message("Special offer expired, sorry.")
end)

A complete example of the welcome message reworked with a timer. ''' 'Game.time' ''' gives us the game time right now so if we call the timer with ''' 'Game.time + 1' ''' we give it a second to think things through.

local Comms = require 'Comms'
local Game = require 'Game'
local Event = require 'Event'
local Timer = require 'Timer'

local onGameStart = function ()
if not Game.player then return end

Timer:CallAt(Game.time + 1, function ()
Comms.Message ('Welcome to Pioneer!')
end)
end

Event.Register("onGameStart", onGameStart)

==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')

==More events==

An event can be registered only once per file. If you need more than one function called by the same event you must wrap them in a function.

Example from '''[https://github.com/pioneerspacesim/pioneer/blob/6111dad3f0b14d64df844511bf3c92b9e583ec76/data/modules/MusicPlayer.lua#L131-L138 /data/modules/MusicPlayer.lua]''':
Event.Register("onGameStart", function ()
MusicPlayer.rebuildSongList()
if Game.player:GetDockedWith() and music["docked"] then
MusicPlayer.playRandomSongFromCategory("docked")
else)
playAmbient()
end
end)

If you register an event more than once in the same file only the last instance will be registered and you will see a log warning on the command line and in output.txt.

Example - test_module_1.lua:
Event.Register("onGameStart", function ()
print("Only the first instance of onGameStart() will be registered")
end)

Event.Register("onGameStart", function ()
print("Only the last instance of onGameStart() will be registered")
end)

Output. Warning and message:
...
Info: Loading [00%]: Sound::Init took 11.47ms
Info: Loading [08%]: Lua::InitModules() started
Warning: Module modules.test_module_1 overwriting event callback function: 0x57d5ed8b5d50
Info: Loading [08%]: Lua::InitModules() took 84.46ms
Info: Loading [17%]: GalaxyGenerator::Init() started
Info: Creating new galaxy generator 'legacy' version
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4609ms
Info: Only the last instance of onGameStart() will be registered
Warning: lodos_shield.model: no materials defined!
Info: CreateCollisionMesh for : (lodos_shield)
...

Use instead:
local message1 = function ()
print("This is message1 calling!")
end

local message2 = function ()
print("This is message2 calling!")
end

Event.Register("onGameStart", function()
message1()
message2()
end)

output:
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4510ms
Info: This is message1 calling!
Info: This is message2 calling!
Warning: skipjack_shield.model: no materials defined!
Info: CreateCollisionMesh for : (skipjack_shield)
...

Events can be registered anytime and anywhere in a file but typically they are grouped at the end of a file/module.

If you need to redirect an event to another function you need to first deregister the event.
local Game = require 'Game'
local Event = require 'Event'

local message1 = function ()
print("This is message1 calling!")
end

local message2 = function ()
print("This is message2 calling!")
end

Event.Register("onGameStart", message1)

print("Now deregistering 'onGameStart message1' and registering 'onGameStart message2'")
print("No warning message will be given below")
Event.Deregister("onGameStart", message1)
Event.Register("onGameStart", message2)
print("See!?")

output:
...
Info: Loading [00%]: Sound::Init took 10.81ms
Info: Loading [08%]: Lua::InitModules() started
Info: Now deregistering 'onGameStart message1' and registering 'onGameStart message2'
Info: No warning message will be given below
Info: See!?
Info: Loading [08%]: Lua::InitModules() took 99.92ms
Info: Loading [17%]: GalaxyGenerator::Init() started
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4787ms
Info: This is message2 calling!
Warning: storeria_shield.model: no materials defined!
Info: CreateCollisionMesh for : (storeria_shield)
...

Interacting with the game: Event-based programming

2026-06-08T12:00:03Z

Zonkmachine: /* More events */ fixup

__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 appears. 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/#LuaClass:Event 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. Let's see if there is an event that better suits our purpose. ''' '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 or when we start a new game, docked at a starport. Now the script works just fine and will launch the message the next time you land or dock with a space station.
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/landing, you may see the greeting posted more than once. This is because the same function is triggered for all ships in the vicinity, not only the player's. The Pioneer universe is populated by ships and characters and they follow pretty much the same rules as the player. To fix this 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

==Setting a timer==
Yet another way to avoid the problem with ''' 'onGameStart' ''' missing your function initially is to place a [https://codedoc.pioneerspacesim.net/#CClass:Timer Timer] to delay the event for a short while. Just a second or so to allow the game to load completely. CallAt takes two arguments, the time of action and a function to be carried out. Example form the Timer documentation:
Timer:CallAt(Game.time+30, function ()
Comms.Message("Special offer expired, sorry.")
end)

A complete example of the welcome message reworked with a timer. ''' 'Game.time' ''' gives us the game time right now so if we call the timer with ''' 'Game.time + 1' ''' we give it a second to think things through.

local Comms = require 'Comms'
local Game = require 'Game'
local Event = require 'Event'
local Timer = require 'Timer'

local onGameStart = function ()
if not Game.player then return end

Timer:CallAt(Game.time + 1, function ()
Comms.Message ('Welcome to Pioneer!')
end)
end

Event.Register("onGameStart", onGameStart)

==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')

==More events==

An event can be registered only once per file. If you need more than one function called by the same event you must wrap them in a function.

Example from '''[https://github.com/pioneerspacesim/pioneer/blob/6111dad3f0b14d64df844511bf3c92b9e583ec76/data/modules/MusicPlayer.lua#L131-L138 /data/modules/MusicPlayer.lua]''':
Event.Register("onGameStart", function ()
MusicPlayer.rebuildSongList()
if Game.player:GetDockedWith() and music["docked"] then
MusicPlayer.playRandomSongFromCategory("docked")
else)
playAmbient()
end
end)

If you register an event more than once in the same file only the last instance will be registered and you will see a log warning on the command line and in output.txt.

Example:
Event.Register("onGameStart", function ()
print("Only the first instance of onGameStart() will be registered")
end)

Event.Register("onGameStart", function ()
print("Only the last instance of onGameStart() will be registered")
end)

Output. Warning and message:
...
Info: Loading [00%]: Sound::Init took 11.47ms
Info: Loading [08%]: Lua::InitModules() started
Warning: Module modules.test_1 overwriting event callback function: 0x57d5ed8b5d50
Info: Loading [08%]: Lua::InitModules() took 84.46ms
Info: Loading [17%]: GalaxyGenerator::Init() started
Info: Creating new galaxy generator 'legacy' version
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4609ms
Info: Only the last instance of onGameStart() will be registered
Warning: lodos_shield.model: no materials defined!
Info: CreateCollisionMesh for : (lodos_shield)
...

Use instead:
local message1 = function ()
print("This is message1 calling!")
end

local message2 = function ()
print("This is message2 calling!")
end

Event.Register("onGameStart", function()
message1()
message2()
end)

output:
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4510ms
Info: This is message1 calling!
Info: This is message2 calling!
Warning: skipjack_shield.model: no materials defined!
Info: CreateCollisionMesh for : (skipjack_shield)
...

Events can be registered anytime and anywhere in a file but typically they are grouped at the end of a file/module.

If you need to redirect an event to another function you need to first deregister the event.
local Game = require 'Game'
local Event = require 'Event'

local message1 = function ()
print("This is message1 calling!")
end

local message2 = function ()
print("This is message2 calling!")
end

Event.Register("onGameStart", message1)

print("Now deregistering 'onGameStart message1' and registering 'onGameStart message2'")
print("No warning message will be given below")
Event.Deregister("onGameStart", message1)
Event.Register("onGameStart", message2)
print("See!?")

output:
...
Info: Loading [00%]: Sound::Init took 10.81ms
Info: Loading [08%]: Lua::InitModules() started
Info: Now deregistering 'onGameStart message1' and registering 'onGameStart message2'
Info: No warning message will be given below
Info: See!?
Info: Loading [08%]: Lua::InitModules() took 99.92ms
Info: Loading [17%]: GalaxyGenerator::Init() started
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4787ms
Info: This is message2 calling!
Warning: storeria_shield.model: no materials defined!
Info: CreateCollisionMesh for : (storeria_shield)
...

Interacting with the game: Event-based programming

2026-06-08T11:54:21Z

Zonkmachine: More events

__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 appears. 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/#LuaClass:Event 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. Let's see if there is an event that better suits our purpose. ''' '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 or when we start a new game, docked at a starport. Now the script works just fine and will launch the message the next time you land or dock with a space station.
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/landing, you may see the greeting posted more than once. This is because the same function is triggered for all ships in the vicinity, not only the player's. The Pioneer universe is populated by ships and characters and they follow pretty much the same rules as the player. To fix this 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

==Setting a timer==
Yet another way to avoid the problem with ''' 'onGameStart' ''' missing your function initially is to place a [https://codedoc.pioneerspacesim.net/#CClass:Timer Timer] to delay the event for a short while. Just a second or so to allow the game to load completely. CallAt takes two arguments, the time of action and a function to be carried out. Example form the Timer documentation:
Timer:CallAt(Game.time+30, function ()
Comms.Message("Special offer expired, sorry.")
end)

A complete example of the welcome message reworked with a timer. ''' 'Game.time' ''' gives us the game time right now so if we call the timer with ''' 'Game.time + 1' ''' we give it a second to think things through.

local Comms = require 'Comms'
local Game = require 'Game'
local Event = require 'Event'
local Timer = require 'Timer'

local onGameStart = function ()
if not Game.player then return end

Timer:CallAt(Game.time + 1, function ()
Comms.Message ('Welcome to Pioneer!')
end)
end

Event.Register("onGameStart", onGameStart)

==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')

==More events==

An event can be registered only once per file. If you need more than one function called by the same event you must wrap them in a function.

Example from '''[https://github.com/pioneerspacesim/pioneer/blob/6111dad3f0b14d64df844511bf3c92b9e583ec76/data/modules/MusicPlayer.lua#L131-L138 /data/modules/MusicPlayer.lua]''':
Event.Register("onGameStart", function ()
MusicPlayer.rebuildSongList()
if Game.player:GetDockedWith() and music["docked"] then
MusicPlayer.playRandomSongFromCategory("docked")
else)
playAmbient()
end
end)

If you register an event more than once in the same file only the last instance will be registered and you will see a log warning on the command line and in output.txt.

Example:
Event.Register("onGameStart", function ()
print("Only the first instance of onGameStart() will be registered")
end)

Event.Register("onGameStart", function ()
print("Only the last instance of onGameStart() will be registered")
end)

Output. Warning and message:
...
Info: Loading [00%]: Sound::Init took 11.47ms
Info: Loading [08%]: Lua::InitModules() started
Warning: Module modules.test_1 overwriting event callback function: 0x57d5ed8b5d50
Info: Loading [08%]: Lua::InitModules() took 84.46ms
Info: Loading [17%]: GalaxyGenerator::Init() started
Info: Creating new galaxy generator 'legacy' version
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4609ms
Info: Only the last instance of onGameStart() will be registered
Warning: lodos_shield.model: no materials defined!
Info: CreateCollisionMesh for : (lodos_shield)
...

Use instead:
local message1 = function ()
print("This is message1 calling!")
end

local message2 = function ()
print("This is message2 calling!")
end

Event.Register("onGameStart", function()
message1()
message2()
end)

output:
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4510ms
Info: This is message1 calling!
Info: This is message2 calling!
Warning: skipjack_shield.model: no materials defined!
Info: CreateCollisionMesh for : (skipjack_shield)
...

Events can be registered anytime and anywhere in a file but typically they are grouped at the end of a file/module.

If you need to redirect an event to another function you need to first deregister the event.
local Game = require 'Game'
local Event = require 'Event'

local message1 = function ()
print("This is message1 calling!")
end

local message2 = function ()
print("This is message2 calling!")
end

Event.Register("onGameStart", message1)

print("Now deregistering 'onGameStart message1' and registering 'onGameStart message2.")
print("No warning message will be given below")
Event.Deregister("onGameStart", message1)
Event.Register("onGameStart", message2)
print("See!?")

output:
...
Info: Loading [00%]: Sound::Init took 10.81ms
Info: Loading [08%]: Lua::InitModules() started
Info: Now deregistering 'onGameStart message1' and registering 'onGameStart message2.
Info: No warning message will be given below
Info: See!?
Info: Loading [08%]: Lua::InitModules() took 99.92ms
Info: Loading [17%]: GalaxyGenerator::Init() started
...
Info: building follow-on industry distillery after surface_aquaponics at station Pluto Research Base
Info: PROFILE | Economy.PrecacheSystem("Sol") took 2.4787ms
Info: This is message2 calling!
Warning: storeria_shield.model: no materials defined!
Info: CreateCollisionMesh for : (storeria_shield)
...

Strings and translation

2026-05-28T21:14:37Z

Zonkmachine: /* Lua Standard Library - String manipulation */ string.scase

==Internationalization==
Recommended reading: [https://dev.pioneerspacesim.net/contribute/translations Pioneer translators wikipage]

It is important that scripters are familiar with the translation system. In the previous example '''hello_world.lua''' used strings directly like <code>print("Hello, World!")</code>. In order for Pioneer to be translated we instead use tokens and calls on the <code>'Lang'</code> module to substitute it for the string in the chosen language. The translated strings are stored together with their 'key' in json format, one language per file that are kept in the [https://github.com/pioneerspacesim/pioneer/tree/master/data/lang data/lang/] directory. If the script file in which they are used is from the '''data/modules''' directory they have names starting with '''module-''' and ending with the name of the module written in one word, in small caps, and with the '.lua' ending omitted. The final translation from English to other languages is done on Pioneer's project page at [https://www.transifex.com/pioneer/pioneer/ Transifex], a dedicated online translation tool. The translations are committed to the pioneer/master branch on GitHub by a bot and are not to be edited manually apart from the '''en.json''' files.

==Translating strings==

Below is a minimal example with one string added into the translation system. It takes two files, one in '''data/modules''' and one in '''data/lang/module-hello'''. The print statement isn't wrapped in a function so it will be executed when the '''hello.lua''' is being parsed on startup. You will have to scroll through the command-line history to find it interleaved with the other output.

'''data/modules/hello.lua'''.
local Lang = require 'Lang'
local l = Lang.GetResource("module-hello")

print(l.HELLO)

And a corresponding file containing the translated string, and a description field shown to the translator, giving the context.

'''data/lang/module-hello/en.json'''
{
"HELLO": {
"description": "A classic message.",
"message": "Hello World!"
}
}

In short, any script containing strings that needs translation needs to load the <code>'Lang'</code> module:
local Lang = require 'Lang'
Then load the translation resource they want to use in their module, often just named <code>'l'</code> as in:
local l = Lang.GetResource("module-hello")
You may load more than one translation resource in your script but they will need to have unique names:
local lh = Lang.GetResource("module-hello")
local lg = Lang.GetResource("module-goodbye")

==Working with strings==

Recommended chapters from [https://www.lua.org/pil/contents.html Programming in Lua (first edition) ] 
[https://www.lua.org/pil/2.4.html 2.4 – Strings] 
[https://www.lua.org/pil/3.4.html 3.4 – Concatenation] 
[https://www.lua.org/pil/20.html 20 – The String Library] 
And from the [https://www.lua.org/manual/5.2/ Lua 5.2 Reference Manual] 
[https://www.lua.org/manual/5.2/manual.html#6.4 6.4 – String Manipulation] 

===Concatenation===

Instead of serving ready made sentences we can stitch them together with the Lua string concatenation operator <code>..</code>. The following codelines result in the same output.
print("Hello Clarice!")
print("Hello" .. " " .. "Clarice!")

This could be created by the more generic:

local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local NameGen = require 'NameGen'

local GREETING = 'Hello'
local FBIAGENT = NameGen.Surname()

local onShipDocked = function (ship)
if ship == Game.player then
Comms.Message(GREETING .. ' ' .. FBIAGENT .. '!')
end
end

Event.Register("onShipDocked", onShipDocked)

The <code>..</code> operator is used all over the codebase. Try a search for its occurrence. On Linux I would do <code>grep -R " \.\. " data/modules/ data/libs/ data/pigui/</code> and that will render a lot of output.

===Token concatenation===

You concatenate strings but you also concatenate the string tokens. In the example below from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/modules/DonateToCranks/DonateToCranks.lua#L14-L21 DonateToCranks.lua]''' we see the table <code>flavours</code> being populated by strings from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/lang/module-donatetocranks/en.json data/lang/module-donatetocranks/en.lua]'''

local flavours = {}
for i = 0,9 do
table.insert(flavours, {
title = l["FLAVOUR_" .. i .. "_ADTITLE"],
desc = l["FLAVOUR_" .. i .. "_DESC"],
message = l["FLAVOUR_" .. i .. "_MESSAGE"],
})
end

The first string in the table is given the value of <code>l[FLAVOUR_" .. i .. "_ADTITLE]</code> is concatenated to <code>l[FLAVOUR_0_ADTITLE]</code> which corresponds to the first string in the language module which is seen below.

{
"FLAVOUR_0_ADTITLE": {
"description": "",
"message": "DONATE!"
},
"FLAVOUR_0_DESC": {
"description": "",
"message": "The Church of The Celestial Flying Spaghetti Monster needs YOUR money to spread the word of god."
},
"FLAVOUR_0_MESSAGE": {
"description": "",
"message": "Please select an amount to donate to the Church of the Celestial Flying Spaghetti Monster."
},
"FLAVOUR_1_ADTITLE": {
"description": "",
"message": "DONATE"
},

...

===Lua Standard Library - String manipulation===

I would start to search the '''data/''' register for ''' 'string' '''. to get a feeling for how it's used. Again on Linux i would use the 'grep' command. <code>grep -R "string\." data/</code>. You will see that the two most frequently used functions is <code>string.format()</code>, which is a part of the lua standard library, and <code>string.interp()</code>, which is a Pioneer global function residing in '''data/libs/autoload.lua''', and is described in the next paragraph about [https://wiki.pioneerspacesim.net/wiki/Strings_and_translation#String_variables String variables].

Some examples from the Lua standard library:
Comms.Message(string.lower('wHaT cAsE sHoULd I usE?'))

We also have extended the string class with our own Pioneer mods. '''string.scase''' Will capitalize the first letter in every sentence in a string. As we will see later a string can contain variables. If a string variable is both a word and is used anywhere in a sentence, then we need to be able to capitalize it on the fly if it is used as the first word.
string.scase("a sentence. another sentence.")
Would return: "A sentence. Another sentence."
Comms.Message(string.scase(string.lower('wHaT cAsE sHoULd I usE? AnY casE yoU waNT!')))

Back to the standard library. Maybe not the most easy function to fit into Pioneer, but it's there:
Comms.Message('Today is opposite day!')
Comms.Message(string.reverse('No, today is not opposite day!'))

A more complex example from '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/pigui/modules/hyperjump-planner.lua#L141 data/pigui/modules/hyperjump-planner.lua]''' 
Here <code>string.format("%.2f", distance)</code> is used to set the number of decimals in the jump to two. The units are translatable but the system name isn't (jump_sys.name). '''lc''' is used as the short name for the '''core''' translation resource.

textLine = jumpIndex ..": ".. jump_sys.name .. " (" .. string.format("%.2f", distance) .. lc.UNIT_LY .. " - " .. fuel .. lc.UNIT_TONNES..")"

Here is what the final formatted text looks like (right side, two selected jump routes): 
[[File:hyperjumpplanner.png]]

===PiGUI - Format===

Pioneer has it's own set of formatting functions accessible through PiGUI, our UI. Some of it is realised on the C++ side and described in codedoc [https://codedoc.pioneerspacesim.net/#CClass:Format here]. Most of the functions, however, are strictly Lua and reside in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/libs/text.lua#L146-L385 data/pigui/libs/text.lua]. You access the functions with '''require''' and make sure that '''PiGUI''' is in the scope.

local ui = require 'pigui'
local Format = require 'Format'

Here is an example from the System overview. The table to the right is relying heavily on the Format functions.
[[File:Systemoverview.png]]

The code responsible for the table is here in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/modules/system-view-ui.lua#L811-L840 data/pigui/modules/system-view-ui.lua] with an excerpt showed below. The examples below take 1 or two arguments and the lines ending with 'or nil' is what makes the System overview info window omit values that don't apply to the selected system body.

...
{ name = lc.ESCAPE_VELOCITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Speed(body.escapeVelocity , true) or nil },
{ name = lc.MEAN_DENSITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Mass(body.meanDensity).."/m³" or nil },
{ name = lc.ORBITAL_PERIOD, icon = icons.body_orbit_period,
value = op and op > 0 and ui.Format.Duration(op, 2) or nil },
{ name = lc.DAY_LENGTH, icon = icons.body_day_length,
value = rp > 0 and ui.Format.Duration(rp, 2) or nil },
...

==String variables==

When you want a string to present variable data such as numbers and names you use the <code>interp()</code> function. <code>interp()</code> accepts a table '{}' and the corresponding keys are then embedded in the translated strings enclosed by curly brackets '{}'.

Using ''''module-stationrefuelling'''' we can do:
print(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = 'JFK', fee = 50}))

Example from the actual StationRefuelling module:

'''data/modules/StationRefuelling/'''
Comms.Message(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = station.label,fee = Format.Money(fee)}))

'''data/lang/module-stationrefuelling/en.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Welcome to {station}. Your landing fee of {fee} has been deducted."
}

'''data/lang/module-stationrefuelling/it.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Benvenuti a {station}. Vi è stata dedotta una tassa di atterraggio di {fee}."
}

==Mission flavours==

A script can define a mission and then place many instances of it onto many bulletin boards. A script that introduces many instances in the game should provide some variety; it would harm immersion if, for examle, all delivery missions were worded identically. The easiest way to achieve multiple versions, or "flavours", is by just making a number of different strings and then choosing between them with a simple random function. This is how the [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L18:L48 deny] and [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L282:L320 pirate taunt] messages are done in the DeliverPackage module.

'''data/modules/DeliverPackage/DeliverPackage.lua'''
local num_deny = 8

...

if not qualified then
local introtext = l["DENY_"..Engine.rand:Integer(1,num_deny)-1]
form:SetMessage(introtext)
return
end

'''data/lang/module-deliverpackage/en.json'''
"DENY_0": {
"description": "",
"message": "I'm sorry, but I don't think I can trust you with this delivery."
},
"DENY_1": {
"description": "",
"message": "Come back when you have some qualifications."

...

"DENY_7": {
"description": "",
"message": "I'm not willing to risk this delivery on someone without any qualifications like you."
You don't have to use a string variable that has been passed to the translation file. The pirate taunts, for example, have access to the clients name and the destination of the package but this information is only used in some of the strings.

"PIRATE_TAUNTS_7": {
"description": "",
"message": "That package isn't going to reach its destination today."
},
"PIRATE_TAUNTS_8": {
"description": "",
"message": "You're not getting to {location} today!"
Another way to add variation is to have a table of strings that are variations of a theme, a flavour. In the example below, again from the DeliverPackage module, you have two of the lines from '''FLAVOUR_0''' AND '''FLAVOUR_1''' compared.
"FLAVOUR_0_ADTEXT": {
"description": "",
"message": "GOING TO the {system} system? Money paid for delivery of a small package."
},
"FLAVOUR_0_FAILUREMSG": {
"description": "",
"message": "Unacceptable! You took forever over that delivery. I'm not willing to pay you."

...

"FLAVOUR_1_ADTEXT": {
"description": "",
"message": "WANTED. Delivery of a package to the {system} system."
},
"FLAVOUR_1_FAILUREMSG": {
"description": "",
"message": "I'm frustrated by the late delivery of my package, and I refuse to pay you."
There are ten flavours in DeliverPackage of five strings each, each forming a short story line. They are static in that you only see lines from within the same flavour. You know what lines will follow if you accept the mission and after a short time of playing you know this already from seeing the ad if delivering things is your forte. It's hard to share strings in between the flavours as they would need to be much more similar. It's a trade off. You could build a very complex interaction with the customers but in the end it needs to be translatable.

Generally, the more specific the text is, the stranger it will appear to see it multiple times in the game. For example, consider the following two examples:
- "Contract is to move X tonnes of Y to system Z"
- "My uncle's cat got sick, so I can't travel right now, so I need you to take my contract for me, to move X tonnes of Y to my home system Z"
The former might not need any flavours, as it's unpersonal, and very general. Seeing the second string multiple times does break immersion. Solution is to not show it often, either by making the mission rare / single occurance (no script to date does this) or have many flavours, making probability of the same twice low.

==Trailing commas==

The two most common text based files you will come across when you work with module scripting are Lua and JSON. While JSON is strictly used for information, Lua is used most as a scripting language but in some instances it's used for data. See for instance '''data/modules/CargoRun/CargoTypes.lua'''. It is basically just tables of data. In any way, we have used both in this chapter and it's probably a good time to address a
difference between the two that could otherwise create confusion. Trailing commas after the last element in a table. The short version is: In Lua, you can use trailing commas on the last element in a table. In JSON you cannot.

===Lua===

Here are the last four ladies in the Hawaiian culture file. '''data/culture/haw.lua'''. These are the files we stitch together characters/clients names from. As you see, the last element, ''''Wanaao'''' has a trailing comma after her. This is perfectly fine.

'Pohaku',
'Oke',
'Wailani',
'Wanaao', -- Lua. A comma here is fine!
}

===JSON===

Here we see the last two elements in the '''data/lang/core/en.json'''. It keeps some of the strings used in the game and every language has it's own version of it. Trailing commas in JSON is explicitly forbidden in the official description of the file format. There are derivative interpreters that are relaxed and allow trailing commas but this is not the case with the one used in Pioneer.

},
"ZOOM_IN": {
"description": "",
"message": "Zoom in"
},
"ZOOM_OUT": {
"description": "",
"message": "Zoom out"
} -- JSON. A comma here is NOT fine!
}

The fastest way to find out what could happen is to simply just put a comma in that place and start Pioneer. Open the '''System oveview''' and click on a planet and look at the data presented in the pop up window. There is now a lot of '''[NO_JSON]''' data presented in there.

"message": "Zoom out"
}, -- ;o -onoh!
}

Also, another difference between the file formats is that the comment I added above in the Lua file is a real Lua comment and would work and be ignored by the language. The ;o emoji comment in the JSON file wouldn't work. JSON doesn't have comments in it. You would have to assign a separate element to be used as a comment like the translation file above which has elements beginning with '''"description":'''.

Pioneer Wiki

2026-04-13T19:41:22Z

Zonkmachine: Fix link

Pioneer is a space adventure game set in the Milkyway galaxy at the turn of the 33rd century. The game is open-ended, and you are free to explore the millions of star systems in the game. You can land on planets, slingshot past gas giants, and burn yourself to a crisp flying between binary star systems.

If you are new to pioneer you may want to know [[How_to_start|how to start]].

*[https://pioneerspacesim.net/page/download/ Download Pioneer] for Windows and Linux

Please make this wiki nice. Add stuff about mods, dev, whatever. Be awesome! [[Getting_started|How to get started]].

----

{| width="100%"
|-
| style="background:#bbffbb; border:2px solid #99ee99; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Community ===

*[https://pioneerspacesim.net/ Pioneer Space Sim Homepage]
*[https://github.com/pioneerspacesim/pioneer/ Main Github repository]
*[https://spacesimcentral.com/viewforum.php?f=49 Community forum]
*[https://forum.pioneerspacesim.net/ Developer forum]
*[https://www.reddit.com/r/pioneerspacesim Pioneer Space Sim on Reddit]
*[https://pioneerspacesim.itch.io/pioneer Pioneer Space Sim on itch]
*[[IRC|Pioneer Space Sim on IRC, Channel: #pioneer, network: libera.chat]] (where devs hang out)
*[https://twitter.com/pioneerspacesim @pioneerspacesim] on Twitter
*[https://mstdn.games/@pioneerspacesim @pioneerspacesim] on Mastodon at [https://mstdn.games mstdn.games]
*[https://www.youtube.com/channel/UCbFD5Oxc1C9zxqnF4OitGjQ Pioneer Space Simulator] on Youtube
*[https://discord.com/invite/RQQe3A7 discord]

----

*[[Manual|Basic Manual]]
*[[Flight_UI|Flight UI]]
*[[Keyboard_and_mouse_controls|Keyboard and mouse controls]]
*[[Tutorials|Tutorials]] (Outdated and WIP)
*[[Mission_Types_and_BBS|Mission Types and BBS]]
*[[Settings_Menu|Settings Menu]]
*[[FAQ|FAQ]]
*[[Media_Coverage|Media Coverage]]

| style="background:#fff9b1; border:2px solid #f0fe66; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |

=== The Pioneer Universe ===

*[[Pioneer_Universe|Pioneer Universe]]
*[[:Category:Ships| Ships]] (work in progress)
*[[:Category:Manufacturers| Manufacturers]] (work in progress)
*[[Places_of_interest|Places of interest]]
*[[Ship_Equipment|Ship Equipment]] (work in progress)
*[[Custom Star Systems|Custom Star Systems]] (Work in progress)

|}

 

{| width="100%"
|-
| style="background:#f0f0ff; border:2px solid #c6c9ff; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |

=== Content Creation ===

*[[Mods|Mods]]
*[[Scripting_and_Mission_Creation|Scripting and Mission Creation]]
*[[Custom_Systems|Custom Systems]]
*[[Design_and_Concept_art|Design and Concept art]]
*[[Modeling,_Texturing,_Graphics_Design|Modeling, Texturing, Graphics Design]]
*[[Music_and_Sound|Music and Sound]]
*[[Translations|Translations]]
*[[Licensing|Licensing]]

| style="background:#fff3e3; border:2px solid #ffc9c9; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Development ===

*[[Design_Scope|Game Scope]]
*[[How_you_can_contribute|How you can contribute]]
*[[Getting_Started_with_Development|Getting Started with Development]]
**[[How_to_communicate|How to communicate]]
**[[Using_git_and_GitHub|Using git and GitHub]]
**[[Coding Conventions]]
**[[Development_team|Development team]]
**[[Engine_Overview|Engine internals overview]]
**[[Development_Tools| Development tools]]
*[[Development_Model|Development Model]]
*[[Design_Workflow|Design and Project Management Workflow]]
*[https://github.com/pioneerspacesim/pioneer/issues Issue tracker]
*[[Roadmap|Roadmap]]
*[[Making a release]]

|}

Pioneer is brought to you by a flock of [https://github.com/pioneerspacesim/pioneer/blob/master/AUTHORS.txt opensource beardy-weirdies], and is [http://www.gnu.org/licenses/gpl.html Free Software]

__NOTOC__

Surviving a reload

2025-11-15T19:38:30Z

Zonkmachine: fixup - layout

When a game is saved, a script is responsible for informing Pioneer exactly which of its data needs to be saved. If nothing is specified, nothing will be saved at all. Similarly, after a game is loaded, a script is responsible for restoring all of its saved data; re-creating bulletin board adverts, the player's mission details, and any run-time state.

Here is a simple form. If a new game is started, you will see this on every bulletin board that you visit:

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()
form:SetMessage("Hello!")
end

local onCreateBB = function (station)
station:AddAdvert('Click here for a greeting', onChat)
end

Event.Register("onCreateBB", onCreateBB)

However, if you save the game, then reload, you will not see it on any bulletin board that had been created in the current system before you saved. onCreateBB will be triggered for any subsequently created bulletin boards, but not for those that already existed. It isn't appropriate to have scripts create new adverts just because a player has loaded; instead, it's the responsibility of the script to tell Pioneer what to save, and to use those saved data to restore all adverts after the game is loaded. The same goes for player missions, and any working data that the script is using.

There are two things we need to do to achieve all of this:

* We need to track everything that the script is doing.
* We need to be able to pack this away for saving, and bring it back after loading.

==Tracking everything that we are doing==

Any local table that is declared in file scope is visible to the entire script, without affecting any other scripts. Essential data should be kept in such tables.

==Tracking adverts==
It's important to be able to re-create an advert, so part of the process of making one should be storing that information. Your script will need to make a note of in which station the advert was placed, which flavour was used (if you have flavours), the face data that was used on the form and any unique information that was used, such as specific mission details, reward, etc. The simplest way to keep all of this together is in a table, gathering up the variables by name into keys of the same name. It could look something like this:

local advert = {
station = station,
flavour = flavour, -- This will be a table
client = client, -- This will be a table (a character)
target = target,
destination = destination,
reward = reward,
}

In the case of the 'greeting', the first example above, we would just have to save the message ('Hello!'), Advert string ('Click here for a greeting') and the station. It's a very simple example but there are real modules that aren't much more complex than that.

Remember, the <code>AddAdvert()</code> method takes three arguments: The advert text, the <code>onChat</code> function and the <code>onDelete</code> function. It also returns a unique number, which lends itself nicely to storing the information away. That same unique number is passed to the onChat function, allowing onChat to check that stored information.

The <code>onDelete()</code> function (again, we call it that by convention only) also accepts this reference as its argument, and is called whenever an advert is destroyed, whether that destruction be explicit (<code>RemoveAdvert()</code>) or implicit (the player hyperspaces away).

So, we can track adverts that have been created, and stop tracking any that have gone away. We'll do that using the reference returned by <code>AddAdvert()</code> as the key to a file-scoped local table:

local flavours = {}
local ads = {}

local onChat = function (form, ref, option)
form:Clear()
form:SetFace(ads[ref].character)
form:SetMessage(ads[ref].flavour.title)
end

local onDelete = function (ref)
ads[ref] = nil
end

local onCreateBB = function (station)
local flavour = flavours[Engine.rand:Integer(1, #flavours)]
ref = station:AddAdvert(flavour.title, onChat, onDelete)
ads[ref] = {
station = station,
flavour = flavour,
character = Character.new()
}
end

Event.Register("onCreateBB", onCreateBB)

==Tracking missions==

This is less of a challenge. Missions created with <code>Mission.New()</code> are stored in the <code>PersistentCharacters.player.missions</code> table. You also need to register them locally in your script. When <code>Mission.New()</code> is called, it returns a reference to the mission. That reference can be stored in a file-local table that can be iterated through when we need to access a mission. We can wrap these functions up:

local missions = {}

local addMission = function(mission)
table.insert(missions,Mission.New(mission))
end

local removeMission = function(mref)
local ref
for i,v in pairs(missions) do
if v == mission then
ref = i
break
end
end
mission:Remove()
missions[ref] = nil
end

Now, instead of directly calling <code>Mission.Add()</code> and <code>mission:Remove()</code>, we call our local functions, <code>addMission()</code> and <code>removeMission()</code>. They will send their argument on to the instance in '''Mission.lua''', and also store or remove the mission ref in the missions table. There is now a record of which missions belong to this script. <code>addMission()</code> and <code>removeMission()</code> in the example above is taken from '''SearchRescue.lua'''. Look how <code>removeMission()</code> is used in the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/SearchRescue/SearchRescue.lua#L241-L252 Search and Rescue module]'''.

==Serializing: Packing away for saving and loading==

The <code>Serializer</code> object provides one method: <code>Register</code>. It takes three arguments. The first is a name; a simple string with which to uniquely identify this script. It's probably sensible to re-use the name that was used for the <code>Translate</code> object's flavour methods. The second and third arguments are both names of functions that each returns a single table. The second argument is your '''serializer''' function and the third is your '''unserializer''' function. By convention, we name these <code>serialize</code> and <code>unserialize</code>.

<code>serialize</code> must return a table, and this table must contain everything that you need to store to get your script working after a reload. It will be run when the player saves the game. The table can contain any pure-lua types, and SystemPath, Body and SceneGraph.ModelSkin core types, anything else will explode, like a ShipDef/EquipDef or a StarSystem.

<code>unserialize</code> accepts a table, and does something with it. It will be run by the serializer after the game is loaded, immediately before the <code>onGameStart</code> event is triggered. It is passed the data that serialize returned at save time.

The most common way to deal with this is as follows (and this is very cut down):

local table_stuff_this_script_uses = {}
local loaded_data

-- The rest of the script goes here!

local onGameStart
if loaded_data then
for k,v in loaded_data.table_stuff_this_script_uses do
table_stuff_this_script_uses[k] = v
end
loaded_data = nil
else
-- New game; do other stuff here perhaps
end
end

local serialize = function ()
return {table_stuff_this_script_uses = table_stuff_this_script_uses}
end

local unserialize = function (data)
loaded_data = data
end

Event.Register("onGameStart", onGameStart)
Serializer:Register("TestModule", serialize, unserialize)

==Complete module==

Now we can finally start to put together complete modules that will save, reload, and behave consistently throughout the game. Many of the modules in Pioneer don't register a mission. As an example of this, see '''BreakdownServicing''', '''DonateToCranks''', and '''CrewContracts'''. In the same spirit, let's complete the first example above, 'Click here for a greeting', and make it survive a reload.

<pre>
local Event = require 'Event'
local Serializer = require 'Serializer'

local ads = {}

local onChat = function (form, ref, option)
local ad = ads[ref]
form:Clear()
form:SetMessage(ad.bodytext)
end

local onDelete = function (ref)
ads[ref] = nil
end

-- when we enter a system the BBS is created and this function is called
local onCreateBB = function (station)

local ad = {
headline = 'Click here for a greeting',
bodytext = "Hello!",
station = station
}

-- create one per BBS
local ref = station:AddAdvert({
description = ad.headline,
onChat = onChat,
onDelete = onDelete}
)
ads[ref] = ad
end

local loaded_data

local onGameStart = function ()
ads = {}

if not loaded_data or not loaded_data.ads then return end

for k,ad in pairs(loaded_data.ads or {}) do
local ref = ad.station:AddAdvert({
description = ad.headline,
onChat = onChat,
onDelete = onDelete})
ads[ref] = ad
end

loaded_data = nil
end

local serialize = function ()
return { ads = ads }
end

local unserialize = function (data)
loaded_data = data
end

Event.Register("onCreateBB", onCreateBB)
Event.Register("onGameStart", onGameStart)

Serializer:Register("message", serialize, unserialize)
</pre>

The '''Advice''' module generously gave up parts of its code to complete this script.

Although the example is functional, it has been coded with brevity alone in mind. I would not recommend using this as the basis for a mission without at least completely rewriting <code>onChat()</code>, and possibly tidying up the temporary loop variable names.

==Don't serialize strings==

When we add the strings literally to the ad as we did in the example above, they will be serialized and saved on game end. Considering this is happening on all active stations, this will waste disk space.

local ad = {
headline = 'Click here for a greeting',
bodytext = 'Hello!',
station = station
}

What we want to do instead is save the information to recreate the same strings. If for instance we have a set of flavours that are selected with a random number, then generate that number and save it in a variable. The ad example above can then be rewritten as such. We only need the station and the flavour number to recreate the ad.

local ad = {
station = station,
n = n
}

The working example in the paragraph above can be updated in this way. When you have the translated strings in a separate module you would start the script by pulling in the strings to the script in an array or set of arrays. In the following example we instead add the strings to an array directly but it shows the general idea.

<pre>
local Engine = require 'Engine'
local Event = require 'Event'
local Game = require 'Game'
local Rand = require 'Rand'
local Serializer = require 'Serializer'

local ads = {}

local flavours = {
{flavour = 'flavour 1', title = 'title 1', text = 'text 1'},
{flavour = 'flavour 2', title = 'title 2', text = 'text 2'},
{flavour = 'flavour 3', title = 'title 3', text = 'text 3'}
}
local onChat = function (form, ref, option)
local ad = ads[ref]
form:Clear()
form:SetMessage(flavours[ad.n].text)
end

local onDelete = function (ref)
ads[ref] = nil
end

-- when we enter a system the BBS is created and this function is called
local onCreateBB = function (station)

local rand = Rand.New(Game.time)
local n = rand:Integer(1, #flavours)

local ad = {
station = station,
n = n
}

-- create one per BBS
local ref = station:AddAdvert({
title = flavours[n].title,
description = flavours[n].flavour,
onChat = onChat,
onDelete = onDelete}
)
ads[ref] = ad
end

local loaded_data

local onGameStart = function ()
ads = {}

if not loaded_data or not loaded_data.ads then return end

for k,ad in pairs(loaded_data.ads or {}) do
local ref = ad.station:AddAdvert({
title = flavours[ad.n].title,
description = flavours[ad.n].flavour,
onChat = onChat,
onDelete = onDelete})
ads[ref] = ad
end

loaded_data = nil
end

local serialize = function ()
return { ads = ads }
end

local unserialize = function (data)
loaded_data = data
end

Event.Register("onCreateBB", onCreateBB)
Event.Register("onGameStart", onGameStart)

Serializer:Register("message", serialize, unserialize)
</pre>

The codedoc is complete and accurate, and the scripts provided with Pioneer are good examples themselves. The API is extensive, but if you find that there are additional things you would like to be able to do, or information you would like from Pioneer, the dev team are willing to extend the API to accommodate script writers. Simply create a new issue on the [https://github.com/pioneerspacesim/pioneer/issues Github issue tracker].

Help is also always available on the [https://forum.pioneerspacesim.net/ Pioneer dev forum], and many of the dev team can be found on [[IRC]] at all hours.

Surviving a reload

2025-11-11T18:44:59Z

Zonkmachine: /* Serializing: Packing away for saving and loading */ Improve language

Missions and the mission list

2025-11-09T22:34:34Z

Zonkmachine: /* The player's mission list */ fixup

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking under the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

We don't recommend using <code>Game.player.frameBody.path</code> here. We're only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.
local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function (ship, station)
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

Event.Register("onGameStart", onGameStart)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Taxi', l.TAXI)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Taxi', l.TAXI, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

Let's fixup the earlier example with it's own mission type and a working '''buildMissionDescription'''.

local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function ()
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

Mission.RegisterType('Test', 'Test', buildMissionDescription)
Event.Register("onGameStart", onGameStart)

[[File:Minimaldescription.png|1024px]]

That's basically it. Here follows a description of the elements you can add to '''buildMissionDescription'''. Try and expand our latest script on you own.

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.

User:Zonkmachine

2025-11-09T20:57:41Z

Zonkmachine: dead links

Links to wiki test pages and other WIP stuff.

Surviving a reload
*[[Surviving_a_reload_WIP|Surviving a reload WIP]]

Scripting Tutorial TODO:
*[[Interacting_with_the_player:_BBS_forms|BBS forms]]
Update BBS images. ''fixed''.

Also mention that the posts are sorted. ''fixed''

Add some info on multiple BBS ads and updating the BBS over time, '''onUpdateBB'''.

Facegen - facemorph:
*[[Facemorph|Facemorph]]

Facegen - picture cleanup:
*[[Facegen_picture_cleanup|Facegen - picture cleanup]]

More facegen - hair:
*[[Facegen_hair|Facegen - more and hair]]

Code example for [[Missions_and_NPC_Interaction|Missions and NPC Interaction]]:
*[[Missions_and_NPC_Interaction_Code_Example|Missions and NPC Interaction Code Example]]

Snippets for new tutorial:
*[[Useful_functions|Useful functions]]

 
 
'''Sally. At night a stand up commedian in Cydonia. Daytime, selling parts her cousins strip from ships that does not belong to them:''' 
[[File:Passiveaggressive.png]]

User:Zonkmachine

2025-11-09T20:54:27Z

Zonkmachine:

Links to wiki test pages and other WIP stuff.

*[[Buildings_and_other_structures|Buildings and stuff]]

Surviving a reload
*[[Surviving_a_reload_WIP|Surviving a reload WIP]]

Scripting Tutorial TODO:
*[[Interacting_with_the_player:_BBS_forms|BBS forms]]
Update BBS images. ''fixed''.

Also mention that the posts are sorted. ''fixed''

Add some info on multiple BBS ads and updating the BBS over time, '''onUpdateBB'''.

Facegen - facemorph:
*[[Facemorph|Facemorph]]

Facegen - picture cleanup:
*[[Facegen_picture_cleanup|Facegen - picture cleanup]]

More facegen - hair:
*[[Facegen_hair|Facegen - more and hair]]

Code example for [[Missions_and_NPC_Interaction|Missions and NPC Interaction]]:
*[[Missions_and_NPC_Interaction_Code_Example|Missions and NPC Interaction Code Example]]

Snippets for new tutorial:
*[[Useful_functions|Useful functions]]

 
 
'''Sally. At night a stand up commedian in Cydonia. Daytime, selling parts her cousins strip from ships that does not belong to them:''' 
[[File:Passiveaggressive.png]]

Scripting and Mission Creation

2025-11-09T20:36:11Z

Zonkmachine: Fix link

See [http://lua-users.org/wiki/TutorialDirectory Lua Tutorial] to learn basics of lua.

*[[Introduction_to_Mission_Scripting|Introduction to Mission Scripting]]
**[[Interacting_with_the_game:_Event-based_programming|Interacting with the game: Event based programming]]
**[[Strings_and_translation|Strings and translation]]
**[[Interacting_with_the_player:_BBS_forms|Interacting with the player: BBS forms]]
**[[Missions_and_the_mission_list|Missions and the mission list]]
**[[Missions_and_NPC_Interaction|Missions and NPC interaction]]
**[[Surviving_a_reload|Surviving a reload]]
**[[Old_scripting_info|Older pages]]
*[[GUI introduction]]
*[http://codedoc.pioneerspacesim.net Lua API Reference]
*[[Ship_AI|Ship AI]]

Interacting with the player: BBS forms

2025-11-09T20:17:29Z

Zonkmachine: /* Adding options to the form */ fixup

The bulletin board system is currently the only place where real dialogue between a script and the player can take place. Bulletin boards can exist within any <code>SpaceStation</code> in the current system. They are created in a station the first time that a ship is either spawned, or lands, in that station. They continue to exist until the player leaves the system or quits the game. They are not saved in saved games, although a saved game contains information about which ones did exist.

When a bulletin board is created, the <code>onCreateBB</code> event is triggered, and passes the <code>SpaceStation</code> body in which that bulletin board was created. There is an exception to this: The event is not triggered after loading a game for those bulletin boards which, having existed at the time of saving, are re-created. The consequences of this will be covered later (see "[[Surviving a reload]]").

There are two components to any mission's entry on a bulletin board: The advert and the form. The advert is the part that is displayed on the main bulletin board list, along with all the other entries. The form is the part that appears on screen when the player clicks the advert's button.

==The BBS advert==

Adverts are placed onto a BBS by calling the station's <code>AddAdvert()</code> method, once the bulletin board has been created. Depending on the nature of your script, you might want to always place one advert on every station (as seen with the Breakdowns & Servicing script), or you might want to place an arbitrary number of adverts on a given station (as seen with deliveries, or assassinations).

The opportunities to add an advert are presented by two events. <code>onCreateBB</code> is the obvious one; there is also <code>onUpdateBB</code>, which is called for all existing bulletin boards in the current system, approximately once every hour or two. The actual interval is not particularly predictable.

The <code>AddAdvert()</code> method takes three arguments. The first is the text that will appear on the advert. The second is the function that will be called when the player clicks the advert. The third is optional, and is a function that can be called when the advert is deleted for any reason.

<code>AddAdvert()</code> returns a reference number, which can subsequently be used to remove the advert using <code>RemoveAdvert()</code>. It represents the number of times a module has generated an advert on a specific station. If no ads has been removed it will be equal to the number of ads on the station.

It's the job of the scripter to decide how many, if any, adverts to add to a bulletin board when <code>onCreateBB</code> is triggered, and whether to add or remove any when <code>onUpdateBB</code> is triggered. Tests could include the population of the system, the type of starport or the type of planet. In the future, tests will be able to include the government type of the system.

One important thing to bear in mind is that the script cannot query a bulletin board to find out what adverts already exist. Each script must carefully track each advert that it has created if it is to have any control over how long they remain, and to be able to re-create them after a reload.

Here is an example of adding an advert. The effect of clicking the advert is simply to send a message to the player console with the name of the station and the reference number, which is one in this case as we're only generating one advert. Furthermore, the advert is only added if the station is in space. There is no mission here, it is simply to illustrate the mechanics of adding an advert. Launch Pioneer and choose a new game with start on Barnard's star.

local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

if station.type == 'STARPORT_ORBITAL' then
ref = station:AddAdvert('Need the name of this station?',sendStationName)
end
end

Event.Register("onCreateBB", onCreateBB)

This code will create an advert:

[[File:BBS1.png]]

Looking at the image, you will notice that the advert has appeared at the top of the bulletin board and that only one of two fields is filled with text. The BBS ad has two components, the '''title''' on top and the '''description'''. Only the description is present and since the BBS posts are sorted on first the title and secondly on the description, since the title is blank the post will show up on top. The icon used is the default. '''AddAdvert''' has two versions and we used a simpler legacy form.

-- Legacy form
ref = station:AddAdvert(description, onChat, onDelete)

Clicking on the advert causes this to happen:

[[File:BBS2.png]]

Even though the only thing our function did was to send a message to the console, you can see that Pioneer automatically created a form for our advert. The only control is the 'Hang up' button.

Going back to the World View you can see the message on the Comms terminal:

[[File:BBS3.png]]

==More AddAdvert()==

As we saw, the legacy form of '''AddAdvert''' created an add that lacked a title and with a default icon. Lets rewrite the example above in the full form. [https://codedoc.pioneerspacesim.net/index.html#LuaClass:SpaceStation:AddAdvert LuaClass:SpaceStation:AddAdvert].

AddAdvert takes a table as argument.
ref = station:AddAdvert({
description = description,
icon = icon,
onChat = onChat,
onDelete = onDelete,
isEnabled = isEnabled,
})

Let's try the earlier example but simplified a bit to run on all stations.
local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

ref = station:AddAdvert({
title = 'STATION NAME',
description = 'Need the name of this station?',
icon = 'news',
onChat = sendStationName,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

The ad now looks complete. It will also show up on the BBS sorted on the title.

[[File:BBS5.png]]

==The BBS form==

Once the player has clicked on an advert, they are presented with a form. Each advert has only one form. The content of the form is added by the script, and can be modified at any time. It consists of a title, a face, a message, and one or more clickable options. The 'one' being the <code>Hang up</code> button that is generated automatically and always is present. The form itself is passed to the function specified in the <code>SpaceStation.AddAdvert()</code> method. In the example above, that function would be <code>sendStationName()</code>, which simply ignored any parameters sent to it. This resulted in the form being blank. The form object which is passed to this function has methods for adding the content. <code>SetTitle()</code> and <code>SetMessage()</code> each accept a string. <code>SetFace()</code> takes a table of information which defines the photofit face on the left but in the following example <code>SetFace()</code> is called without any arguments and the face will therefore be completely randomized.

A minimal example without any clickable options, just the default 'Hang up':

local Event = import("Event")

local populateForm = function (form)
form:SetTitle('This appears above the face picture')
form:SetFace()
form:SetMessage([[This is the main message.

It is normally a multi-line string.]])
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'AD TITLE',
description = 'This appears in the advert list',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

As before, an advert was created:

[[File:BBS4.png]]

We have clicked on the ad and can see that <code>populateForm</code> was called, and it successfully filled the form with content. If you 'hang up' and press the ad again a completely new face is generated. Lets improve on this and make the face persistent for the existence of the advert. Making it reappear in a saved game would take some more work (see "[[Surviving a reload]]").

local Character = require "Character"
local Event = require "Event"

local client = {}
local message

local populateForm = function (form)
form:SetTitle('Pizza time!')
form:SetFace(client)
form:SetMessage(message)
end

local onCreateBB = function (station)

client = Character.New()
message = "I'm " .. client.name .. " and I need some pizza. I'm thinking pepperoni and cheeze. You feelin me?"

station:AddAdvert({
title = 'PIZZA PARTY!',
description = 'Special delivery needed',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

We introduce a new module ''' '[https://codedoc.pioneerspacesim.net/#LuaClass:Character Character]' ''' which basically is an RPG style character sheet with methods to work with it. It's a tool to generate and work with non-player characters (NPC's). <code>client = Character.New()</code> sets client to an all new character with basic characteristics, name, title, and looks. A character can be sent directly to the SetFace method and that's what we're after here. We also used the 'clients' name.

==Adding options to the form==

In the example above, we created a function named <code>populateForm()</code> which was run when the advert button was clicked. That's not the only time it can be run; it is also run whenever options on its form are clicked. To make use of this, it is passed two additional parameters, both of which <code>populateForm()</code> ignored. The first parameter is the form object, the second is the advert's unique reference and the third is the number of the option that was clicked. Because it handles all chat events, by convention we instead name this function <code>onChat()</code>, which is how it shall be named from now on.

In the first example that called the function 'sendStationName' we caught the reference number from ''' 'AddAdvert()' ''' in a variable named ''' 'ref' '''. As you may remember, ''' 'AddAdvert()' ''' takes as one of its arguments a function to execute when the advert is clicked, '''onChat()'''. The function is passed three arguments. The second of these arguments is the reference number so we could have picked it up from within ''' 'sendStationName' '''. The ''' 'ref' ''' number is useful if your script adds several adverts, each of which might have slightly differently worded content.

You've already learned the methods: ''' 'SetTitle()' ''', ''' 'SetMessage()' ''', and ''' 'SetFace()' '''. Let's add the rest of the form() methods: 
* ''' form:AddOption() ''': adds clickable options with buttons. It takes two arguments: A string to set the text of the button and the option nr that will be sent to the form. This value is 0 when first called from the BBS by clicking the add. Every option form will have a default 'Hang up' option which returns -1. 
* ''' form:Clear() ''': removes the Message and Options, but preserves the Title and Face. 
* ''' form:Close() ''': Closes the form. 
* ''' form:RemoveAdvertOnClose() ''': Closes the form and removes the ad. 

Form options are declared like this:

form:AddOption('I am option one',1)
form:AddOption('I am option two',2)

These options will appear with the specified caption, and will call <code>onChat()</code>, which will receive the form object, the advert reference and the option number that was specified after the caption in <code>AddOption()</code>.

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

-- option 0 is called when the form is first activated from the
-- bulletin board
if option == 0 then

form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)

return
end

-- option 1 - red
if option == 1 then
form:SetMessage("Ahh red, the colour of raspberries.")
return
end

-- option 2 - green
if option == 2 then
form:SetMessage("Ahh green, the colour of trees.")
return
end

-- option 3 - blue
if option == 3 then
form:SetMessage("Ahh blue, the colour of the ocean.")
return
end

-- only option left is -1, hang up
form:Close()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Here, every time <code>onChat()</code> is called, regardless of the specified option, the form is cleared. The option is checked, and the relevant content is added to the form. Any other functions can be called from here, and this is how the script gets input from the player.

An alternative format might be to present the options in a table:

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

local options = {
[0] = function ()
form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)
end,
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
end,
[2] = function ()
form:SetMessage("Ahh green, the colour of trees.")
end,
[3] = function ()
form:SetMessage("Ahh blue, the colour of the ocean.")
end,
[-1] = function ()
form:Close()
end
}
options[option]()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Try this out:

* To understand what ''' 'form:Clear()' ''' does, comment out the line above containing it and restart Pioneer. As the form is no longer cleared and the 'Hang up' button is included automatically, there now appears to be only one form. The color selection buttons still works though.

* Try adding 'Go back' buttons from the color options:
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
form:AddOption("Go back", 0)
end,

* Try both suggestions above at the same time. ''' 'form:Clear()' ''' is your friend.

* Stick this code into the second onChat example above (or adopt it to the first one) to try out ''' 'form:RemoveAdvertOnClose()' ''':
form:AddOption("Report post", 4) -- In option[0]

-- ...

[4] = function ()
form:SetMessage("The ad has been reported and will not be shown on your BBS. " ..
"Thank you for helping us improve Haber Connect!")
form:RemoveAdvertOnClose()
end,

==Where to go from here==
To see simple complete examples of BBS interaction used in the game, look in <code>data/modules/DonateToCranks/DonateToCranks.lua</code>, and its accompanying language file <code>data/lang/modules-donatetocranks/en.json</code>, or the Advice module <code>data/modules/Advice/Advice.lua</code> and <code>data/lang/modules-advice/en.json</code>.

Interacting with the player: BBS forms

2025-11-09T20:04:56Z

Zonkmachine: /* Adding options to the form */ text fixup

The bulletin board system is currently the only place where real dialogue between a script and the player can take place. Bulletin boards can exist within any <code>SpaceStation</code> in the current system. They are created in a station the first time that a ship is either spawned, or lands, in that station. They continue to exist until the player leaves the system or quits the game. They are not saved in saved games, although a saved game contains information about which ones did exist.

When a bulletin board is created, the <code>onCreateBB</code> event is triggered, and passes the <code>SpaceStation</code> body in which that bulletin board was created. There is an exception to this: The event is not triggered after loading a game for those bulletin boards which, having existed at the time of saving, are re-created. The consequences of this will be covered later (see "[[Surviving a reload]]").

There are two components to any mission's entry on a bulletin board: The advert and the form. The advert is the part that is displayed on the main bulletin board list, along with all the other entries. The form is the part that appears on screen when the player clicks the advert's button.

==The BBS advert==

Adverts are placed onto a BBS by calling the station's <code>AddAdvert()</code> method, once the bulletin board has been created. Depending on the nature of your script, you might want to always place one advert on every station (as seen with the Breakdowns & Servicing script), or you might want to place an arbitrary number of adverts on a given station (as seen with deliveries, or assassinations).

The opportunities to add an advert are presented by two events. <code>onCreateBB</code> is the obvious one; there is also <code>onUpdateBB</code>, which is called for all existing bulletin boards in the current system, approximately once every hour or two. The actual interval is not particularly predictable.

The <code>AddAdvert()</code> method takes three arguments. The first is the text that will appear on the advert. The second is the function that will be called when the player clicks the advert. The third is optional, and is a function that can be called when the advert is deleted for any reason.

<code>AddAdvert()</code> returns a reference number, which can subsequently be used to remove the advert using <code>RemoveAdvert()</code>. It represents the number of times a module has generated an advert on a specific station. If no ads has been removed it will be equal to the number of ads on the station.

It's the job of the scripter to decide how many, if any, adverts to add to a bulletin board when <code>onCreateBB</code> is triggered, and whether to add or remove any when <code>onUpdateBB</code> is triggered. Tests could include the population of the system, the type of starport or the type of planet. In the future, tests will be able to include the government type of the system.

One important thing to bear in mind is that the script cannot query a bulletin board to find out what adverts already exist. Each script must carefully track each advert that it has created if it is to have any control over how long they remain, and to be able to re-create them after a reload.

Here is an example of adding an advert. The effect of clicking the advert is simply to send a message to the player console with the name of the station and the reference number, which is one in this case as we're only generating one advert. Furthermore, the advert is only added if the station is in space. There is no mission here, it is simply to illustrate the mechanics of adding an advert. Launch Pioneer and choose a new game with start on Barnard's star.

local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

if station.type == 'STARPORT_ORBITAL' then
ref = station:AddAdvert('Need the name of this station?',sendStationName)
end
end

Event.Register("onCreateBB", onCreateBB)

This code will create an advert:

[[File:BBS1.png]]

Looking at the image, you will notice that the advert has appeared at the top of the bulletin board and that only one of two fields is filled with text. The BBS ad has two components, the '''title''' on top and the '''description'''. Only the description is present and since the BBS posts are sorted on first the title and secondly on the description, since the title is blank the post will show up on top. The icon used is the default. '''AddAdvert''' has two versions and we used a simpler legacy form.

-- Legacy form
ref = station:AddAdvert(description, onChat, onDelete)

Clicking on the advert causes this to happen:

[[File:BBS2.png]]

Even though the only thing our function did was to send a message to the console, you can see that Pioneer automatically created a form for our advert. The only control is the 'Hang up' button.

Going back to the World View you can see the message on the Comms terminal:

[[File:BBS3.png]]

==More AddAdvert()==

As we saw, the legacy form of '''AddAdvert''' created an add that lacked a title and with a default icon. Lets rewrite the example above in the full form. [https://codedoc.pioneerspacesim.net/index.html#LuaClass:SpaceStation:AddAdvert LuaClass:SpaceStation:AddAdvert].

AddAdvert takes a table as argument.
ref = station:AddAdvert({
description = description,
icon = icon,
onChat = onChat,
onDelete = onDelete,
isEnabled = isEnabled,
})

Let's try the earlier example but simplified a bit to run on all stations.
local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

ref = station:AddAdvert({
title = 'STATION NAME',
description = 'Need the name of this station?',
icon = 'news',
onChat = sendStationName,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

The ad now looks complete. It will also show up on the BBS sorted on the title.

[[File:BBS5.png]]

==The BBS form==

Once the player has clicked on an advert, they are presented with a form. Each advert has only one form. The content of the form is added by the script, and can be modified at any time. It consists of a title, a face, a message, and one or more clickable options. The 'one' being the <code>Hang up</code> button that is generated automatically and always is present. The form itself is passed to the function specified in the <code>SpaceStation.AddAdvert()</code> method. In the example above, that function would be <code>sendStationName()</code>, which simply ignored any parameters sent to it. This resulted in the form being blank. The form object which is passed to this function has methods for adding the content. <code>SetTitle()</code> and <code>SetMessage()</code> each accept a string. <code>SetFace()</code> takes a table of information which defines the photofit face on the left but in the following example <code>SetFace()</code> is called without any arguments and the face will therefore be completely randomized.

A minimal example without any clickable options, just the default 'Hang up':

local Event = import("Event")

local populateForm = function (form)
form:SetTitle('This appears above the face picture')
form:SetFace()
form:SetMessage([[This is the main message.

It is normally a multi-line string.]])
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'AD TITLE',
description = 'This appears in the advert list',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

As before, an advert was created:

[[File:BBS4.png]]

We have clicked on the ad and can see that <code>populateForm</code> was called, and it successfully filled the form with content. If you 'hang up' and press the ad again a completely new face is generated. Lets improve on this and make the face persistent for the existence of the advert. Making it reappear in a saved game would take some more work (see "[[Surviving a reload]]").

local Character = require "Character"
local Event = require "Event"

local client = {}
local message

local populateForm = function (form)
form:SetTitle('Pizza time!')
form:SetFace(client)
form:SetMessage(message)
end

local onCreateBB = function (station)

client = Character.New()
message = "I'm " .. client.name .. " and I need some pizza. I'm thinking pepperoni and cheeze. You feelin me?"

station:AddAdvert({
title = 'PIZZA PARTY!',
description = 'Special delivery needed',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

We introduce a new module ''' '[https://codedoc.pioneerspacesim.net/#LuaClass:Character Character]' ''' which basically is an RPG style character sheet with methods to work with it. It's a tool to generate and work with non-player characters (NPC's). <code>client = Character.New()</code> sets client to an all new character with basic characteristics, name, title, and looks. A character can be sent directly to the SetFace method and that's what we're after here. We also used the 'clients' name.

==Adding options to the form==

In the example above, we created a function named <code>populateForm()</code> which was run when the advert button was clicked. That's not the only time it can be run; it is also run whenever options on its form are clicked. To make use of this, it is passed two additional parameters, both of which <code>populateForm()</code> ignored. The first parameter is the form object, the second is the advert's unique reference and the third is the number of the option that was clicked. Because it handles all chat events, by convention we instead name this function <code>onChat()</code>, which is how it shall be named from now on.

In the first example that called the function 'sendStationName' we caught the reference number from ''' 'AddAdvert()' ''' in a variable named ''' 'ref' '''. As you may remember, ''' 'AddAdvert()' ''' takes as one of its arguments a function to execute when the advert is clicked, '''onChat()'''. The function is passed three arguments. The second of these arguments is the reference number so we could have picked it up from within ''' 'sendStationName' '''. The ''' 'ref' ''' number is useful if your script adds several adverts, each of which might have slightly differently worded content.

You've already learned the methods: ''' 'SetTitle()' ''', ''' 'SetMessage()' ''', and ''' 'SetFace()' '''. Let's add the rest of the form() methods: 
* ''' form:AddOption() ''': adds clickable options with buttons. It takes two arguments: A string to set the text of the button and the option nr that will be sent to the form. This value is 0 when first called from the BBS by clicking the add. Every option form will have a default 'Hang up' option which returns -1. 
* ''' form:Clear() ''': removes the Message and Options, but preserves the Title and Face. 
* ''' form:Close() ''': Closes the form. 
* ''' form:RemoveAdvertOnClose() ''': Closes the form and removes the ad. 

Form options are declared like this:

form:AddOption('I am option one',1)
form:AddOption('I am option two',2)

These options will appear with the specified caption, and will call <code>onChat()</code>, which will receive the form object, the advert reference and the option number that was specified after the caption in <code>AddOption()</code>.

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

-- option 0 is called when the form is first activated from the
-- bulletin board
if option == 0 then

form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)

return
end

-- option 1 - red
if option == 1 then
form:SetMessage("Ahh red, the colour of raspberries.")
return
end

-- option 2 - green
if option == 2 then
form:SetMessage("Ahh green, the colour of trees.")
return
end

-- option 3 - blue
if option == 3 then
form:SetMessage("Ahh blue, the colour of the ocean.")
return
end

-- only option left is -1, hang up
form:Close()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Here, every time <code>onChat()</code> is called, regardless of the specified option, the form is cleared. The option is checked, and the relevant content is added to the form. Any other functions can be called from here, and this is how the script gets input from the player.

An alternative format might be to present the options in a table:

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

local options = {
[0] = function ()
form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)
end,
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
end,
[2] = function ()
form:SetMessage("Ahh green, the colour of trees.")
end,
[3] = function ()
form:SetMessage("Ahh blue, the colour of the ocean.")
end,
[-1] = function ()
form:Close()
end
}
options[option]()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Try this out:

* To understand what ''' 'form:Clear()' ''' does, comment out the line above containing it and restart Pioneer. As the form is no longer cleared and the 'Hang up' button is included automatically, there now appears to be only one form. The color selection buttons still works though.

* Try adding 'Go back' buttons from the color options:
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
form:AddOption("Go back", 0)
end,

* Try both suggestions above at the same time. ''' 'form:Clear()' ''' is your friend.

* Stick this code into the second onChat example above (or adopt it to the first one) to try out ''' 'form:RemoveAdvertOnClose()' ''':
form:AddOption("Report post", 4) -- In option[0]

-- ...

[4] = function ()
form:SetMessage("The ad has been reported and will not be shown on your BBS. " ..
"Thank you for helping us to improve Haber Connect!")
form:RemoveAdvertOnClose()
end,

==Where to go from here==
To see simple complete examples of BBS interaction used in the game, look in <code>data/modules/DonateToCranks/DonateToCranks.lua</code>, and its accompanying language file <code>data/lang/modules-donatetocranks/en.json</code>, or the Advice module <code>data/modules/Advice/Advice.lua</code> and <code>data/lang/modules-advice/en.json</code>.

Interacting with the player: BBS forms

2025-11-09T18:04:49Z

Zonkmachine: /* Adding options to the form */ Superfluous comment

The bulletin board system is currently the only place where real dialogue between a script and the player can take place. Bulletin boards can exist within any <code>SpaceStation</code> in the current system. They are created in a station the first time that a ship is either spawned, or lands, in that station. They continue to exist until the player leaves the system or quits the game. They are not saved in saved games, although a saved game contains information about which ones did exist.

When a bulletin board is created, the <code>onCreateBB</code> event is triggered, and passes the <code>SpaceStation</code> body in which that bulletin board was created. There is an exception to this: The event is not triggered after loading a game for those bulletin boards which, having existed at the time of saving, are re-created. The consequences of this will be covered later (see "[[Surviving a reload]]").

There are two components to any mission's entry on a bulletin board: The advert and the form. The advert is the part that is displayed on the main bulletin board list, along with all the other entries. The form is the part that appears on screen when the player clicks the advert's button.

==The BBS advert==

Adverts are placed onto a BBS by calling the station's <code>AddAdvert()</code> method, once the bulletin board has been created. Depending on the nature of your script, you might want to always place one advert on every station (as seen with the Breakdowns & Servicing script), or you might want to place an arbitrary number of adverts on a given station (as seen with deliveries, or assassinations).

The opportunities to add an advert are presented by two events. <code>onCreateBB</code> is the obvious one; there is also <code>onUpdateBB</code>, which is called for all existing bulletin boards in the current system, approximately once every hour or two. The actual interval is not particularly predictable.

The <code>AddAdvert()</code> method takes three arguments. The first is the text that will appear on the advert. The second is the function that will be called when the player clicks the advert. The third is optional, and is a function that can be called when the advert is deleted for any reason.

<code>AddAdvert()</code> returns a reference number, which can subsequently be used to remove the advert using <code>RemoveAdvert()</code>. It represents the number of times a module has generated an advert on a specific station. If no ads has been removed it will be equal to the number of ads on the station.

It's the job of the scripter to decide how many, if any, adverts to add to a bulletin board when <code>onCreateBB</code> is triggered, and whether to add or remove any when <code>onUpdateBB</code> is triggered. Tests could include the population of the system, the type of starport or the type of planet. In the future, tests will be able to include the government type of the system.

One important thing to bear in mind is that the script cannot query a bulletin board to find out what adverts already exist. Each script must carefully track each advert that it has created if it is to have any control over how long they remain, and to be able to re-create them after a reload.

Here is an example of adding an advert. The effect of clicking the advert is simply to send a message to the player console with the name of the station and the reference number, which is one in this case as we're only generating one advert. Furthermore, the advert is only added if the station is in space. There is no mission here, it is simply to illustrate the mechanics of adding an advert. Launch Pioneer and choose a new game with start on Barnard's star.

local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

if station.type == 'STARPORT_ORBITAL' then
ref = station:AddAdvert('Need the name of this station?',sendStationName)
end
end

Event.Register("onCreateBB", onCreateBB)

This code will create an advert:

[[File:BBS1.png]]

Looking at the image, you will notice that the advert has appeared at the top of the bulletin board and that only one of two fields is filled with text. The BBS ad has two components, the '''title''' on top and the '''description'''. Only the description is present and since the BBS posts are sorted on first the title and secondly on the description, since the title is blank the post will show up on top. The icon used is the default. '''AddAdvert''' has two versions and we used a simpler legacy form.

-- Legacy form
ref = station:AddAdvert(description, onChat, onDelete)

Clicking on the advert causes this to happen:

[[File:BBS2.png]]

Even though the only thing our function did was to send a message to the console, you can see that Pioneer automatically created a form for our advert. The only control is the 'Hang up' button.

Going back to the World View you can see the message on the Comms terminal:

[[File:BBS3.png]]

==More AddAdvert()==

As we saw, the legacy form of '''AddAdvert''' created an add that lacked a title and with a default icon. Lets rewrite the example above in the full form. [https://codedoc.pioneerspacesim.net/index.html#LuaClass:SpaceStation:AddAdvert LuaClass:SpaceStation:AddAdvert].

AddAdvert takes a table as argument.
ref = station:AddAdvert({
description = description,
icon = icon,
onChat = onChat,
onDelete = onDelete,
isEnabled = isEnabled,
})

Let's try the earlier example but simplified a bit to run on all stations.
local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

ref = station:AddAdvert({
title = 'STATION NAME',
description = 'Need the name of this station?',
icon = 'news',
onChat = sendStationName,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

The ad now looks complete. It will also show up on the BBS sorted on the title.

[[File:BBS5.png]]

==The BBS form==

Once the player has clicked on an advert, they are presented with a form. Each advert has only one form. The content of the form is added by the script, and can be modified at any time. It consists of a title, a face, a message, and one or more clickable options. The 'one' being the <code>Hang up</code> button that is generated automatically and always is present. The form itself is passed to the function specified in the <code>SpaceStation.AddAdvert()</code> method. In the example above, that function would be <code>sendStationName()</code>, which simply ignored any parameters sent to it. This resulted in the form being blank. The form object which is passed to this function has methods for adding the content. <code>SetTitle()</code> and <code>SetMessage()</code> each accept a string. <code>SetFace()</code> takes a table of information which defines the photofit face on the left but in the following example <code>SetFace()</code> is called without any arguments and the face will therefore be completely randomized.

A minimal example without any clickable options, just the default 'Hang up':

local Event = import("Event")

local populateForm = function (form)
form:SetTitle('This appears above the face picture')
form:SetFace()
form:SetMessage([[This is the main message.

It is normally a multi-line string.]])
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'AD TITLE',
description = 'This appears in the advert list',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

As before, an advert was created:

[[File:BBS4.png]]

We have clicked on the ad and can see that <code>populateForm</code> was called, and it successfully filled the form with content. If you 'hang up' and press the ad again a completely new face is generated. Lets improve on this and make the face persistent for the existence of the advert. Making it reappear in a saved game would take some more work (see "[[Surviving a reload]]").

local Character = require "Character"
local Event = require "Event"

local client = {}
local message

local populateForm = function (form)
form:SetTitle('Pizza time!')
form:SetFace(client)
form:SetMessage(message)
end

local onCreateBB = function (station)

client = Character.New()
message = "I'm " .. client.name .. " and I need some pizza. I'm thinking pepperoni and cheeze. You feelin me?"

station:AddAdvert({
title = 'PIZZA PARTY!',
description = 'Special delivery needed',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

We introduce a new module ''' '[https://codedoc.pioneerspacesim.net/#LuaClass:Character Character]' ''' which basically is an RPG style character sheet with methods to work with it. It's a tool to generate and work with non-player characters (NPC's). <code>client = Character.New()</code> sets client to an all new character with basic characteristics, name, title, and looks. A character can be sent directly to the SetFace method and that's what we're after here. We also used the 'clients' name.

==Adding options to the form==

In the example above, we created a function named <code>populateForm()</code> which was run when the advert button was clicked. That's not the only time it can be run; it is also run whenever options on its form are clicked. To make use of this, it is passed two additional parameters, both of which <code>populateForm()</code> ignored. The first parameter is the form object, the second is the advert's unique reference and the third is the number of the option that was clicked. Because it handles all chat events, by convention we instead name this function <code>onChat()</code>, which is how it shall be named from now on.

In the first example that called the function 'sendStationName' we caught the reference number from ''' 'AddAdvert()' ''' in a variable named ''' 'ref' '''. As you may remember, ''' 'AddAdvert()' ''' takes as one of its arguments a function to execute when the advert is clicked, '''onChat()'''. The function is passed three arguments. The second of these arguments is the reference number so we could have picked it up from within ''' 'sendStationName' '''. The ''' 'ref' ''' number is useful if your script adds several adverts, each of which might have slightly differently worded content.

You've already learned the methods: ''' 'SetTitle()' ''', ''' 'SetMessage()' ''', and ''' 'SetFace()' '''. Let's add the rest of the form() methods: 
* ''' form:AddOption() ''': adds clickable options with buttons. It takes two arguments: A string to set the text of the button and the option nr that will be sent to the form. This value is 0 when first called from the BBS by clicking the add. Every option form will have a default 'Hang up' option which returns -1. 
* ''' form:Clear() ''': removes the Message and Options, but preserves the Title and Face. 
* ''' form:Close() ''': Closes the form. 
* ''' form:RemoveAdvertOnClose() ''': Closes the form and removes the ad. 

Form options are declared like this:

form:AddOption('I am option one',1)
form:AddOption('I am option two',2)

These options will appear with the specified caption, and will call <code>onChat()</code>, which will receive the form object, the advert reference and the option number that was specified after the caption in <code>AddOption()</code>.

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

-- option 0 is called when the form is first activated from the
-- bulletin board
if option == 0 then

form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)

return
end

-- option 1 - red
if option == 1 then
form:SetMessage("Ahh red, the colour of raspberries.")
return
end

-- option 2 - green
if option == 2 then
form:SetMessage("Ahh green, the colour of trees.")
return
end

-- option 3 - blue
if option == 3 then
form:SetMessage("Ahh blue, the colour of the ocean.")
return
end

-- only option left is -1, hang up
form:Close()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Here, every time <code>onChat()</code> is called, regardless of the specified option, the form is cleared. The option is checked, and the relevant content is added to the form. Any other functions can be called from here, and this is how the script gets input from the player.

An alternative format might be this:

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

local options = {
[0] = function ()
form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)
end,
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
end,
[2] = function ()
form:SetMessage("Ahh green, the colour of trees.")
end,
[3] = function ()
form:SetMessage("Ahh blue, the colour of the ocean.")
end,
[-1] = function ()
form:Close()
end
}
options[option]()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Try this out:

* To understand what ''' 'form:Clear()' ''' does, comment out the line above containing it and restart Pioneer. As the form is no longer cleared and the 'Hang up' button is included automatically, there now appears to be only one form. The color selection buttons still works though.

* Try adding 'Go back' buttons from the color options:
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
form:AddOption("Go back", 0)
end,

* Try both suggestions above at the same time. ''' 'form:Clear()' ''' is your friend.

* Stick this code into the second onChat example above (or adopt it to the first one) to try out ''' 'form:RemoveAdvertOnClose()' ''':
form:AddOption("Report post", 4) -- In option[0]

-- ...

[4] = function ()
form:SetMessage("The ad has been reported and will not be shown on your BBS. " ..
"Thank you for helping us to improve Haber Connect!")
form:RemoveAdvertOnClose()
end,

==Where to go from here==
To see simple complete examples of BBS interaction used in the game, look in <code>data/modules/DonateToCranks/DonateToCranks.lua</code>, and its accompanying language file <code>data/lang/modules-donatetocranks/en.json</code>, or the Advice module <code>data/modules/Advice/Advice.lua</code> and <code>data/lang/modules-advice/en.json</code>.

Interacting with the player: BBS forms

2025-11-09T17:34:50Z

Zonkmachine: /* Adding options to the form */ remove ref to legacy code

The bulletin board system is currently the only place where real dialogue between a script and the player can take place. Bulletin boards can exist within any <code>SpaceStation</code> in the current system. They are created in a station the first time that a ship is either spawned, or lands, in that station. They continue to exist until the player leaves the system or quits the game. They are not saved in saved games, although a saved game contains information about which ones did exist.

When a bulletin board is created, the <code>onCreateBB</code> event is triggered, and passes the <code>SpaceStation</code> body in which that bulletin board was created. There is an exception to this: The event is not triggered after loading a game for those bulletin boards which, having existed at the time of saving, are re-created. The consequences of this will be covered later (see "[[Surviving a reload]]").

There are two components to any mission's entry on a bulletin board: The advert and the form. The advert is the part that is displayed on the main bulletin board list, along with all the other entries. The form is the part that appears on screen when the player clicks the advert's button.

==The BBS advert==

Adverts are placed onto a BBS by calling the station's <code>AddAdvert()</code> method, once the bulletin board has been created. Depending on the nature of your script, you might want to always place one advert on every station (as seen with the Breakdowns & Servicing script), or you might want to place an arbitrary number of adverts on a given station (as seen with deliveries, or assassinations).

The opportunities to add an advert are presented by two events. <code>onCreateBB</code> is the obvious one; there is also <code>onUpdateBB</code>, which is called for all existing bulletin boards in the current system, approximately once every hour or two. The actual interval is not particularly predictable.

The <code>AddAdvert()</code> method takes three arguments. The first is the text that will appear on the advert. The second is the function that will be called when the player clicks the advert. The third is optional, and is a function that can be called when the advert is deleted for any reason.

<code>AddAdvert()</code> returns a reference number, which can subsequently be used to remove the advert using <code>RemoveAdvert()</code>. It represents the number of times a module has generated an advert on a specific station. If no ads has been removed it will be equal to the number of ads on the station.

It's the job of the scripter to decide how many, if any, adverts to add to a bulletin board when <code>onCreateBB</code> is triggered, and whether to add or remove any when <code>onUpdateBB</code> is triggered. Tests could include the population of the system, the type of starport or the type of planet. In the future, tests will be able to include the government type of the system.

One important thing to bear in mind is that the script cannot query a bulletin board to find out what adverts already exist. Each script must carefully track each advert that it has created if it is to have any control over how long they remain, and to be able to re-create them after a reload.

Here is an example of adding an advert. The effect of clicking the advert is simply to send a message to the player console with the name of the station and the reference number, which is one in this case as we're only generating one advert. Furthermore, the advert is only added if the station is in space. There is no mission here, it is simply to illustrate the mechanics of adding an advert. Launch Pioneer and choose a new game with start on Barnard's star.

local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

if station.type == 'STARPORT_ORBITAL' then
ref = station:AddAdvert('Need the name of this station?',sendStationName)
end
end

Event.Register("onCreateBB", onCreateBB)

This code will create an advert:

[[File:BBS1.png]]

Looking at the image, you will notice that the advert has appeared at the top of the bulletin board and that only one of two fields is filled with text. The BBS ad has two components, the '''title''' on top and the '''description'''. Only the description is present and since the BBS posts are sorted on first the title and secondly on the description, since the title is blank the post will show up on top. The icon used is the default. '''AddAdvert''' has two versions and we used a simpler legacy form.

-- Legacy form
ref = station:AddAdvert(description, onChat, onDelete)

Clicking on the advert causes this to happen:

[[File:BBS2.png]]

Even though the only thing our function did was to send a message to the console, you can see that Pioneer automatically created a form for our advert. The only control is the 'Hang up' button.

Going back to the World View you can see the message on the Comms terminal:

[[File:BBS3.png]]

==More AddAdvert()==

As we saw, the legacy form of '''AddAdvert''' created an add that lacked a title and with a default icon. Lets rewrite the example above in the full form. [https://codedoc.pioneerspacesim.net/index.html#LuaClass:SpaceStation:AddAdvert LuaClass:SpaceStation:AddAdvert].

AddAdvert takes a table as argument.
ref = station:AddAdvert({
description = description,
icon = icon,
onChat = onChat,
onDelete = onDelete,
isEnabled = isEnabled,
})

Let's try the earlier example but simplified a bit to run on all stations.
local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

ref = station:AddAdvert({
title = 'STATION NAME',
description = 'Need the name of this station?',
icon = 'news',
onChat = sendStationName,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

The ad now looks complete. It will also show up on the BBS sorted on the title.

[[File:BBS5.png]]

==The BBS form==

Once the player has clicked on an advert, they are presented with a form. Each advert has only one form. The content of the form is added by the script, and can be modified at any time. It consists of a title, a face, a message, and one or more clickable options. The 'one' being the <code>Hang up</code> button that is generated automatically and always is present. The form itself is passed to the function specified in the <code>SpaceStation.AddAdvert()</code> method. In the example above, that function would be <code>sendStationName()</code>, which simply ignored any parameters sent to it. This resulted in the form being blank. The form object which is passed to this function has methods for adding the content. <code>SetTitle()</code> and <code>SetMessage()</code> each accept a string. <code>SetFace()</code> takes a table of information which defines the photofit face on the left but in the following example <code>SetFace()</code> is called without any arguments and the face will therefore be completely randomized.

A minimal example without any clickable options, just the default 'Hang up':

local Event = import("Event")

local populateForm = function (form)
form:SetTitle('This appears above the face picture')
form:SetFace()
form:SetMessage([[This is the main message.

It is normally a multi-line string.]])
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'AD TITLE',
description = 'This appears in the advert list',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

As before, an advert was created:

[[File:BBS4.png]]

We have clicked on the ad and can see that <code>populateForm</code> was called, and it successfully filled the form with content. If you 'hang up' and press the ad again a completely new face is generated. Lets improve on this and make the face persistent for the existence of the advert. Making it reappear in a saved game would take some more work (see "[[Surviving a reload]]").

local Character = require "Character"
local Event = require "Event"

local client = {}
local message

local populateForm = function (form)
form:SetTitle('Pizza time!')
form:SetFace(client)
form:SetMessage(message)
end

local onCreateBB = function (station)

client = Character.New()
message = "I'm " .. client.name .. " and I need some pizza. I'm thinking pepperoni and cheeze. You feelin me?"

station:AddAdvert({
title = 'PIZZA PARTY!',
description = 'Special delivery needed',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

We introduce a new module ''' '[https://codedoc.pioneerspacesim.net/#LuaClass:Character Character]' ''' which basically is an RPG style character sheet with methods to work with it. It's a tool to generate and work with non-player characters (NPC's). <code>client = Character.New()</code> sets client to an all new character with basic characteristics, name, title, and looks. A character can be sent directly to the SetFace method and that's what we're after here. We also used the 'clients' name.

==Adding options to the form==

In the example above, we created a function named <code>populateForm()</code> which was run when the advert button was clicked. That's not the only time it can be run; it is also run whenever options on its form are clicked. To make use of this, it is passed two additional parameters, both of which <code>populateForm()</code> ignored. The first parameter is the form object, the second is the advert's unique reference and the third is the number of the option that was clicked. Because it handles all chat events, by convention we instead name this function <code>onChat()</code>, which is how it shall be named from now on.

In the first example that called the function 'sendStationName' we caught the reference number from ''' 'AddAdvert()' ''' in a variable named ''' 'ref' '''. As you may remember, ''' 'AddAdvert()' ''' takes as one of its arguments a function to execute when the advert is clicked, '''onChat()'''. The function is passed three arguments. The second of these arguments is the reference number so we could have picked it up from within ''' 'sendStationName' '''. The ''' 'ref' ''' number is useful if your script adds several adverts, each of which might have slightly differently worded content.

You've already learned the methods: ''' 'SetTitle()' ''', ''' 'SetMessage()' ''', and ''' 'SetFace()' '''. Let's add the rest of the form() methods: 
* ''' form:AddOption() ''': adds clickable options with buttons. It takes two arguments: A string to set the text of the button and the option nr that will be sent to the form. This value is 0 when first called from the BBS by clicking the add. Every option form will have a default 'Hang up' option which returns -1. 
* ''' form:Clear() ''': removes the Message and Options, but preserves the Title and Face. 
* ''' form:Close() ''': Closes the form. 
* ''' form:RemoveAdvertOnClose() ''': Closes the form and removes the ad. 

Form options are declared like this:

form:AddOption('I am option one',1)
form:AddOption('I am option two',2)

These options will appear with the specified caption, and will call <code>onChat()</code>, which will receive the form object, the advert reference and the option number that was specified after the caption in <code>AddOption()</code>.

The onChat function below is adapted from an earlier example from the codedoc:

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

-- option 0 is called when the form is first activated from the
-- bulletin board
if option == 0 then

form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)

return
end

-- option 1 - red
if option == 1 then
form:SetMessage("Ahh red, the colour of raspberries.")
return
end

-- option 2 - green
if option == 2 then
form:SetMessage("Ahh green, the colour of trees.")
return
end

-- option 3 - blue
if option == 3 then
form:SetMessage("Ahh blue, the colour of the ocean.")
return
end

-- only option left is -1, hang up
form:Close()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Here, every time <code>onChat()</code> is called, regardless of the specified option, the form is cleared. The option is checked, and the relevant content is added to the form. Any other functions can be called from here, and this is how the script gets input from the player.

An alternative format might be this:

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

local options = {
[0] = function ()
form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)
end,
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
end,
[2] = function ()
form:SetMessage("Ahh green, the colour of trees.")
end,
[3] = function ()
form:SetMessage("Ahh blue, the colour of the ocean.")
end,
[-1] = function ()
form:Close()
end
}
options[option]()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Try this out:

* To understand what ''' 'form:Clear()' ''' does, comment out the line above containing it and restart Pioneer. As the form is no longer cleared and the 'Hang up' button is included automatically, there now appears to be only one form. The color selection buttons still works though.

* Try adding 'Go back' buttons from the color options:
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
form:AddOption("Go back", 0)
end,

* Try both suggestions above at the same time. ''' 'form:Clear()' ''' is your friend.

* Stick this code into the second onChat example above (or adopt it to the first one) to try out ''' 'form:RemoveAdvertOnClose()' ''':
form:AddOption("Report post", 4) -- In option[0]

-- ...

[4] = function ()
form:SetMessage("The ad has been reported and will not be shown on your BBS. " ..
"Thank you for helping us to improve Haber Connect!")
form:RemoveAdvertOnClose()
end,

==Where to go from here==
To see simple complete examples of BBS interaction used in the game, look in <code>data/modules/DonateToCranks/DonateToCranks.lua</code>, and its accompanying language file <code>data/lang/modules-donatetocranks/en.json</code>, or the Advice module <code>data/modules/Advice/Advice.lua</code> and <code>data/lang/modules-advice/en.json</code>.

Interacting with the player: BBS forms

2025-11-08T18:37:16Z

Zonkmachine: /* The BBS advert */ fixup

The bulletin board system is currently the only place where real dialogue between a script and the player can take place. Bulletin boards can exist within any <code>SpaceStation</code> in the current system. They are created in a station the first time that a ship is either spawned, or lands, in that station. They continue to exist until the player leaves the system or quits the game. They are not saved in saved games, although a saved game contains information about which ones did exist.

When a bulletin board is created, the <code>onCreateBB</code> event is triggered, and passes the <code>SpaceStation</code> body in which that bulletin board was created. There is an exception to this: The event is not triggered after loading a game for those bulletin boards which, having existed at the time of saving, are re-created. The consequences of this will be covered later (see "[[Surviving a reload]]").

There are two components to any mission's entry on a bulletin board: The advert and the form. The advert is the part that is displayed on the main bulletin board list, along with all the other entries. The form is the part that appears on screen when the player clicks the advert's button.

==The BBS advert==

Adverts are placed onto a BBS by calling the station's <code>AddAdvert()</code> method, once the bulletin board has been created. Depending on the nature of your script, you might want to always place one advert on every station (as seen with the Breakdowns & Servicing script), or you might want to place an arbitrary number of adverts on a given station (as seen with deliveries, or assassinations).

The opportunities to add an advert are presented by two events. <code>onCreateBB</code> is the obvious one; there is also <code>onUpdateBB</code>, which is called for all existing bulletin boards in the current system, approximately once every hour or two. The actual interval is not particularly predictable.

The <code>AddAdvert()</code> method takes three arguments. The first is the text that will appear on the advert. The second is the function that will be called when the player clicks the advert. The third is optional, and is a function that can be called when the advert is deleted for any reason.

<code>AddAdvert()</code> returns a reference number, which can subsequently be used to remove the advert using <code>RemoveAdvert()</code>. It represents the number of times a module has generated an advert on a specific station. If no ads has been removed it will be equal to the number of ads on the station.

It's the job of the scripter to decide how many, if any, adverts to add to a bulletin board when <code>onCreateBB</code> is triggered, and whether to add or remove any when <code>onUpdateBB</code> is triggered. Tests could include the population of the system, the type of starport or the type of planet. In the future, tests will be able to include the government type of the system.

One important thing to bear in mind is that the script cannot query a bulletin board to find out what adverts already exist. Each script must carefully track each advert that it has created if it is to have any control over how long they remain, and to be able to re-create them after a reload.

Here is an example of adding an advert. The effect of clicking the advert is simply to send a message to the player console with the name of the station and the reference number, which is one in this case as we're only generating one advert. Furthermore, the advert is only added if the station is in space. There is no mission here, it is simply to illustrate the mechanics of adding an advert. Launch Pioneer and choose a new game with start on Barnard's star.

local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

if station.type == 'STARPORT_ORBITAL' then
ref = station:AddAdvert('Need the name of this station?',sendStationName)
end
end

Event.Register("onCreateBB", onCreateBB)

This code will create an advert:

[[File:BBS1.png]]

Looking at the image, you will notice that the advert has appeared at the top of the bulletin board and that only one of two fields is filled with text. The BBS ad has two components, the '''title''' on top and the '''description'''. Only the description is present and since the BBS posts are sorted on first the title and secondly on the description, since the title is blank the post will show up on top. The icon used is the default. '''AddAdvert''' has two versions and we used a simpler legacy form.

-- Legacy form
ref = station:AddAdvert(description, onChat, onDelete)

Clicking on the advert causes this to happen:

[[File:BBS2.png]]

Even though the only thing our function did was to send a message to the console, you can see that Pioneer automatically created a form for our advert. The only control is the 'Hang up' button.

Going back to the World View you can see the message on the Comms terminal:

[[File:BBS3.png]]

==More AddAdvert()==

As we saw, the legacy form of '''AddAdvert''' created an add that lacked a title and with a default icon. Lets rewrite the example above in the full form. [https://codedoc.pioneerspacesim.net/index.html#LuaClass:SpaceStation:AddAdvert LuaClass:SpaceStation:AddAdvert].

AddAdvert takes a table as argument.
ref = station:AddAdvert({
description = description,
icon = icon,
onChat = onChat,
onDelete = onDelete,
isEnabled = isEnabled,
})

Let's try the earlier example but simplified a bit to run on all stations.
local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

ref = station:AddAdvert({
title = 'STATION NAME',
description = 'Need the name of this station?',
icon = 'news',
onChat = sendStationName,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

The ad now looks complete. It will also show up on the BBS sorted on the title.

[[File:BBS5.png]]

==The BBS form==

Once the player has clicked on an advert, they are presented with a form. Each advert has only one form. The content of the form is added by the script, and can be modified at any time. It consists of a title, a face, a message, and one or more clickable options. The 'one' being the <code>Hang up</code> button that is generated automatically and always is present. The form itself is passed to the function specified in the <code>SpaceStation.AddAdvert()</code> method. In the example above, that function would be <code>sendStationName()</code>, which simply ignored any parameters sent to it. This resulted in the form being blank. The form object which is passed to this function has methods for adding the content. <code>SetTitle()</code> and <code>SetMessage()</code> each accept a string. <code>SetFace()</code> takes a table of information which defines the photofit face on the left but in the following example <code>SetFace()</code> is called without any arguments and the face will therefore be completely randomized.

A minimal example without any clickable options, just the default 'Hang up':

local Event = import("Event")

local populateForm = function (form)
form:SetTitle('This appears above the face picture')
form:SetFace()
form:SetMessage([[This is the main message.

It is normally a multi-line string.]])
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'AD TITLE',
description = 'This appears in the advert list',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

As before, an advert was created:

[[File:BBS4.png]]

We have clicked on the ad and can see that <code>populateForm</code> was called, and it successfully filled the form with content. If you 'hang up' and press the ad again a completely new face is generated. Lets improve on this and make the face persistent for the existence of the advert. Making it reappear in a saved game would take some more work (see "[[Surviving a reload]]").

local Character = require "Character"
local Event = require "Event"

local client = {}
local message

local populateForm = function (form)
form:SetTitle('Pizza time!')
form:SetFace(client)
form:SetMessage(message)
end

local onCreateBB = function (station)

client = Character.New()
message = "I'm " .. client.name .. " and I need some pizza. I'm thinking pepperoni and cheeze. You feelin me?"

station:AddAdvert({
title = 'PIZZA PARTY!',
description = 'Special delivery needed',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

We introduce a new module ''' '[https://codedoc.pioneerspacesim.net/#LuaClass:Character Character]' ''' which basically is an RPG style character sheet with methods to work with it. It's a tool to generate and work with non-player characters (NPC's). <code>client = Character.New()</code> sets client to an all new character with basic characteristics, name, title, and looks. A character can be sent directly to the SetFace method and that's what we're after here. We also used the 'clients' name.

==Adding options to the form==

In the example above, we created a function named <code>populateForm()</code> which was run when the advert button was clicked. That's not the only time it can be run; it is also run whenever options on its form are clicked. To make use of this, it is passed two additional parameters, both of which <code>populateForm()</code> ignored. The first parameter is the form object, the second is the advert's unique reference and the third is the number of the option that was clicked. Because it handles all chat events, by convention we instead name this function <code>onChat()</code>, which is how it shall be named from now on.

In the first example that called the function 'sendStationName' we caught the reference number from ''' 'AddAdvert()' ''' in a variable named ''' 'ref' '''. As you may remember, ''' 'AddAdvert()' ''' takes two arguments; A string and a function. The function is passed three arguments. The second of these arguments is the reference number so we could have picked it up from within ''' 'sendStationName' '''. The ''' 'ref' ''' number is useful if your script adds several adverts, each of which might have slightly differently worded content.

You've already learned the methods: ''' 'SetTitle()' ''', ''' 'SetMessage()' ''', and ''' 'SetFace()' '''. Let's add the rest of the form() methods: 
* ''' form:AddOption() ''': adds clickable options with buttons. It takes two arguments: A string to set the text of the button and the option nr that will be sent to the form. This value is 0 when first called from the BBS by clicking the add. Every option form will have a default 'Hang up' option which returns -1. 
* ''' form:Clear() ''': removes the Message and Options, but preserves the Title and Face. 
* ''' form:Close() ''': Closes the form. 
* ''' form:RemoveAdvertOnClose() ''': Closes the form and removes the ad. 

Form options are declared like this:

form:AddOption('I am option one',1)
form:AddOption('I am option two',2)

These options will appear with the specified caption, and will call <code>onChat()</code>, which will receive the form object, the advert reference and the option number that was specified after the caption in <code>AddOption()</code>.

The onChat function below is adapted from an earlier example from the codedoc:

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

-- option 0 is called when the form is first activated from the
-- bulletin board
if option == 0 then

form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)

return
end

-- option 1 - red
if option == 1 then
form:SetMessage("Ahh red, the colour of raspberries.")
return
end

-- option 2 - green
if option == 2 then
form:SetMessage("Ahh green, the colour of trees.")
return
end

-- option 3 - blue
if option == 3 then
form:SetMessage("Ahh blue, the colour of the ocean.")
return
end

-- only option left is -1, hang up
form:Close()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Here, every time <code>onChat()</code> is called, regardless of the specified option, the form is cleared. The option is checked, and the relevant content is added to the form. Any other functions can be called from here, and this is how the script gets input from the player.

An alternative format might be this:

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

local options = {
[0] = function ()
form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)
end,
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
end,
[2] = function ()
form:SetMessage("Ahh green, the colour of trees.")
end,
[3] = function ()
form:SetMessage("Ahh blue, the colour of the ocean.")
end,
[-1] = function ()
form:Close()
end
}
options[option]()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Try this out:

* To understand what ''' 'form:Clear()' ''' does, comment out the line above containing it and restart Pioneer. As the form is no longer cleared and the 'Hang up' button is included automatically, there now appears to be only one form. The color selection buttons still works though.

* Try adding 'Go back' buttons from the color options:
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
form:AddOption("Go back", 0)
end,

* Try both suggestions above at the same time. ''' 'form:Clear()' ''' is your friend.

* Stick this code into the second onChat example above (or adopt it to the first one) to try out ''' 'form:RemoveAdvertOnClose()' ''':
form:AddOption("Report post", 4) -- In option[0]

-- ...

[4] = function ()
form:SetMessage("The ad has been reported and will not be shown on your BBS. " ..
"Thank you for helping us to improve Haber Connect!")
form:RemoveAdvertOnClose()
end,

==Where to go from here==
To see simple complete examples of BBS interaction used in the game, look in <code>data/modules/DonateToCranks/DonateToCranks.lua</code>, and its accompanying language file <code>data/lang/modules-donatetocranks/en.json</code>, or the Advice module <code>data/modules/Advice/Advice.lua</code> and <code>data/lang/modules-advice/en.json</code>.

Interacting with the player: BBS forms

2025-11-08T17:54:54Z

Zonkmachine: /* The BBS form */ Always one button

The bulletin board system is currently the only place where real dialogue between a script and the player can take place. Bulletin boards can exist within any <code>SpaceStation</code> in the current system. They are created in a station the first time that a ship is either spawned, or lands, in that station. They continue to exist until the player leaves the system or quits the game. They are not saved in saved games, although a saved game contains information about which ones did exist.

When a bulletin board is created, the <code>onCreateBB</code> event is triggered, and passes the <code>SpaceStation</code> body in which that bulletin board was created. There is an exception to this: The event is not triggered after loading a game for those bulletin boards which, having existed at the time of saving, are re-created. The consequences of this will be covered later (see "[[Surviving a reload]]").

There are two components to any mission's entry on a bulletin board: The advert and the form. The advert is the part that is displayed on the main bulletin board list, along with all the other entries. The form is the part that appears on screen when the player clicks the advert's button.

==The BBS advert==

Adverts are placed onto a BBS by calling the station's <code>AddAdvert()</code> method, once the bulletin board has been created. Depending on the nature of your script, you might want to always place one advert on every station (as seen with the Breakdowns & Servicing script), or you might want to place an arbitrary number of adverts on a given station (as seen with deliveries, or assassinations).

The opportunities to add an advert are presented by two events. <code>onCreateBB</code> is the obvious one; there is also <code>onUpdateBB</code>, which is called for all existing bulletin boards in the current system, approximately once every hour or two. The actual interval is not particularly predictable.

The <code>AddAdvert()</code> method takes three arguments. The first is the text that will appear on the advert. The second is the function that will be called when the player clicks the advert. The third is optional, and is a function that can be called when the advert is deleted for any reason.

<code>AddAdvert()</code> returns a reference number, which can subsequently be used to remove the advert using <code>RemoveAdvert()</code>. It represents the number of times a module has generated an advert on a specific station. If no ads has been removed it will be equal to the number of ads on the station.

It's the job of the scripter to decide how many, if any, adverts to add to a bulletin board when <code>onCreateBB</code> is triggered, and whether to add or remove any when <code>onUpdateBB</code> is triggered. Tests could include the population of the system, the type of starport or the type of planet. In the future, tests will be able to include the government type of the system.

One important thing to bear in mind is that the script cannot query a bulletin board to find out what adverts already exist. Each script must carefully track each advert that it has created if it is to have any control over how long they remain, and to be able to re-create them after a reload.

Here is an example of adding an advert. The effect of clicking the advert is simply to send a message to the player console with the name of the station and the reference number, which is one in this case as we're only generating one advert. Furthermore, the advert is only added if the station is in space. There is no mission here, it is simply to illustrate the mechanics of adding an advert. Launch Pioneer and choose a new game with start on Barnard's star.

local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

if station.type == 'STARPORT_ORBITAL' then
ref = station:AddAdvert('Need the name of this station?',sendStationName)
end
end

Event.Register("onCreateBB", onCreateBB)

This code will create an advert:

[[File:BBS1.png]]

Looking at the image, you will notice that the advert has appeared at the top of the bulletin board and that only one of two fields is filled with text. The BBS ad has two components, the '''title''' on top and the '''description'''. Only the description is present and since the BBS posts are sorted on first the title and secondly on the description, since the title is blank the post will show up on top. The icon used is the default. '''AddAdvert''' has two versions and we used a simpler legacy form. See

-- Legacy form
ref = station:AddAdvert(description, onChat, onDelete)

Clicking on the advert causes this to happen:

[[File:BBS2.png]]

Even though the only thing our function did was to send a message to the console, you can see that Pioneer automatically created a form for our advert. The only control is the 'Hang up' button.

Going back to the World View you can see the message on the Comms terminal:

[[File:BBS3.png]]

==More AddAdvert()==

As we saw, the legacy form of '''AddAdvert''' created an add that lacked a title and with a default icon. Lets rewrite the example above in the full form. [https://codedoc.pioneerspacesim.net/index.html#LuaClass:SpaceStation:AddAdvert LuaClass:SpaceStation:AddAdvert].

AddAdvert takes a table as argument.
ref = station:AddAdvert({
description = description,
icon = icon,
onChat = onChat,
onDelete = onDelete,
isEnabled = isEnabled,
})

Let's try the earlier example but simplified a bit to run on all stations.
local Event = require "Event"
local Comms = require "Comms"

local ref -- Variable to save the advert's reference number

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label .. "\n" .. "Add ref number: " .. ref)
end

ref = station:AddAdvert({
title = 'STATION NAME',
description = 'Need the name of this station?',
icon = 'news',
onChat = sendStationName,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

The ad now looks complete. It will also show up on the BBS sorted on the title.

[[File:BBS5.png]]

==The BBS form==

Once the player has clicked on an advert, they are presented with a form. Each advert has only one form. The content of the form is added by the script, and can be modified at any time. It consists of a title, a face, a message, and one or more clickable options. The 'one' being the <code>Hang up</code> button that is generated automatically and always is present. The form itself is passed to the function specified in the <code>SpaceStation.AddAdvert()</code> method. In the example above, that function would be <code>sendStationName()</code>, which simply ignored any parameters sent to it. This resulted in the form being blank. The form object which is passed to this function has methods for adding the content. <code>SetTitle()</code> and <code>SetMessage()</code> each accept a string. <code>SetFace()</code> takes a table of information which defines the photofit face on the left but in the following example <code>SetFace()</code> is called without any arguments and the face will therefore be completely randomized.

A minimal example without any clickable options, just the default 'Hang up':

local Event = import("Event")

local populateForm = function (form)
form:SetTitle('This appears above the face picture')
form:SetFace()
form:SetMessage([[This is the main message.

It is normally a multi-line string.]])
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'AD TITLE',
description = 'This appears in the advert list',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

As before, an advert was created:

[[File:BBS4.png]]

We have clicked on the ad and can see that <code>populateForm</code> was called, and it successfully filled the form with content. If you 'hang up' and press the ad again a completely new face is generated. Lets improve on this and make the face persistent for the existence of the advert. Making it reappear in a saved game would take some more work (see "[[Surviving a reload]]").

local Character = require "Character"
local Event = require "Event"

local client = {}
local message

local populateForm = function (form)
form:SetTitle('Pizza time!')
form:SetFace(client)
form:SetMessage(message)
end

local onCreateBB = function (station)

client = Character.New()
message = "I'm " .. client.name .. " and I need some pizza. I'm thinking pepperoni and cheeze. You feelin me?"

station:AddAdvert({
title = 'PIZZA PARTY!',
description = 'Special delivery needed',
icon = 'news',
onChat = populateForm,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

We introduce a new module ''' '[https://codedoc.pioneerspacesim.net/#LuaClass:Character Character]' ''' which basically is an RPG style character sheet with methods to work with it. It's a tool to generate and work with non-player characters (NPC's). <code>client = Character.New()</code> sets client to an all new character with basic characteristics, name, title, and looks. A character can be sent directly to the SetFace method and that's what we're after here. We also used the 'clients' name.

==Adding options to the form==

In the example above, we created a function named <code>populateForm()</code> which was run when the advert button was clicked. That's not the only time it can be run; it is also run whenever options on its form are clicked. To make use of this, it is passed two additional parameters, both of which <code>populateForm()</code> ignored. The first parameter is the form object, the second is the advert's unique reference and the third is the number of the option that was clicked. Because it handles all chat events, by convention we instead name this function <code>onChat()</code>, which is how it shall be named from now on.

In the first example that called the function 'sendStationName' we caught the reference number from ''' 'AddAdvert()' ''' in a variable named ''' 'ref' '''. As you may remember, ''' 'AddAdvert()' ''' takes two arguments; A string and a function. The function is passed three arguments. The second of these arguments is the reference number so we could have picked it up from within ''' 'sendStationName' '''. The ''' 'ref' ''' number is useful if your script adds several adverts, each of which might have slightly differently worded content.

You've already learned the methods: ''' 'SetTitle()' ''', ''' 'SetMessage()' ''', and ''' 'SetFace()' '''. Let's add the rest of the form() methods: 
* ''' form:AddOption() ''': adds clickable options with buttons. It takes two arguments: A string to set the text of the button and the option nr that will be sent to the form. This value is 0 when first called from the BBS by clicking the add. Every option form will have a default 'Hang up' option which returns -1. 
* ''' form:Clear() ''': removes the Message and Options, but preserves the Title and Face. 
* ''' form:Close() ''': Closes the form. 
* ''' form:RemoveAdvertOnClose() ''': Closes the form and removes the ad. 

Form options are declared like this:

form:AddOption('I am option one',1)
form:AddOption('I am option two',2)

These options will appear with the specified caption, and will call <code>onChat()</code>, which will receive the form object, the advert reference and the option number that was specified after the caption in <code>AddOption()</code>.

The onChat function below is adapted from an earlier example from the codedoc:

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

-- option 0 is called when the form is first activated from the
-- bulletin board
if option == 0 then

form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)

return
end

-- option 1 - red
if option == 1 then
form:SetMessage("Ahh red, the colour of raspberries.")
return
end

-- option 2 - green
if option == 2 then
form:SetMessage("Ahh green, the colour of trees.")
return
end

-- option 3 - blue
if option == 3 then
form:SetMessage("Ahh blue, the colour of the ocean.")
return
end

-- only option left is -1, hang up
form:Close()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Here, every time <code>onChat()</code> is called, regardless of the specified option, the form is cleared. The option is checked, and the relevant content is added to the form. Any other functions can be called from here, and this is how the script gets input from the player.

An alternative format might be this:

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()

local options = {
[0] = function ()
form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Blue", 3)
end,
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
end,
[2] = function ()
form:SetMessage("Ahh green, the colour of trees.")
end,
[3] = function ()
form:SetMessage("Ahh blue, the colour of the ocean.")
end,
[-1] = function ()
form:Close()
end
}
options[option]()
end

local onCreateBB = function (station)
station:AddAdvert({
title = 'COLORS',
description = "Let's talk colors!",
icon = 'news',
onChat = onChat,
onDelete = onDelete,
})
end

Event.Register("onCreateBB", onCreateBB)

Try this out:

* To understand what ''' 'form:Clear()' ''' does, comment out the line above containing it and restart Pioneer. As the form is no longer cleared and the 'Hang up' button is included automatically, there now appears to be only one form. The color selection buttons still works though.

* Try adding 'Go back' buttons from the color options:
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
form:AddOption("Go back", 0)
end,

* Try both suggestions above at the same time. ''' 'form:Clear()' ''' is your friend.

* Stick this code into the second onChat example above (or adopt it to the first one) to try out ''' 'form:RemoveAdvertOnClose()' ''':
form:AddOption("Report post", 4) -- In option[0]

-- ...

[4] = function ()
form:SetMessage("The ad has been reported and will not be shown on your BBS. " ..
"Thank you for helping us to improve Haber Connect!")
form:RemoveAdvertOnClose()
end,

==Where to go from here==
To see simple complete examples of BBS interaction used in the game, look in <code>data/modules/DonateToCranks/DonateToCranks.lua</code>, and its accompanying language file <code>data/lang/modules-donatetocranks/en.json</code>, or the Advice module <code>data/modules/Advice/Advice.lua</code> and <code>data/lang/modules-advice/en.json</code>.

Mods

2025-10-23T17:25:32Z

Zonkmachine: /* List of known Mods */

== Available Mods ==

=== How to install Mods ===

Since Alpha 22, Pioneer has had support for modding. This is done by allowing core game data to be added to or given preference by data in your userdir (that is, <code>'My Docs/Pioneer/mods'</code> for Windows, <code>'~/.pioneer/mods'</code> for Linux, and <code>'~/Library/Application Support/Pioneer/mods'</code> for OSX).

Once you have downloaded a mod, you simply place the .zip file in the /mods folder described above. There is no need to extract the files.

If a file in a .zip is identically named with one found in the Main pioneer/data directory, the version in the .zip will be used. You can use this fact to easily modify the core game files of Pioneer

This method can be used for any file under the main Pioneer/data directory and applies to ships, buildings and stations, systems, music, fonts, textures, whatever.

However, there are still some mods not packaged in the mod format (.zip). Overtime these are being repackaged by members of the Pioneer community, but in case you have a mod that is not in the correct format then the data in these style of mods must be placed in the correct folder within your main Pioneer/data directory and not in the mods directory described above. But be warned, make a back up of the files you are about to overwrite as this can not be undone and if you do want to return to a 'vanilla' Pioneer, you will have to re-install Pioneer.

== List of known Mods ==

Overtime all the mods here can also be found on the Pioneer Mods page at sourceforge https://sourceforge.net/projects/modsforpioneer/files/Alpha%2030%20mods/

{| class="wikitable"
|+Current known Mod Packages
|-
!Mod Name
!Mod Description
!Author(s)
!Version
!Tested with Pioneer*
!Size
!Download link
|-
|Skyboxes
|Seven new skyboxes, ranging from slight variations on the Milky Way backdrop to spectacular nebulae.
|[https://github.com/pebblegarden pebblegarden]
|0.1
|20250203
|12 mb
|[https://www.dropbox.com/scl/fi/cbzretcjuvgg2sxjivjcq/pebblegarden-skyboxes-v0.1.zip?rlkey=74byb7c1phsgqhx4jpvi6vet5&st=jk13ntui&dl=0 skyboxes]
|-
|Retro ships
|A mod containing the original versions of four reworked OPLI ships: Amphiesma, Xylophis, Sinonatrix and Natrix.
|[https://github.com/Maks2103 Maks2103]
|0.7
|20250203
|2.19 mb
|[https://www.dropbox.com/scl/fi/fx4w9j1nvo7ydevgb33rh/retro-0.7.zip?rlkey=0wu609kk5isv4r7v1p1u9wcgo&st=bsbf0epi&dl=0 retro ships]
|-
|Retro ships
|A mod containing the original versions of three reworked OPLI ships: Amphiesma, Xylophis and Sinonatrix.
|[https://github.com/Maks2103 Maks2103]
|0.6
|20240710
|2.19 mb
|[https://www.dropbox.com/scl/fi/wf2r59dzr2sfvfwto812x/retro-0.6.zip?rlkey=cqlbhf4ctkm5cztzedt65sgvy&e=1&st=phbzmg0k&dl=0 retro ships]
|-
|ARGH's original unabridged Extend Sol
|The original unabridged version of extended Sol, with additional dwarfs, many more major asteroids and a high populated system
|ARGHouse
|1.3.1
|20210818
|65.7 kb
|[https://drive.google.com/file/d/1NGTbK1xLdjY4NkN92FtvZc5L6seXlgvW/view?usp=sharing]
|-
|Sol Extended
|Extends the Sol system with additional dwarf planets and spaceports.
|EpsilonEridani
|Work-In-Progress
|20210818
|25.5 kb
|[https://libera.ems.host/_matrix/media/r0/download/matrix.org/BJozxFpJFXnoHiRMQNqpVPiG/00_sol_extended.lua 00_sol_extended.lua]
|-
|Honk
|A simple mod which gives the player the ability to sound various car or ship horns.
|[[User:WKFO|WKFO]]
|1.0
|2021-02-03
|~60 kb
|[https://www.dropbox.com/s/nq0rh3dexibi0pe/honk.zip?dl=0]
|-
|Monolithic Carrier
|A not-that-big bulk cargo ship by Haber Corporation.
|[[User:WKFO|WKFO]]
|0.9
|2022-02-03
|3.3 MB
|[https://www.dropbox.com/s/n2gyaqbt9e5xe79/monocarrier.zip?dl=0]
|-
|Graveyard
|Example of bundling multiple files in a mod. Adds a custom system "Graveyard" (up and to the right of Sol) and a script that does something when you jump there.
|[[User:RobN|RobN]]
|1.0
|20131229
|1kb
|[http://eatenbyagrue.org/f/pioneer/graveyard.zip graveyard.zip]
|-
|RedSol
|Example of replacing a core file. Replaces the system def for Sol with one that has a red star.
|[[User:RobN|RobN]]
|1.0
|Alpha22
|1kb
|[http://eatenbyagrue.org/f/pioneer/redsol.zip redsol.zip]
|-
|Skyboxes
|Nebula backgrounds when in space
|[https://spacesimcentral.com/community/pioneer/i-dont-like-the-skybox/#post-46527 pebblegarden]
|1.0
|2015
|8Mb
|[http://spacesimcentral.com/ssc/index.php?app=core&module=attach&section=attach&attach_id=2563]
|-
|Lanner ship
|The Lanner ship
|unclear
|1.0
|2015
|1.58 Mb
|[https://spacesimcentral.com/community/pioneer-mods/lanner-for-current-pioneer-build/#post-4439]
|-
|-
|Vuzz's Milkyway skybox
|Vuzz's skybox is the most realistic version of the Milky Way for Pioneer.
|[[User:impaktor|impaktor]]
|
|20150912
|1.34MB
|[https://spacesimcentral.com/community/pioneer-mods/vuzzs-milky-way-skybox-mod/#post-4460]
|-
|Moon Heightmap
|Higher res heightmap which replaces the 2mb default heightmap.
|Ae-2222
|1.0
|Alpha26 - - (all current versions)
|33Mb
|[http://wikisend.com/download/359748/moon-hi-res-heightmap.zip moon-hi-res-heightmap.zip]
|-
|Character Generator Upgrade (facegen mod)
|A small upgrade that adds some new hair, eyes, clothing, uniforms, additional accessories and other improvements to the existing character generator.
|[[User:baobobafet|baobobafet]]
|1.1
|Compatible with most as well as current v20140217
|8Mb
|[http://www.mediafire.com/download/pr55p4r7g87s9uf/facegen_mod_bao_pioneer20140205_bao_V1.1.zip]
|-
|Wave Explorer (ship mod) includes 2 custom pilots
|HiRes2048x2048_Wave-e -see info below or visit https://forum.pioneerspacesim.net/viewtopic.php?f=3&t=89
|[[User:baobobafet|baobobafet]]
|3.5
|v20140217 - (all current versions)
|18Mb
|[http://www.mediafire.com/download/s7d4rqk2fio9gwu/Ship2048x2048_wave-e-w-pilots_bao_pioneer20140217_bao_V3.5.zip]
|-
|-
|Wave Explorer (ship mod) includes 2 custom pilots
|LoRes1024x1024 version of the Wave-e (for increased graphics performance on lower end systems) see info below or visit: https://forum.pioneerspacesim.net/viewtopic.php?f=3&t=89
|[[User:baobobafet|baobobafet]]
|3.5
|v20140217 - (all current versions)
|8Mb
|[http://www.mediafire.com/download/dgxjgo2tf7dgob3/Ship1024x1024_wave-e-w-pilots_bao_pioneer20140217_bao_V3.5.zip]
|-
|-
|Apollo LEM Lunar orbit save file for Alpha26
|Low fuel LEM landing challenge (-w- cargo to jettison) 3 saves with Lunar lander in unpowered orbit over moon with low fuel(requires HighRes.Moon_Apollo.LEM.a26Mod)
|[[User:baobobafet|baobobafet]]
|1.0
|Alpha26
|520kb
|[http://www.mediafire.com/?sy5d6i4n8vz10c4]
|-
|Interstellar Shuttle 1700
|Adds a modified version of the standard shuttle to the ship roster with hyperdrive capability, ecm, missile, cargo/fuel scoop options and more cargo space.(includes a new shuttle skin and solar array for bottom of existing standard shuttle (readme inside zip file)
|[[User:baobobafet|baobobafet]]
|1.3
|Alpha 30
|3560kb
|[http://www.mediafire.com/?46ci6m4677y5wg3]
|-
|Enterprise 1701a (static ship)
|Replaces the Long Range Cruiser (static Ship) with the NCC 1701a "Enterprise" at realistic scale. (readme inside zip file)
|[[User:baobobafet|baobobafet]]
|1.2
|Alpha 30
|1.78mb
|[http://www.mediafire.com/?g4ng4dk46kdns8v]
|-
|-
|Ship Decals Mod 256x256
|This is version 4.0 - includes 8 ship decals. IMAGE here: http://img708.imageshack.us/img708/7146/decalsversion4.png
|[[User:baobobafet|baobobafet]]
|4.0
|Alpha 27-30
|3mb
|[http://www.mediafire.com/?14bchs29dn06nn2]
|-
|-
|-
|Controller Templates
|Not really a Mod - This is for people who have - or are familiar with either Xpadder, 3D Pro Joystick or the G-13 Gameboard. Extreme 3D Pro Joystick Xpadder profile and G-13 gameboard Basic Template - printable key & joystick button reference. Version 3 (More info see above)
|[[User:baobobafet|baobobafet]]
|3.0
|Most Alphas up to 26
|4490kb
|[https://docs.google.com/open?id=0B5dK9aniVGUnM09GRU1qVFJWemM] [http://www.mediafire.com/?ncnh6bpdvna34n2]
|-
|-
|3DPro Joystick Profile
|This is an update supporting the new view keys, for Extreme 3D Pro Joystick Xpadder profile with Template - printable joystick button reference. Version 5 (see pic: http://imageshack.us/a/img822/864/ztf.png )
|[[User:baobobafet|baobobafet]]
|5.0
|Alphas after 28 (all current versions)
|2.31mb
|[http://www.mediafire.com/?btgkn3sjx0ianuu]
|-
|-
|Pioneer default keyboard reference
|In pdf printable format(see PNG pic: http://img203.imageshack.us/img203/2079/5dh.png )
|[[User:baobobafet|baobobafet]]
|v201305.93bao
|Alphas after 28(all current versions)
|7.3mb
|[http://www.mediafire.com/?y5a2sapya7vfhhr]
|-
|-
|Pioneer custom mouse pointers
|Small simple mods containing only custom mouse pointers
|[[User:Joonicks|joonicks]]
|
|20151001
|1-4kb
|[http://joonicks.eu/pioneer_mods]
|}

*'' Version number represents what the module was tested/built against. There is no guarantee that it will work for later versions.''

== List of known Mod Compilations ==

{| class="wikitable"
|+Current known Mod Compilation Packages
|-
!Mod Name
!Mod Description
!Author(s)
!Version
!Tested with Pioneer*
!Size
!Download link
|-
|HiRes Moon & Apollo LEM Mod
|High res Moon heightmap & flyable Apollo Eagle Lander with docs & nav maps.
|contrib by Ae-2222 & [[User:baobobafet|baobobafet]]
|2.0
|Alpha 30
|35.3Mb
|[https://docs.google.com/open?id=0B4TOJEZxkYiVUGZqVklKVEE0WUE]
|}

*'' Version number represents what the module compilation was tested/built against. There is no guarantee that it will work for later versions.''

'''''The who/when/where for mod storage/testing/package compilation is still to be established. As with all things concerning Pioneer it is up to interested parties to resolve this. There is the beginnings of a discussion on the [[Talk:Mods|discussion page]] as not everyone is on the mailing list yet (another could be started on a specific task page if anyone wants to). You need to register to edit pages and contribute.'''''

== Creating A New Ship Mod ==
This is in response to the couple of people who are interested in doing art, perhaps even leading the direction it can go in.

For programmers there's a path which involves creating a GitHub account, forking the Pioneer repository, creating branches, configuring remotes, making commits and submitting Pull Requests.

For Artists and scripters there's another way which is hopefully preferrable for everyone!

To follow this "tutorial" you'll need at least a way of creating ".zip" files, on Windows I use the 7-zip program.

This example is being written for Windows but the ideas are broadly transferrable even if the exact file paths and locations aren't.

=== MyFirstShip mod ===
There's links to a few existing mods above but they're very simple things:
* They're just zip files containing some directories and files,
* Their contents are "Added" to Pioneer unless replace something like a script, ship, texture, etc,
* They use the same directory structure as Pioneer.
The example that most players are enthusiastic about is adding a new ship which is the first step on the long road to a total conversion!

(For additional information see: [https://wiki.pioneerspacesim.net/wiki/Making_your_first_ship Making_your_first_ship] )

To start with we want to make this task easy for ourselves so lets try the following to create a "mod" called "myfirstship":
* Go to wherever you've extracted your Pioneer download to,
* Open the folder "data" and look down the folder names as there's two we're interested in,
** "ships" and "models",
* open the "ships" folder,
** copy and rename the file "wave.lua" to "myfirstship.lua",
** open the file in a text editor and change the following lines like so
*** from: name='Wave Heavy Hypersonic Fighter'
*** from: model='wave',
*** To: name='My First Ship Tutorial'
*** To: model='myfirstship',
*** save your changes to the "myfirstship.lua" file,
*** now go back up to the data folder,
* open the "models" folder, then the "ships" folder,
** copy and rename the folder "wave" to "myfirstship",
** open the "myfirstship" folder,
*** rename the file "wave.model" to "myfirstships.model",
Now run Pioneer with the parameter "-mv myfirstship" so the command line should look like "pioneer.exe -mv myfirstship" this will open it in the modelviewer mode so you can see if everything has worked.

If you run Pioneer as usual then you should be able to go to the ship yard and buy your very own "My First Ship Tutorial" spaceship. Of course it will look like the Wave heavy Hypersonic Fighter, and it will handle like it and be like it in every possible way because it's a perfect copy of it

If you want to make it look different so it's easier to spot then a quick thing you can do is edit the texture "wave.png" in your "/data/models/ships/myfirstship/" folder, perhaps just paint the white a bright red or something which will make it easy to tell that you've changed it.

Obviously we're not done turning all this effort into a mod yet, we've just copied a ship definition ("myfirstship.lua") and the model data for it.

So lets open a new folder window (if on Windows) and:
* Create a new folder somewhere you won't lose it, "My Documents" for windows users or the home folder on Linux etc, call it "tutorial" this time (to avoid confusion),
* In this folder create two more called "ships" and "models",
* With the "models" folder create another folder called "ships",
* by now you should have something that looks like:
** /tutorial/ships/
** /tutorial/models/ships/
* now you're going to _move_ the "myfirstships.lua" file you edited earlier out of the "/pioneer/data/ships/" into the folder "/tutorial/ships/" folder,
* next you must _move_ the folder "myfirstship" from "/pioneer/data/models/ships/" to "/tutorial/models/ships/",
* now create a "readme.txt" file in the "tutorial" folder and add your name to it for now,
* Add everything inside the "tutorial" folder to a zip archive - to do this with 7-zip just selected everything inside the tutorial folder, right-click, open the 7-zip submenu and choose the "Add to archive",
* Make sure that you choose to use "zip" compression and call the archive "myfirstship.zip".
* Finally, put the file "myfirstship.zip" into the "mods" directory - this IS NOT usually where you extracted the Pioneer download.
** On Windows it will be in a folder under your "My Documents"/"Documents" directory for example:
*** "/My Documents/Pioneer/mods/"
* Now double check that you really did MOVE the files and folders, i.e; go back to where you first copied the wave files and folders and make sure that there aren't any "myfirsthip" files or folder there because they should now all be inside the zip file (and safely backed up in the "tutorial" folder).
** The reason this step is important is that you might have made a mistake with the zipping process and the mod is actually now broken, however it will look like it works because the original files are still being found by Pioneer in it's own data directory.
* Finally, the mod should have been packaged up into a zip, it should be in the "mods" directory, and you've made sure the Pioneer data folder is clean.
* Run Pioneer and make sure your mod works.

There are many steps that take just a second or two and lots of bits you can skip once you know what you're doing.

You can have as many ships within a single mod as you like, this technique just gives you a copy of the Wave to edit and play with.

You can, and should, replace it with your own mesh and edit the parameters it uses for thrust and equipment etc.

=== So how does this get my ships into the Pioneer download? ===
Easy, you create your mod, test it, try it out, share it via this forums download area so that others can play it, respond to criticisms to improve it and then ask the Core Team to include it in the main distribution.

This is basically the same process that we go through for programmers submissions but without having to understand Git and GitHub.

It's also more direct to players and fans of the game who often use several mods together to make Pioneer play how they want it too.

Mods

2025-05-09T15:56:53Z

Zonkmachine: /* List of known Mods */ layout fixup

== Available Mods ==

=== How to install Mods ===

Since Alpha 22, Pioneer has had support for modding. This is done by allowing core game data to be added to or given preference by data in your userdir (that is, <code>'My Docs/Pioneer/mods'</code> for Windows, <code>'~/.pioneer/mods'</code> for Linux, and <code>'~/Library/Application Support/Pioneer/mods'</code> for OSX).

Once you have downloaded a mod, you simply place the .zip file in the /mods folder described above. There is no need to extract the files.

If a file in a .zip is identically named with one found in the Main pioneer/data directory, the version in the .zip will be used. You can use this fact to easily modify the core game files of Pioneer

This method can be used for any file under the main Pioneer/data directory and applies to ships, buildings and stations, systems, music, fonts, textures, whatever.

However, there are still some mods not packaged in the mod format (.zip). Overtime these are being repackaged by members of the Pioneer community, but in case you have a mod that is not in the correct format then the data in these style of mods must be placed in the correct folder within your main Pioneer/data directory and not in the mods directory described above. But be warned, make a back up of the files you are about to overwrite as this can not be undone and if you do want to return to a 'vanilla' Pioneer, you will have to re-install Pioneer.

== List of known Mods ==

Overtime all the mods here can also be found on the Pioneer Mods page at sourceforge https://sourceforge.net/projects/modsforpioneer/files/Alpha%2030%20mods/

{| class="wikitable"
|+Current known Mod Packages
|-
!Mod Name
!Mod Description
!Author(s)
!Version
!Tested with Pioneer*
!Size
!Download link
|-
|Skyboxes
|Seven new skyboxes, ranging from slight variations on the Milky Way backdrop to spectacular nebulae.
|[https://github.com/pebblegarden pebblegarden]
|0.1
|20250203
|12 mb
|[https://www.dropbox.com/scl/fi/cbzretcjuvgg2sxjivjcq/pebblegarden-skyboxes-v0.1.zip?rlkey=74byb7c1phsgqhx4jpvi6vet5&st=jk13ntui&dl=0 skyboxes]
|-
|Retro ships
|A mod containing the original versions of four reworked OPLI ships: Amphiesma, Xylophis Sinonatrix and Natrix.
|[https://github.com/Maks2103 Maks2103]
|0.7
|20250203
|2.19 mb
|[https://www.dropbox.com/scl/fi/fx4w9j1nvo7ydevgb33rh/retro-0.7.zip?rlkey=0wu609kk5isv4r7v1p1u9wcgo&st=bsbf0epi&dl=0 retro ships]
|-
|Retro ships
|A mod containing the original versions of three reworked OPLI ships: Amphiesma, Xylophis and Sinonatrix.
|[https://github.com/Maks2103 Maks2103]
|0.6
|20240710
|2.19 mb
|[https://www.dropbox.com/scl/fi/wf2r59dzr2sfvfwto812x/retro-0.6.zip?rlkey=cqlbhf4ctkm5cztzedt65sgvy&e=1&st=phbzmg0k&dl=0 retro ships]
|-
|ARGH's original unabridged Extend Sol
|The original unabridged version of extended Sol, with additional dwarfs, many more major asteroids and a high populated system
|ARGHouse
|1.3.1
|20210818
|65.7 kb
|[https://drive.google.com/file/d/1NGTbK1xLdjY4NkN92FtvZc5L6seXlgvW/view?usp=sharing]
|-
|Sol Extended
|Extends the Sol system with additional dwarf planets and spaceports.
|EpsilonEridani
|Work-In-Progress
|20210818
|25.5 kb
|[https://libera.ems.host/_matrix/media/r0/download/matrix.org/BJozxFpJFXnoHiRMQNqpVPiG/00_sol_extended.lua 00_sol_extended.lua]
|-
|Honk
|A simple mod which gives the player the ability to sound various car or ship horns.
|[[User:WKFO|WKFO]]
|1.0
|2021-02-03
|~60 kb
|[https://www.dropbox.com/s/nq0rh3dexibi0pe/honk.zip?dl=0]
|-
|Monolithic Carrier
|A not-that-big bulk cargo ship by Haber Corporation.
|[[User:WKFO|WKFO]]
|0.9
|2022-02-03
|3.3 MB
|[https://www.dropbox.com/s/n2gyaqbt9e5xe79/monocarrier.zip?dl=0]
|-
|Graveyard
|Example of bundling multiple files in a mod. Adds a custom system "Graveyard" (up and to the right of Sol) and a script that does something when you jump there.
|[[User:RobN|RobN]]
|1.0
|20131229
|1kb
|[http://eatenbyagrue.org/f/pioneer/graveyard.zip graveyard.zip]
|-
|RedSol
|Example of replacing a core file. Replaces the system def for Sol with one that has a red star.
|[[User:RobN|RobN]]
|1.0
|Alpha22
|1kb
|[http://eatenbyagrue.org/f/pioneer/redsol.zip redsol.zip]
|-
|Skyboxes
|Nebula backgrounds when in space
|[https://spacesimcentral.com/community/pioneer/i-dont-like-the-skybox/#post-46527 pebblegarden]
|1.0
|2015
|8Mb
|[http://spacesimcentral.com/ssc/index.php?app=core&module=attach&section=attach&attach_id=2563]
|-
|Lanner ship
|The Lanner ship
|unclear
|1.0
|2015
|1.58 Mb
|[https://spacesimcentral.com/community/pioneer-mods/lanner-for-current-pioneer-build/#post-4439]
|-
|-
|Vuzz's Milkyway skybox
|Vuzz's skybox is the most realistic version of the Milky Way for Pioneer.
|[[User:impaktor|impaktor]]
|
|20150912
|1.34MB
|[https://spacesimcentral.com/community/pioneer-mods/vuzzs-milky-way-skybox-mod/#post-4460]
|-
|Moon Heightmap
|Higher res heightmap which replaces the 2mb default heightmap.
|Ae-2222
|1.0
|Alpha26 - - (all current versions)
|33Mb
|[http://wikisend.com/download/359748/moon-hi-res-heightmap.zip moon-hi-res-heightmap.zip]
|-
|Character Generator Upgrade (facegen mod)
|A small upgrade that adds some new hair, eyes, clothing, uniforms, additional accessories and other improvements to the existing character generator.
|[[User:baobobafet|baobobafet]]
|1.1
|Compatible with most as well as current v20140217
|8Mb
|[http://www.mediafire.com/download/pr55p4r7g87s9uf/facegen_mod_bao_pioneer20140205_bao_V1.1.zip]
|-
|Wave Explorer (ship mod) includes 2 custom pilots
|HiRes2048x2048_Wave-e -see info below or visit https://forum.pioneerspacesim.net/viewtopic.php?f=3&t=89
|[[User:baobobafet|baobobafet]]
|3.5
|v20140217 - (all current versions)
|18Mb
|[http://www.mediafire.com/download/s7d4rqk2fio9gwu/Ship2048x2048_wave-e-w-pilots_bao_pioneer20140217_bao_V3.5.zip]
|-
|-
|Wave Explorer (ship mod) includes 2 custom pilots
|LoRes1024x1024 version of the Wave-e (for increased graphics performance on lower end systems) see info below or visit: https://forum.pioneerspacesim.net/viewtopic.php?f=3&t=89
|[[User:baobobafet|baobobafet]]
|3.5
|v20140217 - (all current versions)
|8Mb
|[http://www.mediafire.com/download/dgxjgo2tf7dgob3/Ship1024x1024_wave-e-w-pilots_bao_pioneer20140217_bao_V3.5.zip]
|-
|-
|Apollo LEM Lunar orbit save file for Alpha26
|Low fuel LEM landing challenge (-w- cargo to jettison) 3 saves with Lunar lander in unpowered orbit over moon with low fuel(requires HighRes.Moon_Apollo.LEM.a26Mod)
|[[User:baobobafet|baobobafet]]
|1.0
|Alpha26
|520kb
|[http://www.mediafire.com/?sy5d6i4n8vz10c4]
|-
|Interstellar Shuttle 1700
|Adds a modified version of the standard shuttle to the ship roster with hyperdrive capability, ecm, missile, cargo/fuel scoop options and more cargo space.(includes a new shuttle skin and solar array for bottom of existing standard shuttle (readme inside zip file)
|[[User:baobobafet|baobobafet]]
|1.3
|Alpha 30
|3560kb
|[http://www.mediafire.com/?46ci6m4677y5wg3]
|-
|Enterprise 1701a (static ship)
|Replaces the Long Range Cruiser (static Ship) with the NCC 1701a "Enterprise" at realistic scale. (readme inside zip file)
|[[User:baobobafet|baobobafet]]
|1.2
|Alpha 30
|1.78mb
|[http://www.mediafire.com/?g4ng4dk46kdns8v]
|-
|-
|Ship Decals Mod 256x256
|This is version 4.0 - includes 8 ship decals. IMAGE here: http://img708.imageshack.us/img708/7146/decalsversion4.png
|[[User:baobobafet|baobobafet]]
|4.0
|Alpha 27-30
|3mb
|[http://www.mediafire.com/?14bchs29dn06nn2]
|-
|-
|-
|Controller Templates
|Not really a Mod - This is for people who have - or are familiar with either Xpadder, 3D Pro Joystick or the G-13 Gameboard. Extreme 3D Pro Joystick Xpadder profile and G-13 gameboard Basic Template - printable key & joystick button reference. Version 3 (More info see above)
|[[User:baobobafet|baobobafet]]
|3.0
|Most Alphas up to 26
|4490kb
|[https://docs.google.com/open?id=0B5dK9aniVGUnM09GRU1qVFJWemM] [http://www.mediafire.com/?ncnh6bpdvna34n2]
|-
|-
|3DPro Joystick Profile
|This is an update supporting the new view keys, for Extreme 3D Pro Joystick Xpadder profile with Template - printable joystick button reference. Version 5 (see pic: http://imageshack.us/a/img822/864/ztf.png )
|[[User:baobobafet|baobobafet]]
|5.0
|Alphas after 28 (all current versions)
|2.31mb
|[http://www.mediafire.com/?btgkn3sjx0ianuu]
|-
|-
|Pioneer default keyboard reference
|In pdf printable format(see PNG pic: http://img203.imageshack.us/img203/2079/5dh.png )
|[[User:baobobafet|baobobafet]]
|v201305.93bao
|Alphas after 28(all current versions)
|7.3mb
|[http://www.mediafire.com/?y5a2sapya7vfhhr]
|-
|-
|Pioneer custom mouse pointers
|Small simple mods containing only custom mouse pointers
|[[User:Joonicks|joonicks]]
|
|20151001
|1-4kb
|[http://joonicks.eu/pioneer_mods]
|}

*'' Version number represents what the module was tested/built against. There is no guarantee that it will work for later versions.''

== List of known Mod Compilations ==

{| class="wikitable"
|+Current known Mod Compilation Packages
|-
!Mod Name
!Mod Description
!Author(s)
!Version
!Tested with Pioneer*
!Size
!Download link
|-
|HiRes Moon & Apollo LEM Mod
|High res Moon heightmap & flyable Apollo Eagle Lander with docs & nav maps.
|contrib by Ae-2222 & [[User:baobobafet|baobobafet]]
|2.0
|Alpha 30
|35.3Mb
|[https://docs.google.com/open?id=0B4TOJEZxkYiVUGZqVklKVEE0WUE]
|}

*'' Version number represents what the module compilation was tested/built against. There is no guarantee that it will work for later versions.''

'''''The who/when/where for mod storage/testing/package compilation is still to be established. As with all things concerning Pioneer it is up to interested parties to resolve this. There is the beginnings of a discussion on the [[Talk:Mods|discussion page]] as not everyone is on the mailing list yet (another could be started on a specific task page if anyone wants to). You need to register to edit pages and contribute.'''''

== Creating A New Ship Mod ==
This is in response to the couple of people who are interested in doing art, perhaps even leading the direction it can go in.

For programmers there's a path which involves creating a GitHub account, forking the Pioneer repository, creating branches, configuring remotes, making commits and submitting Pull Requests.

For Artists and scripters there's another way which is hopefully preferrable for everyone!

To follow this "tutorial" you'll need at least a way of creating ".zip" files, on Windows I use the 7-zip program.

This example is being written for Windows but the ideas are broadly transferrable even if the exact file paths and locations aren't.

=== MyFirstShip mod ===
There's links to a few existing mods above but they're very simple things:
* They're just zip files containing some directories and files,
* Their contents are "Added" to Pioneer unless replace something like a script, ship, texture, etc,
* They use the same directory structure as Pioneer.
The example that most players are enthusiastic about is adding a new ship which is the first step on the long road to a total conversion!

(For additional information see: [https://wiki.pioneerspacesim.net/wiki/Making_your_first_ship Making_your_first_ship] )

To start with we want to make this task easy for ourselves so lets try the following to create a "mod" called "myfirstship":
* Go to wherever you've extracted your Pioneer download to,
* Open the folder "data" and look down the folder names as there's two we're interested in,
** "ships" and "models",
* open the "ships" folder,
** copy and rename the file "wave.lua" to "myfirstship.lua",
** open the file in a text editor and change the following lines like so
*** from: name='Wave Heavy Hypersonic Fighter'
*** from: model='wave',
*** To: name='My First Ship Tutorial'
*** To: model='myfirstship',
*** save your changes to the "myfirstship.lua" file,
*** now go back up to the data folder,
* open the "models" folder, then the "ships" folder,
** copy and rename the folder "wave" to "myfirstship",
** open the "myfirstship" folder,
*** rename the file "wave.model" to "myfirstships.model",
Now run Pioneer with the parameter "-mv myfirstship" so the command line should look like "pioneer.exe -mv myfirstship" this will open it in the modelviewer mode so you can see if everything has worked.

If you run Pioneer as usual then you should be able to go to the ship yard and buy your very own "My First Ship Tutorial" spaceship. Of course it will look like the Wave heavy Hypersonic Fighter, and it will handle like it and be like it in every possible way because it's a perfect copy of it

If you want to make it look different so it's easier to spot then a quick thing you can do is edit the texture "wave.png" in your "/data/models/ships/myfirstship/" folder, perhaps just paint the white a bright red or something which will make it easy to tell that you've changed it.

Obviously we're not done turning all this effort into a mod yet, we've just copied a ship definition ("myfirstship.lua") and the model data for it.

So lets open a new folder window (if on Windows) and:
* Create a new folder somewhere you won't lose it, "My Documents" for windows users or the home folder on Linux etc, call it "tutorial" this time (to avoid confusion),
* In this folder create two more called "ships" and "models",
* With the "models" folder create another folder called "ships",
* by now you should have something that looks like:
** /tutorial/ships/
** /tutorial/models/ships/
* now you're going to _move_ the "myfirstships.lua" file you edited earlier out of the "/pioneer/data/ships/" into the folder "/tutorial/ships/" folder,
* next you must _move_ the folder "myfirstship" from "/pioneer/data/models/ships/" to "/tutorial/models/ships/",
* now create a "readme.txt" file in the "tutorial" folder and add your name to it for now,
* Add everything inside the "tutorial" folder to a zip archive - to do this with 7-zip just selected everything inside the tutorial folder, right-click, open the 7-zip submenu and choose the "Add to archive",
* Make sure that you choose to use "zip" compression and call the archive "myfirstship.zip".
* Finally, put the file "myfirstship.zip" into the "mods" directory - this IS NOT usually where you extracted the Pioneer download.
** On Windows it will be in a folder under your "My Documents"/"Documents" directory for example:
*** "/My Documents/Pioneer/mods/"
* Now double check that you really did MOVE the files and folders, i.e; go back to where you first copied the wave files and folders and make sure that there aren't any "myfirsthip" files or folder there because they should now all be inside the zip file (and safely backed up in the "tutorial" folder).
** The reason this step is important is that you might have made a mistake with the zipping process and the mod is actually now broken, however it will look like it works because the original files are still being found by Pioneer in it's own data directory.
* Finally, the mod should have been packaged up into a zip, it should be in the "mods" directory, and you've made sure the Pioneer data folder is clean.
* Run Pioneer and make sure your mod works.

There are many steps that take just a second or two and lots of bits you can skip once you know what you're doing.

You can have as many ships within a single mod as you like, this technique just gives you a copy of the Wave to edit and play with.

You can, and should, replace it with your own mesh and edit the parameters it uses for thrust and equipment etc.

=== So how does this get my ships into the Pioneer download? ===
Easy, you create your mod, test it, try it out, share it via this forums download area so that others can play it, respond to criticisms to improve it and then ask the Core Team to include it in the main distribution.

This is basically the same process that we go through for programmers submissions but without having to understand Git and GitHub.

It's also more direct to players and fans of the game who often use several mods together to make Pioneer play how they want it too.

Missions and the mission list

2025-04-30T22:38:03Z

Zonkmachine: /* Registering a mission type */

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

We don't recommend using <code>Game.player.frameBody.path</code> here. We're only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.
local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function (ship, station)
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

Event.Register("onGameStart", onGameStart)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Taxi', l.TAXI)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Taxi', l.TAXI, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

Let's fixup the earlier example with it's own mission type and a working '''buildMissionDescription'''.

local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function ()
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

Mission.RegisterType('Test', 'Test', buildMissionDescription)
Event.Register("onGameStart", onGameStart)

[[File:Minimaldescription.png|1024px]]

That's basically it. Here follows a description of the elements you can add to '''buildMissionDescription'''. Try and expand our latest script on you own.

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.

Missions and the mission list

2025-04-30T07:08:12Z

Zonkmachine: /* The player's mission list */ I -> We

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

We don't recommend using <code>Game.player.frameBody.path</code> here. We're only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission type you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.
local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function (ship, station)
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

Event.Register("onGameStart", onGameStart)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Taxi', l.TAXI)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Taxi', l.TAXI, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

Let's fixup the earlier example with it's own mission type and a working '''buildMissionDescription'''.

local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function ()
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

Mission.RegisterType('Test', 'Test', buildMissionDescription)
Event.Register("onGameStart", onGameStart)

[[File:Minimaldescription.png|1024px]]

That's basically it. Here follows a description of the elements you can add to '''buildMissionDescription'''. Try and expand our latest script on you own.

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.

Strings and translation

2025-04-23T01:17:58Z

Zonkmachine: /* Lua Standard Library - String manipulation */

==Internationalization==
Recommended reading: [https://dev.pioneerspacesim.net/contribute/translations Pioneer translators wikipage]

It is important that scripters are familiar with the translation system. In the previous example '''hello_world.lua''' used strings directly like <code>print("Hello, World!")</code>. In order for Pioneer to be translated we instead use tokens and calls on the <code>'Lang'</code> module to substitute it for the string in the chosen language. The translated strings are stored together with their 'key' in json format, one language per file that are kept in the [https://github.com/pioneerspacesim/pioneer/tree/master/data/lang data/lang/] directory. If the script file in which they are used is from the '''data/modules''' directory they have names starting with '''module-''' and ending with the name of the module written in one word, in small caps, and with the '.lua' ending omitted. The final translation from English to other languages is done on Pioneer's project page at [https://www.transifex.com/pioneer/pioneer/ Transifex], a dedicated online translation tool. The translations are committed to the pioneer/master branch on GitHub by a bot and are not to be edited manually apart from the '''en.json''' files.

==Translating strings==

Below is a minimal example with one string added into the translation system. It takes two files, one in '''data/modules''' and one in '''data/lang/module-hello'''. The print statement isn't wrapped in a function so it will be executed when the '''hello.lua''' is being parsed on startup. You will have to scroll through the command-line history to find it interleaved with the other output.

'''data/modules/hello.lua'''.
local Lang = require 'Lang'
local l = Lang.GetResource("module-hello")

print(l.HELLO)

And a corresponding file containing the translated string, and a description field shown to the translator, giving the context.

'''data/lang/module-hello/en.json'''
{
"HELLO": {
"description": "A classic message.",
"message": "Hello World!"
}
}

In short, any script containing strings that needs translation needs to load the <code>'Lang'</code> module:
local Lang = require 'Lang'
Then load the translation resource they want to use in their module, often just named <code>'l'</code> as in:
local l = Lang.GetResource("module-hello")
You may load more than one translation resource in your script but they will need to have unique names:
local lh = Lang.GetResource("module-hello")
local lg = Lang.GetResource("module-goodbye")

==Working with strings==

Recommended chapters from [https://www.lua.org/pil/contents.html Programming in Lua (first edition) ] 
[https://www.lua.org/pil/2.4.html 2.4 – Strings] 
[https://www.lua.org/pil/3.4.html 3.4 – Concatenation] 
[https://www.lua.org/pil/20.html 20 – The String Library] 
And from the [https://www.lua.org/manual/5.2/ Lua 5.2 Reference Manual] 
[https://www.lua.org/manual/5.2/manual.html#6.4 6.4 – String Manipulation] 

===Concatenation===

Instead of serving ready made sentences we can stitch them together with the Lua string concatenation operator <code>..</code>. The following codelines result in the same output.
print("Hello Clarice!")
print("Hello" .. " " .. "Clarice!")

This could be created by the more generic:

local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local NameGen = require 'NameGen'

local GREETING = 'Hello'
local FBIAGENT = NameGen.Surname()

local onShipDocked = function (ship)
if ship == Game.player then
Comms.Message(GREETING .. ' ' .. FBIAGENT .. '!')
end
end

Event.Register("onShipDocked", onShipDocked)

The <code>..</code> operator is used all over the codebase. Try a search for its occurrence. On Linux I would do <code>grep -R " \.\. " data/modules/ data/libs/ data/pigui/</code> and that will render a lot of output.

===Token concatenation===

You concatenate strings but you also concatenate the string tokens. In the example below from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/modules/DonateToCranks/DonateToCranks.lua#L14-L21 DonateToCranks.lua]''' we see the table <code>flavours</code> being populated by strings from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/lang/module-donatetocranks/en.json data/lang/module-donatetocranks/en.lua]'''

local flavours = {}
for i = 0,9 do
table.insert(flavours, {
title = l["FLAVOUR_" .. i .. "_ADTITLE"],
desc = l["FLAVOUR_" .. i .. "_DESC"],
message = l["FLAVOUR_" .. i .. "_MESSAGE"],
})
end

The first string in the table is given the value of <code>l[FLAVOUR_" .. i .. "_ADTITLE]</code> is concatenated to <code>l[FLAVOUR_0_ADTITLE]</code> which corresponds to the first string in the language module which is seen below.

{
"FLAVOUR_0_ADTITLE": {
"description": "",
"message": "DONATE!"
},
"FLAVOUR_0_DESC": {
"description": "",
"message": "The Church of The Celestial Flying Spaghetti Monster needs YOUR money to spread the word of god."
},
"FLAVOUR_0_MESSAGE": {
"description": "",
"message": "Please select an amount to donate to the Church of the Celestial Flying Spaghetti Monster."
},
"FLAVOUR_1_ADTITLE": {
"description": "",
"message": "DONATE"
},

...

===Lua Standard Library - String manipulation===

I would start to search the '''data/''' register for ''' 'string' '''. to get a feeling for how it's used. Again on Linux i would use the 'grep' command. <code>grep -R "string\." data/</code>. You will see that the two most frequently used functions is <code>string.format()</code>, which is a part of the lua standard library, and <code>string.interp()</code>, which is a Pioneer global function residing in '''data/libs/autoload.lua''', and is described in the next paragraph about [https://wiki.pioneerspacesim.net/wiki/Strings_and_translation#String_variables String variables].

Some examples from the Lua standard library:
Comms.Message(string.lower('wHaT cAsE sHoULd I usE?'))

Maybe not the most easy function to fit into Pioneer, but it's there:
Comms.Message('Today is opposite day!')
Comms.Message(string.reverse('No, today is not opposite day!'))

A more complex example from '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/pigui/modules/hyperjump-planner.lua#L141 data/pigui/modules/hyperjump-planner.lua]''' 
Here <code>string.format("%.2f", distance)</code> is used to set the number of decimals in the jump to two. The units are translatable but the system name isn't (jump_sys.name). '''lc''' is used as the short name for the '''core''' translation resource.

textLine = jumpIndex ..": ".. jump_sys.name .. " (" .. string.format("%.2f", distance) .. lc.UNIT_LY .. " - " .. fuel .. lc.UNIT_TONNES..")"

Here is what the final formatted text looks like (right side, two selected jump routes): 
[[File:hyperjumpplanner.png]]

===PiGUI - Format===

Pioneer has it's own set of formatting functions accessible through PiGUI, our UI. Some of it is realised on the C++ side and described in codedoc [https://codedoc.pioneerspacesim.net/#CClass:Format here]. Most of the functions, however, are strictly Lua and reside in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/libs/text.lua#L146-L385 data/pigui/libs/text.lua]. You access the functions with '''require''' and make sure that '''PiGUI''' is in the scope.

local ui = require 'pigui'
local Format = require 'Format'

Here is an example from the System overview. The table to the right is relying heavily on the Format functions.
[[File:Systemoverview.png]]

The code responsible for the table is here in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/modules/system-view-ui.lua#L811-L840 data/pigui/modules/system-view-ui.lua] with an excerpt showed below. The examples below take 1 or two arguments and the lines ending with 'or nil' is what makes the System overview info window omit values that don't apply to the selected system body.

...
{ name = lc.ESCAPE_VELOCITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Speed(body.escapeVelocity , true) or nil },
{ name = lc.MEAN_DENSITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Mass(body.meanDensity).."/m³" or nil },
{ name = lc.ORBITAL_PERIOD, icon = icons.body_orbit_period,
value = op and op > 0 and ui.Format.Duration(op, 2) or nil },
{ name = lc.DAY_LENGTH, icon = icons.body_day_length,
value = rp > 0 and ui.Format.Duration(rp, 2) or nil },
...

==String variables==

When you want a string to present variable data such as numbers and names you use the <code>interp()</code> function. <code>interp()</code> accepts a table '{}' and the corresponding keys are then embedded in the translated strings enclosed by curly brackets '{}'.

Using ''''module-stationrefuelling'''' we can do:
print(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = 'JFK', fee = 50}))

Example from the actual StationRefuelling module:

'''data/modules/StationRefuelling/'''
Comms.Message(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = station.label,fee = Format.Money(fee)}))

'''data/lang/module-stationrefuelling/en.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Welcome to {station}. Your landing fee of {fee} has been deducted."
}

'''data/lang/module-stationrefuelling/it.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Benvenuti a {station}. Vi è stata dedotta una tassa di atterraggio di {fee}."
}

==Mission flavours==

A script can define a mission and then place many instances of it onto many bulletin boards. A script that introduces many instances in the game should provide some variety; it would harm immersion if, for examle, all delivery missions were worded identically. The easiest way to achieve multiple versions, or "flavours", is by just making a number of different strings and then choosing between them with a simple random function. This is how the [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L18:L48 deny] and [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L282:L320 pirate taunt] messages are done in the DeliverPackage module.

'''data/modules/DeliverPackage/DeliverPackage.lua'''
local num_deny = 8

...

if not qualified then
local introtext = l["DENY_"..Engine.rand:Integer(1,num_deny)-1]
form:SetMessage(introtext)
return
end

'''data/lang/module-deliverpackage/en.json'''
"DENY_0": {
"description": "",
"message": "I'm sorry, but I don't think I can trust you with this delivery."
},
"DENY_1": {
"description": "",
"message": "Come back when you have some qualifications."

...

"DENY_7": {
"description": "",
"message": "I'm not willing to risk this delivery on someone without any qualifications like you."
You don't have to use a string variable that has been passed to the translation file. The pirate taunts, for example, have access to the clients name and the destination of the package but this information is only used in some of the strings.

"PIRATE_TAUNTS_7": {
"description": "",
"message": "That package isn't going to reach its destination today."
},
"PIRATE_TAUNTS_8": {
"description": "",
"message": "You're not getting to {location} today!"
Another way to add variation is to have a table of strings that are variations of a theme, a flavour. In the example below, again from the DeliverPackage module, you have two of the lines from '''FLAVOUR_0''' AND '''FLAVOUR_1''' compared.
"FLAVOUR_0_ADTEXT": {
"description": "",
"message": "GOING TO the {system} system? Money paid for delivery of a small package."
},
"FLAVOUR_0_FAILUREMSG": {
"description": "",
"message": "Unacceptable! You took forever over that delivery. I'm not willing to pay you."

...

"FLAVOUR_1_ADTEXT": {
"description": "",
"message": "WANTED. Delivery of a package to the {system} system."
},
"FLAVOUR_1_FAILUREMSG": {
"description": "",
"message": "I'm frustrated by the late delivery of my package, and I refuse to pay you."
There are ten flavours in DeliverPackage of five strings each, each forming a short story line. They are static in that you only see lines from within the same flavour. You know what lines will follow if you accept the mission and after a short time of playing you know this already from seeing the ad if delivering things is your forte. It's hard to share strings in between the flavours as they would need to be much more similar. It's a trade off. You could build a very complex interaction with the customers but in the end it needs to be translatable.

Generally, the more specific the text is, the stranger it will appear to see it multiple times in the game. For example, consider the following two examples:
- "Contract is to move X tonnes of Y to system Z"
- "My uncle's cat got sick, so I can't travel right now, so I need you to take my contract for me, to move X tonnes of Y to my home system Z"
The former might not need any flavours, as it's unpersonal, and very general. Seeing the second string multiple times does break immersion. Solution is to not show it often, either by making the mission rare / single occurance (no script to date does this) or have many flavours, making probability of the same twice low.

==Trailing commas==

The two most common text based files you will come across when you work with module scripting are Lua and JSON. While JSON is strictly used for information, Lua is used most as a scripting language but in some instances it's used for data. See for instance '''data/modules/CargoRun/CargoTypes.lua'''. It is basically just tables of data. In any way, we have used both in this chapter and it's probably a good time to address a
difference between the two that could otherwise create confusion. Trailing commas after the last element in a table. The short version is: In Lua, you can use trailing commas on the last element in a table. In JSON you cannot.

===Lua===

Here are the last four ladies in the Hawaiian culture file. '''data/culture/haw.lua'''. These are the files we stitch together characters/clients names from. As you see, the last element, ''''Wanaao'''' has a trailing comma after her. This is perfectly fine.

'Pohaku',
'Oke',
'Wailani',
'Wanaao', -- Lua. A comma here is fine!
}

===JSON===

Here we see the last two elements in the '''data/lang/core/en.json'''. It keeps some of the strings used in the game and every language has it's own version of it. Trailing commas in JSON is explicitly forbidden in the official description of the file format. There are derivative interpreters that are relaxed and allow trailing commas but this is not the case with the one used in Pioneer.

},
"ZOOM_IN": {
"description": "",
"message": "Zoom in"
},
"ZOOM_OUT": {
"description": "",
"message": "Zoom out"
} -- JSON. A comma here is NOT fine!
}

The fastest way to find out what could happen is to simply just put a comma in that place and start Pioneer. Open the '''System oveview''' and click on a planet and look at the data presented in the pop up window. There is now a lot of '''[NO_JSON]''' data presented in there.

"message": "Zoom out"
}, -- ;o -onoh!
}

Also, another difference between the file formats is that the comment I added above in the Lua file is a real Lua comment and would work and be ignored by the language. The ;o emoji comment in the JSON file wouldn't work. JSON doesn't have comments in it. You would have to assign a separate element to be used as a comment like the translation file above which has elements beginning with '''"description":'''.

Strings and translation

2025-04-07T17:36:16Z

Zonkmachine: /* Trailing commas */ fixup

==Internationalization==
Recommended reading: [https://dev.pioneerspacesim.net/contribute/translations Pioneer translators wikipage]

It is important that scripters are familiar with the translation system. In the previous example '''hello_world.lua''' used strings directly like <code>print("Hello, World!")</code>. In order for Pioneer to be translated we instead use tokens and calls on the <code>'Lang'</code> module to substitute it for the string in the chosen language. The translated strings are stored together with their 'key' in json format, one language per file that are kept in the [https://github.com/pioneerspacesim/pioneer/tree/master/data/lang data/lang/] directory. If the script file in which they are used is from the '''data/modules''' directory they have names starting with '''module-''' and ending with the name of the module written in one word, in small caps, and with the '.lua' ending omitted. The final translation from English to other languages is done on Pioneer's project page at [https://www.transifex.com/pioneer/pioneer/ Transifex], a dedicated online translation tool. The translations are committed to the pioneer/master branch on GitHub by a bot and are not to be edited manually apart from the '''en.json''' files.

==Translating strings==

Below is a minimal example with one string added into the translation system. It takes two files, one in '''data/modules''' and one in '''data/lang/module-hello'''. The print statement isn't wrapped in a function so it will be executed when the '''hello.lua''' is being parsed on startup. You will have to scroll through the command-line history to find it interleaved with the other output.

'''data/modules/hello.lua'''.
local Lang = require 'Lang'
local l = Lang.GetResource("module-hello")

print(l.HELLO)

And a corresponding file containing the translated string, and a description field shown to the translator, giving the context.

'''data/lang/module-hello/en.json'''
{
"HELLO": {
"description": "A classic message.",
"message": "Hello World!"
}
}

In short, any script containing strings that needs translation needs to load the <code>'Lang'</code> module:
local Lang = require 'Lang'
Then load the translation resource they want to use in their module, often just named <code>'l'</code> as in:
local l = Lang.GetResource("module-hello")
You may load more than one translation resource in your script but they will need to have unique names:
local lh = Lang.GetResource("module-hello")
local lg = Lang.GetResource("module-goodbye")

==Working with strings==

Recommended chapters from [https://www.lua.org/pil/contents.html Programming in Lua (first edition) ] 
[https://www.lua.org/pil/2.4.html 2.4 – Strings] 
[https://www.lua.org/pil/3.4.html 3.4 – Concatenation] 
[https://www.lua.org/pil/20.html 20 – The String Library] 
And from the [https://www.lua.org/manual/5.2/ Lua 5.2 Reference Manual] 
[https://www.lua.org/manual/5.2/manual.html#6.4 6.4 – String Manipulation] 

===Concatenation===

Instead of serving ready made sentences we can stitch them together with the Lua string concatenation operator <code>..</code>. The following codelines result in the same output.
print("Hello Clarice!")
print("Hello" .. " " .. "Clarice!")

This could be created by the more generic:

local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local NameGen = require 'NameGen'

local GREETING = 'Hello'
local FBIAGENT = NameGen.Surname()

local onShipDocked = function (ship)
if ship == Game.player then
Comms.Message(GREETING .. ' ' .. FBIAGENT .. '!')
end
end

Event.Register("onShipDocked", onShipDocked)

The <code>..</code> operator is used all over the codebase. Try a search for its occurrence. On Linux I would do <code>grep -R " \.\. " data/modules/ data/libs/ data/pigui/</code> and that will render a lot of output.

===Token concatenation===

You concatenate strings but you also concatenate the string tokens. In the example below from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/modules/DonateToCranks/DonateToCranks.lua#L14-L21 DonateToCranks.lua]''' we see the table <code>flavours</code> being populated by strings from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/lang/module-donatetocranks/en.json data/lang/module-donatetocranks/en.lua]'''

local flavours = {}
for i = 0,9 do
table.insert(flavours, {
title = l["FLAVOUR_" .. i .. "_ADTITLE"],
desc = l["FLAVOUR_" .. i .. "_DESC"],
message = l["FLAVOUR_" .. i .. "_MESSAGE"],
})
end

The first string in the table is given the value of <code>l[FLAVOUR_" .. i .. "_ADTITLE]</code> is concatenated to <code>l[FLAVOUR_0_ADTITLE]</code> which corresponds to the first string in the language module which is seen below.

{
"FLAVOUR_0_ADTITLE": {
"description": "",
"message": "DONATE!"
},
"FLAVOUR_0_DESC": {
"description": "",
"message": "The Church of The Celestial Flying Spaghetti Monster needs YOUR money to spread the word of god."
},
"FLAVOUR_0_MESSAGE": {
"description": "",
"message": "Please select an amount to donate to the Church of the Celestial Flying Spaghetti Monster."
},
"FLAVOUR_1_ADTITLE": {
"description": "",
"message": "DONATE"
},

...

===Lua Standard Library - String manipulation===

I would start to search the '''data/''' register for ''' 'string' '''. to get a feeling for how it's used. Again on Linux i would use the 'grep' command. <code>grep -R "string\." data/</code>. You will see that the two most frequently used functions is <code>string.format()</code>, which is a part of the lua standard library, and <code>string.interp()</code>, which is a Pioneer global function residing in '''data/libs/autoload.lua''', and is described in the next paragraph about [https://wiki.pioneerspacesim.net/wiki/Strings_and_translation#String_variables String variables].

Some examples from the Lua standard library:
Comms.Message(string.lower('wHaT cAsE sHoULd I usE?'))

Maybe not the most easy function to fit into Pioneer, but it's there:
Comms.Message('Today is opposite day!')
Comms.Message(string.reverse('No, today is not opposite day!'))

A more complex example from '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/pigui/modules/hyperjump-planner.lua#L141 data/pigui/modules/hyperjump-planner.lua]''' 
Here <code>string.format("%.2f", distance)</code> is used to set the number of decimals in the jump to two. The units are translatable but the system name off course isn't (jump_sys.name). '''lc''' is used as the short name for the '''core''' translation resource.

textLine = jumpIndex ..": ".. jump_sys.name .. " (" .. string.format("%.2f", distance) .. lc.UNIT_LY .. " - " .. fuel .. lc.UNIT_TONNES..")"

Here is what the final formatted text looks like (right side, two selected jump routes): 
[[File:hyperjumpplanner.png]]

===PiGUI - Format===

Pioneer has it's own set of formatting functions accessible through PiGUI, our UI. Some of it is realised on the C++ side and described in codedoc [https://codedoc.pioneerspacesim.net/#CClass:Format here]. Most of the functions, however, are strictly Lua and reside in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/libs/text.lua#L146-L385 data/pigui/libs/text.lua]. You access the functions with '''require''' and make sure that '''PiGUI''' is in the scope.

local ui = require 'pigui'
local Format = require 'Format'

Here is an example from the System overview. The table to the right is relying heavily on the Format functions.
[[File:Systemoverview.png]]

The code responsible for the table is here in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/modules/system-view-ui.lua#L811-L840 data/pigui/modules/system-view-ui.lua] with an excerpt showed below. The examples below take 1 or two arguments and the lines ending with 'or nil' is what makes the System overview info window omit values that don't apply to the selected system body.

...
{ name = lc.ESCAPE_VELOCITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Speed(body.escapeVelocity , true) or nil },
{ name = lc.MEAN_DENSITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Mass(body.meanDensity).."/m³" or nil },
{ name = lc.ORBITAL_PERIOD, icon = icons.body_orbit_period,
value = op and op > 0 and ui.Format.Duration(op, 2) or nil },
{ name = lc.DAY_LENGTH, icon = icons.body_day_length,
value = rp > 0 and ui.Format.Duration(rp, 2) or nil },
...

==String variables==

When you want a string to present variable data such as numbers and names you use the <code>interp()</code> function. <code>interp()</code> accepts a table '{}' and the corresponding keys are then embedded in the translated strings enclosed by curly brackets '{}'.

Using ''''module-stationrefuelling'''' we can do:
print(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = 'JFK', fee = 50}))

Example from the actual StationRefuelling module:

'''data/modules/StationRefuelling/'''
Comms.Message(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = station.label,fee = Format.Money(fee)}))

'''data/lang/module-stationrefuelling/en.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Welcome to {station}. Your landing fee of {fee} has been deducted."
}

'''data/lang/module-stationrefuelling/it.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Benvenuti a {station}. Vi è stata dedotta una tassa di atterraggio di {fee}."
}

==Mission flavours==

A script can define a mission and then place many instances of it onto many bulletin boards. A script that introduces many instances in the game should provide some variety; it would harm immersion if, for examle, all delivery missions were worded identically. The easiest way to achieve multiple versions, or "flavours", is by just making a number of different strings and then choosing between them with a simple random function. This is how the [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L18:L48 deny] and [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L282:L320 pirate taunt] messages are done in the DeliverPackage module.

'''data/modules/DeliverPackage/DeliverPackage.lua'''
local num_deny = 8

...

if not qualified then
local introtext = l["DENY_"..Engine.rand:Integer(1,num_deny)-1]
form:SetMessage(introtext)
return
end

'''data/lang/module-deliverpackage/en.json'''
"DENY_0": {
"description": "",
"message": "I'm sorry, but I don't think I can trust you with this delivery."
},
"DENY_1": {
"description": "",
"message": "Come back when you have some qualifications."

...

"DENY_7": {
"description": "",
"message": "I'm not willing to risk this delivery on someone without any qualifications like you."
You don't have to use a string variable that has been passed to the translation file. The pirate taunts, for example, have access to the clients name and the destination of the package but this information is only used in some of the strings.

"PIRATE_TAUNTS_7": {
"description": "",
"message": "That package isn't going to reach its destination today."
},
"PIRATE_TAUNTS_8": {
"description": "",
"message": "You're not getting to {location} today!"
Another way to add variation is to have a table of strings that are variations of a theme, a flavour. In the example below, again from the DeliverPackage module, you have two of the lines from '''FLAVOUR_0''' AND '''FLAVOUR_1''' compared.
"FLAVOUR_0_ADTEXT": {
"description": "",
"message": "GOING TO the {system} system? Money paid for delivery of a small package."
},
"FLAVOUR_0_FAILUREMSG": {
"description": "",
"message": "Unacceptable! You took forever over that delivery. I'm not willing to pay you."

...

"FLAVOUR_1_ADTEXT": {
"description": "",
"message": "WANTED. Delivery of a package to the {system} system."
},
"FLAVOUR_1_FAILUREMSG": {
"description": "",
"message": "I'm frustrated by the late delivery of my package, and I refuse to pay you."
There are ten flavours in DeliverPackage of five strings each, each forming a short story line. They are static in that you only see lines from within the same flavour. You know what lines will follow if you accept the mission and after a short time of playing you know this already from seeing the ad if delivering things is your forte. It's hard to share strings in between the flavours as they would need to be much more similar. It's a trade off. You could build a very complex interaction with the customers but in the end it needs to be translatable.

Generally, the more specific the text is, the stranger it will appear to see it multiple times in the game. For example, consider the following two examples:
- "Contract is to move X tonnes of Y to system Z"
- "My uncle's cat got sick, so I can't travel right now, so I need you to take my contract for me, to move X tonnes of Y to my home system Z"
The former might not need any flavours, as it's unpersonal, and very general. Seeing the second string multiple times does break immersion. Solution is to not show it often, either by making the mission rare / single occurance (no script to date does this) or have many flavours, making probability of the same twice low.

==Trailing commas==

The two most common text based files you will come across when you work with module scripting are Lua and JSON. While JSON is strictly used for information, Lua is used most as a scripting language but in some instances it's used for data. See for instance '''data/modules/CargoRun/CargoTypes.lua'''. It is basically just tables of data. In any way, we have used both in this chapter and it's probably a good time to address a
difference between the two that could otherwise create confusion. Trailing commas after the last element in a table. The short version is: In Lua, you can use trailing commas on the last element in a table. In JSON you cannot.

===Lua===

Here are the last four ladies in the Hawaiian culture file. '''data/culture/haw.lua'''. These are the files we stitch together characters/clients names from. As you see, the last element, ''''Wanaao'''' has a trailing comma after her. This is perfectly fine.

'Pohaku',
'Oke',
'Wailani',
'Wanaao', -- Lua. A comma here is fine!
}

===JSON===

Here we see the last two elements in the '''data/lang/core/en.json'''. It keeps some of the strings used in the game and every language has it's own version of it. Trailing commas in JSON is explicitly forbidden in the official description of the file format. There are derivative interpreters that are relaxed and allow trailing commas but this is not the case with the one used in Pioneer.

},
"ZOOM_IN": {
"description": "",
"message": "Zoom in"
},
"ZOOM_OUT": {
"description": "",
"message": "Zoom out"
} -- JSON. A comma here is NOT fine!
}

The fastest way to find out what could happen is to simply just put a comma in that place and start Pioneer. Open the '''System oveview''' and click on a planet and look at the data presented in the pop up window. There is now a lot of '''[NO_JSON]''' data presented in there.

"message": "Zoom out"
}, -- ;o -onoh!
}

Also, another difference between the file formats is that the comment I added above in the Lua file is a real Lua comment and would work and be ignored by the language. The ;o emoji comment in the JSON file wouldn't work. JSON doesn't have comments in it. You would have to assign a separate element to be used as a comment like the translation file above which has elements beginning with '''"description":'''.

Strings and translation

2025-04-07T17:21:02Z

Zonkmachine: JSON, Lua and trailing commas

==Internationalization==
Recommended reading: [https://dev.pioneerspacesim.net/contribute/translations Pioneer translators wikipage]

It is important that scripters are familiar with the translation system. In the previous example '''hello_world.lua''' used strings directly like <code>print("Hello, World!")</code>. In order for Pioneer to be translated we instead use tokens and calls on the <code>'Lang'</code> module to substitute it for the string in the chosen language. The translated strings are stored together with their 'key' in json format, one language per file that are kept in the [https://github.com/pioneerspacesim/pioneer/tree/master/data/lang data/lang/] directory. If the script file in which they are used is from the '''data/modules''' directory they have names starting with '''module-''' and ending with the name of the module written in one word, in small caps, and with the '.lua' ending omitted. The final translation from English to other languages is done on Pioneer's project page at [https://www.transifex.com/pioneer/pioneer/ Transifex], a dedicated online translation tool. The translations are committed to the pioneer/master branch on GitHub by a bot and are not to be edited manually apart from the '''en.json''' files.

==Translating strings==

Below is a minimal example with one string added into the translation system. It takes two files, one in '''data/modules''' and one in '''data/lang/module-hello'''. The print statement isn't wrapped in a function so it will be executed when the '''hello.lua''' is being parsed on startup. You will have to scroll through the command-line history to find it interleaved with the other output.

'''data/modules/hello.lua'''.
local Lang = require 'Lang'
local l = Lang.GetResource("module-hello")

print(l.HELLO)

And a corresponding file containing the translated string, and a description field shown to the translator, giving the context.

'''data/lang/module-hello/en.json'''
{
"HELLO": {
"description": "A classic message.",
"message": "Hello World!"
}
}

In short, any script containing strings that needs translation needs to load the <code>'Lang'</code> module:
local Lang = require 'Lang'
Then load the translation resource they want to use in their module, often just named <code>'l'</code> as in:
local l = Lang.GetResource("module-hello")
You may load more than one translation resource in your script but they will need to have unique names:
local lh = Lang.GetResource("module-hello")
local lg = Lang.GetResource("module-goodbye")

==Working with strings==

Recommended chapters from [https://www.lua.org/pil/contents.html Programming in Lua (first edition) ] 
[https://www.lua.org/pil/2.4.html 2.4 – Strings] 
[https://www.lua.org/pil/3.4.html 3.4 – Concatenation] 
[https://www.lua.org/pil/20.html 20 – The String Library] 
And from the [https://www.lua.org/manual/5.2/ Lua 5.2 Reference Manual] 
[https://www.lua.org/manual/5.2/manual.html#6.4 6.4 – String Manipulation] 

===Concatenation===

Instead of serving ready made sentences we can stitch them together with the Lua string concatenation operator <code>..</code>. The following codelines result in the same output.
print("Hello Clarice!")
print("Hello" .. " " .. "Clarice!")

This could be created by the more generic:

local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local NameGen = require 'NameGen'

local GREETING = 'Hello'
local FBIAGENT = NameGen.Surname()

local onShipDocked = function (ship)
if ship == Game.player then
Comms.Message(GREETING .. ' ' .. FBIAGENT .. '!')
end
end

Event.Register("onShipDocked", onShipDocked)

The <code>..</code> operator is used all over the codebase. Try a search for its occurrence. On Linux I would do <code>grep -R " \.\. " data/modules/ data/libs/ data/pigui/</code> and that will render a lot of output.

===Token concatenation===

You concatenate strings but you also concatenate the string tokens. In the example below from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/modules/DonateToCranks/DonateToCranks.lua#L14-L21 DonateToCranks.lua]''' we see the table <code>flavours</code> being populated by strings from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/lang/module-donatetocranks/en.json data/lang/module-donatetocranks/en.lua]'''

local flavours = {}
for i = 0,9 do
table.insert(flavours, {
title = l["FLAVOUR_" .. i .. "_ADTITLE"],
desc = l["FLAVOUR_" .. i .. "_DESC"],
message = l["FLAVOUR_" .. i .. "_MESSAGE"],
})
end

The first string in the table is given the value of <code>l[FLAVOUR_" .. i .. "_ADTITLE]</code> is concatenated to <code>l[FLAVOUR_0_ADTITLE]</code> which corresponds to the first string in the language module which is seen below.

{
"FLAVOUR_0_ADTITLE": {
"description": "",
"message": "DONATE!"
},
"FLAVOUR_0_DESC": {
"description": "",
"message": "The Church of The Celestial Flying Spaghetti Monster needs YOUR money to spread the word of god."
},
"FLAVOUR_0_MESSAGE": {
"description": "",
"message": "Please select an amount to donate to the Church of the Celestial Flying Spaghetti Monster."
},
"FLAVOUR_1_ADTITLE": {
"description": "",
"message": "DONATE"
},

...

===Lua Standard Library - String manipulation===

I would start to search the '''data/''' register for ''' 'string' '''. to get a feeling for how it's used. Again on Linux i would use the 'grep' command. <code>grep -R "string\." data/</code>. You will see that the two most frequently used functions is <code>string.format()</code>, which is a part of the lua standard library, and <code>string.interp()</code>, which is a Pioneer global function residing in '''data/libs/autoload.lua''', and is described in the next paragraph about [https://wiki.pioneerspacesim.net/wiki/Strings_and_translation#String_variables String variables].

Some examples from the Lua standard library:
Comms.Message(string.lower('wHaT cAsE sHoULd I usE?'))

Maybe not the most easy function to fit into Pioneer, but it's there:
Comms.Message('Today is opposite day!')
Comms.Message(string.reverse('No, today is not opposite day!'))

A more complex example from '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/pigui/modules/hyperjump-planner.lua#L141 data/pigui/modules/hyperjump-planner.lua]''' 
Here <code>string.format("%.2f", distance)</code> is used to set the number of decimals in the jump to two. The units are translatable but the system name off course isn't (jump_sys.name). '''lc''' is used as the short name for the '''core''' translation resource.

textLine = jumpIndex ..": ".. jump_sys.name .. " (" .. string.format("%.2f", distance) .. lc.UNIT_LY .. " - " .. fuel .. lc.UNIT_TONNES..")"

Here is what the final formatted text looks like (right side, two selected jump routes): 
[[File:hyperjumpplanner.png]]

===PiGUI - Format===

Pioneer has it's own set of formatting functions accessible through PiGUI, our UI. Some of it is realised on the C++ side and described in codedoc [https://codedoc.pioneerspacesim.net/#CClass:Format here]. Most of the functions, however, are strictly Lua and reside in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/libs/text.lua#L146-L385 data/pigui/libs/text.lua]. You access the functions with '''require''' and make sure that '''PiGUI''' is in the scope.

local ui = require 'pigui'
local Format = require 'Format'

Here is an example from the System overview. The table to the right is relying heavily on the Format functions.
[[File:Systemoverview.png]]

The code responsible for the table is here in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/modules/system-view-ui.lua#L811-L840 data/pigui/modules/system-view-ui.lua] with an excerpt showed below. The examples below take 1 or two arguments and the lines ending with 'or nil' is what makes the System overview info window omit values that don't apply to the selected system body.

...
{ name = lc.ESCAPE_VELOCITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Speed(body.escapeVelocity , true) or nil },
{ name = lc.MEAN_DENSITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Mass(body.meanDensity).."/m³" or nil },
{ name = lc.ORBITAL_PERIOD, icon = icons.body_orbit_period,
value = op and op > 0 and ui.Format.Duration(op, 2) or nil },
{ name = lc.DAY_LENGTH, icon = icons.body_day_length,
value = rp > 0 and ui.Format.Duration(rp, 2) or nil },
...

==String variables==

When you want a string to present variable data such as numbers and names you use the <code>interp()</code> function. <code>interp()</code> accepts a table '{}' and the corresponding keys are then embedded in the translated strings enclosed by curly brackets '{}'.

Using ''''module-stationrefuelling'''' we can do:
print(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = 'JFK', fee = 50}))

Example from the actual StationRefuelling module:

'''data/modules/StationRefuelling/'''
Comms.Message(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = station.label,fee = Format.Money(fee)}))

'''data/lang/module-stationrefuelling/en.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Welcome to {station}. Your landing fee of {fee} has been deducted."
}

'''data/lang/module-stationrefuelling/it.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Benvenuti a {station}. Vi è stata dedotta una tassa di atterraggio di {fee}."
}

==Mission flavours==

A script can define a mission and then place many instances of it onto many bulletin boards. A script that introduces many instances in the game should provide some variety; it would harm immersion if, for examle, all delivery missions were worded identically. The easiest way to achieve multiple versions, or "flavours", is by just making a number of different strings and then choosing between them with a simple random function. This is how the [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L18:L48 deny] and [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L282:L320 pirate taunt] messages are done in the DeliverPackage module.

'''data/modules/DeliverPackage/DeliverPackage.lua'''
local num_deny = 8

...

if not qualified then
local introtext = l["DENY_"..Engine.rand:Integer(1,num_deny)-1]
form:SetMessage(introtext)
return
end

'''data/lang/module-deliverpackage/en.json'''
"DENY_0": {
"description": "",
"message": "I'm sorry, but I don't think I can trust you with this delivery."
},
"DENY_1": {
"description": "",
"message": "Come back when you have some qualifications."

...

"DENY_7": {
"description": "",
"message": "I'm not willing to risk this delivery on someone without any qualifications like you."
You don't have to use a string variable that has been passed to the translation file. The pirate taunts, for example, have access to the clients name and the destination of the package but this information is only used in some of the strings.

"PIRATE_TAUNTS_7": {
"description": "",
"message": "That package isn't going to reach its destination today."
},
"PIRATE_TAUNTS_8": {
"description": "",
"message": "You're not getting to {location} today!"
Another way to add variation is to have a table of strings that are variations of a theme, a flavour. In the example below, again from the DeliverPackage module, you have two of the lines from '''FLAVOUR_0''' AND '''FLAVOUR_1''' compared.
"FLAVOUR_0_ADTEXT": {
"description": "",
"message": "GOING TO the {system} system? Money paid for delivery of a small package."
},
"FLAVOUR_0_FAILUREMSG": {
"description": "",
"message": "Unacceptable! You took forever over that delivery. I'm not willing to pay you."

...

"FLAVOUR_1_ADTEXT": {
"description": "",
"message": "WANTED. Delivery of a package to the {system} system."
},
"FLAVOUR_1_FAILUREMSG": {
"description": "",
"message": "I'm frustrated by the late delivery of my package, and I refuse to pay you."
There are ten flavours in DeliverPackage of five strings each, each forming a short story line. They are static in that you only see lines from within the same flavour. You know what lines will follow if you accept the mission and after a short time of playing you know this already from seeing the ad if delivering things is your forte. It's hard to share strings in between the flavours as they would need to be much more similar. It's a trade off. You could build a very complex interaction with the customers but in the end it needs to be translatable.

Generally, the more specific the text is, the stranger it will appear to see it multiple times in the game. For example, consider the following two examples:
- "Contract is to move X tonnes of Y to system Z"
- "My uncle's cat got sick, so I can't travel right now, so I need you to take my contract for me, to move X tonnes of Y to my home system Z"
The former might not need any flavours, as it's unpersonal, and very general. Seeing the second string multiple times does break immersion. Solution is to not show it often, either by making the mission rare / single occurance (no script to date does this) or have many flavours, making probability of the same twice low.

==Trailing commas==

The two most common text based files you will come across when you work with module scripting are Lua and JSON. While JSON is strictly used for information, Lua is used most as a scripting language but in some instances it's used for data. See for instance '''data/modules/CargoRun/CargoTypes.lua'''. It is basically just tables of data. In any way, we have used both in this chapter and it's probably a good time to address a
difference between the two that could otherwise create confusion. Trailing commas after the last element in a table.

===Lua===

Here are the last four ladies in the Hawaiian culture file. '''data/culture/haw.lua'''. These are the files we stitch together characters/clients names from. As you see, the last element, ''''Wanaao'''' has a trailing comma after her. This is perfectly fine.

'Pohaku',
'Oke',
'Wailani',
'Wanaao', -- Lua. A comma here is fine!
}

===JSON===

Here we see the last two elements in the '''data/lang/core/en.json'''. It keeps some of the strings used in the game and every language has it's own version of it. Trailing commas in JSON is explicitly forbidden in the official description of the file format. There are derivative interpreters that are relaxed and allow trailing commas but this is not the case with the one used in Pioneer.

},
"ZOOM_IN": {
"description": "",
"message": "Zoom in"
},
"ZOOM_OUT": {
"description": "",
"message": "Zoom out"
} -- JSON. A comma here is NOT fine!
}

The fastest way to find out what could happen is to simply just put a comma in that place and start Pioneer. Open the '''System oveview''' and click on a planet and look at the data presented in the pop up window. There is now a lot of '''[NO_JSON]''' data presented in there.

"message": "Zoom out"
}, -- ;o -onoh!
}

Also, another difference between the file formats is that the comment I added above in the Lua file is a real Lua comment and would work and be ignored by the language. The ;o emoji comment in the JSON file wouldn't work. JSON doesn't have comments in it. You would have to assign a separate element to be used as a comment like the translation file above which has elements beginning with '''"description":'''.

Translations

2025-04-07T14:47:21Z

Zonkmachine: /* For translators */

All text in Pioneer is translatable, and the game ships with several translations. Here's everything you need to know.

== For translators ==

All our translations are managed through [http://transifex.com Transifex], a free web-based translation service. To start writing translations, sign up there, using [https://www.transifex.com/signup/open-source/?join_project=pioneer this link], and then take a look at the [https://www.transifex.com/projects/p/pioneer/ Pioneer project]. You can either use the web-interface, or download the full file, and edit off line, and then re-upload.

Changes to translations are automatically pulled into the master git repo, from transifex, twice per day, and from there to the builds when they're next run.

In Transifex you can subscribe to notifications for the languages or resources you're interested in. When new strings are added or modified, you'll be notified.

If you want to translate Pioneer to an entirely new language, please [https://github.com/pioneerspacesim/pioneer/issues open an issue] on the tracker and someone will create the translation for you.

English is the canonical language for Pioneer. As such, you can't directly modify the english strings through Transifex. If you want to change those, you'll need to make the change in the source code hosted on GitHub and submit a pull request like for a normal code change. However, do note that changes in english text will trigger re-translation of that string in all other languages, thus there should be a good motivation why a string is changes (e.g. spelling/grammar).

Untranslated strings will use the value from the English version.

You can leave comments in Transifex to help out other translators. You'll also see any notes left by the developers to help you translate a particular string.

If you're a new translator and you'd like your name included in AUTHORS.txt, please let us know!

For when you translate: Text within curly brace denote a varialbe name that will be substituted and should not be translated, e.g.

"Welcome to {system}"

== For mod developers ==

Each module gets its own translation resource, called <tt>module-foo</tt>.

To get at the strings for your module, do something like:

local Lang = import("Lang")
local l = Lang.GetResource("module-foo")

Then you can get at the string by its token:

print(l.SOME_TRANSLATED_STRING)

While its possible to load multiple translation resources to share strings, its highly recommended that you don't do that. Stick to your own strings so that you don't have to track changes in other modules. Duplicates across resources are fine. Note that code that uses multiple resources won't be accepted into the main Pioneer repository unless you've checked it with a core developer first and it has a good reason.

Translations are [https://developer.chrome.com/extensions/i18n.html <tt>chrome.i18n</tt> JSON] files. The format is fairly simple - a JSON object with tokens as keys and values of an object with two keys, <tt>message</tt> and <tt>description</tt>. <tt>message</tt> is the text that will appear in the game, while <tt>description</tt> provides instructions for the translator that will be displayed in Transifex. [https://www.json.org/img/string.png Here] is a useful chart showing how characters are interpreted.

If you're submitting code that requires a new language you should only include <tt>en.json</tt>. Please tag '''@impaktor''' in your pull request so they can create a new resource in Transifex and make sure a language update is done at merge. If you don't do this then you'll break the game for non-English users.

== For core developers ==

The <tt>core</tt> resource is magical. If you add a string to it, you also need to add it to <tt>LangStrings.inc.h</tt> and recompile. It will then be available as <tt>Lang::SOME_TRANSLATED_STRING</tt>.

Strings and translation

2025-04-01T06:52:04Z

Zonkmachine: /* PiGUI - Format */ fixup - need PiGUI for Format

==Internationalization==
Recommended reading: [https://dev.pioneerspacesim.net/contribute/translations Pioneer translators wikipage]

It is important that scripters are familiar with the translation system. In the previous example '''hello_world.lua''' used strings directly like <code>print("Hello, World!")</code>. In order for Pioneer to be translated we instead use tokens and calls on the <code>'Lang'</code> module to substitute it for the string in the chosen language. The translated strings are stored together with their 'key' in json format, one language per file that are kept in the [https://github.com/pioneerspacesim/pioneer/tree/master/data/lang data/lang/] directory. If the script file in which they are used is from the '''data/modules''' directory they have names starting with '''module-''' and ending with the name of the module written in one word, in small caps, and with the '.lua' ending omitted. The final translation from English to other languages is done on Pioneer's project page at [https://www.transifex.com/pioneer/pioneer/ Transifex], a dedicated online translation tool. The translations are committed to the pioneer/master branch on GitHub by a bot and are not to be edited manually apart from the '''en.json''' files.

==Translating strings==

Below is a minimal example with one string added into the translation system. It takes two files, one in '''data/modules''' and one in '''data/lang/module-hello'''. The print statement isn't wrapped in a function so it will be executed when the '''hello.lua''' is being parsed on startup. You will have to scroll through the command-line history to find it interleaved with the other output.

'''data/modules/hello.lua'''.
local Lang = require 'Lang'
local l = Lang.GetResource("module-hello")

print(l.HELLO)

And a corresponding file containing the translated string, and a description field shown to the translator, giving the context.

'''data/lang/module-hello/en.json'''
{
"HELLO": {
"description": "A classic message.",
"message": "Hello World!"
}
}

In short, any script containing strings that needs translation needs to load the <code>'Lang'</code> module:
local Lang = require 'Lang'
Then load the translation resource they want to use in their module, often just named <code>'l'</code> as in:
local l = Lang.GetResource("module-hello")
You may load more than one translation resource in your script but they will need to have unique names:
local lh = Lang.GetResource("module-hello")
local lg = Lang.GetResource("module-goodbye")

==Working with strings==

Recommended chapters from [https://www.lua.org/pil/contents.html Programming in Lua (first edition) ] 
[https://www.lua.org/pil/2.4.html 2.4 – Strings] 
[https://www.lua.org/pil/3.4.html 3.4 – Concatenation] 
[https://www.lua.org/pil/20.html 20 – The String Library] 
And from the [https://www.lua.org/manual/5.2/ Lua 5.2 Reference Manual] 
[https://www.lua.org/manual/5.2/manual.html#6.4 6.4 – String Manipulation] 

===Concatenation===

Instead of serving ready made sentences we can stitch them together with the Lua string concatenation operator <code>..</code>. The following codelines result in the same output.
print("Hello Clarice!")
print("Hello" .. " " .. "Clarice!")

This could be created by the more generic:

local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local NameGen = require 'NameGen'

local GREETING = 'Hello'
local FBIAGENT = NameGen.Surname()

local onShipDocked = function (ship)
if ship == Game.player then
Comms.Message(GREETING .. ' ' .. FBIAGENT .. '!')
end
end

Event.Register("onShipDocked", onShipDocked)

The <code>..</code> operator is used all over the codebase. Try a search for its occurrence. On Linux I would do <code>grep -R " \.\. " data/modules/ data/libs/ data/pigui/</code> and that will render a lot of output.

===Token concatenation===

You concatenate strings but you also concatenate the string tokens. In the example below from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/modules/DonateToCranks/DonateToCranks.lua#L14-L21 DonateToCranks.lua]''' we see the table <code>flavours</code> being populated by strings from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/lang/module-donatetocranks/en.json data/lang/module-donatetocranks/en.lua]'''

local flavours = {}
for i = 0,9 do
table.insert(flavours, {
title = l["FLAVOUR_" .. i .. "_ADTITLE"],
desc = l["FLAVOUR_" .. i .. "_DESC"],
message = l["FLAVOUR_" .. i .. "_MESSAGE"],
})
end

The first string in the table is given the value of <code>l[FLAVOUR_" .. i .. "_ADTITLE]</code> is concatenated to <code>l[FLAVOUR_0_ADTITLE]</code> which corresponds to the first string in the language module which is seen below.

{
"FLAVOUR_0_ADTITLE": {
"description": "",
"message": "DONATE!"
},
"FLAVOUR_0_DESC": {
"description": "",
"message": "The Church of The Celestial Flying Spaghetti Monster needs YOUR money to spread the word of god."
},
"FLAVOUR_0_MESSAGE": {
"description": "",
"message": "Please select an amount to donate to the Church of the Celestial Flying Spaghetti Monster."
},
"FLAVOUR_1_ADTITLE": {
"description": "",
"message": "DONATE"
},

...

===Lua Standard Library - String manipulation===

I would start to search the '''data/''' register for ''' 'string' '''. to get a feeling for how it's used. Again on Linux i would use the 'grep' command. <code>grep -R "string\." data/</code>. You will see that the two most frequently used functions is <code>string.format()</code>, which is a part of the lua standard library, and <code>string.interp()</code>, which is a Pioneer global function residing in '''data/libs/autoload.lua''', and is described in the next paragraph about [https://wiki.pioneerspacesim.net/wiki/Strings_and_translation#String_variables String variables].

Some examples from the Lua standard library:
Comms.Message(string.lower('wHaT cAsE sHoULd I usE?'))

Maybe not the most easy function to fit into Pioneer, but it's there:
Comms.Message('Today is opposite day!')
Comms.Message(string.reverse('No, today is not opposite day!'))

A more complex example from '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/pigui/modules/hyperjump-planner.lua#L141 data/pigui/modules/hyperjump-planner.lua]''' 
Here <code>string.format("%.2f", distance)</code> is used to set the number of decimals in the jump to two. The units are translatable but the system name off course isn't (jump_sys.name). '''lc''' is used as the short name for the '''core''' translation resource.

textLine = jumpIndex ..": ".. jump_sys.name .. " (" .. string.format("%.2f", distance) .. lc.UNIT_LY .. " - " .. fuel .. lc.UNIT_TONNES..")"

Here is what the final formatted text looks like (right side, two selected jump routes): 
[[File:hyperjumpplanner.png]]

===PiGUI - Format===

Pioneer has it's own set of formatting functions accessible through PiGUI, our UI. Some of it is realised on the C++ side and described in codedoc [https://codedoc.pioneerspacesim.net/#CClass:Format here]. Most of the functions, however, are strictly Lua and reside in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/libs/text.lua#L146-L385 data/pigui/libs/text.lua]. You access the functions with '''require''' and make sure that '''PiGUI''' is in the scope.

local ui = require 'pigui'
local Format = require 'Format'

Here is an example from the System overview. The table to the right is relying heavily on the Format functions.
[[File:Systemoverview.png]]

The code responsible for the table is here in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/modules/system-view-ui.lua#L811-L840 data/pigui/modules/system-view-ui.lua] with an excerpt showed below. The examples below take 1 or two arguments and the lines ending with 'or nil' is what makes the System overview info window omit values that don't apply to the selected system body.

...
{ name = lc.ESCAPE_VELOCITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Speed(body.escapeVelocity , true) or nil },
{ name = lc.MEAN_DENSITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Mass(body.meanDensity).."/m³" or nil },
{ name = lc.ORBITAL_PERIOD, icon = icons.body_orbit_period,
value = op and op > 0 and ui.Format.Duration(op, 2) or nil },
{ name = lc.DAY_LENGTH, icon = icons.body_day_length,
value = rp > 0 and ui.Format.Duration(rp, 2) or nil },
...

==String variables==

When you want a string to present variable data such as numbers and names you use the <code>interp()</code> function. <code>interp()</code> accepts a table '{}' and the corresponding keys are then embedded in the translated strings enclosed by curly brackets '{}'.

Using ''''module-stationrefuelling'''' we can do:
print(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = 'JFK', fee = 50}))

Example from the actual StationRefuelling module:

'''data/modules/StationRefuelling/'''
Comms.Message(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = station.label,fee = Format.Money(fee)}))

'''data/lang/module-stationrefuelling/en.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Welcome to {station}. Your landing fee of {fee} has been deducted."
}

'''data/lang/module-stationrefuelling/it.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Benvenuti a {station}. Vi è stata dedotta una tassa di atterraggio di {fee}."
}

==Mission flavours==

A script can define a mission and then place many instances of it onto many bulletin boards. A script that introduces many instances in the game should provide some variety; it would harm immersion if, for examle, all delivery missions were worded identically. The easiest way to achieve multiple versions, or "flavours", is by just making a number of different strings and then choosing between them with a simple random function. This is how the [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L18:L48 deny] and [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L282:L320 pirate taunt] messages are done in the DeliverPackage module.

'''data/modules/DeliverPackage/DeliverPackage.lua'''
local num_deny = 8

...

if not qualified then
local introtext = l["DENY_"..Engine.rand:Integer(1,num_deny)-1]
form:SetMessage(introtext)
return
end

'''data/lang/module-deliverpackage/en.json'''
"DENY_0": {
"description": "",
"message": "I'm sorry, but I don't think I can trust you with this delivery."
},
"DENY_1": {
"description": "",
"message": "Come back when you have some qualifications."

...

"DENY_7": {
"description": "",
"message": "I'm not willing to risk this delivery on someone without any qualifications like you."
You don't have to use a string variable that has been passed to the translation file. The pirate taunts, for example, have access to the clients name and the destination of the package but this information is only used in some of the strings.

"PIRATE_TAUNTS_7": {
"description": "",
"message": "That package isn't going to reach its destination today."
},
"PIRATE_TAUNTS_8": {
"description": "",
"message": "You're not getting to {location} today!"
Another way to add variation is to have a table of strings that are variations of a theme, a flavour. In the example below, again from the DeliverPackage module, you have two of the lines from '''FLAVOUR_0''' AND '''FLAVOUR_1''' compared.
"FLAVOUR_0_ADTEXT": {
"description": "",
"message": "GOING TO the {system} system? Money paid for delivery of a small package."
},
"FLAVOUR_0_FAILUREMSG": {
"description": "",
"message": "Unacceptable! You took forever over that delivery. I'm not willing to pay you."

...

"FLAVOUR_1_ADTEXT": {
"description": "",
"message": "WANTED. Delivery of a package to the {system} system."
},
"FLAVOUR_1_FAILUREMSG": {
"description": "",
"message": "I'm frustrated by the late delivery of my package, and I refuse to pay you."
There are ten flavours in DeliverPackage of five strings each, each forming a short story line. They are static in that you only see lines from within the same flavour. You know what lines will follow if you accept the mission and after a short time of playing you know this already from seeing the ad if delivering things is your forte. It's hard to share strings in between the flavours as they would need to be much more similar. It's a trade off. You could build a very complex interaction with the customers but in the end it needs to be translatable.

Generally, the more specific the text is, the stranger it will appear to see it multiple times in the game. For example, consider the following two examples:
- "Contract is to move X tonnes of Y to system Z"
- "My uncle's cat got sick, so I can't travel right now, so I need you to take my contract for me, to move X tonnes of Y to my home system Z"
The former might not need any flavours, as it's unpersonal, and very general. Seeing the second string multiple times does break immersion. Solution is to not show it often, either by making the mission rare / single occurance (no script to date does this) or have many flavours, making probability of the same twice low.

Strings and translation

2025-03-21T22:01:25Z

Zonkmachine: /* PiGUI - String formatting */ Change subtitle

==Internationalization==
Recommended reading: [https://dev.pioneerspacesim.net/contribute/translations Pioneer translators wikipage]

It is important that scripters are familiar with the translation system. In the previous example '''hello_world.lua''' used strings directly like <code>print("Hello, World!")</code>. In order for Pioneer to be translated we instead use tokens and calls on the <code>'Lang'</code> module to substitute it for the string in the chosen language. The translated strings are stored together with their 'key' in json format, one language per file that are kept in the [https://github.com/pioneerspacesim/pioneer/tree/master/data/lang data/lang/] directory. If the script file in which they are used is from the '''data/modules''' directory they have names starting with '''module-''' and ending with the name of the module written in one word, in small caps, and with the '.lua' ending omitted. The final translation from English to other languages is done on Pioneer's project page at [https://www.transifex.com/pioneer/pioneer/ Transifex], a dedicated online translation tool. The translations are committed to the pioneer/master branch on GitHub by a bot and are not to be edited manually apart from the '''en.json''' files.

==Translating strings==

Below is a minimal example with one string added into the translation system. It takes two files, one in '''data/modules''' and one in '''data/lang/module-hello'''. The print statement isn't wrapped in a function so it will be executed when the '''hello.lua''' is being parsed on startup. You will have to scroll through the command-line history to find it interleaved with the other output.

'''data/modules/hello.lua'''.
local Lang = require 'Lang'
local l = Lang.GetResource("module-hello")

print(l.HELLO)

And a corresponding file containing the translated string, and a description field shown to the translator, giving the context.

'''data/lang/module-hello/en.json'''
{
"HELLO": {
"description": "A classic message.",
"message": "Hello World!"
}
}

In short, any script containing strings that needs translation needs to load the <code>'Lang'</code> module:
local Lang = require 'Lang'
Then load the translation resource they want to use in their module, often just named <code>'l'</code> as in:
local l = Lang.GetResource("module-hello")
You may load more than one translation resource in your script but they will need to have unique names:
local lh = Lang.GetResource("module-hello")
local lg = Lang.GetResource("module-goodbye")

==Working with strings==

Recommended chapters from [https://www.lua.org/pil/contents.html Programming in Lua (first edition) ] 
[https://www.lua.org/pil/2.4.html 2.4 – Strings] 
[https://www.lua.org/pil/3.4.html 3.4 – Concatenation] 
[https://www.lua.org/pil/20.html 20 – The String Library] 
And from the [https://www.lua.org/manual/5.2/ Lua 5.2 Reference Manual] 
[https://www.lua.org/manual/5.2/manual.html#6.4 6.4 – String Manipulation] 

===Concatenation===

Instead of serving ready made sentences we can stitch them together with the Lua string concatenation operator <code>..</code>. The following codelines result in the same output.
print("Hello Clarice!")
print("Hello" .. " " .. "Clarice!")

This could be created by the more generic:

local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local NameGen = require 'NameGen'

local GREETING = 'Hello'
local FBIAGENT = NameGen.Surname()

local onShipDocked = function (ship)
if ship == Game.player then
Comms.Message(GREETING .. ' ' .. FBIAGENT .. '!')
end
end

Event.Register("onShipDocked", onShipDocked)

The <code>..</code> operator is used all over the codebase. Try a search for its occurrence. On Linux I would do <code>grep -R " \.\. " data/modules/ data/libs/ data/pigui/</code> and that will render a lot of output.

===Token concatenation===

You concatenate strings but you also concatenate the string tokens. In the example below from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/modules/DonateToCranks/DonateToCranks.lua#L14-L21 DonateToCranks.lua]''' we see the table <code>flavours</code> being populated by strings from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/lang/module-donatetocranks/en.json data/lang/module-donatetocranks/en.lua]'''

local flavours = {}
for i = 0,9 do
table.insert(flavours, {
title = l["FLAVOUR_" .. i .. "_ADTITLE"],
desc = l["FLAVOUR_" .. i .. "_DESC"],
message = l["FLAVOUR_" .. i .. "_MESSAGE"],
})
end

The first string in the table is given the value of <code>l[FLAVOUR_" .. i .. "_ADTITLE]</code> is concatenated to <code>l[FLAVOUR_0_ADTITLE]</code> which corresponds to the first string in the language module which is seen below.

{
"FLAVOUR_0_ADTITLE": {
"description": "",
"message": "DONATE!"
},
"FLAVOUR_0_DESC": {
"description": "",
"message": "The Church of The Celestial Flying Spaghetti Monster needs YOUR money to spread the word of god."
},
"FLAVOUR_0_MESSAGE": {
"description": "",
"message": "Please select an amount to donate to the Church of the Celestial Flying Spaghetti Monster."
},
"FLAVOUR_1_ADTITLE": {
"description": "",
"message": "DONATE"
},

...

===Lua Standard Library - String manipulation===

I would start to search the '''data/''' register for ''' 'string' '''. to get a feeling for how it's used. Again on Linux i would use the 'grep' command. <code>grep -R "string\." data/</code>. You will see that the two most frequently used functions is <code>string.format()</code>, which is a part of the lua standard library, and <code>string.interp()</code>, which is a Pioneer global function residing in '''data/libs/autoload.lua''', and is described in the next paragraph about [https://wiki.pioneerspacesim.net/wiki/Strings_and_translation#String_variables String variables].

Some examples from the Lua standard library:
Comms.Message(string.lower('wHaT cAsE sHoULd I usE?'))

Maybe not the most easy function to fit into Pioneer, but it's there:
Comms.Message('Today is opposite day!')
Comms.Message(string.reverse('No, today is not opposite day!'))

A more complex example from '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/pigui/modules/hyperjump-planner.lua#L141 data/pigui/modules/hyperjump-planner.lua]''' 
Here <code>string.format("%.2f", distance)</code> is used to set the number of decimals in the jump to two. The units are translatable but the system name off course isn't (jump_sys.name). '''lc''' is used as the short name for the '''core''' translation resource.

textLine = jumpIndex ..": ".. jump_sys.name .. " (" .. string.format("%.2f", distance) .. lc.UNIT_LY .. " - " .. fuel .. lc.UNIT_TONNES..")"

Here is what the final formatted text looks like (right side, two selected jump routes): 
[[File:hyperjumpplanner.png]]

===PiGUI - Format===

Pioneer has it's own set of formatting functions accessible through PiGUI, our UI. Some of it is realised on the C++ side and described in codedoc [https://codedoc.pioneerspacesim.net/#CClass:Format here]. Most of the functions, however, are strictly Lua and reside in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/libs/text.lua#L146-L385 data/pigui/libs/text.lua]. You access the functions with ''''require''''.

local Format = require 'Format'

Here is an example from the System overview. The table to the right is relying heavily on the Format functions.
[[File:Systemoverview.png]]

The code responsible for the table is here in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/modules/system-view-ui.lua#L811-L840 data/pigui/modules/system-view-ui.lua] with an excerpt showed below. The examples below take 1 or two arguments and the lines ending with 'or nil' is what makes the System overview info window omit values that don't apply to the selected system body.

...
{ name = lc.ESCAPE_VELOCITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Speed(body.escapeVelocity , true) or nil },
{ name = lc.MEAN_DENSITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Mass(body.meanDensity).."/m³" or nil },
{ name = lc.ORBITAL_PERIOD, icon = icons.body_orbit_period,
value = op and op > 0 and ui.Format.Duration(op, 2) or nil },
{ name = lc.DAY_LENGTH, icon = icons.body_day_length,
value = rp > 0 and ui.Format.Duration(rp, 2) or nil },
...

==String variables==

When you want a string to present variable data such as numbers and names you use the <code>interp()</code> function. <code>interp()</code> accepts a table '{}' and the corresponding keys are then embedded in the translated strings enclosed by curly brackets '{}'.

Using ''''module-stationrefuelling'''' we can do:
print(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = 'JFK', fee = 50}))

Example from the actual StationRefuelling module:

'''data/modules/StationRefuelling/'''
Comms.Message(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = station.label,fee = Format.Money(fee)}))

'''data/lang/module-stationrefuelling/en.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Welcome to {station}. Your landing fee of {fee} has been deducted."
}

'''data/lang/module-stationrefuelling/it.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Benvenuti a {station}. Vi è stata dedotta una tassa di atterraggio di {fee}."
}

==Mission flavours==

A script can define a mission and then place many instances of it onto many bulletin boards. A script that introduces many instances in the game should provide some variety; it would harm immersion if, for examle, all delivery missions were worded identically. The easiest way to achieve multiple versions, or "flavours", is by just making a number of different strings and then choosing between them with a simple random function. This is how the [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L18:L48 deny] and [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L282:L320 pirate taunt] messages are done in the DeliverPackage module.

'''data/modules/DeliverPackage/DeliverPackage.lua'''
local num_deny = 8

...

if not qualified then
local introtext = l["DENY_"..Engine.rand:Integer(1,num_deny)-1]
form:SetMessage(introtext)
return
end

'''data/lang/module-deliverpackage/en.json'''
"DENY_0": {
"description": "",
"message": "I'm sorry, but I don't think I can trust you with this delivery."
},
"DENY_1": {
"description": "",
"message": "Come back when you have some qualifications."

...

"DENY_7": {
"description": "",
"message": "I'm not willing to risk this delivery on someone without any qualifications like you."
You don't have to use a string variable that has been passed to the translation file. The pirate taunts, for example, have access to the clients name and the destination of the package but this information is only used in some of the strings.

"PIRATE_TAUNTS_7": {
"description": "",
"message": "That package isn't going to reach its destination today."
},
"PIRATE_TAUNTS_8": {
"description": "",
"message": "You're not getting to {location} today!"
Another way to add variation is to have a table of strings that are variations of a theme, a flavour. In the example below, again from the DeliverPackage module, you have two of the lines from '''FLAVOUR_0''' AND '''FLAVOUR_1''' compared.
"FLAVOUR_0_ADTEXT": {
"description": "",
"message": "GOING TO the {system} system? Money paid for delivery of a small package."
},
"FLAVOUR_0_FAILUREMSG": {
"description": "",
"message": "Unacceptable! You took forever over that delivery. I'm not willing to pay you."

...

"FLAVOUR_1_ADTEXT": {
"description": "",
"message": "WANTED. Delivery of a package to the {system} system."
},
"FLAVOUR_1_FAILUREMSG": {
"description": "",
"message": "I'm frustrated by the late delivery of my package, and I refuse to pay you."
There are ten flavours in DeliverPackage of five strings each, each forming a short story line. They are static in that you only see lines from within the same flavour. You know what lines will follow if you accept the mission and after a short time of playing you know this already from seeing the ad if delivering things is your forte. It's hard to share strings in between the flavours as they would need to be much more similar. It's a trade off. You could build a very complex interaction with the customers but in the end it needs to be translatable.

Generally, the more specific the text is, the stranger it will appear to see it multiple times in the game. For example, consider the following two examples:
- "Contract is to move X tonnes of Y to system Z"
- "My uncle's cat got sick, so I can't travel right now, so I need you to take my contract for me, to move X tonnes of Y to my home system Z"
The former might not need any flavours, as it's unpersonal, and very general. Seeing the second string multiple times does break immersion. Solution is to not show it often, either by making the mission rare / single occurance (no script to date does this) or have many flavours, making probability of the same twice low.

Strings and translation

2025-03-21T20:39:24Z

Zonkmachine: /* PiGUI - String formatting */ Code example fixup

==Internationalization==
Recommended reading: [https://dev.pioneerspacesim.net/contribute/translations Pioneer translators wikipage]

It is important that scripters are familiar with the translation system. In the previous example '''hello_world.lua''' used strings directly like <code>print("Hello, World!")</code>. In order for Pioneer to be translated we instead use tokens and calls on the <code>'Lang'</code> module to substitute it for the string in the chosen language. The translated strings are stored together with their 'key' in json format, one language per file that are kept in the [https://github.com/pioneerspacesim/pioneer/tree/master/data/lang data/lang/] directory. If the script file in which they are used is from the '''data/modules''' directory they have names starting with '''module-''' and ending with the name of the module written in one word, in small caps, and with the '.lua' ending omitted. The final translation from English to other languages is done on Pioneer's project page at [https://www.transifex.com/pioneer/pioneer/ Transifex], a dedicated online translation tool. The translations are committed to the pioneer/master branch on GitHub by a bot and are not to be edited manually apart from the '''en.json''' files.

==Translating strings==

Below is a minimal example with one string added into the translation system. It takes two files, one in '''data/modules''' and one in '''data/lang/module-hello'''. The print statement isn't wrapped in a function so it will be executed when the '''hello.lua''' is being parsed on startup. You will have to scroll through the command-line history to find it interleaved with the other output.

'''data/modules/hello.lua'''.
local Lang = require 'Lang'
local l = Lang.GetResource("module-hello")

print(l.HELLO)

And a corresponding file containing the translated string, and a description field shown to the translator, giving the context.

'''data/lang/module-hello/en.json'''
{
"HELLO": {
"description": "A classic message.",
"message": "Hello World!"
}
}

In short, any script containing strings that needs translation needs to load the <code>'Lang'</code> module:
local Lang = require 'Lang'
Then load the translation resource they want to use in their module, often just named <code>'l'</code> as in:
local l = Lang.GetResource("module-hello")
You may load more than one translation resource in your script but they will need to have unique names:
local lh = Lang.GetResource("module-hello")
local lg = Lang.GetResource("module-goodbye")

==Working with strings==

Recommended chapters from [https://www.lua.org/pil/contents.html Programming in Lua (first edition) ] 
[https://www.lua.org/pil/2.4.html 2.4 – Strings] 
[https://www.lua.org/pil/3.4.html 3.4 – Concatenation] 
[https://www.lua.org/pil/20.html 20 – The String Library] 
And from the [https://www.lua.org/manual/5.2/ Lua 5.2 Reference Manual] 
[https://www.lua.org/manual/5.2/manual.html#6.4 6.4 – String Manipulation] 

===Concatenation===

Instead of serving ready made sentences we can stitch them together with the Lua string concatenation operator <code>..</code>. The following codelines result in the same output.
print("Hello Clarice!")
print("Hello" .. " " .. "Clarice!")

This could be created by the more generic:

local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local NameGen = require 'NameGen'

local GREETING = 'Hello'
local FBIAGENT = NameGen.Surname()

local onShipDocked = function (ship)
if ship == Game.player then
Comms.Message(GREETING .. ' ' .. FBIAGENT .. '!')
end
end

Event.Register("onShipDocked", onShipDocked)

The <code>..</code> operator is used all over the codebase. Try a search for its occurrence. On Linux I would do <code>grep -R " \.\. " data/modules/ data/libs/ data/pigui/</code> and that will render a lot of output.

===Token concatenation===

You concatenate strings but you also concatenate the string tokens. In the example below from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/modules/DonateToCranks/DonateToCranks.lua#L14-L21 DonateToCranks.lua]''' we see the table <code>flavours</code> being populated by strings from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/lang/module-donatetocranks/en.json data/lang/module-donatetocranks/en.lua]'''

local flavours = {}
for i = 0,9 do
table.insert(flavours, {
title = l["FLAVOUR_" .. i .. "_ADTITLE"],
desc = l["FLAVOUR_" .. i .. "_DESC"],
message = l["FLAVOUR_" .. i .. "_MESSAGE"],
})
end

The first string in the table is given the value of <code>l[FLAVOUR_" .. i .. "_ADTITLE]</code> is concatenated to <code>l[FLAVOUR_0_ADTITLE]</code> which corresponds to the first string in the language module which is seen below.

{
"FLAVOUR_0_ADTITLE": {
"description": "",
"message": "DONATE!"
},
"FLAVOUR_0_DESC": {
"description": "",
"message": "The Church of The Celestial Flying Spaghetti Monster needs YOUR money to spread the word of god."
},
"FLAVOUR_0_MESSAGE": {
"description": "",
"message": "Please select an amount to donate to the Church of the Celestial Flying Spaghetti Monster."
},
"FLAVOUR_1_ADTITLE": {
"description": "",
"message": "DONATE"
},

...

===Lua Standard Library - String manipulation===

I would start to search the '''data/''' register for ''' 'string' '''. to get a feeling for how it's used. Again on Linux i would use the 'grep' command. <code>grep -R "string\." data/</code>. You will see that the two most frequently used functions is <code>string.format()</code>, which is a part of the lua standard library, and <code>string.interp()</code>, which is a Pioneer global function residing in '''data/libs/autoload.lua''', and is described in the next paragraph about [https://wiki.pioneerspacesim.net/wiki/Strings_and_translation#String_variables String variables].

Some examples from the Lua standard library:
Comms.Message(string.lower('wHaT cAsE sHoULd I usE?'))

Maybe not the most easy function to fit into Pioneer, but it's there:
Comms.Message('Today is opposite day!')
Comms.Message(string.reverse('No, today is not opposite day!'))

A more complex example from '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/pigui/modules/hyperjump-planner.lua#L141 data/pigui/modules/hyperjump-planner.lua]''' 
Here <code>string.format("%.2f", distance)</code> is used to set the number of decimals in the jump to two. The units are translatable but the system name off course isn't (jump_sys.name). '''lc''' is used as the short name for the '''core''' translation resource.

textLine = jumpIndex ..": ".. jump_sys.name .. " (" .. string.format("%.2f", distance) .. lc.UNIT_LY .. " - " .. fuel .. lc.UNIT_TONNES..")"

Here is what the final formatted text looks like (right side, two selected jump routes): 
[[File:hyperjumpplanner.png]]

===PiGUI - String formatting===

Pioneer has it's own set of formatting functions accessible through PiGUI, our UI. Some of it is realised on the C++ side and described in codedoc [https://codedoc.pioneerspacesim.net/#CClass:Format here]. Most of the functions, however, are strictly Lua and reside in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/libs/text.lua#L146-L385 data/pigui/libs/text.lua]. You access the functions with ''''require''''.

local Format = require 'Format'

Here is an example from the System overview. The table to the right is relying heavily on the Format functions.
[[File:Systemoverview.png]]

The code responsible for the table is here in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/modules/system-view-ui.lua#L811-L840 data/pigui/modules/system-view-ui.lua] with an excerpt showed below. The examples below take 1 or two arguments and the lines ending with 'or nil' is what makes the System overview info window omit values that don't apply to the selected system body.

...
{ name = lc.ESCAPE_VELOCITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Speed(body.escapeVelocity , true) or nil },
{ name = lc.MEAN_DENSITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Mass(body.meanDensity).."/m³" or nil },
{ name = lc.ORBITAL_PERIOD, icon = icons.body_orbit_period,
value = op and op > 0 and ui.Format.Duration(op, 2) or nil },
{ name = lc.DAY_LENGTH, icon = icons.body_day_length,
value = rp > 0 and ui.Format.Duration(rp, 2) or nil },
...

==String variables==

When you want a string to present variable data such as numbers and names you use the <code>interp()</code> function. <code>interp()</code> accepts a table '{}' and the corresponding keys are then embedded in the translated strings enclosed by curly brackets '{}'.

Using ''''module-stationrefuelling'''' we can do:
print(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = 'JFK', fee = 50}))

Example from the actual StationRefuelling module:

'''data/modules/StationRefuelling/'''
Comms.Message(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = station.label,fee = Format.Money(fee)}))

'''data/lang/module-stationrefuelling/en.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Welcome to {station}. Your landing fee of {fee} has been deducted."
}

'''data/lang/module-stationrefuelling/it.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Benvenuti a {station}. Vi è stata dedotta una tassa di atterraggio di {fee}."
}

==Mission flavours==

A script can define a mission and then place many instances of it onto many bulletin boards. A script that introduces many instances in the game should provide some variety; it would harm immersion if, for examle, all delivery missions were worded identically. The easiest way to achieve multiple versions, or "flavours", is by just making a number of different strings and then choosing between them with a simple random function. This is how the [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L18:L48 deny] and [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L282:L320 pirate taunt] messages are done in the DeliverPackage module.

'''data/modules/DeliverPackage/DeliverPackage.lua'''
local num_deny = 8

...

if not qualified then
local introtext = l["DENY_"..Engine.rand:Integer(1,num_deny)-1]
form:SetMessage(introtext)
return
end

'''data/lang/module-deliverpackage/en.json'''
"DENY_0": {
"description": "",
"message": "I'm sorry, but I don't think I can trust you with this delivery."
},
"DENY_1": {
"description": "",
"message": "Come back when you have some qualifications."

...

"DENY_7": {
"description": "",
"message": "I'm not willing to risk this delivery on someone without any qualifications like you."
You don't have to use a string variable that has been passed to the translation file. The pirate taunts, for example, have access to the clients name and the destination of the package but this information is only used in some of the strings.

"PIRATE_TAUNTS_7": {
"description": "",
"message": "That package isn't going to reach its destination today."
},
"PIRATE_TAUNTS_8": {
"description": "",
"message": "You're not getting to {location} today!"
Another way to add variation is to have a table of strings that are variations of a theme, a flavour. In the example below, again from the DeliverPackage module, you have two of the lines from '''FLAVOUR_0''' AND '''FLAVOUR_1''' compared.
"FLAVOUR_0_ADTEXT": {
"description": "",
"message": "GOING TO the {system} system? Money paid for delivery of a small package."
},
"FLAVOUR_0_FAILUREMSG": {
"description": "",
"message": "Unacceptable! You took forever over that delivery. I'm not willing to pay you."

...

"FLAVOUR_1_ADTEXT": {
"description": "",
"message": "WANTED. Delivery of a package to the {system} system."
},
"FLAVOUR_1_FAILUREMSG": {
"description": "",
"message": "I'm frustrated by the late delivery of my package, and I refuse to pay you."
There are ten flavours in DeliverPackage of five strings each, each forming a short story line. They are static in that you only see lines from within the same flavour. You know what lines will follow if you accept the mission and after a short time of playing you know this already from seeing the ad if delivering things is your forte. It's hard to share strings in between the flavours as they would need to be much more similar. It's a trade off. You could build a very complex interaction with the customers but in the end it needs to be translatable.

Generally, the more specific the text is, the stranger it will appear to see it multiple times in the game. For example, consider the following two examples:
- "Contract is to move X tonnes of Y to system Z"
- "My uncle's cat got sick, so I can't travel right now, so I need you to take my contract for me, to move X tonnes of Y to my home system Z"
The former might not need any flavours, as it's unpersonal, and very general. Seeing the second string multiple times does break immersion. Solution is to not show it often, either by making the mission rare / single occurance (no script to date does this) or have many flavours, making probability of the same twice low.

Strings and translation

2025-03-21T20:12:11Z

Zonkmachine: /* Lua Standard Library - String manipulation */ Fixup

==Internationalization==
Recommended reading: [https://dev.pioneerspacesim.net/contribute/translations Pioneer translators wikipage]

It is important that scripters are familiar with the translation system. In the previous example '''hello_world.lua''' used strings directly like <code>print("Hello, World!")</code>. In order for Pioneer to be translated we instead use tokens and calls on the <code>'Lang'</code> module to substitute it for the string in the chosen language. The translated strings are stored together with their 'key' in json format, one language per file that are kept in the [https://github.com/pioneerspacesim/pioneer/tree/master/data/lang data/lang/] directory. If the script file in which they are used is from the '''data/modules''' directory they have names starting with '''module-''' and ending with the name of the module written in one word, in small caps, and with the '.lua' ending omitted. The final translation from English to other languages is done on Pioneer's project page at [https://www.transifex.com/pioneer/pioneer/ Transifex], a dedicated online translation tool. The translations are committed to the pioneer/master branch on GitHub by a bot and are not to be edited manually apart from the '''en.json''' files.

==Translating strings==

Below is a minimal example with one string added into the translation system. It takes two files, one in '''data/modules''' and one in '''data/lang/module-hello'''. The print statement isn't wrapped in a function so it will be executed when the '''hello.lua''' is being parsed on startup. You will have to scroll through the command-line history to find it interleaved with the other output.

'''data/modules/hello.lua'''.
local Lang = require 'Lang'
local l = Lang.GetResource("module-hello")

print(l.HELLO)

And a corresponding file containing the translated string, and a description field shown to the translator, giving the context.

'''data/lang/module-hello/en.json'''
{
"HELLO": {
"description": "A classic message.",
"message": "Hello World!"
}
}

In short, any script containing strings that needs translation needs to load the <code>'Lang'</code> module:
local Lang = require 'Lang'
Then load the translation resource they want to use in their module, often just named <code>'l'</code> as in:
local l = Lang.GetResource("module-hello")
You may load more than one translation resource in your script but they will need to have unique names:
local lh = Lang.GetResource("module-hello")
local lg = Lang.GetResource("module-goodbye")

==Working with strings==

Recommended chapters from [https://www.lua.org/pil/contents.html Programming in Lua (first edition) ] 
[https://www.lua.org/pil/2.4.html 2.4 – Strings] 
[https://www.lua.org/pil/3.4.html 3.4 – Concatenation] 
[https://www.lua.org/pil/20.html 20 – The String Library] 
And from the [https://www.lua.org/manual/5.2/ Lua 5.2 Reference Manual] 
[https://www.lua.org/manual/5.2/manual.html#6.4 6.4 – String Manipulation] 

===Concatenation===

Instead of serving ready made sentences we can stitch them together with the Lua string concatenation operator <code>..</code>. The following codelines result in the same output.
print("Hello Clarice!")
print("Hello" .. " " .. "Clarice!")

This could be created by the more generic:

local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local NameGen = require 'NameGen'

local GREETING = 'Hello'
local FBIAGENT = NameGen.Surname()

local onShipDocked = function (ship)
if ship == Game.player then
Comms.Message(GREETING .. ' ' .. FBIAGENT .. '!')
end
end

Event.Register("onShipDocked", onShipDocked)

The <code>..</code> operator is used all over the codebase. Try a search for its occurrence. On Linux I would do <code>grep -R " \.\. " data/modules/ data/libs/ data/pigui/</code> and that will render a lot of output.

===Token concatenation===

You concatenate strings but you also concatenate the string tokens. In the example below from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/modules/DonateToCranks/DonateToCranks.lua#L14-L21 DonateToCranks.lua]''' we see the table <code>flavours</code> being populated by strings from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/lang/module-donatetocranks/en.json data/lang/module-donatetocranks/en.lua]'''

local flavours = {}
for i = 0,9 do
table.insert(flavours, {
title = l["FLAVOUR_" .. i .. "_ADTITLE"],
desc = l["FLAVOUR_" .. i .. "_DESC"],
message = l["FLAVOUR_" .. i .. "_MESSAGE"],
})
end

The first string in the table is given the value of <code>l[FLAVOUR_" .. i .. "_ADTITLE]</code> is concatenated to <code>l[FLAVOUR_0_ADTITLE]</code> which corresponds to the first string in the language module which is seen below.

{
"FLAVOUR_0_ADTITLE": {
"description": "",
"message": "DONATE!"
},
"FLAVOUR_0_DESC": {
"description": "",
"message": "The Church of The Celestial Flying Spaghetti Monster needs YOUR money to spread the word of god."
},
"FLAVOUR_0_MESSAGE": {
"description": "",
"message": "Please select an amount to donate to the Church of the Celestial Flying Spaghetti Monster."
},
"FLAVOUR_1_ADTITLE": {
"description": "",
"message": "DONATE"
},

...

===Lua Standard Library - String manipulation===

I would start to search the '''data/''' register for ''' 'string' '''. to get a feeling for how it's used. Again on Linux i would use the 'grep' command. <code>grep -R "string\." data/</code>. You will see that the two most frequently used functions is <code>string.format()</code>, which is a part of the lua standard library, and <code>string.interp()</code>, which is a Pioneer global function residing in '''data/libs/autoload.lua''', and is described in the next paragraph about [https://wiki.pioneerspacesim.net/wiki/Strings_and_translation#String_variables String variables].

Some examples from the Lua standard library:
Comms.Message(string.lower('wHaT cAsE sHoULd I usE?'))

Maybe not the most easy function to fit into Pioneer, but it's there:
Comms.Message('Today is opposite day!')
Comms.Message(string.reverse('No, today is not opposite day!'))

A more complex example from '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/pigui/modules/hyperjump-planner.lua#L141 data/pigui/modules/hyperjump-planner.lua]''' 
Here <code>string.format("%.2f", distance)</code> is used to set the number of decimals in the jump to two. The units are translatable but the system name off course isn't (jump_sys.name). '''lc''' is used as the short name for the '''core''' translation resource.

textLine = jumpIndex ..": ".. jump_sys.name .. " (" .. string.format("%.2f", distance) .. lc.UNIT_LY .. " - " .. fuel .. lc.UNIT_TONNES..")"

Here is what the final formatted text looks like (right side, two selected jump routes): 
[[File:hyperjumpplanner.png]]

===PiGUI - String formatting===

Pioneer has it's own set of formatting functions accessible through PiGUI, our UI. Some of it is realised on the C++ side and described in codedoc [https://codedoc.pioneerspacesim.net/#CClass:Format here]. Most of the functions, however, are strictly Lua and reside in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/libs/text.lua#L146-L385 data/pigui/libs/text.lua]. You access the functions with ''''require''''.

local Format = require 'Format'

Here is an example from the System overview. The table to the right is relying heavily on the Format functions.
[[File:Systemoverview.png]]

The code responsible for the table is here in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/modules/system-view-ui.lua#L811-L840 data/pigui/modules/system-view-ui.lua] with an excerpt showed below. The examples below take 1 or two arguments and the lines ending with 'or nil' is what makes the System overview info window omit values that don't apply to the selected system body.

{ name = lc.ESCAPE_VELOCITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Speed(body.escapeVelocity , true) or nil },
{ name = lc.MEAN_DENSITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Mass(body.meanDensity).."/m³" or nil },
{ name = lc.ORBITAL_PERIOD, icon = icons.body_orbit_period,
value = op and op > 0 and ui.Format.Duration(op, 2) or nil },
{ name = lc.DAY_LENGTH, icon = icons.body_day_length,
value = rp > 0 and ui.Format.Duration(rp, 2) or nil },
{ name = luc.ORBIT_APOAPSIS, icon = icons.body_semi_major_axis,
value = (parent and not surface) and ui.Format.Distance(body.apoapsis) or nil },
{ name = luc.ORBIT_PERIAPSIS, icon = icons.body_semi_major_axis,
value = (parent and not surface) and ui.Format.Distance(body.periapsis) or nil },

==String variables==

When you want a string to present variable data such as numbers and names you use the <code>interp()</code> function. <code>interp()</code> accepts a table '{}' and the corresponding keys are then embedded in the translated strings enclosed by curly brackets '{}'.

Using ''''module-stationrefuelling'''' we can do:
print(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = 'JFK', fee = 50}))

Example from the actual StationRefuelling module:

'''data/modules/StationRefuelling/'''
Comms.Message(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = station.label,fee = Format.Money(fee)}))

'''data/lang/module-stationrefuelling/en.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Welcome to {station}. Your landing fee of {fee} has been deducted."
}

'''data/lang/module-stationrefuelling/it.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Benvenuti a {station}. Vi è stata dedotta una tassa di atterraggio di {fee}."
}

==Mission flavours==

A script can define a mission and then place many instances of it onto many bulletin boards. A script that introduces many instances in the game should provide some variety; it would harm immersion if, for examle, all delivery missions were worded identically. The easiest way to achieve multiple versions, or "flavours", is by just making a number of different strings and then choosing between them with a simple random function. This is how the [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L18:L48 deny] and [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L282:L320 pirate taunt] messages are done in the DeliverPackage module.

'''data/modules/DeliverPackage/DeliverPackage.lua'''
local num_deny = 8

...

if not qualified then
local introtext = l["DENY_"..Engine.rand:Integer(1,num_deny)-1]
form:SetMessage(introtext)
return
end

'''data/lang/module-deliverpackage/en.json'''
"DENY_0": {
"description": "",
"message": "I'm sorry, but I don't think I can trust you with this delivery."
},
"DENY_1": {
"description": "",
"message": "Come back when you have some qualifications."

...

"DENY_7": {
"description": "",
"message": "I'm not willing to risk this delivery on someone without any qualifications like you."
You don't have to use a string variable that has been passed to the translation file. The pirate taunts, for example, have access to the clients name and the destination of the package but this information is only used in some of the strings.

"PIRATE_TAUNTS_7": {
"description": "",
"message": "That package isn't going to reach its destination today."
},
"PIRATE_TAUNTS_8": {
"description": "",
"message": "You're not getting to {location} today!"
Another way to add variation is to have a table of strings that are variations of a theme, a flavour. In the example below, again from the DeliverPackage module, you have two of the lines from '''FLAVOUR_0''' AND '''FLAVOUR_1''' compared.
"FLAVOUR_0_ADTEXT": {
"description": "",
"message": "GOING TO the {system} system? Money paid for delivery of a small package."
},
"FLAVOUR_0_FAILUREMSG": {
"description": "",
"message": "Unacceptable! You took forever over that delivery. I'm not willing to pay you."

...

"FLAVOUR_1_ADTEXT": {
"description": "",
"message": "WANTED. Delivery of a package to the {system} system."
},
"FLAVOUR_1_FAILUREMSG": {
"description": "",
"message": "I'm frustrated by the late delivery of my package, and I refuse to pay you."
There are ten flavours in DeliverPackage of five strings each, each forming a short story line. They are static in that you only see lines from within the same flavour. You know what lines will follow if you accept the mission and after a short time of playing you know this already from seeing the ad if delivering things is your forte. It's hard to share strings in between the flavours as they would need to be much more similar. It's a trade off. You could build a very complex interaction with the customers but in the end it needs to be translatable.

Generally, the more specific the text is, the stranger it will appear to see it multiple times in the game. For example, consider the following two examples:
- "Contract is to move X tonnes of Y to system Z"
- "My uncle's cat got sick, so I can't travel right now, so I need you to take my contract for me, to move X tonnes of Y to my home system Z"
The former might not need any flavours, as it's unpersonal, and very general. Seeing the second string multiple times does break immersion. Solution is to not show it often, either by making the mission rare / single occurance (no script to date does this) or have many flavours, making probability of the same twice low.

Strings and translation

2025-03-21T19:45:19Z

Zonkmachine: /* PiGUI - String formatting */ fixup

==Internationalization==
Recommended reading: [https://dev.pioneerspacesim.net/contribute/translations Pioneer translators wikipage]

It is important that scripters are familiar with the translation system. In the previous example '''hello_world.lua''' used strings directly like <code>print("Hello, World!")</code>. In order for Pioneer to be translated we instead use tokens and calls on the <code>'Lang'</code> module to substitute it for the string in the chosen language. The translated strings are stored together with their 'key' in json format, one language per file that are kept in the [https://github.com/pioneerspacesim/pioneer/tree/master/data/lang data/lang/] directory. If the script file in which they are used is from the '''data/modules''' directory they have names starting with '''module-''' and ending with the name of the module written in one word, in small caps, and with the '.lua' ending omitted. The final translation from English to other languages is done on Pioneer's project page at [https://www.transifex.com/pioneer/pioneer/ Transifex], a dedicated online translation tool. The translations are committed to the pioneer/master branch on GitHub by a bot and are not to be edited manually apart from the '''en.json''' files.

==Translating strings==

Below is a minimal example with one string added into the translation system. It takes two files, one in '''data/modules''' and one in '''data/lang/module-hello'''. The print statement isn't wrapped in a function so it will be executed when the '''hello.lua''' is being parsed on startup. You will have to scroll through the command-line history to find it interleaved with the other output.

'''data/modules/hello.lua'''.
local Lang = require 'Lang'
local l = Lang.GetResource("module-hello")

print(l.HELLO)

And a corresponding file containing the translated string, and a description field shown to the translator, giving the context.

'''data/lang/module-hello/en.json'''
{
"HELLO": {
"description": "A classic message.",
"message": "Hello World!"
}
}

In short, any script containing strings that needs translation needs to load the <code>'Lang'</code> module:
local Lang = require 'Lang'
Then load the translation resource they want to use in their module, often just named <code>'l'</code> as in:
local l = Lang.GetResource("module-hello")
You may load more than one translation resource in your script but they will need to have unique names:
local lh = Lang.GetResource("module-hello")
local lg = Lang.GetResource("module-goodbye")

==Working with strings==

Recommended chapters from [https://www.lua.org/pil/contents.html Programming in Lua (first edition) ] 
[https://www.lua.org/pil/2.4.html 2.4 – Strings] 
[https://www.lua.org/pil/3.4.html 3.4 – Concatenation] 
[https://www.lua.org/pil/20.html 20 – The String Library] 
And from the [https://www.lua.org/manual/5.2/ Lua 5.2 Reference Manual] 
[https://www.lua.org/manual/5.2/manual.html#6.4 6.4 – String Manipulation] 

===Concatenation===

Instead of serving ready made sentences we can stitch them together with the Lua string concatenation operator <code>..</code>. The following codelines result in the same output.
print("Hello Clarice!")
print("Hello" .. " " .. "Clarice!")

This could be created by the more generic:

local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local NameGen = require 'NameGen'

local GREETING = 'Hello'
local FBIAGENT = NameGen.Surname()

local onShipDocked = function (ship)
if ship == Game.player then
Comms.Message(GREETING .. ' ' .. FBIAGENT .. '!')
end
end

Event.Register("onShipDocked", onShipDocked)

The <code>..</code> operator is used all over the codebase. Try a search for its occurrence. On Linux I would do <code>grep -R " \.\. " data/modules/ data/libs/ data/pigui/</code> and that will render a lot of output.

===Token concatenation===

You concatenate strings but you also concatenate the string tokens. In the example below from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/modules/DonateToCranks/DonateToCranks.lua#L14-L21 DonateToCranks.lua]''' we see the table <code>flavours</code> being populated by strings from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/lang/module-donatetocranks/en.json data/lang/module-donatetocranks/en.lua]'''

local flavours = {}
for i = 0,9 do
table.insert(flavours, {
title = l["FLAVOUR_" .. i .. "_ADTITLE"],
desc = l["FLAVOUR_" .. i .. "_DESC"],
message = l["FLAVOUR_" .. i .. "_MESSAGE"],
})
end

The first string in the table is given the value of <code>l[FLAVOUR_" .. i .. "_ADTITLE]</code> is concatenated to <code>l[FLAVOUR_0_ADTITLE]</code> which corresponds to the first string in the language module which is seen below.

{
"FLAVOUR_0_ADTITLE": {
"description": "",
"message": "DONATE!"
},
"FLAVOUR_0_DESC": {
"description": "",
"message": "The Church of The Celestial Flying Spaghetti Monster needs YOUR money to spread the word of god."
},
"FLAVOUR_0_MESSAGE": {
"description": "",
"message": "Please select an amount to donate to the Church of the Celestial Flying Spaghetti Monster."
},
"FLAVOUR_1_ADTITLE": {
"description": "",
"message": "DONATE"
},

...

===Lua Standard Library - String manipulation===

I would start to search the '''data/''' register for ''' 'string' '''. to get a feeling for how it's used. Again on Linux i would use the 'grep' command. <code>grep -R "string\." data/</code>. You will see that the two most frequently used functions is <code>string.format()</code>, which is a part of the lua standard library, and <code>string.interp()</code>, which is a Pioneer global function residing in '''data/libs/autoload.lua''', and is described in the next paragraph about [https://wiki.pioneerspacesim.net/wiki/Strings_and_translation#String_variables String variables].

Some examples from the Lua standard library:
Comms.Message(string.lower('wHaT cAsE sHoULd I usE?'))

Maybe not the most easy function to fit into Pioneer, but it's there:
Comms.Message('Today is opposite day!')
Comms.Message(string.reverse('No, today is not opposite day!'))

A more complex example from '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/pigui/modules/hyperjump-planner.lua#L141 data/pigui/modules/hyperjump-planner.lua]''' 
Here <code>string.format("%.2f", distance)</code> is used to set the number of decimals in the jump to two. The rest is string variables that are not translated (names) and string concatenation. '''lc''' is used as the short name for the '''core''' translation resource. 
textLine = jumpIndex ..": ".. jump_sys.name .. " (" .. string.format("%.2f", distance) .. lc.UNIT_LY .. " - " .. fuel .. lc.UNIT_TONNES..")"

Here is what the final formatted text looks like (right side, two selected jump routes): 
[[File:hyperjumpplanner.png]]

===PiGUI - String formatting===

Pioneer has it's own set of formatting functions accessible through PiGUI, our UI. Some of it is realised on the C++ side and described in codedoc [https://codedoc.pioneerspacesim.net/#CClass:Format here]. Most of the functions, however, are strictly Lua and reside in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/libs/text.lua#L146-L385 data/pigui/libs/text.lua]. You access the functions with ''''require''''.

local Format = require 'Format'

Here is an example from the System overview. The table to the right is relying heavily on the Format functions.
[[File:Systemoverview.png]]

The code responsible for the table is here in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/modules/system-view-ui.lua#L811-L840 data/pigui/modules/system-view-ui.lua] with an excerpt showed below. The examples below take 1 or two arguments and the lines ending with 'or nil' is what makes the System overview info window omit values that don't apply to the selected system body.

{ name = lc.ESCAPE_VELOCITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Speed(body.escapeVelocity , true) or nil },
{ name = lc.MEAN_DENSITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Mass(body.meanDensity).."/m³" or nil },
{ name = lc.ORBITAL_PERIOD, icon = icons.body_orbit_period,
value = op and op > 0 and ui.Format.Duration(op, 2) or nil },
{ name = lc.DAY_LENGTH, icon = icons.body_day_length,
value = rp > 0 and ui.Format.Duration(rp, 2) or nil },
{ name = luc.ORBIT_APOAPSIS, icon = icons.body_semi_major_axis,
value = (parent and not surface) and ui.Format.Distance(body.apoapsis) or nil },
{ name = luc.ORBIT_PERIAPSIS, icon = icons.body_semi_major_axis,
value = (parent and not surface) and ui.Format.Distance(body.periapsis) or nil },

==String variables==

When you want a string to present variable data such as numbers and names you use the <code>interp()</code> function. <code>interp()</code> accepts a table '{}' and the corresponding keys are then embedded in the translated strings enclosed by curly brackets '{}'.

Using ''''module-stationrefuelling'''' we can do:
print(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = 'JFK', fee = 50}))

Example from the actual StationRefuelling module:

'''data/modules/StationRefuelling/'''
Comms.Message(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = station.label,fee = Format.Money(fee)}))

'''data/lang/module-stationrefuelling/en.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Welcome to {station}. Your landing fee of {fee} has been deducted."
}

'''data/lang/module-stationrefuelling/it.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Benvenuti a {station}. Vi è stata dedotta una tassa di atterraggio di {fee}."
}

==Mission flavours==

A script can define a mission and then place many instances of it onto many bulletin boards. A script that introduces many instances in the game should provide some variety; it would harm immersion if, for examle, all delivery missions were worded identically. The easiest way to achieve multiple versions, or "flavours", is by just making a number of different strings and then choosing between them with a simple random function. This is how the [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L18:L48 deny] and [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L282:L320 pirate taunt] messages are done in the DeliverPackage module.

'''data/modules/DeliverPackage/DeliverPackage.lua'''
local num_deny = 8

...

if not qualified then
local introtext = l["DENY_"..Engine.rand:Integer(1,num_deny)-1]
form:SetMessage(introtext)
return
end

'''data/lang/module-deliverpackage/en.json'''
"DENY_0": {
"description": "",
"message": "I'm sorry, but I don't think I can trust you with this delivery."
},
"DENY_1": {
"description": "",
"message": "Come back when you have some qualifications."

...

"DENY_7": {
"description": "",
"message": "I'm not willing to risk this delivery on someone without any qualifications like you."
You don't have to use a string variable that has been passed to the translation file. The pirate taunts, for example, have access to the clients name and the destination of the package but this information is only used in some of the strings.

"PIRATE_TAUNTS_7": {
"description": "",
"message": "That package isn't going to reach its destination today."
},
"PIRATE_TAUNTS_8": {
"description": "",
"message": "You're not getting to {location} today!"
Another way to add variation is to have a table of strings that are variations of a theme, a flavour. In the example below, again from the DeliverPackage module, you have two of the lines from '''FLAVOUR_0''' AND '''FLAVOUR_1''' compared.
"FLAVOUR_0_ADTEXT": {
"description": "",
"message": "GOING TO the {system} system? Money paid for delivery of a small package."
},
"FLAVOUR_0_FAILUREMSG": {
"description": "",
"message": "Unacceptable! You took forever over that delivery. I'm not willing to pay you."

...

"FLAVOUR_1_ADTEXT": {
"description": "",
"message": "WANTED. Delivery of a package to the {system} system."
},
"FLAVOUR_1_FAILUREMSG": {
"description": "",
"message": "I'm frustrated by the late delivery of my package, and I refuse to pay you."
There are ten flavours in DeliverPackage of five strings each, each forming a short story line. They are static in that you only see lines from within the same flavour. You know what lines will follow if you accept the mission and after a short time of playing you know this already from seeing the ad if delivering things is your forte. It's hard to share strings in between the flavours as they would need to be much more similar. It's a trade off. You could build a very complex interaction with the customers but in the end it needs to be translatable.

Generally, the more specific the text is, the stranger it will appear to see it multiple times in the game. For example, consider the following two examples:
- "Contract is to move X tonnes of Y to system Z"
- "My uncle's cat got sick, so I can't travel right now, so I need you to take my contract for me, to move X tonnes of Y to my home system Z"
The former might not need any flavours, as it's unpersonal, and very general. Seeing the second string multiple times does break immersion. Solution is to not show it often, either by making the mission rare / single occurance (no script to date does this) or have many flavours, making probability of the same twice low.

Strings and translation

2025-03-21T19:43:13Z

Zonkmachine: /* Working with strings */ Describe PiGUI's Format functions

==Internationalization==
Recommended reading: [https://dev.pioneerspacesim.net/contribute/translations Pioneer translators wikipage]

It is important that scripters are familiar with the translation system. In the previous example '''hello_world.lua''' used strings directly like <code>print("Hello, World!")</code>. In order for Pioneer to be translated we instead use tokens and calls on the <code>'Lang'</code> module to substitute it for the string in the chosen language. The translated strings are stored together with their 'key' in json format, one language per file that are kept in the [https://github.com/pioneerspacesim/pioneer/tree/master/data/lang data/lang/] directory. If the script file in which they are used is from the '''data/modules''' directory they have names starting with '''module-''' and ending with the name of the module written in one word, in small caps, and with the '.lua' ending omitted. The final translation from English to other languages is done on Pioneer's project page at [https://www.transifex.com/pioneer/pioneer/ Transifex], a dedicated online translation tool. The translations are committed to the pioneer/master branch on GitHub by a bot and are not to be edited manually apart from the '''en.json''' files.

==Translating strings==

Below is a minimal example with one string added into the translation system. It takes two files, one in '''data/modules''' and one in '''data/lang/module-hello'''. The print statement isn't wrapped in a function so it will be executed when the '''hello.lua''' is being parsed on startup. You will have to scroll through the command-line history to find it interleaved with the other output.

'''data/modules/hello.lua'''.
local Lang = require 'Lang'
local l = Lang.GetResource("module-hello")

print(l.HELLO)

And a corresponding file containing the translated string, and a description field shown to the translator, giving the context.

'''data/lang/module-hello/en.json'''
{
"HELLO": {
"description": "A classic message.",
"message": "Hello World!"
}
}

In short, any script containing strings that needs translation needs to load the <code>'Lang'</code> module:
local Lang = require 'Lang'
Then load the translation resource they want to use in their module, often just named <code>'l'</code> as in:
local l = Lang.GetResource("module-hello")
You may load more than one translation resource in your script but they will need to have unique names:
local lh = Lang.GetResource("module-hello")
local lg = Lang.GetResource("module-goodbye")

==Working with strings==

Recommended chapters from [https://www.lua.org/pil/contents.html Programming in Lua (first edition) ] 
[https://www.lua.org/pil/2.4.html 2.4 – Strings] 
[https://www.lua.org/pil/3.4.html 3.4 – Concatenation] 
[https://www.lua.org/pil/20.html 20 – The String Library] 
And from the [https://www.lua.org/manual/5.2/ Lua 5.2 Reference Manual] 
[https://www.lua.org/manual/5.2/manual.html#6.4 6.4 – String Manipulation] 

===Concatenation===

Instead of serving ready made sentences we can stitch them together with the Lua string concatenation operator <code>..</code>. The following codelines result in the same output.
print("Hello Clarice!")
print("Hello" .. " " .. "Clarice!")

This could be created by the more generic:

local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local NameGen = require 'NameGen'

local GREETING = 'Hello'
local FBIAGENT = NameGen.Surname()

local onShipDocked = function (ship)
if ship == Game.player then
Comms.Message(GREETING .. ' ' .. FBIAGENT .. '!')
end
end

Event.Register("onShipDocked", onShipDocked)

The <code>..</code> operator is used all over the codebase. Try a search for its occurrence. On Linux I would do <code>grep -R " \.\. " data/modules/ data/libs/ data/pigui/</code> and that will render a lot of output.

===Token concatenation===

You concatenate strings but you also concatenate the string tokens. In the example below from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/modules/DonateToCranks/DonateToCranks.lua#L14-L21 DonateToCranks.lua]''' we see the table <code>flavours</code> being populated by strings from '''[https://github.com/pioneerspacesim/pioneer/blob/b7a84a69803e17d9a47fbf9808fd012dfe1ac274/data/lang/module-donatetocranks/en.json data/lang/module-donatetocranks/en.lua]'''

local flavours = {}
for i = 0,9 do
table.insert(flavours, {
title = l["FLAVOUR_" .. i .. "_ADTITLE"],
desc = l["FLAVOUR_" .. i .. "_DESC"],
message = l["FLAVOUR_" .. i .. "_MESSAGE"],
})
end

The first string in the table is given the value of <code>l[FLAVOUR_" .. i .. "_ADTITLE]</code> is concatenated to <code>l[FLAVOUR_0_ADTITLE]</code> which corresponds to the first string in the language module which is seen below.

{
"FLAVOUR_0_ADTITLE": {
"description": "",
"message": "DONATE!"
},
"FLAVOUR_0_DESC": {
"description": "",
"message": "The Church of The Celestial Flying Spaghetti Monster needs YOUR money to spread the word of god."
},
"FLAVOUR_0_MESSAGE": {
"description": "",
"message": "Please select an amount to donate to the Church of the Celestial Flying Spaghetti Monster."
},
"FLAVOUR_1_ADTITLE": {
"description": "",
"message": "DONATE"
},

...

===Lua Standard Library - String manipulation===

I would start to search the '''data/''' register for ''' 'string' '''. to get a feeling for how it's used. Again on Linux i would use the 'grep' command. <code>grep -R "string\." data/</code>. You will see that the two most frequently used functions is <code>string.format()</code>, which is a part of the lua standard library, and <code>string.interp()</code>, which is a Pioneer global function residing in '''data/libs/autoload.lua''', and is described in the next paragraph about [https://wiki.pioneerspacesim.net/wiki/Strings_and_translation#String_variables String variables].

Some examples from the Lua standard library:
Comms.Message(string.lower('wHaT cAsE sHoULd I usE?'))

Maybe not the most easy function to fit into Pioneer, but it's there:
Comms.Message('Today is opposite day!')
Comms.Message(string.reverse('No, today is not opposite day!'))

A more complex example from '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/pigui/modules/hyperjump-planner.lua#L141 data/pigui/modules/hyperjump-planner.lua]''' 
Here <code>string.format("%.2f", distance)</code> is used to set the number of decimals in the jump to two. The rest is string variables that are not translated (names) and string concatenation. '''lc''' is used as the short name for the '''core''' translation resource. 
textLine = jumpIndex ..": ".. jump_sys.name .. " (" .. string.format("%.2f", distance) .. lc.UNIT_LY .. " - " .. fuel .. lc.UNIT_TONNES..")"

Here is what the final formatted text looks like (right side, two selected jump routes): 
[[File:hyperjumpplanner.png]]

===PiGUI - String formatting===

Pioneer has it's own set of formatting functions accessible through PiGUI, our UI. Some of it is realised on the C++ side and described in codedoc [https://codedoc.pioneerspacesim.net/#CClass:Format here]. Most of the functions, however, are strictly Lua and reside in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/libs/text.lua#L146-L385 data/pigui/libs/text.lua]. You access the functions with ''''require''''.

local Format = require 'Format'

Here is an example from the System overview. The table to the right is relying heavily on the Format functions.
[[File:Systemoverview.png]]

The code responsible for the table is here in [https://github.com/pioneerspacesim/pioneer/blob/5c7b2af87913a7106b69140966578c12e8c9180a/data/pigui/modules/system-view-ui.lua#L811-L840 data/pigui/modules/system-view-ui.lua] with an excerpt showed below. The examples take 1 or two arguments and the constant ending with 'or nil' is what makes the System overview omit values that don't apply to the selected system body.

{ name = lc.ESCAPE_VELOCITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Speed(body.escapeVelocity , true) or nil },
{ name = lc.MEAN_DENSITY, icon = icons.body_radius,
value = (not starport) and ui.Format.Mass(body.meanDensity).."/m³" or nil },
{ name = lc.ORBITAL_PERIOD, icon = icons.body_orbit_period,
value = op and op > 0 and ui.Format.Duration(op, 2) or nil },
{ name = lc.DAY_LENGTH, icon = icons.body_day_length,
value = rp > 0 and ui.Format.Duration(rp, 2) or nil },
{ name = luc.ORBIT_APOAPSIS, icon = icons.body_semi_major_axis,
value = (parent and not surface) and ui.Format.Distance(body.apoapsis) or nil },
{ name = luc.ORBIT_PERIAPSIS, icon = icons.body_semi_major_axis,
value = (parent and not surface) and ui.Format.Distance(body.periapsis) or nil },

==String variables==

When you want a string to present variable data such as numbers and names you use the <code>interp()</code> function. <code>interp()</code> accepts a table '{}' and the corresponding keys are then embedded in the translated strings enclosed by curly brackets '{}'.

Using ''''module-stationrefuelling'''' we can do:
print(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = 'JFK', fee = 50}))

Example from the actual StationRefuelling module:

'''data/modules/StationRefuelling/'''
Comms.Message(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = station.label,fee = Format.Money(fee)}))

'''data/lang/module-stationrefuelling/en.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Welcome to {station}. Your landing fee of {fee} has been deducted."
}

'''data/lang/module-stationrefuelling/it.json'''
"WELCOME_TO_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, ground station landing",
"message": "Benvenuti a {station}. Vi è stata dedotta una tassa di atterraggio di {fee}."
}

==Mission flavours==

A script can define a mission and then place many instances of it onto many bulletin boards. A script that introduces many instances in the game should provide some variety; it would harm immersion if, for examle, all delivery missions were worded identically. The easiest way to achieve multiple versions, or "flavours", is by just making a number of different strings and then choosing between them with a simple random function. This is how the [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L18:L48 deny] and [https://github.com/pioneerspacesim/pioneer/blob/da538b07538962a5473cf02e1da0d9b615698772/data/lang/module-deliverpackage/en.json#L282:L320 pirate taunt] messages are done in the DeliverPackage module.

'''data/modules/DeliverPackage/DeliverPackage.lua'''
local num_deny = 8

...

if not qualified then
local introtext = l["DENY_"..Engine.rand:Integer(1,num_deny)-1]
form:SetMessage(introtext)
return
end

'''data/lang/module-deliverpackage/en.json'''
"DENY_0": {
"description": "",
"message": "I'm sorry, but I don't think I can trust you with this delivery."
},
"DENY_1": {
"description": "",
"message": "Come back when you have some qualifications."

...

"DENY_7": {
"description": "",
"message": "I'm not willing to risk this delivery on someone without any qualifications like you."
You don't have to use a string variable that has been passed to the translation file. The pirate taunts, for example, have access to the clients name and the destination of the package but this information is only used in some of the strings.

"PIRATE_TAUNTS_7": {
"description": "",
"message": "That package isn't going to reach its destination today."
},
"PIRATE_TAUNTS_8": {
"description": "",
"message": "You're not getting to {location} today!"
Another way to add variation is to have a table of strings that are variations of a theme, a flavour. In the example below, again from the DeliverPackage module, you have two of the lines from '''FLAVOUR_0''' AND '''FLAVOUR_1''' compared.
"FLAVOUR_0_ADTEXT": {
"description": "",
"message": "GOING TO the {system} system? Money paid for delivery of a small package."
},
"FLAVOUR_0_FAILUREMSG": {
"description": "",
"message": "Unacceptable! You took forever over that delivery. I'm not willing to pay you."

...

"FLAVOUR_1_ADTEXT": {
"description": "",
"message": "WANTED. Delivery of a package to the {system} system."
},
"FLAVOUR_1_FAILUREMSG": {
"description": "",
"message": "I'm frustrated by the late delivery of my package, and I refuse to pay you."
There are ten flavours in DeliverPackage of five strings each, each forming a short story line. They are static in that you only see lines from within the same flavour. You know what lines will follow if you accept the mission and after a short time of playing you know this already from seeing the ad if delivering things is your forte. It's hard to share strings in between the flavours as they would need to be much more similar. It's a trade off. You could build a very complex interaction with the customers but in the end it needs to be translatable.

Generally, the more specific the text is, the stranger it will appear to see it multiple times in the game. For example, consider the following two examples:
- "Contract is to move X tonnes of Y to system Z"
- "My uncle's cat got sick, so I can't travel right now, so I need you to take my contract for me, to move X tonnes of Y to my home system Z"
The former might not need any flavours, as it's unpersonal, and very general. Seeing the second string multiple times does break immersion. Solution is to not show it often, either by making the mission rare / single occurance (no script to date does this) or have many flavours, making probability of the same twice low.

File:Systemoverview.png

2025-03-21T19:09:42Z

Zonkmachine:

Introduction to Mission Scripting

2025-03-21T16:22:48Z

Zonkmachine: Add link to online version of 'Programming in Lua'

Pioneer is extensible through the Lua scripting language. This document is intended to take the reader through the basics of coding up a mission for Pioneer, with working examples. The assumption is made that the reader is already aware of basic programming concepts, and in particular has some knowledge of the Lua programming language.

If you are not familiar with Lua, the [http://lua-users.org/wiki/LearningLua lua-users wiki: Learning Lua] page is a good place to start, or read [http://tylerneylon.com/a/learn-lua/ "learn lua in 15 minutes"]. Also the first edition of Programming in Lua by Roberto Ierusalimschy (the coder behind Lua) is available online [https://lua.org/pil/contents.html here].

==Pioneer's Lua environment==
Pioneer contains a full Lua interpreter. There are three instances of the interpreter; one for defining models, one for defining the galaxy, and one for writing mission scripts. This document is focused exclusively on the latter of the three.

When Pioneer is started, the universe is generated. After the universe is generated, Pioneer traverses the data/libs directory and all subdirectories, looking for files ending in the <code>.lua</code> extension. Each of these files is loaded into the interpreter and run. After these are run, Pioneer traverses the data/modules directory and does exactly the same thing. After this, the main menu is shown, and the player can begin a game.

The order in which the Lua scripts are loaded and run is not strictly defined, other than the fact that scripts in the '''data/libs''' directory will be executed before scripts in the '''data/modules''' directory.

Any globally defined functions or variables defined in those scripts will be available to any other scripts. We recommend that any functions or variables not explicitly intended for use by other scripts be declared with the <code>local</code> keyword, which will make them available only within the scope of the current file.

Chapters:
* [[Interacting with the game: Event-based programming]]
* [[Strings and translation]]
* [[Interacting with the player: BBS forms]]
* [[Missions and the mission list]]
* [[Missions and NPC Interaction]]
* [[Surviving a reload]]

Creating Ships and Stations

2025-02-14T15:34:49Z

Zonkmachine: /* Ship Properties */ typo

Before a ship or station can appear in the game, you have to specify its properties.

== Ship Properties ==

'''Note: this is somewhat obsolete now, since ship definitions are in json. The idea is the same, the syntax is a bit different. ''' Ship definitions live in data/ships. Each .lua file in this directory contains one ship definition. The file name (minus the .lua extension) is used as a unique identifier for the ship type (e.g., "wave"), so that code (e.g., mission scripts) can refer to a particular ship type. That identifier is case sensitive -- it is best to stick to the convention used for existing ships (all lower case, using underscores instead of spaces). The already existing kanara.lua is the police ship currently.

The easiest way to create a ship is to copy an existing ship definition and then edit it. The properties you can set (as of 20140411) are:

define_ship {
-- Name of the ship shown to the player (e.g., in the shipyard)
name = "",

-- Name of the model used for the ship (minus the ".model" extension. This is case sensitive)
model = "",

-- Manufacturer of the ship. Only for logo and decal selection currently.
-- Valid options are the file names (without extension) from data/icons/manufacturers/
manufacturer = "",

-- Ship class. Only for icon and text display in the ship market currently.
-- Valid options are the file names (without extension) from the data/icons/shipclass/
ship_class = "",

-- Linear thruster power in Newtons
forward_thrust = 65e5,
reverse_thrust = 12e5,
up_thrust = 18e5,
down_thrust = 18e5,
left_thrust = 18e5,
right_thrust = 18e5,

-- Angular thruster power
-- This currently uses non-standard units, but is proportional to Newton-metres
-- It is best to find the right value by experimenting in-game
angular_thrust = 25e5,

-- Table of gun mount positions
-- note: these values are deprecated fallback values, camera and gun positions are now specified as tag nodes in the model.
-- See the article on pioneer wiki about the model system
gun_mounts =
{
{ v(0,-2,-46), v(0,0,-1), 5, 'HORIZONTAL' },
{ v(0,0,0), v(0,0,1), 5, 'HORIZONTAL' },
},

-- Equipment limits
-- Each type of item or equipment has a particular slot that it can fit into;
-- equipment can only be fitted if the ship has the right slot available,
-- and also has enough capacity to carry the extra mass
-- For most types of equipment, the slot limit should be set to
-- 0 (to disable that equipment) or 1 (to enable it)
-- Some types of equipment could have limits greater than 1 (e.g., cabins, shields)

-- note: in the future, these slots will change, because a new Lua-driven equipment
-- system is being created (see [https://github.com/pioneerspacesim/pioneer/pull/1719 github issue 1719])

max_cargo = 100, -- usually the same as the 'capacity' value, can not be larger than capacity.
max_engine = 1, -- set to 0 to prevent fitting a hyperdrive
max_laser = 2, -- minimum: 0, maximum 2 currently.
max_missile = 4,
max_ecm = 1,
max_scanner = 1,
max_radarmapper = 1,
max_hypercloud = 1,
max_hullautorepair = 1,
max_energybooster = 1,
max_atmoshield = 1, -- if it's 0, then the ship can't be bought on surface starports, and NPC ships doesn't try to land on these ports either.
max_cabin = 2, -- number of passenger cabins
max_shield = 5,
max_fuelscoop = 1,
max_cargoscoop = 1,
max_lasercooler = 1,
max_cargolifesupport = 1,
max_autopilot = 1,

-- crew limits
-- note: in the future, the ship will not be able to launch with fewer than min_crew crew-members
min_crew = 1,
max_crew = 2,

-- total cargo and equipment capacity (in tonnes)
capacity = 15,
-- mass of the empty hull (in tonnes) - health of the ship is determined from this value
hull_mass = 10,
-- size of the propellant tank (in tonnes)
fuel_tank_mass = 15,

-- Exhaust velocity Vc [m/s] is equivalent of engine efficiency and depend on used technology.
-- Higher Vc means lower fuel consumption. Smaller ships built for speed often mount engines
-- with higher Vc. Another way to make faster ship is to increase fuel_tank_mass.
effective_exhaust_velocity = 59167e3,

-- base price of a ship with just a hyperdrive. If it's 0, then it won't show up in the ship market.
price = 70000,
-- base hyperdrive fitted as standard (set to 0 if the ship is not hyperspace capable). If it's 0, then it won't be seen flying around as an NC ship.
hyperdrive_class = 0,
}

== Station Properties ==

'''To be written...'''

Note: The way that docking bays work is currently being improved. See [https://github.com/pioneerspacesim/pioneer/pull/2058 github issue 2058]

Interacting with the game: Event-based programming

2025-02-12T18:30:25Z

Zonkmachine: /* Events */ Codedoc link to Event

File:Base2.png

2025-01-18T22:27:52Z

Zonkmachine:

File:Base1.png

2025-01-18T22:27:17Z

Zonkmachine:

User:Zonkmachine

2025-01-18T22:19:55Z

Zonkmachine: zonkmachine - WIP

Links to wiki test pages and other WIP stuff.

*[[Buildings_and_other_structures|Buildings and stuff]]

Surviving a reload
*[[Surviving_a_reload_WIP|Surviving a reload WIP]]

Scripting Tutorial TODO:
*[[Interacting_with_the_player:_BBS_forms|BBS forms]]
Update BBS images. ''fixed''.

Also mention that the posts are sorted. ''fixed''

Add some info on multiple BBS ads and updating the BBS over time, '''onUpdateBB'''.

Facegen - facemorph:
*[[Facemorph|Facemorph]]

Facegen - picture cleanup:
*[[Facegen_picture_cleanup|Facegen - picture cleanup]]

More facegen - hair:
*[[Facegen_hair|Facegen - more and hair]]

Code example for [[Missions_and_NPC_Interaction|Missions and NPC Interaction]]:
*[[Missions_and_NPC_Interaction_Code_Example|Missions and NPC Interaction Code Example]]

Snippets for new tutorial:
*[[Useful_functions|Useful functions]]

Dead links:
*[[Dead_links|Dead links]]
 
 
'''Sally. At night a stand up commedian in Cydonia. Daytime, selling parts her cousins strip from ships that does not belong to them:''' 
[[File:Passiveaggressive.png]]

Surviving a reload WIP

2025-01-18T07:07:40Z

Zonkmachine: Copy Surviving a reload at 15 January 2025‎

When a game is saved, a script is responsible for informing Pioneer exactly which of its data needs to be saved. If nothing is specified, nothing will be saved at all. Similarly, after a game is loaded, a script is responsible for restoring all of its saved data; re-creating bulletin board adverts, the player's mission details, and any run-time state.

Here is a simple form. If a new game is started, you will see this on every bulletin board that you visit:

local Event = require 'Event'

local onChat = function (form, ref, option)
form:Clear()
form:SetMessage("Hello!")
end

local onCreateBB = function (station)
station:AddAdvert('Click here for a greeting', onChat)
end

Event.Register("onCreateBB", onCreateBB)

However, if you save the game, then reload, you will not see it on any bulletin board that had been created in the current system before you saved. onCreateBB will be triggered for any subsequently created bulletin boards, but not for those that already existed. It isn't appropriate to have scripts create new adverts just because a player has loaded; instead, it's the responsibility of the script to tell Pioneer what to save, and to use those saved data to restore all adverts after the game is loaded. The same goes for player missions, and any working data that the script is using.

There are two things we need to do to achieve all of this:

* We need to track everything that the script is doing.
* We need to be able to pack this away for saving, and bring it back after loading.

==Tracking everything that we are doing==

Any local table that is declared in file scope is visible to the entire script, without affecting any other scripts. Essential data should be kept in such tables.

==Tracking adverts==
It's important to be able to re-create an advert, so part of the process of making one should be storing that information. Your script will need to make a note of in which station the advert was placed, which flavour was used (if you have flavours), the face data that was used on the form and any unique information that was used, such as specific mission details, reward, etc. The simplest way to keep all of this together is in a table, gathering up the variables by name into keys of the same name. It could look something like this:

local advert = {
station = station,
flavour = flavour, -- This will be a table
client = client, -- This will be a table (a character)
target = target,
destination = destination,
reward = reward,
}

In the case of the 'greeting', the first example above, we would just have to save the message ('Hello!'), Advert string ('Click here for a greeting') and the station. It's a very simple example but there are real modules that aren't much more complex than that.

Remember, the <code>AddAdvert()</code> method takes three arguments: The advert text, the <code>onChat</code> function and the <code>onDelete</code> function. It also returns a unique number, which lends itself nicely to storing the information away. That same unique number is passed to the onChat function, allowing onChat to check that stored information.

The <code>onDelete()</code> function (again, we call it that by convention only) also accepts this reference as its argument, and is called whenever an advert is destroyed, whether that destruction be explicit (<code>RemoveAdvert()</code>) or implicit (the player hyperspaces away).

So, we can track adverts that have been created, and stop tracking any that have gone away. We'll do that using the reference returned by <code>AddAdvert()</code> as the key to a file-scoped local table:

local flavours = {}
local ads = {}

local onChat = function (form, ref, option)
form:Clear()
form:SetFace(ads[ref].character)
form:SetMessage(ads[ref].flavour.title)
end

local onDelete = function (ref)
ads[ref] = nil
end

local onCreateBB = function (station)
local flavour = flavours[Engine.rand:Integer(1, #flavours)]
ref = station:AddAdvert(flavour.title, onChat, onDelete)
ads[ref] = {
station = station,
flavour = flavour,
character = Character.new()
}
end

Event.Register("onCreateBB", onCreateBB)

==Tracking missions==

This is less of a challenge. Missions created with <code>Mission.New()</code> are stored in the <code>PersistentCharacters.player.missions</code> table. You also need to register them locally in your script. When <code>Mission.New()</code> is called, it returns a reference to the mission. That reference can be stored in a file-local table that can be iterated through when we need to access a mission. We can wrap these functions up:

local missions = {}

local addMission = function(mission)
table.insert(missions,Mission.New(mission))
end

local removeMission = function(mref)
local ref
for i,v in pairs(missions) do
if v == mission then
ref = i
break
end
end
mission:Remove()
missions[ref] = nil
end

Now, instead of directly calling <code>Mission.Add()</code> and <code>mission:Remove()</code>, we call our local functions, <code>addMission()</code> and <code>removeMission()</code>. They will send their argument on to the instance in '''Mission.lua''', and also store or remove the mission ref in the missions table. There is now a record of which missions belong to this script. <code>addMission()</code> and <code>removeMission()</code> in the example above is taken from '''SearchRescue.lua'''. Look how <code>removeMission()</code> is used in the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/SearchRescue/SearchRescue.lua#L241-L252 Search and Rescue module]'''.

==Serializing: Packing away for saving and loading==

The <code>Serializer</code> object provides one method: <code>Register</code>. It takes three arguments. The first is a name; a simple string with which to uniquely identify this script. It's probably sensible to re-use the name that was used for the <code>Translate</code> object's flavour methods. The second argument is the name of a function which will return a single table. The third argument is a function that will accept a single table.

The second argument is your '''serializer''' function. The third is your '''unserializer''' function. By convention, we name these <code>serialize</code> and <code>unserialize</code>.

<code>serialize</code> must return a table. This table must contain everything that you need to store to get your script working after a reload. It will be run when the player saves the game. The table can contain any pure-lua types, and SystemPath, Body and SceneGraph.ModelSkin core types, anything else will explode, like a ShipDef/EquipDef or a StarSystem.

<code>unserialize</code> accepts a table, and does something with it. It will be run by the serializer after the game is loaded, immediately before the <code>onGameStart</code> event is triggered. It is passed the data that serialize returned at save time.

The most common way to deal with this is as follows (and this is very cut down):

local table_stuff_this_script_uses = {}
local loaded_data

-- The rest of the script goes here!

local onGameStart
if loaded_data then
for k,v in loaded_data.table_stuff_this_script_uses do
table_stuff_this_script_uses[k] = v
end
loaded_data = nil
else
-- New game; do other stuff here perhaps
end
end

local serialize = function ()
return {table_stuff_this_script_uses = table_stuff_this_script_uses}
end

local unserialize = function (data)
loaded_data = data
end

Event.Register("onGameStart", onGameStart)
Serializer:Register("TestModule", serialize, unserialize)

==Complete module==

Now we can finally start to put together complete modules that will save, reload, and behave consistently throughout the game. Many of the modules in Pioneer don't register a mission. As an example of this, see '''BreakdownServicing''', '''DonateToCranks''', and '''CrewContracts'''. In the same spirit, let's complete the first example above, 'Click here for a greeting', and make it survive a reload.

<pre>
local Event = require 'Event'
local Serializer = require 'Serializer'

local ads = {}

local onChat = function (form, ref, option)
local ad = ads[ref]
form:Clear()
form:SetMessage(ad.bodytext)
end

local onDelete = function (ref)
ads[ref] = nil
end

-- when we enter a system the BBS is created and this function is called
local onCreateBB = function (station)

local ad = {
headline = 'Click here for a greeting',
bodytext = "Hello!",
station = station
}

-- create one per BBS
local ref = station:AddAdvert({
description = ad.headline,
onChat = onChat,
onDelete = onDelete}
)
ads[ref] = ad
end

local loaded_data

local onGameStart = function ()
ads = {}

if not loaded_data or not loaded_data.ads then return end

for k,ad in pairs(loaded_data.ads or {}) do
local ref = ad.station:AddAdvert({
description = ad.headline,
onChat = onChat,
onDelete = onDelete})
ads[ref] = ad
end

loaded_data = nil
end

local serialize = function ()
return { ads = ads }
end

local unserialize = function (data)
loaded_data = data
end

Event.Register("onCreateBB", onCreateBB)
Event.Register("onGameStart", onGameStart)

Serializer:Register("message", serialize, unserialize)
</pre>

The '''Advice''' module generously gave up parts of its code to complete this script.

Although the example is functional, it has been coded with brevity alone in mind. I would not recommend using this as the basis for a mission without at least completely rewriting <code>onChat()</code>, and possibly tidying up the temporary loop variable names.

==Don't serialize strings==

When we add the strings literally to the ad as we did in the example above, they will be serialized and saved on game end. Considering this is happening on all active stations, this will waste disk space.

local ad = {
headline = 'Click here for a greeting',
bodytext = 'Hello!',
station = station
}

What we want to do instead is save the information to recreate the same strings. If for instance we have a set of flavours that are selected with a random number, then generate that number and save it in a variable. The ad example above can then be rewritten as such. We only need the station and the flavour number to recreate the ad.

local ad = {
station = station,
n = n
}

The working example in the paragraph above can be updated in this way. When you have the translated strings in a separate module you would start the script by pulling in the strings to the script in an array or set of arrays. In the following example we instead add the strings to an array directly but it shows the general idea.

<pre>
local Engine = require 'Engine'
local Event = require 'Event'
local Game = require 'Game'
local Rand = require 'Rand'
local Serializer = require 'Serializer'

local ads = {}

local flavours = {
{flavour = 'flavour 1', title = 'title 1', text = 'text 1'},
{flavour = 'flavour 2', title = 'title 2', text = 'text 2'},
{flavour = 'flavour 3', title = 'title 3', text = 'text 3'}
}
local onChat = function (form, ref, option)
local ad = ads[ref]
form:Clear()
form:SetMessage(flavours[ad.n].text)
end

local onDelete = function (ref)
ads[ref] = nil
end

-- when we enter a system the BBS is created and this function is called
local onCreateBB = function (station)

local rand = Rand.New(Game.time)
local n = rand:Integer(1, #flavours)

local ad = {
station = station,
n = n
}

-- create one per BBS
local ref = station:AddAdvert({
title = flavours[n].title,
description = flavours[n].flavour,
onChat = onChat,
onDelete = onDelete}
)
ads[ref] = ad
end

local loaded_data

local onGameStart = function ()
ads = {}

if not loaded_data or not loaded_data.ads then return end

for k,ad in pairs(loaded_data.ads or {}) do
local ref = ad.station:AddAdvert({
title = flavours[ad.n].title,
description = flavours[ad.n].flavour,
onChat = onChat,
onDelete = onDelete})
ads[ref] = ad
end

loaded_data = nil
end

local serialize = function ()
return { ads = ads }
end

local unserialize = function (data)
loaded_data = data
end

Event.Register("onCreateBB", onCreateBB)
Event.Register("onGameStart", onGameStart)

Serializer:Register("message", serialize, unserialize)
</pre>

The codedoc is complete and accurate, and the scripts provided with Pioneer are good examples themselves. The API is extensive, but if you find that there are additional things you would like to be able to do, or information you would like from Pioneer, the dev team are willing to extend the API to accommodate script writers. Simply create a new issue on the [https://github.com/pioneerspacesim/pioneer/issues Github issue tracker].

Help is also always available on the [https://forum.pioneerspacesim.net/ Pioneer dev forum], and many of the dev team can be found on [[IRC]] at all hours.

User:Zonkmachine

2025-01-18T07:05:51Z

Zonkmachine: WIP - Surviving a reload

Links to wiki test pages. WIP stuff.

Surviving a reload
*[[Surviving_a_reload_WIP|Surviving a reload WIP]]

Scripting Tutorial TODO:
*[[Interacting_with_the_player:_BBS_forms|BBS forms]]
Update BBS images. ''fixed''.

Also mention that the posts are sorted. ''fixed''

Add some info on multiple BBS ads and updating the BBS over time, '''onUpdateBB'''.

Facegen - facemorph:
*[[Facemorph|Facemorph]]

Facegen - picture cleanup:
*[[Facegen_picture_cleanup|Facegen - picture cleanup]]

More facegen - hair:
*[[Facegen_hair|Facegen - more and hair]]

Code example for [[Missions_and_NPC_Interaction|Missions and NPC Interaction]]:
*[[Missions_and_NPC_Interaction_Code_Example|Missions and NPC Interaction Code Example]]

Snippets for new tutorial:
*[[Useful_functions|Useful functions]]

Dead links:
*[[Dead_links|Dead links]]
 
 
'''Sally. At night a stand up commedian in Cydonia. Daytime, selling parts her cousins strip from ships that does not belong to them:''' 
[[File:Passiveaggressive.png]]

Missions and the mission list

2025-01-16T06:47:50Z

Zonkmachine: /* Mission description */ Fixup

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

I don't recommend using <code>Game.player.frameBody.path</code> here. I'm only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission type you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.
local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function (ship, station)
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

Event.Register("onGameStart", onGameStart)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Taxi', l.TAXI)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Taxi', l.TAXI, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

Let's fixup the earlier example with it's own mission type and a working '''buildMissionDescription'''.

local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function ()
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

Mission.RegisterType('Test', 'Test', buildMissionDescription)
Event.Register("onGameStart", onGameStart)

[[File:Minimaldescription.png|1024px]]

That's basically it. Here follows a description of the elements you can add to '''buildMissionDescription'''. Try and expand our latest script on you own.

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.

Missions and the mission list

2025-01-16T06:40:19Z

Zonkmachine: No longer outdated

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

I don't recommend using <code>Game.player.frameBody.path</code> here. I'm only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission type you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.
local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function (ship, station)
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

Event.Register("onGameStart", onGameStart)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Taxi', l.TAXI)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Taxi', l.TAXI, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

[[File:Minimaldescription.png|1024px]]

Let's fixup the earlier example with it's own mission type and a working '''buildMissionDescription'''.

local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function ()
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

Mission.RegisterType('Test', 'Test', buildMissionDescription)
Event.Register("onGameStart", onGameStart)

That's basically it. Here follows a description of the elements you can add to '''buildMissionDescription'''. Try and expand our latest script on you own.

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.

Missions and the mission list

2025-01-16T06:38:28Z

Zonkmachine: /* Mission description */ Completed example

{{outdated}}

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

I don't recommend using <code>Game.player.frameBody.path</code> here. I'm only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission type you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.
local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function (ship, station)
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

Event.Register("onGameStart", onGameStart)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Taxi', l.TAXI)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Taxi', l.TAXI, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

[[File:Minimaldescription.png|1024px]]

Let's fixup the earlier example with it's own mission type and a working '''buildMissionDescription'''.

local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function ()
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Test",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

Mission.RegisterType('Test', 'Test', buildMissionDescription)
Event.Register("onGameStart", onGameStart)

That's basically it. Here follows a description of the elements you can add to '''buildMissionDescription'''. Try and expand our latest script on you own.

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.

Missions and the mission list

2025-01-16T06:28:57Z

Zonkmachine: /* Registering a mission type */ Fixup example

{{outdated}}

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

I don't recommend using <code>Game.player.frameBody.path</code> here. I'm only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission type you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.
local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onGameStart = function (ship, station)
Timer:CallAt(Game.time + 2, function ()

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time+15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end)
end

Event.Register("onGameStart", onGameStart)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Taxi', l.TAXI)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Taxi', l.TAXI, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

[[File:Minimaldescription.png|1024px]]

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.

Missions and the mission list

2025-01-16T05:54:03Z

Zonkmachine: /* Registering a mission type */ fixup - escape apostrophe

{{outdated}}

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

I don't recommend using <code>Game.player.frameBody.path</code> here. I'm only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission type you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.

local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onShipDocked = function (ship, station)
if ship:IsPlayer() then

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time + 15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end

Event.Register("onShipDocked", onShipDocked)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Taxi', l.TAXI)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Taxi', l.TAXI, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

[[File:Minimaldescription.png|1024px]]

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.

Missions and the mission list

2025-01-16T05:41:53Z

Zonkmachine: /* Mission description */ Fixup - Taxi example

{{outdated}}

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

I don't recommend using <code>Game.player.frameBody.path</code> here. I'm only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission type you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.

local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onShipDocked = function (ship, station)
if ship:IsPlayer() then

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time + 15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I'm at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end

Event.Register("onShipDocked", onShipDocked)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Taxi', l.TAXI)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Taxi', l.TAXI, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

[[File:Minimaldescription.png|1024px]]

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.

Missions and the mission list

2025-01-16T05:39:01Z

Zonkmachine: /* Mission description */ Minimal buildMissionDescription fixup

{{outdated}}

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

I don't recommend using <code>Game.player.frameBody.path</code> here. I'm only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission type you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.

local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onShipDocked = function (ship, station)
if ship:IsPlayer() then

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time + 15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I'm at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end

Event.Register("onShipDocked", onShipDocked)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Delivery', l.DELIVERY)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

[[File:Minimaldescription.png|1024px]]

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.

Missions and the mission list

2025-01-16T05:34:22Z

Zonkmachine: /* Mission description */ Fix link

{{outdated}}

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

I don't recommend using <code>Game.player.frameBody.path</code> here. I'm only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission type you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.

local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onShipDocked = function (ship, station)
if ship:IsPlayer() then

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time + 15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I'm at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end

Event.Register("onShipDocked", onShipDocked)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Delivery', l.DELIVERY)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will launch a minimal info window with just the basics. A title, The customer image, and a '''Go back''' button.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

[[File:Minimaldescription.png|1024px]]

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.

Missions and the mission list

2025-01-16T05:32:24Z

Zonkmachine: /* Mission description */ Fixup

{{outdated}}

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].

Create a new mission and add it to the player’s mission list while retrieving the reference number:

ref = Mission.New({
'type' = 'Delivery', -- Must be a translatable token!
'client' = Character.New(),
'due' = Game.time + 3*24*60*60, -- three days
'reward' = 123.45,
'location' = SystemPath:New(0,0,0,0,16), -- Mars High, Sol
'status' = 'ACTIVE',
})

In practice, it might look more like this:

local Character = require 'Character'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'

local missions = {}

local onShipDocked = function (ship)
if ship:IsPlayer() then

table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end
end

Event.Register("onShipDocked", onShipDocked)

I don't recommend using <code>Game.player.frameBody.path</code> here. I'm only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.

This creates a mission visible on the mission screen:

[[File:Missionlist3.png|1024px]]

==Registering a mission type==
Before a module can create missions that are visible in the player's mission list, it needs to register a mission type. It's a painless task.

'''[https://codedoc.pioneerspacesim.net/#LuaClass:Mission:RegisterType LuaClass:Mission:RegisterType]'''

Mission.RegisterType(typeid, display, onClick)

Apart from a unique string and a translatable mission name, you have the option to pass a function that takes care of the mission info presented when you press the '''More info...''' button in the missions list. By convention, this function is named '''buildMissionDescription'''. This would typically happen at the very end of the module. Here is what it looks like at the end of [https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L513 '''DeliverPackage.lua''']

Event.Register("onGameEnd", onGameEnd)
Event.Register("onReputationChanged", onReputationChanged)

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

Serializer:Register("DeliverPackage", serialize, unserialize)

The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission type you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

Timer:CallAt(Game.time + 2, function ()
...
end)

Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.

local Character = require 'Character'
local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local Mission = require 'Mission'
local Player = require 'Player'
local Timer = require 'Timer'

local missions = {}

local onShipDocked = function (ship, station)
if ship:IsPlayer() then

-- On docking, starting a new game, we create
-- two npc's and book them on a taxi mission.
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 10, -- ten seconds
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
table.insert(missions, Mission.New({
type = "Taxi",
client = Character.New(),
due = Game.time + 20, -- 20 seconds
reward = 5000,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))
end

-- Magically, without moving, we've arrived at the destination
-- after 15 seconds and check in with our passengers.
Timer:CallAt(Game.time + 15, function () -- 15 seconds timer
for ref,mission in pairs(missions) do
if Game.time > mission.due then
mission.status = 'FAILED'
Comms.ImportantMessage('We are five seconds late and I'm at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
else
Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
mission.status = "COMPLETED"
Game.player:AddMoney(mission.reward)
end
mission:Remove()
missions[ref] = nil
end
end)
end

Event.Register("onShipDocked", onShipDocked)

Missions Created:

[[File:Missionlist1.png]]

1 Mission failed and 1 mission completed:

[[File:Missionlist2.png]]

More info? If you look to the right on the mission list there is a button named '''More info...''' which will let you see more specific details of your mission. This will need to be specified in the mission script itself so if you press this button in the example above Pioneer will crash. The common name for the function you need to write in your script is '''buildMissionDescription'''. Here is what it looks like in '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L462-L490 DeliverPackage.lua]'''.

==Mission description==
If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.

Mission.RegisterType('Delivery', l.DELIVERY)

You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will launch a minimal info window with just the basics. A title, The customer image, and a '''Go back''' button.

local buildMissionDescription = function (mission)
end

Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)

The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L49-L76 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = ""
desc.client = mission.client
desc.details = {false}

return desc;
end

[[File:Minimaldescription.png|1024px]]

===desc.description===
This is a string and will typically be based on the conversation from onChat.

desc.description = "String to be shown on top of the mission description goes in here!"

===desc.client===
Takes a character as it's input and usually this means the character passed via the mission argument.

desc.client = mission.client

===desc.details===
This is a table that is passed to '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/libs/text-table.lua#L15-L28 textTable.draw()]''' in '''data/pigui/libs/text-table.lua'''.

desc.details = {
{"data here", "more data"},
...
}

====string====
A string will be presented in the form of a header with a delimiter underneath.
"Just a string",

====table====
A table that takes strings and data/numbers in a key/value sort of way. Only one post in the table will cause a crash and any number of entries above the first two will be discarded.

{"Left","Right"},
{"Data", 42},
--{"This entry would cause a crash"},
{"No crash", ""} -- Two entries in the table with one being just an empty string works.
}

====spacing====
The key word '''false''' can be used to insert some padding.

false,

===desc.location===
Add a button to set the mission location as navigation target.

From the CargoRun module:
desc.location = mission.location

===desc.returnLocation===
Add a button to set the return location as navigation target.

From the CargoRun module:
desc.returnLocation = mission.domicile

===Example===
local buildMissionDescription = function (mission)
local ui = require 'pigui'
local desc = {}

desc.description = "String to be shown on top of the mission description goes in here!"

desc.details = {
"This will be a 'title' with a delimiter underneath",
{"Left","Right"},
{"Data", 42},
false, -- some space.
-- {"This entry would cause a crash"},
{"No crash", ""}
}

desc.client = mission.client

return desc;
end

[[File:Moremissiondetails.png|1024px]]

==Maintaining immersion==

Fictionally, of course, the bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.