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.

A pack can also add no NPC and only change one from another mod: a translation, an outfit, or new portraits. Those are described on Kinds of packs.

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: festivals (her place and 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"]
EmbedLocales = ["es-ES"]
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.

An entry can also be an NPC folder, such as NPCs/Rei/:

• If the folder has an NPC file in it, that NPC is loaded, just as if you had listed the file.

• If it does not, the entry says that the pack changes this NPC without defining it. This is what a translation pack, an outfit pack or a portrait pack does:

  toml

  NPCs = ["NPCs/Rei/"]
  

The folder form is optional. NPC Helper 2 finds the translations and images of a pack without it, and NPCs = [] and leaving NPCs out work too. The entry only lets NPC Helper 2 check your pack more precisely: it warns when the folder holds no translation, no sprites and no portraits, and it checks at startup that an NPC with that name is loaded.

• The folder must be directly inside NPCs/. The / at the end is optional.
• A folder that does not exist is an error, like a missing NPC file.
• The name must be a valid NPC name (see Naming rules).
• A pack that changes an NPC with images needs NPC Helper 2.4.3 or later. See Kinds of packs.

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.

In a pack that changes an NPC from another mod, PortraitScale is the scale of the pack's own portraits, and it replaces the NPC's own value for them. Without it, the pack's portraits follow the NPC they change. See Choose the portrait scale. NPC Helper 2 warns when a pack sets it but has no portraits.

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.

EmbedLocales#

For an NPC pack that has locale/<code>/ folders of its own. It lists the languages you ship with the NPC. Any other language folder in your pack is treated as a legacy translation that someone copied in by hand. A regional folder follows its language: listing th also covers locale/th-TH.

EmbedLocales = ["es-ES", "th"]

Without this setting, NPC Helper 2 guesses from the files (see Embedded or legacy). Set it when you want the log to label your folders correctly. An empty list, EmbedLocales = [], says that none of the folders are yours. A listed language with no folder is reported at startup. Older versions of NPC Helper 2 report the setting as unknown and ignore it, so require version 2.4.1 or later in manifest.json if you use it.

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, a festival, or a location and season: Hospital.png, summer.png, Hospital_Summer.png, spring13.png. Avoid dots in variant names. See Image variants.
• Images from another mod. Another content pack can add images to your NPC, or replace yours, by using the same folders and names under its own NPCs/<Npc>/. See Replacing images from other mods.
• 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: no NPC, no translation, and no sprites or portraits for an NPC.
• A translation folder, or an image folder, whose NPC does not exist (the message says which NPC you probably meant).
• An NPCs entry that is a folder with no translation, sprites or portraits in it, or that is not directly inside NPCs/.
• PortraitScale in a pack that has no portraits.

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.