Interacting with the player: BBS forms

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 SpaceStation 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 onCreateBB event is triggered, and passes the SpaceStation 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.

Internationalization

It is important that scripters are familiar with the Translations library (scroll down to "Lua module translation"). A list of Translate:Add() calls are usually placed in a file named Languages.lua and kept in the same subdirectory as the script that needs them.

This is by convention only; all translations, regardless of filename, are available to all scripts, and it would technically be perfectly possible to recycle the translated strings provided by another script. In order to keep the workload as simple as possible for translators, however, we do prefer the convention to be followed.

The script itself makes use of translated strings by getting the translator function and using it to translate strings by token. So, if the Languages.lua file contained this:

Translate:Add({
    English = {
        ['Please, help me!'] = 'Please, help me!',
    },
    Deutsch = {
        ['Please, help me!'] = 'Bitte, hilf mir!',
    },
})

then in the main script, you would first get the translator function:

local t = Translate:GetTranslator()

where t could be any other convenient name, in the event that you already have a variable named t. Once you have your translator, you can simply use it to translate by giving it the key:

Comms.ImportantMessage(t('Please, help me!'))

This would put "Please, help me!" on the screens of English players, and "Bitter, hilf mir!" on the screens of German players.

The translator is fully documented in the codedoc. For the remainder of the document, I shall be using string literals. This is for clarity only; all custom scripts should be fully translatable if they are intended to be included with the game.

The BBS advert

Adverts are placed onto a BBS by calling the station's AddAdvert() 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. onCreateBB is the obvious one; there is also onUpdateBB, 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 AddAdvert() 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.

AddAdvert() returns a reference number, which can subsequently be used to remove the advert using RemoveAdvert().

It's the job of the scripter to decide how many, if any, adverts to add to a bulletin board when onCreateBB is triggered, and whether to add or remove any when onUpdateBB 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 boad 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. The advert is only added if the station is in space. There is no mission here; I am simply illustrating the mechanics of adding the advert.

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)
    end
 
    if station.type == 'STARPORT_ORBITAL' then
        station:AddAdvert('Need the name of this station?',sendStationName)
    end
end

Event.Register("onCreateBB", onCreateBB)

This code will create an advert:

Looking at the image, you will notice that my advert has appeared at a completely arbitrary location on the bulletin board. There is no way to specify the location, and no way to determine it.

Clicking on the advert causes this to happen:

Even though the only thing our function did was to send a message to the console (visible at the bottom), you can see that Pioneer automatically created a form for our advert. The only control is the "Go back" button, and the name and face are defaulted to that which was displayed on the main bulletin board.

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 zero or more clickable options.

The form itself is passed to the function specified in the SpaceStation.AddAdvert() method. In the example above, that function would be sendStationName(), 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. SetTitle() and SetMessage() each accept a string. SetFace() takes a table of information which defines the photofit face on the left. AddOption() adds clickable options with buttons. Clear() removes the Message and Options, but preserves the Title and Face, while Close() acts the same way as the "Go back" button.

The following example doesn't have any clickable options, but does have a customized form:

