Home

Custom Museum Framework

Lost Books

Custom Museum Framework promises full feature parity with the vanilla museum, and that includes the Lost Book system, even if it doesn't really have much to do with being a museum. I guess that kind of makes this Custom Library Framework too?

Anyway! You can create custom Lost Book items that the player can find that will unlock some books in your museum location. They will work the same way as vanilla Lost Books. When the player finds them, they will (optionally) disappear from their inventory and the player will be notified that they have found a Lost Book and that a new book has been added to your museum. If this is not their first time finding a Lost Book for your museum, they will simply get a HUD message on the side. After finding a Lost Book and going back to your museum, there will be little animated book sprites above the tiles you specify to let the player now that they can now read whatever book you placed there. Many of these aspects are able to be customized by you.

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

Table of Contents

LostBook Data

To get started adding Lost Books to your museum, you must make an edit targeting Spiderbuttons.CMF/LostBooks, which is a dictionary? whose key is your museum Id and whose value is a list of LostBook objects (also referred to as booksets across this documentation). A LostBook object contains the following fields:

FIELD PURPOSE
Id The string Id of this bookset. While this does not need to be globally unique, it must be unique across all of the booksets in your museum.
ItemId The qualified item Id of the item you want to use as a Lost Book.

This does not need to be a new, custom item. You may use any qualified item ID for any item in the game as your Lost Book item. However, as with vanilla lost books, they will become impossible to actually receive, as Lost Books are removed from the player's inventory upon collection.

ReceiveText (Optional) The string message that will be shown to the player when they find a Lost Book. This will be a dialogue box the first time and a HUD pop-up every subsequent time. This field supports tokenizable strings.
Default You found a lost book. The library has been expanded.[1]
BroadcastText (Optional) The string message that will be shown in chat when a player finds a Lost Book in a multiplayer game. {0} will be replaced with the display name of the player who found the book. This field supports tokenizable strings, which will be parsed after the aforementioned substitution.
Default {0} has found a Lost Book![1]
MissingText (Optional) The string message that will be shown when the player tries to interact with a lost book tile in your museum when they do not have that book unlocked. This field supports tokenizable strings.
Important: Setting this to null does not set it to a default string; instead, setting it to null means that no message will be shown, however the tile will still appear interactable.[2] Omit this field entirely to use the default string.
Default There's a book missing here...[1]
Entries A list of BookData objects that will be used as the individual, discoverable books that belong to this bookset. See Book Entries.

[1] The default text for the ReceiveText, BroadcastText, and MissingText fields are taken from the vanilla strings, so they will automatically work in all officially supported languages; only the English version is shown on this documentation.

[2] If you want there to be no indication at all that a book should go there, you can always omit the TileData by default and conditionally patch it in later after checking for the relevant mail flag.

Remember that Spiderbuttons.CMF/LostBooks is a string to list of LostBook objects dictionary. Meaning, you are allowed to have multiple sets of Lost Books that each use a different ItemId, different book entries, different tiles in your museum, etc. There is no minimum number of booksets you must have nor is there a minimum number of books that must be in a bookset. However, keep in mind that Custom Museum Framework will not make sure that you have enough Lost Book tiles in your museum to display them all. That's on you!

Each bookset and its set of museum tiles is tracked independently of each other, so it is possible for the player to have unlocked every book in the first bookset but no books from a second bookset.

Book Entries

Each bookset contains a list of BookData objects that are used for the Lost Book tiles in your museum. A BookData object is identical to an InteractionData object, however since there are some contextual differences, the model will be repeated here.

A BookData object contains the following fields:

FIELD PURPOSE
Id The string Id of this entry. While this does not need to be globally unique, it must be unique across all of the books in this BookData list.
InteractionType (Optional) The type of interaction that should occur when the player interacts with the Lost Book tile that goes with this book entry. Allowed values are Default, Sign, Message, Letter, Custom, or None. A value of Default in the context of Lost Book interactions is equivalent to Letter, which is the same behaviour as the vanilla museum. Message and Letter perform identically to their respective map actions. Custom will tell Custom Museum Framework to do whatever action you wrote in the Action field (described below) instead of displaying your book. A value of None means nothing will happen at all when the player interacts with the Lost Book tile that goes with this book entry.
Default Default
Text The text that will be displayed for this book when showing a Default, Sign, Message, or Letter interaction. This field is ignored if InteractionType is set to Custom or None. This field supports tokenizable strings.
Action (Optional) An action string that will be run when the player interacts with the Lost Book tile that goes with this book entry.
Default null

The order of BookData objects within your Entries field is very important. Like in vanilla, custom Lost Books are discovered in order. If the player finds 3 of your lost books, for example, then the first 3 BookData objects in your list will be the ones that are unlocked and visible in your museum. Therefore, it is important to keep the order of this list in mind when creating your museum or when adding more books to an existing bookset with additional patches (such as when editing someone else's museum).

Complete Example

 1 
{
 2 
   "Action": "EditData",
 3 
   "Target": "Spiderbuttons.CMF/LostBooks",
 4 
   "Entries": {
 5 
      "{{ModId}}_MyMuseumId": [
 6 
         {
 7 
            "Id": "{{ModId}}_Bookset1",
 8 
            "ItemId": "(O)MyMuseumBook",
 9 
            "ReceiveText": "You found a lost book. Check out the library.",
10 
            "BroadcastText": "{0}, where did you get this?",
11 
            "MissingText": "It looks like a book goes here...",
12 
            "Entries": [
13 
               {
14 
                  "Id": "{{ModId}}_Book1",
15 
                  "Text": "This is the first book in my custom Lost Book set."
16 
               },
17 
               {
18 
                  "Id": "{{ModId}}_Book2",
19 
                  "InteractionType": "Message",
20 
                  "Text": "This is the second book in my custom Lost Book set. It uses Message instead!"
21 
               }
22 
            ]
23 
         },
24 
         {
25 
            "Id": "{{ModId}}_Bookset2",
26 
            "ItemId": "(O)MyMuseumBook2",
27 
            "MissingText": null,
28 
            "Entries": [
29 
               {
30 
                  "Id": "{{ModId}}_Book1",
31 
                  "Text": "This is the first book in my second custom Lost Book set."
32 
               },
33 
               {
34 
                  "Id": "{{ModId}}_Book2",
35 
                  "InteractionType": "Custom",
36 
                  "Action": "spacechase0.SpaceCore_PlaySound breakingGlass"
37 
               }
38 
            ]
39 
         }
40 
      ]
41 
   }
42 
}