Modding:Museum

This page details adding custom museum donations and rewards. This is an advanced guide for mod developers

Data format

You can add/edit the items which the museum gives back in rewards through the new Data/MuseumRewards data asset. The data asset consists of a string → model lookup, where...

  • The key is a unique string ID for the reward group.
  • The value is a model with the fields listed below.
field effect
TargetContextTags The items that must be donated to complete this reward group. The player must fulfill every entry in the list to unlock the reward. This consists of a list of models with these fields:
field effect
Tag The context tag for the items to require.
Count The minimum number of items matching the context tags that must be donated.

For example, an entry with the tag forage_item and count 2 will require donating any two forage items.

Special case: an entry with the exact values Tag: "", Count: -1 passes if the museum is complete (i.e. the player has donated the max number of items, including any custom items that can be donated).

FlagOnCompletion (Optional if RewardItemIsSpecial is true) Whether to add the ID value to the player's received mail. This is used to track whether the player has collected the reward, and should almost always be true. If this is omitted and RewardItemIsSpecial is false, the player will be able collect the reward infinite times. Default false.

After the reward is collected, you can check this value using the HasFlag condition in Content Patcher.

RewardActions Run one or more trigger action strings. For example, this adds data-sort-value="500"> 500g to the current player:
"RewardActions": [
    "AddMoney 500"
]
RewardItemId (Optional) The qualified item ID for the item given to the player when they donate all required items for this group. There's no reward item if omitted.
RewardItemCount (Optional) The stack size for the RewardItemId (if the item supports stacking). Default 1.
RewardItemIsSpecial (Optional) Whether to mark the RewardItemId as a special permanent item, which can't be destroyed/dropped and can only be collected once. Default false.
RewardItemIsRecipe (Optional) Whether to give the player a cooking/crafting recipe which produces the RewardItemId, instead of the item itself. Ignored if the item type can't be cooked/crafted (i.e. non-object-type items). Default false.
CustomFields The custom fields for this entry.

For example, this content pack adds two rewards (one mail and one item):

{
    "Format": "2.0.0",
    "Changes": [
        {
            "Action": "EditData",
            "Target": "Data/MuseumRewards",
            "Entries": {
                // send a letter when a specific item is donated
                "{{ModId}}_ShinyArtifact": {
                    "TargetContextTags": [
                        {
                            "Tag": "id_{{ModId}}_ShinyArtifact", // unique context tag identifying the item by ID
                            "Count": 1
                        },
                    ],
                    "FlagOnCompletion": true,
                    "RewardActions": [ "AddMail Current {{ModId}}_ShinyArtifact" ]
                },

                // give item when 18 minerals are donated
                "{{ModId}}_18MineralItems": {
                    "TargetContextTags": [
                        {
                            "Tag": "item_type_minerals",
                            "Count": 18
                        },
                    ],
                    "RewardItemId": "(BC){{ModId}}_SuperMachine",
                    "RewardItemCount": 1,
                    "FlagOnCompletion": true
                }
            }
        }
    ]
}

See also mail data, custom items, and custom machines to add the custom mail and items.

Achievements

The A Complete Collection achievement is automatically adjusted to require any custom donations added too. This is based on the number of donated items though, so removing custom donations later may incorrectly mark the museum complete (since you may have donated enough items to meet the total required).