Bulletin Board System

From Elite Wiki
IconBB.png

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.

This is a requirement for such OXP's as Bulletin Board Contracts, GalCop Missions, Enhanced Passenger Contracts & Hermitage

Player Usage

The Bulletin Board is accessed through the Interfaces screen (F4), and it's normally found under Contracts.

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 "GalCop 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.
If the destination system of a mission is directly on your currently plotted course on the F6 system map, the mission will be coloured green.
If the destination is within 7ly of any system on your currently plotted course, the mission will be coloured dark green.
Using the Library Config OXP, the use of colour can be changed to instead use markers, where a † beside the destination system name means "on current course", and a ‡ means "near current course".

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

DescriptionThe short description of this mission.
DetailsFull details of the mission parameters.
Destination systemWhere the mission needs to be completed at.
Mission expires inHow much time you have to complete the mission.
Payment on completionHow much you will be paid when the mission is completed.
PenaltyHow 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 completeHow much of the mission has been completed so far.

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

Accept missionThis will signal that you are starting this mission.
Show destinationThis 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 missionThis 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 missionThis 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.

Moving contracts onto the Bulletin Board

If you want to move all the cargo, passenger and parcel contracts onto the Bulletin Board, see the Bulletin Board Contracts OXP.

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 BB system and saved in the save game file, but the list of available missions will be cleared out with each hyperspace jump.

$addBBMission

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!",
     statusText:"A special text description to include on the briefing screen.",
     expiry:clock.seconds + 86400,
     payment:1000,
     penalty:100,
     deposit:0,
     allowPartialComplete:false,
     allowTerminate:true,
     accepted:false,
     percentComplete:0,
     completionType:"AT_SOURCE",
     stopTimeAtComplete:false,
     markerShape:"MARKER_PLUS",
     markerColor:"cyanColor",
     markerScale:1.0,
     model:"police",
     spinModel:true,
     disablePercentDisplay:true,
     customDisplayItems:"",
     initiateCallback:"$myMissionInitiate",
     completedCallback:"$myMissionComplete",
     confirmCompleteCallback:"$myMissionConfirmComplete",
     terminateCallback:"$myMissionTerminate",
     failedCallback:"$myMissionFailed",
     manifestCallback:"$myMissionUpdateManifest",
     availableCallback:"$myMissionAvailableCheck",
     worldScript:"MyFirstMission",
     keepAvailable: false
   });
 }

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.
Setting destination to -1 equals Interstellar space.
Setting destination to 256 means there is no fixed destination.
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
detailsThis 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.
statusText(optional) This is the text to display on the mission briefing screen when the mission is active. If not set, the "manifestText" property will be used instead.
expiry(required) The time is clock seconds when the mission must be completed by. If set to -1 this means the item has no expiry time.
payment(optional) 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.
deposit(optional) The number of credits the player will need to pay up-front to accept the mission. This amount will be refunded when the mission is completed.
allowPartialComplete(optional) True/false value that indicates whether the player can complete the mission with less than the full percentage. Payment and deposit will be scaled by the percentage completed. Penalties will also apply, again scaled by the percentage completed.
For example, if the payment is 100 cr and the penalty 10 cr, and the player completes 70% of the mission, if they hand it in they would receive 70 cr (70% of 100), and the penalty would be 3 cr (30% of 10), meaning their total payment would be 67 cr.
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.
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.
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_SOURCEPlayer must return to the source system/station, open the mission and select "Complete mission".
AT_STATIONKEYPlayer can return to any system, dock at any station with the same stationKey, open the mission and select "Complete mission".
ANYWHEREPlayer can return to any system, dock at any station, open the mission and select "Complete mission".
IMMEDIATEPlayer is rewarded immediately when the mission is flagged as 100% complete - player won't need to dock anywhere.
WHEN_DOCKED_SOURCEPlayer is automatically rewarded as soon as they next dock at the source system/station. Notice will appear in arrival report.
WHEN_DOCKED_STATIONKEYPlayer 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_ANYWHEREPlayer 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".
stopTimeAtComplete(optional) True/value flag to indicate that the clock will stop when the mission is flagged 100% complete.
Default false. This means that, for a completionType of "AT_SOURCE" the player has to return to the original station within the allowed time in order to complete the mission. If this flag is set to true, once the player completes the mission at the destination, they are free to take as much time as they like to return to the original station and hand in their mission.
This flag will be ignored if the completionType is set to "IMMEDIATE".
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) guiTextureSpecifier (name of a picture used as background)
overlay(optional) guiTextureSpecifier (name of a picture used as overlay). Will default to the bulletin board graphic when not set.
mapOverlay(optional) guiTextureSpecifier (name of a picture used as overlay) for the map screen. Will default to the "overlay" setting (if set), otherwise will use the bulletin board graphic.
forceLongRangeChart(optional) True/false value which, when true, indicates that the map display for this mission
markerShape(optional) Allows the shape of the galactic chart marker to be overridden. Default is "MARKER_PLUS". Possible values are:
NONENo galactic chart marker will be added.
MARKER_XUses an "X" to mark the system.
MARKER_PLUSUses a "+" to mark the system.
MARKER_SQUAREUses a square shape to mark the system.
MARKER_DIAMONDUses 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.
additionalMarkers(optional) Array of marker dictionaries definition any extra systems that should be marked on the system map for this mission. Each item can have:
systemsystem ID to mark (required)
markerShapeone of the standard marker shapes (default MARKER_PLUS)
markerColorcolor of the marker (default redColor)
markerScalescale of the marker (default 1.0)
disablePercentDisplay(optional) Controls the display of the "Percent complete" value on this mission details page. Default false.
When set to true, only the mission manifest text will be shown on the mission details page.
playAcceptedSound(optional) Controls whether the [contract-accepted] sound will be player upon contract acceptance.
Default is true.
customDisplayItems(optional) Allows a mission to specify additional, non-standard items on the details page.

