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).
  • 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.

An outfit or portrait pack does nothing#

  • The pack needs ContentPackFor.UniqueID set to Framework.Mod.NpcHelper in its manifest.json, and MinimumVersion of 2.4.3. NPC Helper 2 only looks in its own content packs, never in the rest of Mods.
  • The folder inside NPCs must be named exactly like the NPC (NPCs/Rei). Capitalisation does not matter, but spelling does. If the NPC is not loaded, the log says which NPC it probably meant.
  • The images go in NPCs/<Npc>/sprites and NPCs/<Npc>/portraits, as PNG files. Check the folder names.
  • The NPC's own mod must be installed and loaded. Add it to Dependencies in the manifest.
  • Read the log. A line such as Outfit pack for Rei: sprites Beach_Summer; portraits Beach_Summer. means NPC Helper 2 found your files. This pack does nothing explains why it found none.
  • mod.toml lists NPCs/Rei/, but that folder has no translation ... and no sprites or portraits means the folder in the NPCs list is empty or has no sprites or portraits PNG files.
  • NPC file 'NPCs/Ghost/' not found means an entry of NPCs points to a folder that does not exist. An entry such as Rei/ is reported because the folder is not directly inside NPCs/.
  • mod.toml sets PortraitScale, but the pack has no portraits means the setting has nothing to apply to. Remove it, or add portraits.

The outfit is not worn#

  • The file name decides when. Beach_Summer.png is the Beach in summer, Beach.png is the Beach in any season, summer.png is summer anywhere, and spring13.png is the Egg Festival. Use the game's exact location name. See Image variants.
  • Another mod can replace your image, or win over it. The log says which image was used and which it replaced. See Replacing images from other mods.
  • A festival outfit is worn only while the NPC is at the festival, and that needs the NPC's own mod to bring her there (Festivals).
  • A more specific outfit wins, for example one from the NPC's own mod for the same place and season. Give your file the same name to replace it.

A portrait pack looks wrong#

  • Check PortraitScale. It is the scale of your pack's portraits and replaces the NPC's. At 2 every portrait in your pack, including Marriage.png and every variant, must be 256 pixels wide with faces 128 by 128 and a height that is a multiple of 128. Without it, your portraits follow the NPC's scale. See Make a portrait pack.
  • A portrait you do not provide keeps the NPC's own art. Provide an image for each file in the NPC's portraits folder to restyle all of them.
  • The faces must be in the same order as the NPC's own, because dialogue asks for a face by number.

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. If the sheet comes from an outfit pack, NPC Helper 2 checks it when it replaces Default.png. It does not check outfits from another mod, so check those yourself.

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, and 2.4.2 for festival placement.
  • 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.
  • The NPC has to be placed at the festival. Add a table named after the festival ID to Festivals.toml, even an empty [spring13]. Without it she is not at that festival. See Festivals.

The NPC is missing, or in the wrong place, at a festival#

  • Check the table: [spring13], with the ID written exactly as the game does (spring13, spring24, summer11, summer28, fall16, fall27, winter8, winter25), and ContentPackFor.MinimumVersion of at least 2.4.2.
  • The log names a Position it could not read and says NPC Helper 2 picks a spot instead.
  • A Position in water, inside a wall or on a villager looks wrong in the game. The festival maps differ in the first year and later years, so check the tile in both, or leave Position out.
  • Another mod that changes the same festival can replace the NPC's entry. Test without it.

The festival outfit is not worn#

  • The file is named after the festival ID (sprites/spring13.png, portraits/Festival.png). Capitalization and _, - or a space between the season and the day are fine.
  • The outfit is only worn while the player is inside the festival, and only if the NPC is at the festival.
  • The log reports a second file for the same festival and says which one it uses.

A married NPC stands beside the bed instead of sleeping#

She has no sleeping pose. Draw one and set SleepFrame in [Home]. See A sleeping pose. If the log says the sleep frame is empty, that frame has nothing drawn in it.

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.
  • A separate content pack with the same language folder replaces the NPC mod's own (embedded) folder for that language. See Localization.
  • See Localization for merge order.

The log says a translation is incomplete, outdated, or legacy#

NPC Helper 2 compares each translation with its NPC at startup, for every language.

  • INCOMPLETE TRANSLATION: the NPC has lines the translation does not. Add them, or accept that they stay in the original language.
  • OUTDATED TRANSLATION: many lines are missing, or the translation's oldest file is more than 60 days older than the NPC's newest file. The translation was probably written for another version of the NPC. Update it.
  • (legacy) on a language folder inside your own NPC pack: NPC Helper 2 took it for a hand-copied translation. Add EmbedLocales = ["<code>"] for the languages you ship to mod.toml and require NPC Helper 2.4.1 or later.
  • A note about extra entries is not a problem.

See Translation checks at startup for what is compared and the thresholds.

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.

All versions