Email System OXP

Introduction

For a long time Oolite players have been receiving mission screens that array themselves as an email message. This makes sense in-game, as you would imagine a lot of communication between the player and NPC's in the game world would take place inside the bounds of an email system. However, while the conceit of an email system has been present, many other aspects of a true email system are lacking. In particular:

The ability to re-read emails after you receive them
The ability to analyse the trace of an email (ie, the path the email took to reach the player).

The Email System OXP attempts to address these shortcomings and provide (as much as possible) a true, in-game email system. After installing the OXP, you will begin to receive emails from various GalCop departments, confirming various actions that have taken place. For instance, after destroying a ship with a bounty, you will receive an email from "GalCop Bounty Processing" confirming the kill and how much bounty was paid.

Standard Operations

The OXP adds a new option on the "Interfaces" (F4) screen called "Email system". The number of unread emails will be displayed here.

After opening the email system, the player will see their inbox, sorted with the most recently received email at the top. The inbox view shows the senders name or email address, the date the email was sent, and the subject line of the email. A "!" symbol beside the email indicates it is unread.

At the bottom of the screen are the functions the player can select. They are:

Go to next page: If the inbox flows to multiple pages, this option will go to the next page.
Go to previous page: If the inbox flows to multiple pages, this option will go to the next page.
Mark all items read: This option will remove the unread "!" flag from all emails in your inbox.
Delete all read items: This option will delete all emails that have been read and are not waiting for a response from the player.
Delete all items: This will delete all emails that are not waiting for a response from the player.
Exit email system: This will exit the email system and return the player to the Interfaces F4 screen.

To open an email, use the up and down arrow keys to move the highlight bar to the desired email and press enter. Opening an email will automatically flag it as read.

When an email is opened, at the top of the screen will be the senders name or email address, the date the email was sent, and the subject line of the email.

Below this is the content of the email.

At the bottom of the screen are functions the player can perform on this email. They are:

Close email: This will close the email and return the player to the inbox. The email will now be flagged as "read".
Close email and open next: This will close the current email and open the next email in the inbox.
Close and delete email: This will close the email and delete it from the inbox if there are no response required by the player.
Show trace: This will open the email trace, which will display the path the email took to reach the player.

Some emails can require the player to make a response. When an email requires a response, there will be additional options below the "Show trace" option. The format of these options will be "Send 'option' response." For instance, an email could ask the player "Do you want to join our team?". In this case the options might be:

Send 'Yes' response
Send 'No' response

The player can select either of these options and press enter to send the response.

When an email has previously had a response sent, additional text will be added to the email body, similar to an email trail. Continuing the example above, if the player has response "Yes", the email display might end up looking like this:

From: Commander Curruthers
Sent: 2084504:05:16:02
Subject: Request for assistance
-----------------------------------------------------------------------
Commander Jameson,

Her Majesty is in need of your assistance. Thargoid incursions are on
the increase, and we need your help in the battle. Would you be willing
to join us in the fight against this rising tide of evil?

-----------------------------------------------------------------------
Reply sent: 2084504:05:29:42
Reply:

Commander Curruthurs, it would be an honour.

External Interfaces

Other OXP's can make use of the email system by calling the $createEmail function.

 var w = worldscripts.EmailSystem;
 w.$createEmail({Object with parameters (see below)});

Required fields:

sender (text) Name of person sending email
subject (text) Subject line of email
date (time in seconds) the global.clock time the email was sent

Optional fields:

