Custom Museum Framework

Museum Maps

A map made to be used for your custom museum location does not need to look any particular way. It does not need to have a minimum number of item pedestals nor is there a maximum number of item pedestals that can exist on the map. The only limitation that you must keep in mind is that a donated item will always be drawn on top of its pedestal (but not drawn on top of the AlwaysFront layer!). As well, please keep in mind that Custom Museum Framework will not ensure that you have enough item pedestals in your location to display every valid donation item or reach every museum milestone. It is up to you to ensure that you have enough spaces available.

Click here to download an example map that utilizes all of the features listed on this page.

Table of Contents

• Item Pedestals
• Map Actions
• MuseumMenu
• Rearrange
• Multiplayer Compatibility
• Lost Books

Item Pedestals

In the vanilla museum, in order for a tile to be a valid item pedestal, you must use these tiles to paint your pedestals onto your map:

As long as you use those tiles (specifically, the top surfaces that the items actually get placed onto), the game considers the tile to be a valid item pedestal for the vanilla museum. The same is true for your custom museum. If you use the same tilesheet and those same tiles on the same map layer (Buildings), those tiles will be considered valid item pedestals in your custom museum.

But of course, for your museum, that isn't your only choice. Custom Museum Framework also allows you to designate any tile as a valid item pedestal. In order to do so, you need only place a TileData object on the Buildings layer on the tile in question with the following properties:

Any tile with valid matching TileData will be considered a valid item pedestal and the player will be able to place an item onto it when they donate or rearrange the item. There are no limitations to which tile may be designated a valid item pedestal aside from the usual limitation that there must be a tile painted on the Buildings layer below the TileData object.

However, please be advised that if your museum accepts items that are visually larger than one tile wide (like tables) or have a collision box that is larger than one tile tall (also like tables), Custom Museum Framework will not shrink them to fit nor will it block off any item pedestals that may otherwise be covered by the item in question. For example, if there are two item pedestals side by side and the player donates a 2x2 coffee table to the pedestal on the left, then the coffee table will visually cover both pedestals (as well as the two tiles above the pedestals) however the player will still be able to donate another item to the pedestal on the right. This right item will then be visually clipping inside the coffee table to its left, since the coffee table is trying to appear over top of it. The player will also be able to walk directly behind the left pedestal, clipping through the top half of the table. Please keep this in mind when designing your museum or deciding what items may be donated.

Map Actions

MuseumMenu Tile

A museum map is hardly useful without some tile for the player to interact with in order to actually donate their items. In the vanilla museum, players must interact with the tile just in front of Gunther in order to open up his dialogue menu. In your museum, this tile, the MuseumMenu tile, can be anywhere in your museum, however it's a good idea to put it near your owner area if you have one set. You can have more than one MuseumMenu tile in your map, however they will all share the same owner area restrictions, if applicable.

In order for a tile to be a MuseumMenu tile, you must add a tile action TileData object on the Buildings to the tile in question with the following properties:

Interacting with this tile will open up the main museum dialogue menu, which will have options for donating an item (if the player has a valid donation item in their inventory), collecting rewards (if there are any to claim), and leaving the dialogue. If you do not have a Rearrange tile somewhere on your map, then there will also be dialogue options for rearranging your museum and retrieving items (if applicable) if there are items already donated to your museum. You are able to change the text shown for any of these dialogue options by customizing your museum strings.

If the player does not currently have any valid donation items in their inventory, has no unclaimed rewards, and there is a Rearrange tile somewhere on your map, then the main museum dialogue will not open up. Instead, a different customizable message will be shown. If you do not customize your museum strings, then a default message will be shown, however it may use a vanilla string and thus be written with Gunther in mind or be from Gunther's perspective.

