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:

1. The ability to re-read emails after you receive them
2. 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.".

 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.

 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.

Download

Download v1.4.11 EmailSystem.oxz (downloaded 13666 times).
Alternative download for the OXZ from here.
To download this as a OXP inside a ZIP file, click here. You will need to extract the OXP folder to your AddOns folder to use this option.

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.

Version History

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

Quick Facts

Version	Released	License	Features	Category	Author(s)	Feedback
1.4.11	2015-05-15	CC BY-NC-SA 4.0	Email	Equipment OXPs	phkb	Oolite BB

Gameplay and Balance indicator