Content Pack Structure | NPC Helper 2 Docs

Standard layout#

Each content pack goes in its own folder under Stardew Valley/Mods/:

text

[Author] PackName/
├── manifest.json
└── NPCs/
    └── Rei/
        ├── Rei.toml
        ├── Dialogue.toml
        ├── Schedule.toml
        ├── Marriage.toml
        ├── sprites/
        │   ├── Default.png
        │   ├── Hospital.png
        │   └── summer.png
        ├── portraits/
        │   ├── Default.png
        │   ├── Marriage.png
        │   └── Hospital.png
        └── locale/
            └── th/
                ├── Rei.toml
                ├── Dialogue.toml
                ├── Schedule.toml
                └── Marriage.toml

Only the pack manifest and each NPC's main TOML file are needed for a basic character. The other TOML files separate dialogue, schedules, or marriage content; image and locale folders are optional.

Files and folders#

Path	Purpose
`manifest.json`	SMAPI metadata for the content pack. `ContentPackFor.UniqueID` must be `Framework.Mod.NpcHelper`.
`NPCs/<Name>/<Name>.toml`	Main NPC definition. The folder name and file name conventionally match the NPC's internal name.
`NPCs/<Name>/Dialogue.toml`	Optional `[Dialogue]` table.
`NPCs/<Name>/Schedule.toml`	Optional `[Schedule]` and `[Marriage]` tables.
`NPCs/<Name>/Marriage.toml`	Optional `[Engagement]`, spouse `[Dialogue]`, and `[Wedding]` tables.
`NPCs/<Name>/sprites/`	Main sprite sheet and optional location or season variants.
`NPCs/<Name>/portraits/`	Main portrait sheet and optional variants; `Marriage.png` is the optional wedding portrait.
`NPCs/<Name>/locale/<language>/`	Optional translated TOML files, using the same names as the base files.

How NPC definition files are found#

NPC Helper 2 looks for NPC definitions in the pack's NPCs/ folder. It recognizes:

A TOML file directly inside NPCs/.
A folder containing <FolderName>.toml.
If that named file is absent, other TOML files directly inside the folder.

Dialogue.toml, Schedule.toml, and Marriage.toml are supporting files, not NPC definitions. TOML files inside locale/ are translations, not additional NPCs.

An optional mod.toml at the pack root can restrict which NPC definition paths to load:

toml

NPCs = ["NPCs/Rei/Rei.toml"]

Without this file, all discovered NPC definitions in the pack are considered.

Naming rules#

Keep names consistent between the NPC's folder, main TOML file, and Name value.
The internal name must be 1–64 Unicode letters, combining marks, digits, _, or -. Do not use spaces, dots, or slashes.
File and folder matching is case-insensitive.
Image variants are selected by their file name. Use names such as Hospital.png or summer.png; avoid dots in variant names.
Put images only in sprites/ and portraits/. File paths are convention-based and are not configured in TOML.

See Sprites & Portraits for image formats and variant rules.