JK Mail Plugin [MV]

JK MailSystem v2.51

JK Mail Editor v3.0.1

Author: Pirobi and JK Software

Note: Mail Editor is Windows-only for now. We are working to get a Mac version built, please stay tuned!

Introduction

This plugin adds a mailbox and messaging system to a project. Messages can be sent to the player's "inbox" through plugin commands and read.

(Experimental) NEW FEATURE ~ Attachment Restrictions

As of version 2.5, you can specify attachment criteria!

Do you have a plugin that restricts inventory?

Maybe the attachment is encrypted and you can only collect it if you solve a puzzle?

To do this, specify attachment criteria (default is true, always claim)!

Examples:

"attachmentCriteria":"$gameSwitches.value(10)" - only claim attachment if switch 10 is ON

"attachmentCriteria":"$gameVariables.value(1) == 4" - only claim attachment if variable 1 equals 4

"attachmentCriteria":"SomePlugin.hasRoomForItem()" - only claim attachment if the plugin script call (SomePlugin.hasRoomForItem()) returns true

FEATURE ~ Shared Mail

Introduced in version 2.41, you can now add the same instance of mail to multiple mailboxes. All triggers/attachments/read status will be shared among the mailboxes it is placed into. New plugin commands are provided for this (see the Plugin Commands section).

FEATURE ~ Optional Avatar

Introduced in version 2.3, you can now make a message display a portrait at the top of the message text (to the left of the sender and subject text). For now, you can choose from any image in the img/faces folder. The syntax in the json is as follows:

"imgName":x,"imgIndex":y

Where x is the name of the file in img/faces, and y is the index of the portrait to use.

FEATURE ~ Updated Plugin Parameters

As of version 2.2, we have updated our plugin parameters to utilize the new features in MV 1.5! If you have plugin parameters set, you will probably need to update them to be compatible!

FEATURE ~ Scrolling!

As of version 2.41, scrolling is always enabled, and multiple pages have been removed. Word wrapping is also now supported with scrolling. (Credit to Yanfly for the inspiration). A plugin parameter has been provided to indicate what the wordwrap command is. For example, if you type in <WordWrap> to specify word wrapping, the plugin parameter will read "WordWrap".

You will need to add the command (e.g. <WordWrap>) to the beginning of the mail body for each message.

FEATURE ~ Flags!

Introduced in version 2.1, you can now flag a message so that the player cannot delete it from the mailbox scene.

The following line must be placed inside each mail json object:

"flag":"w,x,y,z"

Where x is the type of flag you want to set:

s - allow this message to be deleted only after a switch with an ID of x is set to ON.

v - allow this message to be deleted only after a variable with an ID of x passes the given condition

    In this case, y can be set to the following:

    0 - pass if the variable at x is equal to z

    1 - if the variable at x is greater than z

    2 - if the variable at x is greater than or equal than z

    3 - if the variable at x is less than z

    4 - if the variable at x is less than or equal to z

    5 - if the variable at x is not equal to z

    y and z are only looked at in this case.

n - never allow the message to be deleted

j - allow this message to be deleted if and only if the script at x evaluates to true

RULES FOR FLAGS:

- Only a message that has no attachment can be deleted - meaning you must collect any attachments before you can delete it.

- PLUGIN COMMANDS WILL STILL REMOVE THE MESSAGE, EVEN IF IT IS SET TO NEVER. The reason for this is because plugin commands are at the discretion of the developer, which should override the player's extent of control.

- Triggers will still execute even if a READ message is deleted. If an UNREAD message is deleted, the trigger will NOT execute. One way to guarantee your trigger will run is to use a common event trigger that does your processing, then sets a switch at the end. Then, give the message a switch flag using that switch. That way, the message can't be deleted until the trigger runs!

- Because triggers don't activate until you leave the mail scene, if a message's flag is set to a switch that gets set in a trigger, you need to exit the mail scene before you're allowed to delete the message.

EXAMPLES OF FLAGS:

"flag": "s,10" - this message can only be deleted if switch 10 is ON

"flag": "j, $gameSwitches.value(10)" - the same as above but using a script call

"flag": "j, $gameParty._actors[0] === 1" - this message can only be deleted while actor 1 is the leader of the party.

"flag": "j, $gameParty._actors[0] === 1 && $gameSwitches.value(10) && $gameActors.actor(1)._level === 5"

    - this message can only be deleted while actor 1 is the leader of the party, switch 10 is on, and actor 1 is level 5

"flag": "v, 10, 1, 30" - this message can only be deleted while variable 10 is greater than 30

"flag": "0" - this message can always be deleted from the mailbox scene

FEATURE ~ Triggers!

You can now perform triggers when a message is read. The following line must be placed inside each mail json object:

"trigger":"w, x, y, z"

     Where w s the type of trigger you want to perform:

     s to set a switch. If the switch is off, it will turn on, and vice versa.

     v to set a variable. It will OVERWRITE the previous value.

     c to run a common event.

     j to run a script call.

     Put any other value to have no trigger.

     For switches, variables, or common events, x will be the index

     For a script call, x will be the script itself.

