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 When block, 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:

content.json
{
  "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:

content.json
{
  "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.

  1. Start from a copy of the original portrait sheet so your frames stay in the same positions and sizes.
  2. Draw your new expressions into the matching frames and save the sheet as a PNG in your pack’s assets folder.
  3. Add an EditImage patch that targets Portraits/<Name>. To replace only one expression, use ToArea.
content.json
{
  "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.