NPC Helper 2/Docs

Create an NPC

Troubleshooting for authors

Find and fix common problems in an NPC pack: NPC missing, ignored settings, images, schedules, dialogue, marriage, events, and translations.

NPC Helper 2 reports content problems in the SMAPI console and log. Search for NpcHelper, your pack's name, or the NPC's name. Each message names the file, line, and setting. Running npchelper validate finds most problems before you start the game (Test and publish).

The NPC does not appear#

  1. Confirm Stardew Valley 1.6 or later and SMAPI 4.0 or later.
  2. Confirm NPC Helper 2 and your pack are directly inside Mods.
  3. Check that manifest.json has ContentPackFor.UniqueID set to Framework.Mod.NpcHelper.
  4. Check that the NPC file is under NPCs/ and follows the naming rules in Pack structure.
  5. Read the log for the exact file, line, setting, or rejected value.
  6. If mod.toml has an NPCs list, check the NPC is in it, and is not in Exclude.

A setting or table is ignored#

Check spelling and placement. [Dialogue] is valid and [Dialgue] is not. Quote text values, and check that each setting is in the right table. Unknown keys and tables are reported so you can correct them. Setting StrictToml = true in mod.toml turns TOML typos into errors.

The log mentions a pack-structure problem#

Packs laid out by hand are checked for misspelled or misplaced folders and files (NPCs, locale, sprites, portraits), language folders named th_TH, Dialog.toml for Dialogue.toml, non-.toml files, and misnamed manifest.json or mod.toml. Fix the name the message points to. See Pack structure.

The NPC has no sprite or portrait#

  • Check the names: sprites/Default.png and portraits/Default.png.
  • Check that the files are in the right NPC folder and are real PNG files.
  • Check the frame grid (Sprites and portraits).
  • If a variant is missing, the next fallback is used: location, then season, then the default image.
  • Portraits that look cropped or doubled: check PortraitScale. With PortraitScale = 2 every portrait file, including variants and Marriage.png, must be double size.

The NPC disappears while kissing or at the wedding#

A required sprite frame is empty. NPC Helper 2 warns and names it: the spouse kiss is frame 28 and the wedding frames are 36 to 38. Draw those frames in Default.png and in every variant. See Sprites and portraits.

The schedule is not working#

  • Check key spelling and use the game's weekday, season, date, and festival names.
  • Use a time the game can read: 600 to 2600 in 10-minute steps, or a clock time.
  • Make sure two stops under one key do not share a time.
  • Check every stop has a valid tile and a valid location name.
  • A more specific key can take priority over a weekday routine; see Schedules.
  • Pick tiles the NPC can walk to and reach in time.

Dialogue or gifts behave unexpectedly#

  • Check dialogue keys and special text against the Stardew Valley dialogue page.
  • Gift taste lists go in [GiftTastes]. Gift reaction lines go in [Dialogue]. See Gift tastes.
  • Use an item ID or a valid English item name when a gift is not recognised.

Marriage content is missing#

  • Set [Romance] Marriageable = true.
  • Put engagement, spouse dialogue, and vows in Marriage.toml.
  • Put the spouse routine in the [Marriage] table of Schedule.toml.
  • Draw frames 28 and 36 to 38. See Marriage.

A heart event or festival line does not play#

  • Require NPC Helper 2.4.0 or later in manifest.json.
  • An event with a bad step, unknown emote, bad direction, or a / in its text is skipped. The log names the step. The NPC and other events still load.
  • An event ID is <Npc>_<EventName>. If the game or another mod already uses it, yours is left out.
  • NPC Helper 2 adds festival lines but does not place the NPC on the festival map yet. See Heart events and festivals.

A translation does not apply#

  • The language folder must be a code such as th, es-ES, or pt-BR, and the file names must mirror the NPC folder.
  • A translation pack must be a content pack for NPC Helper 2, with manifest.json set to Framework.Mod.NpcHelper.
  • Set Locales and Translates in the translation's mod.toml. NPC Helper 2 then reports a missing language, or an NPC that is not loaded.
  • See Localization for merge order.

Still stuck?#

Update NPC Helper 2 and SMAPI. Reproduce the problem with only your pack and NPC Helper 2 installed. Read the first warning or error related to your pack in the SMAPI log. When asking for help, give the NPC Helper 2 version and the log messages, and do not share save data or unrelated personal information.

Report a documentation issueAll versions