NPC Helper 2/Docs

Create an NPC

Heart events

Write heart events in plain words with Events.toml: when they play, the scene, and the steps.

An optional Events.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), or 2.5.0 if it writes times, places and waits the readable way shown below. To bring the NPC to festivals, see Festivals.

Step by step: add a heart event#

  1. Create Events.toml in the NPC's folder, next to the NPC file.
  2. Add one table named after your event, for example [RainyClinic]. The name must be unique in the file.
  3. Say when it plays: Location and Hearts are required. Add Weather, Time, Days, or After to narrow it.
  4. Say where everyone stands: Farmer and Npc are required, as "x=10 y=18 face=up".
  5. Write the Steps, one entry per line: speech, walking, emotes, and so on (see the step table below).
  6. Start the game through SMAPI and check the log. An event with a problem is skipped and the message names the step.
  7. To see it, give the NPC enough hearts, then enter the Location under the conditions you set.

Events.toml: heart events#

A heart event is a cutscene that plays once the player has enough hearts with the NPC. You describe the scene in plain words and NPC Helper turns it into the game's event script, so you never write the game's /-separated format, event IDs or friendship numbers. Each event is one table named after the event:

toml
[RainyClinic]
Location = "Hospital"
Hearts = 4
Weather = "rainy"
Time = "9:00-15:00"
Farmer = "x=10 y=18 face=up"
Npc = "x=8 y=12 face=down"
Steps = [
  "wait 0.5s",
  "Rei: You came in out of the rain. Sit down, I'll find you a towel.$h",
  "Rei walks down 2",
  "farmer faces left",
  "Rei emotes heart",
  "Rei: ...Don't tell the senior doctor I said that.$9",
]

That is the whole event. NPC Helper adds the music (none), the camera (on the NPC), the actors, skippable and the final end, and registers it in the game's Data/Events/Hospital with the right conditions.

When it plays#

Key Meaning
Location Where it plays: Town, Hospital, FarmHouse, Beach ... Required.
Hearts 1 to 14. Required.
Weather sunny, rainy ... Optional.
Time A range of the day: 9:00-15:00, 9am-3pm, 9am to 3:30pm, or the game's 900-1500. Between 6:00 and 2:00 the next morning. Optional.
Days ["Mon", "Tue"]. Optional.
After The name of another event in this file that the player must have seen first. Optional.
Conditions Anything else, in the game's own condition format (["f Harvey 500"]). Optional.

The scene#

Key Meaning
Farmer Where the player starts: "x=10 y=18 face=up". Facing is up, right, down or left, and defaults to down. Required.
Npc Where the NPC starts, written the same way. Required.
Others More characters, ["Harvey x=7 y=10 face=left"]. Optional.
Music A track name. Default: none.
Camera "x=10 y=12". Default: on the NPC.
Steps What happens, one step per entry. Required (or Script).

Steps#

Step What it does
Rei: text The character says it. The player does not speak in events; use message. Portrait codes ($h, $9) work as in dialogue.
wait 0.5s Pauses. Write the unit: 0.5s, 2 seconds or 500ms. A plain number (wait 500) is milliseconds.
Rei walks down 2 Walks that many tiles (2 or 2 tiles) in up, right, down or left.
Rei faces up / farmer faces left Turns.
Rei emotes heart An emote: question, angry, exclamation, heart, sleep, sad, happy, x, pause, videogame, music or blush.
Rei jumps A small jump.
music name / sound name Plays a track or a sound.
fade / unfade Fades the screen out and back in.
message text A message box.
raw command A command in the game's event format, for anything above does not cover.
end Ends the event. Added for you when left out.

Times, places and waits#

Times, places and waits can be written in words and units, so nobody has to guess what a bare number means. The older forms still work, so an existing Events.toml does not need to change.

What Readable (2.5.0) Older form, still accepted
Time of day "9:00-15:00", "9am-3pm", "9am to 3:30pm", "9-15" "900-1500"
A place "x=10 y=18 face=up" (the keys can come in any order) "10 18 up", "10,18,up"
A wait wait 0.5s, wait 2 seconds, wait 500ms wait 500
A walk Rei walks down 2 tiles Rei walks down 2

The same place forms work for Farmer, Npc, Others, Camera and the festival Position. The facing can be left out and is then down. A place with a repeated key, an unknown word or a negative number is reported with the form NPC Helper 2 expected.

A wait with a plain number below 50, such as wait 1, gets a warning: it is one millisecond, and you probably meant wait 1s.

Every name in a step must be in the scene: farmer, the NPC, or someone in Others. A step that is not understood, an unknown emote, a bad direction or a / in the text makes NPC Helper skip that event and say which step it was; the other events and the NPC still load. NPC Helper also notes when the NPC never speaks in her event.

The game's event ID is <Npc>_<EventName> (for example Rei_RainyClinic), so it cannot clash with another mod's. If the game or another mod already has that ID, yours is left out and a warning says so.

If you already have a game script#

Script takes the whole script the game's own way, one command per entry (music, viewport, actors, then the commands, with end last). It replaces Music, Camera, the actors and Steps; the conditions above still apply. See the Stardew Valley wiki page "Modding:Event data" for every command.

Translating events#

A translation pack can carry locale/<code>/Events.toml (a Texts list per event, in the order the lines are said). See Localization.

From C##

csharp
new NpcBuilder("Rei")
    .HeartEvent("RainyClinic", "Hospital", 4, e => e
        .Weather("rainy").Between(900, 1500)
        .Farmer(10, 18, Facing.Up).Npc(8, 12, Facing.Down)
        .Wait(TimeSpan.FromSeconds(0.5))
        .Say("You came in out of the rain.$h")
        .Walk("Rei", Facing.Down, 2)
        .Emote("Rei", "heart"));

The SDK writes Events.toml in the readable form (Time = "9:00-15:00", x=10 y=18 face=up, wait 500ms), so the pack needs NPC Helper 2.5.0. It refuses a negative tile, a negative wait, text with a /, an unknown emote or a backwards time range when you call the method, and reports a bad heart level or an incomplete scene when the NPC is validated.