Dialogue & Schedules

Dialogue#

Put dialogue in the main NPC TOML file or in Dialogue.toml:

[Dialogue]
Introduction = "Hi, @. I'm Rei."
Mon = "A new week begins."
Hospital8 = "I hope everyone is feeling better."
AcceptGift_Loved = "You remembered what I like!"

NPC Helper 2 uses Stardew Valley's dialogue keys and text syntax. It passes keys and text to the game; it does not define a separate conditional dialogue language. See the Stardew Valley dialogue reference for the complete key list and special text syntax.

Portrait expressions#

Append an expression token to a dialogue line to select the NPC's portrait. Prefer the letter tokens for standard expressions; use numeric tokens for custom portraits:

For example, "You remembered what I like!$h" selects the happy portrait, while "A special reaction.$6" selects Custom 1.

Gift reactions are dialogue entries, separate from the [GiftTastes] table. Common response keys include:

• AcceptGift_<qualified item ID> for a specific item.
• AcceptGift_Loved, AcceptGift_Liked, AcceptGift_Neutral, AcceptGift_Disliked, or AcceptGift_Hated.
• AcceptGift as a general fallback.

Schedule tables#

Place schedules in the main NPC TOML file or Schedule.toml. Each key identifies the days or conditions, and its value is a list of stops:

[Schedule]
Weekday = [
  "600 Hospital 1 18 1",
  "a1200 Town 29 54 2",
  "1800 Saloon 37 23 0 sit_down \"Good evening!\"",
  "2200 bed",
]

summer_12 = ["900 Beach 20 20 2"]
Rain = ["GOTO spring"]

The compact stop format follows TIME MAP X Y FACING [ANIMATION] ["message"]. The location may be omitted to stay at the previous location. A stop may also use a readable clock format:

[Schedule]
Sat = [
  "7:00 Town x=84 y=13 face=right",
  "by 12:00 Beach x=4 y=5 face=up",
  "10:00pm Hospital x=3 y=7 face=left",
]

Schedule key patterns#

Common keys include:

When multiple patterns could match, Stardew checks more-specific schedule keys before general weekday and season schedules. In practical terms, date-specific and friendship schedules can override the ordinary weekday routine. The game may skip a schedule key if its conditions do not match.

For reference, the game's non-marriage schedule lookup proceeds through these scopes, from more specific to more general:

1. The game's current island schedule, when one is active.
2. GreenRain.
3. Festival ID with an optional day suffix, such as fall27_3, then the festival ID alone.
4. season_day, such as summer_12.
5. day_hearts, then day.
6. Rain2, then Rain.
7. season_weekday_hearts, then season_weekday.
8. weekday_hearts, then weekday.
9. The season key, then spring_<weekday> and spring as fallbacks.

The game checks the first matching key. Heart-level weekday rules have game-specific matching behavior, so prefer an ordinary weekday schedule unless you specifically need friendship-gated routines. Location names, animation names, and festival IDs are supplied by the game and other installed mods.

Weekday and Weekend are convenience aliases. For a schedule that should run only when no more specific routine applies, use the spring fallback key.

Commands and checks#

A schedule value can be a whole-key game command instead of a list:

[Schedule]
Rain = "GOTO spring"

GOTO can redirect to a season or another schedule key. A schedule list can begin with a friendship condition:

spring = [
  "NOT friendship Sam 6 Abigail 4",
  "900 Town 10 12 2",
]

If any listed friendship condition is met, the NPC uses the spring schedule instead. Other non-list values are passed to the game as schedule commands.

Two stops for the same key cannot use the same time. Invalid times and duplicate stops are reported in the SMAPI log; correct those warnings if the game skips a routine.

For spouse routines, use the [Marriage] table in Schedule.toml; see Marriage.