local populateForm = function (form)
    local facedata = {
        name = "Bob",
        female = true,
        title = "Lorry driver",
    }

    form:SetTitle('This appears above the face picture')
    form:SetFace(facedata)
    form:SetMessage([[This is the main message.

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

local onCreateBB = function (station)
    station:AddAdvert('This appears in the advert list',populateForm)
end

Event.Register("onCreateBB", onCreateBB)

As before, an advert was created:

Randomly, it has appeared at the top of the list.

Clicking on the advert causes this to happen:

Now we can see that populateForm was called, and it successfully filled the form with content. All of the face options were optional; if they aren't provided, Pioneer will choose random values. I have left out a couple of options here; it's wise to specify them all, because after a saved game is loaded, it's the script's job to make sure that the same face appears (see "Surviving a reload").

Adding options to the form

In the example above, I created a function named populateForm() 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 populateForm() 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 onChat(), which is how it shall be named from now on.

The previous example did not store or use the value returned by AddAdvert(). It is this value which is sent as the second parameter; very useful if your script adds several adverts, each of which might have slightly differently worded content.

When the advert was clicked in the main bulletin board list, it was passed the value 0 as the option.

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 onChat(), which will receive the form object, the advert reference and the number that was specified after the caption in AddOption().

The codedoc has a brilliant example of a complete onChat, which I will reproduce here:

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("Yellow",    3)
        form:AddOption("Blue",      4)
        form:AddOption("Hang up.", -1)

        return
    end

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

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

    -- option 3 - yellow
    if option == 3 then
        form:SetMessage("Ahh yellow, the colour of the sun.")
        form:AddOption("Hang up.", -1)
        return
    end

    -- option 4 - blue
    if option == 4 then
        form:SetMessage("Ahh blue, the colour of the ocean.")
        form:AddOption("Hang up.", -1)
        return
    end

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

Here, every time onChat() 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 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("Yellow",    3)
            form:AddOption("Blue",      4)
            form:AddOption("Hang up.", -1)
        end,
        [1] = function ()
            form:SetMessage("Ahh red, the colour of raspberries.")
            form:AddOption("Hang up.", -1)
        end,
        [2] = function ()
            form:SetMessage("Ahh green, the colour of trees.")
            form:AddOption("Hang up.", -1)
        end,
        [3] = function ()
            form:SetMessage("Ahh yellow, the colour of the sun.")
            form:AddOption("Hang up.", -1)
        end,
        [4] = function ()
            form:SetMessage("Ahh blue, the colour of the ocean.")
            form:AddOption("Hang up.", -1)
        end,
        [-1] = function ()
            form:Close()
        end
    }
    options[option]()
end

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 Player object, which can always be found at Game.player, and which inherits from Ship and Body. Missions are added to the screen using the AddMission() 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. So, it usually looks a little like ref = Game.player:AddMission(table_of_info).

In practice, it might look more like this:

local mission_storage={}

table.insert(mission_storage,Game.player:AddMission({
    type = "Fetch beer",
    client = "Bert Beerbreath",
    due = Game.time + 600, -- ten minutes' time
    reward = 10,
    location = Game.player.frameBody.path, -- here, basically
    status = 'ACTIVE'
}))

table.insert(mission_storage,Game.player:AddMission({
    type = "Fetch curry",
    client = "Curt Curryface",
    due = Game.time + 900, -- fifteen minutes' time
    reward = 5,
    location = Game.player.frameBody.path,
    status = 'ACTIVE'
}))

I don't recommend using Game.player.frameBody.path 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.

This creates visible missions on the mission screen:

These missions will remain exactly like that forever, unless a script explicitly makes changes. There is no automatic logic, and no automatic removal. Your script must keep track of them. In this example, I have the references in the mission_storage table.

The UpdateMission() method allows a script to alter any detail. The status can be 'ACTIVE','FAILED' or 'COMPLETED'. I'm going to change the status of the first mission to 'COMPLETED'.

Game.player:UpdateMission(mission_storage[1],{status='COMPLETED'})

The updated information can be a partial table. The unspecified members will remain unchanged:

The GetMission() method allows a script to read data from a mission, if the script has the reference. It returns a table with that information. Here, I'm going to add ten minutes to the deadline of the second mission:

local due_date = Game.player:GetMission(mission_storage[2]).due
Game.player:UpdateMission(mission_storage[2],{due = due_date + 600})

The result:

The RemoveMission() method allows a script to remove a mission. Here I remove the completed one:

Game.player:RemoveMission(mission_storage[1])
table.remove(mission_storage,1)

And here it isn't:

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 should provide some variety; it would harm immersion if all delivery missions were worded identically, for example.

To introduce variety, we can use tables, which contain all of the lines needed for bulletin board forms, messages and so forth. It's then a simple matter to use a similar, but differently worded, table to make the same misison appear different. A flavour might look like this:

{
    title = "Shill bidder wanted for auction",
    greeting = "Hi there. Want to earn some quick cash?",
    yesplease = "Sure. What do you need me to do?",
    nothanks = "No, ta - this looks a bit shady.",
}

An alternative flavour might look like this:

{
     title = "Help me win an auction.",
     greeting = "Hello. I'll pay you to place fake bids for me. Interested?",
     yesplease = "Yes, I like to live dangerously.",
     nothanks = "No thanks; I'd rather not get arrested for fraud.",
}

Ideally, we just need a table with as many of these as we can be bothered to write, then select one at random.

There are issues with translation, though. Because flavours are often full of colloquial language, and can feature several ways of saying basically the same thing, translating them all word-for-word is not necessarily productive. To this end, the Translate system features a pair of methods which can ease the handling of flavours, especially in different languages.

The Translate:AddFlavour() method allows a flavour to be added, and marked as being of a specific language. By convention, these statements would appear in the script's Languages.lua file so that translators could see them and be inspired to write some in other languages. The method takes three arguments. The first is the language of the flavour, as a string. The second is a name, so that the Translate class can give flavours back to the correct script. The third is the flavour table itself. If my script was named TestModule, I might define the two flavours above in my Languages.lua as follows:

Translate:AddFlavour('English','TestModule',{
     title = "Shill bidder wanted for auction",
     greeting = "Hi there. Want to earn some quick cash?",
     yesplease = "Sure. What do you need me to do?",
     nothanks = "No, ta - this looks a bit shady.",
})

Translate:AddFlavour('English','TestModule',{
     title = "Help me win an auction.",
     greeting = "Hello. I'll pay you to place fake bids for me. Interested?",
     yesplease = "Yes, I like to live dangerously.",
     nothanks = "No thanks; I'd rather not get arrested for fraud.",
})

As an added benefit, Translate:AddFlavour() checks all flavour tables for uniformity. It does this by comparing all of the table's keys with that of the first English flavour that was specified; a technical consequence of this is that an English flavour needs to come first in your Languages.lua file, otherwise Pioneer will give you an error.

To fetch the flavours into your script, use Translate.GetFlavours(). It takes a single argument, which is the module name that was specified in AddFlavour()'s second parameter. It doesn't matter to Translate how many flavours there are in each language, or whether it's an equal number. If my current language is not English, and there are no flavours in that language, English flavours will be used instead. If there is only one flavour in my language, I will only see that one variety.

The following example will select a random flavour from my flavour tables.

local all_flavours = Translate:GetFlavours('TestModule')
local flavour = all_flavours[Engine.rand:Integer(1,#all_flavours)]

GetFlavours() returns a table of flavours. The second line of code generates a random number between 1 and the number of flavours in that table, and returns that flavour from the table. After this, flavour.title will either be "Shill bidder wanted for auction" or "Help me win an auction.". Adding more flavours means more variety.

Maintaining immersion

Fictionally, of course, this 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.