Create your first NPC

This tutorial makes one character, Rei, from nothing. Each step says what to create, what to put in it, and what you should see. Later pages explain every setting in depth.

You need NPC Helper 2 installed, a plain text editor (Notepad, VS Code, or any editor that saves plain UTF-8 text), and an image editor that saves PNG files.

Step 1: Create the mod folder#

Inside the game's Mods folder, create a new folder named MyFirstNPC. This is your content pack.

Inside it create this structure (you create the empty folders now and the files in the next steps):

Mods/
└── MyFirstNPC/
    ├── manifest.json
    └── NPCs/
        └── Rei/
            ├── Rei.toml
            ├── sprites/
            │   └── Default.png
            └── portraits/
                └── Default.png

The folder inside NPCs is the NPC's folder. Its name is the NPC's internal name: letters, digits, _, or -, with no spaces or dots.

Step 2: Write manifest.json#

SMAPI reads this file to learn what your mod is. Create MyFirstNPC/manifest.json:

{
  "Name": "My First NPC",
  "Author": "YourName",
  "Version": "1.0.0",
  "Description": "Adds Rei, a baker in Pelican Town.",
  "UniqueID": "YourName.MyFirstNPC",
  "ContentPackFor": {
    "UniqueID": "Framework.Mod.NpcHelper",
    "MinimumVersion": "2.4.0"
  }
}

Step 3: Write the NPC file#

Create NPCs/Rei/Rei.toml. The file is named after the folder.

Name = "Rei"
DisplayName = "Rei the Baker"

[Personality]
Gender = "Female"
Age = "Adult"

[Birthday]
Season = "Spring"
Day = 14

[Home]
Map = "Town"
X = 10
Y = 12
Facing = 2

[Dialogue]
Introduction = "Hi, I'm Rei. I just opened a bakery."
Mon = "A new week begins. Time to bake."

[Schedule]
Weekday = ["600 Town 10 12 2", "1200 Town 20 20 3"]

What each part does:

• Name is the internal name and must match the folder. DisplayName is what players see.
• [Personality] sets gender and age group.
• [Birthday] sets the birthday: the season and the day (1 to 28).
• [Home] is where Rei lives and first appears: the location (Town), the tile (X, Y), and the direction she faces (2 is down).
• [Dialogue] holds her lines. Introduction is what she says the first time you talk to her. Mon is her line on Mondays.
• [Schedule] is her routine. Weekday covers Monday to Friday. Each entry is TIME LOCATION X Y FACING: at 6:00 she is in the Town at tile 10, 12 facing down, and at 12:00 she is at tile 20, 20 facing left.

Anything you leave out gets a default. See NPC definition for every setting.

Step 4: Add the images#

An NPC needs two images. Both are looked up by name.

1. sprites/Default.png is the walking sprite sheet. It is 64 pixels wide: 4 columns of frames that are 16 pixels wide and 32 tall. The rows show the character facing down, right, up, then left. A sheet 128 pixels tall holds those four rows.
2. portraits/Default.png is the portrait sheet: 2 columns of faces that are 64 by 64 pixels (128 pixels wide). The first face is the neutral expression.

If you do not have art yet, copy a placeholder: the command-line tool can create a starter pack with valid placeholder images (npchelper new pack). Details about frame order and extra poses are on Sprites and portraits.

Step 5: Start the game and check#

1. Start Stardew Valley through SMAPI.
2. In the console, find the NPC Helper 2 summary. It should list Rei under My First NPC, with no errors.
3. If something is wrong, the message names the file, the line, and the setting. Fix it, and restart the game.
4. Load a save and open the Social tab. Rei should be listed.
5. Go to the Town at the time given in her schedule and talk to her.

A message such as No sprite image found means the sprites/Default.png file is missing or misnamed.

What next#

You now have a working NPC. Continue with the pages in this order:

1. Pack structure — what every folder and file is for.
2. NPC definition — all personality, birthday, home, and option settings.
3. Gift tastes, Dialogue, and Schedules.
4. Sprites and portraits for the full sheet layout and variants.
5. Optional: Marriage, Heart events and festivals, and Localization.
6. Test and publish when you are ready to share it.