Simple Dialogs

Simple Dialogs is NOT a stand alone entity mod, rather it is an add on that is designed to be (rather easily) integrated with other entity mods. TenPlus1 has very generously already integrated simple_dialogs into his mobs_redo/mobs_npcs. So if you wish to try it out you can use his mod: mobs_npc.

Simple Dialogs allows you to create conversation trees (dialogs) for any entity. And those dialogs are created using only a simple in game text file. No API or LUA programming required.

This means that any player who has ownership of an npc can create their own customized dialogs for that npc. A player building a shop can write a dialog for the npc shop keeper. A player who builds a huge castle can craft their own custom dialog for the guard at the gate to tell people about the castle. AND, since the control mechanism is just text, the players have no direct lua access, avoiding some security risks.

Of course, dialogs can be used by the server owner/game designer as well. They can create individually customized dialogs for npcs in the same manner that any player can. BUT, they can also add a text file containing a dialog to the game folder, and have it automatically uploaded to specific kinds of entities whenever they are spawned.

So, how does all of this work? The heart and key to simple dialogs is the dialog control text. Which, at it's simplest, looks something like this:

===Start
Shiver me timbers, but you caught me by surprise matey!
What be ye doin here?  Arrrgh!  This be no fit place for land lubbers!
>name:What is your name
>arrg:Why do pirates always say Arrrgh?
>treasure:I'm looking for treasure.  Can you tell me where the treasure is?
>rude:What's got you so cranky?  Did a beaver chew on your wooden leg?

TOPICS

The dialog starts with a topic, a topic is any line that has an equal sign "=" in position one. Every dialog file must have at least one START topic.
Topics are not case sensitive, and any characters besides letters, digits, dashes, and underscores are removed. Start, start, st art, and START will all be treated the same by simple dialogs. This also means all equal symbols will be removed. Every topic must start with one equal sign, I like three, I think it makes them stand out more, but it doesn't matter how many equal signs you have at the begining, as long as you have at least one, in position one. You can also add a "weight" to a topic line if you wish, we will talk more about that later.

Following the topic will be the dialog you want the character to say. This can be as long or as short as you wish. Just don't start any lines with "=", ":", or ">" in position one.

NOTE: Everything BEFORE the first =START topic will be ignored. If you want to set variables before the beginning of your dialog, set them in the =START topic, and then use :goto begin (or whatever you want to name the first visible dialog) to direct to the beginning

REPLIES

After the dialog will come the replies. Replies all start with a greater than sign ">" in position one. Followed by a target, followed by a colon, then by the text of the reply. The target is the dialog topic you want to go to next.

>name:What is your name

So in the above reply, the target is "name", and the display field is "What is your name" "What is your name" will be displayed in the reply area, and if the user clicks on it, the dialog will move to the "name" topic.

There is one special target, "end", that does NOT go to another dialog topic, instead it closes the formspec and ends the conversation.

ADDING MORE TOPICS

Of course, every "target" in a reply must have a corresponding topic to go to. So lets expand our dialog with another topic:

===Start
Shiver me timbers, but you caught me by surprise matey!
What be ye doin here?  Arrrgh!  This be no fit place for land lubbers!

>name:What is your name
>arrg:Why do pirates always say Arrrgh?
>treasure:I'm looking for treasure.  Can you tell me where the treasure is?
>rude:What's got you so cranky?  Did a beaver chew on your wooden leg?
>end:Good bye.

===name
My name be Davey Jones.  Not that it be any business of a bildge rat like you!
>bildge rat:What's a bildge rat?
>arrg:Why do pirates always say Arrrgh?
>treasure:I'm looking for treasure.  Can you tell me where the treasure is?
>rude:What's got you so cranky?  Did a beaver chew on your leg?

Now we have created the "Name" topic. So, if the player clicks on "What is your name" in the start section, the dialog will move to the "name" section and display that. You keep adding topics until every possible path through the dialog has a dialog topic for it. It is very important that you do NOT have reply targets that do not actually match up with a dialog topic. If you do, your dialog will not work.