When used, should be set to an array of dictionary items, having "heading" and "value" properties in each dictionary object.

eg [{heading:"Special Instructions:", value:"Be very, very qwiet..."}]
customMenuItems(optional) Provides a way for a third party to add custom menu entries to a BB item.

When used, should be set to an array of dictionary items, having the following elements:

text(required) Text to display in the menu item
worldScript(required) Name of the worldScript which contains the callback function
callback(required) Name of the callback function (the mission ID will be passed as a parameter)
condition(optional) Name of a callback function that will return either a blank string, meaning the menu item is available, or a string containing the reason why the menu item is unavailable. (The mission ID will be passed as a parameter)
activeOnly(optional) Boolean value indicating the menu item is only visible when the mission is active. Default is true.
autoRemove(optional) Boolean value that indicates the menu should be remove from the BB item as soon as the player selects it. Default is false.
initiateCallback(optional) The function name to call back when the mission is accepted by the player.
completedCallback(optional) 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(optional) 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.
availableCallback(optional) The function to call to check if the mission is actually available. The mission ID will be passed as a parameter. Function should return a string value of either a blank (""), to indicate the mission is available, or a short description of the reason why the mission is unavailable (eg "Insufficient cargo space").
bonusCalculationCallback(optional) The function to call to calculate and return any bonus payment when the player successfully completes a mission. Will only be called if the mission is 100% completed inside the allotted time. If set, must return a number >= 0. Will be called after the completedCallback function, if set.
worldScript(required) The name of the worldScript where these functions reside.
keepAvailable(optional) Flag to indicate whether mission should kept when player leaves the system. Default false.
postStatusMessages(optional) Array of dictionary objects defining a message to be displayed to the player when they accept, complete or terminate a mission.
status(required) Defines which status the message will follow. Possible values: initiated, completed, terminated
text(required) The text of the message to be displayed
return(optional) Where to return the player to after the mission page is displayed
itemReturns player to the mission details page (N/A for completed/terminated)
listReturns player to the mission listing
exitReturns player to the F4 Interfaces screen
background(optional) guiTextureSpecifer to use for the background of the message
overlay(optional) guiTextureSpecifer to use for the overlay of the message
model(optional) ship model to use on the message.
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 is true.
If any of the optional parameters are left out, the equivalent parameter from the BB item will be used.
data(optional) Any data that might be useful to store with the mission for later access.

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.

