NPC Helper

Introduction

NPC Helper is a Stardew Valley mod for creating custom NPCs with simple TOML configuration files. No C# coding is required for normal content packs.

• TOML-based NPC definitions with readable files.
• Dynamic dialogue using Stardew Valley native dialogue keys, including daily, heart-level, location, time, festival, question, and gift response keys.
• Day, season, exact date, weekday, weekend, and named weekday schedule filtering.
• Location, season, weather, festival, and birthday sprite or portrait variants with fallback handling.
• Gift tastes, gift response messages, localization overlays, and a small API for mod integrations.

Installation

Quick Start Guide

Mods/
└── MyFirstNPC/              # Your content pack folder
    ├── manifest.json        # Required: SMAPI metadata
    ├── mod.toml             # Required: NPC list
    └── NPCs/
        └── Alex/            # Example NPC name
            ├── Alex.toml    # NPC definition
            ├── sprite.png   # Character sprite, 16x32 per frame
            └── portrait.png # Portrait, 64x64 per expression

{
  "Name": "My First NPC",
  "Author": "YourName",
  "Version": "1.0.0",
  "Description": "Adds a custom NPC to Stardew Valley",
  "UniqueID": "YourName.MyFirstNPC",
  "ContentPackFor": {
    "UniqueID": "TamKungZ.NpcHelper"
  },
  "UpdateKeys": []
}

# List NPC definition files relative to this content pack.
NPCs = ["NPCs/Alex/Alex.toml"]

# Basic Identity
Name = "Alex"
DisplayName = "Alex the Adventurer"
Gender = "male"
Age = "adult"

# Birthday
BirthdaySeason = "spring"
BirthdayDay = 13

# Starting Location
DefaultMap = "Town"
DefaultX = 52
DefaultY = 87
DefaultFacing = 2

# Assets
CustomSpritePath = "sprite.png"
CustomPortraitPath = "portrait.png"

Configuration Files

manifest.json

This file defines your content pack metadata. ContentPackFor.UniqueID must be exactly TamKungZ.NpcHelper.

{
  "Name": "My Custom NPC Pack",
  "Author": "YourName",
  "Version": "1.0.0",
  "UniqueID": "YourName.MyCustomNPCs",
  "Description": "Adds custom NPCs to Stardew Valley",
  "ContentPackFor": {
    "UniqueID": "TamKungZ.NpcHelper"
  },
  "UpdateKeys": []
}

mod.toml

Lists all NPC definition files relative to the content pack root.

# List all NPC definition files
NPCs = [
  "NPCs/Rei/Rei.toml",
  "NPCs/Alex/Alex.toml",
  "NPCs/Sophia/Sophia.toml"
]

NPC Definition (.toml)

The main TOML file defines an NPC. Place it inside the NPC folder and reference it from mod.toml.

# Basic Identity
Name = "Rei"                    # Internal name: unique and no spaces
DisplayName = "Rei"             # Name shown to players

# Core Properties
Gender = "female"               # "male" or "female"
Age = "adult"                   # "child", "teen", or "adult"
Manner = "polite"               # "polite", "rude", or "neutral"
SocialAnxiety = "neutral"       # "outgoing", "shy", or "neutral"
Optimism = "positive"           # "positive", "negative", or "neutral"

# Birthday
BirthdaySeason = "summer"       # "spring", "summer", "fall", or "winter"
BirthdayDay = 12                # 1-28

# Spawn Location
HomeRegion = "Town"             # Region for game logic
DefaultMap = "Hospital"         # Starting map
DefaultX = 9                    # X tile coordinate
DefaultY = 7                    # Y tile coordinate
DefaultFacing = 2               # 0=Up, 1=Right, 2=Down, 3=Left

# Relationship Flags
Datable = true                  # Can be dated
Marriageable = true             # Can be married

# Asset Paths
CustomSpritePath = "sprite.png"             # Default sprite
CustomPortraitPath = "portrait.png"         # Default portrait

# External Files
DialoguePath = "Dialogue.toml"              # Separate dialogue file
SchedulePath = "Schedule.toml"              # Separate schedule file

