Tokens & Animations
Conditions, tokens, portraits and animations
for Stardew Valley content packs.
What are Content Patcher tokens?
Tokens are values that Content Patcher knows about the current game: the season, the day, the weather, where the player is, who they’re married to and much more. A content pack can use tokens in two ways:
- As conditions in a patch’s
Whenblock, so the patch only applies when the condition is true. - Inside values, written in double braces like
{{Season}}, so one patch can pick a different file or text automatically.
- Season
- spring, summer, fall or winter
- Day / DayOfWeek
- day of the month (1–28) or the weekday name, such as Monday
- Weather
- Sun, Rain, Storm, Snow or Wind (and GreenRain in 1.6)
- Time
- the in-game time, from 0600 to 2600
- LocationName
- the current location, such as Farm, Town or Beach
- Spouse
- the name of the player’s spouse, if any
- Hearts
- friendship level with an NPC, for example
Hearts:Abigail - Year
- the current in-game year
Conditions in practice
This example gives Abigail a portrait for each season, a rainy-day portrait, special dialogue once she is your spouse and an evening portrait after 6 pm:
{
"Format": "2.0.0",
"Changes": [
{
"Action": "EditImage",
"Target": "Portraits/Abigail",
"FromFile": "assets/abigail-{{Season}}.png"
},
{
"Action": "EditImage",
"Target": "Portraits/Abigail",
"FromFile": "assets/abigail-rain.png",
"When": {
"Weather": "Rain, Storm"
}
},
{
"Action": "EditData",
"Target": "Characters/Dialogue/Abigail",
"Entries": {
"Mon": "Morning, dear! I already fed the chickens."
},
"When": {
"Spouse": "Abigail"
}
},
{
"Action": "EditImage",
"Target": "Portraits/Abigail",
"FromFile": "assets/abigail-evening.png",
"When": {
"Time": "{{Range: 1800, 2600}}"
},
"Update": "OnTimeChange"
}
]
}- Commas in a condition mean “any of these”:
"Rain, Storm"matches both. - Patches apply in order, so later image edits are drawn on top of earlier ones. Put the most specific patches last.
- By default, tokens update at the start of each day. Add
"Update": "OnLocationChange"or"OnTimeChange"when a patch must react during the day.
Let players choose options
A ConfigSchema block creates a config.json file that players can edit. Each option becomes a token you can use like any other:
{
"Format": "2.0.0",
"ConfigSchema": {
"PortraitStyle": {
"AllowValues": "Classic, Cozy",
"Default": "Cozy"
}
},
"Changes": [
{
"Action": "EditImage",
"Target": "Portraits/Abigail",
"FromFile": "assets/{{PortraitStyle}}/abigail.png"
}
]
}Stardew Valley Content Patcher portraits
Portrait mods are among the most popular content packs. Every character’s portraits live in one image, Portraits/<Name>, with each expression in a 64×64 pixel frame, two frames per row.
- Start from a copy of the original portrait sheet so your frames stay in the same positions and sizes.
- Draw your new expressions into the matching frames and save the sheet as a PNG in your pack’s assets folder.
- Add an
EditImagepatch that targetsPortraits/<Name>. To replace only one expression, useToArea.
{
"Action": "EditImage",
"Target": "Portraits/Abigail",
"FromFile": "assets/abigail-happy.png",
"ToArea": { "X": 64, "Y": 0, "Width": 64, "Height": 64 }
}Walking sprites work the same way: they are in Characters/<Name>, usually in 16×32 pixel frames.
Content Patcher animations
Stardew Valley animates characters, animals and many objects by switching between frames in a spritesheet. When a content pack edits those frames with EditImage, the game plays your new frames with the same timing as the original, so a reskinned character or animal animates correctly.
- Reskin existing animations: keep the frame layout of the original sheet and redraw each frame.
- Change art during the day: combine conditions with
"Update": "OnTimeChange"to switch images as time passes, for example lights that turn on in the evening. - Brand-new animation behavior, such as extra frames or custom timing, is not something Content Patcher adds by itself. It needs a separate framework mod or code, and the pack’s page will list it as a requirement.
Next steps
New to content packs? Start with the basic structure of a content pack. If a pack doesn’t behave as expected, the SMAPI command patch summary shows every patch and why it is or isn’t applied; more tips are on the troubleshooting page.
