Modding:Dialogue

← Index

This page explains how the game stores dialogue text, its format, and how the game parses it. This is an advanced guide for mod developers.

Data

The dialogue text is stored in four sets of files.

Character-specific dialogue

Characters\Dialogue\*.xnb contains most of the dialogue for each character (one file per character). The format in this file is:

"<preface>[heart level]_[date]_[year][suffix]": "String"

...where:

<preface> is an arbitrary key which identifies what it's for (like Introduction, Event, Season, etc).
[heart level] is the minimum heart level the player must have reached with the NPC for this dialogue to appear.
[date] is the numeric day of the month (like 28), or the three-character weekday (like Mon).
[year] is 1 for year one, or 2 for any year after that.
[suffix] is any string further identifying the dialogue (like inlaw_Abigail, for dialogue that only appears when you're married to Abigail).

If multiple dialogues are eligible, the game prioritises by the following:

marriage status;
preface;
suffix;
in-law status;
day of month;
year;
heart level;
day of week.

Strings from CS files

Strings\StringsFromCSFiles.xnb contains many translation strings, including NPC dialogue defined in the code. That includes every bit of dialogue that's shared between multiple characters, and dialogue for some hardcoded events like marriage. The format in this file is:

"<key>": "dialogue string"

The key is generated based on the file that contained it before translations were added (in the form <file name>.<int id>), but doesn't have any particular meaning now.

Event files

Data\Events\*.xnb contains event scripts, including any dialogue in the event (see Modding:Event data).

Animation descriptions

Data\animationDescriptions.xnb contains short bits of dialogue to go with certain schedule points.

Algorithm

The game finds dialogue as follows:

Event dialogue is read from the appropriate event commands (see Modding:Event data).
Location-specific dialogue is read from StringsFromCSFiles <location>.cs.
Else character dialogue is read from the character-specific files.
If no dialogues were found, the game resorts to hardcoded dialogue from the StringsFromCSFiles files (specifically keys prefixed with NPC.cs NPC.cs).

Format

Dialogue text can contain tokens and commands which control the dialogue box, change the text (e.g. switch between gender-specific strings), inject values, etc. These are parsed by the Dialogue class.

Special tokens:

character	description
`#`	Separates two commands in a dialogue string.
`{`	TODO. Stands for "breakSpecialCharacter".
`^`	Gender switch character. The text before it is shown for male farmers, the text after it for female farmers. Example: `Oh, good morning Mr. @!^Oh, good morning Ms. @!`
`*`	TODO. Stands for "quickResponseDelineator".

Portrait commands

These commands determine which portrait will be shown in the dialogue box. Portrait commands go to the end of a line of dialogue:

"fall_Fri6": "When I was a little girl, my father abandoned us.$s#$b#I'm sorry to make things uncomfortable for you...$u#$e#Anyway... How's the farming life going?",

command	description
`$neutral`	Switch the speaking character to their neutral portrait.
`$h`	Switch the speaking character to their happy portrait.
`$s`	Switch the speaking character to their sad portrait.
`$u`	Switch the speaking character to their unique portrait.
`$l`	Switch the speaking character to their love portrait.
`$a`	Switch the speaking character to their angry portrait.
`$<id>`	Switch the speaking character to the portrait at the given index in their portraits file, beginning with 0. All characters have six standard portraits: `$0` (neutral), `$1` (happy), `$2` (sad), `$3` (unique), `$4` (love), and `$5` (angry). Characters may have custom portraits beyond those for their dialogue and cutscenes. NOTE: `$1` can't be used as the first dialogue command (see `$1` below).

Dialogue commands

`$q <response IDs> <fallback>#<text>`	Show a dialogue box containing the given question text. If `<response IDs>` (a list delimited by `/`) contains an answer already given, the question is skipped (along with the rest of this dialogue line), and instead the dialogue entry identified by `<fallback>` will be appended to whatever precedes this $q command. The `<fallback>` dialogue typically uses a $p command to adjust the text based on the player's answer to this question.
`$r <response ID> <friendship> <reaction>#<answer text>`	Define a response option to a $q question dialogue. `<answer text>` is the text shown. `<response ID>` is used to group responses for future reference (multiple answers can share an answer ID). `<friendship>` defines the change in friendship value, positive or negative, if this response is selected. `<reaction>` names the dialogue entry from the NPC's `Content\Characters\Dialogue\*.xnb` file that will be the NPC's reaction if this response is selected by the player.
`$p <response ID>#<match text>\|<no-match text>`	Stands for "dialoguePrerequisite". Shows different text depending on whether the player gave a particular answer to a previously-asked question. If `<response ID>` matches an answer the player gave, `<match text>` is shown; otherwise, `<no-match text>` is shown. These texts, separated by `\|`, can each contain multiple commands separated by `#`.
`$b`	Indicates pauses in dialogue, where the player will need to click for the next part to load in the dialogue box.
`$e`	Ends the current dialogue, closing the dialogue box and resuming player control. The dialogue following `$b` will require a new interaction with the NPC.
`$k`	TODO. Stands for "dialogueKill".
`$c <probability>#<text1>#<text2>`	Show `<text1>` with a `<probability>` between 0 and 1; otherwise, show `<text2>`. E.g. `$c 0.9` for a 90% chance of `<text1>` and a 10% chance of `<text2>`. NOTE: Replacer commands (see below) do not work in `<text1>`.
`$d <bus\|joja\|cc>`	dialogueDependingOnWorldState `"Tue4": "$d` `<dependence>#\|Dialogue when dependence value is true.\|Dialogue in other situations.",` The dependence can take one of three values: "bus": is the bus fixed?; "joja": is JoJa Mart in business?; "cc": has the Community Centre been completed?
`$y`	TODO. Stands for "dialogueQuickResponse"; works like $q, but within one and the same text line.
`$1 <letter ID>#<1st-time text> #$e# <nth-time text>`	Creates a line of dialogue which the character will only see once (at most). `<1st-time text>` is shown only if `<letter ID>` has not been marked as sent yet (and this marks it as sent); otherwise, `<nth-time text>` is shown. `<letter ID>` should not correspond to an actual piece of mail (because it will not be sent), but it can be referenced by events or other dialogue lines.
`%fork`	TODO. Seems to have to do with questions and forks, however is used sparingly in game code. May be limited to forking events.
`[# # #]`	Gives the player a random item, from the pool of item IDs within the brackets.

Question example

To understand how $q, $r, and $p work, an example may be helpful. Consider this excerpt from Haley's dialogue file.

    summer_Sat: "Farming sounds so boring...#$q 42/43 summer_Sat_old#What do you even do all day?#$r 42 10 summer_Sat_12#Care for plants#$r 42 10 summer_Sat_12#Explore the caves#$r 43 -10 summer_Sat_13#Snoop around in your room#$r 42 10 summer_Sat_12#Dig for treasure" #!String
    summer_Sat_old: "#$p 43#Hey, you better not be snooping around in my room anymore!$a|But I guess it could get you in pretty good shape." #!String
    summer_Sat_12: "Hmm... sounds like a lot of work." #!String
    summer_Sat_13: "What? You'd better not be doing that!$a" #!String

The first time the summer_Sat dialogue is chosen, neither response 42 nor 43 will have been given (because this question is the only one which has them as responses), so Haley will say, "Farming sounds so boring... What do you even do all day?" The player can select among these responses:

Care for plants
Explore the caves
Snoop around in your room
Dig for treasure

The third response, $r 43 -10 summer_Sat_13#Snoop around in your room, sets response ID 43, reduces Haley's friendship by 10 points, and brings up the dialogue summer_Sat_13 (Haley says, "What? You'd better not be doing that!"). All of the other responses set response ID 42, increase Haley's friendship by 10 points, and bring up the dialogue summer_Sat_12 ("Hmm... sounds like a lot of work.").

The next time summer_Sat is chosen, one of the response IDs listed in the $q command will have been given (either 42 or 43). Therefore, the $q and everything after is scrapped, and dialogue summer_Sat_old is put in its place. This new dialogue uses the $p command to change Haley's dialogue based on whether or not you gave response ID 43 to any previous question. If you answered "Snoop around your room," everything before the | will be used, so Haley will now say, "Farming sounds so boring... Hey, you better not be snooping around in my room anymore!" If response ID 43 has not been given (in this case, you must have given response ID 42, i.e. one of the other three responses to the previous question), everything after the | will be used, so Haley will instead say, "Farming sounds so boring... But I guess it could get you in pretty good shape."

Replacer commands

Replacer commands will be replaced with the relevant string.

`@`	Farmer's name. Example: `Hi there @!`
`%adj`	Random adjective. (Defined in StringsFromCSFiles.xnb)
`%noun`	Random noun. (Defined in StringsFromCSFiles.xnb)
`%place`	Random place name. (Defined in StringsFromCSFiles.xnb)
`%spouse`	The name of Farmer's spouse.
`%name`	TODO. Stands for "randomNameSpecialCharacter". Seems to return a random name?
`%firstnameletter`	TODO. Stands for "firstNameLettersSpecialCharacter". Possibly returns the first letter in the name of a specific NPC, such as in Welwick's fortune.
`%time`	Current time.
`%band`	TODO. Possibly the genre of Sam and Sebastian's band.
`%book`	Randomly assigned title to Elliott's book.
`%rival`	Rival's name (not used outside of unimplemented features). Possibly used as the name or personal pronoun of Leah's ex instead.
`%pet`	The name of Farmer's pet.
`%farm`	Farm name.
`%favorite`	TODO. Returns favorite thing? Unused?
`%kid1`	The name of Farmer's first child.
`%kid2`	The name of Farmer's second child.