message (text) Body text of email
sentFrom (int) ID of Planet that is the source of the email. Defaults to the current planet.
If the optional stopTrace flag is set, this ID will be the last planet in the trace.
isRead (boolean) Setting this to true will add the email to the inbox as if its been read by the player. This might be useful if you have displayed the message to the player using "addMessageToArrivalReport" or a mission screen, and want to add a corresponding email, which, because the player has seen it, should be flagged as read.
expiryDate (time in seconds) The time this email will expire and be deleted (if no expiryText is set). Alternatively, use the following params
expiryDays (int) number of days past the current date when the email will expire
expiryHours (int) number of hours past the current date when the email will expire
expiryMinutes (int) number of minutes past the current date when the email will expire
expirySeconds (int) number of seconds past the current date when the email will expire
Note: the above expiry options can be combined: to expire an email 2 hours and 30 minutes in the future, use expiryHours:2, expiryMinutes:30
expiryText (text) Text to display in the header when the email expired. If this text is not supplied, the email will be deleted when it expires.
expiryOptions (csv text) The response option numbers to display when the email expires. eg "3,4" would mean that option numbers 3 and 4 will be visible when the email expires.
allowExpiryCancel (boolean) Indicates whether the option to cancel the expiry notice will be avaiable to the player. Defaults to true if not supplied.
stopTrace (boolean) Indicates that the routing ticket is corrupt and a trace is only partial. The trace will terminate at the "sentFrom" planet. Defaults to false.
traceRoute (csv text) Allows the trace route information to be fully specified. If not specified, the route will be all planets between sentFrom and the current planet using the fastest route.
forceResponse (boolean) Indicates that the player must select a response before the email can be closed. Defaults to false.
option1 (object) Response option 1
option2 (object) Response option 2
option3 (object) Response option 3
option4 (object) Response option 4

The Response options have the following format: Required fields:

display (text) Text to display to the user. Shown as "Send 'displayText' response".
reply (text) The text to be appended to the body of the email as the reply from the player.
script (text) The name of the worldScript where the callback function resides
callback (text) The name of the function to call

Optional fields:

parameter (object) The object to pass to the callback function.

Example

In its most simplest form, sending an email is done with the following code. In this example, an email is sent from "Caption Solo", with the subject line of "I've got a bad feeling about this". The current time is used as the date the email was sent, and the body of the message is "I thought they smelled bad on the outside.".

 var w = worldScripts.EmailSystem;
 w.$createEmail(
   {sender:"Captain Solo",					// senders name or email address
   subject:"I've got a bad feeling about this",		// subject line
   date:global.clock.seconds,				// the time the email was sent
   message:"I thought they smelled bad on the outside."	// body text of the email
   });

A more complex example is below. In this example there is an expiry time set, 2 minutes and 30 seconds from now. Because the "expiryText" option is set, the email will remain in the inbox, but will change to an "expired" state. There are three options on this email, the first two are available while the email is current. If the email expires, the third option will be displayed and the first two will be hidden. This is controlled through the "expiryOptions" parameter.

 var w = worldScripts.EmailSystem;
 w.$createEmail(
   {sender:"The Chaser",				// senders name or email address
   subject:"Something for you do look at...",	// subject lin
   date:global.clock.seconds,			// the time the email was sent
   message:"Would you like to play a game?",	// body text of the email
   expiryMinutes:2,
   expirySeconds:30,
   allowExpiryCancel:false,
   expiryText:"This email has expired",
   expiryOptions:"3",
   option1:{display:"Yes", reply:"Sure. Why not?", script:"EmailSystemDemo", callback:"$AcceptChallenge", parameter:"mydata"},
   option2:{display:"No", reply:"Sorry. Too busy right now.", script:"EmailSystemDemo", callback:"$DeclineChallenge"}
   option3:{display:"Too late", reply:"Sorry I didn't respond to your email in time. Can I still join in?", script:"EmailSystemDemo", callback:"$TooLate"}}
   });

See the readme file in the installation package for more examples.

Installation

Place the 'EmailSystem.oxz' into your 'AddOns' folder and when you start the game, hold down 'Shift' until you see the spinning Cobra.
Alternatively, you can download the expansion using the expansion pack manager in the game itself.

Note: If using v1.20 of Deepspace Ships, ensure the "oolite-font.plist" file, located in the "Config" folder of the OXP, is removed or renamed. This custom font is incompatible with the current version of Oolite, and the Email System in particular. Version 1.21 should work fine.

Download

