NPC Helper Documentation v1.0.1

{
  "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": []
}

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

# ───── Basic Identity ─────
Name = "Rei"                    # Internal name (no spaces, unique)
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 or names (supports universal keys like "Universal_Love")
Love = ["Diamond", "Coffee", "Universal_Love"]
Like = ["Blueberry", "Universal_Like"]
Neutral = ["Universal_Neutral"]
Dislike = ["Universal_Dislike"]
Hate = ["Universal_Hate"]

[Dialogue]
# Basic dialogue keys (following Stardew Valley format)
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 (Stardew Valley uses numeric suffixes)
2 = "You're becoming a familiar face."
4 = "Good to see you again!"
6 = "I'm glad we're friends."

# Location-based (when NPC is at these locations)
Hospital = "I'm on duty today. Please don't distract me too much."
Town = "The town looks peaceful today."

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

# Time-based (using game's time format)
Town_2000 = "It's getting late. You should head home soon."

# Weekly rotation (Stardew Valley's || operator)
Greeting = "Hello! || Hi there! || Good to see you!"

# Festival dialogue (must match festival names)
EggFestival = "Egg hunting isn't really my thing."
FlowerDance = "The flowers are beautiful this year."

# Using Stardew Valley dialogue commands
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."

# Special dialogue 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."

# Separate Schedule.toml file structure

# ───── Weekday Schedule (Mon-Fri) ─────
[[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 (Sat-Sun) ─────
[[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

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

DisplayName = "Rei"  # Spanish display name

[Dialogue]
Introduction = "Hola. Soy Rei, médico en prácticas en la clínica."
Mon = "Los lunes no me asustan. Solo necesitan el café adecuado."
Default = "Si me necesitas, estoy en la clínica."

# Gift messages can also be localized
LoveMessage = "¡Oh, vaya! ¿Esto es para mí? ¡Me encanta!"
LikeMessage = "¡Gracias! Esto está bien."
DislikeMessage = "Oh... um, ¿gracias?"