WEIGHTED TOPICS

It is possible to have multiple topics with the same topic name. When you do that, simple_dialogs will chose randomly which topic is shown. Example:

===Start
I am the mystic of the temple.  Do you have a question?
>dragon:Where does the dragon live and how can I defeat him?
>end:No thank you, I'm just looking around.

===Dragon
You do not appear wise enough to handle the answer to that question.
>start:I really need to know the answer though!
>end:Oh well, good bye then!

===Dragon
You ask the wrong questions.  Go and gain more wisdom first, perhaps study with the master of trees in the crystal forest, then come and ask again.
>start:I dont have TIME to go find another mystic, I need to know now!
>end:I will go and seek for more knowledge then.

===Dragon
Hmmm, I think you are foolish to ask this question, but wisdom comes through hard trials.
The dragon lives on the black mountain in the land of the elves.  As for how to defeat him?  Ask the elves.
>end:Thank you!

So in the above dialog, if the player clicks on "Where does the dragon live and how can I defeat him?" He will get one of three possible responses randomly. Each just as likely to come up as the others.

BUT, what if you wanted to change the odds of which topic shows up? Well, that is actually quite easy to do. You just add a weight (in parenthesis) after the topic name. like below:

===Dragon(4)
You do not appear wise enough to handle the answer to that question.
>start:I really need to know the answer though!
>end:Oh well, good bye then!

===Dragon(3)
You ask the wrong questions.  Go and gain more wisdom first, perhaps study with the master of trees in the crystal forest, then come and ask again.
>start:I dont have TIME to go find another mystic, I need to know now!
>end:I will go and seek for more knowledge then.

===Dragon(1)
Hmmm, I think you are foolish to ask this question, but wisdom comes through hard trials.
The dragon lives on the black mountain in the land of the elves.  As for how to defeat him?  Ask the elves.
>end:Thank you!

so, in the above example, the first "dragon" topic has a weight of 4, the second 3, and the last one 1. When going to the dragon topic, simple_dialogs will roll a random number between 1 and 8 (4+3+1=8) If the number comes up 1-4, the first Dragon topic will show. If it comes up 5-7, the second topic will show. And only if the number comes up 8 will the last topic show.

VARIABLES

You can use variables in your dialogs. Variables should be enclosed in at sign brackets, like this: @[playername]@ Variables are not case sensitive, and all characters other than letters, numbers, underscore, dash, and period are stripped out. So @[PlayerName]@, @[playername]@, and @[Player Name]@ are all the same.

The variable playername is set by simple_dialogs and will always be available. Other variables may be set by the entity mod using simple_dialogs. Such as @[NPCNAME]@ or @[Owner]@ And you can set your own variables (more on that later)

An example of using a variable in a dialog:

===Start
Hello @[playername]@.  I am the wizard Fladnag.  I forsaw that you would come to see me today.
>tower:Tell me about your tower please?
>spell:Will you cast a spell for me?
>end:I prefer not to meddle in the affairs of wizards, for they are subtle and quick to anger.

When the above dialog is displayed @[playername]@ will be replaced by the actual playername.

Variable persistence

• Variables for each npc will persist between different dialog sessions. See notes on the command SET for details on how to make variables player specific.
• Whenever you click the "Save & Test" button, the dialog is rebuilt, and all the variables are reset. In order to test variables that should persist between dialog sessions, use the "Test (without save or resetting variables)" button.

CONCLUSION

Combining topics, commands, and replies can allow you to create some really complex simple_dialogs. (yes, just wallow in the oxymoron and enjoy it!) You can find some example dialog scripts in the simple_dialogs mod folder. They are all have names in the format of sd-*.txt

https://github.com/Kilarin/simple_dialogs

https://github.com/Kilarin/simple_dialogs/blob/main/sd-guard.txt

https://github.com/Kilarin/simple_dialogs/blob/main/sd-pirate.txt

https://github.com/Kilarin/simple_dialogs/blob/main/sd-test-npc.txt