Tutorial: Adding New Dialogue

From Stardew Modding Wiki
Jump to navigation Jump to search

Adding new dialog is easy with Content Patcher! This tutorial aims to walk you through the entire creation process of adding new dialogue for an existing NPC (Mayor Lewis). The general principles also apply for other dialogue mods, but you will need to think about your target file(s) depending on what kind of additions/changes you want to make.

If you would like to make a video based on this tutorial, you are welcome to do so but please edit the page to add a link to your video for users who prefer to learn that way. :)

Future infobox info: CopperSun, April 22 2021

Getting ready

  1. Install Smapi if you haven't already
  2. Install Content Patcher.
  3. Unpack the Stardew Valley xnb files so you can see how they work.
    1. Don't worry about "only needing one section." Just unpack the whole thing. It's quick, easy, and you'll want to reference more than you think.
    2. Make sure to poke around in Stardew Valley\Content (unpacked)\Characters\Dialogue
    3. More dialog can be found in Stardew Valley\Content (unpacked)\Data\Events and Stardew Valley\Content (unpacked)\Data\Festivals
  4. Get Notepad++, Visual Studio Code, or another text editing program designed for reading code. (You'll be using it for Json files.)

Finding Examples

Examples are really the key to understanding any mod or coding project. Fortunately, there are LOTS for you to look at!

  1. Download another dialog mod to see how it works.
    1. Canon-Friendly Dialogue Expansion is a very complete mod and shows how to use translations.
    2. Allie's Dialogue Expansion for Elliot shows lots of ways to add dialogue for a marriage candidate.
  2. To see how the mod is doing what it does, go into its folder in Stardew Valley\Mods and open up any of the files there. Start with content.json and then take a look at what else they included.
    1. This is where you'll want to use Notepad++ or whatever editor you have. Notepad is fine and will work, but won't show you matching brackets, highlight variable names, etc.
    2. To get a first taste at modding, you can change a line of dialog in one of these mods, load up Smapi, and see your new dialogue in action. If you're not comfortable doing that yet, though, read on.
  3. Look at Modding:Dialogue on the official wiki for formatting options.
    1. If you're brand-new to coding of any kind, think of this as a sort of dictionary. It's the place to see what "#$e#" means or how to put conditions on a certain line.
    2. Once you know what you're doing, you'll be amazed at all the ideas that will come to you as you read through the list.

Creating a Manifest

Now we're actually going to code! (Finally.)

Sample manifests from Modding:Modder Guide/APIs/Manifest. We'll be using the one for Content Patcher.
  1. First, create a new folder in Stardew Valley\Mods and name it whatever you want your mod to be called. "Test" is a perfectly fine name for now.
  2. In this folder, create two new files, "content.json" and "manifest.json"
    1. You can create these files any way that works for you. I usually right-click inside of the folder and choose "New->Text Document" and then rename the file including the extension. You could also create them by choosing "New" inside your text editing program of choice.
  3. Open manifest.json in your editing program. I'll be using Notepad++.
    1. We're starting with the Manifest because it is short, easy, and every mod needs one to run with Smapi.
  4. The manifest documentation on the official wiki is very clear and simple, so start by looking at that.
  5. See the part in "Basic Examples" that says "For a content pack"? That's what we're going to use. It has everything you need for your dialogue mod's manifest.
    {
  "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"
  }
}
    It's important to include the first { and last }. These brackets/braces (technically "curly braces" if you have a pedantic friend) tell Smapi where your file begins and ends. All json files utilized by SMAPI use them.
  6. Copy that text into your manifest.json file exactly as it appears.
  7. Change the appropriate text to be for your own mod.
    1. Version is what version of your mod you are on. Generally, you will start with 1.0, then if after you release your mod you have an update you might call that 1.1, and so on. The version number in the manifest is how Smapi can tell if your mod has a newer version available or not.
    2. Leave UpdateKeys empty for now (but make sure to keep the "[ ]"!). You can fill it in later with a key from Nexus or wherever you release your mod.
    3. It's very important to list any frameworks that your mod requires to run in the ContentPackFor section. We're using Content Patcher, so you can see that that is listed with its UniqueID of "Pathoschild.ContentPatcher".
  8. Save your file.
  9. Triple-check that you got all the right brackets and commas in the right places by uploading your manifest.json file at https://smapi.io/json
  10. Congrats! You just made your first json. That's programming! (Sort of.)

