Skip to content

New Contributor Guide Dialogue

Mark Langsdorf edited this page Jun 17, 2020 · 1 revision

Adding more NPC dialogue

NPC dialogue is almost entirely implemented in JSON with some C++ code support. All general dialogue, including assigning missions to the player and setting NPC combat rules, can be done through JSON.

NPC dialogue is stored in data/json/npcs/, specifically the TALK_*.json files and talk_tags.json. The dialogue system is extensively documented in doc/NPCs.md.

Dialogue consists of talk_topics, where each talk_topic has a "dynamic_line" that the NPC says, and then a "responses" list of things that the player can say in response. This is the talk_topic object for the Old Guard Rep at the evacuee center:

  {
    "id": "TALK_OLD_GUARD_REP",
    "type": "talk_topic",
    "dynamic_line": { "u_has_any_trait": [ "PROF_FED" ], "yes": "Marshal...", "no": "Citizen..." },
    "responses": [
      { "text": "Who are you?", "topic": "TALK_OLD_GUARD_REP_NEW" },
      { "text": "Heard anything about the outside world?", "topic": "TALK_OLD_GUARD_REP_WORLD" },
      { "text": "Is there any way I can join the 'Old Guard'?", "topic": "TALK_OLD_GUARD_REP_ASK_JOIN" },
      { "text": "Does the Old Guard need anything?", "topic": "TALK_MISSION_LIST" },
      { "text": "Well, bye.", "topic": "TALK_DONE" }
    ],
    "//": "TODO: The rep should know whether you're actually a sworn officer: Wearing the badge without the trait => Bad idea"
  }

Dynamic Lines

Dynamic lines can be strings, lists, or objects, and any string can be replaced by a list or objected repeatedly. So that dynamic line could be expanded to provide a lot more variety like this:

"dynamic_line": {
  "u_has_any_trait": [ "PROF_FED" ], 
  "yes": [
    "Marshal...",
    "Marshal, it's good to see you."
    "What can I do for you, Marshal?"
  ],
  "no": {
    "u_is_wearing": "badge_marshal",
      "yes": [
        "Where did you get that badge?",
        "Why are you pretending to be a US Marshal?",
        "Explain yourself!  You're no <swear> Marshal, but you're wearing the badge!"
      ],
      "no": [
        "Citizen...",
        "Can I help you?",
        "Is there something you need?",
        "<greet>",
        {
          "u_male": [
            "Sir.",
            "You look capable, I may have some work for you."
          ],
          "no": [ 
            "Ma'am",
            "Hello miss, the US government is an equal opportunity employer."
          ]
        }
      ]
   }
 }
}

Snippets

"<greet>" and "<swear" are examples of snippets. Snippets are stored in data/json/npcs/talk_tags.json, and are lists of strings. When the dialogue system gets ready to display text that includes a snippet, it randomly selects a snippet from the list and inserts it in the text. So that "<greet>" would reference the greet snippet:

{
  "type" : "snippet",
  "category" : "<greet>",
  "text" : [
    "Hey <name_g>.",
    "Greetings <name_g>.",
    "Hi <name_g><punc> You okay?",
    "<name_g><punc>  Let's talk.",
    "Well hey there.",
    "<name_g><punc>  Hello.",
    "What's up, <name_g>?",
    "You okay, <name_g>?",
    "Hello, <name_g>.",
    "Hi <name_g>"
  ]
}

and the Old Guard Rep would have 12 new lines that he would randomly say to you.
Snippets can also reference other snippets, such as the references to which is a snippet for punctuation or to <name_g> which are various friendly references.

Existing talk_topics don't take nearly as much advantage of snippets as they could, and a good learning project for someone who wanted to get started contributing would be to add a bunch of snippet references and new snippets to the existing dialogue.

Responses

Responses are the options for things that the player can say in response to the NPC. There is a whole system for deciding which responses to display, and then having various changes to the game get triggered when the player chooses them. It's all documented in NPCs.md, linked above.

Also, the "text" section of a response is a bit of dialogue, and can use snippets just like dynamic lines do. Player responses could also use more snippets.

A friendly offer

The existing filters for dynamic lines and responses were the ones necessary to get the game's existing dialogue out of the C++ hardcode into JSON. They are by no means all the filters that you might want for some piece of dialogue you're working on. Similarly for response effects.

If you are working on NPC dialogue for vanilla game, or for a mod that is included in the game's CleverRaven repo at github, and find you need a filter or effect that doesn't exist, please PM mlangsdorf on Discourse or on reddit or on the CDDA Discord or open a github issue and I'll try to add it in a reasonably timely manner.

Missions

New missions can mostly be added in JSONs, but it's another large topic.

Clone this wiki locally