Pack structure

An NPC mod is a content pack for NPC Helper 2. This page describes the complete layout, what each file is for, and the rules that decide how files are found. You never write file paths in your TOML: everything is found by its name and place.

The layout#

[Author] PackName/                     the pack folder (goes in Mods/)
  manifest.json                        required: SMAPI manifest
  mod.toml                             optional: pack settings
  NPCs/
    Rei/                               one folder per NPC
      Rei.toml                         the NPC itself
      Dialogue.toml                    optional: dialogue
      Schedule.toml                    optional: schedule, and the spouse schedule
      Marriage.toml                    optional: engagement, spouse dialogue, wedding vows
      Events.toml                      optional: heart events
      Festivals.toml                   optional: festival lines
      sprites/
        Default.png                    the main sprite sheet
        Hospital.png                   a variant used in the Hospital
        summer.png                     a variant used in summer
        Hospital_Summer.png            a variant used in the Hospital in summer
      portraits/
        Default.png                    the main portrait sheet
        Marriage.png                   portrait shown during the wedding vows
        Hospital.png                   a variant, same rules as sprites
      locale/
        th/                            one folder per language
          Rei.toml                     translated name and data
          Dialogue.toml                translated dialogue
          Marriage.toml                translated marriage text

Only manifest.json and one NPC file are required. Everything else is optional.

What each file does#

Keeping everything in one file#

Everything in Dialogue.toml and Schedule.toml can also live in the NPC file. A small NPC can put [Dialogue] and [Schedule] in Rei.toml and skip the other files.

If both exist:

• Dialogue entries from Dialogue.toml win over the same keys in Rei.toml.
• Schedules from both are added together.

mod.toml: optional settings#

mod.toml sits next to manifest.json. Every setting is optional, and NPC Helper 2 finds NPCs, translations, and images from the folders alone. The settings only let it check your pack more precisely.

Nothing in mod.toml repeats manifest.json. The name, version, author, unique ID, dependencies, and update keys stay in the manifest. A copy in mod.toml is reported and ignored, and unknown settings are reported too.

NPCs = ["NPCs/Rei/Rei.toml"]
Exclude = ["Draft", "Old"]
PortraitScale = 2
Locales = ["th", "pt-BR"]
Translates = ["Rei"]
StrictToml = true

NPCs#

The list of NPC files to load, as paths from the pack folder. Without it, every NPC found in NPCs/ is loaded. An empty list, NPCs = [], states that the pack adds no NPC, which is what a translation-only pack uses.

Exclude#

NPCs to skip by name, folder name, or path, for example drafts you are not ready to ship. A name that matches nothing is reported, so a typo does not go unnoticed.

PortraitScale#

Set PortraitScale = 2 to use portrait sheets with 128 by 128 faces instead of the game's 64 by 64. NPC Helper 2 scales the sheets down when it loads them. Every file in portraits/ must use the same scale, including Marriage.png and every variant. Without the setting, or with PortraitScale = 1, portraits are the normal size. A pack that uses this setting needs NPC Helper 2.2.0 or later in manifest.json.

Locales and Translates#

These are for packs that carry translations.

• Locales lists the languages the pack provides. A language with no files is reported.
• Translates lists the NPCs the pack translates. If none of them is loaded, NPC Helper 2 says so at startup.

They change nothing about what is loaded. They let NPC Helper 2 tell you a translation will not apply, or that a language folder is misnamed.

StrictToml#

Reads the pack's TOML files as strict TOML 1.0, so a typo becomes an error instead of a warning. Names stay case-insensitive. See TOML syntax.

How NPC files are found#

For each folder inside NPCs/, NPC Helper 2 looks for the NPC file in this order:

1. NPCs/<Folder>/<Folder>.toml.
2. NPCs/*.toml, files directly inside NPCs.
3. If a folder has no file named after it, every other .toml directly inside the folder.

These files are never NPCs: Dialogue.toml, Schedule.toml, Marriage.toml, Events.toml, Festivals.toml, mod.toml, and anything inside locale/.

Naming rules#

• Files are found by name. Dialogue.toml, Schedule.toml, Marriage.toml, Events.toml, Festivals.toml, sprites/*.png, and portraits/*.png need no setting in the TOML. There are no path settings at all.
• Images. Default.png is the main image. Marriage.png in portraits is the wedding outfit portrait. Every other name is a variant for a location, a season, or both: Hospital.png, summer.png, Hospital_Summer.png. Avoid dots in variant names. See Sprites and portraits.
• NPC names. The name (folder and Name setting) is 1 to 64 letters, combining marks, digits, _, or -. Unicode letters are fine. It becomes part of asset names, so use no spaces, dots, or slashes.
• Capitalisation. File and folder names are matched without regard to case, so a pack written on Windows also works on Linux and macOS.
• Language folders are language codes such as th, es-ES, pt-BR. See Localization.

Mistakes NPC Helper 2 reports#

The game ignores a wrongly named folder or file without any message, so NPC Helper 2 checks packs laid out by hand for the usual slips:

• A misspelled or misplaced NPCs, locale, sprites, or portraits folder.
• A language folder named th_TH or thai instead of a code such as th or th-TH.
• Dialog.toml instead of Dialogue.toml.
• Files that are not .toml where TOML is expected, or .toml files at the top of the pack.
• A manifest.json or mod.toml with the wrong name.
• An NPC file missing from the NPCs list in mod.toml.
• A pack that loads nothing.
• A translation folder whose NPC does not exist (the message says which NPC you probably meant).

Ordinary folders such as docs are not reported. Files left by mod managers are ignored. You can run the same checks before starting the game with npchelper validate; see Test and publish.

Moving a pack from 1.x#

The flat keys (Gender, DefaultMap, and so on), [[Schedule]] blocks, [Sprites] and [Portraits] tables, and the marriage/ folder of 1.x are no longer read. Each one is reported when the NPC loads, with where it lives now. The release notes list the full table under 2.0.0.