# Sprite Variants
[Sprites]
Hospital = "sprite_Hospital.png"           # When at Hospital
Beach = "sprite_Beach.png"                 # When at Beach
summer = "sprite_Summer.png"               # During summer
rainy = "sprite_Rainy.png"                 # When raining

# Portrait Variants
[Portraits]
Hospital = "portrait_Hospital.png"         # When at Hospital
summer = "portrait_Summer.png"             # During summer

# Gift Tastes
[GiftTastes]
# Item IDs, names, universal taste keys, or context tags
Love = ["Diamond", "Coffee", "Universal_Love"]
Like = ["Blueberry", "Universal_Like"]
Neutral = ["Universal_Neutral"]
Dislike = ["Universal_Dislike"]
Hate = ["Universal_Hate"]

Dialogue System

Dialogue is defined in TOML files. NPC Helper passes the dialogue to the game engine, which handles selection, friendship levels, dates, locations, and special commands.

[Dialogue]
Introduction = "Hi, I'm Rei. Nice to meet you!"

# Day of week
Mon = "Mondays are tough, but we'll get through it."
Tue = "Tuesday already? Time flies."

# Heart levels
2 = "You're becoming a familiar face."
4 = "Good to see you again!"
6 = "I'm glad we're friends."

# Location-based
Hospital = "I'm on duty today. Please don't distract me too much."
Town = "The town looks peaceful today."

# Seasonal and date dialogue
spring_1 = "Spring is finally here!"
winter_24 = "Happy Winter Star!"

# Time-based
Town_2000 = "It's getting late. You should head home soon."

# Weekly rotation
Greeting = "Hello! || Hi there! || Good to see you!"

# Festival dialogue
EggFestival = "Egg hunting isn't really my thing."
FlowerDance = "The flowers are beautiful this year."

# Questions and response options
Question = "$q 100/101 Do you like medicine?#$b#I'm just curious."
AnswerYes = "$r 100 10 Yes, I find it fascinating!"
AnswerNo = "$r 101 0 Not really, it's not for me."

# Relationship and gift keys
breakUp = "This is for the best..."
divorced = "Please, just leave me alone."
AcceptGift_Loved = "This is wonderful! Thank you!"
AcceptGift_Liked = "Thanks, I appreciate it."

Old format (not supported):
[friendship >= 6] Hello friend! || Hi there.
[time >= 1800] Good evening! || Hello.
[season = summer] It's hot today!

New Stardew Valley format:
6 = "Hello friend!"
Default = "Hi there."
Town_1800 = "Good evening!"
Town = "Hello."
summer = "It's hot today!"

Conditional Dialogue Migration

Older NPC Helper content sometimes used custom [condition] dialogue lines. Current NPC Helper expects Stardew Valley native dialogue keys instead, so conditions should be represented as key names whenever possible.

# Do not use this old custom condition syntax:
# [friendship >= 4] Good to see you again.
# [time >= 1800] Good evening.
# [season = summer] It is hot today.

# Use native Stardew Valley keys:
[Dialogue]
4 = "Good to see you again."
Town_1800 = "Good evening."
summer = "It is hot today."
Default = "Hello."

Dialogue Converter Notes

The legacy page linked to #dialogue-converter, but that anchor did not have a full section in the old HTML. This section keeps the migration guidance visible in the new documentation.

