The main NPC file (NPCs/Rei/Rei.toml) says who the NPC is. This page covers every setting in it except gift tastes, dialogue, and schedules, which have their own pages: Gift tastes, Dialogue, Schedules.
Every value can be left out, and its default is used. Table and key names are not case-sensitive. Unknown keys and tables are reported, which catches typos such as Gendr or [Dialgue]. Values are normalised ("female" becomes Female), and an invalid value rejects the NPC with a message that says why.
A complete example#
Name = "Rei"
DisplayName = "Rei"
[Personality]
Gender = "Female"
Age = "Adult"
Manner = "Polite"
SocialAnxiety = "Neutral"
Optimism = "Positive"
[Birthday]
Season = "Summer"
Day = 12
[Home]
Region = "Town"
Map = "Hospital"
X = 9
Y = 7
Facing = 2
[Romance]
Datable = true
Marriageable = true
[Options]
SocialTab = "AlwaysShown"
CanReceiveGifts = true
[GiftTastes]
Love = ["Diamond", "Coffee"]
Step by step: write the main file#
1. Name the NPC#
Name = "Rei"
DisplayName = "Rei the Baker"
| Key | Type | Default | Notes |
|---|---|---|---|
Name |
text | the file name | The internal name. 1 to 64 letters, combining marks, digits, _, or -. No spaces, dots, or slashes. |
DisplayName |
text | Name |
What players see. Spaces are allowed. |
Keep Name the same as the NPC's folder. Translations change DisplayName, never Name.
2. Set the personality#
[Personality]
Gender = "Female"
Age = "Adult"
Manner = "Polite"
SocialAnxiety = "Shy"
Optimism = "Positive"
| Key | Options | Default |
|---|---|---|
Gender |
Male, Female, Undefined |
Male |
Age |
Adult, Teen, Child |
Adult |
Manner |
Neutral, Polite, Rude |
Neutral |
SocialAnxiety |
Neutral, Outgoing, Shy |
Neutral |
Optimism |
Neutral, Positive, Negative |
Neutral |
These are the game's own personality values. They affect how the NPC reacts in some situations, such as shop comments and how they greet other villagers.
3. Set the birthday#
[Birthday]
Season = "Summer"
Day = 12
| Key | Options | Default |
|---|---|---|
Season |
Spring, Summer, Fall, Winter |
Spring |
Day |
1 to 28 |
1 |
4. Set the home#
The home is where the NPC lives and first appears.
[Home]
Region = "Town"
Map = "Hospital"
X = 9
Y = 7
Facing = 2
| Key | Options | Default | Notes |
|---|---|---|---|
Region |
Town, Desert, Other |
Town |
The game's three regions. Town also sets defaults for shop comments and Winter Star participation. |
Map |
a location name | BusStop |
The game's location name, with no spaces. |
X, Y |
whole number, 0 or more | 10 |
The tile. |
Facing |
0 up, 1 right, 2 down, 3 left |
2 |
Which way the NPC faces. |
To find a good tile, stand on it in the game and use a tile-position display mod, or read the location's map file.
5. Set romance#
[Romance]
Datable = true
Marriageable = true
| Key | Default | Meaning |
|---|---|---|
Datable |
false |
The NPC can be romanced. |
Marriageable |
false |
The NPC can be married. This implies Datable. It also enables Marriage.toml; see Marriage. |
6. Set the options#
[Options]
SocialTab = "AlwaysShown"
Calendar = "AlwaysShown"
CanReceiveGifts = true
| Key | Options | Default |
|---|---|---|
Language |
Default, Dwarvish |
Default |
SocialTab |
UnknownUntilMet, AlwaysShown, HiddenUntilMet, HiddenAlways |
AlwaysShown |
Calendar |
AlwaysShown, HiddenUntilMet, HiddenAlways |
AlwaysShown |
EndSlideShow |
Hidden, MainGroup, TrailingGroup |
MainGroup |
IsDarkSkinned |
true, false |
false |
CanReceiveGifts |
true, false |
true |
CanGreetNearbyCharacters |
true, false |
true |
PerfectionScore |
true, false |
true |
CanCommentOnPurchasedShopItems |
true, false |
not set: the game decides |
IntroductionsQuest |
true, false |
not set: the game decides |
FlowerDanceCanDance |
true, false |
not set: the game decides |
SocialTab = "AlwaysShown" is NPC Helper 2's default so that a new NPC is visible straight away; the game's own default hides characters until you meet them. Language = "Dwarvish" makes the NPC's dialogue appear in Dwarvish unless the player can understand dwarves. The three keys that default to "the game decides" only take effect if you write them. Game options lists every value in one place.
7. Add the other parts#
The remaining parts of an NPC are covered on their own pages:
[GiftTastes]— Gift tastes[Dialogue]— Dialogue[Schedule]and[Marriage]— Schedules and Marriage- Images — Sprites and portraits
When something is wrong#
- A syntax problem is reported with its line number, and parsing continues so that you see all problems at once.
- An unknown key or table is reported as a possible typo.
- An invalid value rejects the NPC, and the message says which setting and why.
Unquoted text, numbers such as 0600, repeated keys or tables, and unusual key characters are accepted with a warning so older packs keep loading. Quote text values and fix the warnings. See TOML syntax for the format rules and file size limits.