Marriage

Step by step: make an NPC marriageable#

1. In the NPC file, set Marriageable = true in [Romance]. This implies Datable = true, so the NPC can also be romanced.
2. Create Marriage.toml next to the NPC file. Add the tables you need: [Engagement], [Dialogue], and [Wedding]. Leave out any you do not want.
3. Add a [Marriage] table to Schedule.toml for the routine once married (see below).
4. Draw the extra sprite frames: the spouse kiss (frame 28) and the wedding outfit (frames 36 to 38). See Sprites and portraits.
5. Optionally add portraits/Marriage.png for the wedding vows.
6. Start the game through SMAPI and read the log. Any empty frame is reported with its number.

Marriage content is only loaded when Marriageable = true. The files involved are:

NPCs/<NpcName>/
  Marriage.toml
  portraits/Marriage.png       (optional) portrait in the wedding outfit
  Schedule.toml                its [Marriage] table is the spouse schedule

Marriage.toml has up to three tables. Leave out the ones you do not need.

[Engagement]
AcceptMermaidPendant = "This... is a Mermaid Pendant, right? I will."
Engagement_Generic = "We are really doing this, huh?"

[Dialogue]
Good_0 = "Good morning, @."
Rainy_Day_0 = "Rain again..."

[Wedding]
Vows = [
  "I waited a long time for this day.$h",
  "I'll patch you up when you fall, @, and stay right next to you.$l",
]

[Engagement]#

These lines are said when the player proposes. Keys:

• AcceptMermaidPendant becomes <Name>0
• Engagement_Generic becomes <Name>1
• Vanilla-style keys for this NPC are also accepted and win over the mapped ones: <Name>0, <Name>1, <Name>Roommate0, ...
• Keys that belong to other NPCs are ignored.

[Dialogue]#

The NPC's dialogue while married. Use the game's marriage key formats (Rainy_Day_*, Good_*, OneKid_*, patio_<Name>, ...).

The spouse schedule: the [Marriage] table of Schedule.toml#

Same stop and key syntax as the main schedule (both ways of writing a stop work), in its own table next to [Schedule]:

[Schedule]
Weekday = ["600 Town 10 12 2"]

[Marriage]
Weekday = ["6:00 FarmHouse x=20 y=4 face=down"]
summer_12 = ["900 Farm 20 20 2"]

NPC Helper 2 writes it under the game's marriage_ keys alongside the normal schedule. A [Marriage] table needs Marriageable = true; without it the table is ignored with a warning. In locale/<lang>/Schedule.toml a [Marriage] table replaces the base one. The game only reads those keys while the player is married to the NPC, so NPC Helper 2 does not track marriage state.

What the game reads for a spouse, in this order: marriage_<festival>_<day> then marriage_<festival> for each active passive festival, marriage_<season>_<day>, marriageJob (tried only for the vanilla NPCs Penny, Maru and Harvey, so never for a custom NPC), then marriage_<Mon..Sun>. The weekday key is only tried when it is not raining. There is no spouse key for season + weekday, for rain, for hearts, or a plain season. NPC Helper 2 therefore:

[Wedding]#

The wedding ceremony is the game's own. Vows are the lines the NPC says in it, one per entry, after the officiant's words and before the kiss. NPC Helper 2 gives the NPC its own wedding script made of the game's default script plus the vows, so the ceremony, guests, music and kiss stay the game's. While the NPC speaks, portraits/Marriage.png is shown (the normal portrait without it).

• A vow is plain dialogue text, so $h, $l and @ work. It cannot contain ", /, [, ] or a line break (the event script has no way to hold them); such a vow is skipped with a warning.
• Without Vows the NPC uses the default wedding.
• If a game update changes the default script so the vows no longer fit, NPC Helper 2 logs a warning and the NPC uses the default wedding.
• In locale/<lang>/Marriage.toml, Vows replace the base lines.

The wedding outfit#

In the ceremony the game shows the spouse in frames 36, 37 and 38 of their sprite sheet (row 10 of sprites/Default.png: facing the guests, turning to the farmer, the kiss), not in a separate wedding image. Draw the wedding outfit there. A sheet with nothing in those frames shows an invisible NPC at the wedding.

For the everyday spouse kiss, the game uses frame 28 (the first cell of row 8, x 0 and y 224 in a 16x32 sprite sheet), facing right by default. The game uses this one pose and mirrors it horizontally when needed; it doesn't select separate front/back kiss poses. Custom NPC sprite sheets should include a kiss pose there; an empty frame makes the NPC disappear during the kiss. NPC Helper checks the kiss frame and the three wedding frames of every marriageable NPC (in sprites/Default.png and each variant) and warns, naming the frame, when one is empty or beyond the end of the sheet.

portraits/Marriage.png#

Without the file the normal portrait is used. It is shown while the NPC speaks their wedding vows. The game never shows it anywhere else on its own.

Roommate dialogue#

The game also has separate engagement and married dialogue for roommate spouses. NPC Helper 2 passes the <Name>Roommate0 and <Name>Roommate1 engagement keys through [Engagement], but does not provide roommate married dialogue.

Not supported#

Stardew Valley 1.6 changed how these work, so the 1.x versions of these features no longer apply:

• Whole custom wedding events (wedding_event.toml in 1.x). The game now builds weddings from its own data; use [Wedding] Vows to add the NPC's lines to it.
• Spouse room and patio (spouse_room.toml, patio.toml in 1.x). The game now stores these with the character data and they need map assets. NPC Helper 2 does not provide them yet.

Localization#

NPCs/<Name>/locale/<lang>/Marriage.toml:

• [Engagement] and [Dialogue] entries are merged over the base file (locale keys override).
• The spouse schedule is not in this file: a [Marriage] table in locale/<lang>/Schedule.toml replaces the base one.
• Locale fallback: xx-YY then xx.

An old marriage/ folder from 1.x is not read; if one is found the NPC reports where its content goes now.