Mod Making: Adding New Areas

I’ve been asked to assist with this a few times recently, so thought it well worth writing a blog post about. Today I shall be sharing how to add new maps into the game.

Firstly: for what purpose are you creating a new map? If it is for custom NPC housing, consider this question: Does my character need this much space? If you are creating a family, or perhaps an eccentric goat-herder, then perhaps, yes, your character does need a fair amount of space. If it is just a single person who will spend most of them time wandering around the other maps, then I would suggest that you look into the Boarding House mod instead. Why? Because patching the map can cause significant lag for the user (when I was running 94 custom NPCs with multiple patches and a recolor, my game would “hang” for a good 5-10 seconds when I entered the town map for the first time – and that was with a dedicated gaming laptop. Back with my desktop it tried to crash regularly). Also, players need more than one reason to wander off the familiar and into new terrain on a regular basis. It’s not enough that your NPC might be hanging out there!

Reasons to visit:

  • Multiple new NPCs, possibly even a village!
  • A shop
  • Interesting forage
  • Good fishing
  • Puzzles or a mystery to solve

Right, so you’ve decided you really need to make this map exist… now it’s a two step process and will require two framework mods: TMXL Toolkit and Content Patcher. Also, you will need the program Tiled.

(It is possible to do both these things with TMXL alone, but it cannot add some of the more interesting features I will talk about).

Step One: Make your map. Use an existing one as your base. This will often bring with it animated tiles, which is much easier than doing it yourself – believe me!

East Scarpe in its raw form. The red dots I applied to the tilesheet png so I could see which water tiles were impassable to the farmer. They do not appear in the actual game! The other red tiles are the “paths” layer: these add items generated by the game’s code such as berry bushes and choppable trees.

You need TMXL toolkit to load custom maps. It, paired with PYTK, connects them into the game and allows NPCs to pave around and into and out of them.

A screenshot of the map in Tiled. Under “Custom Properties” you will see a list of the map’s properties.

DayTiles: These are the coordinates for the lamps during the day, to make sure it shows their “off” sprite.

Format: <layer> <x coordinate> <Y coordinate> <tile index number>

Light: This sets a circlet of light around the tile coordinates, actually making the lights appear to glow at night (the light itself is always one, you just cannot see it during daylight levels)

Format: <X coordinate (of the center)> <Y coordinate (of the center)> <Light type>

NightTiles: Changes the lamp sprite to the “on” sprite after dark.

Outdoors: T = the area is outdoors and thus subject to environmental effects such as rain.

Warp: The exit warp, in the format <coordinates of exit on this map> <new Map to teleport character to> <coordinates for them to land on>

Note: If you have an additional space in the Day/NightTiles or forget to include a warp, you will get an error message when you load the map in. I believe it is “Input String was not in the correct format”.

Other Map Properties exist on current maps, including ones pertaining to fish and archaeology spots, but many of these are not implemented in game.

To load the map into the game, the TMXL code is simple:

"addMaps": [ 
{ "name": "EastScarpe",
"file": "assets/EastScarpeRevised.tmx"

And that is all it takes to get your map loading into the game: but there’s only one problem!

How will your characters get there?

Next post, we shall look into adding the patches.

NPC Creation: Events (part 2)

Okay! So first and foremost… Cameron isn’t going to mysteriously suddenly appear in town, she’s going to arrive by bus, and she’s going to move into the Boarding House while she completes her research.

This allows scope for another event, the Introduction (0 heart) event.

Now, here’s the tricky bit… We could have her arrive by bus, but what happens if the farmer leaves the farm by the north or south entrance? Then the farmer could run into her before seeing the introduction event! And if we set the introduction event to happen before she actually spawns in town, she’s going to be invisible for the remainder of the day!

Easiest option? Have her turn up on the farmer’s doorstep. There is still a chance the player might leave their house by another route (ie: warp totem), but most players will walk out their front door!

Here’s the code to set up the event:

{   “Action”: “EditData”, 
    “Target”: “Data/Events/Farm”,
    “Entries”:{ ….

Now we need an ID# for this event. Since a lot of custom NPCs and other mods exist, it’s important that you choose a unique number: 7 to 8 digits is recommended. It is recommended to use your 4-digit Nexus ID followed by 3-4 other numbers. NOTE THESE DOWN SOMEWHERE!

Since Jasper’s mod is “5599” and Cameron will likely be an extension of that, let’s start with “55991001”.

You can add other pre-conditions too, but overall, I think it’s probably safest to have this event trigger No Matter What.


Next step is to set up your scene. Farm events are almost always the same. In fact, changing the positions of the actors actually won’t work and they will revert to the below. General set-up goes:

“music/viewport/actors’ positions/skippable/pause 500/<event continues>”

The list of musical tracks can be found on the Great ID Spreadsheet, and you can play them through the links there, or by typing “debug music <trackname>” into the Smapi console (it does not like spaces though). You can also use “continue” or “none” but you cannot leave it blank.

Viewport is the co-ordinates the screen will be centered on.

“55991001”: “continue/64 15/farmer 64 16 2 Peasbody 64 18 0/skippable/pause 1500/…”

(“skippable” should be included in most scenes, because it means if they crash, the player will be able to escape from them. You do not want the player to have to restart the game. The only time you would not include it would be: if the character had to give the player something, the information was essential, or you needed the scene to end with the character invisible. Non skippable scenes on the doorstep are generally OK, since the characters don’t move and they tend to be short.)

The next part I like to think of as running a play: you get to determine which way the character’s will face, what they will say, and what emotions they will display.

…speak Peasbody \”Oh hi there! I was wondering if you might be able to help me?#$b#I’ve just arrived from Zuzu City, and I’m afraid I’m lost.\”/emote farmer 8/pause 1000/speak Peasbody \”Oh, sorry! My name’s Peasbody, Professor Cameron Peasbody.$1#$b#I was wondering if you’d be able to point me in the direction of the museum?$2\”/pause 500/emote farmer 16/pause 1000/…

(emote 8 = ?, emote 16 = !)

Why this reaction? Because Cameron isn’t going to load into the game until the farmer knows their name and has already drawn some conclusions about them, possibly negative conclusions.

So the next option should be a choice: to direct Cameron to the museum, or to put her in her place. For this we are going to use a question fork. There are two ways to do this, but this is the easiest, so we’ll start here.

…question fork0 \”…#Follow the path into town, it’s just over the stream.#You should go back to Zuzu. We don’t want you here.\”/fork HelpCameron/pause 500/emote Peasbody 60/pause 1500/speak Peasbody \”I thought village folk were meant to be friendly.$5\”/pause 500/emote farmer 12/pause 2500/faceDirection farmer 0/warp farmer -100 -100/viewport 64 15/playSound doorClose/pause 1000/emote Peasbody 28/pause 500/faceDirection Peasbody 2/speak Peasbody \”Okay… I suppose I deserved that.$2#$b#But…$2\”/pause 1000/faceDirection Peasbody 0/pause 1500/speak Peasbody \”This might be harder than I thought…$2\”/pause 2000/end”,

Now, we need the alternate fork for if you do choose to not let your prejudice against Peasbody influence you (or perhaps you are just naturally helpful). This begins with the Key “HelpCameron”:

“HelpCameron”: “pause 500/speak Peasbody \”Thanks! I hope to see you around sometime. I might be here for a while.\”/pause 500/faceDirection Peasbody 2/pause 1500/faceeDirection Peasbody 0/speak Peasbody \”Oh, hey, I hear there’s a saloon in town. We could meet up for a drink there sometime.#$b#If you wanted to, that is?$2\”/pause 500/emote farmer 40/pause 1500/speak Peasbody \”Hey, no need to answer now. Don’t be a stranger, okay? Later!$1\”/pause 1500/faceDirection Peasbody 2/pause 1500/end”

Now, how to test your event? For the above, it’s quite easy – all I have to do is exit the house. For other events, however, the easiest way to test them is to enter

debug ebi 55991001

into your Smapi console (that’s the black box that pops up when you load a modded game and shows what the mods are doing). For this to work, the mod Console Commands must be on your list. It’s added automatically with Smapi, so if you don’t have it, just install Smapi again.

There’s another neat debug command too. If you need to make adjustments to your event because it crashes, or the character walks in the wrong direction, or whatever, you can fix the code, save the file, and enter this into your Smapi console:

patch reload <unique ID>

Unique ID being what your mod is called in the manifest. Standard set up for these is: ModCreator Name.Mod Name(.Framework).

So: LemurKat.CameronNPC

This will reload the mod, and allow you to replay the event with your adjustments. Note that really bad crashes (lots of red text) will require a complete restart, and sometimes things may behalf a little differently after a patch reload (specifically, I’ve found, strings dialogue).

But what if we wanted the way you chose to answer the question to influence the way Peasbody acts towards you? In the next post, we will look at a slightly more complicated way to code a question fork, one that can be used to influence friendship, and also to flavor future dialogue.

Trouble shooting:

Events can require a lot of debugging! Before testing your event, I recommend you enable Debug Mode, this provides a pop up cursor box in which you can watch the steps of the event, and if it crashes, you can determine approximately where.

Common errors:

  • “Input string was not in the correct format”: Often means you’ve made an error with your actors’ positions, usually an additional space or you’ve forgotten to include the direction for the character to face. Can also mean extra space, you’re missing part of the command, or another typo (ie, spelt Elliott’s name wrong).
  • Invalid Command: <something>“: there’s something wrong with that line. Whether it’s that you’ve entered a musical track that doesn’t exist, or written a command wrong.

There are numerous ways to make a mistake in an event, and the more events you make, the smoother the first play through will get.

The SDV Discord is very helpful with finding the errors, so don’t be afraid to share. A lot of us love problem solving (and you can PM me there if you like: @lemurkat#3754)

NPC Creation: Events (part 1)

Events are one of the reasons many of us befriend NPCs: the chance to uncover the character’s story, to potentially influence the choices they make or the path they choose. Potentially, also, to learn new skills or recipes.

Writing events is a challenge and, whilst I might touch on how to do this later, a good reference for the mechanics is here:

The mechanics are one thing, but how do you determine what to reveal in an event, or what it will involve?

In the core game, Non-datable NPCs normally only have a couple of events, sometimes not even that! Datable NPCs, on the other hand, are more interesting.

Here’s an analysis of the basic structure:

(Note that this is my observations, and not rules, it’s just a useful guideline to decide what sort of interactions your character may have with the farmer).

2 hearts : a sort of “getting to know them better” kind of event, they reach out to the farmer, allowing you a little glimpse into their personality. (ie: Shane on the dock, Alex boosting, Haley and Emily bickering).

4 hearts: The farmer gets a deeper hint, possibly of some inner turbulence or that their original perception isn’t completely accurate. (ie: Alex talking to Dusty, Shane on the floor).

6 hearts: I like to think of this as the “turning point” event. (Possibly biased because of Shane’s which is arguably one of the most powerful events in the game). Perhaps your character’s flaws could catch up with them, or the farmer have a solid opportunity to make a difference in their life.

8 hearts: You’re now best friends. The character may bare their soul, or you may get an inkling of the manner in which the farmer has really influenced their life. Generally positive, although some (ie: Alex’s) can pack a fairly emotional punch.

10 hearts: Typically, this one seems to be a date or something with romantic connotations (Abigail’s being the exception). Try and make it authentic to your character. Can end in a kiss. If you choose to go this route, it’s advisable to give the farmer a choice of whether to kiss or not.

If you’re writing a not-datable character, but wanted to do a 10-heart scene, aim for something powerful: possibly the character choosing to take on a new direction in life. Consider this the 14-heart event for non-datables.

Also note that some players have no inclination to date everyone, but may want to see your event anyway. If possible, a platonic version of this event would make a nice finale for the story-arc. Platonic mods already exist, but you could also add an option to change your character’s datability status (NONE of my characters currently start datable for various reasons).

Post Marriage Events

12 hearts: not a feature of the core game, but some creators do like to give their character a 12 heart event. You could choose something romantic, or an activity that you feel the character might like to share with their spouse. It could be a heartfelt conversation on what the farmer means to them.

14 hearts: The grand finale! This event should indicate how the character has grown in themselves, due to the influence of the farmer. The character should be the one who drives the event, not the farmer. They shouldn’t be a passive player (ie: imagine if for Haley’s 14-heart event the farmer suggested the idea to Haley, not vice versa? It would completely change the message). Personally, I like 14 heart events to permanently change the world in some way, either in the character’s behavior, or by adding a new feature to the town. But this is, of course, completely optional.

Now… Cameron… what should we show in her 2 heart event? She’s come to Pelican Town for a reason… and a good way to start would be by revealing that reason…

… or possibly TWO reasons. One could be to uncover or research a rare artifact that she has heard about. The other? An attempt to disrupt the life of someone she once dated.

(This could get awkward, I’m happily married to Jasper in my main game! Still, I have been pondering polyamory options…)

For the 2 heart event we will focus on the artifact … we’ll acknowledge her feelings for Jasper in the 4 heart one.

(Also, for complete immersion, when I release Cameron, it will likely be in tandem with certain events in Jasper’s story line, but let’s lay the basics down first).

So what artifact is she here for? What secret is she trying to unearth? Something to ponder on before we move on to Step 2: Writing the event.

NPC Creation: Home

Tired of your NPC arbitarily spawning somewhere on the map? Want to give them a bed to lie in? It’s time to make them a home!

There are several options for this:

  • You can move them in with existing NPCs
  • You can move them into custom NPC accommodation
  • You can design your own house and garden.

But let’s start simple! By creating a room.

The easiest way to give a custom NPC a room is to install the Boarding House.

To create a map you will need:

  1. Tiled
  2. A XNB unpacking program, like xnbcli

Tiled is not the most intuitive program to use. The first thing you will need to do once you’ve downloaded it is to enable it to accept Tbin files.

Tbin files consist of two parts: the tbin file itself, and tilesheets/tilesets (PNGs with the tiles on them). These need to be stored in the same folder as the Tbin files.

The wiki explains the basics: (you can skimread the C# part, but do read everything under ‘If you’re using Tiled’).

And do ask questions on the Discord!

Always start with an existing map. That way you have the layers (as seen top right) and should have at least two tilesets (likely Indoors and Paths). It also gives you a good basis for creating your own rooms.

Since I am moving Cameron into the Boarding House, I have loaded their map into Tiled.

Each room in the boarding house is the same size: 9 x 7 tiles. The only significant difference is that some are north of the hallway, others are south and this affects the positioning of the doorway.

Top right shows the layers. There are two sorts: Objects and Tiles. For part on of this tutorial we will be focusing on the Tiles. They’re indicated with the blue 3×3 grid. Boarding House has 5 layers:

  • Back: the floor. Characters (NPC and Players) will appear on top of this.
  • Building: obstacles, things the Characters will have to walk around and can collide with (NPCs CAN sit or stand on Building tiles, but they cannot walk through them).
  • Front: will always appear in front of the character.
  • AlwaysFront: Appears above everything else.
  • Paths: inform the code where to place lights etc. Please note that whilst you can add actual paths to the maps, NPCs are not coded to follow them. It is quite useful to label areas where your NPC stands by placing the red circle however.

Below the Layers, you will see another section displaying the tilesets. Most commonly in indoor locations these are labelled “Indoors” (sometimes also “Indoors2”) and “Paths”. Boarding House adds a third that is Walls_And_Floors.

The tileset named “Indoors” (or in the above case “1”) is TownInterior and it contains almost every piece of furniture, floor and wall used in all the core game interior maps. You will become very familiar with these file!

Now comes the fun part, decorating your character’s room!

The two most useful tools for this are the stamp tool and the eraser. To add parts to your map, select your tool, then choose what you want to add from the tileset by clicking on that square (or click and dragging it over several squares) then place it onto the map.

Experiment with the layering. To stop characters walking up or through the walls, make sure they are blocked by building tiles. Beds need to be a mix of Building (pillow, legs) and Front (sheets, head- and tailboard) tiles, so the character can walk into them. If you want your NPC to actually go into or get out of their bed, the tile next to them needs to be left empty too.

Think about your character’s personality while you are designing their room: Are they messy? Organized? What sort of hobbies do they have?

Cameron is an outdoorsy scholar, so it would make sense that she have: books, a computer (albeit a rather retro one), a few artifacts and, since she’s not the tidiest of people, a few scraps of paper and notes here and there.

Sadly, there are not a lot of things on the TownIndoors tileset to highlight every part of her personality. So we need to look a bit further.

When adding other tilesheets to the map, I recommend you use ones that exist in the Content/Maps folder. Why? Because there are numerous mods that recolor or alter tilesheets, and if you add in your own custom ones they can stand out. That’s not to say that you shouldn’t design your own images if you have the ability – just be aware of the possibility that you may end up with something that does not *quite* look right. Note also that your map will only be able to access tilesheets in the Maps folder, and not those in the Content/Tilesheets folder. If you wish to use any of the latter (ie “furniture”) these will need to be included in the same folder with your map file.

This is the Rustic Country Interior mod, with the “furniture” tile sheet added into the map. You’ll see it is a distinct contrast to the more subdued tones. (Map here is the second storey of the Archaeology House as added by my mod ‘NPC Jasper’)

To reflect Professor Cameron’s occupation as a geologist, we should add in some artifacts. To add in a new tileset you need to locate the button on the bottom right labelled “new tileset” (it looks like a piece of paper with a sunburst). This will bring up the following.

Check that “embed in map” is ticked, and it is good practice to name your tileset with a Z so it will appear after the pre-existing tilesets in the file. Otherwise, it might interfere with hard-coded tileset references and break the map.

Here I have added in a vase from Desert_Tiles and a crystal from my customized version of the “furniture” tilesheet.

Now, how to load this map in game? Two ways: you can patch it in using TMXL Toolkit or Content Patcher.

Content Patcher is easier to use. I recommend it when you are adding patches to existing maps. If you are loading an entirely new location, however, you will need to use TMXL Toolkit.

Also, as multiple people add things to the Boarding House, you don’t want to over-write anyone else’s room, so must only patch in your part.

You can save it as a TMX file or a TBIN file. My personal preference is TMX, because if you find any errors, they can be fixed in Notepad. If you do use TMX format however, make sure that you change the Tile Layer Format to CSV, otherwise it will not be compatible with Mac or Linux.

Here is the code you would use to patch in this image above

using Content Patcher:

{ “Action”: “EditMap”,
“Target”: “Maps/BoardingHouse2”,
“FromFile”: “assets/BoardingHouseCameron.tmx”,
“FromArea”: { “X”: 35, “Y”: 15, “Width”: 11, “Height”: 8  },
“ToArea”: { “X”: 35, “Y”: 15, “Width”: 11, “Height”: 8  },
“When”: { “HasMod”: “BusStopExpansion”   }

and in TMXL Toolkit:

“mergeMaps”: [
“name”: “BoardingHouse2”,
“file”: “assets/BoardingHouseCameron.tmx”,
“sourceArea”: [ 35, 15, 11, 8 ],
“position”: [ 35, 15 ],
“conditions”: “LC Luau.hasMod(‘BusStopExpansion’)”


  • BoardingHouse2 IS a custom map, but because it is loaded via TMXL Toolkit, the game believes it exists in game. You can edit custom maps just as easily as you can edit core game maps (as long as they are loaded correctly first).
  • You should remove all Map Properties from your map, otherwise yours will over-ride any pre-existing or previously applied ones. This is a very common cause for broken warps/doors/lighting and other errors.
  • If the tileset is located in the Content/Maps folder of the game, you should remove it from your ‘assets’ folder before you load your map into the game. This means it will use any recolored maps that exist.
  • You can crop down your tbin/tmx file to just the size of your edits, if you prefer. In which case the FromArea/Source Area would be “X”:”0″, “Y”:”0″, “width”:”11″, “height”:”8″ (or [ 0, 0, 11, 8]).

Also, if you are moving an NPC into the Boarding House, don’t forget to let Trent (the creator) know!

Tomorrow, we add TileData so you can snoop around their house an uncover some of their secrets.

Below, the second story of my boarding house. Residents include: Shiko, Mike, Kim and Amelia (who is currently occupying the room I just designed for Cameron). This is as seen in game using Rustic Interiors (which I find rather pleasing, and may keep for a while).

NPC Creation: Schedules

Now that your character is loaded into the game, and you can talk to them and give them gifts, let’s get them moving!

For this you will need one (or both) of the following:

  • Tiled and unpacked maps of the town and surrounds.
  • Debug mode
  • Custom NPC Fixes (just install it and ignore it, it works its magic behind the scenes)

Mechanics of Schedules:

Scheduling can be a beast to tackle! What is your character going to do each day? What activities might they pursue? Do they work somewhere?

Let’s consider Cameron:

Cameron lives in the boarding house. She’s an archaeologist and a surfer, so it stands to reason that she’s an outdoorsy type. Her archaeological interests lies more in the previous people that lived in Stardew Valley rather than rocks, etc, so she’s probably more interested in strolling around the areas where those people lived worked and played than entering the cave of quarry. Also, being a surfer, she is likely to enjoy the beach.

You can begin your character with only one entry in their schedule. “Spring” is the default. Although the day may start at 600 hours, schedules should start no earlier than 610.

Here is Cameron’s schedule. Note that EastScarpe is a custom location, and not part of the main game. It makes no difference, she can still go there just as easily!

“spring”: “700 EastScarpe 33 101 2/1200 EastScarpe 69 21 2/1800 Beach 4 6 2/2200 BoardingHouse 36 19 3”,

<time> <map> <X coordinate> <Y coordinate> <direction to face>

Find your X and Y co-ordinates by using debug mode at the position where you want your NPC to stand.

  • NPCs walk slowly, allow them around 2 hours per map they need to cross. To walk from Marnie’s ranch to the Adventurer’s Guild takes about 3-4 hours.
  • There are three maps that are out of bounds to NPCs: The backwoods, the secret woods, and the farm. If you include any of these areas in the NPC’s schedule, they will simply refuse to move.
  • There are at least five maps that edit the Town map, and some of those also affect other maps. Be prepared to move your NPC or make compatible schedules. (even if you don’t test them all yourself, someone will tell you).
  • Some places are extremely popular for NPCs to stand: In the middle of the end of the jetties, in front of Mona’s grave… Stalk your NPC.
  • Having characters walk together can be challenging. Even if they start side by side, pathing may send them on forking routes. If you want two characters to walk side by side, have them start side by side first.

Schedule dialogue

There are two ways to add schedule based dialogue. One is using strings, the other uses locational tags in the dialogue.

“…1300 CommunityCenter 33 9 2 \”Strings\\schedules\\Sebastian:Solarion_So1/…”


“CommunityCenter_33_9”: “insert dialogue here”

I haven’t really found any advantage or disadvantage to using one over the other. The first one only gives you one looping dialogue box. The second one still loops, but allows you to go through multiple dialogue boxes before beginning to loop.

Idle Animations

Want your character to be doing more than just standing there? Animate them! To decide your animation, consider your character and what they might do in their free time: Alex plays with a football, Haley takes photos, Shane puts items on the shelf at work. A lot of characters (including Jasper) read.

Consider Juliet: she spends long hours standing behind the JojaMart counter. What sort of things might she be doing as well?

Here are the animation sprites for this:

And here is the code:

{   “LogName”: “Animations”,  
    “Action”: “EditData”,  
    “Target”: “Data/animationDescriptions”,
    “Entries”: {
        “Juliet_work”: “12 24 24 24/16 16 16 17 17 18 18 19 19 18 18 18 19 19 19 18 18 18 19 19 19 17 17 20 20 20 20 20 20 21 21 21 20 20 20 22 22 20 20 22 22 20 20 21 21 21 21/24 24 24 12”,

The numbers correspond to the frame on the sprite sheet. and they go in: pre-animation/looping animation/post-animation. Pre and post are generally identical, only mirror imaged.

The speed is predetermined (I think around 120 ms) so you will need to repeat the same frame multiple times to avoid having them move very fast.

Animation is added to the schedule BEFORE the dialogue:

850 JojaMart 9 25 1 Juliet_work \”Strings\schedules\Juliet:JojaMart.01\”/

Why isn’t my character moving?

There are numerous reasons an NPC might fail to follow their schedule. Here are a few reasons I’ve found:

  • Typo in the schedule, either an extra space, a map name misspelled (ArchaeologyHouse was my bane for a while) or two locations that the character is supposed to head to at the same time.
  • Destination cannot be accessed: There might a bush in the way, or impassable building tiles (note, an NPC will walk TO and stand on a building tile, but will not walk OVER one to get to a destination beyond it). Could also be a broken door.
  • Something has affected pathing: mostly happens to custom or altered maps and can be very tricky to bug fix. Have found this happens when you adjust “addWarps” (in TMXL) based on HasMod conditions, or when redone maps load based on HasSeen conditions. I theorize it is caused by Smapi making changes to the map AFTER the pathing has been determined.
  • NPCs may do other random things too: walk off maps and vanish into the void. Refuse to move. Walk around the wrong map for a day (this usually happens when their spawn point is adjusted). Some are worst behaved than others. Cameron spent a lot of time staring at the wall in one of the houses I moved her into (she would leave, then reenter and walk into the wall) despite the fact that her house mate came and went perfectly happily. Another time I tried to send Cameron into the movie theater and she chose to stand beside the river instead… what can I say? She’s wilful. Keep playing, testing and retesting until they work.
  • Sometimes they just won’t enter a destination, and there appears no logical reason why.

NPC Creation: Dialogue

Well, this is awkward, Jasper’s my husband …

This is where the chance to show your character’s personality really shines through. Coming into this stage, it helps to know a little about your character first:

  • What are their hobbies/interests?
  • How do they talk? Are they formal? Casual? Irreverent?
  • How would your character react to meeting a stranger?
  • Do they have any friends/allies/acquaintances/enemies/etc among the other NPCs?

At a minimum, your character will need seven lines of dialogue, one for each day of the week. You will obviously want more than this!

This guide is mostly going to focus on the dialogue itself, for a guide on the mechanics (including how to change portraits or give items), everything is covered here:

Dialogue is based on heart level (even numbers only). If you add dialogue for every <season>_<day><heart level> you can have around 168 lines with those alone. When you add in specific day (<season>_<date>) and conversation topic dialogue (more on that later), it is possible to add in hundreds of lines. Using Content Patcher tokens it is also possible to add a LOT more!

This is not essential though – canon NPCs can have as few as 11 (Dwarf) or as many as 107 (Abigail). Generally speaking though, the more lines your character has, the more interesting they will be to talk to, and the more replayability the character will have.

Note that once you start gaining hearts with a character, they can go up in level very quickly (especially when birthdays are taken into account) and thus it is better to focus on higher level dialogue (8 hearts for datables, 10 hearts for non-datables) as the player will likely be on those for a long time.

General guideline of heart-level dialogue:

0 – 2 Barely know each other, small talk or superficial.
4 – 6 You’re starting to become friends. Might give a little more personal information, conversation flows more freely.
8 You’ve become a trusted friend and confidant
8 – 10*You’re best friends. They might be willing to tell you anything.

*  For datable characters, anything over 8 hearts implies that you are romantically involved. However, as platonic relationship mods exist, it is best if the really flirty stuff is added via:
    “When”: { “Relationship:Cameron”:”Dating, Engaged” }

It is also possible to change dialogue based on heart events or other conditions. For Jasper, (who starts non-datable) depending on how you answer a specific question in his 8-heart event you can end up with new dialogue. The same applies to my Marnie expansion (which was partly began so I could stop her telling me about her nephew Shane living with her, when he was married to me and had been for over a year).

You could even lead your NPC’s story arc through different paths depending on what choices the player makes.

Which leads to the next thing… The dreaded questions!

If they’re so tricky to code, why ask questions at all?

Questions give another level of interactivity, allowing the player to feel like they have actively contributed to the NPC’s choices. They can be as simple as “Does my hair look good today?” or as complicated as “Should I ask Sebastian and Sam if I can join their band?”.

Yes, it is completely possible to add entirely new story arcs based on choices the player makes. You can change schedules, dialogue, heart events, using “When”: { “HasDialogueAnswer”: “<Dialogue Answer ID>” } conditions.

So, what’s the structure?

I’ve found it’s a lot easier to write the questions out in multiple lines, before combining them together in the dialogue. So here’s a sample from my Jas expansion mod:

“$q 525991/525992 Jas_Caves#You go into the caves, don’t you, Farmer @?
#$r 525991 10 Jas_Caves_Yes#All the time! They’re fun and exciting.
#$r 525991 0 Jas_Caves_Dangerous#Yes, but they’re really dangerous.
#$r 525992 25 Jas_Caves_NoBrave#No, I’m not brave enough for that, I’d rather tend my crops and look after the animals.”,   

“$q” is the question, the numbers afterwards are the Dialogue answer IDs.

The “Caves” is the follow-up. Since questions are only asked once, instead of giving the question again on the following Saturday in summer, the dialogue will instead default to the one beginning with “Caves”.

You will notice that the numbers after the #$r (the possible responses) have two the same and one different, this is also referred to in the “follow-up” where 525991 indicates that the farmer enters the caves and has adventures, and 525992 that they do not.

The Jas_Caves_yes/Jas_Caves_Dangerous/Jas_Caves_NoBrave all have corresponding dialogue tags, and she will respond depending on which you choose.

The following week, if it is still summer and you are still at 6 hearts with her and you speak to her, this is how she may respond:

“Caves”: “$p 525991#I found this in the bottom of my closet. It belonged to my mom. It might be good for the caves.$1[531]|Are there any baby animals on your farm? Can I come over and play with them?”,

If you answered with the choices that indicate you visit the mines, she gives you a ring (it cannot be worn, alas), if you said you were scared, she asks about the baby animals. Note that this will repeat for every Saturday remaining in summer that you are with 6 hearts with her, so you could end up with 3 unwearable rings. This isn’t advisable!

Another thing to note, is that if you have dialogue before the question:

“winter_Fri10”: “Uncle Shane doesn’t believe in magic; he believes in science.#$b#$q 976/977 MagicReal#Do you believe in magic, Farmer @?…

The next Friday in winter that you talk to her, she will start her conversation with “Uncle Shane doesn’t believe in magic; he believes in science…” then jump to the “MagicReal” (follow-up) dialogue. So make sure that your starting dialogue and your follow-up flow into each other neatly!

Some other things I have observed:

  • Writing a one sided conversation can be challenging. It can take a while to warm to your character.
  • Try and limit how many dialogue boxes you use. 1-2 preferable, 3 occasionally. Try not to exceed this. One of the arts of writing NPC dialogue is learning how to be succinct!
  • If you have a map specific tag (ie: “Saloon_Mon”) the dialogue will loop. It is inadvisable to have the NPC give the player alcohol in the saloon, as it can easily be exploited (and that was how my farmer funded her barn).
  • If you want the char to give the farmer a gift but don’t want them to do it every day afterwards, use the “$1 Cameron_Gift#Here have this [151]…” tag. What this does is creates a mail flag labelled “Cameron_Gift” to say that she’s given you the item, and it won’t be repeated the following week. (Note that there will also be an alternative dialogue to say in the following week).
  • If you want to write an action, begin the dialogue with “%”. DO NOT leave a space before or after it: “#%Cameron won’t meet your eye.” (not “# % Cameron won’t meet your eye.”) Otherwise your character will “speak” it!

NPC Creation: Gift Tastes

When adding gift tastes, you will need a list of the item IDs. These can be found online in various places, as well as part of the Great ID Spreadsheet (alas, as it’s a Google Drive document, I’m not sure I can share it).

(you can google “item ids stardew” to find various websites with lists.)

{          “LogName”: “NPC Gift Tastes”,
            “Action”: “EditData”,
            “Target”: “Data/NPCGiftTastes”,
            “Entries”: {
                “Peasbody”: “wow, thanks! You’ve been doing your research. I love this!/581 586 587 563 730/This is wicked – and I mean that in a good way!/96 97 98 99/Um, yeah, not really my thing but it’s the thought that counts, I guess…/440 346 209/Oh aren’t you a jokester? What is this? Trash?/196 2 156/Thanks!//” 

This is the order the gift tastes are in:


You can enter individual item IDs, or type IDs (characterized by a – preceding the number) . If, for example, you want your character to dislike fish, you can use -4 instead of entering every fish species separately.

When selecting what your character likes and dislikes, try not to choose arbitrarily (unless of course you want to!). Try and think about what your character does, who they are. As an Archaeologist, Cameron loves certain artifacts (I gave her one above). Try not to give them too many loves or, if you do, make them ones that are harder to get. Then again, it may be that you want your character to be easily friended. My (and Cameron’s) beloved Jasper is very fond of blueberries, for example. A lot of gift tastes are pre-set (refer to the wikipedia), so you really only need to focus on Loves and Hates and maybe make a few adjustments to Likes and Dislikes.

Note: Portrait reactions to gift tastes are hard-coded.

How your character reacts too says a lot about their personality. Remember how disorientating it is when you gift Shane at low hearts, and he gives a delighted response, then basically tells you to shove off?

Yes, it is possible to change your NPCs reactions as you gain hearts with them. Also, when you marry them. These are all functions that Content Patcher add to the game that actually allows custom NPCs to be more immersive, more interactive, than the canon NPCs (although there is also nothing to stop people adding similar features to existing NPCs).

But more on conditional tokens later. Next up, we are going to get into Dialogue.

NPC Creation: Sprites

There are two sorts of sprites required for your character in the game: portraits and walking sprites.


Portraits measure 64×64 pixels. They are seen when you talk to the character.

I have found the best way to do the portraits is by copying. Not directly; Cameron isn’t traced, but I did refer to one of the existing ones to do her details. The core game images use only a small amount of colors and do their shading via hues and dynamic shading. To keep the colors close to canon, I choose a character in the game with a similar skin/hair tone, and pick the colors from them using the eye drop tool. This means your character will blend in somewhat with the pre-existing characters.

The number of portraits can vary between one and many. Some characters: Dwarf (1) and Wizard (2) have very few, whereas datable characters tend to have at least 6, usually more. Cameron isn’t datable (she’s too hung up on Jasper) but I like to give them a range. Also note that some of these pictures appear to have her topless. Cameron was originally designed to be “farmer gendered” like Kel: in that if you were playing a female character, she would be female, and if you were playing a male character, he would be male. So, I decided to do one portrait to fit both.

This is too complicated to do in NPCD for these example purposes (but actually 100% entirely possible, using the wonder of Content Patcher “When” Conditions, you can even have gender fluid characters, like Riley).

Here’s the general layout of portraits for datable characters:

$0 Neutral$1 Happy
$2 Sad$3 “Unique”
$4 “Love”$5 Angry

As you can see, Cameron’s “love” portrait is more of a slightly perplexed one. Marnie’s one in that position is a “shocked” one. So, be careful when you use them in dialogue!

Walking Sprites

Walking sprites are the ones that appear on the map. They measure 16 x 32 pixels.

I am not good with small pixel art. The easiest way to do it is to draw over an existing one. In Cameron’s case, I chose Pierre, which is doing her a disservice, but I wanted her to not be particularly feminine.

The first 16 lines are the walking ones: towards, right, away, left. Get these around the wrong way and your character will moonwalk. As per before, frames start numbering from 0.

In datable characters, frame #28 is the kissing sprite. They should be facing to the right-hand side of the panel.

There are also set positions for dancing sprites (for the Flower Dance, yes, you can dance with your custom NPCs!) and wedding sprites.

You can also make animations, and add sleeping sprites. More on animations later though – let’s get your character to appear in game first, shall we?

Here’s the code to load the sprites:

{          “LogName”: “Peasbody Portraits”, 
            “Action”: “Load”,
            “Target”: “Portraits/Peasbody”,
            “FromFile”: “assets/Cameron-portraits.png”      
{          “LogName”: “Peasbody Sprites”, 
            “Action”: “Load”,
            “Target”: “Characters/Peasbody”,
            “FromFile”: “assets/PeasbodyF.png”          

Note that you are loading them into the same name as you loaded into the computer on the NPCD, not their social menu/display name.

This code takes the pngs from the assets folder of your mod, and loads them into the Portraits or Characters file, where the game will now believe they exist as: Portraits/Peasbody.xnb and Characters/Peasbody.xnb.

If you have been entering these into your content.json, and have created a manifest.json as well, you should now be able to load the game and actually see your character in it!

You will notice several things however:

  • They will not move and will be facing away from you.
  • They will not talk to you.
  • They will not accept gifts.
Cameron’s sad beginnings as a sample NPC…

Time to start letting their personality show through!

NPC Creation: Dispositions

Just for fun, I thought I would take you through the process of creating a custom NPC for Stardew Valley. To begin your creation process, you will need the following:

  • Several Framework mods: specifically Content Patcher and TMXL Toolkit
  • A program in which you can edit and write code. I use Visual Studio Code.
  • A sprite creation program. I recommend Aseprite. It’s US$15, or free if you compile it yourself.
  • Tiled if you wish to design custom accommodation for your NPC.
  • A template or basic custom NPC to use for reference.
  • A character concept.

There are various other tools you can use to make the process smoother. Miss Coriel has created two useful resources, the NPC Creator and a template. The Creator takes a lot of the guesswork out of it, and walks you through the steps, but I personally prefer to use a template, as that way I learn the actual process.

Now I’d like to introduce you to my character, Cameron.

Cameron is an archaeologist, and head of the Archaeology Department at Zuzu City University (ZuCU). She enjoys adventure sports, surfing, and antagonizing Professor Jasper.

Currently she appears as a temporary actor in one of my other mods, so I have repurposed her sprites and portraits to use as a demonstration.

To convince the game that Cameron exists, we need three things for her:

  • An NPCD
  • A portrait
  • Sprites

Firstly, the NPCD, this is what Cameron Peasbody’s looks like. Now, notice that I have named her as “Peasbody” in the code. Whatever name you put there must be unique to your character. This will avoid clashes with other mods later. This is the name in which she will be called in the code, but not the name shown for her on the screen, which is ‘Cameron.’ The latter can be changed, but the name in the code cannot.

   {       “LogName”: “NPC Manifestation”,
            “Action”: “EditData”,
            “Target”: “Data/NPCDispositions”, 
            “Entries”: {

 “Peasbody”: “adult/polite/outgoing/positive/female/not-datable/Jasper/Town/summer 8/Jasper ”/BoardingHouse 36 19/Cameron”        
Below is the breakdown of what each field means. Note that the numbering starts at 0.
0. Agechild/teen/adult
1. Mannerspolite/neutral/rude
2. Personalityshy/neutral/outgoing
3. Attitudenegative/neutral/positive
4. Gendermale/female (note that Dwarf is ‘undetermined’)
5. Databilitydatable/not-datable (note that Krobus is ‘secret’)
6. Romantic Interestnot actually used in game, but fun to add anyway
7. AreaTown/Desert/Other
8. Birthday
9. Relationshipsfamily members/friends/housemates
10. Spawn Point<MapName> X Y
11. Social Menu Name

Things to note:

  • If your character does not appear on screen, the first thing you should do is count the fields in their NPCD, it’s very easy to miss one!
  • There are various hard-coded responses to things that are affected by the first 3-4 fields above, including: birthday gift responses, garbage can reaction dialogue, greeting dialogue.
  • Characters that begin as not-datable can be made datable during the game.
  • Area determines whether your character will develop friendship due to the Luau contribution. Town, yes, anything else, no.
  • It’s best to choose a day that doesn’t already have a birthday on it, as only one NPC will appear on the calendar. However, with so many new NPCs being created, clashes are inevitable.
  • Relationships affect greeting behavior (ie: when two villagers pass each other and occasionally say “hi”) and they may also (randomly I think) give information on the other characters likes and dislikes.

What happened to my cellar stairs?

Congratulations! You’re now happily married in Stardew Valley, but something bizarre has happened: the stairs to your cellar have transformed into… something else…

What has happened? Is your new spouse some sort of weird redecorator? A kind of anti-carpenter?

The answer lies in how custom spouse rooms are added into the game, and how the game code selects where to find the stairs.


  • Tilesheet: is the source image, so below it is lemurfurniture.png.
  • Tileset: is the name the tilesheet is given in the index, below that is z-lemurfurniture

Tileset order is very important in your map design. There are a few times in the core game where completing an action will draw a tile from a selected index and place it. If you disrupt the order, then it will still draw this tile: but from a different tileset…

Therefore, it is highly recommended, that when creating a spouse room (or making any additions to existing maps) that when you add a new Tilesheet into the game, you begin the tileset’s name with a “Z-” (also, make sure the “embed in map” box is checked).

So that in the Tileset index, “Indoor” is always the first one on the left hand-side (or in the case of non-spouse room maps, the original order is preserved).

But my spouse’s room is correct and it’s still messed up! Why?

When TMX Toolkit adds the spouse rooms, it doesn’t just add your actual spouse’s room. It adds all of the spouse rooms that exist in your files, with your actual spouse’s room at the top. So the good news is, it may not be your mod breaking it! The bad news is, it can be very tricky to find which NPC’s spouse room IS.

I have found the easiest thing to do is simply not install spouse rooms if they are separate files and I do not intend to marry that character. If this is not the case, the only other solution is to look through the .tmx files until you find the spouse room with the issue (and notify the creator).

Note that you can disable blocks of code without deleting them, by framing that section with: /* and */.

Alternatively, you can open the tmx file in either Tiled or Notepad and change the tileset name yourself.

Previous Older Entries