Search targets:
[friendship
[time
[season
LoveMessage
LikeMessage
NeutralMessage
DislikeMessage
HateMessage

Common replacements:
[friendship >= 2] -> 2
[friendship >= 4 on Monday] -> Mon4
[time >= 2000 in Town] -> Town_2000
[season = spring day = 1] -> spring_1
LoveMessage -> AcceptGift_Loved
LikeMessage -> AcceptGift_Liked

Schedule System

Schedules define NPC movement patterns throughout the day. Entries can be filtered by weekday/weekend, specific days, season, or exact date.

# Separate Schedule.toml file structure

# Weekday schedule
[[Schedule]]
Time = 600              # 6:00 AM
Map = "Hospital"
X = 1
Y = 18
Facing = 2              # Facing down
Days = "Weekday"        # Monday through Friday

[[Schedule]]
Time = 1200             # 12:00 PM
Map = "Town"
X = 29
Y = 54
Facing = 2
Days = "Weekday"
Action = "Having lunch" # Optional description

[[Schedule]]
Time = 1800             # 6:00 PM
Map = "Hospital"
X = 13
Y = 5
Facing = 0              # Facing up
Days = "Weekday"

# Weekend schedule
[[Schedule]]
Time = 900              # 9:00 AM
Map = "Beach"
X = 20
Y = 20
Facing = 2
Days = "Weekend"        # Saturday and Sunday

[[Schedule]]
Time = 1700             # 5:00 PM
Map = "Saloon"
X = 21
Y = 17
Facing = 1
Days = "Weekend"

# Specific day schedule
[[Schedule]]
Time = 1000             # 10:00 AM
Map = "ArchaeologyHouse"
X = 15
Y = 8
Facing = 2
Season = "spring"
Day = 1                 # Only on Spring 1

# Birthday schedule
[[Schedule]]
Time = 1400             # 2:00 PM
Map = "Saloon"
X = 21
Y = 17
Season = "summer"       # Rei's birthday is Summer 12
Day = 12

# Specific days of week
[[Schedule]]
Time = 800
Map = "Forest"
X = 45
Y = 32
Facing = 2
Days = "Mon,Wed,Fri"    # Only on Monday, Wednesday, Friday

Gift Tastes System

Gift tastes define what items your NPC loves, likes, is neutral about, dislikes, or hates using Stardew Valley gift rules. Gift response messages are defined separately in the dialogue file.

# In your main NPC TOML file, for example Rei.toml

[GiftTastes]
# Use item names, qualified IDs, universal taste keys, or context tags
Love = [
  "Diamond",      # Specific item name
  "(O)395",       # Qualified item ID: Coffee
  "Starfruit"
  # "Universal_Love"
]

Like = [
  "Blueberry",
  "Coconut",
  "Salmon",
  "Cheese"
  # "Universal_Like"
]

Neutral = [
  "Stone",
  "Wood",
  "Wheat"
  # "Universal_Neutral"
]

Dislike = [
  "Clay",
  "Copper Ore",
  "Algae"
  # "Universal_Dislike"
]

Hate = [
  "Joja Cola",
  "Trash",
  "Broken Glasses"
  # "Universal_Hate"
]

# Deprecated - do not use here:
# LoveMessage = "Old format - no longer works!"
# LikeMessage = "Use AcceptGift_* in Dialogue.toml instead"

# In Dialogue.toml - gift response messages
# These keys follow Stardew Valley's standard format.

# Regular gift reactions
AcceptGift_Loved = "Oh wow! Is this for me? I love it! $h"
AcceptGift_Liked = "Thanks! This is nice. I appreciate it. $h"
AcceptGift_Neutral = "Thank you."
AcceptGift_Disliked = "Oh... um, thanks? $u"
AcceptGift_Hated = "Eww, why would you give me this? $a"

# Birthday gift reactions
AcceptBirthdayGift_Loved = "You remembered my birthday! This is amazing! $h"
AcceptBirthdayGift = "A birthday gift? Thank you! $h"

# Optional: specific item reactions
AcceptGift_(O)72 = "A diamond! How extravagant... $h"
AcceptGift_Coffee = "Coffee! Exactly what I needed. $h"
AcceptGift_(O)395 = "More coffee? You know me too well. $h"

# Optional: context tag reactions
AcceptGift_category_gem = "A gemstone! Very thoughtful. $h"
AcceptGift_category_cooking = "Homemade food? You shouldn't have! $h"

Old format (deprecated):
[GiftTastes]
Love = ["Diamond", "Coffee"]
LoveMessage = "I love this! $h"
LikeMessage = "Thanks! $h"

New format:
[GiftTastes]
Love = ["Diamond", "Coffee"]
Like = ["Blueberry", "Coconut"]

# In Dialogue.toml:
AcceptGift_Loved = "I love this! $h"
AcceptGift_Liked = "Thanks! $h"
AcceptBirthdayGift = "A birthday gift! $h"

Asset Variants

NPC Helper switches sprites and portraits based on location, season, weather, festival, birthday, or configured asset paths. The older documentation emphasized the fallback order, which is included below.

# In your main NPC TOML file

[Sprites]
# Location-based variants
Hospital = "sprite_Hospital.png"
Beach = "sprite_Beach.png"
Saloon = "sprite_Saloon.png"

# Season-based variants
spring = "sprite_Spring.png"
summer = "sprite_Summer.png"
fall = "sprite_Fall.png"
winter = "sprite_Winter.png"

# Weather-based variants
rainy = "sprite_Rainy.png"
snow = "sprite_Snow.png"

# Special occasion variants
festival = "sprite_Festival.png"
birthday = "sprite_Birthday.png"

[Portraits]
# Same structure for portraits
Hospital = "portrait_Hospital.png"
summer = "portrait_Summer.png"
rainy = "portrait_Rainy.png"
festival = "portrait_Festival.png"

Localization

NPC Helper loads localized TOML overlays based on the current game language. Create a locale folder inside the NPC folder with language-specific TOML files.

NPCs/
└── Rei/
    ├── Rei.toml                    # Default definition
    ├── sprite.png
    ├── portrait.png
    └── locale/                     # Localization folder
        ├── es-ES/                  # Spanish, Spain
        │   └── Rei.toml            # Spanish translation overlay
        ├── fr-FR/                  # French
        │   └── Rei.toml
        └── de/                     # Generic German
            └── Rei.toml

# locale/es-ES/Rei.toml - Spanish translation
# Only include properties that need translation.

DisplayName = "Rei"  # Spanish display name

[Dialogue]
Introduction = "Hola. Soy Rei, medico en practicas en la clinica."
Mon = "Los lunes no me asustan. Solo necesitan el cafe adecuado."
Default = "Si me necesitas, estoy en la clinica."

# Gift messages can also be localized.
AcceptGift_Loved = "Oh, vaya! Esto es para mi? Me encanta!"
AcceptGift_Liked = "Gracias! Esto esta bien."
AcceptGift_Disliked = "Oh... um, gracias?"

• Locale detection uses SMAPI translation locale values, such as es-ES or fr-FR.
• If es-ES does not exist, NPC Helper can fall back to es.
• Localized TOML merges with the base definition as an overlay.
• No code is required; create locale folders and matching TOML files.
• Assets reload automatically when language-specific data changes.
• Gift messages should use AcceptGift_* keys in localized dialogue data, not old LoveMessage or LikeMessage fields.

API Reference

Other mods can register NPC definitions programmatically with NPC Helper through its API interface.

using StardewModdingAPI;
using NpcHelper;

public class MyMod : Mod
{
    public override void Entry(IModHelper helper)
    {
        // Get the NPC Helper API
        var npcHelper = helper.ModRegistry.GetApi<INpcHelperApi>("TamKungZ.NpcHelper");

        if (npcHelper != null)
        {
            // Create NPC definition programmatically
            var customNpc = new NpcDefinition
            {
                DisplayName = "Programmatic NPC",
                Gender = "female",
                Age = "adult",
                DefaultMap = "Town",
                DefaultX = 35,
                DefaultY = 42,
                DefaultFacing = 2,
                Datable = true,
                Marriageable = false
            };

            // Add dialogue
            customNpc.Dialogue["Introduction"] = "Hello from code!";
            customNpc.Dialogue["Mon"] = "Monday dialogue from API.";

            // Add gift tastes
            customNpc.GiftTastes["Love"] = new List<string> { "Diamond", "Prismatic Shard" };
            customNpc.GiftTastes["Hate"] = new List<string> { "Joja Cola" };

            // Register the NPC
            npcHelper.RegisterNpc("CustomNPC", customNpc);
        }
    }
}

public interface INpcHelperApi
{
    /// <summary>
    /// Register a new NPC programmatically.
    /// </summary>
    /// <param name="name">Unique NPC name with no spaces.</param>
    /// <param name="data">NPC definition data.</param>
    void RegisterNpc(string name, NpcDefinition data);
}

public class NpcHelperApi : INpcHelperApi
{
    private readonly NpcManager _manager;
    public NpcHelperApi(NpcManager manager) => _manager = manager;

    // Implementation in ModEntry.cs
    public void RegisterNpc(string name, NpcDefinition data)
    {
        data.Name = name;
        _manager.Register(data);
    }
}

Troubleshooting

Compatibility

Frequently Asked Questions