Make an outfit pack

An outfit pack gives an existing NPC other clothes, or replaces her sprite, without touching the NPC's own mod. It is its own mod with its own manifest.json, so a mod manager can update it and players can choose whether to install it. It needs NPC Helper 2.4.3 or later.

This page is for an NPC you did not make. If the NPC is yours, put the images in your own pack: see Image variants. If you only want to give an NPC new faces, see Make a portrait pack. The rules for choosing between images from several mods are on Replacing images from other mods. The kinds of pack are compared on Kinds of packs.

What an outfit pack can do#

• Add an outfit that is worn in a place, in a season, in both, or at a festival.
• Replace the NPC's main sprite (Default.png), and her main portrait.
• Replace the NPC's wedding portrait (portraits/Marriage.png).
• Replace one of the NPC's own outfits, by giving an image the same name.
• Do all of that for several NPCs in one pack.

It cannot change what the NPC says or does, only how she looks. An outfit is chosen by place, season and festival. It cannot depend on the weather, the time of day, or friendship.

Step 1: Find the NPC's name and mod ID#

1. Open the NPC's mod folder. Inside NPCs, the name of the NPC's folder is the NPC's name, for example NPCs/Rei for Rei. The name in the NPC Helper 2 summary in the SMAPI console is the same.
2. Open the NPC mod's manifest.json and note its UniqueID, for example TamKungZ.Rei.NPC. You need it for the dependency.
3. Look at the NPC's sprites and portraits folders. They show which outfits already exist, what size the images are, and whether the portraits use PortraitScale = 2 (see Portraits).

Step 2: Make the folder#

Beach Outfit/
├── manifest.json
├── mod.toml                         optional
└── NPCs/
    └── Rei/
        ├── sprites/
        │   └── Beach_Summer.png
        └── portraits/
            └── Beach_Summer.png

The folder inside NPCs must be named exactly like the NPC. You write no paths in any file: the images are found by their place and name.

Step 3: Write manifest.json#

{
  "Name": "Dr. Rei - Beach Outfit",
  "Author": "You",
  "Version": "1.0.0",
  "UniqueID": "You.Rei.BeachOutfit",
  "Description": "Gives Rei a summer outfit at the Beach.",
  "MinimumApiVersion": "4.0.0",
  "ContentPackFor": {
    "UniqueID": "Framework.Mod.NpcHelper",
    "MinimumVersion": "2.4.3"
  },
  "Dependencies": [
    {
      "UniqueID": "TamKungZ.Rei.NPC",
      "IsRequired": true
    }
  ]
}

• ContentPackFor.MinimumVersion is 2.4.3. An older NPC Helper 2 does not look for images in other mods.
• Dependencies names the NPC's mod and makes it required. SMAPI loads that mod first, and tells the player if it is missing.
• If the outfit needs a feature that only a newer version of the NPC's mod has (for example festival attendance), add a MinimumVersion to the dependency too.

Step 4: Add mod.toml (optional)#

mod.toml is not needed. NPC Helper 2 finds the images from the folders alone. If you add it, name the NPC the pack changes:

NPCs = ["NPCs/Rei/"]

NPC Helper 2 then checks that NPCs/Rei/ holds something for the NPC, and warns if it does not. NPCs = [] and leaving the file out are fine too. A pack with several NPCs lists each folder:

NPCs = ["NPCs/Rei/", "NPCs/Mira/"]

If your portraits use a different scale than the NPC's own, add PortraitScale. See Make a portrait pack.

Step 5: Draw and name the images#

Draw the images in the same format as the NPC's own: a sprite sheet with 16 by 32 frames (Sprites) and portraits with 64 by 64 faces (Portraits). The file name decides when the outfit is worn:

• The location is the game's exact location name, such as Beach, Town or Hospital. Seasons are spring, summer, fall and winter. Capitalisation does not matter. Avoid dots in the name.
• Sprites and portraits are chosen independently. You can add an outfit for the sprite without a portrait, or the other way round.
• The more specific name wins: festival, then location and season, then location, then season, then Default.png. See Image variants.
• A festival outfit is only worn while the NPC is at that festival. That needs the NPC's own mod to bring her there. See Festivals.

Step 6: Draw the frames the NPC needs#

An outfit sprite is used for every frame the game asks for while it is worn. If the sheet has nothing in a frame, the NPC is invisible in that pose.

• A walking outfit for a place or a season needs the four walking rows: 128 pixels tall.
• A marriageable NPC also uses frame 28 for the spouse kiss, frames 36 to 38 at the wedding, and the sleeping frame set as SleepFrame in [Home] of her NPC file. Draw them if the outfit can be worn while those happen.
• A replacement for Default.png is used everywhere, so it needs all of them. NPC Helper 2 checks the sprite it uses for those frames and warns about each empty one.
• NPC Helper 2 does not check the other outfits that come from another mod. Check them yourself by going to the place and season.

The frames are listed on Sprites.

Step 7: Test it#

1. Install the NPC's mod and your pack in Mods, and start the game through SMAPI.

2. Read the log. It names your pack and what it found:

   text

   Outfit pack for Rei: sprites Beach_Summer; portraits Beach_Summer. Default replaces the NPC's own image, any other name is an outfit.
   

   A warning here means a mistake in the pack: see Troubleshooting for authors.

3. Go to the place in the right season, or the festival, and check the sprite. Talk to the NPC there and check the portrait.

4. If you replaced Default.png, check the kiss, the wedding and the sleeping pose too.

5. Optionally run the checker. See Command-line tool:

   sh

   npchelper validate "Beach Outfit" --base "[HP] ReiMod"
   

   It lists what the pack changes, warns about a PortraitScale with no portraits, and checks that manifest.json requires the NPC's mod.

Step 8: Publish#

1. Raise Version for every release.
2. Run npchelper pack "Beach Outfit" to make the zip. See Test and publish.
3. In the description, say the pack requires the NPC's mod and NPC Helper 2.4.3, and link both.
4. Say where the outfit is worn, for example "at the Beach in summer", so players know where to look.
5. If the pack replaces Default.png, say that it changes her everywhere, and that it conflicts with other mods that do too.

Examples#

A seasonal outfit for a place: sprites/Beach_Summer.png and portraits/Beach_Summer.png. She wears it at the Beach in summer and her usual clothes everywhere else.

A winter coat: sprites/winter.png and portraits/winter.png. She wears it in winter wherever she is, unless an outfit for the place and the season, or the festival, applies.

A festival dress: sprites/spring24.png and portraits/spring24.png. She wears it at the Flower Dance, if the NPC's mod brings her there.

A whole new look: sprites/Default.png and portraits/Default.png. They replace her sprite and her main portrait. Her own variants from the NPC's mod (for example Hospital.png) still apply in their places, so provide an image for each of them too if you want the new look everywhere.

Several NPCs: put a folder for each under NPCs. The pack's mod.toml lists them all.