$updateBBMissionPercentage

 $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.)

$updateBBStatusText

 $updateBBStatusText(bbID, newtext);

This function will update the status text on the mission briefing screen for a given mission ID. This function should generally be called from the "manifestCallback" routine. If no status text is supplied, the "manifestText" property will be used instead.

$updateBBManifestText

 $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.

$percentCompleted

 $percentCompleted(bbID)

Returns the current percentage complete value for a particular mission ID.

$removeBBMission

 $removeBBMission(bbID)

Removes a particular mission ID from the list. This method skips any mission constraints and completed/failed events and just removed the record. This can be useful when chaining missions together, if the previous mission needs to be removed completely, without performing any of the callbacks.

$getItem

 $getItem(bbID)

Returns a bulletin board mission object for the given mission ID.

$getIndex

 $getIndex(bbID)

Returns the index value of the given mission ID in the internal data array. This can be useful if you would like to update mission parameters directly (eg. changing the "stopTimeAtComplete" flag).
Note: Because index values are subject to change without notices (particularly between saves) the value returned from this function should be used and then discarded. Do not try to save the index value in some method and use it later - you may be updating a completely different mission!

$registerBBEvent

 $registerBBEvent(wsName, fnName, eventName)

Registers a worldScript/function to be called when a particular BB system event takes place.

wsNameName of worldscript where function can be found.
fnNameName of the function to call.
eventNameName of the event to attach to.

At the moment, the possible events are:

missionAddedOccurs when a mission is added to the BB.
openOccurs when the BB is opened.
closeOccurs when the BB is closed using the "Close" option.
exitOccurs when the BB is closed by the player selecting another Fn command.
launchExitOccurs when the BB is closed by the player launching their ship. The station launched from will be passed as a parameter.
preListDisplayOccurs just before the BB mission list is displayed
postListDisplayOccurs just after the BB mission list is displayed
preItemDisplayOccurs just before a mission detail page is displayed. The mission ID will be passed as a parameter.
postItemDisplayOccurs just after a mission detail page is displayed. The mission ID will be passed as a parameter.
preItemChartDisplayOccurs just before the chart view of a mission is displayed. The mission ID will be passed as a parameter.
postItemChartDisplayOccurs just after the chart view of a mission is displayed. The mission ID will be passed as a parameter.

$unregisterBBEvent

 $unregisterBBEvent(wsName, fnName, eventName)

Removes a callback from the registration list.

wsNameName of worldscript where function can be found.
fnNameName of the function to call.
eventNameName of the event to detach from.

$setBackgroundDefault

 $setBackgroundDefault(guiTextureSpecifer)

Sets the default background to use on the BB.

$resetBackgroundDefault

 $resetBackgroundDefault()

Resets the default background back to the original default.

$setOverlayDefault

 $setOverlayDefault(guiTextureSpecifier)

Sets the default overlay to use on the BB.

$resetOverlayDefault

 $resetOverlayDefault()

Resets the default overlay back to the original default.

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 multiple station keys, depending on the worldScript, but if no specific station key is added, the default station key will be the stations "allegiance" property. 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. 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 perform the following function: 

 var bb = worldScripts.BulletinBoardSystem;
 var stns = system.stations;

 // loop through all the available 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 >>) {
     // add the station key for this worldScript
     bb.$addStationKey(this.name, stns[i], "myStationKey");

     // first parameter is "worldScriptName". Normally this would be "this.name".
     // second parameter is "station". This is a reference to the station.
     // third parameter is "stationKey". This is the station key that will be added to the list of keys for this worldScript and station combination.
   }
 }

