Tutorial: Sending a Letter (Content Patcher)

It's really, really, really easy to send a letter in Stardew Valley thanks to Content Patcher. In fact, it's so easy it's usually just bundled into the information about events, and it's hard to find a mod that just sends mail - usually the letters are part of a mod for more dialog, events, getting recipes, new NPCs, etc. But today, we're going to make two simple pieces of junk mail to spam the farmer with.

Note: This tutorial will assume you are already familiar with some modding basics, like making sure to have Smapi installed and how a manifest works. If you would like a tutorial using Content Patcher that goes over every single step, see Adding New Dialogue.

Future infobox info: CopperSun, May 7, 2021

You can also use Mail Framework Mod to send mail.

Finding Examples

Examples are really the key to understanding any mod or coding project. Fortunately, mail is used in a lot of mods so there are lots of examples out there to look at. Unfortunately, it's usually buried in with a bunch of other code that you might not understand yet.

The code to send mail will be found inside content.json in whichever mod you're looking at. Joja Immersion has some examples, but you'll have to scroll to the bottom of the file to find them.

The best examples are going to be the ones from the original game code.

• The Vanilla letters can be found in Stardew Valley\Content (unpacked)\Data\mail.json
• The code to trigger the sending of these letters can be found in Stardew Valley\Content (unpacked)\Data\Events\Farm.json

Creating a Manifest

We'll be using the standard Content Patcher manifest for our mod. Sample taken from the official wiki.

{
  "Name": "Your Project Name",
  "Author": "your name",
  "Version": "1.0.0",
  "Description": "One or two sentences about the mod.",
  "UniqueID": "YourName.YourProjectName",
  "UpdateKeys": [],
  "ContentPackFor": {
    "UniqueID": "Pathoschild.ContentPatcher"
  }
}

Creating a Letter

There are two main parts to sending a letter to the player. The first, of course, is creating the letter, so let's do that.

1. Inside your mod folder, in the same place you put your manifest.json, create a new file called content.json.
2. In content.json, put in your usual opening and closing braces, the format, and your changes array. (If you don't remember what these are, see Adding New Dialogue.)
3. Inside of your changes array, add this code:

   {
       "Action": "EditData",
       "Target": "data/mail",
   		
       "Entries": {
   		"junk_mail_1": "@,^^Why survive when you could THRIVE?^Thrive with Joja Cola! Stop by your local JojaMart today for a sip of pure blue refreshment![#]Joja Cola Ad",
   	
   		"junk_mail_2": "Fresh vegetables are the best way to live a healthier, longer life!^Visit Pierre's for iridium-quality veggies that'll have your doctor asking YOU for YOUR secret![#]Vegetable Ad",
   	}
   },
   

4. This code tells Content Patcher that we are going to edit the data located at data/mail. That's the mail.json file you should have looked at earlier.
5. We are adding two entries to the list of letters stored in mail.json, junk_mail_1 and junk_mail_2. We can call our letters anything we like, but as is always the case our keys must be unique. (Remember that jsons use key and value pairs; the key here is "junk_mail_1" and the value is "@,^^Why survive....") If your mod adds a letter with the same key as another mod's letter, you will get errors.
6. Letters have much less flexibility than dialogue. You can still use @ to insert the player's name, but placeholders that use $ will not work.
7. The ^ is a line break. You can have multiple in a row if you want extra space between lines.
8. If our junk mail was coming with a free gift, we would put that at the end of the letter text and before the [#]. See the official wiki for options.
9. [#] means we're done with our letter text. The part after it is what the letter will be named in the collections tab of the player.
10. Wow, that was easy! Now how do we send these?

Sending a Letter

Sending a letter is considered an event by the game code unless it is sent via certain circumstances like as part of another event or the letter is set to be sent on a specific day. In Stardew Valley, the code for each event is stored in a json file corresponding to where that event takes place. Sending letters happens on the farm (not the farmhouse!), so we'll be adding our entries to Farm.json in the events folder.

1. In the same content.json file as you were just editing, add this code. It doesn't matter if it is before or after your code for adding the letters.

   {
   	"Action": "EditData",
   	"Target": "Data/Events/Farm",
   
   	"Entries": {
   		"012344667/r .3/d Mon Tue Wed Thu Fri/x junk_mail_1": "null",
   		"012344668/m 15000/x junk_mail_2": "null",			
   	}
   },
   

2. Unlike our letters, here it's the key that is much more interesting, because our value is just null.
3. The beginning number is the event id and must be unique.
   1. From the official wiki: "Event IDs are a max of 10 digits, with a maximum value of 2147483647 (based on the game coding). You may use any ID for testing BUT When you are ready to publish, you are recommended to use the four digit mod ID you get from Nexus (found in the mod page URL) as the prefix instead."
4. After the event ID comes our list of conditions for sending our junk mail. These conditions are specified exactly the same way they are for all events and you can look at the list on the official wiki.
   1. For junk_mail_1, we have specified a random chance of 30% and that it not be Monday, Tuesday, Wednesday, Thursday, or Friday. (Why the code defaults to which days it is not is ????)
   2. For junk_mail_2, our condition is that the player have earned at least 15,000g.
5. The last piece is x junk_mail_1. This is special to null events used to send letters. It tells the game "just send this letter and don't do anything else."
6. Because our event just sends a letter and we already took care of that part with x, our event doesn't need to be defined in terms of who moves where or says what. So we can just put "null" and call it done.
7. Later on, we can use these letters themselves as conditions, like if the player has seen junk_mail_1, Pierre complains about Joja's mail littering the town. In this context, junk_mail_1 has become a mail flag. There are a bunch of these in the original code associated with all sorts of events and conditions. You usually aren't aware of them because the letters themselves are null and thus don't show up in the player's mailbox.
8. Run content.json and manifest.json through https://smapi.io/json just to double-check you've got all your braces and commas in the right place (always a bigger concern when you're copy-pasting pieces of code), and then you're done!

What's next?

Per usual, this tutorial only scratched the surface of what can be accomplished with mail and mail flags. Reading through Modding:Mail Data and Modding:Event Data on the official wiki will give you lots of ideas for ways to incorporate mail into your next mod. Then again, why not create a mod full of nothing but letters for the player? After all, everyone likes getting mail. :)

PS: Interesting in writing a tutorial for this wiki? We'd love to have you! No qualifications are needed. Just create a new page, call it "Tutorial: Doing a Thing" (name as appropriate), and start sharing your knowledge. :)