NPC Helper 2/Docs

For Developers

Command-line tool

Install npchelper and use it to create packs, add NPCs and translations, check packs, and package them for release.

npchelper is a command-line tool for people who make NPC mods. It creates starter packs, checks packs the way the game reads them, and packages packs for release. It works on the same content-pack format as hand-written packs, so you can mix both.

Install#

The tool is a .NET tool installed from NuGet.

sh
dotnet tool install -g NpcHelper.StardewValley.Cli

To update it later:

sh
dotnet tool update -g NpcHelper.StardewValley.Cli

Check that it works:

sh
npchelper --help

Use npchelper <command> --help for the options of one command.

Commands#

npchelper new pack#

Creates a new content pack that you edit by hand.

sh
npchelper new pack "[HP] MyPack" --id Me.MyPack --npc Rei
  • The first argument is the folder to create.
  • --id is the pack's unique ID, written into manifest.json.
  • --npc names the first NPC. The pack includes a starter NPC file and valid placeholder images, so it loads straight away.

npchelper new npc#

Adds another NPC to an existing pack.

sh
npchelper new npc "[HP] MyPack" Alex

npchelper new translation#

Creates a translation content pack for an existing NPC. It writes the correct layout and sets Locales and Translates in mod.toml. Run npchelper new translation --help for its options.

npchelper new dll-mod#

Creates a C# SMAPI mod that defines NPCs in code. See C# SDK.

sh
npchelper new dll-mod MyMod --id Me.MyMod --npc Rei

npchelper validate#

Checks a pack the way the game will read it and prints every error and warning.

sh
npchelper validate "[HP] MyPack"

It reports bad values, unknown keys, and the pack-structure mistakes listed in Pack structure, including misnamed folders and files, language folders such as th_TH, and translations for an NPC that does not exist.

It also checks packs that change an NPC from another mod. For an outfit pack or a portrait pack it lists what the pack changes, for example Outfit pack for Rei: sprites Beach_Summer; portraits Beach_Summer., and warns when mod.toml sets PortraitScale but the pack has no portraits.

Options:

  • --base <folder> is the folder of the pack that adds the NPC. For a translation pack it reports keys that do not exist there and how much is still untranslated. For a translation, outfit or portrait pack it also checks that manifest.json lists that pack in Dependencies.
  • --locale th loads the NPC with that language applied.
  • --strict makes warnings fail the command, which is useful in a build script.

npchelper inspect#

Shows how a pack is understood.

sh
npchelper inspect "[HP] MyPack"

npchelper pack#

Creates a zip of a pack for upload.

sh
npchelper pack "[HP] MyPack"

It refuses to package a pack that has structure problems. Add --force to package it anyway. It works for NPC packs, translation packs, outfit packs and portrait packs.

A typical workflow#

  1. npchelper new pack "[HP] MyPack" --id Me.MyPack --npc Rei
  2. Edit the TOML files and replace the placeholder images.
  3. npchelper validate "[HP] MyPack" until clean.
  4. Copy the folder into Mods and test in the game.
  5. npchelper pack "[HP] MyPack" and upload the zip.

See Test and publish.

All versions