Tutorial: Changing/Adding Portraits

PLEASE NOTE: XNB files are obsolete - content files should be unpacked and left unpacked. You can convert XNB files to CP files without loading the packed XNB using a converter, such as Pillow's.

Designing a new NPC? Or perhaps you just want to change out an existing one? Maybe you've found an old XNB mod and want to transcribe it into Content Patcher format so you don't risk breaking your game files? Here's some handy steps you can go about to achieve it.

(Why XNB replacement is discouraged)

Future infobox info: Lemurkat, April 28 2021

Getting Ready

1. Install Smapi if you haven't already
2. Install Content Patcher.
3. If you are creating your own portraits, you will need an image editing program. There are free ones like Gimp and Paint.net, but Asperite is my personal favourite (and fairly cheap, free if you compile it yourself).
4. You will need a program that you can use to write your code in. You can use Wordpad/Notepad, but Visual Studio Code or Note++ is a better option, since they will highlight syntax errors. I personally use Visual Studio Code.
5. If you are updating a dated xnb mod to run via Content Patcher, I highly recommend that you unpack both the xnb file from the game's original content folder, and the one you wish to replace it with. For the Sebastian one I linked above, it was made in 2016, so there is highly likely that more portraits may have been added. If there are additional portraits, you may need to do some editing yourself.

Creating Your Portraits

(Skip this step if you are translating an already created XNB mod)

Portraits measure 64x64 pixels, and are organized on a set format of 2 across. Some characters merely have one portrait (Dwarf), others may have a dozen, or more.

Numbered from top left you have:

$0 neutral, $1 Happy ($h)

$2 Sad ($s), $3 "unique" ($u)

$4 Love (blush) ($l), $5 angry ($a)

etc (note that for non datable characters they often have $4 angry which can lead to unexpected results!)

A few tips for designing your own portraits:

• If you wish to remain true to the vanilla style, use vanilla portraits for reference. This includes sampling colour palettes. Try not to make your character look too much like a vanilla one however, as people will notice and may think it is a re-sprite rather than an original character.
• Cut and paste your character across each panel (make sure they are lined up correctly!) and edit the expression.

If modifying an existing portrait, you will likely be editing the original ones. Don't reorganize their expressions! Otherwise you will lead to conflicts with vanilla or other mods, meaning that a character may blush instead of frowning or so forth.

Creating your Content Pack

1. Create a folder labelled "[CP] Ginger Sebastian" (or whatever)
2. Inside this folder, create an "assets" folder (this will make things look tidy)
3. Into this "assets" folder, copy the unpacked PNG file (with any edits you have made), or the XNB file from the mod you are translating (if it hasn't required editing).
4. Create a manifest for Content Patcher
5. Now you need to create the content.json page.

{  
    "Format": "1.22", //Minimal format of Content Patcher to use. Set it to most up to date current one at time of mod creation.

    "Changes": [
        {   "Action": "Load", //Load or EditImage
            "Target": "Characters/Portraits/Sebastian", //The file you want replaced in the Contents folder.
            "FromFile": "assets/Sebastian.xnb",//The file you want to replace it with.
            }
    ]
}

For original NPCs, you MUST load the portrait first, before applying any edits. But each Target can only be Loaded once, if you try and have two loading, then you will receive a message that "Two mods want to upload Characters/Portraits/Sebastian none will be applied". If you are replacing a vanilla character, then it'll default back to the vanilla portrait. If you are using a custom character, it will try and default to the vanilla one, which doesn't exist, so your character will disappear and you'll get an error message.

If you are using EditImage (recommended for if you are applying conditional changes, such as seasonal clothing), then the last one applicable will be the one applied.

For an original (Custom) character to appear in game, you need to have a portrait and a walking sprite.

"Sebastian is a Ginger" by Melkat - https://www.nexusmods.com/stardewvalley/mods/561