Schedules

A schedule tells the NPC where to be and when. It is a [Schedule] table in Schedule.toml (or in the NPC file). Each key says which days the routine is for, 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"

Step 1: Write a stop#

A stop is one quoted text. There are two ways to write it. Use either, or mix them in one file.

The game's own form:

TIME MAP X Y FACING

"600 Town 3 8 2" means: at 6:00, be in the Town at tile 3, 8, facing down.

The spelled-out form:

"6:00 Town x=3 y=8 face=down"

Both forms accept the same optional extras after the position: an animation and a message.

"1800 Saloon 37 23 0 sit_down \"Evening!\""
"by 12:00 Beach x=4 y=5 face=up sit_down \"Hi!\""

The parts of a stop#

Location names, animation names, and festival IDs come from the game and from other mods, so they are not listed here.

Rules for stops#

• Stops of one key are sorted by time.
• Two stops at the same time make the game reject the whole key, so NPC Helper 2 keeps the first and reports the second.
• A stop that cannot be read is skipped with a warning that names it.

Step 2: Choose the key#

The key decides when the routine runs.

Hearts run from 1 to 14. The game picks the highest level the player has reached.

Step 3: Understand which schedule the game uses#

The game tries these keys in order and uses the first one that exists. If none exists, the NPC has no schedule that day. NPC Helper 2 can write every one of them.

1. GreenRain (green rain, first year only).
2. A festival ID, with day suffix then without it, for each currently active festival.
3. <season>_<day>, for example summer_12.
4. <day>_<hearts>, then <day>.
5. Rain2 (on half of rainy days, if present), then Rain.
6. <season>_<weekday>_<hearts>, then <season>_<weekday>.
7. <weekday>_<hearts>, then <weekday>.
8. <season>.
9. spring_<weekday>, then spring: the fallback.

Practical effects:

• A date key such as summer_12 beats the ordinary weekday routine, so use it for a birthday or special day.
• Rain beats the weekday key on rainy days.
• Write a spring schedule as the general fallback, for days nothing else matches.
• Heart-level keys for weekdays are only tested at every second level counting down from the player's hearts (6, 4, 2, and so on), so a weekday key for an odd or even level can be skipped. NPC Helper 2 warns about this. Prefer an ordinary weekday key unless you need heart-gated routines.
• Some game keys are only used by particular vanilla NPCs. For example the game tries bus for one villager only, and marriageJob only for three. NPC Helper 2 warns if you use them on another NPC.

Step 4: Use whole-key commands#

A value that is a single text instead of a list is a command for the whole key.

[Schedule]
Rain = "GOTO spring"

A list can start with a friendship check:

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

If any player has that many hearts with a listed NPC (here Sam at 6 or Abigail at 4), the spring schedule is used instead.

A worked example#

[Schedule]
# Monday to Friday
Weekday = [
  "6:00 Hospital x=1 y=18 face=right",
  "by 12:00 Town x=29 y=54 face=down",
  "18:00 Saloon x=37 y=23 face=up sit_down \"Evening!\"",
  "22:00 bed",
]

# Saturday and Sunday
Weekend = [
  "9:00 Beach x=20 y=20 face=down",
  "20:00 Hospital x=3 y=7 face=left",
]

# The birthday (summer 12) overrides everything else
summer_12 = ["10:00 Town x=5 y=5 face=down"]

# Rainy days: stay on the spring routine
Rain = "GOTO spring"

# Fallback for any day nothing else matches
spring = ["7:00 Hospital x=2 y=3 face=down"]

Step 5: Test#

1. Start the game through SMAPI and read the summary. Schedule warnings name the key and the stop.
2. Watch the NPC through a day. Use a day skip or a time-changing mod to reach the times you wrote.
3. Check that every walk fits its time. An NPC that has too little time to reach the next stop will arrive late.
4. If an NPC gets stuck or vanishes, the tile may be inside a wall or unreachable. Pick a tile the NPC can walk to.

The spouse schedule#

Once the player marries the NPC, a different set of keys is used. They go in a [Marriage] table in the same file. See Marriage.

Translating a schedule#

A translated [Schedule] with at least one valid entry replaces the base schedule rather than adding to it. Most translations should leave the schedule out. See Localization.