Writing dialog and events can be done in text files included with your mod. They are written in a custom markup language designed to be very simple, allowing you to make new dialog without needing any coding skills.
The best way to get starting with dialog, is to take a look at some examples! All of the events in the base game are available on the modding resources page. Additionally, it's easy to take a look at the mods to see how the dialog inside works. Let's start with an example:
Labels start with a dash, such as "-General-0Heart-Normal-1". This is a daily dialog label, as explained in a following section.
Dialog begins with a character's name, followed by a colon and the text that they say.
Commands are inside square brackets. For example,
[SetEmotion Emma embarrassed] changes Emma's (Rosie's) portrait artwork. The
[AddFriendshipOnce Emma -2] call subtracts two friendship from your total for her. It only does it once, though, so you can't repeatedly gain or lose friendship. For a complete list of dialog commands, see below.
Your dialog is triggered by EventTriggers, so you might want to take a look at that.
Daily dialogs are the single unique message you get each day. They work a little differently and don't require triggers. The first time you get a new message each day, you also automatically get friend points. An algorithm chooses which dialogs you are eligible to receive and then chooses the one you've seen least recently. This maximizes the number of different but fresh dialogs you can get at a time.
They follow a pattern, and the first message you get is: "-General-0Heart-Normal-1"
All daily dialogs start with General, and have 4 sections. The second section (0Heart in this example) relates to your relationship status. 0Heart occurs before you have your first heart.
Valid daily relationship values:
- 0Heart to 8Heart - For that number of hearts.
- Married - Only when you are married to that person.
- MoveIn - Shows both when you are married and when you are moved in.
- JustFriends - If you choose not to date them, you'll go down this path. After breaking up with someone, you will also get these dialogs.
- BrokenUpWithBaby - If you've broken up with them, but you do have a baby, you can get these. Although the code is implemented, I don't think we have any in the base game. This would be a fun mod to write!
- Baby - You have a baby with this person, regardless of your other relationship status.
"Normal" - should always be "Normal". This was added to expand the dialog system in the future. We're not sure what it might be used for.. Early in development it was intended to be for weather or seasonal changes.
The final section is a number. It simply serves to order the different valid dialogs. For each heart level, it's nice to have 6 or 7 dialogs. That's usually enough to get them to the next level. For longer term relationship states, like JustFriends, it's nice to have more like 12 or 15.
Take a look at existing characters to get more information on how daily dialogs work.
Dialog Command List
There are many many different dialog commands. You can always see the examples for how they are used, but some of the most popular ones will be documented here:
- SetEmotion [SetEmotion Emma concern]
- Change the portrait art for a given character to match one of the emotion portraits.
- JumpIfSet [JumpIfSet Miles-NoMeat Special-GivePlayerMeal-1-Cornball]
- If the flag "Miles-NoMeat" is set, it will jump to the specified label.
- SetFlag [SetFlag Emma-PlayerLikesColony]
- Sets a marker that you can use later. For example you can set a flag so a character will remember the player's response to something. Later you can use a Jump to change dialog in response to that flag. You can also set a flag matching an event name in order to prevent it from occurring in the future.
- ClearFlag [ClearFlag Emma-PlayerThinksColonyIsTooQuiet]
- Clear a flag that's already been set. This can undo a SetFlag call, and allows you to change in response to changing circumstances. As an example, if you tell Sasha you've learned how to read, she will clear the Satine-1-PlayerCannotRead flag. You can also clear a flag with an event name to allow the event to repeat. For an example, see "LandingEventEmmaWaitingForScrap".
- SetCharacterToWaypoint [SetCharacterToWaypoint Player LandingEvent-PlayerStart Outside]
- Teleport a character to a waypoint instantly. Note that you need to include the AreaName as a parameter.
- MoveToWaypoint [MoveToWaypoint Emma LandingEvent-EmmaHelpPlayerBack]
- Cause a character walk to the specified waypoint. Don't include an area name! The waypoint must be in the same area that character already is.
- WaitForCharacterToStop [WaitForCharacterToStop Emma]
- If a character is moving, stop and wait until they reach the end of the waypoint.
- FaceDirection [FaceDirection Emma E]
- Face a certain direction, W for West, E for East, N for North, S for South.
- goto [goto LandingEvent-3]
- Jump to a specific label in the dialog file and keep going.
Various Jump Commands
- JumpIfAllSet2 [JumpIfAllSet2 Hailey-4-BridgeNotBuilt playerHasBuiltBridge Hailey-5-Progress]
- Checks the first two arguments as flags, and if they are all set, it then jumps to the last argument as a label.
- JumpIfAllSet3 [JumpIfAllSet3 playerAccessMountain playerTownSquareLevel playerHasBuiltBridge General-4Heart-Normal-3-AllBuilt]
- If all three flags are set, it will jump to the label.
- JumpIfNotSet [JumpIfNotSet Anthony-PlayerIsGoodCook General-4Heart-Normal-2-No-1]
- Jump if the flag is not set.
- Jump if neither of the two flags are set.
- Jump if none of the three flags are set.
- JumpIfUnwillingToDateYou [JumpIfUnwillingToDateYou Anthony Anthony-6-WithSomeoneAlready]
- If the person is unwilling to date you, it will jump to the label. Characters won't be willing to date you if you're dating someone and they require exclusive dating. They will also be unwilling to date you if you are already dating someone that requires exclusive dating (even if they aren't exclusive themselves).
- JumpIfHasItem [JumpIfHasItem Cave_Mushroom UnlockAutoSprinkler-Two-Start]
- If you have the item specified in your inventory, it will jump to that label. It must be in your player's inventory, not the fridge or storage.
- JumpIfStayedOvernightWith [JumpIfStayedOvernightWith Nessa General-MoveIn-Normal-5-1]
- If you slept overnight at that person's house last time you slept in a bed, it will jump to that label.
- IntroduceName [IntroduceName Emma]
- Before IntroduceName, the character's name will show up as question marks. This will replace it with the character's actual name.
- ShowIntroText [ShowIntroText Emma]
- Show the paragraph of intro text on a black background for a character. This also gives the player the opportunity to rename that character.
- JumpIfJustFriends [JumpIfJustFriends Emma Emma-9-JustFriends]
- All self explanatory jumps that test various logic.
- JumpIfFriendsWith [JumpIfFriendsWith Hailey General-JustFriends-Normal-15-Hailey]
- Friends is defined as having more than 3 stars (or hearts).
- JumpIfStarsWith [JumpIfStarsWith 5 Emma General-Married-Normal-10-EmmaFriend]
- Check for the number of starts (or hearts) that person has. It will jump if they have that many or more.
- JumpIfBabyCountMoreThan [JumpIfBabyCountMoreThan 1 BabyCouldGrowUp-Multibaby]
- If you have more babies than specified, it will jump.
- JumpIfHaveBabyWith [JumpIfHaveBabyWith Emma General-Baby-Normal-8-Baby]
- Jump if you have a baby with a specific person.