An optional Festivals.toml in an NPC's folder, found by name. A pack that uses it must require NPC Helper 2.4.0 or later in manifest.json (ContentPackFor.MinimumVersion). Bringing the NPC to festivals, Position and festival outfits need 2.4.2. For cutscenes at heart levels, see Heart events.
Festivals.toml: festivals#
One table per festival, named after the festival's ID. A table brings the NPC to that festival. The game only shows an NPC at a festival when she is placed on its map, so an NPC with no table is simply not there. The shortest form is an empty table:
[spring13]
Add what she says and where she stands only when you want to:
[spring13]
Dialogue = "I never find an egg. I only eat them."
SpouseDialogue = "Hold my basket, dear. I'm going to try this egg hunt thing."
Position = "27 67 down"
MainEventPosition = "26 64"
[winter25]
Dialogue = "The punch is not from the clinic's cabinet. I checked."
| Key | Meaning |
|---|---|
Dialogue |
Said when the player talks to the NPC at the festival. |
SpouseDialogue |
Said instead when she is the player's spouse. |
Position |
Where she stands when the festival opens: "x y" or "x y facing" (up, right, down, left), in the tiles of the festival's map. Leave it out and NPC Helper 2 picks a free spot. |
MainEventPosition |
Where she stands for the festival's main event. Same form. Only spring13, summer11, summer28 and winter8 have one. Leave it out and NPC Helper 2 picks a spot. |
The festival IDs of the game are:
| ID | Festival | Has a main event |
|---|---|---|
spring13 |
Egg Festival | yes (the egg hunt) |
spring24 |
Flower Dance | no |
summer11 |
Luau | yes (the soup) |
summer28 |
Moonlight Jellies | yes |
fall16 |
Stardew Valley Fair | no |
fall27 |
Spirit's Eve | no |
winter8 |
Festival of Ice | yes (the fishing contest) |
winter25 |
Feast of the Winter Star | no |
Where she stands#
The festival maps are different in the first year and in later years, and some of the map is water or built over, so a tile that works in one place may not in another. When you leave Position out, NPC Helper 2 uses a spot checked against the game's own festival maps for both years: dry ground, nothing built on it, reachable on foot, and not where one of the game's villagers stands. Several NPCs at one festival get different spots.
If you give a Position, it is your job to pick a tile she can stand on. A tile in water, inside a wall or on top of a villager shows her in a wrong place. The tile numbers are the same as in a schedule. A Position is used in both years. Choose a tile that is open on both maps, or leave it out.
A festival ID that is not one of the game's eight is accepted for a festival another mod adds. NPC Helper 2 has no spot to pick there, so give a Position.
How it appears in the game#
Dialogue and SpouseDialogue are added to the festival's data under the NPC's name and <Name>_spouse, like the game's own villagers. The NPC is placed through the festival's Set-Up_additionalCharacters entry, and MainEvent_additionalCharacters for the main event (Main-Event_additionalCharacters for the Festival of Ice). These entries are part of the game's festival format and work for any NPC, so the festival map itself is not changed.
Festival outfits#
An NPC can wear a different outfit at a festival. Name an image after the festival ID, in any capitalization, with or without a separator, and she wears it while the player is inside that festival. See Image variants.
Translating festivals#
A translation pack can carry locale/<code>/Festivals.toml (same tables as the base file). See Localization.
From C##
new NpcBuilder("Rei")
.FestivalDialogue("spring13", "I only eat them.", spouseDialogue: "Hold my basket, dear.")
.AttendFestival("summer11") // she comes; NPC Helper 2 picks the spot
.AttendFestival("winter8", "69 32 down", "70 36"); // or give the spots
The SDK writes Festivals.toml and reports a bad festival ID or a bad position when the NPC is validated.