NPC Helper 2/Docs

NPC Helper 2

NPC Helper 2 adds custom NPCs to Stardew Valley from plain text files, with translations, outfits and portraits as separate packs. Find the guide for players, NPC mod authors, or C# developers.

NPC Helper 2 is a SMAPI mod for Stardew Valley 1.6 that adds custom NPCs to the game. An NPC is described in readable TOML text files plus a few PNG images, and NPC Helper 2 puts everything into the game when it starts: the character, gift tastes, dialogue, daily schedule, sprites, portraits, and optional marriage content, heart events, festival lines, and translations. Writing an NPC mod needs no programming.

“HP” stands for “Helper.” NPC Helper 2 is just the beginning of the HP series—maybe House Helper will be next, lol.

Where to start#

Reference#

  • TOML syntax — what the file format allows.
  • Game options — every value the game fixes: personality, regions, item categories, and schedule keys.
  • Release notes — what changed in each version, including the 2.0.0 breaking changes.

What an NPC mod can contain#

Feature Where to read
Name, personality, birthday, home NPC definition
Gift tastes and gift reactions Gift tastes
Dialogue that depends on day, weather, hearts, and place Dialogue
Daily routines by weekday, season, date, weather, and hearts Schedules
The walking character, wedding frames and a sleeping pose Sprites
The face shown in dialogue, and the wedding portrait Portraits
Images that change with location, season and festival Image variants
Engagement, spouse dialogue and schedule, wedding vows, sleeping in the bed Marriage
Cutscenes at heart levels Heart events
Taking part in festivals Festivals
Another game language Localization, Translate your own NPC, Make a translation pack
Other clothes or faces for an NPC, from a separate mod Kinds of packs, Make an outfit pack, Make a portrait pack, Replacing images from other mods

Upgrading from 1.x#

NPC files are now grouped into tables such as [Personality] and [Home], schedules are lists of stops, marriage content is one Marriage.toml, and files are found by name instead of by configured paths. Invalid values now reject the NPC instead of crashing the game's data load. The game reports each old key it finds and where it lives now. The 2.0.0 entry in the release notes lists every breaking change.

External references#