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, and the x= y= form of Position needs 2.5.0. 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 = "x=27 y=67 face=down"
MainEventPosition = "x=26 y=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=27 y=67 face=down", "27 67 down" or just "27 67" (facing is up, right, down or left, default down), 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", "x=69 y=32 face=down", "x=70 y=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.