JK Mail System

Pirobi

Veteran
Veteran
Joined
Oct 25, 2015
Messages
61
Reaction score
82
First Language
English
Primarily Uses
JK MailSystem v2.41
Author: Pirobi and JK Software

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.

Features
A json file called Mail.json must be placed in your data folder. This file will contain the collection of messages that the plugin will interact with. The formatting for the json should be as follows:

Code:
[
{
"id":1,"sender":"Dad","subject":"Test","attachment":"0","trigger":"0",
"message":"Hello!"
},
{
"id":2,"sender":"Mom","subject":"Test2","attachment":"g100","trigger":"0",
"message":"Hi! Here's some money to help you out!"
},
{
"id":3,"sender":"Pirobi","subject":"Updates!","attachment":"i1","trigger":"c,30",
"message":"Here's a potion for your trouble!"
},
{
"id":4,"sender":"Dad","subject":"2.1!","attachment":"0","trigger":"0",flag:"s15",
"message":"Here's a message with a flag in it! It can only be deleted if switch 15 is ON"
}
]
NEW 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.

Tool - JKMailEditor!
The mail Editor is officially available for use! There is one included in the demo(see below). You can also download it here.

Be sure to save the json file as explained ABOVE!

The tool will auto-format your messages so that they will properly fit in the mail screen. If you don't use the tool, you will need to make sure your JSON files are properly escaped(place \n at the end of every line in your message).

Please provide any feedback or bugs from using the tool!

New in 2.2!
The Editor has been updated to let you insert a <br> or a <pg> into your message - just right click the message box and select the option you wish. NOTE: The cursor will always move to the beginning of the text after you insert a break - we are looking into this.

<br> - will indicate a new line
<pg> - will indicate a new page

New in 2.0.1!
The tool has been visually updated and is a little more versatile! Each message can be individually saved/reverted to its original state, and the entire collection can be reset to the original JSON version!

With this update we are also looking to provide an ability to check for plugin updates through the editor. That functionality is still experimental so please bear with us as we finalize it!

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!

Screenshots

Editor2.0.1.PNG MailScene.PNG

How to Use
Simply add the script file to the plugins folder, and add the plugin to the plugin list. SEE DEPENDENCIES BELOW. See the demo for more information on 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.

Dependencies
You will need to create a Test_Mail.json in your data folder in order to use the battle test. Looking into this for a future update so you don't need to make it.

Demo
JKMail Demo
JKMail Editor

Script
JKMail System Plugin

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 either a line break (<br>), 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. :p
- 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!)
- When right-clicking to insert a page/line break in the editor, the cursor will jump to the beginning after it has been added.

Release History
-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
 
Last edited:

Ghost of Christmas Kloe

Ghost of a Princess Seagull
Veteran
Joined
Nov 15, 2015
Messages
1,504
Reaction score
913
First Language
English
Primarily Uses
N/A
Wow! This is really cool and really easy to use! Thank you!


Is there a way to add an item which is only added into your inventory when the specific message is read by adding another bit to the .json? E.g

"id":1,sender":"Kate","subject":"Hiya","item":15,"message":"Here is that thing you wanted!"


Or if you didnt want an item attached:


"id":1,sender":"Kate","subject":"Sorry","item":0,"message":"I couldnt find that thing you wanted, sorry..."

I just thought that it's mail, and sometimes you can get things through the post!
 

Khayalan

Mapping-Guru
Veteran
Joined
Dec 21, 2015
Messages
50
Reaction score
27
First Language
German
Primarily Uses
Really Nice :)


I like the idea of @Kloe


But personally i would like that the User has to press the Accept-Button to get the Item or Gold :)
 

Ghost of Christmas Kloe

Ghost of a Princess Seagull
Veteran
Joined
Nov 15, 2015
Messages
1,504
Reaction score
913
First Language
English
Primarily Uses
N/A
Really Nice :)


I like the idea of @Kloe


But personally i would like that the User has to press the Accept-Button to get the Item or Gold :)
Well, I sorta meant that, as in you read it and press accept to get the item, not just get it by glacing over it!
 

TheDeadGPU

Warper
Member
Joined
Feb 16, 2016
Messages
1
Reaction score
0
First Language
English
Primarily Uses
Good Job @Pirobi the editor will be released soon when I have it fully debugged.
 

ThePotatoOfFire

8-bit Obsessed
Veteran
Joined
Jan 15, 2016
Messages
156
Reaction score
58
First Language
English
Primarily Uses
RMMV
Does there have to be a specific filename for the plugin?
 

Pirobi

Veteran
Veteran
Joined
Oct 25, 2015
Messages
61
Reaction score
82
First Language
English
Primarily Uses
@Kloe updated to version 1.1! Now has the ability to add an attachment to mail!


The Mail.json file must have this additional member in each mail entry:


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


~Other Updates/Fixes~

  • I stupidly forgot to save the state of the mailbox in the game, so it would wipe clean every time you load your data...Now, it doesn't do that!
  • Mail Editor is still on the way!
 

Pirobi

Veteran
Veteran
Joined
Oct 25, 2015
Messages
61
Reaction score
82
First Language
English
Primarily Uses
Update to 1.4!


New Feature - Multiple Mailboxes!


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


New Tool - JKMailEditor!


The mail Editor is officially available for use! There is one included in the demo(see below). You can also download it here.


Be sure to save the json file as explained ABOVE!


Please provide any feedback or bugs from using the tool!
 

Kenen

Veteran
Veteran
Joined
Apr 3, 2012
Messages
256
Reaction score
153
First Language
English
Primarily Uses
RMMV
Hi Pirobi, really enjoying this plugin. Found a super small bug:


case "a"://Armor
this._hasAttachment = true;
return $dataItems[num];


Should of course be $dataArmors[num];


Thanks for posting this!
 

Pirobi

Veteran
Veteran
Joined
Oct 25, 2015
Messages
61
Reaction score
82
First Language
English
Primarily Uses
Hi Pirobi, really enjoying this plugin. Found a super small bug:



case "a"://Armor
this._hasAttachment = true;
return $dataItems[num];


Should of course be $dataArmors[num];


Thanks for posting this!


Thanks for pointing it out! I updated the demo and code.
 

erestorpat

Villager
Member
Joined
Jan 16, 2016
Messages
17
Reaction score
1
First Language
french
I got to admit... I just LOVE your plugin!


It makes me wonder if it would be "possible" to use it as a base plugin for monetizing the game on mobile devices (like providing the player with unique key items he cannot find in the game that gives him access to secret dungeons or locked rooms for new characters, spells, etc.)


Trying to figure out how "OBB Files" works and how I could manage to edit the Mail.json to add a new message without deleting others and without giving access to other monetizing mail without having paid for it.
 

Pirobi

Veteran
Veteran
Joined
Oct 25, 2015
Messages
61
Reaction score
82
First Language
English
Primarily Uses
I got to admit... I just LOVE your plugin!


It makes me wonder if it would be "possible" to use it as a base plugin for monetizing the game on mobile devices (like providing the player with unique key items he cannot find in the game that gives him access to secret dungeons or locked rooms for new characters, spells, etc.)


Trying to figure out how "OBB Files" works and how I could manage to edit the Mail.json to add a new message without deleting others and without giving access to other monetizing mail without having paid for it.
So you mean like sending out new Mail.json files like dlc, containing the new messages? I don't know anything about mobile, but since I only save the mail that is in the mailbox, it might be possible to send out updates that add new messages to Mail.json. The master list of mail gets loaded when the game starts, so the new mail would be picked up, and you can then place checks (let's say all messages with ID greater than 50 are monetized). The actual system to purchase and have the mail system recognize this is unknown to me beyond making an extention that records which messages have been paid for by the user.
 

erestorpat

Villager
Member
Joined
Jan 16, 2016
Messages
17
Reaction score
1
First Language
french
So you mean like sending out new Mail.json files like dlc, containing the new messages? I don't know anything about mobile, but since I only save the mail that is in the mailbox, it might be possible to send out updates that add new messages to Mail.json. The master list of mail gets loaded when the game starts, so the new mail would be picked up, and you can then place checks (let's say all messages with ID greater than 50 are monetized). The actual system to purchase and have the mail system recognize this is unknown to me beyond making an extention that records which messages have been paid for by the user.
The mobile version (for example : Android) actually is an APK from the "www" folder when you export the game in Android/iOS so indeed, I guess it would be possible to manage the "read" or "unread" mails and, actually... if we do an OBB file (Android Expansion file) or an update file that is actually just the script to "add" or edit (in the case someone purchases the same pack over and over again) the mail should make it work I guess. :)  
 

solaris1111

Veteran
Veteran
Joined
Jan 1, 2014
Messages
115
Reaction score
19
First Language
French
Primarily Uses
When i start i battle test, it says : File missing data/Test_Mail.json


Weird.


EDIT: Ok i took the mail.json from your demo and copied it with that name Test_Mail.json and it fix it.
 
Last edited by a moderator:

Ghost of Christmas Kloe

Ghost of a Princess Seagull
Veteran
Joined
Nov 15, 2015
Messages
1,504
Reaction score
913
First Language
English
Primarily Uses
N/A
When i start i battle test, it says : File missing data/Test_Mail.json


Weird.
Yes, with Yanfly's scripts for some reason, scripts which use .json files like Gamus' Quests, a Test_ version is required for battle test. Just copy your Mail.json, and paste a second verson which you rename Test_Mail.json
 

Sakurahan01

Sakurahan
Veteran
Joined
May 4, 2016
Messages
31
Reaction score
5
First Language
English
Primarily Uses
@Pirobi


Wow this is amazing  I am so getting this Plugin. Thanks for sharing. I wonder if it would be possible to send mail back in the future :) xD this would be a grate system maniac for simulator games. xD example: you get a mail quest to send a person a packaged, you send it you get your reward and the mail deletes form the mail box :D so many possibility's ^_^
 
Last edited by a moderator:

Yoshifull

Veteran
Veteran
Joined
Oct 31, 2015
Messages
47
Reaction score
4
First Language
French
Primarily Uses
THat's a plugin I'd use for sure! Though there is the error that pops up when you have no mail in your mailbox, which crashes the game.


On another note, when you adjust the size of the game using a plugin, the mail window stays at the standard position...

Capture.PNG
 

Users Who Are Viewing This Thread (Users: 0, Guests: 1)

Latest Threads

Latest Posts

Latest Profile Posts

Writing out an idea for the No Travel Game Jam. I have a general plot and challenge written out, it's just a matter of filling the rest in and making it interesting.
A definite difficult time right now. How is everyone doing during this pandemic? I already have seen furloughs and layoffs.
Hollow 1977 wrote on Archeia's profile.
Hope you and your family are doing well during this difficult time. :)
My elderly neighbor whom I've been buying groceries for just got carried out of his home on a stretcher by guys with hazmat suits. Considering I've been his only point of contact for the past month it's probably safe to say my boss was right to tell me to stay home once I developed a mild cough after all.
Damn. All these new features to the forums. Takes some getting used to.

Forum statistics

Threads
95,642
Messages
930,674
Members
125,963
Latest member
highchloride
Top