In addition to the above, if your museum has an owner that is required to be present, then the owner must be considered "clocked in" for this tile to open the main museum dialogue menu. If the owner is not clocked in, the player does not have any unclaimed rewards, and you have a Rearrange tile somewhere on your map, then a different customizable message will be shown to the player instead to let them know that they are unable to donate an item until the owner is present. If you do not have a Rearrange tile somewhere on your map, then the aforementioned message will never be shown as long as your museum has one item donated, as the option to rearrange your museum will always be available regardless of whether or not the owner is clocked in.

If your museum has no owner or they are not required to be clocked in, then the player does not need to wait for any NPC to be present in order for the main museum dialogue menu to open, as long as they meet the other requirements described earlier.

Once the player selects the option to donate an item, the process is identical to the vanilla museum. Valid item pedestals will be shown for the player to place their donation onto. Similarly, if they select the option to collect their rewards, a chest menu will appear, identical to the one that appears when you collect rewards from the vanilla museum, where the player will be able to take out items but will not be able to put them back in. If the option to rearrange the museum is placed in your main museum dialogue menu, then the rearranging is also identical to rearranging the vanilla museum. If the option to retrieve items is placed in your main museum dialogue menu, see Item Retrieval to read on how that works.

Rearrange Tile

In the vanilla museum, the tile the player must interact with in order to rearrange the museum is a separate tile from the vanilla Gunther tile that opens Gunther's dialogue menu. In Custom Museum Framework, you also have the option of placing a separate Rearrange tile to handle rearranging the museum as well as retrieving items from the museum (if applicable). If you choose to not include a Rearrange tile in your museum map, then the options will be placed into the main museum dialogue menu opened with your MuseumMenu tile instead. However, I personally recommend including a separate Rearrange tile both because it's what players would expect and to prevent the main museum dialogue menu from becoming too large/tall.

In order for a tile to be a Rearrange tile, you must add a tile action TileData object on the Buildings layer to the tile in question with the following properties:

If your museum has any items currently in it, then interacting with this tile will open up the secondary museum dialogue menu, which will have options for rearranging your museum, retrieving items from your museum (if applicable), and leaving the dialogue.

If the player selects the option to rearrange your museum, then the process will be identical to rearranging the vanilla museum. If the option to retrieve items is present and the player selects it, see Item Retrieval to read on how that works.

Multiplayer Compatibility

In vanilla, only one player is allowed to interact with Gunther or the rearrange menu at one time. The same is true for your museum. When a player in a multiplayer game begins donating, rearranging, or retrieving items, your museum will consider itself "locked" and no other player may begin any of those same interactions until the locking player has finished or disconnected. If a player attempts to begin any of those interactions, a customizable message will be shown letting them know that your museum or its owner is busy right now and cannot be interacted with.

Lost Books

First things first, if you have not yet read the Lost Books documentation, it would greatly benefit you if you did before reading this section. If you do not plan on including custom lost books in your museum, you can safely ignore everything from this point onwards.

If you are including custom lost books in your museum, though, then you must include some TileData in your museum map to tell Custom Museum Framework where your books should go. Custom Museum Framework will place floating book icons above these tiles when a book has been found but not read, just like the vanilla museum. These tiles will get the relevant data from the relevant book if both your Lost Book data and your TileData are set up correctly.

In order for a tile to contain a lost book, you must add a tile action TileData object on the Buildings layer to the tile in question with the following properties:

Each individual lost book in a bookset must have its own TileData on its own tile shared with no other books (from the same bookset or otherwise) if you want it to be unlocked and readable. When the player finds a custom lost book that belongs to your museum and unlocks a new lost book, a floating book icon will appear over the tile with the TileData that matches the Bookset Id and Book Id of the lost book that was found. If you do not have a tile with the TileData for a given lost book, then it will not appear anywhere in your museum and the player will not be able to interact with it.

When a player interacts with a tile that has valid lost book TileData on it, Custom Museum Framework will check that the player has actually found enough lost books to have unlocked that specific tile and, if so, will follow the rules you defined in your book data to determine what message to display, if any. If the player has not unlocked the lost book that goes with a tile, then a customizable message will pop up letting the player know that a lost book will go there eventually (assuming you have not chosen to hide the message completely).