Tools & API

Hand-written TOML is enough for a normal content pack. Mod authors can also use the optional CLI, C# SDK, or public SMAPI API.

Command-line tool#

Install the npchelper tool from NuGet:

dotnet tool install --global TamKungZ.NpcHelper.Cli

Useful commands:

npchelper new pack "[HP] MyPack" --id HP.MyPack --npc Rei
npchelper new npc "[HP] MyPack" Alex
npchelper validate "[HP] MyPack"
npchelper inspect "[HP] MyPack"
npchelper pack "[HP] MyPack"

The tool creates or checks the same content-pack format described in Content Pack Structure. Use npchelper <command> --help for command options.

C# SDK#

Install NpcHelper.StardewValley.Sdk from NuGet:

dotnet package add NpcHelper.StardewValley.Sdk

This command requires the .NET 10 SDK or later. With the .NET 9 SDK or earlier, use:

dotnet add package NpcHelper.StardewValley.Sdk

The SDK lets you define NPC data in C# and write a standard TOML content pack:

using NpcHelper.Sdk;

var npc = new NpcBuilder("Rei")
    .DisplayName("Rei the Baker")
    .Gender(Gender.Female)
    .Birthday(Season.Summer, 12)
    .Spawn("Town", 10, 12)
    .Introduction("Hi! I'm Rei.")
    .Loves("Diamond", "Coffee")
    .OnWeekdays(schedule => schedule.At(600, "Town", 10, 12));

var result = new NpcPackBuilder("HP.ReiPack", "Rei Pack")
    .Author("HP")
    .Add(npc)
    .WriteTo("output/[HP] ReiPack");

The generated pack still needs NPC Helper 2 installed in the player's game. See the pack guide for its structure and NPC Definition for supported values.

Public SMAPI API#

Another SMAPI mod can request the public API after NPC Helper 2 is loaded:

var api = helper.ModRegistry.GetApi<INpcHelperApi>("Framework.Mod.NpcHelper");

The API supports registering an NPC from TOML, registering a typed NPC definition, and querying registered NPC names:

bool RegisterNpcFromToml(string name, string toml, string sourceDirectory);
void RegisterNpc(string name, NpcDefinition data);
bool IsNpcRegistered(string name);
IReadOnlyList<string> GetRegisteredNpcNames();

RegisterNpcFromToml is recommended for integrations because it passes plain text across the mod boundary. Call the API at game launch or later. If an NPC needs separate dialogue, schedule, image, or locale files, provide its content folder as sourceDirectory; pass null when it has no supporting files. Check the return value and SMAPI log when registration fails.

Choose a workflow#