Download EmailSystem.oxz v1.7.7 (downloaded 13666 times).
Download EmailSystem.zip v1.7.7 (extract OXP folder to Addons)

Licence/Author

This work is licensed under the Creative Commons Attribution-Noncommercial-Share Alike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/4.0/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.
The expansion pack was developed by phkb.

Big thanks go to Wildeblood who pushed me not to compromise on functionality. Thanks to Norby who is always willing to contribute valuable ideas to any project. Thanks to Disembodied for some wonderful suggestions on new parts of the system. And huge thanks to cim, who is an amazing help with any and all technical questions relating to Oolite.

Sound files from "Robot Blip Sound" WAV file, created by Marianne Gagnon and sourced from soundbible.com. Licenced under Creative Commons Attribution 3.0.
Images from http://simpleicon.com/message_8.html, http://simpleicon.com/message.html

Version History

1.7.7

Bug fixes.

1.7.6

Better handling of purchasing equipment emails when equipment item is for the removal of something.
Better handling of purchasing equipment emails when price is calculated via a condition script.

1.7.5

Spelling corrections.
New ship email had additional zero on cost of new ship.

1.7.4

Cost of new ship in the new ship email now formatted to include cr symbol.
Small change to format of all script and text files.
Included check for a new Elite rank of "Harmless".
Code refactoring.

1.7.3

When future dated emails arrive in player's inbox, the trace route will now reflect the system they receive the email in, not the system where the email was generated.
A console message will appear when future dated emails arrive in the player's inbox.

1.7.2

Fixed issue where missile kills were not being noted in bounty emails.

1.7.1

Remove debug message in new ship email.
Added missing Elite Federation email subject for Above Average.
Fixed repair email, which was not being triggered under certain conditions.

1.7.0

Fixed issue where docking fine email was being sent after using an escape pod.
Added new email for when the player purchases, uses or sells an escape pod.
Better handling of sale of items via Ship Configuration.

1.6.8

Player will now be notified of unread emails that require a response whenever they dock at a station.
If player has unread emails requiring a response, the interface screen entry will include a token in its text.
Fixed issue where emails having expired responses could not be deleted.
Fixed issue with new ship email, where "Remove laser" was appearing in laser mounts that didn't have anything (or really, had EQ_WEAPON_NONE installed).
Fixed issue where the sales rep name was missing from new ship emails.
Fixed issue where equipment repair emails had "NaN.NaN" for the repair cost.
Fixed issue where bounty payments were being overstated for Pirate coves (or any piloted entity defined with scanClass "CLASS_ROCK").
Added some configuration items to Library Config to control what emails are sent.

1.6.7

Updated check for "Allow Big GUI".
Fixed Javascript error when setting up rep names.
Switched name generator to use "randomName".
Updated maintenance overhaul email so that it won't try to lookup equipment keys that aren't known to have a "maint_" item in descriptions. This should prevent a lot of unnecessary Javascript error messages about expansion keys not found.
Updated output of all credit amounts to use the formatCredits function.
Changed "==" comparisons to "===" for performance improvements.
Better handling of interstellar space conditions.
Better menu handling, where the current email will still be selected in the list when returning from viewing it.
Fixed issue with HUD not becoming visible again when launching while viewing the Email list.
Code cleanup.

1.6.6

small code cleanup items, added overlay background image.
Updated screenID's to enable BGS background sounds.

1.6.3

Added check to fine email for a zero calculation.
Added check to repair email for a zero payment.
Fixed issue where launching within 1 second of purchasing a new item would generate a Javascript error.
Fixed variable naming issue.
Fixed Javascript timeout issue.
Bug fixes and code cleanup.

1.6.2

Improvements to the "marked for fines" email - added additional checks for bounty threshold, suppression of arrival reports and sun going nova.
Improvements to the "docking fine" email - added additional check for sun going nova.
Switched to use "clock.adjustedSeconds" as the date sent in most GalCop emails.

1.6.1