Adding Your Content

Now we're going to tell our mod what we want it to do. Because we're using Content Patcher, we only need to specify which parts of the game we want to change or add.

Here's the code we're going to use for your first dialogue mod. We're going to add a line to Lewis's dialogue file, delete a line, and change a line. When you make your own mods, you can add as many lines as you like to as many NPCs as you like - and even make more NPCs to add more dialogue to! :)

{

"Format": "1.20",   //This is the edition of Content Patcher needed to run your mod. When it doubt, use the latest edition.


"Changes": [    	//This is where you tell Content Patcher what changes to the game your mod is making
	
	{ 
	
	    "Action": "EditData",   //This tells CP you are EDITING the following data (not replacing it)
	    "Target": "Characters/Dialogue/Lewis",   //This tells CP which file you are editing

	    "Entries": {   //these are all the changes you want made
            
                    //add a line
			        "spring_4": "Hello @! I see you made a mod successfully!$h",  //Lewis will say hello and congratulate you on the 4th day of spring. @ is the player's name. $h means use his happy face
			
			        //delete a line
			        "summer_Sat": null, //Lewis will no longer say people seem happier on weekends on Saturdays in summer.
			
			        //change a line
			        "fall_Fri": "Modding is a crazy rabbit hole, isn't it?", //Lewis will say this instead of hoping things are going well for you on the farm on Fridays during fall.
			
			        },
	
	},		
]
			
}
  2. First, open up the content.json file you created earlier. Just like manifest.json, it needs to start with "{" and end with "}".
  3. Json files don't care about "white space" (blank spaces) unless they're inside quotation marks. Most people prefer to line up brackets visually so it's easy to see where they go.
  4. Any text following // is a "comment," which means it is not read by the program. You can put whatever comments you want in your code. It's a good idea to remind yourself what each section does!
    1. You can also use /* and */ to make large sections of your code a comment and invisible to Smapi.
  5. The first line after the first bracket is "Format": "1.20",
    1. Format means what version of Content Patcher is required to run your mod. When in doubt, use the latest version of CP. You can see what it is by checking NexusMods or wherever else you downloaded Content Patcher from in the first place.
    2. See the quotation marks and the comma? Those are Very Important. They're used to make sure the json file is read correctly by Smapi. Don't leave them out!
  6. Next we have "Changes": [
    1. This is the heart of our content.json file. We are telling Smapi that we have the following changes to make to the code.
    2. See that square bracket? That's because what goes in Changes is technically an array. You may remember arrays from math class. In this case, just remember that you need a [ at the beginning and a ] at the very end to close your array and tell Smapi you're done listing your changes.
  7. Changes is followed by a single {.
    1. This means we're about to specify a change (or a "patch"), and everything inside this curly brace goes with this specific change we want to make. It will need to be closed and followed by a comma before we can add another change later.
  8. "Action": "EditData",
    1. For this change, we are going to edit some existing data. Simple. :)
    2. Once you get comfortable making mods, you might want to use other fun actions like "Load" or "EditImage".
  9. "Target": "Characters/Dialogue/Lewis",
    1. This line is Very Important. It tells Smapi exactly what data we're planning to edit. In this case, we are going to edit Lewis's main ialogue file. If you followed the instructions above and unpacked the xnb files, you can see this file at Stardew Valley\Content (unpacked)\Characters\Dialogue\Lewis.json. See how the target matches the location? It just leaves off the ".json" in the file name.
    2. Any change you make must tell Smapi exactly which file to change, and must match the file name and folder path exactly. This means your capitalization and spacing must match.
  10. "Entries": {
    1. These are all the changes we are going to make to this specific file right now. Once again, the { means that we can have a long list if we want and we must use a } to tell Smapi where our list of entries ends.
  11. "spring_4": "Hello @! I see you made a mod successfully!$h",
    1. Woah! Suddenly we've got actual dialogue in our dialogue mod!
    2. Each of our entries has two parts, a key and a value. The key here is "spring_4". The value is "Hello @! I see you made a mod successfully!$h".
    3. There are lots of ways you can choose your key to create dialogue in Stardew Valley. In this case, we are saying that on day 4 of Spring (any year), Mayor Lewis should say this text. More keys can be found at Modding:Dialogue.
    4. In our text, we've got a couple other neat things happening. @ is the player's name. So if the player is named Buttercup, this dialogue will display to them as "Hello Buttercup! I see you made a mod successfully!"
    5. At the end of the line we have $h. This is to tell Smapi to display Lewis's happy portrait. A portrait command must always come at the end of the line just before the last quotation mark OR before a # sign, which signals a break in the dialog. More portrait commands can be found at Modding:Dialogue.
    6. Because the key "spring_4" does not already exist in Lewis.json (his main dialogue file) we are adding this key. Content Patcher will figure this out automatically and you do not need to do anything special to tell it this is a new line for Lewis.
  12. "summer_Sat": null,
    1. Sometimes you may want to delete a line of dialogue that a character has. You can do this by setting the corresponding key to "null".
    2. In Lewis.json, this line is "summer_Sat": "Everyone seems a little happier on the weekends, don't you think?#$e#I'm on the job seven days a week, though.",
    3. If you set a key to null but that key doesn't exist in the file you are targeting, nothing happens.
    4. This key corresponds to Saturdays in summer (any year). Again, more keys can be found at Modding:Dialogue.
  13. "fall_Fri": "Modding is a crazy rabbit hole, isn't it?",
    1. We are changing an existing line here.
    2. In Lewis.json, this line says "fall_Fri": "I hope things are going well for you on the farm.",
    3. Now when you talk to Lewis on a Friday in fall, he will instead say "Modding is a crazy rabbit hole, isn't it?",
  14. },
    1. We're done with our entries for this change to Lewis.json, so we need to close our braces so Smapi knows that we're done.
    2. The comma allows us to add more entries after this one. You don't need it if it's the last one on the list (and usually it will be in this context), but it won't cause any problems if it's there. Usually it's easier to just always have the comma.
  15. },
    1. Then we have another closing brace and comma. This one is telling Smapi that we're done with this particular change.
    2. If you wanted to edit more than one file (perhaps you also have new dialogue for Marnie in your mod), you would add that after this closing brace. You would need a new open brace and specify your next action, target, and entries. You can add as many of these changes as you want. Just make sure each is contained in its own pair of { } and there is a comma after each closing brace.
  16. ]
    1. This is the closing bracket for our Changes array. You may remember it from step 5.
  17. }
    1. And last, we have one more closing brace. This one is to tell Smapi that our json file has come to an end. Don't forget it!
  18. Hit save on your file and use https://smapi.io/json to make sure you've got all your brackets, braces, and commas right.
    1. If you copy-pasted this code exactly, you will get two "errors".
    2. The first "error" is that Content Patcher has come out with a new version since this code was written. This is okay. You can leave it the way it is because nothing in this code requires anything special from the latest version of CP.
      1. This is a good time to note that these tools can help you, but they can't think for you.
    3. The second "error" is that we are setting a key to "null" where it expects a string (a string is text in quotation marks). Again, this is okay. Null is a special value that means "absolutely nothing."
  19. Your mod is now ready to run! Load up Smapi, talk to Lewis, and see your changes!
    1. If you want to quickly see if your dialogue is working for a certain day or other conditions, you can use smapi debug commands. To see a list, type "help" in the smapi console while it is running.
      1. The Smapi console is that window that's running with all the text in it while you play Stardew Valley. You won't see anywhere to type, but that's okay. Just click on that window and type help. It'll work.
    2. To change the day to Fall 5 and see the new Fall Friday dialogue, you can type "world_setseason fall", hit enter, then type "world_setday 5"
      1. Doing this can mess up your game if you save (sleep) after doing it, so be forewarned.
      2. Testing this way may cause you to miss other conditions that might affect your mod.
      3. It's still pretty darn handy. :)
  20. That's it! You've made your first mod and seen it in action!

What's next?

There are a LOT of fun things you can do modding Stardew Valley just with dialogue. This tutorial barely scratches the surface. We didn't even cover using #$b# and #$e# to make breaks in conversation! The best advice is, as always, to look at the original code and other mods for ideas, then play around in your mod and see what you can do. Have fun!

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. :)

Retrieved from "https://stardewmodding.wiki.gg/index.php?title=Tutorial:_Adding_New_Dialogue&oldid=4008"