Email System OXP

From Elite Wiki
Revision as of 14:20, 13 March 2015 by Phkb (talk | contribs) (→‎Download)

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. There are three indicators that can appear beside each email.

  • "!" indicates the email is unread.
  • "*" indicates the email has been marked by the player.
  • ">" indicates the currently selected email.


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

  • Select next item: This will move the ">" indicator to the next email in the list.
  • Select previous item: This will move the ">" indicator to the previous email in the list.
  • 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.
  • Open selected item: This will open the mail currently selected with ">".
  • Mark selected item: This will put a "*" mark beside the currently selected item.
  • Unmark selected item: This will remove the "*" mark beside the currently selected item.
  • Delete marked items: This will delete all emails that are currently marked with "*" 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.


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 is most simplest form, sending an email is done in the following. 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.3.0 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.

Version History

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.2.0 2015-03-08 CC BY-NC-SA 4.0 Email Equipment OXPs phkb Oolite BB

Gameplay and Balance indicator

Tag-colour-green.png

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