New Contributor Guide Missions

Adding more NPC dialogue part 3: New Missions

NPCs can give the player missions. Mission structure is fairly complicated and some parts of it aren't in JSON yet, but you can add simple fetch quests and monster kill quests in JSON.

Mission data is stored in data/json/npcs/missiondef.json. There's a lot of documentation at doc/MISSION_JSON.md but I'm going to expand on it. Each mission looks like this:

  {
    "id": "MISSION_FREE_MERCHANTS_EVAC_1",
    "type": "mission_definition",
    "name": "Clear Back Bay",
    "goal": "MGOAL_KILL_MONSTER",
    "difficulty": 2,
    "value": 50000,
    "start": {
      "assign_mission_target": { "om_terrain": "evac_center_9", "reveal_radius": 1 },
      "update_mapgen": {
        "om_terrain": "evac_center_9",
        "om_special": "evac_center",
        "place_monster": [ { "monster": "mon_zombie_electric", "name": "Sean McLaughlin", "x": 10, "y": 10, "target": true } ]
      }
    },
    "origins": [ "ORIGIN_SECONDARY" ],
    "followup": "MISSION_FREE_MERCHANTS_EVAC_2",
    "dialogue": {
      "describe": "We need help...",
      "offer": "If you really want to lend a hand we could use your help clearing out the dead in the back bay.  Fearful of going outside during the first days of the cataclysm we ended up throwing our dead and the zombies we managed to kill in the sealed back bay.  Our promising leader at the time even fell... he turned into something different.  Kill all of them and make sure they won't bother us again.  We can't pay much but it would help us to reclaim the bay.",
      "accepted": "Please be careful, we don't need any more deaths.",
      "rejected": "Come back when you get a chance, we really need to start reclaiming the region.",
      "advice": "If you can, get a friend or two to help you.",
      "inquire": "Will they be bothering us any longer?",
      "success": "Thank you, having that big of a threat close to home was nerve wrecking.",
      "success_lie": "What good does this do us?",
      "failure": "It was a lost cause anyways..."
    }
  }

Relevant bits:

• "id" is the internal mission ID
• "type" must be "mission_definition"
• "name" is the sentence displayed when you look up your missions, so make it as clear as possible
• "value" is the cash value of the mission, in cents. So a mission worth $500 in goods on completion has a value of 50000
• "goal" is a special string that defines how to complete the mission.
• • MGOAL_GO_TO means the player must reach a specific overmap tile, specified in the start function or by "assign_mission_target"
• • MGOAL_GO_TO_TYPE means the player must reach a type of overmap tile, specified in the start function or by "assign_mission_target"
• • MGOAL_FIND_ITEM means the player must find any copy of an item and bring it back.
• • MGOAL_FIND_ANY_ITEM means the player must find any copy of an item and bring it back. The item can be specified in a C++ function or via the "target": true field in a mapgen_update block in the "start" JSON.
• • MGOAL_FIND_MONSTER means the player must find and retrieve a friendly monster. The monster can be specified in a C++ function or via the "target": true field in a mapgen_update block in the "start" JSON.
• • MGOAL_FIND_NPC means the player must find and retrieve an NPC. The NPC can be specified in a C++ function or via the "target": true field in a mapgen_update block in the "start" JSON.
• • MGOAL_ASSASSINATE means the player must find and kill an NPC. The NPC can be specified in a C++ function or via the "target": true field in a mapgen_update block in the "start" JSON.
• • MGOAL_RECRUIT_NPC means the player must find and recruit an NPC. The NPC can be specified in a C++ function or via the "target": true field in a mapgen_update block in the "start" JSON.
• • MGOAL_KILL_MONSTER_TYPE means the player must kill a number of a specific type of monster, like shocker brutes. The type is specified in "monster_type" below.
• • MGOAL_KILL_MONSTER_SPEC means the player must kill a number of a specific monster species, like MUTANTS, specified in the "mosnter_species" below.
• "item" is the optional "id" of the item to retrieve, from data/json/items/
• "count" is an optional number that is number of items to retrieve. if it is absent, only 1 item is needed.
• "monster_species" is the optional monster "species" to kill for MGOAL_KILL_MONSTER_SPEC. You can find a list of species in data/json/species.json.
• "monster_type" is the optional monster "id" for MGOAL_KILL_MONSTER_TYPE, from data/json/monsters.json and data/json/monsters/
• "monster_kill_goal" is the optional number of monsters to kill
• "start" is an optional field that specifies changes that occur when the mission is accepted by the player. It can be either
• • an optional reference to a hardcoded, C++ function. "start" is optional, and existing start functions often don't have anything to do with the mission - for instance, almost all the remaining Tacoma Commune/Refugee Ranch start functions involve building up the ranch, and the mission is still valid even if they didn't run.
• • an object containing information on a target overmap special and target terrain. See the doc for details. This can now include an "update_mapgen" object or array, which is a special type of mapgen JSON that updates existing maps. See doc/MAPGEN.md for more details.
• "end" is an optional field like "start" that triggers when the mission is completed succesfully. See above.
• "fail" is an optional field like "start" that triggers if the mission fails. See above.
• "origins" is a list of types of NPCs that can generate the mission.
• • "ORIGIN_SECONDARY" means that it comes from the "followup" of another mission.
• • "ORIGIN_OPENER_NPC" means that the starting NPC can have this mission
• • "ORIGIN_ANY_NPC" means that any random NPC can have this mission
• "followup" is a mission "id" that the NPC will offer after the player completes this mission successfully.
• "dialogue" is an object, with each value being a dynamic line that the NPC says in response to the player asking about the mission. These are normal dynamic lines, as described above, and can use dynamic line filters and snippets
• • "describe" is what the NPC says to indicate they have a mission
• • "offer" is what the NPC says to further describe the mission, specify what the player needs to do, and indicate how the NPC will reward the player
• • "advice" is what the NPC will say if the player asks for advice on the quest
• • the other values have fairly self-explanatory names

Any NPC that has a mission should have a the mission's id in the "missions_offered" field of their NPC template. In addition, either the template's "chat" talk_topic should be added to the first talk_topic in (https://github.com/CleverRaven/Cataclysm-DDA/tree/master/data/npcs/TALK_COMMON_MISSION.json), or have the NPC should have a responses entry like this somewhere in their dialogue:

      { "text": "Can I do anything for you?", "topic": "TALK_MISSION_LIST" },

Reaching the TALK_MISSION_LIST talk_topic will cause CDDA to display the data/json/missiondef.json data for the NPC's current missions. It's not necessary for you do anything other than make sure that your missions have valid "dialogue" objects.