NPC Helper 2/Docs

Create an NPC

Test and publish

Check an NPC pack before the game starts, test it in game, package it as a zip, and release it with the right manifest settings.

This page takes a finished pack from your Mods folder to a release other players can install.

The npchelper tool reads your pack the same way the game does, so it finds problems before you start Stardew Valley. Install it once; see Command-line tool.

sh
npchelper validate "MyFirstNPC"
npchelper inspect "MyFirstNPC"
  • validate reports errors and warnings: bad values, unknown keys, and misnamed folders and files.
  • inspect shows how the pack was understood, so you can compare it with what you meant.

Fix everything validate reports, then run it again until it is clean.

Step 2: Test in the game#

  1. Start Stardew Valley through SMAPI.
  2. Read the NPC Helper 2 summary in the console. Each NPC is listed under its pack with its errors and warnings.
  3. Load a save and check, in this order:
    • The NPC is in the Social tab, with the right name.
    • They appear at their home and follow the schedule. Test a weekday, a weekend day, a rainy day, and their birthday.
    • Their dialogue plays with the right portraits.
    • Gifts: give an item from each taste group and read the reactions.
    • Sprites and portraits change correctly in each variant location and season.
    • If marriageable: propose, marry, and check the kiss and the wedding.
    • Heart events and festival lines, if you made them.
  4. Change the game's language and check each translation you ship.

If something is wrong, see Troubleshooting for authors.

Step 3: Prepare the manifest for release#

Open manifest.json and check:

Setting Check
Version Raise it for every release.
UniqueID Unique, and never changed after release.
ContentPackFor.UniqueID Framework.Mod.NpcHelper.
ContentPackFor.MinimumVersion The oldest NPC Helper 2 version your pack works with. Use 2.4.0 if you use heart events or festival lines, and at least 2.2.0 if you use PortraitScale or <Location>_<Season> image variants.
UpdateKeys Optional. Lets SMAPI tell players about updates, for example ["Nexus:12345"] with your mod page's number.

Step 4: Package it#

sh
npchelper pack "MyFirstNPC"

This creates a zip you can upload. It refuses to zip a pack that has structure problems. If you must package anyway, add --force; players will then see the same warnings.

A good zip contains one folder with manifest.json and NPCs inside it, so players can extract it straight into Mods.

Without the tool, zip the pack folder yourself so that the folder, not its contents, is at the top level of the zip.

Step 5: Publish#

  1. Upload the zip to your mod page.
  2. In the description, say the mod requires NPC Helper 2 and link its page, and name the minimum version.
  3. Tell players to install it like any content pack (Install NPC mods and translations).
  4. Note any other requirements, such as the translations you provide.

Releasing translations#

A translation is its own content pack. Create it with npchelper new translation, put the locale files under NPCs/<Npc>/locale/<code>/, and set Locales and Translates in mod.toml. See Localization. Package and publish it the same way, and tell players that the NPC mod must be installed too.

Releasing an update#

  1. Raise Version in manifest.json.
  2. Run npchelper validate again and test in game.
  3. Package and upload the new zip.
  4. Say in the changelog if players must also update NPC Helper 2.
Report a documentation issueAll versions