Once the station has been given this custom key for your worldScript, 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 multiple keys for your worldScript.

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.systemWillPopulate = function() {
   if (system.mainStation) {
     var bb = worldScript.BulletinBoardSystem;
     bb.$addStationKey(this.name, system.mainStation, "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;
   }
 }

Adding main menu items

There may be times when you want a special menu item to appear on the main control listing page of the BB system, not just on the mission details page itself. To do this you can use the $addMainMenuItem and $removeMainMenuItem functions.

To add a menu item use the $addMainMenuItem function: 

 var bb = worldScripts.BulletinBoardSystem;
 if (bb) {
   bb.$addMainMenuItem({
     text: "Special function text",
     color:"greenColor",
     unselectable: false,
     autoRemove: true,
     worldScript:"myWorldScriptName",
     menuCallback:"myFunctionName"
   });
 }

In detail these parameters are:

text(required) Text to display on the menu
color(optional) Color of the item. Will default to this._menuColor (orangeColor)
unselectable(optional) Flag to control whether the item should be unselectable. Defaults to false.
If true, color will be set to this._disabledColor (darkGreyColor).
autoRemove(optional) Flag to indicate the item should be removed from the menu when selected by the player. Defaults to false.
worldScript(required) WorldScript name for the callback function.
menuCallback(required) Function to call when the user selects the item.

To manually remove a menu item (ie if the "autoRemove" option is set to false), use the $removeMainMenuItem function: 

 var bb = worldScripts.BulletinBoardSystem;
 if (bb) {
   bb.$removeMainMenuItem("myWorldScriptName", "myFunctionName");
 }

This function accepts two parameters:

worldScriptNameThe name of the worldScript registered on the item.
functionCallbackNameThe name of the menu function callback on the item.

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 most of the functions of the Bulletin Board, and should be used as a reference for OXP developers who want to make use of it.

Download

Download BulletinBoardSystem_2.6.3.oxz
Download BulletinBoardSystem.zip v2.6.3 (extract OXP folder to AddOns)

License

This work is licensed under the Creative Commons Attribution-Noncommercial-Share Alike 4.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/4.0/

Bulletin board image by icons8.com from http://www.iconsplace.com/black-icons/copy-icon with licence Creative Commons Attribution-NoDerivs 3.0 Unported

Version History

2.6.3

  • Added check for deferred bounty system (Bounty System OXP) when missions with completion type "IMMEDIATE" are completed.
  • Improved clarity for when you have completed a mission but are docked at the wrong station type.

2.6.2

  • When a contract is complete, the "Set course for" option is now only shown if the completion type is "AT_SOURCE" or "WHEN_DOCKED_SOURCE".

2.6.1

  • Corrected name of HUD.

2.6

  • Switched method of displaying a full screen so that the message box is visible when messages are sent.

2.5

  • Really fixed issue with missions not able to be created in systems with ID 0 or 255.

2.4

  • Fixed issue that would prevent missions being created in systems with ID 0 or 255.
  • Added a "keepAvailable" flag to prevent a mission from being dropped if it isn't accepted when you leave the system.

2.3

  • Better protection against missions in the list whose worldscript is no longer available.
  • Better cleanup of system markers where missions are removed from the bulletin board.

2.2

  • Fixed issue that could lead to missions having the same ID.

2.1

  • The email ID of the last email sent relating to a BB item is now accessible through the "lastEmailID" property. Requires Email System v1.7.8.

2.0

  • Fixed issue were text was covering the map when the Advanced Navigation Array wasn't installed.

1.9

  • Tweaks to the calculation for determining if an unaccepted mission is expired.

1.8

  • Fixed issue where the calculation to determine whether an unaccepted mission should be considered expired was being a little too broad.
  • Bug fixes.
  • Code refactoring.

1.7

  • Calls to 'confirmCompletedCallback' now performed each time mission screen is opened when a "Complete mission" menu item is displayed.
Show older

Links

Quick Facts

Levelindicator0.png
0-{{{2}}}

Minimum Oolite versionCPU usage lowMemory usage averageGPU usage lowisAPIisDocumentedisConfigurable

Config options available through 'Library'
Version Released License Features Category Author(s) Feedback
2.6.3 2024-05-27 CC BY-NC-SA 4.0 Mission framework Misc OXPs phkb Oolite BB

Gameplay and Balance indicator

Tag-colour-green.png

Retrieved from "https://wiki.alioth.net/index.php?title=Bulletin_Board_System&oldid=83923"