When w is set to a variable (e.g. "trigger":"v,1,11,0"), y will be the value and z will be the operation. In the above example, x is 1, y is 11, and z is 0.

z can be set to one of the following values:

0 - Set the value of y to the variable at index x

1 - Add the value of y to the variable at index x

2 - Subtract the value of the variable at index x by y

3 - Multiply the value of the variable at index x by y

4 - Divide the current value of the variable by y

5 - Mod the current value of the variable at index x by y

If z has any other value, or if z is omitted from the trigger, it will default to 0.

        EXAMPLE:

            "trigger":"j,$gameVariables.setValue(1,4);" - Will run a script call to set the variable at index 1 to 4.

            "trigger":"v,1,4" - The same as above except using direct notation

            "trigger":"v,1,11,4" - Will divide the value of the variable at index 1 by 11 and store the answer in the same variable

            "trigger":"v,3,$gameVariables.getValue(2)",1" - Adds the value at variable index 2 to the value at index 3

            "trigger":"c,30" - Will run common event at index 30

    NOTE: If you add the same mail more than once, or are in a situation where

    the same message will be in the "unread" state more than once, the trigger

    WILL run again! This might be addressed in a future update if needed.

    NOTE:, triggers will NOT activate until you exit the mail scene!

Feature ~ Attachments!

You can choose to add 1 attachment to your message. The syntax is displayed in the above spoilertag, but I will define it here:

"attachment":"xy"

    Where x is the type of item you want to attach: a for armor, w for weapon, i for item, g for gold. Put any other value to have no attachment.

    If you are attaching gold, y is the amount of gold to attach. For the other types, it is the index of that item in the database.

    i.e. a1 will attach the Armor at index 1 in the database. g100 will attach 100 gold to the message.

    In the mailbox scene, just press enter on the message with an attachment, and it will be added to your inventory.

Feature ~ Multiple Mailboxes!

    You are able to change the number of mailboxes in the game! Each mailbox will have its own list of messages, and you can add mail to each one separately.

    There are 2 plugin parameters added to the game:

         MailBoxLength - The number of different mailboxes in the game.

         MailBoxNames - The name to attach to each mailbox, This is currently only a quality of life change.

Plugin Commands

Several plugin commands can be used to interact with this list:　　　

• MailAdd id
  • Adds the specified message to the first mailbox.
• MailAdd id box1 box2 box3 . . .
  • Adds the specified message to the specified box(es).
• MailAddSame id box1 box2 box3...
  • Adds the same instance of the message to the specified box(es).
• MailAddAll id1 id2 id3 . . .
  • Adds the specified message(s) to every mailbox.
• MailAddAllSame id1 id2 id3 ...
  • Adds the same instance of the specified message(s) to every mailbox
• MailBoxAdd box id1 id2 id3 . . .
  • Adds the specified message(s) to the specified mailbox.
• MailRemove id
  • Removes the specified message from the first mailbox.
• MailRemove id box
  • Removes the specified message from the specified box.
• MailRead id
  • Changes the status of the specified message in the first mailbox to read.
  • Mail must already be in the mailbox for this to work!
• MailRead id box
  • Changes the status of the specified message in the specified box to read.
  • Mail must already be in the mailbox for this to work!
• MailUnread id
  • Changes the status of the specified message in the first box to unread.
  • Mail must already be in the mailbox for this to work!
• MailUnread id box
  • Changes the status of the specified message in the specified box to unread.
  • Mail must already be in the mailbox for this to work!
• MailBoxOpen id
  • Opens up the mailbox scene using the specified mailbox.
  • Mail Box ID starts from zero!

    It would be a good idea to keep track of which id belongs to which mailbox! We may add the ability to call boxes by name in the future!

How to Use

• To call the Mailbox scene, use the following script call:
  • SceneManager.push(Scene_Mail);
  • Note, this call will open the last used mailbox!
  • You can also use this call if only 1 mailbox is being used.
• To check if a message is in the first(default) mailbox, use the following:
  • JKMail.isMailRead(mailID);
• To check if a message in a specific box has been read, use the following script call:
  • JKMail.isMailReadInBox(box, mailID);
• To check if a message is in the first(default) mailbox, use the following:
  • JKMail.hasMail(mailID);
  • RETURNS THE INDEX OF THE MAIL IF FOUND, OR -1 IF NOT FOUND
• To check if a message is in a specific mailbox, use the following:
  • JKMail.hasMailInBox(box, mailID);
  • RETURNS THE INDEX OF THE MAIL IF FOUND, OR -1 IF NOT FOUND
• To check if a box has unread mail, use the following:
  • JKMail.hasUnreadMail(box);
• To get the Sender of a specified message, use the following:
  • JKMail.getSender(mailID);