Spelling corrections.
Small tweaks to the IronHide repair email.
Tweaks to the repair email, so items that have "repair" in the name don't get "Repair of" at the beginning of the item (eg "Repair of Emergency Hull Repairs").

1.6.0

Added overlay background image to interface screens.
Changed color of menu items on interface screens, so it's less yellow.
Really fixed issue with maintenance email and no weapon mounts.
Other maintenance email bug fixes.

1.5.2

Fixed issue with maintenance email, where maintenance was said to be performed on weapon mounts with no weapons installed.

1.5.1

Added more equipment exclusions for the Smuggling OXP.
Fixed a small bug in the inbox compilation routine that would only have reared it's head if your inbox was ever empty.
Fixed issue where the routine to clear out old emails was removing the most recent first instead of the oldest.
Added extra process to the routine to clear out old emails to remove expired items first.

1.5.0

Added some equipment exclusions for the Smuggling OXP.
Moved lists of equipment items from descriptions and into proper arrays.
Added routine to use 1.83/4 code to check for big GUI HUD's.

1.4.20

Fixed issue with new rank email referencing incorrect array variable.

1.4.19

Added specific docking fine email for Black Monks monastery.
Moved list of Federation HQ planet ID's to be accessible to external OXP's (via worldScripts.GalCopAdminServices._fedHQ array), in case it's ever needed.
Switched back to "shipKilledOther" so untargeted ships destroyed by the player (eg via missile) are included in the kill count and email.

1.4.18

Checks for the "allow_big_gui" HUD option.
Escape pod recovery emails now turn up immediately.
Added RRS refueling to list of equipment items excluded from purchase emails.
Reworked the procedure for when the player buys equipment, to ensure the email process happens after any other OXP process.
Added condition for when the purchase price of an item is 0 (zero) credits (eg removing lasers).

1.4.17

Fixed the fine amount calculation on the fine email (really totally for sure this time).
Put option text into descriptions.plist file.

1.4.16

Added ellipsis to columns when text is truncated
Slight adjustment to column widths to cater for wider fonts
Removed seconds component from email items on the inbox display. The full sent date/time, including seconds is still visible when you open an email.

1.4.15

Fixed an issue with the new parcel and passenger contracts, where the contract name wasn't being added to the email correctly.

1.4.14

Fixed an issue with purchasing passenger berths, where an incorrect email was being sent.

1.4.13

Fixed an issue with the rescued escape pod email, where a substitution was not entered correctly.
Fixed issue with maintenance email. Report will now only list items that have "isVisible = true".

1.4.12

Code improvements as suggested by Wildeblood.

1.4.11

Speed improvements as suggested by Norby.

1.4.10

Small bug fix when checking Combat Simulator
Added exclusion for extra ship respray equipment item

1.4.9

Fixed bug where the new pilot registration email was not being sent for new pilots. Instead, the late notice email was being sent.

1.4.8

Corrected a minor bug with calculating the route to another system. Had "OPTIMISED_BY_TIME" instead of "OPTIMIZED_BY_TIME".
Faster sorting algorithm
Added exclusion for "Ship Respray" OXP.

1.4.7

Fixed issue where using the Combat Simulator OXP would generate invalid emails

1.4.6

Better error handling of maint_itemname code.
Fixed manifest version number issue

1.4.5

Added some more equipment key exclusions for the maintenance email (ShipVersion OXP items)
Added some special cases for ShipVersion repair equipment items.
Switched from shipKilledOther to shipTargetDestroyed to better monitor for ships destroyed by the player
Small bug fixes and tweaks.

1.4.4

Fixed grammar issue with bounty emails in Interstellar space.
Added some more exams to the new pilot registration email
Fixed decimal number issue with docking fines and other places.
Fixed issue with docking fines at some stations, where the wrong name was showing in the duty officers email signature.

1.4.3

You can now exit from the email system just by pressing another function key.

1.4.2

Attempt to fix issue when the number of unread emails on the interfaces screen was not updating in some circumstances

1.4.1

