Getting Started

So you want to make a mod for Stardew Valley. That's great, welcome to the modding community! But where should you start?

First, ask yourself: do I know how to code? If the answer is yes, you can head right over to the official wiki and start poking around. We also have a stub of a page with a couple other resources.

If you don't know how to code, that's okay! You can still make a Stardew Valley mod and it will be easier than you think. There are several mods that make it easy for anyone to add content to the game. The best known are Content Patcher and Json Assets. If you've previously installed any mods these were probably requirements for at least one. Just make sure you're using a decent program (and not just Notepad)! You'll find some suggestions here.

Note: No matter what project you choose to start, you are probably going to discover that you missed a bracket, didn't add enough commas, capitalized something you shouldn't have, etc. This happens to every programmer ever. Fortunately, there's a tool to help you check your brackets and commas before you spend ages waiting for smapi to load: smapi.io/json. And keep in mind that that dopamine hit when you get everything working is going to be so great.

Read on for some additional tips on getting started with making mods!

Pick an easy first project

Tutorial: Making a New Crop

Tutorial: Adding New Dialogue

Feel free to peruse the Tutorials category for other goodies!

C# is optional!

Don't know or don't want to know C# coding? No problem! We have framework mods, which are already written in C#, that you can make content packs for. The content packs involve JSON scripting, which can be much easier to learn. You can check out an explanation of existing content pack frameworks on the main wiki here.

• You could also commission C# modders! Here's a list of mod authors that take commissions.

Know your audience

It's important to know your audience. Are you making a mod that you want to use? Are you filling a niche that only some people will be interested in? Or are you trying to attract a wide audience? The obvious advice is to make a mod that you want to use, so that you're happy with it no matter what others may say. But if you're considering other people the target audience, the features you include (or don't include) should be tailored to that audience. We have a page elaborating on mod user preferences and you, the mod author.

Respect mod author permissions

The modding community cares a lot about permissions. Personal use of assets is ok, but if you intend to publish your mod to the public, get permission from the mod authors of the assets you used BEFORE uploading. It's seen as impolite to take the attitude of "well I'll upload it and if the mod author complains, I'll take it down". Asking for forgiveness rather than permission is frowned upon. Some mod authors might say you don't have to ask on their permissions info, so you can use their assets, but it's still good practice to at least give them a heads-up, and it could be as simple as a comment on the mod page. Here's additional reading on unofficial updates.

2 cakes: my idea is already a mod

You can read about the origin of 2 cakes here. In the context of modding, we mean that you can make your mod idea real even if another similar mod already exists, because you're adding your own take on the idea. So if you have your own spin on it, or different options or features, then that's a-ok! For example, there are multiple dialog mods for the same characters. They don't all have the same tone or concepts. This also gives mod users / players more options to choose from, which we all like!

To be clear: 2 cakes does not mean that you can just straight up copy someone else's mod or ideas. The whole point is if you have a mod idea that already exists, you can still make your version, yours, with unique features.

Experiment with modding!

There are basically no consequences for trying something out in writing a mod, so feel free to go rogue! Your first mod doesn't need to be perfect. You might get errors or something else going wrong, and that's ok! Part of the process of creating mods involves troubleshooting. Quick links on troubleshooting here.

For content packs at least, you can quit the day without saving if something is broken, and if for some reason you edited vanilla (base game) files, 1) XNB modding is no bueno, additional reading on XNB mods here, and 2) you can reset / validate your game files and restore whatever files got messed up! C# people might not be able to throw caution to the wind if what they're doing is changing the save file.

Do some reading

When you're getting started with modding, you probably have a lot of questions. Check the documentation before asking. What does "documentation" mean? Mod descriptions, any additional "guides for mod authors", the official wiki, and this wiki. Unpack your game files and poke at those. Check the great ID spreadsheet, which has a lot of useful (if possibly outdated) information. If your mod idea is something similar to an existing mod, or you're making a content pack like for Json Assets or something else, download an existing mod and take a look at its structure. Look at how the folders and files are set up, open up the manifest.json, content.json, etc. and check how they are written.

So many wikis; which are correct?

The official wiki got a new URL, but the old one still shows up on search results. Make sure you're on the new one and not the old one. The old wiki is read-only, stardewcommunitywiki.com. You want to avoid those links if they pop up and only go to stardewvalleywiki.com, which is the new domain that gets updated. There is a notice on the old wiki at the top that says it's read-only, but it's small and fairly easy to miss. Our wiki, knows as the Stardew Modding wiki, got a new URL in June 2023 as well; you can read more about that here, including how to convert old links to the new links (it's quick and easy).

