Bulletin Board System

Overview

This OXP adds a bulletin board to most stations in Oolite, from which missions (added by other OXP's) can be viewed and accepted. This OXP doesn't include any missions itself - it is a framework that other OXP's can utilise to make the process of adding missions easier.

Player Usage

The Bulletin Board is accessed through the Interfaces screen (F4), and it's normally found under "Station Interfaces". If there are no missions available, and you don't have any active missions, the interface won't be listed. When there are missions available, or you have active missions, the number of these will be displayed on the interface entry. eg "Station bulletin board (4 available, 2 active)".

When the interface is opened, any active missions will be grouped at the top of the list. Active missions are marked with a "•" and also have a value in the "%" (percentage completed) column. All other entries in the list are available missions.

When a mission is selected from the list, details of the mission will be displayed. These details include:

Description	The short description of this mission.
Details	Full details of the mission parameters.
Destination system	Where the mission needs to be completed at.
Mission expires in	How much time you have to complete the mission.
Payment on completion	How much you will be paid when the mission is completed.
Penalty	How much you will be charged if you fail to complete the mission. This value will be scaled by how much of the mission you completed.

If you have accepted a mission you will also see:

Percent complete

How much of the mission has been completed so far.

At the bottom of the screen will be the following options:

Accept mission	This will signal that you are starting this mission.
Show destination	This will display a chart (either a short range or long range, depending on the distance to the destination), allowing the player to see where the destination is.

Once you have accepted a mission, you will see the following options:

Terminate mission	This will signal that you are giving up on this mission. If the mission has a penalty, it will be applied now. The mission will be removed from the list.
Complete mission	This will only be available once the percent complete reaches 100%. This option will give you your payment and remove the mission from the list.

Active missions are shown on the F5F5 Manifest screen, under the "Bulletin Board Missions" heading. Depending on the mission, you will likely see how much of the mission you have yet to complete, and how much time is remaining before the mission expires.

Some missions will automatically complete as soon as you reach 100%, some will complete the next time you dock. It's important to check back on the Bulletin Board to see if you need to "Complete" the mission yourself.

Technical Details

The purpose of the Bulletin Board system is to create a simple yet flexible interface which OXP authors can use to offer custom missions to the player. Missions added to the list are intended to be only available in the current system. Active missions are stored by the system and saved in the save game file, but the list of available missions will be cleared out with each hyperspace jump.

To add a new mission to the Bulletin Board, you need to run the "$addBBMission" function and pass an object with the following parameters:

 var bb = worldScripts.BulletinBoardSystem;
 if (bb) {
   var myID = bb.$addBBMission({
     description:"My first mission",
     source:7,
     destination:129,
     stationKey:"galcop",
     details:"This is my first sample mission available on the Bulletin board.",
     manifestText:"My mission is active!",
     expiry:clock.seconds + 86400,
     payment:1000,
     penalty:100,
     accepted:false,
     allowTerminate:true,
     percentComplete:0,
     completionType:"AT_SOURCE",
     markerShape:"MARKER_PLUS",
     markerColor:"cyanColor",
     markerScale:1.0,
     model:"police",
     spinModel:true,
     initiateCallback:"$myMissionInitiate",
     completedCallback:"$myMissionComplete",
     confirmCompleteCallback:"$myMissionConfirmComplete",
     terminateCallback:"$myMissionTerminate",
     failedCallback:"$myMissionFailed",
     manifestCallback:"$myMissionUpdateManifest",
     worldScript:"MyFirstMission"
   });
 }

In detail these parameters are:

description	(required) This is the description of the mission shown in the Bulletin board list
source	(optional) The system ID of the source of this mission. If not included it will default to the current system's ID.
destination	(required) This is the system ID of the destination system where the mission will be carried out. This can be the current system, if the mission is local.
stationKey	(optional) The stationKey helps to limit which stations the mission will be offered in. See the section below title "Station Keys" for more details. If omitted this will default to "" (blank), meaning this mission will be available from all stations in this system
details	This is the full details of the mission parameters.
manifestText	(optional) This is the text to display on the F5F5 manifest screen when the mission has been accepted. See also "manifestCallback" below.
expiry	(required) The time is clock seconds when the mission must be completed by.
payment	(required) The number of credits the player will be given when they complete the mission.
penalty	(optional) The number of credits the player will be charged if they fail to complete the mission, scaled by the percentage completed.
accepted	(optional) True/false value indicating whether this mission will be added to the list as already accepted by the player. Under normal circumstances this item can be left out. However, if you want to link missions together, so completing one mission automatically starts a second mission, you may want to add the mission to the list as "accepted:true" so the player doesn't have to go to the Bulletin Board and manually accept the second mission. The default is false.
allowTerminate	(optional) True/false value indicating whether the "Terminate mission" will be available to the player after accepting the mission. The default is true.
percentComplete	(optional) A decimal value between 0 and 1. Allows you to create missions that already have some part completed.
completionType	(optional) A text value indicating what should happen when the player completes the mission (ie the percentComplete value reached 1, or 100%). Can be one of these: AT_SOURCE Player must return to the source system/station, open the mission and select "Complete mission". AT_STATION Player can return to any system, dock at any station with the same stationKey, open the mission and select "Complete mission". ANYWHERE Player can return to any system, dock at any station, open the mission and select "Complete mission". IMMEDIATE Player is rewarded immediately when the mission is flagged as 100% complete - player won't need to dock anywhere. WHEN_DOCKED_SOURCE Player is automatically rewarded as soon as they next dock at the source system/station. Notice will appear in arrival report. WHEN_DOCKED_STATION Player is automatically rewarded as soon as they next dock at any station, any system, but with the same station key. Notice will appear in arrival report. WHEN_DOCKED_ANYWHERE Player is automatically rewarded as soon as they next dock at any station, any system. Notice will appear in arrival report. The default is "AT_SOURCE".
arrivalReportText	(optional) When the completionType is set to "WHEN_DOCKED_*" this text will be displayed on the arrival report when the player completes the mission. If omitted, will default to "'<description>' mission complete. You have been awarded <payment>."
model	(optional) Role of a ship to use as the background on the mission details screen.
modelPersonality	(optional) The entityPersonality assigned to the ship model.
spinModel	(optional) True/false value indicating whether the ship model will rotate or not. The default to true.
background	(optional) Name of a picture to use as the background for the mission details screen.
backgroundHeight	(optional) Allows a height value to be specified for the background image.
overlay	(optional) Name of a picture to use as an overlay on the mission details screen. Will default to the bulletin board graphic when not set.
overlayHeight	(optional) Allows a height value to be specified for the overlay image.
markerShape	(optional) Allows the shape of the galactic chart marker to be overridden. Default is "MARKER_PLUS". Possible values are: NONE No galactic chart marker will be added. MARKER_X Uses an "X" to mark the system. MARKER_PLUS Uses a "+" to mark the system. MARKER_SQUARE Uses a square shape to mark the system. MARKER_DIAMOND Uses a diamond shape to mark the system.
markerColor	(optional) Allows the color of the galactic chart marker to be overridden. Default is "redColor".
markerScale	(optional) Allows the scale setting of the galactic chart marker to be overridden. Value between 0.5 and 2.0. Default is 1.0.
initiateCallback	(required) The function name to call back when the mission is accepted by the player.
completedCallback	(required) The function name to call back when the mission is completed by the player, based on the completionType setting.
confirmCompleteCallback	(optional) A function name to call to confirm the mission has been completed. Useful if there are secondary steps that must have been completed by the player. For instance, you might want to check that the player has a particular amount of a certain commodity in their hold. Expects a string return value of blank (meaning mission is completed) or [string explaining why mission cannot be completed] (meaning the mission is not complete).
terminateCallback	(required) The function name to call back when the mission is terminated/cancelled by the player.
failedCallback	(optional) The function name to call back when the player fails to complete the mission in the alloted time. Called during the "shipWillDockWithStation" event.
manifestCallback	(optional) The function name to call back when the manifest entry for the mission requires updating.
worldScript	(required) The name of the worldScript where these functions reside.

This call will return a unique ID (integer) value that can be stored and used to reference this mission in other bulletin board functions.

Once a mission has been added, it is up to the calling script to work out and track the criteria required to complete a mission. The BB system will handle the display of information, and will pay or charge the player if they complete or fail the mission. But the rules which govern the mission criteria are controlled solely by the calling routine. It is up to the calling routine to track the mission and tell the BB system when updates are required.

With that in mind, the following functions will be of use to the calling party:

 $updateBBMissionPercentage(bbID, percentage);

This function will update the percentage completed value for a given mission ID (as provided by the $addBBMission function).

When this function is called, it will also initiate the "manifestCallback" routine, giving the OXP an opportunity to update the manifest entry.

If the percentage is 1 (ie. 100%), and the completionType is "IMMEDIATE", the "completedCallback" routine will be called and the mission will be removed from the list. Otherwise, the mission will be completed at another event (eg when docking, or when the player selects "Complete Mission" on the mission details screen.)

 $updateBBManifestText(bbID, newtext);

This function will update the manifest text entry for a given mission ID. This function should generally be called from the "manifestCallback" routine.

Station Keys

To limit the stations at which a mission will be available from, a station key is required. When the "stationKey" is not provided to the "$addBBMission" function, the mission will be available at all stations in the source system.

Each station can have one station key. The default key given to each station will be the same as the stations "allegiance". So, a station with an allegiance of "galcop" will have a default station key of "galcop". Therefore, if you want to limit your mission to only be available at GalCop-aligned stations, you would include "galcop" in the "stationKey" when adding the mission to the bulletin board. If you want to include your mission at both "galcop" and "chaotic" stations, you would use a comma separator and make your mission stationKey "galcop,chaotic".

But what if allegiance is insufficient to identify the specific station you want to add your mission to? In these cases, you need to give your target station a special stationKey of its own. You can do this in one of two ways:

1. In the shipdata.plist file for the station, include the following item in the "script_info" section:

 "script_info" = {
   "bb_station_key" = "my_station";
 };
 

2. At some point after the system has been populated, (for instance, during the systemWillPopulate or startUpComplete events), find the station you want to give your special key to and add "bb_station_key" value to the "script" property by doing the following:

 var stns = system.stations;
 for (var i = 0; i < stns.length; i++) {
   // if this station is the one I'm looking for....you'll need to provide some logic for identifying your station
   if (stns[i].~something~) {
     stns[i].script.bb_station_key = "my_station";
   }
 }

Once the station has been given this custom key, you can use that key when adding missions. The custom key will override whatever default key the station may have had previously. A station can have one key only.

For example, let's say I wanted to create a mission that was only available at the main station of the system. However, with OXP's like "Stations For Extra Planets" installed, I can't just rely on the station.allegiance. What I need to do is this:

 this.startUpComplete = function() {
   system.mainStation.script.bb_station_key = "mainStation";
 }

Now I can apply the "mainStation" station key to any bulletin board missions I add, and they will now only be visible at the main station in the system.

Removing the Bulletin Board from a Station

You may decide that you don't want to have the bulletin board at a particular station. This can be achieved in one of two ways:

1. In the shipdata.plist file for the station, include the following item in the "script_info" section:

 "script_info" = {
   "bb_hide" = 1;
 };
 

2. At some point after the system has been populated, find the station you want to hide the bulletin board on and add "bb_hide" value to the "script" property by doing the following:

 var stns = system.stations;
 for (var i = 0; i < stns.length; i++) {
   // if this station is the one I'm looking for....you'll need to provide some logic for identifying your station
   if (stns[i].~something~) {
     stns[i].script.bb_hide = 1;
   }
 }

Example Mission Script

In the download package, in the "Resources" sub folder, is a mini-OXP that adds a simple "Asteroid Hunt" mission to the Bulletin Board. This OXP contains examples of all usage for the Bulletin Board, and should be used as a reference for OXP developers who want to make use of it.

Download

Download BulletinBoardSystem.oxz v0.3 BulletinBoardSystem.oxz (downloaded 3813 times).
Download BulletinBoardSystem.zip (OXP to extract to AddOns) v0.3 BulletinBoardSystem.zip

License

This OXP is released under the Creative Commons Attribution - Non-Commercial - Share Alike 3.0 license. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/

Version History

0.3

• Fixed Javascript reference error when displaying mission details.
• Fixed issue where setting course for the destination system wasn't actually setting the course.
• Bulletin Board was not reseting itself correctly between views.
• Fixed issue where the space between accepted and available missions was not appearing if there were only 1 of each type in the list.
• Added a confirmation screen to the terminate mission process.
• Added a "Set course for" option to the mission briefing page.
• Added the "confirmCompleteCallback" callback function, so that secondary steps can be confirmed before a mission can be accepted as complete. This would be useful if there is a possibility that something might have changed between completing the required steps of a mission, and getting to a dock to enter the "Complete Mission" response (eg loosing or selling cargo).

0.2

• Missions whose expiry time has already passed are now excluded from the list of available missions.
• Missions whose expiry time is extremely tight are now highighted on the list of available missions and in the mission details as well.
• clock.adjustedSeconds now used to calculate remaining time to complete mission.
• Spelling corrections.

0.1

• Initial release

Version	Released	License	Features	Category	Author(s)	Feedback
0.3	2016-02-11	CC BY-NC-SA 3.0	Mission framework	Misc OXPs	phkb	Oolite BB

Gameplay and Balance indicator