Home

Custom Museum Framework

Quests

Custom Museum Framework allows you to create custom quests that can be progressed and completed by filling out your museum. Museum quests will show up in the player's quest log just the same as any other quest and quest progress will be checked and updated as necessary every time an item is donated to your museum. Museum quests and their Ids can be used for trigger action actions and game state queries and Content Patcher tokens and whatnot just like any other quest.

In basically all regards, a quest added via Custom Museum Framework functions identically to a vanilla quest, it's just added via an easy to edit data model instead of a slash-delimited string and has custom functionality made for museum tracking. You can start a Custom Museum Framework quest the same way you start any other quest; via mail, dialogue commands, events, etc. Just use the MuseumQuest Id as the quest Id where relevant.

While you can already make quests and track their progress using mail flags just using the built-in museum rewards functionality and the triggers added by Custom Museum Framework, adding quests via the method described on this page is likely to be much easier both for you and anyone else who might want to add on to your museum.

Also, as of writing there is no vanilla action for completing a quest, just removing one. So without doing this the player won't get that satisfying little ding! noise when they complete a quest, and we can't have that, can we?

Like with the basic museum data documentation, a complete Content Patcher example JSON will be at the bottom of the page.

Table of Contents

MuseumQuest Data

In order to create a custom museum quest for your museum, you must make an edit targeting Spiderbuttons.CMF/Quests, which is a string to MuseumQuest dictionary.? A MuseumQuest object contains the following fields:

FIELD PURPOSE
Id The string Id of this museum quest. This should be globally unique, so using the {{ModId}} Content Patcher token is highly recommended.

This Id must also be unique amongst all regular quest Ids found in Data/Quests, since Museum Quests do still use the vanilla quest system under the hood.

MuseumId The string Id of the museum that this quest belongs to.
Title (Optional) The title of the quest e.g. "Colourful Donations." This field supports tokenizable strings.
Default null[1]
Description (Optional) The description of the quest e.g. "The museum could use a little splash of colour in it. Why don't you help make this happen?" This field supports tokenizable strings.
Default null[1]
Hint (Optional) A hint for the player to help them figure out how to complete the quest e.g. "Donate one red, blue, and green item to the museum." This field supports tokenizable strings.
Default null[1]
Requirements (Optional) A list of CountableDonationRequirement objects defining what items must be donated to your museum in order to complete this quest. These CountableDonationRequirement objects contain the same fields as a DonationRequirement object as well as the following additional field:
  • Count - (Optional) An integer for how many items matching this requirement must be donated in order to meet this quest requirement. Default 1
For MuseumQuest data, you are allowed to leave all three of ItemIds, ContextTags, and Categories as null. If you do, then Custom Museum Framework will only check if there are Count items of any kind donated to your museum.
Every requirement in this list of requirements must be met in order for this quest to be considered complete.
Default null[2]
NextQuests (Optional) A list of NextQuest objects. When this quest is completed, every quest in this list will be added to the player's quest log automatically. See Next Quests.
Reward (Optional) An integer determining how much money the player should receive as a reward for completing this quest.
Default 0
CanBeCancelled (Optional) A bool determining whether or not the player is allowed to cancel this quest.
Default true

If you set this to false but it becomes impossible for the player to fulfill the quest requirements, there will be no way for them to remove this quest from their quest log without console commands.

TimeToComplete (Optional) An integer determining how many days the player has to complete the quest. If this is set to 0 or higher, this will be a timed quest. If this is set to -1, the quest will not have a timer.
Default -1
ActionOnCompletion[3] (Optional) An action string that will be run when the player collects the reward (not when it is earned).
Default null
ActionsOnCompletion[3] (Optional) A list of action strings that will be run when the player collects the reward (not when it is earned).
Default null

[1] The Title, Description, and Hint fields are optional in the sense that the quest won't break per se without them... but it will lead to weird empty spaces in the quest log if they aren't included. Please include all of them.

[2] If a quest has no requirements, it will be completed as soon as the player receives it.

[3] You may fill out both the ActionOnCompletion field and the ActionsOnCompletion field if you'd like, though you should probably just choose one for simplicity. The former will run first.

Next Quests

A NextQuest object can be added to the NextQuests field of a MuseumQuest object in order to automatically create a quest chain. When the player finishes the first quest, every quest defined in the NextQuests list will be added to their quest log automatically. A NextQuest object does not contain quest data—it only points the game in the direction of a quest, meaning that you can use a NextQuest object to add any quest to the player's quest log, not just Custom Museum Framework quests.

A NextQuest object contains the following fields:

FIELD PURPOSE
Id The string Id of the quest that should be added. This does not need to be a Custom Museum Framework quest specifically.
HostOnly (Optional) A bool that determines whether this quest should be considered a "host only" quest. If this is set to true, then this next quest will not be given to the player if they are not the host. If the player is the host, or if it is not a multiplayer game, the player will get the quest (assuming the condition passes). If this is set to false, then it will not matter whether or not the player is the host.
Default false
Condition (Optional) A Game State Query determining whether or not the player should receive this next quest. If this condition does not pass, the player will not receive the quest. If this condition passes, they will receive the quest. This condition is checked when the initial quest is completed, not when the initial quest is given.
Default null

Complete Example

 1 
{
 2 
   "Action": "EditData",
 3 
   "Target": "Spiderbuttons.CMF/Quests",
 4 
   "Entries": {
 5 
      "{{ModId}}_MyMuseumQuest1": {
 6 
         "Id": "{{ModId}}_MyMuseumQuest1",
 7 
         "MuseumId": "{{ModId}}_MyMuseum",
 8 
         "Title": "Colourful Donations",
 9 
         "Description": "The museum could use a little splash of colour in it. Why don't you help make this happen?",
10 
         "Hint": "Donate one red, blue, and green item to the museum.",
11 
         "Requirements": [
12 
            {
13 
               "ContextTags": [
14 
                  "color_red"
15 
               ],
16 
               "Count": 1
17 
            },
18 
            {
19 
               "ContextTags": [
20 
                  "color_blue"
21 
               ],
22 
               "Count": 1
23 
            },
24 
            {
25 
               "ContextTags": [
26 
                  "color_green"
27 
               ],
28 
               "Count": 1
29 
            }
30 
         ],
31 
         "NextQuests": [
32 
            {
33 
               "Id": "{{ModId}}_MySecondQuest",
34 
               "Condition": "SEASON spring"
35 
            }
36 
         ],
37 
         "Reward": 69,
38 
         "CanBeCancelled": true,
39 
         "TimeToComplete": -1,
40 
         "ActionOnCompletion": "AddConversationTopic MuseumQuestComplete",
41 
         "ActionsOnCompletion": null
42 
      },
43 
      "{{ModId}}_MySecondQuest": {
44 
         "Id": "{{ModId}}_MySecondQuest",
45 
         "MuseumId": "{{ModId}}_MyMuseum",
46 
         "Title": "So Many Items!",
47 
         "Description": "How many items can the museum hold? Let's find out!",
48 
         "Hint": "Donate 10 items to the museum.",
49 
         "Requirements": [
50 
            {
51 
               "Id": "{{ModId}}_10ItemsRequired",
52 
               "Count": 10
53 
            }
54 
         ],
55 
         "Reward": 1000
56 
      }
57 
   }
58 
}