• To get the Subject of a specified message, use the following:
  • JKMail.getSubject(mailID);
• NEW in 2.4 - To open a mailbox from the menu, use the following:
  • this.commandMail.bind(this); -- will open the last-opened mailbox
  • this.commandMail.bind(this, x); -- where x is the mailbox to open

Where box is the id of the mailbox, and mailID is the id of the message.

When in the mailbox scene, the controls are currently as follows (using defaults):

•      Up/Down - navigate through the list of messages, or through the message.
•      Space/Enter - Select a Message, select a command.
•      X - exit the message/mail scene, cancel.

FAQ

Q: Can I use this plugin for my commercial game?

A: Yes, you can! Please be sure to check the licensing information, either in the script or below. And be sure to let me know if you do use it (a copy of the game would be nice too!)

Q: I'm running into [insert bug/error here], what do I do?

A: Please report any problems, suggestions, or comments here in this thread, or send me a pm. I will do my best to keep working on the plugin to make it more beautiful, optimized, etc.

Q: My text is cutting off on the edge!

A: If you are not using word-wrapping, then you must manually insert escape characters (\r\n), or hit enter where you want your text to break.

Credit and Thanks

- Pirobi, aka Kevin Garrone

- TheDeadGPU for debugging and the mail editor.

- JK Software

- Liquidize, for formatting support, moral support, etc.  

- NewtonSoft for the JSON Library for the MailEditor

   

Known Issues

- Deleting mail from the mailbox scene does NOT give you a prompt. We could potentially put one, but my thinking was that if it's that important, you would put a flag on the message. 

- There is no better way to determine if a message has more pages besides the message itself staying unread. I'll see how people like this, and if there may be a better way to convey this information (the scene is a little crowded as it is!)

Release History

-2.51: Fixed plugin crashing when no mail in mailbox

-2.5: Added ability to restrict when an attachment can be claimed.

-2.42: Fixed issue where opening a mailbox without specifying an id would crash the game. Editor scaling adjustments.

-2.41: Removed Multiple Pages. Updated how scrolling works and allowed

compatibility with wordwrap, hence why multiple pages is no longer needed.

Added plugin commands to share mail between mailboxes.

-2.4: Added compatibility with MOG custom backgrounds. Added ability to open the Mailbox scene from the Menu.

-2.3: Added ability to attach an image to a message. Various fixes and optimizations.

-2.21: Fixed issue where deleting mail while on a different page could cause 

outOfBounds issue if next mail doesn't have same page number. Fixed issue where exiting out of mail would not reset back to first page. Fixed issue where exiting mail and then pressing left/right would still cause the mail pages to change.

-2.2: Added ability to have multiple pages in one message. Added more Flag options. Added ability to disable scrolling, allowing for word wrapping to be used.

-2.11: Fixed issue where empty mailbox would crash game.

-2.1: Added ability to delete mail from inside the mailbox scene. Added Flags to indicate if a message can be deleted or not. Updated Mail Scene Look & Feel to incorporate deletion. Added support for multiple resolutions.

-2.02: Fixed issue with saving/loading mail from a save file. This was introduced during 2.0.1.

-2.01: Added plugin parameters to adjust text colors of unread mail,

"From", and "Subject" texts. General performance improvements.

Added option to perform manual line breaks using <br> in the json.

-2.0: Added options to add, sub, mult, divide, and mod variables via triggers. Made newest messages appear at the top of the mailbox list.

-1.95: Small bug fixes. Modified Attachment Window to reveal the Attachment

name when the message is read.

-1.9: Static text in the Mail scene is now customizable. Added getter functions to return Sender and Subjects for specified messages, indicated by ID. Adjusted Attachments so that they can only be collected when the message is read.

-1.8: Fixed issue Where MailAdd id box1 box2 box3 . . . was doing the same as MailAddAll. Changed MailAddAll to be able to add multiple messages to all mailboxes.

-1.7: Added ability to call a trigger after a message is read. Fixed issue where loading a saved game would double the messages in the mailbox.

-1.6: Fixed bug where mailbox doesn't open when there is no mail. Updated code to center the mail scene on bigger resolution.

-1.5: Added ability to scroll through messages if it is too long to fit on the screen. Removed word-wrapping dependency from plugin, and moved it to the editor tool. Adjusted size of editor to better show how the message would look in-game.

-1.4: Added plugin commands to add multiple messages to a mailbox, to add a message to multiple mailboxes.

-1.3: Added ability to have multiple mailboxes, so that each mailbox can receive different messages (Useful for characters, bulletin boards, etc.)

-1.2: Removed a drawAllItems() line from the attachment window. In some cases, nothing happened, while in other cases, the game crashed. Removing the line seems to have stopped the crashing. I will continue to monitor this moving forward. Please note that save files using older versions of this plugin MAY NOT WORK ANYMORE.

-1.1: Forgot to add ability to save the mail list(fixed). Added ability

to add attachments to messages.

-1.0: Initial release