Tutorial: How to Add Portraits via HD Portraits

From The Stardew Modding Wiki
Tutorial: HD Portraits


This guide is for anyone who wants to add a portrait with tiles larger than 64x64 pixels to their game.

Base Game Portraits[edit | edit source | hide | hide all]

A base game portrait has tiles of 64x64 pixels, in two columns, and a number of rows dependent on the character.

SDV Vanilla Abigail Portraits.png

For example, Abigail's portrait file has 2 columns and 5 rows of 64x64 pixel tiles.

The purpose of HD Portraits is to surpass this limit and allow you to have much larger and therefore much more detailed images for NPC Portraits.

Getting Started with HD Portraits[edit | edit source | hide]

To begin, you'll need to install HD Portraits here. The nice thing about HD Portraits is it essentially functions as an extension of Content Patcher, so the parts you'll be writing will be Content Patcher mods which utilize HD Portraits under the hood.

Every HD Portrait mod can be divided into three parts:

  1. Loading the portrait itself
  2. Loading the portrait's size
  3. Configuring HD Portraits to use the portrait you specified.

Step 1 - Loading the Portrait Itself[edit | edit source | hide]

Essentially what you're doing is putting the portrait into the game alongside a key which HD Portraits can use to reference it later.

Put the following code into your content.json, under the "Changes" part of the file (inside the array, signified by []).
	{
		"LogName": "Import Wizard Portrait",
		"Action": "Load",
		"Target": "Mods/NameOfMod/Wizard",
		"FromFile": "assets/Wizard.png"
	},
Let's break that down.

The first line is an optional parameter in Content Patcher that labels what you're doing with this specific patch.

The second line is what type of action we're performing, and we're adding a new asset in its entirety, so we're using "Load".

The third line is the target, which should always start with "Mods" then followed by the name of your mod, and finally the name of the portrait you are trying to replace.

The fourth line is where your portrait file is located. It is good practice to always have an assets folder inside your mod folder and to place your assets in there.

Step 2 - Loading the Portrait's Size[edit | edit source | hide]

Next we need to tell the framework how big they should expect this character's portrait to be.

First, go inside your asset folder create a json file called "size.json" and paste the following inside
{
	"Size": 128
}
This is specifying that each tile of your new portraits are going to be 128x128 pixels. If you're having trouble figuring out this number, take the total pixel width of your portrait file and divide it by two. Next, we need to tell HD Portraits that this is the size you're using. Add the following to your content.json, again in the "Changes" section of the file.
	{
		"LogName": "Specify Wizard Portrait Size",
		"Action": "Load",
		"Target": "Mods/HDPortraits/Wizard",
		"FromFile": "assets/size.json"
	},
Let's break that down.

The first line is an optional parameter in Content Patcher that labels what you're doing with this specific patch.

The second line is what type of action we're performing, and we're adding a new asset in its entirety, specifically a file specifying what size the Wizard portrait should be, so we're using "Load".

The third line is the target, which should always look like "Mods/HDPortraits/" followed by the name of the NPC whose portraits you are trying to replace.

The fourth line is where your size file that you created above is located.

Step 3 - Configuring HD Portraits to Load the Portrait You Want[edit | edit source | hide]

Now that we've loaded the portrait into the game and specified what size the game should expect, now we must tell the game to use our portrait.

This is done by adding the following to your content.json
	{
        "LogName": "Select Wizard Portrait",
		"Action": "EditData",
		"Target": "Mods/HDPortraits/Wizard",
		"Entries": {
			"Portrait": "Mods/NameOfMod/Wizard"
		}
	},
Let's break that down.

The first line is an optional parameter in Content Patcher that labels what you're doing with this specific patch.

The second line is what type of action we're performing, and here we are telling HD Portraits where to find the portrait we want it to load.

The third line is the target, which should always look like "Mods/HDPortraits/" followed by the name of the NPC whose portraits you are trying to replace.

The fourth line should have the exact string from the "Target" of Step 1. The portrait was loaded into the game, in this case under the location Mods/NameOfMod/Wizard, and we are now telling HD Portraits to use that image for the Wizard's portrait.

Final Content.json from Above Steps[edit | edit source | hide]

Here is what your content.json should look after you've followed the above steps:

{
    "Format": "1.26.0",
    "Changes": [
    	{
    		"LogName": "Import Wizard Portrait",
    		"Action": "Load",
    		"Target": "Mods/NameOfMod/Wizard",
    		"FromFile": "assets/Wizard.png"
    	},
    	{
    		"LogName": "Specify Wizard Portrait Size",
    		"Action": "Load",
    		"Target": "Mods/HDPortraits/Wizard",
    		"FromFile": "assets/size.json"
    	},
    	{
            "LogName": "Select Wizard Portrait",
    		"Action": "EditData",
    		"Target": "Mods/HDPortraits/Wizard",
    		"Entries": {
    			"Portrait": "Mods/NameOfMod/Wizard"
    		}
    	}
    ]
}

Advanced: Dynamic Portraits[edit | edit source | hide]

Want to do something more complex with HD Portraits? See the HD Dynamic Portrait tutorial here. It will explain how to create dynamic HD Portraits that change under certain conditions.