Make a portrait pack

A portrait pack gives an existing NPC new faces in dialogue and nothing else. It is its own mod with its own manifest.json, so players can choose to install it and a mod manager can update it. It is the right kind of pack for high-resolution portraits or a different art style. It needs NPC Helper 2.4.3 or later.

A pack with portraits and sprites is an outfit pack. The kinds are compared on Kinds of packs, and the rules for choosing between images from several mods are on Replacing images from other mods.

Step 1: Look at the NPC's portraits#

Open the NPC's mod folder and its NPCs/<Npc>/portraits folder. Note:

• The NPC's name (the folder's name inside NPCs) and the mod's UniqueID from its manifest.json.
• Which files it has: Default.png, Marriage.png and any variants such as Hospital.png or summer.png.
• The size of the main sheet. 128 pixels wide means the NPC uses the game's normal size. 256 pixels wide means the NPC's mod sets PortraitScale = 2.
• How many faces the sheet has and in what order. The faces are numbered left to right, top to bottom, and the dialogue chooses a face by that number ($h for happy, $s for sad, and so on). See Dialogue.

Step 2: Make the folder#

Anime Portraits/
├── manifest.json
├── mod.toml
└── NPCs/
    └── Rei/
        └── portraits/
            ├── Default.png
            ├── Marriage.png
            └── Hospital.png

The folder inside NPCs must be named exactly like the NPC. A portrait pack has no sprites folder. If you add one, the pack becomes an outfit pack.

Step 3: Write manifest.json#

{
  "Name": "Dr. Rei - Anime Portraits",
  "Author": "You",
  "Version": "1.0.0",
  "UniqueID": "You.Rei.AnimePortraits",
  "Description": "Redrawn portraits for Rei.",
  "MinimumApiVersion": "4.0.0",
  "ContentPackFor": {
    "UniqueID": "Framework.Mod.NpcHelper",
    "MinimumVersion": "2.4.3"
  },
  "Dependencies": [
    {
      "UniqueID": "TamKungZ.Rei.NPC",
      "IsRequired": true
    }
  ]
}

Step 4: Write mod.toml#

NPCs = ["NPCs/Rei/"]
PortraitScale = 2

NPCs is optional. It names the NPC, and NPC Helper 2 checks that the folder has something for her. PortraitScale is explained next.

Choose the portrait scale#

Portraits are read at a scale. At scale 1, the game's normal size, a face is 64 by 64 pixels and the sheet is 128 pixels wide (two faces across). At scale 2 a face is 128 by 128 and the sheet is 256 pixels wide. NPC Helper 2 scales every selected portrait down to the game's size.

PortraitScale in a portrait pack's mod.toml is the scale of the pack's own portraits. It replaces the NPC's own value for them, so a high-resolution pack works for an NPC whose own portraits are normal size:

When the pack does not set PortraitScale, its portraits follow the NPC. Set it whenever your art is not the same scale as the NPC's own, and say so on your mod page.

• The value applies to every portrait in your pack, including Marriage.png and every variant, and for every NPC in it. If you need two scales, make two packs.
• It applies only to your portraits. The NPC's other portraits, the ones your pack does not replace, keep her own scale.
• The only values are 1 and 2. Any other value is reported as an error and ignored.
• A 2x sheet that is not 256 pixels wide, or whose height is not a multiple of 128, cannot be loaded. SMAPI logs A 2x portrait sheet must be 256 pixels wide and a multiple of 128 pixels high, and the portrait is not shown correctly.
• If you set PortraitScale and the pack has no portraits, NPC Helper 2 warns that there is nothing for it to apply to.

Step 5: Choose which images to provide#

The most important point: a portrait you do not replace keeps the NPC's own art. If you only provide Default.png and the NPC's mod also has portraits/Hospital.png, her original portrait is still shown in the Hospital. To restyle her completely, provide an image for every file in the NPC's portraits folder. If the NPC's own Hospital.png is normal size and yours is 2x, that is fine: each file is read at the scale of the mod it comes from.

• Keep the faces in the same order. The dialogue asks for a face by number, so your sheet needs a face for every number the NPC's dialogue uses, in the same order as hers. A face your sheet does not have cannot be shown.
• Variant names work as described on Image variants: a location, a season, both, or a festival.

Step 6: Test it#

1. Install the NPC's mod and your pack, start the game through SMAPI, and read the log. It names your pack:

   text

   Portrait pack for Rei: portraits Default, Marriage, Hospital (PortraitScale 2). Default replaces the NPC's own image, any other name is an outfit.
   portraits/Default.png comes from mod 'Dr. Rei - Anime Portraits', replacing the NPC's own pack.
   

2. Talk to the NPC. Check every expression, not only the neutral face.

3. Check the places and seasons that have their own portrait.

4. For a marriageable NPC, check the wedding vows.

5. Optionally run npchelper validate "Anime Portraits" --base "[HP] ReiMod". See Command-line tool.

Step 7: Publish#

1. Raise Version for every release, and run npchelper pack "Anime Portraits". See Test and publish.
2. In the description, say the pack requires the NPC's mod and NPC Helper 2.4.3, and link both.
3. Say which images it replaces, and whether it covers every variant the NPC has.
4. Say that it conflicts with other portrait mods for the same NPC. Only one of them is shown for each image. See Replacing images from other mods.