Ok I have the correct wiki, how do I search?

Atravita's tip for searching the official wiki using the search box in it is: you need to use the Advanced search to search the whole wiki and check the box for Modding. By default, it does not search the modding pages. Lumina's suggestion with the search box is: type modding:yoursearch.

LenneDalben's preferred method is to to google stardew valley X modding wiki, where X can be maps, NPC, schedule, etc. That usually pulls up the correct page. LenneDalben also has a list of pages they've created or edited on their user page, which also happen to be the ones LenneDalben frequents. You can also just bookmark useful pages to your browser for quick reference.

Creating content packs: so many missed commas and parentheses / brackets!

First, award yourself a badge. Second: content pack modders, the json validator is your best friend. If you forget to check your json files on it before testing (or just don't want to have this extra step), LenneDalben HIGHLY encourages you to set up the schema checker. That is a built-in json validator that checks your files as you write your mod. You don't have to suffer through forgetting commas and parentheses and hunting them down in the code!

I want to make an NPC!

Hurray! Note that this is a big project. There are so many aspects to modding an NPC: dialog, schedules, events, art (portraits and sprites), maybe even maps if you're adding a new location for your NPC's home, or just editing an existing map for your NPC's home. This is not recommended as your first modding project, because it's so substantial and complex that it can be overwhelming. If you're feeling ready to tackle it, there are a couple of useful links to get you started:

• Overview on NPC data, including links to other useful wiki pages
• Lemurkat's tutorial series
• Tutorial: Adding New Dialogue
• How to make pixel art, relevant for portraits and sprites
• A tutorial on a simple way to add integration / immersion with other mods, and even vanilla as well (Conversation Topics)
• Tips for Making Events from a Novice by LenneDalben
• For maps, we have video tutorials here and here, as well as a written tutorial here
• The "textbook" of map modding is the map modding wiki page, but it can be difficult to look through. Ctrl+F is your friend to search the page
• Feel free to peruse the Tutorials category for other goodies!

Other useful things to note for NPC modding:

• There is a spreadsheet with festival placements. This can be useful in deciding where to place your NPC at a festival, to attempt to avoid overlap. You can also add your NPC locations on there, but be sure to check the instructions / guidance on the spreadsheet. Note that the spreadsheet has been known to be glitchy and sometimes data is lost, so it may be challenging to make sure the information is updated.
• You can use internal names for your NPC that are different from the display name, to avoid any conflicts with someone with a similarly-named character. Please note that from a marketing standpoint, characters with same names can cause confusion for players, and they may not know which character is being talked about, so you may want to consider changing your NPC's name if it’s already in use.
• With such limited space around the Valley, deciding where to place your NPC can be quite the Herculean task if you're trying to avoid conflicts with other mods. You may want to consider placing them outside the Valley, in a place that's accessible by bus or train (using the Bus Locations or Train Station frameworks). Of course, the drawback to this is that the bus and railroad are not immediately available in the game. If you really want your NPC to be part of Pelican Town, but aren't sure if the spot you're thinking of is free, you might want to check in with mod users on the main SDV discord. Players will often be able to tell you if that spot is already occupied. (Also note, that sometimes conflicts are unavoidable and it may just be the case that not everyone can use your mod at the same time as another one).

Art is HARD

If you just can't even with art, no matter how hard you try, commissioning is always an option!

Shop Names

Similar to NPCs, shops created using Shop Tile Framework need to have unique internal names, otherwise SMAPI won't load either of them! So make sure you give your shop a name that is unlikely to be in use already.

I have an idea and can't / won't make it a mod OR I want to mod but I don't have an idea!

Check out the mod ideas list! Here, anyone can write up an idea that they would like to see be made into a mod. It's more of a "message bottle" than a "suggestion box" or "request list". Someone may come by, checking for ideas, and decide to make one of the mods on that list. That someone could be you! Or you could be the person who writes an idea that later inspires someone else.

What are all these acronyms / abbreviations?

The modding community is a fan of acronyms and abbreviations; see a list here.

Something Went Terribly Wrong (halp)

If Something Went Terribly Wrong while testing your mod, do not fret! You can check out some debugging / troubleshooting tips, and if you are still stuck, ask for help!