Made the licence number longer (it's a big galaxy after all)
Moved the licence email out of the block that checks for a new ship. This is so users of the Hardships OXP will at least get a pilot's licence when they start.
Fixed a bug with saving and loading to mission variables.

1.4.0

Changed the inbox UI to be similar to contract interfaces, where you highlight the desired item and press enter to open the email.
Added a couple of other GalCop admin-related emails, relating to transfer of ownership of ships, and pilot licensing.
Layout tweaks to maintenance email, adding some headings
Small tweaks to the text of bounty emails.
Small grammar corrections.

1.3.0

Improved the purchase equipment email to handle removal of equipment better.
Added equipment description to the purchase equipment email.
Made the random names a little less random. Now, multiple purchases of equipment will have the same sales rep name while you are docked at that station.
Improved compatibility with Hardships. You won't get an initial "Welcome to your new ship" with Hardship's start choices, but you also won't get spammed either.
Included no bounty kills in the bounty email, with appropriate notices
Added the number of kills to the bounty email
Future-dated emails are now hidden until their sent date is in the past. This means you can send emails at any time, but with a future date, and player won't see them until the right time.
ExpiryDays, ExpiryHours, ExpiryMinutes and ExpirySeconds are now linked to the sent date, rather than to the current date. So if you future date an email and give it an expiry of 2 days, that will be 2 days after the future date, not the current date.
Added a tone for when future dated emails become current. Will only play when docked.
Code cleanup.

1.2.0

Fixed bug with the equipment purchase email, when the wrong price was being shown when equipment was bought in any non-main station.
Added emails from the Elite Federation for changes in player rank
Improved the new ship email content, including the method of calculating the cost of the new ship.
Improved default option selection on multi-page emails
Improved the bounty email. If there are several systems between dockings, the email will include the system name the bounties were collected in.
Added more maintenance items for overhaul email, including notation for damaged items
New ship email will now be sent whenever a new game is started (hopefully this will catch most scenarios as well as the standard ones)
Fixed the calculation of the fine amount
Fixed bug with failed passenger contracts subject line
Fixed issue with overhaul email and ships without hyperspace capability (email might have included witchdrive maintenance items)
Removed expiry date from new contract emails
Spelling corrections

1.1.5

Fixed problem with recursive function on Macs. Removed recursion.

1.1.4

Added GalCop emails for purchasing equipment, new ships, and maintenance overhauls.

1.1.3

Remove the %R special expansion and replaced with [nom] for better random name generation.

1.1.2

Removed arrival report message. If you really want it, you can turn it on with a setting.
Fixed issue with the bounty report email if the player destroys a ship with no bounty. No entry will be made in this case now.
Added an archive limit, so that emails will automatically be start to be deleted if they have 100 emails or more.
Added an expiry date to all the standard galcop notices.
Simplified $createEmail object parameters.
added a zero check on expiry time
fixed bug where number of pages wasn't updating when deleting emails.
spelling corrections

1.1.1

Removed unnecessary OXP folders, combines GALCOP Admin services into main OXP, ready for OXZ publication
Fixed bug when calling $createEmail during flight (thanks to Wildeblood for the heads up)
Removed unnecessary option on the $createMail function
Added message to arrival report if the player has unread emails.

1.1.0

Fixed bug with closing a long email on a page greater than 1 and opening the next email. Thanks to Wildeblood for the bug report.
Added ExpiryDate option (thanks to Wildeblood for the suggestion)
Reworked the response options so that there is no need for OXP's to reconnect callback functions.
Changed the save format in mission variables to use a single value, rather than multiple values, for emails.
Code cleanup (thanks to Wildeblood for the pointers)

1.0.1

Changed createEmail function call to use an object, rather than parameters.
Added galaxy number to stored emails, which will be displayed when the player is in a galaxy other than the one they received the email in.
fixed bug that was preventing bounty email from being sent
fixed bug that was sending a docking clearance penalty notice when docking clearance was about to expire
Spelling fixes
Code cleanup